docs(boundaries): add import-topology guardrails

This commit is contained in:
Vincent Koc
2026-04-04 14:06:05 +09:00
parent 0777ddace8
commit 561db47566
4 changed files with 50 additions and 0 deletions

View File

@@ -26,6 +26,15 @@ can affect bundled plugins and third-party plugins.
- Do not expose implementation convenience from `src/channels/**`,
`src/agents/**`, `src/plugins/**`, or other internals unless you are
intentionally promoting a supported public contract.
- Keep public SDK entrypoints cheap at module load. If a helper is only needed
on async paths such as send, monitor, probe, directory-live, login, or setup,
prefer a narrow `*.runtime` subpath over re-exporting it through a broad SDK
barrel that hot channel entrypoints import on startup.
- Keep SDK facades acyclic. Do not add back-edge re-exports that route a
lightweight contract file back through heavier policy or runtime modules.
- Do not mix static and dynamic imports for the same runtime surface when
shaping SDK seams. If a surface must stay lazy, keep the eager side on a
light contract file and the deferred side on a dedicated runtime subpath.
- Prefer `api.runtime` or a focused SDK facade over telling extensions to reach
into host internals directly.
- When core or tests need bundled plugin helpers, prefer the plugin package
@@ -33,6 +42,14 @@ can affect bundled plugins and third-party plugins.
provider-named `src/plugin-sdk/<id>.ts` seam just to make core aware of a
bundled channel's private helpers.
## Verification
- If you touch SDK seams that affect lazy loading, hot channel entrypoints, or
bundled plugin import topology, run `pnpm build`.
- If the change can alter bundled channel startup cost, also run the isolated
entrypoint profiler for the affected plugin:
`OPENCLAW_LOCAL_CHECK=0 node scripts/profile-extension-memory.mjs --extension <id> --skip-combined --concurrency 1`
## Expanding The Boundary
- Additive, backwards-compatible changes are the default.