refactor(cordis): generate catalogs from Typert models

docs/capability-seams.md

@@ -29,6 +29,9 @@ flowchart LR
   pkg_invariants["invariants"]
   svc_invariants["ctx.invariants<br/>Package-owned invariant registry"]
   pkg_scope["scope"]
+  pkg_typert_registry["typert-registry"]
+  svc_typert["ctx.typert<br/>Runtime type registry"]
+  pkg_typert_loader["typert-loader"]
   svc_sessionPersistence["ctx.sessionPersistence<br/>Durable session persistence seam"]
   pkg_session_persistence_jsonl["session-persistence-jsonl"]
   pkg_session_persistence_sqlite["session-persistence-sqlite"]
@@ -224,6 +227,7 @@ flowchart LR
   pkg_tools --> svc_tools
   pkg_tui --> svc_tui
   pkg_tui --> svc_userInteraction
+  pkg_typert_registry --> svc_typert
   pkg_user_interaction --> svc_userInteraction
   pkg_web --> svc_web
   pkg_web_fetch_local --> svc_web
@@ -318,6 +322,7 @@ flowchart LR
   svc_tools --> pkg_tool_subagent
   svc_tools --> pkg_tool_todo
   svc_tools --> pkg_tool_web
+  svc_typert --> pkg_typert_loader
   svc_userInteraction --> pkg_tool_ask_user
   svc_userInteraction --> pkg_tui
   svc_web --> pkg_tool_web
@@ -334,6 +339,7 @@ flowchart LR
 | `ctx.toolResultPrune` | `core` | [`compact-tool-result-prune`](../packages/compact/compact-tool-result-prune) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Rewrites oversized current tool results through replayable single-node surface replacements before summary compaction. |
 | `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`cli-demo`](../packages/examples/cli-demo), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
 | `ctx.invariants` | `core` | [`invariants`](../packages/support/invariants) | - | [`session`](../packages/core/session), [`agent`](../packages/core/agent), [`scope`](../packages/core/scope), [`agent-loop`](../packages/core/agent-loop) | - | Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures. |
+| `ctx.typert` | `core` | [`typert-registry`](../packages/typert/registry) | - | [`typert-loader`](../packages/typert/loader) | - | Plugins register live zod contributions directly or through dsh-typert-loader; runtime consumers query schemas and reflection metadata at their own edges. |
 | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`session-query`](../packages/session-query/session-query), [`session-query-sqlite`](../packages/session-query/session-query-sqlite) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
 | `ctx.telemetry` | `seam` | [`session-telemetry`](../packages/telemetry/session-telemetry) | [`session-telemetry-otel`](../packages/telemetry/session-telemetry-otel) | - | - | The seam captures, redacts, and hands session records to one backend; nothing else consumes the service — its output leaves the process. |
 | `ctx.storage` | `seam` | [`storage`](../packages/storage/storage) | [`storage-json`](../packages/storage/storage-json), [`storage-sqlite`](../packages/storage/storage-sqlite) | [`storage-domain`](../packages/storage/storage-domain) | - | Backends register side by side under names; data forms (domain first) mount on the hub and translate typed operations into opaque KV-unit primitives. |

docs/config-catalog.md

@@ -2022,6 +2022,20 @@ Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) ·
 
 Source: [`packages/examples/tui-demo/src/index.ts:39`](../packages/examples/tui-demo/src/index.ts)
 
+## `@deepseek-ai/dsh-typert-loader`
+
+Requires: `typert` · `loader`
+
+```ts config-catalog
+/** Additional package artifacts whose owning plugins are nested behind another Loader entry. */
+export interface Config {
+  /** Exact npm package names that must resolve and export `./typert`. */
+  packages?: string[]
+}
+```
+
+Source: [`packages/typert/loader/src/index.ts:47`](../packages/typert/loader/src/index.ts)
+
 ## `@deepseek-ai/dsh-user-approval`
 
 ```ts config-catalog
@@ -2264,6 +2278,7 @@ These load from a `cordis.yml` entry with no `config:` block; they declare no co
 - `@deepseek-ai/dsh-timeout-policy` — requires `tools` ([`packages/timeout/timeout-policy/src/index.ts`](../packages/timeout/timeout-policy/src/index.ts))
 - `@deepseek-ai/dsh-tool-ask-user` — requires `tools` · `userInteraction` ([`packages/ui/tool-ask-user/src/index.ts`](../packages/ui/tool-ask-user/src/index.ts))
 - `@deepseek-ai/dsh-tool-todo` — requires `tools` ([`packages/todo/tool-todo/src/index.ts`](../packages/todo/tool-todo/src/index.ts))
+- `@deepseek-ai/dsh-typert-registry` ([`packages/typert/registry/src/index.ts`](../packages/typert/registry/src/index.ts))
 - `@deepseek-ai/dsh-user-interaction` ([`packages/ui/user-interaction/src/index.ts`](../packages/ui/user-interaction/src/index.ts))
 - `@deepseek-ai/dsh-workspace` — requires `storageDomain` · `sessionPersistence` ([`packages/workspace/workspace/src/index.ts`](../packages/workspace/workspace/src/index.ts))
 
@@ -2315,3 +2330,4 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-subagent-inprocess` ([`packages/subagent/subagent-inprocess/src/index.ts`](../packages/subagent/subagent-inprocess/src/index.ts))
 - `@deepseek-ai/dsh-telemetry` ([`packages/sdk/telemetry/src/index.ts`](../packages/sdk/telemetry/src/index.ts))
 - `@deepseek-ai/dsh-timeout` ([`packages/util/timeout/src/index.ts`](../packages/util/timeout/src/index.ts))
+- `@deepseek-ai/dsh-typert-generator` ([`packages/typert/generator/src/index.ts`](../packages/typert/generator/src/index.ts))

docs/cordis-catalog/events.md

@@ -9,7 +9,7 @@ This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verifie
 
 The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns, grouped by scope. The **inherited tier** at the end is the cordis-core + loader/hmr/timer event surface a plugin also sees — pinned vendor source, summarized tersely. The event-dispatch methods themselves are generated in the [Cordis core Events API](core/events.md).
 
-Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`), **bail** (synchronous in-order dispatch until one listener returns a bail value; the scoped input-mutation events use it for an applied/not-applied answer).
+Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`).
 
 ## `agent/*`
 
@@ -32,7 +32,7 @@ Effective broad cancellation was requested, before queued/outbox work is cleared
 
 Types: [Agent](../core-data-structures/core.md) · [AgentCancelCause](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:286`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:289`](../../packages/core/agent/src/types.ts)
 
 ### `agent/created` — emit
 
@@ -54,7 +54,7 @@ A fully configured agent and live session were published. Setup is composition-o
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:218`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:221`](../../packages/core/agent/src/types.ts)
 
 ### `agent/disposed` — emit
 
@@ -74,7 +74,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence and sco
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:227`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:230`](../../packages/core/agent/src/types.ts)
 
 ### `agent/error` — emit
 
@@ -96,7 +96,7 @@ A step or turn errored. The machine reports a failure here (plus the logger) eve
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:400`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:403`](../../packages/core/agent/src/types.ts)
 
 ### `agent/inbox/dequeue` — emit
 
@@ -119,7 +119,7 @@ The driver claimed one item out of the inbox: a queued item at a turn boundary,
 
 Types: [Agent](../core-data-structures/core.md) · [InboxPlacement](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:259`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:262`](../../packages/core/agent/src/types.ts)
 
 ### `agent/inbox/discard` — emit
 
@@ -142,7 +142,7 @@ Pending inbox items were dropped without delivering them, so every enqueue occur
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:276`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:279`](../../packages/core/agent/src/types.ts)
 
 ### `agent/inbox/enqueue` — emit
 
@@ -164,7 +164,7 @@ An item entered the queued or steering inbox. `placement` is the acceptance-time
 
 Types: [Agent](../core-data-structures/core.md) · [InboxPlacement](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:247`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:250`](../../packages/core/agent/src/types.ts)
 
 ### `agent/prompt-submit` — waterfall
 
@@ -187,7 +187,7 @@ Allow, rewrite, or block one claimed prompt before it becomes a user message or
 
 Types: [Agent](../core-data-structures/core.md) · [PromptDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [UserMessage](../core-data-structures/session.md)
 
-Source: [`packages/core/agent/src/types.ts:313`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:316`](../../packages/core/agent/src/types.ts)
 
 ### `agent/request` — waterfall
 
@@ -211,7 +211,7 @@ Replace the frozen call configuration. `await next()` yields the config the mach
 
 Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:339`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:342`](../../packages/core/agent/src/types.ts)
 
 ### `agent/request-error` — waterfall
 
@@ -241,7 +241,7 @@ Handle a model-request failure after its failed step has closed but before the f
 
 Types: [Agent](../core-data-structures/core.md) · [LlmFailure](../core-data-structures/llm-streaming.md) · [RequestError](../core-data-structures/core.md) · [RequestErrorAction](../core-data-structures/core.md) · [ResolvedRetryPolicy](../core-data-structures/llm-streaming.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:358`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:361`](../../packages/core/agent/src/types.ts)
 
 ### `agent/session-start` — emit
 
@@ -263,7 +263,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SessionStartSource](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:299`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:302`](../../packages/core/agent/src/types.ts)
 
 ### `agent/settled` — emit
 
@@ -288,7 +288,7 @@ One drain chain reached its terminal turn: that turn's `turn/end` is already com
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SettleReason](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/types.ts:387`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:390`](../../packages/core/agent/src/types.ts)
 
 ### `agent/status` — emit
 
@@ -308,7 +308,7 @@ Agent status changed (`idle` ⇄ `running`). `send()` does not enter `running` s
 
 Types: [Agent](../core-data-structures/core.md) · [AgentStatus](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:236`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:239`](../../packages/core/agent/src/types.ts)
 
 ### `agent/step` — serial
 
@@ -332,7 +332,7 @@ Awaited serial checkpoint before EVERY request of a turn is built (the first as
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:326`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:329`](../../packages/core/agent/src/types.ts)
 
 ### `agent/turn-stopping` — serial
 
@@ -358,7 +358,7 @@ The turn is about to close: the model owes no response (no live tool calls, no f
 
 Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
-Source: [`packages/core/agent/src/types.ts:373`](../../packages/core/agent/src/types.ts)
+Source: [`packages/core/agent/src/types.ts:376`](../../packages/core/agent/src/types.ts)
 
 ## `agent-loop/*`
 
@@ -661,75 +661,6 @@ A skill provider, runtime contribution, or provider-backed catalog may have chan
 
 Source: [`packages/skill/skill/src/index.ts:157`](../../packages/skill/skill/src/index.ts)
 
-## `slash/*`
-
-### `slash/input-begin-command` — bail
-
-Applies one command claim to the scoped Input. Dispatched with the session's scope carrier; the owning session's input listener returns `true` only after the phase and span CAS checks pass and the machine actually mutated — producers treat anything else as "not applied".
-
-```ts cordis-catalog
-/**
- * Applies one command claim to the scoped Input. Dispatched with the
- * session's scope carrier; the owning session's input listener returns
- * `true` only after the phase and span CAS checks pass and the machine
- * actually mutated — producers treat anything else as "not applied".
- * @param request - Claim and menu-time span CAS.
- * @mode bail
- */
-'slash/input-begin-command'(request: BeginCommandRequest): true | undefined
-```
-
-Source: [`packages/client/ui-slash/src/types.ts:232`](../../packages/client/ui-slash/src/types.ts)
-
-### `slash/input-consume-token` — bail
-
-Consumes one command token after business success (popup settle / menu-pick execute). Same carrier routing and applied-truth contract.
-
-```ts cordis-catalog
-/**
- * Consumes one command token after business success (popup settle /
- * menu-pick execute). Same carrier routing and applied-truth contract.
- * @param request - Exact span or bare-token guard.
- * @mode bail
- */
-'slash/input-consume-token'(request: ConsumeTokenRequest): true | undefined
-```
-
-Source: [`packages/client/ui-slash/src/types.ts:246`](../../packages/client/ui-slash/src/types.ts)
-
-### `slash/input-insert-reference` — bail
-
-Inserts one reference into the scoped Input (same carrier routing and applied-truth contract as begin-command).
-
-```ts cordis-catalog
-/**
- * Inserts one reference into the scoped Input (same carrier routing and
- * applied-truth contract as begin-command).
- * @param request - Reference and menu-time span CAS.
- * @mode bail
- */
-'slash/input-insert-reference'(request: InsertReferenceRequest): true | undefined
-```
-
-Source: [`packages/client/ui-slash/src/types.ts:239`](../../packages/client/ui-slash/src/types.ts)
-
-### `slash/input-insert-text` — bail
-
-Replaces the trigger token span with literal text — the plain-text reference path (decision 21). Same carrier routing and applied-truth contract; the draft gains ordinary characters, no occurrence entry.
-
-```ts cordis-catalog
-/**
- * Replaces the trigger token span with literal text — the plain-text
- * reference path (decision 21). Same carrier routing and applied-truth
- * contract; the draft gains ordinary characters, no occurrence entry.
- * @param request - Replacement text and menu-time span CAS.
- * @mode bail
- */
-'slash/input-insert-text'(request: InsertTextRequest): true | undefined
-```
-
-Source: [`packages/client/ui-slash/src/types.ts:254`](../../packages/client/ui-slash/src/types.ts)
-
 ## `subagent/*`
 
 ### `subagent/end` — emit

docs/cordis-catalog/services.md

@@ -978,7 +978,7 @@ signal(owner: Agent, id: PtySessionId, signal: PtySignal): Promise<PtySignalResu
  * @param reason - diagnostic cleanup reason.
  * @returns true for a newly closed session, false when the same close is already in flight.
  */
-async kill(owner: Agent, id: PtySessionId, reason = 'model request'): Promise<boolean>
+async kill(owner: Agent, id: PtySessionId, reason: string = 'model request'): Promise<boolean>
 
 /**
  * List fresh snapshots for exactly one owner.
@@ -1447,7 +1447,7 @@ Exact-read consumer that prepares immutable cross-session message context.
  * @param signal - optional cancellation boundary for host autocomplete teardown.
  * @returns candidates labeled by latest title or, when absent, session id.
  */
-async listCandidates( agent: Agent, query = '', limit = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>
+async listCandidates( agent: Agent, query: string = '', limit: number = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>
 
 /**
  * Snapshot all references before enqueue and return one aggregated durable context.
@@ -1590,7 +1590,7 @@ fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId):
 
 Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [Session](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md)
 
-Source: [`packages/core/session/src/index.ts:694`](../../packages/core/session/src/index.ts)
+Source: [`packages/core/session/src/index.ts:695`](../../packages/core/session/src/index.ts)
 
 ## `ctx.sessionTitle` — `SessionTitleService`
 
@@ -2198,6 +2198,67 @@ abstract openOverlay(request: TuiOverlayRequest): TuiOverlaySession
 
 Source: [`packages/ui/tui/src/index.ts:247`](../../packages/ui/tui/src/index.ts)
 
+## `ctx.typert` — `TypertRegistry`
+
+Registry of generated schemas and package reflection.
+
+```ts cordis-catalog
+/**
+ * Register one generated contribution atomically for the calling fiber.
+ * Duplicate package-face identities or schema keys reject the whole batch.
+ * @param contribution - generated schemas and package metadata.
+ * @returns the exact effect disposer that removes this contribution.
+ */
+register(contribution: TypertContribution): () => void
+
+/**
+ * Look up one schema by `<package>#<name>`.
+ * @param key - global schema key.
+ * @returns the live schema record, or `undefined` when absent.
+ */
+get(key: string): TypertSchemaRecord | undefined
+
+/**
+ * Resolve one required schema.
+ * @param key - global schema key.
+ * @returns the live schema record.
+ * @throws when the key is malformed, the package face is absent, or the schema is not contributed.
+ */
+resolve(key: string): TypertSchemaRecord
+
+/**
+ * Enumerate live schemas in registration order.
+ * @param filter - optional package and face restriction.
+ * @returns matching schema records.
+ */
+list(filter: TypertSchemaFilter = {}): TypertSchemaRecord[]
+
+/**
+ * Look up generated reflection for one package face.
+ * @param packageName - exact npm package name.
+ * @param face - face to query; defaults to the host runtime.
+ * @returns the live package record, or `undefined` when absent.
+ */
+getPackage(packageName: string, face: TypertFace = 'host'): TypertPackageRecord | undefined
+
+/**
+ * Enumerate generated package reflection in registration order.
+ * @param filter - optional package and face restriction.
+ * @returns matching package records.
+ */
+listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]
+
+/**
+ * Project a live Zod schema to JSON Schema without caching the result.
+ * @param key - global schema key.
+ * @param params - Zod projection parameters.
+ * @returns a fresh JSON Schema document.
+ */
+toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema
+```
+
+Source: [`packages/typert/registry/src/index.ts:67`](../../packages/typert/registry/src/index.ts)
+
 ## `ctx.userInteraction` — `UserInteractionService`
 
 `ctx.userInteraction`: one active UI provider plus an `ask()` surface.

docs/event-producer-consumer.md

@@ -8,21 +8,21 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | Event | Mode | Declared in | Dispatchers | Listeners |
 | --- | --- | --- | --- | --- |
 | `agent-loop/config-start-failed` | `emit` | [`packages/core/agent-loop/src/index.ts:148`](../packages/core/agent-loop/src/index.ts) | [`agent-loop`](../packages/core/agent-loop) (`events.dispatch`) | [`tui`](../packages/ui/tui) |
-| `agent/cancel-requested` | `emit` | [`packages/core/agent/src/types.ts:286`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal-session`](../packages/goal/goal-session) |
-| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:218`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
-| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:227`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
-| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:400`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tui`](../packages/ui/tui) |
-| `agent/inbox/dequeue` | `emit` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`tui`](../packages/ui/tui) |
-| `agent/inbox/discard` | `emit` | [`packages/core/agent/src/types.ts:276`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`tui`](../packages/ui/tui) |
-| `agent/inbox/enqueue` | `emit` | [`packages/core/agent/src/types.ts:247`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`goal-session`](../packages/goal/goal-session) |
-| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:313`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`tui`](../packages/ui/tui) |
-| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:339`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
-| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:358`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
-| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:299`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`workspace-context`](../packages/context/workspace-context) |
-| `agent/settled` | `emit` | [`packages/core/agent/src/types.ts:387`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`compact-basic`](../packages/compact/compact-basic) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:236`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
-| `agent/step` | `serial` | [`packages/core/agent/src/types.ts:326`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`plan-mode`](../packages/plan/plan-mode), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) |
-| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:373`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
+| `agent/cancel-requested` | `emit` | [`packages/core/agent/src/types.ts:289`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal-session`](../packages/goal/goal-session) |
+| `agent/created` | `emit` | [`packages/core/agent/src/types.ts:221`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
+| `agent/disposed` | `emit` | [`packages/core/agent/src/types.ts:230`](../packages/core/agent/src/types.ts) | [`agent`](../packages/core/agent) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
+| `agent/error` | `emit` | [`packages/core/agent/src/types.ts:403`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`session-telemetry`](../packages/telemetry/session-telemetry), [`tui`](../packages/ui/tui) |
+| `agent/inbox/dequeue` | `emit` | [`packages/core/agent/src/types.ts:262`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`tui`](../packages/ui/tui) |
+| `agent/inbox/discard` | `emit` | [`packages/core/agent/src/types.ts:279`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`tui`](../packages/ui/tui) |
+| `agent/inbox/enqueue` | `emit` | [`packages/core/agent/src/types.ts:250`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`goal-session`](../packages/goal/goal-session) |
+| `agent/prompt-submit` | `waterfall` | [`packages/core/agent/src/types.ts:316`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`repeat-tool-guard`](../packages/guard/repeat-tool-guard), [`tui`](../packages/ui/tui) |
+| `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:342`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
+| `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:361`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
+| `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:302`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`workspace-context`](../packages/context/workspace-context) |
+| `agent/settled` | `emit` | [`packages/core/agent/src/types.ts:390`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`compact-basic`](../packages/compact/compact-basic) |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:239`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`agent`](../packages/core/agent), `apiproxy`, [`goal-session`](../packages/goal/goal-session), [`tui`](../packages/ui/tui) |
+| `agent/step` | `serial` | [`packages/core/agent/src/types.ts:329`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`compact-basic`](../packages/compact/compact-basic), [`plan-mode`](../packages/plan/plan-mode), [`session-checkpoint-policy`](../packages/session-persistence/session-checkpoint-policy), [`time-context`](../packages/context/time-context), [`tmux-context`](../packages/context/tmux-context), [`tool-skill`](../packages/skill/tool-skill), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) |
+| `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:376`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/ui/user-approval/src/index.ts:30`](../packages/ui/user-approval/src/index.ts) | [`user-approval`](../packages/ui/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
 | `commands/change` | `emit` | [`packages/ui/commands/src/index.ts:154`](../packages/ui/commands/src/index.ts) | [`commands`](../packages/ui/commands) (`events.dispatch`) | `apiproxy`, [`tui`](../packages/ui/tui) |
 | `domain/changed` | `emit` | [`packages/storage/storage-domain/src/events.ts:46`](../packages/storage/storage-domain/src/events.ts) | [`storage-domain`](../packages/storage/storage-domain) (`emit`) | `apiproxy`, [`storage-domain`](../packages/storage/storage-domain), [`workspace`](../packages/workspace/workspace) |
@@ -36,10 +36,6 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `session/event` | `emit` | [`packages/core/session/src/index.ts:93`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/acp/acp), `apiproxy`, [`cli-demo`](../packages/examples/cli-demo), [`compact`](../packages/compact/compact), [`compact-basic`](../packages/compact/compact-basic), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`jsonrpc`](../packages/ui/jsonrpc), [`session`](../packages/core/session), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-projection`](../packages/session-projection/session-projection), [`session-projection-cache`](../packages/session-projection/session-projection-cache), [`session-telemetry`](../packages/telemetry/session-telemetry), [`session-title`](../packages/session-title/session-title), [`token-meter`](../packages/llm/token-meter), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-approval`](../packages/ui/user-approval), [`workspace-context`](../packages/context/workspace-context) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:103`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence), [`session-telemetry`](../packages/telemetry/session-telemetry) |
 | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:157`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | [`tui`](../packages/ui/tui) |
-| `slash/input-begin-command` | `bail` | [`packages/client/ui-slash/src/types.ts:232`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` |
-| `slash/input-consume-token` | `bail` | [`packages/client/ui-slash/src/types.ts:246`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` |
-| `slash/input-insert-reference` | `bail` | [`packages/client/ui-slash/src/types.ts:239`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` |
-| `slash/input-insert-text` | `bail` | [`packages/client/ui-slash/src/types.ts:254`](../packages/client/ui-slash/src/types.ts) | - | `ui-conversation` |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:140`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc), [`subagent`](../packages/subagent/subagent) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:114`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:120`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
@@ -67,9 +63,13 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `commands/changed` | `runtime` (`emit`) | `ui-command` |
 | `connection/reset` | `runtime` (`emit`) | `ui-command` |
 | `internal/dispatch` | - | [`commands`](../packages/ui/commands), [`compact`](../packages/compact/compact), [`fs`](../packages/fs/fs), [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hook-protocol`](../packages/hooks/hook-protocol), [`llm-retry`](../packages/llm/llm-retry), [`permission`](../packages/ui/permission), [`plan-mode`](../packages/plan/plan-mode), [`pty-local`](../packages/pty/pty-local), `runtime`, [`sandbox-policy`](../packages/sandbox/sandbox-policy), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-title`](../packages/session-title/session-title), [`subagent`](../packages/subagent/subagent), [`time-context`](../packages/context/time-context), [`tool-todo`](../packages/todo/tool-todo), [`tools`](../packages/core/tools), [`user-approval`](../packages/ui/user-approval), [`workflow`](../packages/workflow/workflow) |
-| `internal/plugin` | - | `hmr`, `modules`, `webserver` |
+| `internal/plugin` | - | `hmr`, `loader`, `modules`, `webserver` |
 | `internal/status` | - | [`agent`](../packages/core/agent) |
 | `locale/change` | `locale` (`emit`) | `locale`, `ui-models`, `ui-settings-general` |
+| `slash/input-begin-command` | - | `ui-conversation` |
+| `slash/input-consume-token` | - | `ui-conversation` |
+| `slash/input-insert-reference` | - | `ui-conversation` |
+| `slash/input-insert-text` | - | `ui-conversation` |
 | `slots/changed` | `runtime` (`emit`) | - |
 | `theme/change` | `ui-theme` (`emit`) | `ui-layout`, `ui-theme` |
 

docs/module-graph.md

@@ -241,6 +241,11 @@ flowchart TD
     pkg_session_telemetry["session-telemetry"]
     pkg_session_telemetry_otel["session-telemetry-otel"]
   end
+  subgraph group_typert["packages/typert"]
+    pkg_typert_generator["typert-generator"]
+    pkg_typert_loader["typert-loader"]
+    pkg_typert_registry["typert-registry"]
+  end
   subgraph group_workflow["packages/workflow"]
     pkg_tool_ralph["tool-ralph"]
     pkg_tool_workflow["tool-workflow"]
@@ -274,6 +279,8 @@ flowchart TD
   pkg_host_webserver --> pkg_invariants
   pkg_storage --> pkg_invariants
   pkg_subprocess --> pkg_invariants
+  pkg_typert_generator --> pkg_invariants
+  pkg_typert_registry --> pkg_invariants
   pkg_llm --> pkg_brand
   pkg_llm --> pkg_invariants
   pkg_llm --> pkg_timeout
@@ -321,6 +328,8 @@ flowchart TD
   pkg_storage_sqlite --> pkg_storage
   pkg_subprocess_local --> pkg_invariants
   pkg_subprocess_local --> pkg_subprocess
+  pkg_typert_loader --> pkg_invariants
+  pkg_typert_loader --> pkg_typert_registry
   pkg_llm_deepseek --> pkg_invariants
   pkg_llm_deepseek --> pkg_llm
   pkg_llm_deepseek --> pkg_timeout
@@ -1003,6 +1012,8 @@ flowchart TD
 | [`host-webserver`](../packages/host/webserver) | `host` | [`invariants`](../packages/support/invariants) |
 | [`storage`](../packages/storage/storage) | `storage` | [`invariants`](../packages/support/invariants) |
 | [`subprocess`](../packages/subprocess/subprocess) | `subprocess` | [`invariants`](../packages/support/invariants) |
+| [`typert-generator`](../packages/typert/generator) | `typert` | [`invariants`](../packages/support/invariants) |
+| [`typert-registry`](../packages/typert/registry) | `typert` | [`invariants`](../packages/support/invariants) |
 | [`llm`](../packages/llm/llm) | `llm` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`timeout`](../packages/util/timeout) |
 | [`client-connection`](../packages/client/connection) | `client` | [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
 | [`client-hmr`](../packages/client/hmr) | `client` | [`client-modules`](../packages/client/modules), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |
@@ -1019,6 +1030,7 @@ flowchart TD
 | [`storage-json`](../packages/storage/storage-json) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
 | [`storage-sqlite`](../packages/storage/storage-sqlite) | `storage` | [`invariants`](../packages/support/invariants), [`storage`](../packages/storage/storage) |
 | [`subprocess-local`](../packages/subprocess/subprocess-local) | `subprocess` | [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess) |
+| [`typert-loader`](../packages/typert/loader) | `typert` | [`invariants`](../packages/support/invariants), [`typert-registry`](../packages/typert/registry) |
 | [`llm-deepseek`](../packages/llm/llm-deepseek) | `llm` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout) |
 | [`llm-pi-ai`](../packages/llm/llm-pi-ai) | `llm` | [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`timeout`](../packages/util/timeout) |
 | [`session`](../packages/core/session) | `core` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope) |

docs/typert-catalog-integration-design.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write docs/typert-catalog-integration-design.md
+typert-catalog-integration-design.md: c7d601730655f61f3b875ad5ad6997d3c888bfea
+typert-catalog-integration-design.zh.md: abaddfe1f740d4bd7cff5b2db8fd91e34626aab8

docs/typert-catalog-integration-design.md

@@ -0,0 +1,133 @@
+# Typert Catalog Integration Design
+
+English | [中文](typert-catalog-integration-design.zh.md)
+
+## Current State and Problem
+
+Typert already provides separate host/client `FaceModel` instances, a `TypeGraph` with explicit cross-face references, and analysis support for services, events, `@typert object`, generics, inheritance, and External types. The TypeScript compiler API should only translate source code into this standard model; downstream consumers should not traverse the TypeScript AST again.
+
+The repository currently has two catalog pipelines that analyze TypeScript source directly: the static API catalog consumed by `tool-cordis`, and the generation and freshness gate for `docs/cordis-catalog/events.md` and `docs/cordis-catalog/services.md`. They analyze the same services, events, and related types, but maintain separate collection and rendering logic, so they cannot prove that the Typert model is sufficient to represent the existing domain semantics.
+
+The first phase makes both pipelines consume the Typert model while keeping the three committed artifacts character-for-character identical to their pre-migration versions:
+
+- `docs/cordis-catalog/events.md`
+- `docs/cordis-catalog/services.md`
+- `packages/cordis/tool-cordis/src/api-catalog.ts`
+
+This phase does not require product plugins to publish Typert subpaths, example applications to load Typert, or changes to the runtime dependencies of `tool-cordis`.
+
+## Options
+
+### Drive `tool-cordis` from the Runtime Registry
+
+Each plugin publishes and loads Typert artifacts, then `tool-cordis` reads the current runtime model from `ctx.typert`. This path reflects the set of plugins actually loaded, but it requires every product package represented in the catalog to add package exports, generated artifacts, registry contributions, and application assembly. That integration surface is much larger than the analysis capability being validated now.
+
+### Publish Typert Artifacts Repository-Wide, Then Aggregate Them Statically
+
+All product packages generate host/client JS and DTS during the normal build/typecheck process, then the catalog generator aggregates those artifacts. This path establishes the complete publication protocol up front, but it also changes many package manifests and the build topology at once, coupling catalog migration to repository-wide Typert publication.
+
+### Analyze at Build Time, Then Project the Catalog
+
+`WorkspaceAnalyzer` builds a `WorkspaceModel` and `TypeGraph` from the host TypeScript project. The repository-specific `CordisCatalogProjector` consumes only that model and generates the three texts. `tool-cordis` continues to import the committed static `api-catalog.ts`, so the runtime does not need the Typert service.
+
+This phase uses build-time projection. It directly verifies that the standard Typert model can replace the existing AST collector while leaving runtime publication and automatic loading to separate follow-up decisions.
+
+## Phase-One Architecture
+
+```text
+tsconfig.host.json
+        │
+        ▼
+WorkspaceAnalyzer ── TypeScript compiler API 的唯一边界
+        │
+        ▼
+WorkspaceModel + TypeGraph
+        │
+        ▼
+CordisCatalogProjector ── 不依赖 TypeScript AST
+        ├── docs/cordis-catalog/events.md
+        ├── docs/cordis-catalog/services.md
+        └── packages/cordis/tool-cordis/src/api-catalog.ts
+```
+
+The objects have the following responsibilities:
+
+- `WorkspaceAnalyzer` analyzes packages, exports, services, events, type declarations, and reference relationships, and produces a compiler-independent model.
+- `WorkspaceModel` and `TypeGraph` are the standard data structures shared by all generation and scanning analyses. They preserve developer-authored generics, inheritance, and type trees without retaining the TypeScript AST.
+- The root entry point of `@deepseek-ai/dsh-typert-generator` exports `CordisCatalogProjector`, which performs model-driven selection, sorting, summary extraction, source location handling, JSDoc completeness checks, type-link closure, and rendering in three text formats. Its implementation remains in a dedicated Cordis catalog file, but it does not create another package subpath or embed a list of repository type names.
+- `scripts/gen-cordis-catalog.ts` provides `LINK_MAP`, `FOUNDATION_TYPE_NAMES`, `TYPE_LINK_EXEMPTIONS`, and the inherited Cordis list, injects them explicitly into the projector through `CordisCatalogPolicy`, and owns the write/check CLI behavior. The vendor Cordis core pages continue to be generated by a separate pinned-source projector.
+- `tool-cordis` imports only the static `api-catalog.ts` and does not depend on `typert-registry` or `typert-loader`.
+
+`CordisCatalogProjector` is a repository-specific downstream consumer and is not part of Typert's general-purpose model. When adding another category, first extend the standard model, then add the corresponding projector. The Typert analyzer must not absorb Cordis documentation formats or `tool-cordis` presentation logic.
+
+## Model Additions
+
+In addition to type structure, the catalog's character-for-character projection needs the declaration forms written by developers and exact source locations. The standard model therefore retains event/service locations, body-free text for events and members, parameter initializers, and the export status and canonical text of type declarations. `SourceDeclarationModel` also indexes top-level exported declarations for ambiguity checks and static type closure, without promoting them to domain graph roots.
+
+```ts
+interface SourceLocation {
+  readonly file: string
+  readonly line: number
+  readonly column: number
+}
+
+interface EventModel {
+  readonly location: SourceLocation
+  readonly text: string
+}
+```
+
+Repository-wide analysis supports building bounded `ts.Program` instances in package batches, then merging them through source-location-stable graph ids into a face model equivalent to monolithic analysis. This capability changes only the memory boundary of the compiler program; it does not change package, declaration, or type graph semantics.
+
+All information required by the projector must come from `WorkspaceModel` or `TypeGraph`. If a fact required for character-for-character compatibility cannot be expressed by the model, extend the standard model; do not reintroduce `ts.Node`, `ts.Symbol`, or `ts.TypeChecker` in the projector or script.
+
+## Character-for-Character Migration Oracle
+
+Before migration, retain the three texts produced by the old generator against the same source state. After migration, run the new analyzer and projector and require the three outputs to be byte-for-byte identical. Newlines, spaces, ordering, JSDoc, source pointers, and generated headers are all part of the comparison.
+
+`pnpm run verify-cordis-catalog` retains its `--check` mode, which reads the three committed artifacts and compares them directly with the newly computed results. A missing file or any differing character makes the artifact stale, and the error points to the single `pnpm run gen-cordis-catalog` repair command.
+
+Tests pin both of the following layers:
+
+- Typert fixture snapshots pin the `WorkspaceModel`, `TypeGraph`, JS, DTS, and Zod outputs, proving the behavior of the standard model and general-purpose emitters.
+- Cordis catalog tests or snapshots pin the projector's three complete texts, proving that the repository-specific product projection does not bypass the standard model and providing directly reviewable textual evidence.
+
+The three committed artifacts are the migration oracle between the old and new implementations and the continuing freshness oracle after migration. The old `gen-cordis-api` AST collector is removed. The scripts and commands with that name remain only as compatibility entry points for the unified projector because the generated file header itself contains the command; retaining the entry point preserves the character-for-character oracle without creating a second source of truth.
+
+## Exact Change List
+
+### Typert Generator
+
+- Add the locations, authored declaration text, parameter initializers, export status, and top-level source declaration index needed for character-for-character projection, with coverage in analyzer and model snapshots.
+- Support bounded package-batch analysis and prove that direct and batched models are equivalent.
+- Confirm that the catalog's required service declarations, public instance members, JSDoc, generics, inheritance, and referenced types are all available from the model.
+- Keep the TypeScript compiler API encapsulated within the analyzer; the public model and projector inputs do not expose compiler objects.
+
+### Cordis Catalog Projector
+
+- Select the complete set of Cordis services and events from the host `WorkspaceModel`.
+- Preserve the old generator's JSDoc rules: events must have `@mode` and payload `@param` tags; service methods must have a matching `@param` for every parameter; non-void returns must have `@returns`.
+- Compute the type links used by signatures and the transitive public type closure required by `tool-cordis` from the type graph.
+- Receive caller-maintained type classifications and the inherited surface through an explicit `CordisCatalogPolicy`; do not maintain the repository documentation taxonomy inside the generator package.
+- Preserve the existing output rules for source pointers, signatures, summaries, ordering, declaration truncation, and the inherited context catalog.
+- Project once and render the events Markdown, services Markdown, and TypeScript API catalog, preventing drift between documentation and tool data.
+
+### Commands and Consumers
+
+- `scripts/gen-cordis-catalog.ts` maintains repository policy data, assembles the analyzer and projector, and writes/checks all three artifacts together. Parsing, validation, and rendering logic lives in the generator's dedicated Cordis source file and is exported uniformly from the package root entry point.
+- Narrow `scripts/gen-cordis-api.ts` to a logic-free compatibility entry point for the unified CLI; the root `gen-cordis-api` and `verify-cordis-api` aliases point to that entry point.
+- Restore the static catalog default in `tool-cordis` and remove its dependencies on `ctx.typert`, `typert-registry`, and runtime package-model completeness.
+- `gen-doc-graphs` obtains the projector's model-level result once and reuses its services and events; it must not continue to import the AST collector or analyze the repository again.
+
+### Narrow the Scope of Phase-One Changes
+
+- Remove the newly added `./typert` and `./client/typert` exports and `lib/typert.*` files from product plugin package.json files.
+- Remove `typert-registry` and `typert-loader` assembly from examples.
+- Normal build/typecheck does not run repository-wide `gen-typert` or require product-package Typert artifacts to exist before it runs on a clean tree.
+- Retain `packages/typert/generator`, `packages/typert/registry`, and `packages/typert/loader`, along with their independent fixture, emitter, and runtime registration tests.
+
+## Future Extensions
+
+The runtime registry remains the receiving and query layer for generated JS/Zod, and the loader remains the automatic loading mechanism; neither supplies data to the first-phase static catalog. When product packages need runtime reflection, they can opt in by publishing `package/typert` and `package/client/typert`, which the loader then registers with `ctx.typert`.
+
+Future integration does not change the phase-one layering: only the analyzer handles TypeScript, the standard model serves both static generation and scan analysis, and the emitter produces runtime artifacts from that same model. Whether to extend publication to more packages, enable the loader by default, or extend the runtime registry's query capabilities are separate review decisions and remain decoupled from the Cordis catalog migration.

docs/typert-catalog-integration-design.zh.md

@@ -0,0 +1,133 @@
+# Typert catalog 接入设计
+
+[English](typert-catalog-integration-design.md) | 中文
+
+## 现状与问题
+
+Typert 已经具备独立的 host/client `FaceModel`、可显式跨 face 引用的 `TypeGraph`，以及 service、event、`@typert object`、泛型、继承和 External 类型的分析能力。TypeScript compiler API 只应负责把源码转换成这套标准模型；后续消费者不应再次遍历 TypeScript AST。
+
+仓库目前有两条直接分析 TypeScript 源码的 catalog 链路：`tool-cordis` 使用的静态 API catalog，以及 `docs/cordis-catalog/events.md`、`docs/cordis-catalog/services.md` 的生成与 freshness gate。它们分析的是同一批 service、event 和相关类型，却分别维护收集与渲染逻辑，不能证明 Typert 模型足以承载现有业务语义。
+
+第一阶段的目标是让这两条链路共同消费 Typert 模型，并保持三份已提交产物与迁移前字符级一致：
+
+- `docs/cordis-catalog/events.md`
+- `docs/cordis-catalog/services.md`
+- `packages/cordis/tool-cordis/src/api-catalog.ts`
+
+本阶段不要求业务插件发布 Typert 子路径，不要求示例应用加载 Typert，也不改变 `tool-cordis` 的运行时依赖关系。
+
+## 可选路径
+
+### 运行时 registry 驱动 `tool-cordis`
+
+每个插件发布并加载 Typert 产物，`tool-cordis` 再从 `ctx.typert` 读取当前运行时模型。这条路径可以反映实际加载的插件集合，但会要求所有参与 catalog 的业务包增加 package exports、生成产物、registry contribution 和应用装配，接入面远大于当前要验证的分析能力。
+
+### 全仓发布 Typert 产物后静态汇总
+
+所有业务包在普通 build/typecheck 中生成 host/client JS 与 DTS，再由 catalog 生成器汇总这些产物。这条路径能够提前建立完整的发布协议，但会同时修改大量 package manifest 和构建拓扑，使 catalog 迁移与 Typert 的全仓发布绑定。
+
+### 构建期分析后投影 catalog
+
+`WorkspaceAnalyzer` 从 host TypeScript project 构建 `WorkspaceModel` 与 `TypeGraph`，仓库专用的 `CordisCatalogProjector` 只消费该模型并生成三份文本。`tool-cordis` 继续导入已提交的静态 `api-catalog.ts`，运行时不需要 Typert service。
+
+本阶段采用构建期投影。它直接验证 Typert 标准模型能否替代现有 AST collector，同时把运行时 publication 和自动加载留在独立的后续决策中。
+
+## 第一阶段架构
+
+```text
+tsconfig.host.json
+        │
+        ▼
+WorkspaceAnalyzer ── TypeScript compiler API 的唯一边界
+        │
+        ▼
+WorkspaceModel + TypeGraph
+        │
+        ▼
+CordisCatalogProjector ── 不依赖 TypeScript AST
+        ├── docs/cordis-catalog/events.md
+        ├── docs/cordis-catalog/services.md
+        └── packages/cordis/tool-cordis/src/api-catalog.ts
+```
+
+各对象的职责如下：
+
+- `WorkspaceAnalyzer` 负责 package、export、service、event、类型声明和引用关系的分析，并产生 compiler-independent model。
+- `WorkspaceModel` 与 `TypeGraph` 是所有生成和扫描分析共用的标准数据结构，保留开发者写出的泛型、继承和类型树，不保存 TypeScript AST。
+- `@deepseek-ai/dsh-typert-generator` 根入口导出的 `CordisCatalogProjector` 负责模型驱动的选择、排序、摘要、源位置、JSDoc 完整性、类型链接闭包和三种文本格式；实现仍单独放在 Cordis catalog 专用文件中，但不形成额外的 package subpath，也不内置仓库类型名单。
+- `scripts/gen-cordis-catalog.ts` 提供 `LINK_MAP`、`FOUNDATION_TYPE_NAMES`、`TYPE_LINK_EXEMPTIONS` 和 inherited Cordis 清单，通过 `CordisCatalogPolicy` 显式注入 projector，并负责 write/check 的命令行行为；vendor Cordis core 页面仍由独立的 pinned-source projector 生成。
+- `tool-cordis` 只导入静态 `api-catalog.ts`，不依赖 `typert-registry` 或 `typert-loader`。
+
+`CordisCatalogProjector` 是仓库业务消费者，不进入 Typert 通用模型。新增其他类别时，先扩展标准模型，再增加对应 projector；Typert analyzer 不吸收 Cordis 文档格式或 `tool-cordis` 展示逻辑。
+
+## 模型补充
+
+Catalog 的字符级投影除了类型结构，还需要开发者写下的声明形式和精确源码位置。标准模型因此保留 event/service location、event/member 的 body-free text、parameter initializer，以及 type declaration 的 export 状态和 canonical text；`SourceDeclarationModel` 另外索引顶层导出声明，供歧义检查和静态类型闭包使用，但不把它们提升为业务 graph root。
+
+```ts
+interface SourceLocation {
+  readonly file: string
+  readonly line: number
+  readonly column: number
+}
+
+interface EventModel {
+  readonly location: SourceLocation
+  readonly text: string
+}
+```
+
+全仓分析支持按 package 分批构建有界 `ts.Program`，再依靠源码位置稳定的 graph id 合并为与一次性分析等价的 face model。该能力只改变 compiler program 的内存边界，不改变 package、declaration 或 type graph 语义。
+
+projector 所需信息必须来自 `WorkspaceModel` 或 `TypeGraph`。如果字符级兼容需要的事实无法从模型表达，应补充标准模型；不得在 projector 或脚本中重新引入 `ts.Node`、`ts.Symbol` 或 `ts.TypeChecker`。
+
+## 字符级迁移 oracle
+
+迁移前，在同一份源码状态下保留旧生成器产生的三份文本。迁移后运行新的 analyzer 与 projector，要求三份输出逐字节相等；换行、空格、排序、JSDoc、source pointer 和生成头都属于比较内容。
+
+`pnpm run verify-cordis-catalog` 的 `--check` 模式继续读取三份 committed artifact，并与本次计算结果直接比较。任一文件缺失或任一字符不同都视为 stale，错误信息指向统一的 `pnpm run gen-cordis-catalog` 修复命令。
+
+测试同时固定以下两层：
+
+- Typert fixture snapshots 固定 `WorkspaceModel`、`TypeGraph`、JS、DTS 与 Zod 输出，证明标准模型和通用 emitter 的行为。
+- Cordis catalog 测试或 snapshot 固定 projector 的三份完整文本，证明仓库业务投影没有绕过标准模型，并给出可直接评审的文本证据。
+
+三份 committed artifact 是旧实现与新实现的迁移 oracle，也是迁移完成后的持续 freshness oracle。旧 `gen-cordis-api` AST collector 被删除；同名脚本和命令只作为统一 projector 的兼容入口保留，因为生成文件头本身包含该命令，保留入口可以维持字符级 oracle 而不产生第二套真源。
+
+## 精确改造清单
+
+### Typert generator
+
+- 补齐字符级投影所需的 location、authored declaration text、parameter initializer、export 状态和顶层 source declaration index，并在 analyzer 与 model snapshots 中覆盖。
+- 支持有界 package batch 分析，并证明 direct 与 batched model 等价。
+- 确认 catalog 所需的 service 声明、public instance member、JSDoc、泛型、继承和引用类型均可从 model 读取。
+- 保持 TypeScript compiler API 封装在 analyzer 内；公共 model 和 projector 输入不暴露 compiler 对象。
+
+### Cordis catalog projector
+
+- 从 host `WorkspaceModel` 选择完整的 Cordis service/event 集合。
+- 保留旧生成器的 JSDoc 规则：event 必须有 `@mode` 和 payload `@param`，service method 必须有参数对应的 `@param`，非 void 返回必须有 `@returns`。
+- 从 type graph 计算签名涉及的类型链接和 `tool-cordis` 所需的传递 public type closure。
+- 通过显式 `CordisCatalogPolicy` 接收调用方维护的类型分类和 inherited surface，不在 generator 包内维护仓库文档 taxonomy。
+- 保留 source pointer、签名、摘要、排序、声明截断和 inherited context catalog 的既有输出规则。
+- 一次投影并渲染 events Markdown、services Markdown 与 TypeScript API catalog，避免文档和工具数据漂移。
+
+### 命令与消费方
+
+- `scripts/gen-cordis-catalog.ts` 维护仓库 policy 数据、组装 analyzer/projector，并同时 write/check 三份产物；解析、校验和渲染逻辑位于 generator 的 Cordis 专用源文件，并统一从 package 根入口导出。
+- 将 `scripts/gen-cordis-api.ts` 收窄为统一 CLI 的无逻辑兼容入口；根目录的 `gen-cordis-api`、`verify-cordis-api` aliases 指向该入口。
+- `tool-cordis` 恢复静态 catalog 默认值，移除对 `ctx.typert`、`typert-registry` 和运行时 package model 完整性的依赖。
+- `gen-doc-graphs` 一次取得 projector 的 model-level 结果并复用 services/events，不能继续导入 AST collector 或重复分析全仓。
+
+### 收窄本阶段改动面
+
+- 撤销业务插件 package.json 中新增的 `./typert`、`./client/typert` exports 和 `lib/typert.*` files。
+- 撤销 examples 中的 `typert-registry`、`typert-loader` 装配。
+- 普通 build/typecheck 不运行全仓 `gen-typert`，也不要求 clean tree 预先存在业务包 Typert artifact。
+- 保留 `packages/typert/generator`、`packages/typert/registry`、`packages/typert/loader` 及其独立 fixture、emitter 和 runtime registration 测试。
+
+## 后续扩展
+
+Runtime registry 继续作为生成 JS/Zod 后的接收与查询层，loader 继续作为自动装载机制；两者不承担第一阶段静态 catalog 的数据来源。业务包需要运行时反射时，可以按 package opt-in 发布 `package/typert` 与 `package/client/typert`，再由 loader 注册到 `ctx.typert`。
+
+后续接入不改变本阶段的分层：TypeScript 只进入 analyzer，标准模型同时服务静态生成与扫描分析，runtime artifact 由 emitter 从同一模型产生。是否把更多 package 接入 publication、是否默认启用 loader，以及 runtime registry 最终提供哪些查询能力，分别评审，不与 Cordis catalog 迁移捆绑。

packages/cordis/tool-cordis/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/cordis/tool-cordis/README.md
-README.md: 5b58e665dae95aea0d0ad094238fef5d3dc0fb97
-README.zh.md: 237b72244be2336a82c8c48cb341d7f9796d08f4
+README.md: eda135d93e2912bbb4e111af40d176409b383b5b
+README.zh.md: 6eef10086142d56dd809e5114b4e0e712f726ecc

packages/cordis/tool-cordis/README.md

@@ -28,7 +28,7 @@ The sandbox isolates globals but is not a security boundary. Node globals are ab
 
 ## The generated API catalog
 
-`src/api-catalog.ts` is generated by `scripts/gen-cordis-api.ts` from the same AST walk as [docs/cordis-catalog](../../../docs/cordis-catalog/services.md) and freshness-gated by `pnpm run verify-cordis-api` (in `doc-sync`) — never edit it by hand. `cordis_inspect` intersects it with the live service store at call time. Broad `api` / `events` reports render summaries and signatures only; an exact `name` opts into the retained method/event JSDoc, and unknown or non-running service targets fail loud.
+`src/api-catalog.ts` is generated from the same Typert `FaceModel` projection as [docs/cordis-catalog](../../../docs/cordis-catalog/services.md) and freshness-gated by `pnpm run verify-cordis-api` (in `doc-sync`) — never edit it by hand. `scripts/gen-cordis-api.ts` is a compatibility entry point for that unified projection, not a second collector. `cordis_inspect` intersects the committed catalog with the live service store at call time; it has no runtime Typert dependency. Broad `api` / `events` reports render summaries and signatures only; an exact `name` opts into the retained method/event JSDoc, and unknown or non-running service targets fail loud.
 
 ## Rendering
 

packages/cordis/tool-cordis/README.zh.md

@@ -28,7 +28,7 @@
 
 ## 生成的 API 目录
 
-`src/api-catalog.ts` 由 `scripts/gen-cordis-api.ts` 生成，使用与 [docs/cordis-catalog](../../../docs/cordis-catalog/services.md) 相同的 AST 遍历，并由 `pnpm run verify-cordis-api`（位于 `doc-sync` 中）实施新鲜度门禁，绝不可手工编辑。`cordis_inspect` 在调用时把该目录与存活服务 store 取交集。宽泛的 `api`／`events` 报告只渲染摘要与签名；精确 `name` 会选择保留的方法／事件 JSDoc，未知或未运行的服务目标会明确报错。
+`src/api-catalog.ts` 与 [docs/cordis-catalog](../../../docs/cordis-catalog/services.md) 由同一个 Typert `FaceModel` 投影生成，并由 `pnpm run verify-cordis-api`（位于 `doc-sync` 中）实施新鲜度门禁，绝不可手工编辑。`scripts/gen-cordis-api.ts` 是该统一投影的兼容入口，而非第二套收集器。`cordis_inspect` 在调用时把已提交的目录与存活服务 store 取交集；它在运行时不依赖 Typert。宽泛的 `api`／`events` 报告只渲染摘要与签名；精确 `name` 会选择保留的方法／事件 JSDoc，未知或未运行的服务目标会高声失败。
 
 ## 渲染
 

packages/cordis/tool-cordis/src/api-catalog.ts

@@ -489,7 +489,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         jsDoc: '/**\n * Deliver an allowed signal through an owned backend session.\n * @param owner - exact session owner.\n * @param id - target PTY identity.\n * @param signal - allowed POSIX signal name.\n * @returns delivered foreground process-group identity.\n */',
       },
       {
-        signature: 'async kill(owner: Agent, id: PtySessionId, reason = \'model request\'): Promise<boolean>',
+        signature: 'async kill(owner: Agent, id: PtySessionId, reason: string = \'model request\'): Promise<boolean>',
         jsDoc: '/**\n * Close one owned session and remove it only after quiescent backend cleanup.\n * @param owner - exact session owner.\n * @param id - target PTY identity.\n * @param reason - diagnostic cleanup reason.\n * @returns true for a newly closed session, false when the same close is already in flight.\n */',
       },
       {
@@ -679,7 +679,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     summary: 'Exact-read consumer that prepares immutable cross-session message context.',
     methods: [
       {
-        signature: 'async listCandidates( agent: Agent, query = \'\', limit = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>',
+        signature: 'async listCandidates( agent: Agent, query: string = \'\', limit: number = this.config.candidateLimit, signal?: AbortSignal, ): Promise<SessionReferenceCandidate[]>',
         jsDoc: '/**\n * List reference candidates, ranked by working-directory affinity.\n * @param agent - target agent; self is excluded and its cwd drives ranking.\n * @param query - optional case-insensitive session-id/cwd/title substring.\n * @param limit - optional positive result cap.\n * @param signal - optional cancellation boundary for host autocomplete teardown.\n * @returns candidates labeled by latest title or, when absent, session id.\n */',
       },
       {
@@ -1002,6 +1002,40 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
       },
     ],
   },
+  {
+    key: 'typert',
+    summary: 'Registry of generated schemas and package reflection.',
+    methods: [
+      {
+        signature: 'register(contribution: TypertContribution): () => void',
+        jsDoc: '/**\n * Register one generated contribution atomically for the calling fiber.\n * Duplicate package-face identities or schema keys reject the whole batch.\n * @param contribution - generated schemas and package metadata.\n * @returns the exact effect disposer that removes this contribution.\n */',
+      },
+      {
+        signature: 'get(key: string): TypertSchemaRecord | undefined',
+        jsDoc: '/**\n * Look up one schema by `<package>#<name>`.\n * @param key - global schema key.\n * @returns the live schema record, or `undefined` when absent.\n */',
+      },
+      {
+        signature: 'resolve(key: string): TypertSchemaRecord',
+        jsDoc: '/**\n * Resolve one required schema.\n * @param key - global schema key.\n * @returns the live schema record.\n * @throws when the key is malformed, the package face is absent, or the schema is not contributed.\n */',
+      },
+      {
+        signature: 'list(filter: TypertSchemaFilter = {}): TypertSchemaRecord[]',
+        jsDoc: '/**\n * Enumerate live schemas in registration order.\n * @param filter - optional package and face restriction.\n * @returns matching schema records.\n */',
+      },
+      {
+        signature: 'getPackage(packageName: string, face: TypertFace = \'host\'): TypertPackageRecord | undefined',
+        jsDoc: '/**\n * Look up generated reflection for one package face.\n * @param packageName - exact npm package name.\n * @param face - face to query; defaults to the host runtime.\n * @returns the live package record, or `undefined` when absent.\n */',
+      },
+      {
+        signature: 'listPackages(filter: TypertPackageFilter = {}): TypertPackageRecord[]',
+        jsDoc: '/**\n * Enumerate generated package reflection in registration order.\n * @param filter - optional package and face restriction.\n * @returns matching package records.\n */',
+      },
+      {
+        signature: 'toJSONSchema(key: string, params?: z.core.ToJSONSchemaParams): z.core.JSONSchema.BaseSchema',
+        jsDoc: '/**\n * Project a live Zod schema to JSON Schema without caching the result.\n * @param key - global schema key.\n * @param params - Zod projection parameters.\n * @returns a fresh JSON Schema document.\n */',
+      },
+    ],
+  },
   {
     key: 'userInteraction',
     summary: '`ctx.userInteraction`: one active UI provider plus an `ask()` surface.',
@@ -1281,34 +1315,6 @@ export const EVENT_API: readonly EventApiEntry[] = [
     jsDoc: '/**\n * A skill provider, runtime contribution, or provider-backed catalog may\n * have changed. This is an unfiltered invalidation notification; consumers\n * refetch the catalog for their own lookup options. Listener failures are\n * contained and cannot veto the registry mutation.\n * @mode emit\n */',
     summary: 'A skill provider, runtime contribution, or provider-backed catalog may have changed.',
   },
-  {
-    name: 'slash/input-begin-command',
-    mode: 'bail',
-    signature: '\'slash/input-begin-command\'(request: BeginCommandRequest): true | undefined',
-    jsDoc: '/**\n * Applies one command claim to the scoped Input. Dispatched with the\n * session\'s scope carrier; the owning session\'s input listener returns\n * `true` only after the phase and span CAS checks pass and the machine\n * actually mutated — producers treat anything else as "not applied".\n * @param request - Claim and menu-time span CAS.\n * @mode bail\n */',
-    summary: 'Applies one command claim to the scoped Input.',
-  },
-  {
-    name: 'slash/input-consume-token',
-    mode: 'bail',
-    signature: '\'slash/input-consume-token\'(request: ConsumeTokenRequest): true | undefined',
-    jsDoc: '/**\n * Consumes one command token after business success (popup settle /\n * menu-pick execute). Same carrier routing and applied-truth contract.\n * @param request - Exact span or bare-token guard.\n * @mode bail\n */',
-    summary: 'Consumes one command token after business success (popup settle / menu-pick execute).',
-  },
-  {
-    name: 'slash/input-insert-reference',
-    mode: 'bail',
-    signature: '\'slash/input-insert-reference\'(request: InsertReferenceRequest): true | undefined',
-    jsDoc: '/**\n * Inserts one reference into the scoped Input (same carrier routing and\n * applied-truth contract as begin-command).\n * @param request - Reference and menu-time span CAS.\n * @mode bail\n */',
-    summary: 'Inserts one reference into the scoped Input (same carrier routing and applied-truth contract as begin-command).',
-  },
-  {
-    name: 'slash/input-insert-text',
-    mode: 'bail',
-    signature: '\'slash/input-insert-text\'(request: InsertTextRequest): true | undefined',
-    jsDoc: '/**\n * Replaces the trigger token span with literal text — the plain-text\n * reference path (decision 21). Same carrier routing and applied-truth\n * contract; the draft gains ordinary characters, no occurrence entry.\n * @param request - Replacement text and menu-time span CAS.\n * @mode bail\n */',
-    summary: 'Replaces the trigger token span with literal text — the plain-text reference path (decision 21).',
-  },
   {
     name: 'subagent/end',
     mode: 'emit',
@@ -2694,6 +2700,62 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'TurnTriggerMap',
     declaration: 'export interface TurnTriggerMap {\n    message: {\n        kind: \'message\';\n        source: MessageSource;\n    };\n    retry: {\n        kind: \'retry\';\n    };\n    injection: {\n        kind: \'injection\';\n        source: MessageSource;\n    };\n}',
   },
+  {
+    name: 'TypertContribution',
+    declaration: 'export interface TypertContribution {\n    readonly package: string;\n    readonly face: TypertFace;\n    readonly schemas: readonly TypertSchema[];\n    readonly model: TypertPackageModel;\n}',
+  },
+  {
+    name: 'TypertDocTag',
+    declaration: 'export interface TypertDocTag {\n    readonly name: string;\n    readonly argument?: string;\n    readonly comment?: string;\n    readonly text: string;\n}',
+  },
+  {
+    name: 'TypertDocumentation',
+    declaration: 'export interface TypertDocumentation {\n    readonly description?: string;\n    readonly summary?: string;\n    readonly tags: readonly TypertDocTag[];\n    readonly jsDoc?: string;\n}',
+  },
+  {
+    name: 'TypertEventModel',
+    declaration: 'export interface TypertEventModel extends TypertDocumentation {\n    readonly name: string;\n    readonly mode?: string;\n    readonly signature: string;\n}',
+  },
+  {
+    name: 'TypertMemberModel',
+    declaration: 'export interface TypertMemberModel {\n    readonly kind: \'property\' | \'method\' | \'getter\' | \'setter\' | \'call\' | \'construct\' | \'index\';\n    readonly name: string;\n    readonly signature: string;\n    readonly summary?: string;\n    readonly jsDoc?: string;\n}',
+  },
+  {
+    name: 'TypertObjectModel',
+    declaration: 'export interface TypertObjectModel extends TypertDocumentation {\n    readonly name: string;\n    readonly exportName: string;\n    readonly members: readonly TypertMemberModel[];\n    readonly types: readonly TypertTypeModel[];\n}',
+  },
+  {
+    name: 'TypertPackageFilter',
+    declaration: 'export interface TypertPackageFilter {\n    readonly package?: string;\n    readonly face?: TypertFace;\n}',
+  },
+  {
+    name: 'TypertPackageModel',
+    declaration: 'export interface TypertPackageModel {\n    readonly services: readonly TypertServiceModel[];\n    readonly events: readonly TypertEventModel[];\n    readonly objects: readonly TypertObjectModel[];\n}',
+  },
+  {
+    name: 'TypertPackageRecord',
+    declaration: 'export interface TypertPackageRecord {\n    readonly package: string;\n    readonly face: TypertFace;\n    readonly key: string;\n    readonly model: TypertPackageModel;\n}',
+  },
+  {
+    name: 'TypertSchema',
+    declaration: 'export interface TypertSchema {\n    readonly name: string;\n    readonly schema: z.ZodType;\n}',
+  },
+  {
+    name: 'TypertSchemaFilter',
+    declaration: 'export interface TypertSchemaFilter {\n    readonly package?: string;\n    readonly face?: TypertFace;\n}',
+  },
+  {
+    name: 'TypertSchemaRecord',
+    declaration: 'export interface TypertSchemaRecord extends TypertSchema {\n    readonly package: string;\n    readonly face: TypertFace;\n    readonly key: string;\n}',
+  },
+  {
+    name: 'TypertServiceModel',
+    declaration: 'export interface TypertServiceModel extends TypertDocumentation {\n    readonly key: string;\n    readonly exportName: string;\n    readonly members: readonly TypertMemberModel[];\n    readonly types: readonly TypertTypeModel[];\n}',
+  },
+  {
+    name: 'TypertTypeModel',
+    declaration: 'export interface TypertTypeModel {\n    readonly name: string;\n    readonly declaration: string;\n}',
+  },
   {
     name: 'UserInteractionProvider',
     declaration: 'export interface UserInteractionProvider {\n    ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>;\n}',

packages/typert/generator/src/analyzer.ts

@@ -1207,7 +1207,7 @@ class FaceAnalyzer {
     const owner = this.registrationForFile(declaration.getSourceFile().fileName)
     if (owner !== undefined) {
       if (owner.name !== from.name) {
-        if (module === undefined || module.package !== owner.name) {
+        if (module === undefined) {
           this.fail(site, `reference to ${symbol.name} crosses a package without an explicit package import`)
         }
         const exportName = authoredExportName(site, moduleSpecifier as string)

packages/typert/generator/tests/cordis-catalog-contract.spec.ts

@@ -1,5 +1,5 @@
 /**
- * Contract and negative-path tests for the cordis catalog generator
+ * Model-extraction and negative-path contracts for the Cordis catalog generator
  * (`scripts/gen-cordis-catalog.ts`).
  */
 
@@ -7,16 +7,91 @@ import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it } from 'vitest'
-import { collectEvents, collectServices, renderEvents, renderServices } from '../../../../scripts/gen-cordis-catalog.ts'
+import {
+  collectEvents as collectEventsWithPolicy,
+  collectServices as collectServicesWithPolicy,
+  renderEvents as renderEventsWithPolicy,
+  renderServices as renderServicesWithPolicy,
+} from '../src/cordis-catalog.ts'
+import type {
+  CordisCatalogPolicy,
+  EventEntry,
+  ServiceEntry,
+} from '../src/cordis-catalog.ts'
+
+const TEST_POLICY: CordisCatalogPolicy = {
+  linkedTypePages: { SessionEvent: 'core.md' },
+  foundationTypeNames: new Set(['AbortSignal', 'Promise', 'Readonly']),
+  typeLinkExemptions: { PresetSpec: 'fixture deployment metadata' },
+  inheritedEvents: [],
+  inheritedServices: [],
+}
+
+function collectEvents(root: string): EventEntry[] {
+  return collectEventsWithPolicy(root, TEST_POLICY)
+}
+
+function collectServices(root: string): ServiceEntry[] {
+  return collectServicesWithPolicy(root, TEST_POLICY)
+}
+
+function renderEvents(events: EventEntry[]): string {
+  return renderEventsWithPolicy(events, TEST_POLICY)
+}
+
+function renderServices(services: ServiceEntry[]): string {
+  return renderServicesWithPolicy(services, TEST_POLICY)
+}
+
+const TYPE_FIXTURES = [
+  'export interface FixtureEntry {}',
+  'interface SessionEvent {}',
+  'interface PresetSpec {}',
+  'interface MissingOne {}',
+  'type missingTwo = string',
+  'interface MissingServiceType {}',
+  '',
+].join('\n')
+
+/** Materialize one independently compilable package and its host aggregate. */
+function writeProject(root: string, source: string): void {
+  const packageRoot = join(root, 'packages', 'group', 'fix')
+  const sourceRoot = join(packageRoot, 'src')
+  mkdirSync(sourceRoot, { recursive: true })
+  writeFileSync(join(root, 'tsconfig.host.json'), JSON.stringify({
+    files: [],
+    references: [{ path: './packages/group/fix' }],
+  }))
+  writeFileSync(join(packageRoot, 'package.json'), JSON.stringify({
+    name: '@fixture/fix',
+    private: true,
+    type: 'module',
+    exports: {
+      '.': {
+        types: './lib/types/index.d.ts',
+        default: './lib/index.js',
+      },
+    },
+  }))
+  writeFileSync(join(packageRoot, 'tsconfig.json'), JSON.stringify({
+    compilerOptions: {
+      composite: true,
+      module: 'ESNext',
+      moduleResolution: 'Bundler',
+      rootDir: 'src',
+      target: 'ES2022',
+    },
+    include: ['src'],
+  }))
+  writeFileSync(join(sourceRoot, 'index.ts'), `${TYPE_FIXTURES}${source}`)
+}
 
 /** Write a fixture package exposing one `interface Events` block and return the
  * scan root to hand `collectEvents`. */
 function fixtureRoot(eventsBlock: string): string {
   const root = mkdtempSync(join(tmpdir(), 'cordis-catalog-'))
-  const dir = join(root, 'packages', 'group', 'fix', 'src')
-  mkdirSync(dir, { recursive: true })
-  writeFileSync(
-    join(dir, 'index.ts'),
+  writeProject(
+    root,
     `declare module 'cordis' {\n  interface Events {\n${eventsBlock}\n  }\n}\n`,
   )
   return root
@@ -27,10 +102,8 @@ function fixtureRoot(eventsBlock: string): string {
  * `collectServices`. */
 function serviceFixtureRoot(classSource: string): string {
   const root = mkdtempSync(join(tmpdir(), 'cordis-catalog-'))
-  const dir = join(root, 'packages', 'group', 'fix', 'src')
-  mkdirSync(dir, { recursive: true })
-  writeFileSync(
-    join(dir, 'index.ts'),
+  writeProject(
+    root,
     `declare module 'cordis' {\n  interface Context {\n    fix: FixService\n  }\n}\n\n${classSource}\n`,
   )
   return root
@@ -95,9 +168,9 @@ describe('gen-cordis-catalog collectEvents', () => {
       'fix/two',
       'packages/group/fix/src/index.ts',
       'missingTwo',
-      'Add it to LINK_MAP',
-      'FOUNDATION_TYPE_NAMES',
-      'TYPE_LINK_EXEMPTIONS',
+      'Add it to linkedTypePages',
+      'foundationTypeNames',
+      'typeLinkExemptions',
     ].join('[\\s\\S]*'))
     expect(() => collectEvents(make(
       '    /**\n     * First.\n     * @param value - first value.\n     * @mode emit\n     */\n    \'fix/one\'(value: MissingOne): void\n    /**\n     * Second.\n     * @param value - second value.\n     * @mode emit\n     */\n    \'fix/two\'(value: missingTwo): void',
@@ -222,7 +295,7 @@ export class FixService {
   it('hard-errors on an unannotated (inferred) return type', () => {
     expect(() => collectServices(makeService(
       '/** Fixture service. */\nexport class FixService {\n  /**\n   * Do the thing.\n   * @param id - which thing.\n   */\n  run(id: string) { return id }\n}',
-    ))).toThrow(/no return type annotation/)
+    ))).toThrow(/missing an explicit type annotation/)
   })
 
   it('hard-errors on a service class with no JSDoc', () => {

packages/typert/generator/tests/cordis-catalog.spec.ts

@@ -0,0 +1,24 @@
+import { readFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import {
+  projectCordisCatalog,
+  renderEvents,
+  renderServices,
+} from '../src/cordis-catalog.ts'
+import { CORDIS_CATALOG_POLICY } from '../../../../scripts/gen-cordis-catalog.ts'
+
+const workspaceRoot = resolve(import.meta.dirname, '../../../..')
+
+describe('Typert-backed Cordis catalog', () => {
+  it('reproduces every committed catalog artifact byte for byte', { timeout: 480_000 }, () => {
+    const { projector, model } = projectCordisCatalog(workspaceRoot, CORDIS_CATALOG_POLICY)
+    const expected = (path: string): string => readFileSync(join(workspaceRoot, path), 'utf8')
+
+    expect(renderEvents([...model.events], CORDIS_CATALOG_POLICY)).toBe(expected('docs/cordis-catalog/events.md'))
+    expect(renderServices([...model.services], CORDIS_CATALOG_POLICY)).toBe(expected('docs/cordis-catalog/services.md'))
+    expect(projector.renderRuntimeApi(model)).toBe(
+      expected('packages/cordis/tool-cordis/src/api-catalog.ts'),
+    )
+  })
+})

packages/typert/generator/tests/tools-catalog.spec.ts

@@ -0,0 +1,68 @@
+import { mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
+import type { TypertContribution } from '@deepseek-ai/dsh-typert-registry/types'
+import { EVENT_API, SERVICE_API, TYPE_API } from '@deepseek-ai/dsh-tool-cordis/src/api-catalog.ts'
+import { WorkspaceAnalyzer } from '../src/analyzer.ts'
+import { FaceModelEmitter } from '../src/emitter.ts'
+
+const workspaceRoot = resolve(import.meta.dirname, '../../../..')
+const temporaryRoots: string[] = []
+
+afterEach(() => {
+  for (const root of temporaryRoots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+describe('model-driven dsh-tools generation', () => {
+  it('round-trips the complete service and event structure through the runtime registry', { timeout: 30_000 }, async () => {
+    const workspace = new WorkspaceAnalyzer({
+      root: workspaceRoot,
+      faces: ['host'],
+      packages: ['@deepseek-ai/dsh-tools'],
+    }).analyze()
+    const host = workspace.faces.find(candidate => candidate.face === 'host')
+    if (host === undefined) throw new Error('dsh-tools has no analyzed host face')
+    const artifact = new FaceModelEmitter(host).emit('@deepseek-ai/dsh-tools')
+
+    const root = mkdtempSync(join(import.meta.dirname, '.generated-tools-'))
+    temporaryRoots.push(root)
+    const modulePath = join(root, 'host.mjs')
+    writeFileSync(modulePath, artifact.js)
+    const generated = await import(`${pathToFileURL(modulePath).href}?test=${Date.now()}`) as {
+      TYPERT: TypertContribution
+    }
+
+    const ctx = new Context()
+    await ctx.plugin(TypertRegistry)
+    const dispose = ctx.typert.register(generated.TYPERT)
+    const record = ctx.typert.getPackage('@deepseek-ai/dsh-tools', 'host')
+    const service = record?.model.services.find(candidate => candidate.key === 'tools')
+    expect(service).toBeDefined()
+    expect({
+      key: service?.key,
+      summary: service?.summary,
+      methods: service?.members
+        .filter(member => member.kind === 'method' && !member.name.startsWith('['))
+        .map(member => ({
+          signature: member.signature,
+          jsDoc: member.jsDoc ?? '',
+        })),
+    }).toEqual(SERVICE_API.find(candidate => candidate.key === 'tools'))
+    expect(record?.model.events.filter(event => event.name.startsWith('tools/')).map(event => ({
+      name: event.name,
+      mode: event.mode,
+      signature: event.signature,
+      jsDoc: event.jsDoc ?? '',
+      summary: event.summary,
+    }))).toEqual(EVENT_API.filter(event => event.name.startsWith('tools/')))
+    expect(service?.types.find(type => type.name === 'ToolDefinition')).toEqual(
+      TYPE_API.find(type => type.name === 'ToolDefinition'),
+    )
+
+    dispose()
+    expect(ctx.typert.getPackage('@deepseek-ai/dsh-tools', 'host')).toBeUndefined()
+  })
+})

packages/typert/generator/tests/type-model.spec.ts

@@ -489,6 +489,59 @@ describe('WorkspaceAnalyzer', { timeout: 60_000 }, () => {
       && node.target.symbol === payload?.id)).toBe(true)
   })
 
+  it('resolves explicit same-face package re-exports to their declaration owner', () => {
+    const root = copyFixture('typert-same-face-reexport-')
+    const packageRoot = join(root, 'packages/barrel')
+    mkdirSync(join(packageRoot, 'src'), { recursive: true })
+    writeFileSync(join(packageRoot, 'package.json'), JSON.stringify({
+      name: '@fixture/barrel',
+      private: true,
+      type: 'module',
+      exports: {
+        '.': {
+          types: './lib/types/index.d.ts',
+          default: './lib/index.js',
+        },
+      },
+    }, null, 2))
+    writeFileSync(join(packageRoot, 'tsconfig.json'), JSON.stringify({
+      extends: '../../tsconfig.base.json',
+      compilerOptions: { rootDir: 'src', outDir: 'lib/types' },
+      include: ['src'],
+      references: [{ path: '../host' }],
+    }, null, 2))
+    writeFileSync(
+      join(packageRoot, 'src/index.ts'),
+      "export type { Payload } from '@fixture/host/models'\n",
+    )
+    const basePath = join(root, 'tsconfig.base.json')
+    const base = JSON.parse(readFileSync(basePath, 'utf8')) as {
+      compilerOptions: { paths: Record<string, string[]> }
+    }
+    base.compilerOptions.paths['@fixture/barrel'] = ['./packages/barrel/src/index.ts']
+    writeFileSync(basePath, `${JSON.stringify(base, null, 2)}\n`)
+    const aggregatePath = join(root, 'tsconfig.host.json')
+    const aggregate = JSON.parse(readFileSync(aggregatePath, 'utf8')) as { references: { path: string }[] }
+    aggregate.references.push({ path: './packages/barrel' })
+    writeFileSync(aggregatePath, `${JSON.stringify(aggregate, null, 2)}\n`)
+    addSameFacePackage(root, '@fixture/barrel', 'Payload')
+    const consumerConfigPath = join(root, 'packages/consumer/tsconfig.json')
+    const consumerConfig = JSON.parse(readFileSync(consumerConfigPath, 'utf8')) as {
+      references: { path: string }[]
+    }
+    consumerConfig.references.push({ path: '../barrel' })
+    writeFileSync(consumerConfigPath, `${JSON.stringify(consumerConfig, null, 2)}\n`)
+
+    const model = new WorkspaceAnalyzer({ root }).analyze()
+    const host = model.faces.find(face => face.face === 'host')
+    const payload = host?.graph.declarations.find(declaration => declaration.name === 'Payload')
+    expect(host?.graph.nodes.some(node => node.id.includes('packages/consumer/src/index.ts')
+      && node.kind === 'reference'
+      && node.name === 'Payload'
+      && node.target.kind === 'declaration'
+      && node.target.symbol === payload?.id)).toBe(true)
+  })
+
   it('rejects same-face package imports outside package.json exports', () => {
     const root = copyFixture('typert-private-package-')
     writeFileSync(

scripts/cordis-walk.ts

@@ -1,11 +1,6 @@
-/**
- * AST walkers for the Cordis catalog generator: locate the Cordis module merge
- * in a source file, enumerate its `interface Events` members, and resolve the
- * `interface Context` service keys to their service classes.
- */
+/** Locate the Cordis module merge used by the vendored core API projector. */
 
 import ts from 'typescript'
-import { parseJsDoc, pointer, rawJsDoc } from './jsdoc.ts'
 
 /** The body of the cordis module merge in `sf`: `declare module 'cordis'`
  * (harness packages) or `declare module './context.ts'` (vendor core), or
@@ -18,74 +13,3 @@ export function cordisModuleBody(sf: ts.SourceFile): ts.ModuleBlock | null {
   }
   return null
 }
-
-/** Every `interface Events` method member of a cordis module merge, with the
- * event name resolved from its (possibly string-literal) property name. */
-export function eventMembers(body: ts.ModuleBlock, sf: ts.SourceFile): { name: string; member: ts.MethodSignature }[] {
-  const out: { name: string; member: ts.MethodSignature }[] = []
-  for (const stmt of body.statements) {
-    if (!ts.isInterfaceDeclaration(stmt) || stmt.name.text !== 'Events') continue
-    for (const member of stmt.members) {
-      if (!ts.isMethodSignature(member)) continue
-      const name = ts.isStringLiteral(member.name) ? member.name.text : member.name.getText(sf)
-      out.push({ name, member })
-    }
-  }
-  return out
-}
-
-/** The `ctx.<key> → type name` map declared by a merge's `interface Context`. */
-function contextKeyMap(body: ts.ModuleBlock, sf: ts.SourceFile): Map<string, string> {
-  const keyToType = new Map<string, string>()
-  for (const stmt of body.statements) {
-    if (!ts.isInterfaceDeclaration(stmt) || stmt.name.text !== 'Context') continue
-    for (const member of stmt.members) {
-      if (!ts.isPropertySignature(member) || !member.type) continue
-      keyToType.set(member.name.getText(sf), member.type.getText(sf))
-    }
-  }
-  return keyToType
-}
-
-/** One `ctx.<key>` service class resolved from a Context merge. */
-export interface ServiceClass {
-  key: string
-  type: string
-  cls: ts.ClassDeclaration
-  abstract: boolean
-  /** Class-level JSDoc prose (empty string when missing — also reported). */
-  doc: string
-}
-
-/**
- * Resolve each `ctx.<key>` of a merge to the service class declared in the
- * same file. A key whose type is not a class here (a Pick-mixin member, e.g.
- * timer helpers) is skipped. A class without JSDoc prose is reported into
- * `violations` (named `where` by the caller's gate).
- *
- * @param body — the cordis module merge body.
- * @param sf — the source file containing the merge.
- * @param rel — repo-relative path of `sf`, for violation pointers.
- * @param violations — sink for JSDoc-completeness violations.
- * @returns the resolved service classes, in Context-declaration order.
- */
-export function serviceClasses(
-  body: ts.ModuleBlock,
-  sf: ts.SourceFile,
-  rel: string,
-  violations: string[],
-): ServiceClass[] {
-  const text = sf.getFullText()
-  const out: ServiceClass[] = []
-  for (const [key, type] of contextKeyMap(body, sf)) {
-    const cls = sf.statements.find(
-      (s): s is ts.ClassDeclaration => ts.isClassDeclaration(s) && s.name?.text === type,
-    )
-    if (!cls) continue // a Pick-mixin member, not a class here
-    const abstract = cls.modifiers?.some(m => m.kind === ts.SyntaxKind.AbstractKeyword) ?? false
-    const doc = parseJsDoc(rawJsDoc(text, cls)).doc
-    if (!doc) violations.push(`service ctx.${key} (${pointer(rel, sf, cls)}): class ${type} has no JSDoc.`)
-    out.push({ key, type, cls, abstract, doc })
-  }
-  return out
-}

scripts/doc-budgets.manifest.json

@@ -1,11 +1,11 @@
 {
   "AGENTS.md": 1750,
   "docs/AGENTS.md": 1150,
-  "docs/architecture.md": 1800,
+  "docs/architecture.md": 1920,
   "docs/cordis-primer.md": 600,
   "docs/defensive-patterns.md": 550,
   "docs/testing.md": 1100,
   "examples/AGENTS.md": 310,
   "packages/AGENTS.md": 675,
-  "packages/README.md": 870
+  "packages/README.md": 900
 }

scripts/gen-cordis-api.ts

@@ -1,282 +1,9 @@
 /**
- * Generate the model-facing Cordis API data module from the same event/service
- * collector as the documentation catalogs. It emits original declaration
- * JSDoc, first-sentence summaries, raw signatures, transitive public type
- * shapes, and inherited context entries, without source pointers; output is
- * deterministic and `--check` verifies it.
+ * Compatibility entry point for the unified Typert-backed Cordis catalog
+ * projection. The generated API module retains this command in its banner,
+ * while all extraction, validation, and rendering live in one implementation.
  */
 
-import { globSync, readFileSync, writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import ts from 'typescript'
-import { collectEvents, collectServices, INHERITED_SERVICES } from './gen-cordis-catalog.ts'
+import { main } from './gen-cordis-catalog.ts'
 
-const root = resolve(import.meta.dirname, '..')
-const OUT = 'packages/cordis/tool-cordis/src/api-catalog.ts'
-
-/** Declarations longer than this render as a truncated stub — a shape the model cannot skim teaches nothing. */
-const MAX_DECL_CHARS = 1500
-
-/** The first sentence of a (possibly multi-line) JSDoc prose block. */
-function firstSentence(doc: string): string {
-  const line = doc.split('\n', 1)[0] ?? ''
-  const match = /^(.*?[.!?])(?:\s|$)/.exec(line)
-  return (match?.[1] ?? line).trim()
-}
-
-/** Render a string as a single-quoted, lint-clean TS literal. */
-function quote(value: string): string {
-  return `'${value.replace(/\\/g, '\\\\').replace(/'/g, '\\\'').replace(/\n/g, '\\n')}'`
-}
-
-/**
- * Reduce an exported class to its type shape: drop method/constructor bodies
- * and property initializers so the catalog serves member signatures, not
- * implementation. An abstract class (e.g. `Agent`) is a public type consumers
- * program against, so it belongs in the type closure alongside interfaces.
- */
-function classShape(node: ts.ClassDeclaration): ts.ClassDeclaration {
-  const isNonPublic = (member: ts.ClassElement): boolean =>
-    (ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined)?.some(m =>
-      m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword) ?? false
-  const members = node.members.flatMap((member): ts.ClassElement[] => {
-    // A model-facing type shape carries only the public surface — drop private,
-    // protected, and #private members, and strip every kept member's body.
-    if (isNonPublic(member) || (ts.isPropertyDeclaration(member) && ts.isPrivateIdentifier(member.name))) return []
-    if (ts.isMethodDeclaration(member)) {
-      return [ts.factory.updateMethodDeclaration(
-        member, member.modifiers, member.asteriskToken, member.name, member.questionToken,
-        member.typeParameters, member.parameters, member.type, undefined)]
-    }
-    if (ts.isConstructorDeclaration(member)) {
-      return [ts.factory.updateConstructorDeclaration(member, member.modifiers, member.parameters, undefined)]
-    }
-    if (ts.isGetAccessorDeclaration(member)) {
-      return [ts.factory.updateGetAccessorDeclaration(
-        member, member.modifiers, member.name, member.parameters, member.type, undefined)]
-    }
-    if (ts.isSetAccessorDeclaration(member)) {
-      return [ts.factory.updateSetAccessorDeclaration(
-        member, member.modifiers, member.name, member.parameters, undefined)]
-    }
-    if (ts.isPropertyDeclaration(member)) {
-      return [ts.factory.updatePropertyDeclaration(
-        member, member.modifiers, member.name, member.questionToken ?? member.exclamationToken, member.type, undefined)]
-    }
-    return [member]
-  })
-  return ts.factory.updateClassDeclaration(
-    node, node.modifiers, node.name, node.typeParameters, node.heritageClauses, members)
-}
-
-/**
- * Collect exported interface, type-alias, and (body-stripped) class shapes;
- * omit names declared in multiple packages rather than risk serving the wrong
- * package's shape.
- */
-function collectTypeDecls(scanRoot: string = root): Map<string, string> {
-  const printer = ts.createPrinter({ removeComments: true })
-  const decls = new Map<string, string>()
-  const ambiguous = new Set<string>()
-  for (const rel of globSync('packages/*/*/src/*.ts', { cwd: scanRoot }).sort()) {
-    const abs = resolve(scanRoot, rel)
-    const sf = ts.createSourceFile(abs, readFileSync(abs, 'utf8'), ts.ScriptTarget.Latest, true)
-    for (const stmt of sf.statements) {
-      const named = ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt) || ts.isClassDeclaration(stmt)
-      if (!named || stmt.name === undefined) continue
-      if (!(stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false)) continue
-      const name = stmt.name.text
-      if (decls.has(name)) {
-        ambiguous.add(name)
-        continue
-      }
-      const emit = ts.isClassDeclaration(stmt) ? classShape(stmt) : stmt
-      const printed = printer.printNode(ts.EmitHint.Unspecified, emit, sf).replace(/\r/g, '')
-      decls.set(name, printed.length > MAX_DECL_CHARS
-        ? `${printed.slice(0, MAX_DECL_CHARS)} /* …truncated — full shape in source */`
-        : printed)
-    }
-  }
-  for (const name of ambiguous) decls.delete(name)
-  return decls
-}
-
-/** Resolve and sort the word-bounded transitive type closure referenced by seed text. */
-function referencedTypes(seeds: string[], decls: Map<string, string>): { name: string; declaration: string }[] {
-  const included = new Map<string, string>()
-  let frontier = seeds
-  while (frontier.length > 0) {
-    const next: string[] = []
-    for (const [name, declaration] of decls) {
-      if (included.has(name)) continue
-      const pattern = new RegExp(`\\b${name}\\b`)
-      if (frontier.some(text => pattern.test(text))) {
-        included.set(name, declaration)
-        next.push(declaration)
-      }
-    }
-    frontier = next
-  }
-  return [...included].map(([name, declaration]) => ({ name, declaration })).sort((a, b) => a.name.localeCompare(b.name))
-}
-
-/** Render the whole generated module (pure, deterministic given sorted collector output). */
-function render(): string {
-  const services = collectServices()
-  const events = collectEvents().sort((a, b) => a.name.localeCompare(b.name))
-  const types = referencedTypes(services.flatMap(service => service.methods.map(method => method.signature)), collectTypeDecls())
-  const lines: string[] = [
-    '/**',
-    ' * Generated by scripts/gen-cordis-api.ts — do not edit by hand; run',
-    ' * `pnpm run gen-cordis-api` to regenerate (freshness-gated by',
-    ' * `pnpm run verify-cordis-api` in doc-sync).',
-    ' *',
-    ' * The machine-readable cordis API catalog `cordis_inspect` serves to the',
-    ' * model: harness services (summary + public method signatures/JSDoc),',
-    ' * harness events (mode + signature/JSDoc), and the inherited `ctx` surface. Produced by',
-    ' * the same AST walk as docs/cordis-catalog, so this data and the rendered',
-    ' * docs cannot diverge.',
-    ' *',
-    ' * @module @deepseek-ai/dsh-tool-cordis/api-catalog',
-    ' */',
-    '',
-    '/** One public service method and its source-owned contract. */',
-    'export interface ServiceApiMethod {',
-    '  /** Public method signature with its body stripped. */',
-    '  signature: string',
-    '  /** Original method JSDoc, with only container indentation removed. */',
-    '  jsDoc: string',
-    '}',
-    '',
-    '/** One harness `ctx.<key>` service: its one-line summary and public methods. */',
-    'export interface ServiceApiEntry {',
-    '  /** The `ctx.<key>` name, e.g. `tools`. */',
-    '  key: string',
-    '  /** First sentence of the service class JSDoc. */',
-    '  summary: string',
-    '  /** Public methods, bodies stripped, in source order. */',
-    '  methods: readonly ServiceApiMethod[]',
-    '}',
-    '',
-    '/** One harness event: its dispatch mode, exact signature, and one-line summary. */',
-    'export interface EventApiEntry {',
-    '  /** The scoped event name, e.g. `agent/status`. */',
-    '  name: string',
-    '  /** The dispatch mode from the declaration\'s `@mode` tag. */',
-    '  mode: string',
-    '  /** The exact listener signature, whitespace-normalized. */',
-    '  signature: string',
-    '  /** Original event JSDoc, with only container indentation removed. */',
-    '  jsDoc: string',
-    '  /** First sentence of the event JSDoc. */',
-    '  summary: string',
-    '}',
-    '',
-    '/** One inherited (cordis core + loader/hmr/timer) `ctx` member group with its summary. */',
-    'export interface InheritedApiEntry {',
-    '  /** The `ctx` member name(s), e.g. `ctx.on / ctx.once`. */',
-    '  name: string',
-    '  /** One-line summary of what the member does. */',
-    '  summary: string',
-    '}',
-    '',
-    '/** One named type shape the service signatures reference. */',
-    'export interface TypeApiEntry {',
-    '  /** The exported type/interface name, e.g. `BashRunResult`. */',
-    '  name: string',
-    '  /** The full declaration text, comments stripped. */',
-    '  declaration: string',
-    '}',
-    '',
-    '/** Every harness `ctx.<key>` service, sorted by key. */',
-    'export const SERVICE_API: readonly ServiceApiEntry[] = [',
-  ]
-  for (const service of services) {
-    lines.push('  {')
-    lines.push(`    key: ${quote(service.key)},`)
-    lines.push(`    summary: ${quote(firstSentence(service.doc))},`)
-    if (service.methods.length === 0) {
-      lines.push('    methods: [],')
-    } else {
-      lines.push('    methods: [')
-      for (const method of service.methods) {
-        lines.push('      {')
-        lines.push(`        signature: ${quote(method.signature)},`)
-        lines.push(`        jsDoc: ${quote(method.jsDoc)},`)
-        lines.push('      },')
-      }
-      lines.push('    ],')
-    }
-    lines.push('  },')
-  }
-  lines.push(
-    ']',
-    '',
-    '/** Every harness event, sorted by name. */',
-    'export const EVENT_API: readonly EventApiEntry[] = [',
-  )
-  for (const event of events) {
-    lines.push('  {')
-    lines.push(`    name: ${quote(event.name)},`)
-    lines.push(`    mode: ${quote(event.mode)},`)
-    lines.push(`    signature: ${quote(event.signature)},`)
-    lines.push(`    jsDoc: ${quote(event.jsDoc)},`)
-    lines.push(`    summary: ${quote(firstSentence(event.doc))},`)
-    lines.push('  },')
-  }
-  lines.push(
-    ']',
-    '',
-    '/** Shapes of every exported type the SERVICE_API signatures reference (transitively), sorted by name. */',
-    'export const TYPE_API: readonly TypeApiEntry[] = [',
-  )
-  for (const type of types) {
-    lines.push('  {')
-    lines.push(`    name: ${quote(type.name)},`)
-    lines.push(`    declaration: ${quote(type.declaration)},`)
-    lines.push('  },')
-  }
-  lines.push(
-    ']',
-    '',
-    '/** The inherited `ctx` surface (cordis core + loader/hmr/timer), in curated order. */',
-    'export const INHERITED_CTX_API: readonly InheritedApiEntry[] = [',
-  )
-  for (const inherited of INHERITED_SERVICES) {
-    lines.push(`  { name: ${quote(inherited.name)}, summary: ${quote(inherited.summary)} },`)
-  }
-  lines.push(']', '')
-  return lines.join('\n')
-}
-
-/** CLI entry: default writes the artifact, `--check` fails if the committed
- * copy is stale. Guarded behind an entry-point check so importing this module
- * for tests neither regenerates the committed file nor calls process.exit. */
-function main(): void {
-  const content = render()
-  if (process.argv.includes('--check')) {
-    let committed: string | null = null
-    try {
-      committed = readFileSync(resolve(root, OUT), 'utf8')
-    } catch {
-      // Only ENOENT (not yet generated) is expected; a present-but-unreadable
-      // file is not a state this repo produces. Either way the remedy is the
-      // same — regenerate — so treat a read failure as "stale".
-      committed = null
-    }
-    if (committed === content) {
-      console.log(`gen-cordis-api: ${OUT} is up to date.`)
-      process.exit(0)
-    }
-    console.error(`gen-cordis-api: ${OUT} is stale. Run \`pnpm run gen-cordis-api\` and commit ${OUT}.`)
-    process.exit(1)
-  }
-
-  writeFileSync(resolve(root, OUT), content)
-  console.log(`gen-cordis-api: wrote ${OUT}.`)
-}
-
-// Run only when invoked as a script, not when imported by a test.
-if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
-  main()
-}
+main()

scripts/gen-cordis-catalog.ts

@@ -1,32 +1,25 @@
 /**
- * Generate the Cordis event and service catalogs from static declarations.
- * The walk enforces event modes, JSDoc parameter/return completeness, and
- * signature type-link coverage; inherited Cordis services come from the
- * curated table below. `--check` verifies both committed artifacts.
+ * Generate committed Cordis artifacts from the Typert catalog projector and
+ * the independent vendored-core projector.
  */
 
-import { globSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, resolve, sep } from 'node:path'
-import ts from 'typescript'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import {
+  projectCordisCatalog,
+  renderEvents,
+  renderServices,
+} from '@deepseek-ai/dsh-typert-generator'
+import type { CordisCatalogPolicy } from '@deepseek-ai/dsh-typert-generator'
 import { renderCordisCoreApiPages } from './cordis-core-api.ts'
-import { checkParams, checkReturns, parseJsDoc, parseTags, pointer, rawJsDoc, reportViolations, type Mode } from './jsdoc.ts'
-import { cordisModuleBody, eventMembers, serviceClasses } from './cordis-walk.ts'
 
 const root = resolve(import.meta.dirname, '..')
 const OUT_EVENTS = 'docs/cordis-catalog/events.md'
 const OUT_SERVICES = 'docs/cordis-catalog/services.md'
+const OUT_RUNTIME_API = 'packages/cordis/tool-cordis/src/api-catalog.ts'
 
-/** The fenced-block info string for generated signature blocks (skipped by
- * doc-typecheck, since a bare signature fragment is not standalone-compilable). */
-const FENCE = 'ts cordis-catalog'
-
-/**
- * One primary core-data-structures page per project type used by a generated
- * signature. This stays curated because union names intentionally do not
- * reuse the type-equivalence manifest's map-symbol entries and some symbols
- * appear on more than one page.
- */
-export const LINK_MAP: Record<string, string> = {
+/** One primary core-data-structures page per project type used by a generated signature. */
+export const LINK_MAP: Readonly<Record<string, string>> = {
   Agent: 'core.md',
   AgentCancelCause: 'core.md',
   AgentOptions: 'core.md',
@@ -51,8 +44,8 @@ export const LINK_MAP: Record<string, string> = {
   MessageSource: 'core.md',
   UserMessage: 'session.md',
   PromptDecision: 'core.md',
-  RequestErrorAction: 'core.md',
   RequestError: 'core.md',
+  RequestErrorAction: 'core.md',
   PreparedReferencedMessage: 'session-reference.md',
   SessionReferenceCandidate: 'session-reference.md',
   SessionReferenceInput: 'session-reference.md',
@@ -206,12 +199,13 @@ export const LINK_MAP: Record<string, string> = {
   WorkflowStartRequest: 'workflow.md',
 }
 
-/** TypeScript lib and pinned framework types that have no repository-owned data page. */
-const FOUNDATION_TYPE_NAMES = new Set([
+/** TypeScript lib and pinned framework types with no repository-owned data page. */
+export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
   'AbortSignal',
   'AsyncIterable',
   'Context',
   'Error',
+  'Map',
   'Partial',
   'Pick',
   'Promise',
@@ -219,7 +213,7 @@ const FOUNDATION_TYPE_NAMES = new Set([
 ])
 
 /** Project types deliberately documented outside the core-data catalog. */
-const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
+export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   AgentFactory: 'agent creation seam is owned by packages/core/agent/README.md',
   BeginCommandRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
   InsertReferenceRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
@@ -244,6 +238,14 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   ProjectionSnapshot: 'watermark snapshot shape is owned by packages/session-projection/session-projection/src/index.ts',
   ProjectionCheckpoint: 'persisted checkpoint row map is owned by packages/session-projection/session-projection/src/index.ts',
   CommandExecution: 'executor return contract is owned by packages/ui/commands/src/index.ts',
+  TypertContribution: 'registry contribution contract is owned by packages/typert/registry/README.md',
+  TypertFace: 'registry face identity is owned by packages/typert/registry/README.md',
+  TypertPackageFilter: 'registry package query filter is owned by packages/typert/registry/README.md',
+  TypertPackageRecord: 'registry package record is owned by packages/typert/registry/README.md',
+  TypertSchemaFilter: 'registry schema query filter is owned by packages/typert/registry/README.md',
+  TypertSchemaRecord: 'registry schema record is owned by packages/typert/registry/README.md',
+  'z.core.JSONSchema.BaseSchema': 'zod projection output is owned by the zod v4 API',
+  'z.core.ToJSONSchemaParams': 'zod projection parameters are owned by the zod v4 API',
   InvariantInstaller: 'service-local contribution contract is owned by packages/support/invariants/README.md',
   LocaleDict: 'service-local dictionary shape is owned by packages/client/i18n/src/index.ts',
   WebBootGraph: 'web boot graph wire shape is owned by packages/client/modules/src/client/index.ts',
@@ -270,401 +272,51 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   WorkspaceId: 'branded id is owned by packages/workspace/workspace/README.md',
 }
 
-/** Collect named references from parameter, generic-constraint/default, and return types. */
-function signatureTypeNames(member: ts.MethodSignature | ts.MethodDeclaration, sf: ts.SourceFile): string[] {
-  const declared = new Set(member.typeParameters?.map(parameter => parameter.name.text) ?? [])
-  const referenced = new Set<string>()
-  const visit = (node: ts.Node): void => {
-    if (ts.isTypeReferenceNode(node)) referenced.add(node.typeName.getText(sf))
-    if (ts.isTypeQueryNode(node)) referenced.add(node.exprName.getText(sf))
-    ts.forEachChild(node, visit)
-  }
-  for (const parameter of member.typeParameters ?? []) {
-    if (parameter.constraint) visit(parameter.constraint)
-    if (parameter.default) visit(parameter.default)
-  }
-  for (const parameter of member.parameters) {
-    if (parameter.type) visit(parameter.type)
-  }
-  if (member.type) visit(member.type)
-  return [...referenced].filter(name => !declared.has(name)).sort()
+/** Repository data policy consumed by the Cordis catalog projector. */
+export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
+  linkedTypePages: LINK_MAP,
+  foundationTypeNames: FOUNDATION_TYPE_NAMES,
+  typeLinkExemptions: TYPE_LINK_EXEMPTIONS,
+  inheritedEvents: [
+    { name: 'internal/plugin', summary: 'A plugin fiber was created.', source: 'vendor/cordis/src/events.ts:328' },
+    { name: 'internal/status', summary: 'A fiber changed lifecycle state.', source: 'vendor/cordis/src/events.ts:330' },
+    { name: 'internal/service', summary: 'Interception hook for a service binding (no core producer).', source: 'vendor/cordis/src/events.ts:332' },
+    { name: 'internal/update', summary: 'Waterfall: a fiber config update is being applied.', source: 'vendor/cordis/src/events.ts:334' },
+    { name: 'internal/get', summary: 'Waterfall: a service is being read from the store.', source: 'vendor/cordis/src/events.ts:336' },
+    { name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:338' },
+    { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:340' },
+    { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:342' },
+    { name: 'hmr/change', summary: 'A watched source file changed on disk.', source: 'vendor/hmr/src/index.ts:20' },
+    { name: 'hmr/reload', summary: 'Plugins are being reloaded after a change.', source: 'vendor/hmr/src/index.ts:21' },
+    { name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:23' },
+    { name: 'loader/config-update', summary: 'The loader config tree changed.', source: 'vendor/loader/src/index.ts:24' },
+    { name: 'loader/entry-init', summary: 'A config entry is being initialized.', source: 'vendor/loader/src/index.ts:25' },
+    { name: 'loader/partial-dispose', summary: 'An entry is being partially disposed on reload.', source: 'vendor/loader/src/index.ts:26' },
+    { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:27' },
+  ],
+  inheritedServices: [
+    { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:34' },
+    { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:34' },
+    { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:164' },
+    { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.', source: 'vendor/cordis/src/fiber.ts:9' },
+    { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.', source: 'vendor/cordis/src/reflect.ts:7' },
+    { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).', source: 'vendor/cordis/src/context.ts:42' },
+    { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.', source: 'vendor/cordis/src/context.ts:16' },
+    { name: 'ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick).', source: 'vendor/timer/src/index.ts:4' },
+    { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).', source: 'vendor/loader/src/index.ts:30' },
+    { name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).', source: 'vendor/hmr/src/index.ts:15' },
+  ],
 }
 
-/** Append fail-closed signature type-link violations with actionable ownership choices. */
-function checkTypeLinks(
-  where: string,
-  member: ts.MethodSignature | ts.MethodDeclaration,
-  sf: ts.SourceFile,
-  violations: string[],
-): void {
-  for (const name of signatureTypeNames(member, sf)) {
-    if (Object.hasOwn(LINK_MAP, name)
-      || FOUNDATION_TYPE_NAMES.has(name)
-      || Object.hasOwn(TYPE_LINK_EXEMPTIONS, name)) continue
-    violations.push(
-      `${where} references unclassified type '${name}'. Add it to LINK_MAP with its core-data-structures page, `
-      + 'to FOUNDATION_TYPE_NAMES if TypeScript or Cordis owns it, or to TYPE_LINK_EXEMPTIONS with '
-      + 'the non-catalog documentation owner.',
-    )
-  }
-}
-
-/** Throw one aggregated diagnostic for every unclassified signature type. */
-function reportTypeLinkViolations(gate: string, violations: string[]): void {
-  if (violations.length === 0) return
-  throw new Error(
-    `${gate}: ${violations.length} signature type-link coverage violation(s):\n`
-    + violations.map(violation => `  ${violation}`).join('\n'),
-  )
-}
-
-/** One harness event, extracted from an `interface Events` block. */
-interface EventEntry {
-  /** Scoped name, e.g. `agent/request`. */
-  name: string
-  /** The scope prefix, e.g. `agent` (everything before the first `/`). */
-  scope: string
-  /** Full signature text (the method-signature member, JSDoc stripped). */
-  signature: string
-  /** Original declaration JSDoc, dedented from its containing interface. */
-  jsDoc: string
-  /** Dispatch mode from the `@mode` tag. */
-  mode: Mode
-  /** Description prose (JSDoc minus the `@mode` tag), one line per paragraph. */
-  doc: string
-  /** Source pointer `packages/…/file.ts:line` of the declaration. */
-  source: string
-}
-
-/** One public service method and the source contract attached to it. */
-interface ServiceMethodEntry {
-  /** Public method signature (body stripped). */
-  signature: string
-  /** Original method JSDoc, dedented from its containing class. */
-  jsDoc: string
-}
-
-/** One harness service, extracted from an `interface Context` block. */
-interface ServiceEntry {
-  /** The `ctx.<key>` name, e.g. `llm`. */
-  key: string
-  /** The service class/interface name, e.g. `LlmService`. */
-  type: string
-  /** Whether the service class is abstract (a seam interface). */
-  abstract: boolean
-  /** Class-level JSDoc prose, one line per paragraph. */
-  doc: string
-  /** Public methods (bodies stripped), in source order. */
-  methods: ServiceMethodEntry[]
-  /** Source pointer of the class declaration. */
-  source: string
-}
-
-/** A terse inherited-tier entry (pinned vendor surface). */
-interface InheritedEntry {
-  name: string
-  summary: string
-  /** Source pointer `vendor/…:line`. */
-  source: string
-}
-
-// cordisModuleBody / eventMembers / serviceClasses live in cordis-walk.ts.
-
-/** The signature text of a method-signature member (everything but a body). */
-function memberSignature(member: ts.TypeElement | ts.ClassElement, sf: ts.SourceFile): string {
-  const full = member.getText(sf)
-  const body = (member as { body?: ts.Node }).body
-  const sig = body ? full.slice(0, full.length - body.getText(sf).length) : full
-  return sig.replace(/\s*;?\s*$/, '').replace(/\s+/g, ' ').trim()
-}
-
-/**
- * Copy a node's original JSDoc while removing only the indentation imposed by
- * its containing interface or class.
+/** CLI entry: default writes every artifact; `--check` reports stale files.
+ * @returns nothing; writes files or reports freshness through the process.
  */
-function jsDocText(text: string, sf: ts.SourceFile, node: ts.Node): string {
-  const raw = rawJsDoc(text, node)
-  if (!raw) return ''
-  const start = text.lastIndexOf(raw, node.getStart(sf))
-  const { line } = sf.getLineAndCharacterOfPosition(start)
-  const lineStart = sf.getPositionOfLineAndCharacter(line, 0)
-  const indent = text.slice(lineStart, start)
-  return raw.split('\n')
-    .map((lineText, index) => index > 0 && lineText.startsWith(indent) ? lineText.slice(indent.length) : lineText)
-    .join('\n')
-}
-
-/** Walk every harness `interface Events` block and extract its events, hard-
- * erroring (aggregated) on any JSDoc-completeness violation: a missing/
- * contradicted `@mode`, missing description prose, or an undocumented payload
- * parameter. `scanRoot` defaults to the repo root; tests pass a fixture dir. */
-export function collectEvents(scanRoot: string = root): EventEntry[] {
-  const entries: EventEntry[] = []
-  const violations: string[] = []
-  const typeLinkViolations: string[] = []
-  for (const rel of globSync('packages/*/*/src/*.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
-    const abs = resolve(scanRoot, rel)
-    const text = readFileSync(abs, 'utf8')
-    if (!text.includes('interface Events')) continue
-    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
-    const body = cordisModuleBody(sf)
-    if (!body) continue
-    for (const { name, member } of eventMembers(body, sf)) {
-      const signature = memberSignature(member, sf)
-      const raw = rawJsDoc(text, member)
-      const { doc, mode } = parseJsDoc(raw)
-      const src = pointer(rel, sf, member)
-      const where = `event '${name}' (${src})`
-      checkTypeLinks(where, member, sf, typeLinkViolations)
-      if (!mode) {
-        violations.push(`${where} is missing an @mode tag. Add '@mode emit|waterfall|parallel|serial|bail' to its JSDoc (see AGENTS.md).`)
-      }
-      // Conclusive structural check: a trailing `next: () => …` parameter is a
-      // waterfall. (emit vs parallel vs serial is not structurally
-      // distinguishable, so it is trusted from the tag.)
-      const last = member.parameters.at(-1)
-      const hasNext = !!last && last.name.getText(sf) === 'next'
-      if (mode && hasNext && mode !== 'waterfall') {
-        violations.push(`${where} has a trailing 'next' parameter (structurally a waterfall) but is tagged '@mode ${mode}'. Fix the tag or the signature.`)
-      }
-      if (mode && !hasNext && mode === 'waterfall') {
-        violations.push(`${where} is tagged '@mode waterfall' but has no trailing 'next' parameter. A waterfall delegates via next().`)
-      }
-      if (!doc) violations.push(`${where} has no description prose. Say what happened / what a listener may do, above the block tags.`)
-      // Payload parameters need a non-empty @param. The `this` receiver is not
-      // payload, and a waterfall's trailing `next` is covered by its mode.
-      const { params } = parseTags(raw)
-      checkParams(where, 'event', member.parameters, params, sf,
-        p => (ts.isIdentifier(p.name) && p.name.text === 'this') || (hasNext && p === last), violations)
-      if (mode) entries.push({ name, scope: name.split('/')[0] ?? name, signature, jsDoc: jsDocText(text, sf, member), mode, doc, source: src })
-    }
-  }
-  reportViolations('gen-cordis-catalog', violations)
-  reportTypeLinkViolations('gen-cordis-catalog', typeLinkViolations)
-  return entries
-}
-
-/** Walk every harness `interface Context` block + its service class, hard-
- * erroring (aggregated) on any JSDoc-completeness violation: a class or public
- * method without JSDoc prose, an undocumented parameter, a stale `@param`, a
- * missing `@returns` on a non-void method, or an inferred (unannotated) return
- * type the pure-AST walk cannot classify.
- * `scanRoot` defaults to the repo root; tests pass a fixture dir. */
-export function collectServices(scanRoot: string = root): ServiceEntry[] {
-  const entries: ServiceEntry[] = []
-  const violations: string[] = []
-  const typeLinkViolations: string[] = []
-  for (const rel of globSync('packages/*/*/src/index.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
-    const abs = resolve(scanRoot, rel)
-    const text = readFileSync(abs, 'utf8')
-    if (!text.includes('interface Context')) continue
-    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
-    const body = cordisModuleBody(sf)
-    if (!body) continue
-    // Resolve each ctx key to its service class (shared walk) and emit an entry.
-    for (const { key, type, cls, abstract, doc: clsDoc } of serviceClasses(body, sf, rel, violations)) {
-      const methods: ServiceMethodEntry[] = []
-      for (const member of cls.members) {
-        if (!ts.isMethodDeclaration(member)) continue
-        // Only instance methods callable through `ctx.<key>` are surface;
-        // private, protected, and static methods are not.
-        const nonPublic = member.modifiers?.some(m =>
-          m.kind === ts.SyntaxKind.PrivateKeyword
-          || m.kind === ts.SyntaxKind.ProtectedKeyword
-          || m.kind === ts.SyntaxKind.StaticKeyword)
-          || ts.isPrivateIdentifier(member.name)
-        if (nonPublic) continue
-        const memberName = member.name.getText(sf)
-        if (memberName.startsWith('[')) continue // computed/symbol members
-        const where = `service method ctx.${key}.${memberName} (${pointer(rel, sf, member)})`
-        checkTypeLinks(where, member, sf, typeLinkViolations)
-        const raw = rawJsDoc(text, member)
-        methods.push({ signature: memberSignature(member, sf), jsDoc: jsDocText(text, sf, member) })
-        if (!raw) { violations.push(`${where} has no JSDoc.`); continue }
-        if (!parseJsDoc(raw).doc) violations.push(`${where} has no description prose above its block tags.`)
-        const { params, returns } = parseTags(raw)
-        // Every parameter needs a non-empty @param (`this` receiver exempt),
-        // and a non-void ANNOTATED result needs a non-empty @returns — the
-        // shared checkers carry the exact contract.
-        checkParams(where, 'service', member.parameters, params, sf,
-          p => ts.isIdentifier(p.name) && p.name.text === 'this', violations)
-        checkReturns(where, member.type, returns, sf, violations)
-      }
-      entries.push({
-        key,
-        type,
-        abstract,
-        doc: clsDoc,
-        methods,
-        source: pointer(rel, sf, cls),
-      })
-    }
-  }
-  reportViolations('gen-cordis-catalog', violations)
-  reportTypeLinkViolations('gen-cordis-catalog', typeLinkViolations)
-  return entries.sort((a, b) => a.key.localeCompare(b.key))
-}
-
-/**
- * The inherited tier — cordis core + loader/hmr/timer. Curated, terse, and
- * hand-summarized because (a) it is pinned vendor source that changes only on a
- * deliberate vendor sync, (b) the cordis-core `Context` mixes true ctx members
- * with non-service fields (`root`, `baseUrl`, `logger`) that a blind walk would
- * wrongly surface as services, and (c) the internal/* events carry no JSDoc to
- * render. Source pointers are verified against vendor by `verify-md-links`'
- * sibling check is N/A; keep them current on a vendor bump.
- */
-const INHERITED_EVENTS: InheritedEntry[] = [
-  { name: 'internal/plugin', summary: 'A plugin fiber was created.', source: 'vendor/cordis/src/events.ts:328' },
-  { name: 'internal/status', summary: 'A fiber changed lifecycle state.', source: 'vendor/cordis/src/events.ts:330' },
-  { name: 'internal/service', summary: 'Interception hook for a service binding (no core producer).', source: 'vendor/cordis/src/events.ts:332' },
-  { name: 'internal/update', summary: 'Waterfall: a fiber config update is being applied.', source: 'vendor/cordis/src/events.ts:334' },
-  { name: 'internal/get', summary: 'Waterfall: a service is being read from the store.', source: 'vendor/cordis/src/events.ts:336' },
-  { name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:338' },
-  { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:340' },
-  { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:342' },
-  { name: 'hmr/change', summary: 'A watched source file changed on disk.', source: 'vendor/hmr/src/index.ts:20' },
-  { name: 'hmr/reload', summary: 'Plugins are being reloaded after a change.', source: 'vendor/hmr/src/index.ts:21' },
-  { name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:23' },
-  { name: 'loader/config-update', summary: 'The loader config tree changed.', source: 'vendor/loader/src/index.ts:24' },
-  { name: 'loader/entry-init', summary: 'A config entry is being initialized.', source: 'vendor/loader/src/index.ts:25' },
-  { name: 'loader/partial-dispose', summary: 'An entry is being partially disposed on reload.', source: 'vendor/loader/src/index.ts:26' },
-  { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:27' },
-]
-
-export const INHERITED_SERVICES: InheritedEntry[] = [
-  { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:34' },
-  { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:34' },
-  { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:164' },
-  { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.', source: 'vendor/cordis/src/fiber.ts:9' },
-  { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.', source: 'vendor/cordis/src/reflect.ts:7' },
-  { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).', source: 'vendor/cordis/src/context.ts:42' },
-  { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.', source: 'vendor/cordis/src/context.ts:16' },
-  { name: 'ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick).', source: 'vendor/timer/src/index.ts:4' },
-  { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).', source: 'vendor/loader/src/index.ts:30' },
-  { name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).', source: 'vendor/hmr/src/index.ts:15' },
-]
-
-/** Render the cross-link "Types:" line for a signature, or '' if none apply. */
-function typeLinks(signature: string): string {
-  const seen = new Set<string>()
-  for (const name of Object.keys(LINK_MAP)) {
-    if (new RegExp(`\\b${name}\\b`).test(signature)) seen.add(name)
-  }
-  if (seen.size === 0) return ''
-  const links = [...seen].sort().map(n => `[${n}](../core-data-structures/${LINK_MAP[n]})`)
-  return `Types: ${links.join(' · ')}`
-}
-
-/** Render one harness event entry. */
-function renderEvent(e: EventEntry): string[] {
-  const out = [`### \`${e.name}\` — ${e.mode}`, '']
-  if (e.doc) out.push(e.doc, '')
-  out.push('```' + FENCE, e.jsDoc, e.signature, '```', '')
-  const links = typeLinks(e.signature)
-  if (links) out.push(links, '')
-  out.push(`Source: [\`${e.source}\`](../../${e.source.split(':')[0]})`, '')
-  return out
-}
-
-/** Render one harness service entry. */
-function renderService(s: ServiceEntry): string[] {
-  const kind = s.abstract ? ' (abstract seam)' : ''
-  const out = [`## \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
-  if (s.doc) out.push(s.doc, '')
-  if (s.methods.length) {
-    const declarations = s.methods.flatMap((method, index) => [
-      ...(index > 0 ? [''] : []),
-      method.jsDoc,
-      method.signature,
-    ])
-    out.push('```' + FENCE, ...declarations, '```', '')
-    const links = typeLinks(s.methods.map(method => method.signature).join('\n'))
-    if (links) out.push(links, '')
-  }
-  out.push(`Source: [\`${s.source}\`](../../${s.source.split(':')[0]})`, '')
-  return out
-}
-
-/** The shared generated-file banner comment. */
-const BANNER = [
-  '<!-- Generated by scripts/gen-cordis-catalog.ts — do not edit by hand.',
-  '     Run `pnpm run gen-cordis-catalog` to regenerate. -->',
-  '',
-]
-
-/** The shared GENERATED + freshness-gate + fence notice paragraph. */
-const GATE_NOTICE = 'This file is GENERATED from source (`scripts/gen-cordis-catalog.ts`) and verified fresh by `pnpm run verify-cordis-catalog` (part of `doc-sync`) — do not edit it by hand. Signature blocks use a `ts cordis-catalog` fence and include the original source JSDoc immediately before each event or service method. doc-typecheck skips these bare declaration fragments; type names in a signature link to the page that documents them.'
-
-/** Render the events catalog (pure, deterministic given sorted inputs). */
-export function renderEvents(events: EventEntry[]): string {
-  const lines: string[] = [
-    ...BANNER,
-    '# Cordis Events Catalog',
-    '',
-    'Every cordis event a plugin can listen to: exact signature, dispatch mode, and original declaration JSDoc. This is one axis of the **wiring** reference a plugin author works against — the callable `ctx.<key>` surface is the sibling [services catalog](services.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around.',
-    '',
-    GATE_NOTICE,
-    '',
-    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns, grouped by scope. The **inherited tier** at the end is the cordis-core + loader/hmr/timer event surface a plugin also sees — pinned vendor source, summarized tersely. The event-dispatch methods themselves are generated in the [Cordis core Events API](core/events.md).',
-    '',
-    'Dispatch modes: **emit** (fire-and-forget), **waterfall** (each listener gets `next()` and may transform or veto — see [waterfall semantics](../cordis-primer.md#cordis-waterfall-semantics)), **parallel** (awaited fan-out; all listeners run), **serial** (awaited in registration order until one returns a bail value — anything other than `null`, `false`, or `undefined`), **bail** (synchronous in-order dispatch until one listener returns a bail value; the scoped input-mutation events use it for an applied/not-applied answer).',
-    '',
-  ]
-  const scopes = [...new Set(events.map(e => e.scope))].sort()
-  for (const scope of scopes) {
-    lines.push(`## \`${scope}/*\``, '')
-    for (const e of events.filter(x => x.scope === scope).sort((a, b) => a.name.localeCompare(b.name))) {
-      lines.push(...renderEvent(e))
-    }
-  }
-  lines.push(
-    '## Inherited events (cordis core + loader/hmr/timer)',
-    '',
-    'The framework events every plugin also sees, beyond the harness vocabulary above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of the event bus, without elevating framework internals to the harness tier\'s prominence.',
-    '',
-  )
-  for (const e of INHERITED_EVENTS) {
-    lines.push(`- \`${e.name}\` — ${e.summary} ([\`${e.source}\`](../../${e.source.split(':')[0]}))`)
-  }
-  lines.push('')
-  return lines.join('\n')
-}
-
-/** Render the services catalog (pure, deterministic given sorted inputs). */
-export function renderServices(services: ServiceEntry[]): string {
-  const lines: string[] = [
-    ...BANNER,
-    '# Cordis Services Catalog',
-    '',
-    'Every `ctx.<key>` service a plugin can call: the exact public interface with original method JSDoc, plus the class JSDoc. This is one axis of the **wiring** reference a plugin author works against — the events a plugin listens to are the sibling [events catalog](events.md), and [core-data-structures/](../core-data-structures/core.md) catalogs the *data structures* these signatures move around. An abstract seam (e.g. `ctx.bash`) is implemented by a separate package; the interface is what consumers code against.',
-    '',
-    GATE_NOTICE,
-    '',
-    'The **harness tier** below (the `@deepseek-ai/dsh-*` packages) is the vocabulary this repo owns. The **inherited tier** at the end is the cordis-core + loader/hmr/timer `ctx` surface a plugin also sees — pinned vendor source, summarized tersely. Detailed Context, Fiber, Registry, and Service APIs are generated in the [Cordis core API](core/context.md).',
-    '',
-  ]
-  for (const s of services) lines.push(...renderService(s))
-  lines.push(
-    '## Inherited `ctx` members (cordis core + loader/hmr/timer)',
-    '',
-    'The framework `ctx` surface every plugin also sees, beyond the harness services above. This is pinned vendor source ([vendoring policy](../../vendor/README.md)); it is summarized here so the page is a complete picture of what `ctx` offers, without elevating framework internals to the harness tier\'s prominence.',
-    '',
-  )
-  for (const s of INHERITED_SERVICES) {
-    lines.push(`- \`${s.name}\` — ${s.summary} ([\`${s.source}\`](../../${s.source.split(':')[0]}))`)
-  }
-  lines.push('')
-  return lines.join('\n')
-}
-
-/** CLI entry: `--write` (default) writes both catalogs, `--check` fails if
- * either is stale. Guarded behind an entry-point check so importing this module
- * for tests neither regenerates the committed files nor calls process.exit. */
-function main(): void {
+export function main(): void {
+  const { projector, model } = projectCordisCatalog(root, CORDIS_CATALOG_POLICY)
   const outputs: [string, string][] = [
-    [OUT_EVENTS, renderEvents(collectEvents())],
-    [OUT_SERVICES, renderServices(collectServices())],
+    [OUT_EVENTS, renderEvents([...model.events], CORDIS_CATALOG_POLICY)],
+    [OUT_SERVICES, renderServices([...model.services], CORDIS_CATALOG_POLICY)],
+    [OUT_RUNTIME_API, projector.renderRuntimeApi(model)],
     ...renderCordisCoreApiPages(),
   ]
   if (process.argv.includes('--check')) {
@@ -674,9 +326,7 @@ function main(): void {
       try {
         committed = readFileSync(resolve(root, out), 'utf8')
       } catch {
-        // Only ENOENT (not yet generated) is expected; a present-but-unreadable
-        // file is not a state this repo produces. Either way the remedy is the
-        // same — regenerate — so treat a read failure as "stale".
+        // Only ENOENT is expected; either read failure has the same remedy.
         committed = null
       }
       if (committed !== content) stale.push(out)
@@ -697,7 +347,4 @@ function main(): void {
   console.log(`gen-cordis-catalog: wrote ${outputs.length} generated file(s).`)
 }
 
-// Run only when invoked as a script, not when imported by a test.
-if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
-  main()
-}
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) main()

scripts/gen-doc-graphs.ts

@@ -8,7 +8,9 @@
 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'
+import { projectCordisCatalog } from '@deepseek-ai/dsh-typert-generator'
+import { CORDIS_CATALOG_POLICY } from './gen-cordis-catalog.ts'
+import type { EventEntry, ServiceEntry } from '@deepseek-ai/dsh-typert-generator'
 import {
   collectPackageGraph,
   escapeMermaidLabel as escLabel,
@@ -58,6 +60,7 @@ const GROUP_ORDER = [
   'util',
   'llm',
   'core',
+  'typert',
   'goal',
   'process',
   'bash',
@@ -128,6 +131,14 @@ const SERVICE_ROLES: ServiceRole[] = [
     consumers: ['session', 'agent', 'scope', 'agent-loop'],
     note: 'Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures.',
   },
+  {
+    key: 'typert',
+    pkg: 'typert-registry',
+    title: 'Runtime type registry',
+    mode: 'core',
+    consumers: ['typert-loader'],
+    note: 'Plugins register live zod contributions directly or through dsh-typert-loader; runtime consumers query schemas and reflection metadata at their own edges.',
+  },
   {
     key: 'sessionPersistence',
     pkg: 'session-persistence',
@@ -507,8 +518,8 @@ function tableCell(value: string): string {
   return value.replace(/\|/g, '\\|').replace(/\n/g, '<br>')
 }
 
-function assertServiceRolesComplete(): void {
-  const discovered = new Set(collectServices().map(service => service.key))
+function assertServiceRolesComplete(services: readonly ServiceEntry[]): void {
+  const discovered = new Set(services.map(service => service.key))
   const classified = new Set(SERVICE_ROLES.map(role => role.key))
   const missing = [...discovered].filter(key => !classified.has(key)).sort()
   const stale = [...classified].filter(key => !discovered.has(key)).sort()
@@ -520,8 +531,8 @@ function assertServiceRolesComplete(): void {
   }
 }
 
-function renderCapabilitySeams(pkgs: Pkg[]): string {
-  assertServiceRolesComplete()
+function renderCapabilitySeams(pkgs: Pkg[], services: readonly ServiceEntry[]): string {
+  assertServiceRolesComplete(services)
   const pkgsByShort = new Map(pkgs.map(pkg => [pkg.short, pkg]))
   const maintenance = 'hybrid: services are discovered from Cordis declarations; interface/implementation/consumer roles are classified in `scripts/gen-doc-graphs.ts` with a completeness guard'
   const nodes = new Map<string, string>()
@@ -970,8 +981,7 @@ function listenerPackages(listeners: Set<string>, pkgsByShort: Map<string, Pkg>)
   return [...listeners].sort().map(pkg => pkgLink(pkgsByShort.get(pkg), pkg)).join(', ')
 }
 
-function renderEventRelations(pkgs: Pkg[]): string {
-  const events = collectEvents()
+function renderEventRelations(pkgs: Pkg[], events: readonly EventEntry[]): string {
   const relations = collectEventRelations()
   const pkgsByShort = new Map(pkgs.map(pkg => [pkg.short, pkg]))
   const maintenance = 'generated: Cordis event declarations and producer/listener edges are resolved from the repository TypeScript Program'
@@ -1160,10 +1170,11 @@ function renderToolPipeline(): string {
 
 function renderDocs(): GraphDoc[] {
   const pkgs = collectPackageGraph(root, GROUP_ORDER, 'gen-doc-graphs')
+  const { model } = projectCordisCatalog(root, CORDIS_CATALOG_POLICY)
   const docs: GraphDoc[] = [
-    { rel: 'docs/capability-seams.md', content: renderCapabilitySeams(pkgs) },
+    { rel: 'docs/capability-seams.md', content: renderCapabilitySeams(pkgs, model.services) },
     ...APP_EXAMPLES.map(example => ({ rel: example.rel, content: renderAppComposition(example) })),
-    { rel: 'docs/event-producer-consumer.md', content: renderEventRelations(pkgs) },
+    { rel: 'docs/event-producer-consumer.md', content: renderEventRelations(pkgs, model.events) },
     { rel: 'docs/agent-lifecycle.md', content: renderLifecycle() },
     { rel: 'docs/tool-execution-pipeline.md', content: renderToolPipeline() },
   ]

scripts/run-gates.ts

@@ -490,7 +490,6 @@ function docSyncLeafGates(options: {
   return [
     pnpmScript('doc-typecheck', 'doc-typecheck', docTypecheckOptions),
     pnpmScript('cordis-catalog', 'verify-cordis-catalog', { label: 'cordis catalog' }),
-    pnpmScript('cordis-api', 'verify-cordis-api', { label: 'cordis api' }),
     pnpmScript('export-jsdoc', 'verify-export-jsdoc', { label: 'export jsdoc' }),
     pnpmScript('tool-catalog', 'verify-tool-catalog', { label: 'tool catalog' }),
     pnpmScript('config-catalog', 'verify-config-catalog', { label: 'config catalog' }),