From c67c3d9413503f8f86ca800b842c46b6329dc07c Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 14 Jul 2026 23:14:51 +0800
Subject: [PATCH] refactor: derive event graphs and scope invariants from
 TypeScript

---
 AGENTS.md                                     |   2 +-
 docs/architecture.md                          |   2 +-
 docs/cordis-catalog/events.md                 |  12 +-
 docs/cordis-catalog/services.md               |   4 +-
 docs/event-producer-consumer.md               |  18 +-
 .../2026-07-12-agent-scope-runtime-design.md  |   2 +-
 package.json                                  |   5 +-
 packages/core/session/src/index.ts            |   4 +
 packages/subagent/subagent/src/index.ts       |   2 +
 packages/support/invariants/package.json      |   4 +
 packages/support/invariants/src/index.ts      |  50 +-
 .../invariants/src/scoped-events.generated.ts |  69 +++
 .../invariants/tests/invariants.spec.ts       |   2 +-
 packages/support/invariants/tsconfig.json     |  12 +
 pnpm-lock.yaml                                |  12 +
 scripts/gen-doc-graphs.ts                     | 361 +++++++++-----
 scripts/gen-scoped-events.ts                  | 441 ++++++++++++++++++
 scripts/run-gates.ts                          |   2 +-
 scripts/ts-project.ts                         | 113 +++++
 scripts/verify-scoped-dispatch.ts             |  69 ---
 20 files changed, 938 insertions(+), 248 deletions(-)
 create mode 100644 packages/support/invariants/src/scoped-events.generated.ts
 create mode 100644 scripts/gen-scoped-events.ts
 create mode 100644 scripts/ts-project.ts
 delete mode 100644 scripts/verify-scoped-dispatch.ts

diff --git a/AGENTS.md b/AGENTS.md
index c33774db9e..22c1f47aa8 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -92,7 +92,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - Every npm package is `@deepseek-ai/dsh-<name>`; vendored packages keep upstream names and are `private: true`. `cordis` is a peerDependency (+ dev) of every harness package.
 - ESM everywhere (`"type": "module"`). Cross-package imports use package names, never relative paths; in-package relative imports use explicit `.ts` extensions. Dev/test/demo run unbuilt via tsx + the root tsconfig `paths` map; builds are for outside consumers only.
 - **Registrations are effects**: every contribution goes through `ctx.effect()` / `ctx.on()`; a registry's `register()` returns the disposer.
-- **Typed events use declaration merging**; extensible unions use merge-extensible maps. Event JSDoc needs `@mode` and payload `@param` tags; public service methods document parameters and non-void returns. Catalog gates enforce this.
+- **Typed events use declaration merging** and merge-extensible maps. Event JSDoc needs `@mode` and payload `@param`; scoped keys absent from payloads need `@dshScopeScan unsupported`. Public service methods document parameters and non-void returns.
 - **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default.
 - **Waterfall listeners MUST call `next()`** to delegate; returning without it is the veto ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
 - **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
diff --git a/docs/architecture.md b/docs/architecture.md
index d9c3d86a1e..899c48bb8a 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -110,7 +110,7 @@ Every session event is turn-enclosed. Reloading a crashed session preserves the
 
 ### Agent Scope
 
-Every live agent owns a scoped `agent.ctx`. Its registrations shadow same-named globals, receive only that agent's dispatches, and unwind with the agent. `CreateAgentOptions.setup(agentCtx)` composes the scope before publication. See the [agent-scope RFC](rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md); subagent composition controls are documented [separately](rfc/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md).
+Every live agent owns a scoped `agent.ctx`. Its registrations shadow same-named globals, receive only that agent's dispatches, and unwind with the agent. `CreateAgentOptions.setup(agentCtx)` composes the scope before publication. Generated typed resolvers derive carrier checks from merged `Events` signatures and `scopeTarget`, eliminating the handwritten event table. See the [agent-scope RFC](rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md); subagent composition controls are documented [separately](rfc/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md).
 
 ## State
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index aa87ea66d7..4af431f8c0 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -245,7 +245,7 @@ Creation announcement during session publication. A synchronous throw vetoes and
 'session/created'(this: Scoped<Session>, session: Session): void
 ```
 
-Source: [`packages/core/session/src/index.ts:46`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:47`](../../packages/core/session/src/index.ts)
 
 ### `session/disposed` — emit
 
@@ -255,7 +255,7 @@ Emitted once when an announced session leaves the store, including publication r
 'session/disposed'(this: Scoped<Session>, session: Session): void
 ```
 
-Source: [`packages/core/session/src/index.ts:55`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:57`](../../packages/core/session/src/index.ts)
 
 ### `session/event` — emit
 
@@ -267,7 +267,7 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before
 
 Types: [SessionEvent](../core-data-structures/core.md)
 
-Source: [`packages/core/session/src/index.ts:66`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:69`](../../packages/core/session/src/index.ts)
 
 ### `session/flush` — parallel
 
@@ -277,7 +277,7 @@ Awaited parallel durability checkpoint: every listener runs and the caller await
 'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
 ```
 
-Source: [`packages/core/session/src/index.ts:75`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:79`](../../packages/core/session/src/index.ts)
 
 ## `skill/*`
 
@@ -311,7 +311,7 @@ A ready child settled. Scope-filtered dispatch uses the same delegating parent c
 'subagent/end'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void
 ```
 
-Source: [`packages/subagent/subagent/src/index.ts:90`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:92`](../../packages/subagent/subagent/src/index.ts)
 
 ### `subagent/provider-added` — emit
 
@@ -341,7 +341,7 @@ A provider established a ready child. For in-process providers, `ctx.agents.get(
 'subagent/start'(this: Scoped<SubagentService>, info: SubagentRunInfo): void
 ```
 
-Source: [`packages/subagent/subagent/src/index.ts:82`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:83`](../../packages/subagent/subagent/src/index.ts)
 
 ## `system-prompt/*`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index ca83b3c489..1509afc76a 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -200,7 +200,7 @@ list(): Session[]
 fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
 ```
 
-Source: [`packages/core/session/src/index.ts:560`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:564`](../../packages/core/session/src/index.ts)
 
 ## `ctx.skills` — `SkillService`
 
@@ -226,7 +226,7 @@ list(): string[]
 async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
 ```
 
-Source: [`packages/subagent/subagent/src/index.ts:123`](../../packages/subagent/subagent/src/index.ts)
+Source: [`packages/subagent/subagent/src/index.ts:125`](../../packages/subagent/subagent/src/index.ts)
 
 ## `ctx.systemPrompt` — `SystemPrompt`
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index d1a097fe24..bdf1c6e320 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -3,7 +3,7 @@
 
 # Event Producer And Consumer Matrix
 
-This matrix shows which packages dispatch each harness-owned event and which packages listen to it. It is intentionally a table rather than one large graph: events are many-to-many, and dense relation data is easier to review in rows. Dynamic dispatch overrides cover sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.
+This matrix shows which packages dispatch each harness-owned event and which packages listen to it. It is intentionally a table rather than one large graph: events are many-to-many, and dense relation data is easier to review in rows. Receiver and event-name types also cover contained dispatch sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.
 
 | Event | Mode | Declared in | Dispatchers | Listeners |
 | --- | --- | --- | --- | --- |
@@ -15,7 +15,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/queued` | `emit` | [`packages/core/agent/src/types.ts:167`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | - |
 | `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:224`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
 | `agent/session-prefix` | `waterfall` | [`packages/core/agent/src/types.ts:239`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`tool-skill`](../packages/skill/tool-skill) |
-| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:180`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`invariants`](../packages/support/invariants) |
+| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:180`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `agent/status` | `emit` | [`packages/core/agent/src/types.ts:157`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`invariants`](../packages/support/invariants), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`stdio-agent`](../packages/ui/stdio-agent) |
 | `agent/step-result` | `waterfall` | [`packages/core/agent/src/types.ts:250`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | - |
 | `agent/turn-continuation` | `waterfall` | [`packages/core/agent/src/types.ts:260`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
@@ -25,16 +25,16 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `fs/observed` | `emit` | [`packages/fs/fs/src/index.ts:68`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`emit`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `fs/write-intent` | `waterfall` | [`packages/fs/fs/src/index.ts:51`](../packages/fs/fs/src/index.ts) | [`tool-fs`](../packages/fs/tool-fs) (`waterfall`) | [`fs-policy`](../packages/fs/fs-policy) |
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:39`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`invariants`](../packages/support/invariants), [`llm-replay`](../packages/support/llm-replay) |
-| `session/created` | `emit` | [`packages/core/session/src/index.ts:46`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence) |
-| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:55`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | - |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:66`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio-agent`](../packages/ui/stdio-agent) |
-| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:75`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence) |
+| `session/created` | `emit` | [`packages/core/session/src/index.ts:47`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence) |
+| `session/disposed` | `emit` | [`packages/core/session/src/index.ts:57`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | - |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:69`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio-agent`](../packages/ui/stdio-agent) |
+| `session/flush` | `parallel` | [`packages/core/session/src/index.ts:79`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence) |
 | `skill/provider-added` | `emit` | [`packages/skill/skill/src/index.ts:131`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`emit`) | - |
 | `skill/provider-removed` | `emit` | [`packages/skill/skill/src/index.ts:137`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`emit`) | - |
-| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:90`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc) |
+| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:92`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:66`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:72`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:82`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) |
+| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:83`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude) |
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:27`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | - |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:33`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
 | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:116`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
@@ -55,4 +55,4 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | --- | --- | --- |
 | `internal/dispatch` | - | [`invariants`](../packages/support/invariants) |
 
-Maintenance mode: hybrid generated: Cordis event declarations and most producer/listener edges are AST-scanned; dynamic dispatch sites are classified in `scripts/gen-doc-graphs.ts`.
+Maintenance mode: generated: Cordis event declarations and producer/listener edges are resolved from the repository TypeScript Program.
diff --git a/docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md b/docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
index f09ab214f5..e58fcab37a 100644
--- a/docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
+++ b/docs/rfc/implemented/architecture/2026-07-12-agent-scope-runtime-design.md
@@ -328,7 +328,7 @@ The plugin does not police trusted setup by scanning registries or reject prompt
 
 ### Generated artifacts keep public contracts aligned
 
-The event catalog, service catalog, producer/consumer matrix, configuration catalog, module graph, tool catalog, and type-equivalence blocks are generated or freshness-gated from source. `verify-scoped-dispatch` keeps the declared scoped-event set aligned with runtime invariant coverage.
+The event catalog, service catalog, producer/consumer matrix, configuration catalog, module graph, tool catalog, type-equivalence blocks, and scoped-event resolver map are generated or freshness-gated from source. The scoped-event generator derives each resolver from `this: Scoped<…>` signatures and real `scopeTarget` key types, compiles it against merged `Events`, and uses `@dshScopeScan unsupported` only when an external key permits presence checks alone.
 
 Behavioral tests pin scoped routing and disposal, final-entry collision cleanup, publication rollback, ordered quiescence, durable pre/post-commit behavior, live tool filtering across presentation and execution, cooperative prompt assembly, structured-output commit in native and Code Mode, async subagent startup and signal cancellation, worker terminal arbitration, ACP settlement, and process teardown.
 
diff --git a/package.json b/package.json
index a9ce8a6b87..b436a161fe 100644
--- a/package.json
+++ b/package.json
@@ -65,10 +65,11 @@
     "gen-persistence-catalog": "tsx scripts/gen-persistence-catalog.ts",
     "verify-persistence-catalog": "tsx scripts/gen-persistence-catalog.ts --check",
     "gen-module-graph": "tsx scripts/gen-module-graph.ts",
-    "verify-scoped-dispatch": "tsx scripts/verify-scoped-dispatch.ts",
+    "gen-scoped-events": "tsx scripts/gen-scoped-events.ts",
+    "verify-scoped-events": "tsx scripts/gen-scoped-events.ts --check",
     "verify-module-graph": "tsx scripts/gen-module-graph.ts --check",
     "constraints": "tsx scripts/check-workspace-constraints.ts",
-    "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-cordis-api && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-scoped-dispatch && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-package-readme-model-experience && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets && pnpm run verify-package-readme-limitations",
+    "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-cordis-api && pnpm run verify-export-jsdoc && pnpm run verify-tool-catalog && pnpm run verify-config-catalog && pnpm run verify-persistence-catalog && pnpm run verify-doc-graphs && pnpm run verify-scoped-events && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-package-readme-model-experience && pnpm run verify-mermaid && pnpm run verify-rfc-classification && pnpm run verify-rfc-format && pnpm run verify-type-equiv && pnpm run verify-translation-pairing && pnpm run verify-doc-budgets && pnpm run verify-package-readme-limitations",
     "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-cordis-config && pnpm run verify-node-next-types && pnpm run verify-runtime-closure",
     "demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml",
     "demo:repl": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml",
diff --git a/packages/core/session/src/index.ts b/packages/core/session/src/index.ts
index 28312abb7a..89f1627445 100644
--- a/packages/core/session/src/index.ts
+++ b/packages/core/session/src/index.ts
@@ -41,6 +41,7 @@ declare module 'cordis' {
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
      * receive only sessions entered through that agent's context.
      * @param session - the session just entered and announced.
+     * @dshScopeScan unsupported
      * @mode emit
      */
     'session/created'(this: Scoped<Session>, session: Session): void
@@ -50,6 +51,7 @@ declare module 'cordis' {
      * did not begin. Listener failures are logged and contained.
      * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
      * @param session - the session that is no longer live in the store.
+     * @dshScopeScan unsupported
      * @mode emit
      */
     'session/disposed'(this: Scoped<Session>, session: Session): void
@@ -61,6 +63,7 @@ declare module 'cordis' {
      * receive only events from sessions entered through that agent's context.
      * @param session - the session whose log grew.
      * @param event - the appended event, exactly as recorded.
+     * @dshScopeScan unsupported
      * @mode emit
      */
     'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
@@ -70,6 +73,7 @@ declare module 'cordis' {
      * {@link SessionStore.flush}. Scope-filtered dispatch
      * (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
      * @param session - the session whose buffered events must reach durable storage.
+     * @dshScopeScan unsupported
      * @mode parallel
      */
     'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index 4635de9697..8657e7d06e 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -77,6 +77,7 @@ declare module 'cordis' {
      * parent-scoped listener observes only its own delegations. Paired with
      * `subagent/end`.
      * @param info - the provider and ready child identity.
+     * @dshScopeScan unsupported
      * @mode emit
      */
     'subagent/start'(this: Scoped<SubagentService>, info: SubagentRunInfo): void
@@ -85,6 +86,7 @@ declare module 'cordis' {
      * parent carrier as `subagent/start`, so the lifecycle pair reaches the
      * same scoped audience.
      * @param info - the run identity and terminal outcome.
+     * @dshScopeScan unsupported
      * @mode emit
      */
     'subagent/end'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void
diff --git a/packages/support/invariants/package.json b/packages/support/invariants/package.json
index 3568465d18..85a249dbd1 100644
--- a/packages/support/invariants/package.json
+++ b/packages/support/invariants/package.json
@@ -33,6 +33,10 @@
     "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-scope": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-approval": "workspace:^",
     "cordis": "^4.0.0-rc.6"
   }
 }
diff --git a/packages/support/invariants/src/index.ts b/packages/support/invariants/src/index.ts
index f5b7828a3d..8da5429b06 100644
--- a/packages/support/invariants/src/index.ts
+++ b/packages/support/invariants/src/index.ts
@@ -14,6 +14,7 @@ import type { CallId, GenerateOptions } from '@deepseek-ai/dsh-llm'
 import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
 import { Session, SessionId, foldRequestHeader } from '@deepseek-ai/dsh-session'
 import type { SessionEvent, SurfaceEventType } from '@deepseek-ai/dsh-session'
+import { scopedSubjectResolverFor } from './scoped-events.generated.ts'
 
 export const name = 'invariants'
 export const inject = ['sessions']
@@ -75,17 +76,6 @@ interface SessionTraceTransition {
   seq: number
 }
 
-/** Event payload prefix for scoped seams whose first argument names its agent. */
-interface AgentSubject {
-  agent: Agent
-}
-
-/** Structural subject fields used without coupling this dev plugin to owning services. */
-interface ScopedSubjectFields {
-  agent?: Agent
-  scope?: object
-}
-
 /** Assert that a step-scoped event names the currently open turn and step. */
 function requireOpenStep(trace: SessionTrace, kind: string, turn: number, step: number): void {
   if (trace.openTurn !== turn || trace.openStep !== step) {
@@ -410,40 +400,12 @@ export function apply(ctx: Context): void {
   // (agent-scoped listeners over-hear foreign agents), and a mis-keyed one
   // delivers to the wrong agent's listeners. `internal/dispatch` fires
   // synchronously before listener delivery, so a violation throws at the
-  // dispatching call site. The table maps each family to how its subject is
-  // read from the event arguments; `null` = the subject is not recoverable
-  // from the arguments (session events key by the OWNING agent; subagent
-  // lifecycle events key by the delegating parent), so only carrier
-  // PRESENCE is asserted there.
-  const scopedSubject: Record<string, ((args: unknown[]) => unknown) | null> = {
-    'agent/created': args => args[0],
-    'agent/disposed': args => args[0],
-    'agent/status': args => args[0],
-    'agent/queued': args => args[0],
-    'agent/session-start': args => args[0],
-    'agent/pre-step': args => args[0],
-    'agent/prompt-submit': args => args[0],
-    'agent/request': args => args[0],
-    'agent/session-prefix': args => args[0],
-    'agent/step-result': args => args[0],
-    'agent/turn-continuation': args => args[0],
-    'agent/turn-stop': args => args[0],
-    'agent/error': args => args[0],
-    'approval/request': args => (args[0] as AgentSubject).agent,
-    'tools/pre-execute': args => (args[0] as ScopedSubjectFields).agent,
-    'tools/execute': args => (args[0] as ScopedSubjectFields).agent,
-    'tools/post-execute': args => (args[0] as ScopedSubjectFields).agent,
-    'tools/result': args => (args[0] as ScopedSubjectFields).agent,
-    'system-prompt/assemble': args => (args[1] as ScopedSubjectFields).scope,
-    'session/created': null,
-    'session/disposed': null,
-    'session/event': null,
-    'session/flush': null,
-    'subagent/start': null,
-    'subagent/end': null,
-  }
+  // dispatching call site. The generated table maps each family to the unique
+  // payload path whose Program type matches the real scopeTarget routing key;
+  // `null` means the key is external to the payload, so only carrier presence
+  // can be asserted.
   ctx.on('internal/dispatch', (_mode, name, args, thisArg) => {
-    const subjectOf = scopedSubject[name]
+    const subjectOf = scopedSubjectResolverFor(name)
     if (subjectOf === undefined) return
     if (!isScopeCarrier(thisArg)) {
       throw new InvariantError(
diff --git a/packages/support/invariants/src/scoped-events.generated.ts b/packages/support/invariants/src/scoped-events.generated.ts
new file mode 100644
index 0000000000..06cca6bf55
--- /dev/null
+++ b/packages/support/invariants/src/scoped-events.generated.ts
@@ -0,0 +1,69 @@
+/**
+ * Generated scoped-event routing-subject resolvers for dsh-invariants.
+ * Do not edit by hand; run `pnpm run gen-scoped-events`.
+ *
+ * @module @deepseek-ai/dsh-invariants/scoped-events.generated
+ */
+
+import type { Events } from 'cordis'
+import type { Scoped } from '@deepseek-ai/dsh-scope'
+import type {} from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-subagent'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import type {} from '@deepseek-ai/dsh-tools'
+import type {} from '@deepseek-ai/dsh-user-approval'
+
+type ScopedEventName = {
+  [K in keyof Events]: ThisParameterType<Events[K]> extends Scoped<object> ? K : never
+}[keyof Events]
+
+type ScopedSubjectResolver = (args: readonly unknown[]) => unknown
+
+function adapt<K extends ScopedEventName>(
+  resolver: (args: Parameters<Events[K]>) => unknown,
+): ScopedSubjectResolver {
+  return args => resolver(args as Parameters<Events[K]>)
+}
+
+const scopedSubjectResolvers = Object.freeze({
+  'agent/created': adapt<'agent/created'>(args => args[0]),
+  'agent/disposed': adapt<'agent/disposed'>(args => args[0]),
+  'agent/error': adapt<'agent/error'>(args => args[0]),
+  'agent/pre-step': adapt<'agent/pre-step'>(args => args[0]),
+  'agent/prompt-submit': adapt<'agent/prompt-submit'>(args => args[0]),
+  'agent/queued': adapt<'agent/queued'>(args => args[0]),
+  'agent/request': adapt<'agent/request'>(args => args[0]),
+  'agent/session-prefix': adapt<'agent/session-prefix'>(args => args[0]),
+  'agent/session-start': adapt<'agent/session-start'>(args => args[0]),
+  'agent/status': adapt<'agent/status'>(args => args[0]),
+  'agent/step-result': adapt<'agent/step-result'>(args => args[0]),
+  'agent/turn-continuation': adapt<'agent/turn-continuation'>(args => args[0]),
+  'agent/turn-stop': adapt<'agent/turn-stop'>(args => args[0]),
+  'approval/request': adapt<'approval/request'>(args => args[0].agent),
+  'session/created': null,
+  'session/disposed': null,
+  'session/event': null,
+  'session/flush': null,
+  'subagent/end': null,
+  'subagent/start': null,
+  'system-prompt/assemble': adapt<'system-prompt/assemble'>(args => args[1].scope),
+  'tools/execute': adapt<'tools/execute'>(args => args[0].agent),
+  'tools/post-execute': adapt<'tools/post-execute'>(args => args[0].agent),
+  'tools/pre-execute': adapt<'tools/pre-execute'>(args => args[0].agent),
+  'tools/result': adapt<'tools/result'>(args => args[0].agent),
+} as const satisfies Readonly<Record<ScopedEventName, ScopedSubjectResolver | null>>)
+
+const scopedSubjectResolverIndex: Readonly<Record<string, ScopedSubjectResolver | null>> = scopedSubjectResolvers
+
+/**
+ * Resolve the routing key named by one scoped event payload. A null
+ * resolver means the payload cannot expose its external routing key, so the
+ * invariant checks carrier presence only.
+ * @param event - runtime Cordis event name.
+ * @returns the generated subject resolver, null for presence-only,
+ *   or undefined when the event is not scope-filtered.
+ */
+export function scopedSubjectResolverFor(event: string): ScopedSubjectResolver | null | undefined {
+  return scopedSubjectResolverIndex[event]
+}
diff --git a/packages/support/invariants/tests/invariants.spec.ts b/packages/support/invariants/tests/invariants.spec.ts
index e53b0b8e40..0212501114 100644
--- a/packages/support/invariants/tests/invariants.spec.ts
+++ b/packages/support/invariants/tests/invariants.spec.ts
@@ -834,7 +834,7 @@ describe('scoped-dispatch invariants', () => {
 
   it('accepts a matching carrier and rejects a mismatched one for EVERY agent-subject event', async () => {
     const ctx = await scopedCtx()
-    // Real Session objects: the session-start tracker WeakSet-keys them.
+    // Real Session objects keep the synthetic Agent handles structurally valid.
     const agent = { id: 'a1', session: new Session(SessionId('a1-s')) } as unknown as Agent
     const other = { id: 'a2', session: new Session(SessionId('a2-s')) } as unknown as Agent
     // One dispatch per table row keeps every subject extractor covered: the
diff --git a/packages/support/invariants/tsconfig.json b/packages/support/invariants/tsconfig.json
index cd17f67d7c..6c5bc479b5 100644
--- a/packages/support/invariants/tsconfig.json
+++ b/packages/support/invariants/tsconfig.json
@@ -25,6 +25,18 @@
     },
     {
       "path": "../../core/scope"
+    },
+    {
+      "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../../ui/user-approval"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../../subagent/subagent"
     }
   ]
 }
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 70e54d7b05..1905b80887 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -1107,6 +1107,18 @@ importers:
       '@deepseek-ai/dsh-session':
         specifier: workspace:^
         version: link:../../core/session
+      '@deepseek-ai/dsh-subagent':
+        specifier: workspace:^
+        version: link:../../subagent/subagent
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      '@deepseek-ai/dsh-user-approval':
+        specifier: workspace:^
+        version: link:../../ui/user-approval
       cordis:
         specifier: ^4.0.0-rc.6
         version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 468a46e904..9629e367d7 100644
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -5,7 +5,7 @@
  * `--check` verifies the generated set.
  */
 
-import { existsSync, globSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, relative, resolve } from 'node:path'
 import ts from 'typescript'
 import { collectEvents, collectServices } from './gen-cordis-catalog.ts'
@@ -15,6 +15,7 @@ import {
   graphNodeId as nodeId,
   type PackageGraphNode,
 } from './package-graph.ts'
+import { TypeScriptProject } from './ts-project.ts'
 
 const root = resolve(import.meta.dirname, '..')
 type Pkg = PackageGraphNode
@@ -45,6 +46,14 @@ interface EventRelation {
   listeners: Set<string>
 }
 
+interface PackageSource {
+  rel: string
+  pkg: string
+  sourceFile: ts.SourceFile
+}
+
+type EventReceiverKind = 'context' | 'agent-dispatch' | 'events-service'
+
 const GROUP_ORDER = [
   'util',
   'llm',
@@ -242,51 +251,6 @@ const SERVICE_ROLES: ServiceRole[] = [
   },
 ]
 
-const DYNAMIC_EVENT_DISPATCHERS: Array<{ event: string; pkg: string; method: string }> = [
-  // Creation notifications preserve synchronous veto/rollback but observe
-  // returned promises explicitly so async listener rejection is not unhandled.
-  { event: 'agent/created', pkg: 'agent', method: 'events.dispatch' },
-  // Registry disposal reuses the stable carrier captured before entry commit
-  // and contains each listener directly rather than rebuilding via agentEvents.
-  { event: 'agent/disposed', pkg: 'agent', method: 'events.dispatch' },
-  { event: 'session/created', pkg: 'session', method: 'events.dispatch' },
-  // Session event callbacks are likewise resolved before the log push, then
-  // invoked individually after commit so observer failures are contained.
-  { event: 'session/event', pkg: 'session', method: 'events.dispatch' },
-  // Flush resolves the scoped callback set directly so internal instrumentation
-  // cannot substitute the accepted session before parallel invocation.
-  { event: 'session/flush', pkg: 'session', method: 'events.dispatch' },
-  // Session disposal uses direct callback resolution so teardown contains each
-  // synchronous throw and returned-promise rejection independently.
-  { event: 'session/disposed', pkg: 'session', method: 'events.dispatch' },
-  // tools/result uses ctx.events.dispatch directly so the registry can invoke
-  // every synchronous observer while containing each callback independently.
-  { event: 'tools/result', pkg: 'tools', method: 'events.dispatch' },
-  // Subagent lifecycle events intentionally bypass ctx.emit and call
-  // ctx.events.dispatch directly so one throwing listener cannot starve later
-  // listeners or strand an already-started child run.
-  { event: 'subagent/start', pkg: 'subagent', method: 'events.dispatch' },
-  { event: 'subagent/end', pkg: 'subagent', method: 'events.dispatch' },
-  // provider-removed fires inside the provider registration's DISPOSER and
-  // routes through the same contained dispatch (see emitLifecycle in
-  // dsh-subagent), so the AST scan cannot attribute it either.
-  { event: 'subagent/provider-removed', pkg: 'subagent', method: 'events.dispatch' },
-  // The workflow/* lifecycle events dispatch the same way, for the same
-  // per-listener-containment reason (WorkflowService.emitWorkflowEvent).
-  { event: 'workflow/start', pkg: 'workflow', method: 'events.dispatch' },
-  { event: 'workflow/phase', pkg: 'workflow', method: 'events.dispatch' },
-  { event: 'workflow/log', pkg: 'workflow', method: 'events.dispatch' },
-  { event: 'workflow/agent-start', pkg: 'workflow', method: 'events.dispatch' },
-  { event: 'workflow/agent-end', pkg: 'workflow', method: 'events.dispatch' },
-  { event: 'workflow/end', pkg: 'workflow', method: 'events.dispatch' },
-]
-
-const DYNAMIC_EVENT_LISTENERS: Array<{ event: string; pkg: string }> = [
-  // The invariants oracle marks the session started from its global
-  // internal/dispatch listener before product session-start callbacks run.
-  { event: 'agent/session-start', pkg: 'invariants' },
-]
-
 function generatedHeader(title: string): string[] {
   return [
     '<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.',
@@ -505,81 +469,256 @@ function renderAppComposition(example: AppExample): string {
   return lines.join('\n')
 }
 
-function collectEventRelations(): Map<string, EventRelation> {
-  const out = new Map<string, EventRelation>()
-  const ensure = (event: string): EventRelation => {
-    const existing = out.get(event)
-    if (existing) return existing
-    const next = { dispatchers: new Map<string, Set<string>>(), listeners: new Set<string>() }
-    out.set(event, next)
-    return next
+/** Collect event dispatch/listener relations from real cross-file receiver types. */
+class EventRelationCollector {
+  private readonly relations = new Map<string, EventRelation>()
+  private readonly callSites = new Map<ts.SignatureDeclaration | ts.JSDocSignature, ts.CallExpression[]>()
+  private readonly contextType: ts.Type
+  private readonly agentDispatchType: ts.Type
+  private readonly eventsServiceType: ts.Type
+
+  constructor(
+    private readonly project: TypeScriptProject,
+    private readonly sources: readonly PackageSource[],
+  ) {
+    this.contextType = this.declaredType('vendor/cordis/src/context.ts', 'Context')
+    this.agentDispatchType = this.declaredType('packages/core/agent/src/dispatch.ts', 'AgentEventDispatch')
+    this.eventsServiceType = this.declaredType('vendor/cordis/src/events.ts', 'EventsService')
+    this.indexCallSites()
   }
-  for (const rel of globSync('packages/*/*/src/**/*.ts', { cwd: root }).sort()) {
-    const [, , leaf] = rel.split('/')
-    if (leaf === undefined) continue
-    const text = readFileSync(resolve(root, rel), 'utf8')
-    const sf = ts.createSourceFile(rel, text, ts.ScriptTarget.Latest, true)
+
+  /** Return all event relations discovered from the Program. */
+  collect(): Map<string, EventRelation> {
+    for (const source of this.sources) this.visitSource(source)
+    return this.relations
+  }
+
+  /** Resolve one named class/interface declaration to its merged instance type. */
+  private declaredType(relativePath: string, name: string): ts.Type {
+    const sourceFile = this.project.sourceFile(relativePath)
+    const declaration = sourceFile.statements.find((statement): statement is ts.ClassDeclaration | ts.InterfaceDeclaration => {
+      return (ts.isClassDeclaration(statement) || ts.isInterfaceDeclaration(statement)) && statement.name?.text === name
+    })
+    const symbol = declaration?.name && this.project.checker.getSymbolAtLocation(declaration.name)
+    if (!symbol) throw new Error(`cannot resolve TypeScript type ${name} from ${relativePath}`)
+    return this.project.checker.getDeclaredTypeOfSymbol(symbol)
+  }
+
+  /** Index resolved local function calls for narrow argument-flow recovery. */
+  private indexCallSites(): void {
+    const visit = (node: ts.Node): void => {
+      if (ts.isCallExpression(node)) {
+        const declaration = this.project.checker.getResolvedSignature(node)?.declaration
+        if (declaration) {
+          const calls = this.callSites.get(declaration) ?? []
+          calls.push(node)
+          this.callSites.set(declaration, calls)
+        }
+      }
+      ts.forEachChild(node, visit)
+    }
+    for (const source of this.sources) visit(source.sourceFile)
+  }
+
+  /** Walk one package source file and classify event API calls by receiver type. */
+  private visitSource(source: PackageSource): void {
     const visit = (node: ts.Node): void => {
       if (ts.isCallExpression(node) && ts.isPropertyAccessExpression(node.expression)) {
+        const receiverKind = this.receiverKind(node.expression.expression)
         const method = node.expression.name.text
-        if (!isCordisContextReceiver(node.expression, sf)) {
-          ts.forEachChild(node, visit)
-          return
-        }
-        if (method === 'on') {
-          const event = eventArg(node.arguments, method)
-          if (event) ensure(event).listeners.add(leaf)
-        } else if (method === 'emit' || method === 'parallel' || method === 'serial' || method === 'waterfall') {
-          const event = eventArg(node.arguments, method)
-          if (event) {
-            const relation = ensure(event)
-            const methods = relation.dispatchers.get(leaf) ?? new Set<string>()
-            methods.add(method)
-            relation.dispatchers.set(leaf, methods)
+        if (receiverKind === 'events-service' && method === 'dispatch') {
+          const argumentList = node.arguments[1]
+          if (argumentList) {
+            for (const event of this.eventNamesFromArgumentList(argumentList, new Set())) {
+              this.addDispatcher(event, source.pkg, 'events.dispatch')
+            }
+          }
+        } else if (receiverKind === 'context' || receiverKind === 'agent-dispatch') {
+          const eventNames = this.eventNamesFromCall(node, receiverKind)
+          if (method === 'on') {
+            for (const event of eventNames) this.ensure(event).listeners.add(source.pkg)
+          } else if (method === 'emit' || method === 'parallel' || method === 'serial' || method === 'waterfall') {
+            for (const event of eventNames) this.addDispatcher(event, source.pkg, method)
           }
         }
       }
       ts.forEachChild(node, visit)
     }
-    visit(sf)
+    visit(source.sourceFile)
   }
-  for (const entry of DYNAMIC_EVENT_DISPATCHERS) {
-    const relation = ensure(entry.event)
-    const methods = relation.dispatchers.get(entry.pkg) ?? new Set<string>()
-    methods.add(entry.method)
-    relation.dispatchers.set(entry.pkg, methods)
+
+  /** Classify a receiver using assignability to the repository's actual event API types. */
+  private receiverKind(receiver: ts.Expression): EventReceiverKind | undefined {
+    const type = this.project.checker.getTypeAtLocation(receiver)
+    if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never)) return undefined
+    if (this.project.checker.isTypeAssignableTo(type, this.eventsServiceType)) return 'events-service'
+    if (this.project.checker.isTypeAssignableTo(type, this.contextType)) return 'context'
+    if (this.project.checker.isTypeAssignableTo(type, this.agentDispatchType)) return 'agent-dispatch'
+    return undefined
   }
-  for (const entry of DYNAMIC_EVENT_LISTENERS) {
-    ensure(entry.event).listeners.add(entry.pkg)
+
+  /** Resolve the event-name argument for Context and fused agent dispatch calls. */
+  private eventNamesFromCall(call: ts.CallExpression, receiverKind: Exclude<EventReceiverKind, 'events-service'>): Set<string> {
+    const candidates = receiverKind === 'context' ? call.arguments.slice(0, 2) : call.arguments.slice(0, 1)
+    for (const candidate of candidates) {
+      const values = this.finiteStringValues(candidate)
+      if (values) return values
+    }
+    return new Set()
   }
+
+  /** Recover the event slot from the argument array handed to EventsService.dispatch(). */
+  private eventNamesFromArgumentList(expression: ts.Expression, seen: Set<ts.Node>): Set<string> {
+    const current = unwrapExpression(expression)
+    if (seen.has(current)) return new Set()
+    seen.add(current)
+
+    if (ts.isArrayLiteralExpression(current)) {
+      for (const element of current.elements.slice(0, 2)) {
+        if (ts.isOmittedExpression(element) || ts.isSpreadElement(element)) continue
+        const values = this.finiteStringValues(element)
+        if (values) return values
+      }
+      return new Set()
+    }
+    if (ts.isConditionalExpression(current)) {
+      return unionSets(
+        this.eventNamesFromArgumentList(current.whenTrue, new Set(seen)),
+        this.eventNamesFromArgumentList(current.whenFalse, new Set(seen)),
+      )
+    }
+    if (!ts.isIdentifier(current)) return new Set()
+
+    const symbol = this.project.checker.getSymbolAtLocation(current)
+    if (!symbol) return new Set()
+    const events = new Set<string>()
+    for (const declaration of symbol.declarations ?? []) {
+      if (ts.isVariableDeclaration(declaration) && declaration.initializer && isConstDeclaration(declaration)) {
+        addAll(events, this.eventNamesFromArgumentList(declaration.initializer, new Set(seen)))
+      } else if (ts.isParameter(declaration)) {
+        addAll(events, this.eventNamesFromParameter(declaration, seen))
+      }
+    }
+    return events
+  }
+
+  /** Follow a non-exported local helper parameter back to every resolved call site. */
+  private eventNamesFromParameter(parameter: ts.ParameterDeclaration, seen: Set<ts.Node>): Set<string> {
+    const owner = parameter.parent
+    if (!ts.isFunctionDeclaration(owner) || hasExportModifier(owner)) return new Set()
+    const index = owner.parameters.indexOf(parameter)
+    if (index < 0) return new Set()
+    const events = new Set<string>()
+    for (const call of this.callSites.get(owner) ?? []) {
+      const argument = call.arguments[index]
+      if (argument) addAll(events, this.eventNamesFromArgumentList(argument, new Set(seen)))
+    }
+    return events
+  }
+
+  /** Return a finite string-literal value set, rejecting widened and generic strings. */
+  private finiteStringValues(expression: ts.Expression): Set<string> | undefined {
+    const current = unwrapExpression(expression)
+    if (ts.isStringLiteralLike(current)) return new Set([current.text])
+    if (this.isForwardedAgentEventParameter(current)) return undefined
+    return finiteStringTypeValues(this.project.checker.getTypeAtLocation(current))
+  }
+
+  /** Reject the contextual parameter inside the AgentEventDispatch forwarding object. */
+  private isForwardedAgentEventParameter(expression: ts.Expression): boolean {
+    if (!ts.isIdentifier(expression)) return false
+    const declarations = this.project.checker.getSymbolAtLocation(expression)?.declarations ?? []
+    return declarations.some((declaration) => {
+      if (!ts.isParameter(declaration)) return false
+      const method = declaration.parent
+      if (!ts.isMethodDeclaration(method) || !ts.isObjectLiteralExpression(method.parent)) return false
+      const contextualType = this.project.checker.getContextualType(method.parent)
+      return contextualType !== undefined
+        && this.project.checker.isTypeAssignableTo(contextualType, this.agentDispatchType)
+    })
+  }
+
+  /** Get or create one relation row. */
+  private ensure(event: string): EventRelation {
+    const existing = this.relations.get(event)
+    if (existing) return existing
+    const relation = { dispatchers: new Map<string, Set<string>>(), listeners: new Set<string>() }
+    this.relations.set(event, relation)
+    return relation
+  }
+
+  /** Add one dispatcher method without duplicating package/method labels. */
+  private addDispatcher(event: string, pkg: string, method: string): void {
+    const relation = this.ensure(event)
+    const methods = relation.dispatchers.get(pkg) ?? new Set<string>()
+    methods.add(method)
+    relation.dispatchers.set(pkg, methods)
+  }
+}
+
+/** Peel syntax-only wrappers that do not change an expression's runtime value. */
+function unwrapExpression(expression: ts.Expression): ts.Expression {
+  let current = expression
+  while (
+    ts.isParenthesizedExpression(current)
+    || ts.isAsExpression(current)
+    || ts.isTypeAssertionExpression(current)
+    || ts.isNonNullExpression(current)
+    || ts.isSatisfiesExpression(current)
+  ) {
+    current = current.expression
+  }
+  return current
+}
+
+/** Return every value only when a type is a closed string-literal union. */
+function finiteStringTypeValues(type: ts.Type): Set<string> | undefined {
+  if (type.flags & ts.TypeFlags.StringLiteral) {
+    return new Set([(type as ts.StringLiteralType).value])
+  }
+  if (type.flags & ts.TypeFlags.Never) return new Set()
+  if (!type.isUnion()) return undefined
+  const values = new Set<string>()
+  for (const member of type.types) {
+    const memberValues = finiteStringTypeValues(member)
+    if (!memberValues) return undefined
+    addAll(values, memberValues)
+  }
+  return values
+}
+
+/** Return whether a variable declaration belongs to a const declaration list. */
+function isConstDeclaration(declaration: ts.VariableDeclaration): boolean {
+  return (declaration.parent.flags & ts.NodeFlags.Const) !== 0
+}
+
+/** Return whether a declaration is visible to callers outside its source module. */
+function hasExportModifier(node: ts.Node): boolean {
+  return ts.canHaveModifiers(node) && (ts.getModifiers(node)?.some((modifier) => {
+    return modifier.kind === ts.SyntaxKind.ExportKeyword || modifier.kind === ts.SyntaxKind.DefaultKeyword
+  }) ?? false)
+}
+
+/** Add every member of source to target. */
+function addAll<T>(target: Set<T>, source: ReadonlySet<T>): void {
+  for (const value of source) target.add(value)
+}
+
+/** Return the union of two sets without mutating either input. */
+function unionSets<T>(left: ReadonlySet<T>, right: ReadonlySet<T>): Set<T> {
+  const out = new Set(left)
+  addAll(out, right)
   return out
 }
 
-function isCordisContextReceiver(expr: ts.PropertyAccessExpression, sf: ts.SourceFile): boolean {
-  // The chained fused-dispatch spelling: `agentEvents(ctx, agent).emit(…)` —
-  // the receiver is a call expression, not an identifier.
-  if (ts.isCallExpression(expr.expression) && expr.expression.expression.getText(sf) === 'agentEvents') {
-    return true
-  }
-  const target = expr.expression.getText(sf)
-  if (target === 'ctx' || target === 'this.ctx') return true
-  // Scoped-dispatch spellings are conventional names. Keep this list in sync
-  // with renames or the relationship matrix can silently lose an edge.
-  return target === 'events' || target === 'childCtx' || target === 'this.loopCtx' || target === 'emitCtx'
-}
-
-function eventArg(args: ts.NodeArray<ts.Expression>, method: string): string | undefined {
-  if (method === 'waterfall') {
-    const arg = args.find(ts.isStringLiteralLike)
-    return arg?.text
-  }
-  const first = args[0]
-  if (first && ts.isStringLiteralLike(first)) return first.text
-  // Scope-carrier dispatch: `emit(carrier, 'event/name', …)` puts the event
-  // name second. Accept a string literal in position 1 when position 0 is a
-  // non-literal expression (the carrier).
-  const second = args[1]
-  return second && ts.isStringLiteralLike(second) ? second.text : undefined
+function collectEventRelations(): Map<string, EventRelation> {
+  const project = new TypeScriptProject(root)
+  const sources = project.sourceFiles().flatMap((sourceFile): PackageSource[] => {
+    const rel = project.relativePath(sourceFile)
+    const match = /^packages\/[^/]+\/([^/]+)\/src\/.+\.ts$/.exec(rel)
+    return match?.[1] ? [{ rel, pkg: match[1], sourceFile }] : []
+  }).sort((left, right) => left.rel.localeCompare(right.rel))
+  return new EventRelationCollector(project, sources).collect()
 }
 
 function relationPackages(map: Map<string, Set<string>>, pkgsByShort: Map<string, Pkg>): string {
@@ -599,10 +738,10 @@ function renderEventRelations(pkgs: Pkg[]): string {
   const events = collectEvents()
   const relations = collectEventRelations()
   const pkgsByShort = new Map(pkgs.map(pkg => [pkg.short, pkg]))
-  const maintenance = 'hybrid generated: Cordis event declarations and most producer/listener edges are AST-scanned; dynamic dispatch sites are classified in `scripts/gen-doc-graphs.ts`'
+  const maintenance = 'generated: Cordis event declarations and producer/listener edges are resolved from the repository TypeScript Program'
   const lines = generatedHeader('Event Producer And Consumer Matrix')
   lines.push(
-    'This matrix shows which packages dispatch each harness-owned event and which packages listen to it. It is intentionally a table rather than one large graph: events are many-to-many, and dense relation data is easier to review in rows. Dynamic dispatch overrides cover sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.',
+    'This matrix shows which packages dispatch each harness-owned event and which packages listen to it. It is intentionally a table rather than one large graph: events are many-to-many, and dense relation data is easier to review in rows. Receiver and event-name types also cover contained dispatch sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.',
     '',
     '| Event | Mode | Declared in | Dispatchers | Listeners |',
     '| --- | --- | --- | --- | --- |',
@@ -612,7 +751,7 @@ function renderEventRelations(pkgs: Pkg[]): string {
     lines.push(`| \`${event.name}\` | \`${event.mode}\` | ${sourceLink(event.source)} | ${relationPackages(relation.dispatchers, pkgsByShort)} | ${listenerPackages(relation.listeners, pkgsByShort)} |`)
   }
   // Every declared event needs a dispatcher: zero means dead vocabulary or an
-  // unrecognized dispatch spelling. Listener-free extension points remain valid.
+  // unrecognized semantic dispatch shape. Listener-free extension points remain valid.
   const undispatched = [...events]
     .filter(event => (relations.get(event.name)?.dispatchers.size ?? 0) === 0)
     .map(event => event.name)
@@ -620,8 +759,8 @@ function renderEventRelations(pkgs: Pkg[]): string {
   if (undispatched.length > 0) {
     throw new Error(
       `event-producer-consumer matrix: no dispatcher found for declared event${undispatched.length > 1 ? 's' : ''} `
-      + `${undispatched.map(name => `"${name}"`).join(', ')} — dead vocabulary, or a dispatch spelling the scan misses `
-      + '(teach scripts/gen-doc-graphs.ts the spelling or add a DYNAMIC_EVENT_DISPATCHERS override)',
+      + `${undispatched.map(name => `"${name}"`).join(', ')} — dead vocabulary, or a dispatch shape the semantic scan misses `
+      + '(teach scripts/gen-doc-graphs.ts the shape)',
     )
   }
   const declared = new Set(events.map(event => event.name))
diff --git a/scripts/gen-scoped-events.ts b/scripts/gen-scoped-events.ts
new file mode 100644
index 0000000000..cca0896be8
--- /dev/null
+++ b/scripts/gen-scoped-events.ts
@@ -0,0 +1,441 @@
+/**
+ * Generate the dev-invariants scoped-event resolver map from the
+ * repository TypeScript Program.
+ *
+ * A scoped event declares `this: Scoped<Base>`. Real `scopeTarget(base, key)`
+ * calls establish the routing-key type for that base. The generator searches
+ * every event payload parameter and one property level for exactly one type
+ * equivalent to that key. Each generated resolver compiles against the merged
+ * `Events` parameter tuple. Zero matches require `@dshScopeScan unsupported`;
+ * multiple matches are ambiguous and always fail loud.
+ *
+ *   `tsx scripts/gen-scoped-events.ts`          -> write the generated source
+ *   `tsx scripts/gen-scoped-events.ts --check`  -> exit 1 when it is stale
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import ts from 'typescript'
+import { pointer, rawJsDoc } from './jsdoc.ts'
+import { TypeScriptProject } from './ts-project.ts'
+
+const root = resolve(import.meta.dirname, '..')
+const OUT = 'packages/support/invariants/src/scoped-events.generated.ts'
+const SCOPE_DOC_MARKER = 'Scope-filtered dispatch'
+
+interface ScopeTargetContract {
+  baseType: ts.Type
+  keyType: ts.Type
+  source: string
+}
+
+interface SubjectCandidate {
+  path: string
+  parameter: number
+  property?: string
+  type: ts.Type
+}
+
+interface ScopedEventResolver {
+  event: string
+  candidate: SubjectCandidate | null
+  ownerPackage: string
+}
+
+interface ScopeTag {
+  present: boolean
+  unsupported: boolean
+}
+
+/** Program-backed analyzer and renderer for the generated scoped-event resolvers. */
+class ScopedEventGenerator {
+  private readonly checker: ts.TypeChecker
+  private readonly packageSources: ts.SourceFile[]
+  private readonly scopeTargetDeclaration: ts.FunctionDeclaration
+  private readonly scopedSymbol: ts.Symbol
+  private readonly violations: string[] = []
+  private readonly packageNames = new Map<string, string>()
+
+  constructor(private readonly project: TypeScriptProject) {
+    this.checker = project.checker
+    this.packageSources = project.sourceFiles().filter((sourceFile) => {
+      return /^packages\/[^/]+\/[^/]+\/src\/.+\.ts$/.test(project.relativePath(sourceFile))
+    })
+    this.scopeTargetDeclaration = this.functionDeclaration(
+      'packages/core/scope/src/index.ts',
+      'scopeTarget',
+    )
+    this.scopedSymbol = this.typeAliasSymbol(
+      'packages/core/scope/src/index.ts',
+      'Scoped',
+    )
+  }
+
+  /** Render the complete generated TypeScript module or throw every contract violation. */
+  render(): string {
+    const contracts = this.collectScopeTargetContracts()
+    const resolvers = this.collectScopedEventResolvers(contracts)
+    if (this.violations.length > 0) {
+      throw new Error(
+        `gen-scoped-events: ${this.violations.length} scoped-event contract violation(s):\n`
+        + this.violations.map(violation => `  - ${violation}`).join('\n'),
+      )
+    }
+    const ownerImports = [...new Set(resolvers.map(resolver => resolver.ownerPackage))]
+      .sort()
+      .map(packageName => `import type {} from ${quote(packageName)}`)
+    return [
+      '/**',
+      ' * Generated scoped-event routing-subject resolvers for dsh-invariants.',
+      ' * Do not edit by hand; run `pnpm run gen-scoped-events`.',
+      ' *',
+      ' * @module @deepseek-ai/dsh-invariants/scoped-events.generated',
+      ' */',
+      '',
+      "import type { Events } from 'cordis'",
+      "import type { Scoped } from '@deepseek-ai/dsh-scope'",
+      ...ownerImports,
+      '',
+      'type ScopedEventName = {',
+      '  [K in keyof Events]: ThisParameterType<Events[K]> extends Scoped<object> ? K : never',
+      '}[keyof Events]',
+      '',
+      'type ScopedSubjectResolver = (args: readonly unknown[]) => unknown',
+      '',
+      'function adapt<K extends ScopedEventName>(',
+      '  resolver: (args: Parameters<Events[K]>) => unknown,',
+      '): ScopedSubjectResolver {',
+      '  return args => resolver(args as Parameters<Events[K]>)',
+      '}',
+      '',
+      'const scopedSubjectResolvers = Object.freeze({',
+      ...resolvers.map(({ event, candidate }) => {
+        if (candidate === null) return `  '${event}': null,`
+        const subject = candidate.property === undefined
+          ? `args[${candidate.parameter}]`
+          : `args[${candidate.parameter}].${candidate.property}`
+        return `  '${event}': adapt<'${event}'>(args => ${subject}),`
+      }),
+      '} as const satisfies Readonly<Record<ScopedEventName, ScopedSubjectResolver | null>>)',
+      '',
+      'const scopedSubjectResolverIndex: Readonly<Record<string, ScopedSubjectResolver | null>> = scopedSubjectResolvers',
+      '',
+      '/**',
+      ' * Resolve the routing key named by one scoped event payload. A null',
+      ' * resolver means the payload cannot expose its external routing key, so the',
+      ' * invariant checks carrier presence only.',
+      ' * @param event - runtime Cordis event name.',
+      ' * @returns the generated subject resolver, null for presence-only,',
+      ' *   or undefined when the event is not scope-filtered.',
+      ' */',
+      'export function scopedSubjectResolverFor(event: string): ScopedSubjectResolver | null | undefined {',
+      '  return scopedSubjectResolverIndex[event]',
+      '}',
+      '',
+    ].join('\n')
+  }
+
+  /** Resolve one named function declaration from a known source file. */
+  private functionDeclaration(relativePath: string, name: string): ts.FunctionDeclaration {
+    const sourceFile = this.project.sourceFile(relativePath)
+    const declaration = sourceFile.statements.find((statement): statement is ts.FunctionDeclaration => {
+      return ts.isFunctionDeclaration(statement) && statement.name?.text === name
+    })
+    if (!declaration) throw new Error(`gen-scoped-events: cannot resolve function ${name} from ${relativePath}`)
+    return declaration
+  }
+
+  /** Resolve one named type-alias symbol from a known source file. */
+  private typeAliasSymbol(relativePath: string, name: string): ts.Symbol {
+    const sourceFile = this.project.sourceFile(relativePath)
+    const declaration = sourceFile.statements.find((statement): statement is ts.TypeAliasDeclaration => {
+      return ts.isTypeAliasDeclaration(statement) && statement.name.text === name
+    })
+    const symbol = declaration && this.checker.getSymbolAtLocation(declaration.name)
+    if (!symbol) throw new Error(`gen-scoped-events: cannot resolve type ${name} from ${relativePath}`)
+    return symbol
+  }
+
+  /** Collect every real scopeTarget(base, key) base/key type contract. */
+  private collectScopeTargetContracts(): ScopeTargetContract[] {
+    const contracts: ScopeTargetContract[] = []
+    const visit = (sourceFile: ts.SourceFile, node: ts.Node): void => {
+      if (ts.isCallExpression(node)
+        && this.checker.getResolvedSignature(node)?.declaration === this.scopeTargetDeclaration) {
+        const base = node.arguments[0]
+        const key = node.arguments[1]
+        if (!base || !key) {
+          const source = pointer(this.project.relativePath(sourceFile), sourceFile, node)
+          this.violations.push(`${source} calls scopeTarget without base and key arguments`)
+        } else {
+          contracts.push({
+            baseType: this.checker.getTypeAtLocation(base),
+            keyType: this.checker.getTypeAtLocation(key),
+            source: pointer(this.project.relativePath(sourceFile), sourceFile, node),
+          })
+        }
+      }
+      ts.forEachChild(node, child => { visit(sourceFile, child) })
+    }
+    for (const sourceFile of this.packageSources) visit(sourceFile, sourceFile)
+    return contracts
+  }
+
+  /** Collect every Events member and derive its generated resolver. */
+  private collectScopedEventResolvers(contracts: readonly ScopeTargetContract[]): ScopedEventResolver[] {
+    const resolvers: ScopedEventResolver[] = []
+    for (const sourceFile of this.packageSources) {
+      const rel = this.project.relativePath(sourceFile)
+      const ownerPackage = this.packageName(packageRootFor(rel))
+      const visit = (node: ts.Node): void => {
+        if (ts.isInterfaceDeclaration(node) && node.name.text === 'Events' && isCordisModuleInterface(node)) {
+          for (const member of node.members) {
+            if (!ts.isMethodSignature(member) || !ts.isStringLiteral(member.name)) continue
+            const event = member.name.text
+            const raw = rawJsDoc(sourceFile.text, member)
+            const where = `event '${event}' (${pointer(rel, sourceFile, member)})`
+            const tag = parseScopeTag(raw, where, this.violations)
+            const thisParameter = member.parameters.find(isThisParameter)
+            const scopedBase = thisParameter && this.scopedBaseType(thisParameter)
+            if (!scopedBase) {
+              if (raw.includes(SCOPE_DOC_MARKER)) {
+                this.violations.push(
+                  `${where} documents scope-filtered dispatch but its signature has no this: Scoped<...> receiver`,
+                )
+              }
+              if (tag.present) {
+                this.violations.push(`${where} has @dshScopeScan metadata but is not a Scoped event`)
+              }
+              continue
+            }
+            if (!raw.includes(SCOPE_DOC_MARKER)) {
+              this.violations.push(
+                `${where} has this: Scoped<...> but its JSDoc does not explain "${SCOPE_DOC_MARKER}"`,
+              )
+            }
+            const keyType = this.routingKeyType(where, scopedBase, contracts)
+            if (!keyType) continue
+            const candidates = this.subjectCandidates(member)
+              .filter(candidate => this.typesEquivalent(candidate.type, keyType))
+            if (candidates.length > 1) {
+              this.violations.push(
+                `${where} has multiple routing-key candidates for ${this.typeText(keyType)}: `
+                + candidates.map(candidate => `${candidate.path}: ${this.typeText(candidate.type)}`).join(', '),
+              )
+              continue
+            }
+            if (candidates.length === 0) {
+              if (!tag.unsupported) {
+                const keyLabel = this.typeText(keyType)
+                this.violations.push(
+                  `${where} exposes no parameter or one-level property equivalent to routing key type ${keyLabel}; `
+                  + 'add @dshScopeScan unsupported only when the key is intentionally absent from the payload',
+                )
+              }
+              resolvers.push({ event, candidate: null, ownerPackage })
+              continue
+            }
+            if (tag.unsupported) {
+              this.violations.push(
+                `${where} has unnecessary @dshScopeScan unsupported; ${candidates[0]?.path} exposes the routing key`,
+              )
+              continue
+            }
+            resolvers.push({ event, candidate: candidates[0] ?? null, ownerPackage })
+          }
+        }
+        ts.forEachChild(node, visit)
+      }
+      visit(sourceFile)
+    }
+    return resolvers.sort((left, right) => left.event.localeCompare(right.event))
+  }
+
+  /** Extract the Base type from one exact this: Scoped<Base> parameter. */
+  private scopedBaseType(parameter: ts.ParameterDeclaration): ts.Type | undefined {
+    const type = this.checker.getTypeAtLocation(parameter)
+    if (type.aliasSymbol !== this.scopedSymbol) return undefined
+    return type.aliasTypeArguments?.[0]
+  }
+
+  /** Resolve one unambiguous key type for a scoped carrier base. */
+  private routingKeyType(
+    where: string,
+    scopedBase: ts.Type,
+    contracts: readonly ScopeTargetContract[],
+  ): ts.Type | undefined {
+    const matches = contracts.filter(contract => {
+      return this.checker.isTypeAssignableTo(this.normalizedType(contract.baseType), this.normalizedType(scopedBase))
+    })
+    if (matches.length === 0) {
+      this.violations.push(
+        `${where} has no matching scopeTarget(base, key) call for carrier base ${this.typeText(scopedBase)}`,
+      )
+      return undefined
+    }
+    const keyTypes: ts.Type[] = []
+    for (const match of matches) {
+      if (!keyTypes.some(type => this.typesEquivalent(type, match.keyType))) keyTypes.push(match.keyType)
+    }
+    if (keyTypes.length > 1) {
+      this.violations.push(
+        `${where} carrier base ${this.typeText(scopedBase)} has inconsistent routing-key types: `
+        + matches.map(match => `${this.typeText(match.keyType)} at ${match.source}`).join(', '),
+      )
+      return undefined
+    }
+    return keyTypes[0]
+  }
+
+  /** Enumerate every payload parameter and every accessible one-level property. */
+  private subjectCandidates(member: ts.MethodSignature): SubjectCandidate[] {
+    const candidates: SubjectCandidate[] = []
+    let runtimeIndex = 0
+    for (const parameter of member.parameters) {
+      if (isThisParameter(parameter)) continue
+      const directPath = `args[${runtimeIndex}]`
+      const parameterType = this.checker.getTypeAtLocation(parameter)
+      candidates.push({ path: directPath, parameter: runtimeIndex, type: parameterType })
+      for (const property of this.checker.getPropertiesOfType(this.normalizedType(parameterType))) {
+        const name = property.getName()
+        if (name.startsWith('__@') || hasNonPublicDeclaration(property)) continue
+        candidates.push({
+          path: `${directPath}.${name}`,
+          parameter: runtimeIndex,
+          property: name,
+          type: this.checker.getTypeOfSymbolAtLocation(property, parameter),
+        })
+      }
+      runtimeIndex += 1
+    }
+    return dedupeCandidates(candidates)
+  }
+
+  /** Read and cache one workspace package name. */
+  private packageName(packageRoot: string): string {
+    const cached = this.packageNames.get(packageRoot)
+    if (cached) return cached
+    const manifest: unknown = JSON.parse(readFileSync(resolve(root, packageRoot, 'package.json'), 'utf8'))
+    const name: unknown = typeof manifest === 'object' && manifest !== null
+      ? Reflect.get(manifest, 'name')
+      : undefined
+    if (typeof name !== 'string') throw new Error(`gen-scoped-events: ${packageRoot}/package.json has no name`)
+    this.packageNames.set(packageRoot, name)
+    return name
+  }
+
+  /** Compare exact Program type identities after removing null and undefined. */
+  private typesEquivalent(left: ts.Type, right: ts.Type): boolean {
+    const normalizedLeft = this.normalizedType(left)
+    const normalizedRight = this.normalizedType(right)
+    if (normalizedLeft.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) return false
+    if (normalizedRight.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) return false
+    return normalizedLeft === normalizedRight
+  }
+
+  /** Remove null and undefined from a routing or candidate type. */
+  private normalizedType(type: ts.Type): ts.Type {
+    return this.checker.getNonNullableType(type)
+  }
+
+  /** Render a stable diagnostic type label. */
+  private typeText(type: ts.Type): string {
+    return this.checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation)
+  }
+}
+
+/** Return whether an Events interface is inside declare module 'cordis'. */
+function isCordisModuleInterface(node: ts.InterfaceDeclaration): boolean {
+  const block = node.parent
+  const declaration = block.parent
+  return ts.isModuleBlock(block)
+    && ts.isModuleDeclaration(declaration)
+    && ts.isStringLiteral(declaration.name)
+    && declaration.name.text === 'cordis'
+}
+
+/** Return whether a parameter is the explicit TypeScript this receiver. */
+function isThisParameter(parameter: ts.ParameterDeclaration): boolean {
+  return ts.isIdentifier(parameter.name) && parameter.name.text === 'this'
+}
+
+/** Parse and validate the optional @dshScopeScan unsupported tag. */
+function parseScopeTag(raw: string, where: string, violations: string[]): ScopeTag {
+  const tags = raw
+    .replace(/^\/\*\*/, '')
+    .replace(/\*\/$/, '')
+    .split('\n')
+    .map(line => line.replace(/^\s*\*?\s?/, '').trim())
+    .filter(line => line.startsWith('@dshScopeScan'))
+  if (tags.length > 1) violations.push(`${where} has multiple @dshScopeScan tags`)
+  if (tags.length === 0) return { present: false, unsupported: false }
+  const unsupported = tags[0] === '@dshScopeScan unsupported'
+  if (!unsupported) {
+    violations.push(
+      `${where} has invalid scoped-event scan metadata '${tags[0]}'; expected '@dshScopeScan unsupported'`,
+    )
+  }
+  return { present: true, unsupported }
+}
+
+/** Return whether a property has a private or protected declaration. */
+function hasNonPublicDeclaration(symbol: ts.Symbol): boolean {
+  return (symbol.declarations ?? []).some((declaration) => {
+    if (!ts.canHaveModifiers(declaration)) return false
+    return ts.getModifiers(declaration)?.some((modifier) => {
+      return modifier.kind === ts.SyntaxKind.PrivateKeyword || modifier.kind === ts.SyntaxKind.ProtectedKeyword
+    }) ?? false
+  })
+}
+
+/** Deduplicate candidate paths contributed by merged/intersection types. */
+function dedupeCandidates(candidates: readonly SubjectCandidate[]): SubjectCandidate[] {
+  const seen = new Set<string>()
+  return candidates.filter((candidate) => {
+    if (seen.has(candidate.path)) return false
+    seen.add(candidate.path)
+    return true
+  })
+}
+
+/** Return the workspace package root owning one package source file. */
+function packageRootFor(relativePath: string): string {
+  const match = /^(packages\/[^/]+\/[^/]+)\/src\//.exec(relativePath)
+  if (!match?.[1]) throw new Error(`gen-scoped-events: cannot derive package root from ${relativePath}`)
+  return match[1]
+}
+
+/** Quote a generated property key as a single-quoted TypeScript string. */
+function quote(value: string): string {
+  return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`
+}
+
+/**
+ * Render the generated scoped-event resolver module for one repository root.
+ * @param projectRoot - repository root carrying tsconfig.json.
+ * @returns complete generated TypeScript source.
+ */
+export function renderScopedEvents(projectRoot: string = root): string {
+  return new ScopedEventGenerator(new TypeScriptProject(projectRoot)).render()
+}
+
+/** Generate or freshness-check the fixed invariants source file. */
+function main(): void {
+  const content = renderScopedEvents()
+  const output = resolve(root, OUT)
+  if (process.argv.includes('--check')) {
+    const committed = existsSync(output) ? readFileSync(output, 'utf8') : null
+    if (committed === content) {
+      console.log(`gen-scoped-events: ${OUT} is up to date.`)
+      return
+    }
+    console.error(`gen-scoped-events: ${OUT} is stale. Run \`pnpm run gen-scoped-events\` and commit it.`)
+    process.exit(1)
+  }
+  writeFileSync(output, content)
+  console.log(`gen-scoped-events: wrote ${OUT}.`)
+}
+
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
+  main()
+}
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index d1f5b2944e..7f23a666ae 100644
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -276,7 +276,7 @@ function docSyncLeafGates(): Gate[] {
     pnpmScript('config-catalog', 'verify-config-catalog', { label: 'config catalog' }),
     pnpmScript('persistence-catalog', 'verify-persistence-catalog', { label: 'persistence catalog' }),
     pnpmScript('doc-graphs', 'verify-doc-graphs', { label: 'doc graphs' }),
-    pnpmScript('scoped-dispatch', 'verify-scoped-dispatch', { label: 'scoped dispatch' }),
+    pnpmScript('scoped-events', 'verify-scoped-events', { label: 'scoped events' }),
     pnpmScript('markdown-wrap', 'verify-md-wrap', { label: 'markdown wrap' }),
     pnpmScript('markdown-links', 'verify-md-links', { label: 'markdown links' }),
     pnpmScript('doc-refs', 'verify-doc-refs', { label: 'doc refs' }),
diff --git a/scripts/ts-project.ts b/scripts/ts-project.ts
new file mode 100644
index 0000000000..f82b4286c1
--- /dev/null
+++ b/scripts/ts-project.ts
@@ -0,0 +1,113 @@
+/**
+ * Shared TypeScript Program construction for repository gates that need real
+ * cross-file symbols and types instead of isolated syntax trees.
+ */
+
+import { relative, resolve } from 'node:path'
+import ts from 'typescript'
+
+interface ProjectGraph {
+  rootNames: string[]
+  options: ts.CompilerOptions
+}
+
+const configHost: ts.ParseConfigFileHost = {
+  useCaseSensitiveFileNames: ts.sys.useCaseSensitiveFileNames,
+  readDirectory: ts.sys.readDirectory,
+  fileExists: ts.sys.fileExists,
+  readFile: ts.sys.readFile,
+  getCurrentDirectory: ts.sys.getCurrentDirectory,
+  onUnRecoverableConfigFileDiagnostic(diagnostic) {
+    throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'))
+  },
+}
+
+/** Parse a root tsconfig and flatten all referenced projects into one semantic graph. */
+function loadProjectGraph(projectRoot: string): ProjectGraph {
+  const rootConfigPath = resolve(projectRoot, 'tsconfig.json')
+  const rootConfig = parseConfig(rootConfigPath)
+  const rootNames = new Set<string>()
+  const visited = new Set<string>()
+
+  const collect = (configPath: string, parsed: ts.ParsedCommandLine): void => {
+    if (visited.has(configPath)) return
+    visited.add(configPath)
+    for (const fileName of parsed.fileNames) rootNames.add(fileName)
+    for (const reference of parsed.projectReferences ?? []) {
+      const referencePath = ts.resolveProjectReferencePath(reference)
+      collect(referencePath, parseConfig(referencePath))
+    }
+  }
+  collect(rootConfigPath, rootConfig)
+
+  return {
+    rootNames: [...rootNames],
+    options: rootConfig.options,
+  }
+}
+
+/** Parse one config file and fail loud on any config diagnostic. */
+function parseConfig(configPath: string): ts.ParsedCommandLine {
+  const parsed = ts.getParsedCommandLineOfConfigFile(configPath, {}, configHost)
+  if (!parsed) throw new Error(`cannot parse TypeScript config ${configPath}`)
+  if (parsed.errors.length > 0) {
+    throw new Error(parsed.errors.map(error => ts.flattenDiagnosticMessageText(error.messageText, '\n')).join('\n'))
+  }
+  return parsed
+}
+
+/** Disable emit-only options after loading the root solution config. */
+function semanticCompilerOptions(options: ts.CompilerOptions): ts.CompilerOptions {
+  return {
+    ...options,
+    noEmit: true,
+    composite: false,
+    declaration: false,
+    declarationMap: false,
+    sourceMap: false,
+    incremental: false,
+  }
+}
+
+/** A repository-scoped TypeScript Program and its shared TypeChecker. */
+export class TypeScriptProject {
+  /** The bound cross-file TypeScript program. */
+  readonly program: ts.Program
+  /** The checker shared by every semantic query in this project. */
+  readonly checker: ts.TypeChecker
+
+  constructor(private readonly projectRoot: string) {
+    const graph = loadProjectGraph(projectRoot)
+    this.program = ts.createProgram(graph.rootNames, semanticCompilerOptions(graph.options))
+    this.checker = this.program.getTypeChecker()
+  }
+
+  /**
+   * Return every source file loaded into the flattened root project graph.
+   * @returns program source files, including libraries and external dependencies.
+   */
+  sourceFiles(): readonly ts.SourceFile[] {
+    return this.program.getSourceFiles()
+  }
+
+  /**
+   * Render a loaded source file relative to the project root.
+   * @param sourceFile - a source file from this project.
+   * @returns a slash-separated repository-relative path.
+   */
+  relativePath(sourceFile: ts.SourceFile): string {
+    return relative(this.projectRoot, sourceFile.fileName).replaceAll('\\', '/')
+  }
+
+  /**
+   * Return one program source file by repository-relative path.
+   * @param relativePath - path relative to the project root.
+   * @returns the source file bound into this project.
+   * @throws if a requested root or imported source was not loaded.
+   */
+  sourceFile(relativePath: string): ts.SourceFile {
+    const sourceFile = this.program.getSourceFile(resolve(this.projectRoot, relativePath))
+    if (!sourceFile) throw new Error(`TypeScript project did not load ${relativePath}`)
+    return sourceFile
+  }
+}
diff --git a/scripts/verify-scoped-dispatch.ts b/scripts/verify-scoped-dispatch.ts
deleted file mode 100644
index 64e2333340..0000000000
--- a/scripts/verify-scoped-dispatch.ts
+++ /dev/null
@@ -1,69 +0,0 @@
-/**
- * Scoped-dispatch drift gate: the set of scope-filtered events is declared in TWO places that
- * must never diverge — the dev-invariants runtime table (the `scopedSubject` map in
- * `packages/support/invariants/src/index.ts`, which enforces carriers at dispatch time) and
- * the event declarations' JSDoc (the "Scope-filtered dispatch" sentence rendered into the
- * events catalog, which tells plugin authors what a scoped listener will and won't hear).
- * Registry-subject notifications are intentionally unfiltered and belong in neither set.
- */
-
-import { globSync, readFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-
-const root = resolve(import.meta.dirname, '..')
-
-/** The marker sentence every scope-filtered event's JSDoc carries. */
-const MARKER = 'Scope-filtered dispatch'
-
-/** Events that are deliberately UNFILTERED registry-subject notifications. */
-const REGISTRY_SUBJECT = new Set(['tools/change', 'system-prompt/change', 'subagent/provider-added', 'subagent/provider-removed'])
-
-function invariantTable(): Set<string> {
-  const source = readFileSync(resolve(root, 'packages/support/invariants/src/index.ts'), 'utf8')
-  const start = source.indexOf('const scopedSubject')
-  if (start < 0) throw new Error('verify-scoped-dispatch: cannot find the scopedSubject table in dsh-invariants')
-  const block = source.slice(start, source.indexOf('}', start))
-  return new Set([...block.matchAll(/'([a-z-]+\/[a-z-]+)':/g)].flatMap(match => match[1] === undefined ? [] : [match[1]]))
-}
-
-function documentedSet(): Set<string> {
-  const documented = new Set<string>()
-  for (const rel of globSync('packages/*/*/src/**/*.ts', { cwd: root })) {
-    const source = readFileSync(resolve(root, rel), 'utf8')
-    if (!source.includes(MARKER)) continue
-    // Each event declaration: a JSDoc block followed by the quoted event name.
-    // Tolerate `//` comment lines between the JSDoc and the declaration
-    // (e.g. an inline TODO under the doc block).
-    for (const match of source.matchAll(/\/\*\*([\s\S]*?)\*\/\s*\n(?:\s*\/\/[^\n]*\n)*\s*'([a-z-]+\/[a-z-]+)'\(/g)) {
-      const [, doc, event] = match
-      if (doc === undefined || event === undefined) continue
-      if (doc.includes(MARKER)) documented.add(event)
-    }
-  }
-  return documented
-}
-
-const table = invariantTable()
-const documented = documentedSet()
-
-const problems: string[] = []
-for (const event of table) {
-  if (!documented.has(event)) {
-    problems.push(`"${event}" is enforced by the dev-invariants carrier table but its declaration JSDoc carries no "${MARKER}" sentence — document the filtering plugin authors will observe.`)
-  }
-  if (REGISTRY_SUBJECT.has(event)) {
-    problems.push(`"${event}" is a registry-subject notification (deliberately unfiltered) but appears in the dev-invariants carrier table.`)
-  }
-}
-for (const event of documented) {
-  if (!table.has(event)) {
-    problems.push(`"${event}" documents scope-filtered dispatch but is missing from the dev-invariants carrier table (packages/support/invariants) — a bare dispatch of it would silently revert to global delivery.`)
-  }
-}
-
-if (problems.length > 0) {
-  console.error(`verify-scoped-dispatch: ${problems.length} drift(s) between the invariant table and the documented scoped-event set:`)
-  for (const problem of problems) console.error(`  - ${problem}`)
-  process.exit(1)
-}
-console.log(`verify-scoped-dispatch: ${table.size} scope-filtered event(s) consistent between the invariant table and the declaration docs.`)