Merge remote-tracking branch 'origin/master' into codex/pr370-review-20260719

2026-07-19 21:21:53 +08:00
parent fe5c3e2a7a f84092045c
commit 2bc4791f84
633 changed files with 28132 additions and 6472 deletions
--- a/scripts/demo-code-mode.mjs
+++ b/scripts/demo-code-mode.mjs
@@ -1,7 +1,7 @@
 /**
- * Boot the REPL or ACP Code Mode overlay, defaulting to REPL. Each overlay
+ * Boot the REPL, TUI, or ACP Code Mode overlay, defaulting to REPL. Each overlay
 * includes its base example, selects Code Mode, and adds the worker runtime.
- * Both require a DeepSeek API key; unsupported arguments fail with usage.
+ * All require a DeepSeek API key; unsupported arguments fail with usage.
 */
 import { spawn } from 'node:child_process'

@@ -9,14 +9,15 @@ import { spawn } from 'node:child_process'
 // the overlay config (the stdio bin keeps --expose-internals for the cordis
 // Loader's HMR path).
 const UIS = new Map([
-  ['repl', ['--expose-internals', '--import', 'tsx', 'packages/examples/stdio-demo/src/bin.ts', 'examples/coding-agent/code-mode.cordis.yml']],
+  ['repl', ['--expose-internals', '--import', 'tsx', 'packages/examples/stdio-demo/src/bin.ts', 'examples/repl-agent/code-mode.cordis.yml']],
+  ['tui', ['--expose-internals', '--import', 'tsx', 'packages/examples/stdio-demo/src/bin.ts', 'examples/tui-agent/code-mode.cordis.yml']],
  ['acp', ['--import', 'tsx', 'packages/examples/acp-demo/src/bin.ts', '--config', 'examples/acp-agent/code-mode.cordis.yml']],
 ])

 const ui = process.argv[2] ?? 'repl'
 const args = UIS.get(ui)
 if (!args || process.argv.length > 3) {
-  console.error('usage: pnpm run demo:code-mode [repl|acp]')
+  console.error('usage: pnpm run demo:code-mode [repl|tui|acp]')
  process.exit(2)
 }

--- a/scripts/doc-budgets.manifest.json
+++ b/scripts/doc-budgets.manifest.json
@@ -1,11 +1,11 @@
 {
-  "AGENTS.md": 1500,
-  "docs/AGENTS.md": 1100,
+  "AGENTS.md": 1600,
+  "docs/AGENTS.md": 1150,
  "docs/architecture.md": 1790,
  "docs/cordis-primer.md": 600,
  "docs/defensive-patterns.md": 550,
  "docs/testing.md": 960,
  "examples/AGENTS.md": 310,
-  "packages/AGENTS.md": 290,
+  "packages/AGENTS.md": 650,
  "packages/README.md": 760
 }
--- a/scripts/doc-typecheck.ts
+++ b/scripts/doc-typecheck.ts
@@ -1,6 +1,6 @@
 /**
 * Typecheck Markdown `ts` fences against the workspace API. `ignore-check` fences are reported as
- * opt-outs; generated catalog fragments and `type-equiv` blocks are skipped here because their
+ * opt-outs; generated catalog fragments and source-equivalence blocks are skipped here because their
 * owning gates verify them. A build-coordinated mode consumes existing declarations without emit.
 */

@@ -33,6 +33,7 @@ const KIND_BY_INFO: Record<string, BlockKind> = {
  'ts': 'check',
  'ts ignore-check': 'ignore',
  'ts type-equiv': 'type-equiv',
+  'ts public-api': 'type-equiv',
  'ts cordis-catalog': 'cordis-catalog',
  'ts persistence-catalog': 'persistence-catalog',
  'ts config-catalog': 'config-catalog',
--- a/scripts/gen-cordis-api.ts
+++ b/scripts/gen-cordis-api.ts
@@ -1,8 +1,9 @@
 /**
 * Generate the model-facing Cordis API data module from the same event/service
- * collector as the documentation catalogs. It emits first-sentence docs, raw
- * signatures, transitive public type shapes, and inherited context entries,
- * without source pointers; output is deterministic and `--check` verifies it.
+ * 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.
 */

 import { globSync, readFileSync, writeFileSync } from 'node:fs'
@@ -80,7 +81,7 @@ function referencedTypes(seeds: string[], decls: Map<string, string>): { name: s
 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), collectTypeDecls())
+  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',
@@ -88,22 +89,30 @@ function render(): string {
    ' * `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), harness',
-    ' * events (mode + signature), and the inherited `ctx` surface. Produced by',
+    ' * 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 harness `ctx.<key>` service: its one-line summary and public method signatures. */',
+    '/** 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 method signatures, bodies stripped, in source order. */',
-    '  methods: readonly string[]',
+    '  /** Public methods, bodies stripped, in source order. */',
+    '  methods: readonly ServiceApiMethod[]',
    '}',
    '',
    '/** One harness event: its dispatch mode, exact signature, and one-line summary. */',
@@ -114,6 +123,8 @@ function render(): string {
    '  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',
    '}',
@@ -145,7 +156,12 @@ function render(): string {
      lines.push('    methods: [],')
    } else {
      lines.push('    methods: [')
-      for (const method of service.methods) lines.push(`      ${quote(method)},`)
+      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('  },')
@@ -161,6 +177,7 @@ function render(): string {
    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('  },')
  }
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -1,8 +1,8 @@
 /**
 * Generate the Cordis event and service catalogs from static declarations.
- * The walk enforces event modes plus JSDoc parameter/return completeness;
- * inherited Cordis services come from the curated table below. `--check`
- * verifies both committed artifacts.
+ * 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.
 */

 import { globSync, readFileSync, writeFileSync } from 'node:fs'
@@ -20,47 +20,199 @@ const OUT_SERVICES = 'docs/cordis-catalog/services.md'
 const FENCE = 'ts cordis-catalog'

 /**
- * One primary core-data-structures page per signature type, shared by the
- * Cordis and config catalogs; union names intentionally do not reuse the
- * type-equivalence manifest's map-symbol entries.
+ * 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.
 */
-// TODO(catalog-type-links): verify or generate link-map coverage.
 export const LINK_MAP: Record<string, string> = {
  Agent: 'core.md',
+  AgentOptions: 'core.md',
+  AgentStatus: 'core.md',
  ContentBlock: 'core.md',
-  Message: 'core.md',
-  MessageSource: 'core.md',
+  ContinuationDecision: 'core.md',
+  ContinuationStop: 'core.md',
  GenerateOptions: 'core.md',
  LlmCallConfig: 'core.md',
+  LlmModelInfo: 'core.md',
+  LlmProviderInfo: 'core.md',
+  Message: 'core.md',
+  MessageSource: 'core.md',
+  PromptDecision: 'core.md',
+  RequestError: 'core.md',
+  RequestErrorDecision: 'core.md',
  SessionEvent: 'core.md',
+  SessionId: 'core.md',
  SessionStartSource: 'core.md',
-  StreamChunk: 'llm-streaming.md',
-  TurnEndReason: 'session.md',
-  ToolDefinition: 'tools.md',
-  ToolExecution: 'tools.md',
-  ToolExecutionInput: 'tools.md',
-  ToolExecutionResult: 'tools.md',
-  ToolExecutionToken: 'tools.md',
  ApprovalOutcome: 'approval.md',
  ApprovalPolicy: 'approval.md',
  ApprovalRequest: 'approval.md',
+  ApprovalService: 'approval.md',
  BashExecRequest: 'bash.md',
  BashExecSpec: 'bash.md',
+  BashProcess: 'bash.md',
  BashRunResult: 'bash.md',
-  ConfinedArgv: 'sandbox.md',
-  SandboxMode: 'sandbox.md',
-  SandboxPolicy: 'sandbox.md',
+  DshEnvironment: 'bash.md',
  CodeRunRequest: 'code-runtime.md',
  CodeRunResult: 'code-runtime.md',
+  CompactionResult: 'compaction.md',
+  CompactionTrigger: 'compaction.md',
+  FileReadOutcome: 'filesystem.md',
+  FsDirEntry: 'filesystem.md',
  FsEditOutcome: 'filesystem.md',
  FsEditRequest: 'filesystem.md',
  FsInfo: 'filesystem.md',
+  FsPathInfo: 'filesystem.md',
+  FsPolicyExec: 'filesystem.md',
  FsTarget: 'filesystem.md',
  FsVersion: 'filesystem.md',
  FsWriteIntent: 'filesystem.md',
  FsWriteOutcome: 'filesystem.md',
-  FsPolicyExec: 'filesystem.md',
-  FileReadOutcome: 'filesystem.md',
+  LlmAdapter: 'llm-streaming.md',
+  LlmService: 'llm-streaming.md',
+  StreamChunk: 'llm-streaming.md',
+  CreateSessionOptions: 'persistence.md',
+  SessionHeader: 'persistence.md',
+  SessionLocation: 'persistence.md',
+  ConfinedArgv: 'sandbox.md',
+  SandboxMode: 'sandbox.md',
+  SandboxPolicy: 'sandbox.md',
+  ScopeKey: 'scope.md',
+  Scoped: 'scope.md',
+  EpochHeader: 'session.md',
+  Session: 'session.md',
+  TurnEndReason: 'session.md',
+  SessionEventReadRequest: 'session-query.md',
+  SessionEventRecord: 'session-query.md',
+  SessionEventTrace: 'session-query.md',
+  SessionEventTraceRequest: 'session-query.md',
+  SessionEventWindow: 'session-query.md',
+  SessionLineageTrace: 'session-query.md',
+  SessionRecord: 'session-query.md',
+  SkillDefinition: 'skills.md',
+  SkillLookupOptions: 'skills.md',
+  SkillProvider: 'skills.md',
+  SkillRegistration: 'skills.md',
+  SkillSummary: 'skills.md',
+  SaveTextSpill: 'spill.md',
+  SpillRef: 'spill.md',
+  SubagentProvider: 'subagent.md',
+  SubagentRun: 'subagent.md',
+  SubagentService: 'subagent.md',
+  SubagentStartRequest: 'subagent.md',
+  AssembleContext: 'system-prompt.md',
+  PromptSection: 'system-prompt.md',
+  SystemPrompt: 'system-prompt.md',
+  ToolProviderResult: 'system-prompt.md',
+  TaskDoneListener: 'tasks.md',
+  TaskId: 'tasks.md',
+  TaskRead: 'tasks.md',
+  TaskSnapshot: 'tasks.md',
+  TaskStart: 'tasks.md',
+  TokenMeasurement: 'token-meter.md',
+  PostToolDecision: 'tools.md',
+  PreToolDecision: 'tools.md',
+  ToolDefinition: 'tools.md',
+  ToolExecution: 'tools.md',
+  ToolExecutionInput: 'tools.md',
+  ToolExecutionMode: 'tools.md',
+  ToolExecutionResult: 'tools.md',
+  ToolExecutionToken: 'tools.md',
+  ToolGuard: 'tools.md',
+  ToolRegistry: 'tools.md',
+  ToolRestriction: 'tools.md',
+  ToolSchema: 'tools.md',
+  AskUserQuestionAnswer: 'user-interaction.md',
+  AskUserQuestionRequest: 'user-interaction.md',
+  UserInteractionProvider: 'user-interaction.md',
+  WebFetchProvider: 'web.md',
+  WebFetchRequest: 'web.md',
+  WebFetchResult: 'web.md',
+  WebSearchProvider: 'web.md',
+  WebSearchRequest: 'web.md',
+  WebSearchResult: 'web.md',
+  WorkflowRun: 'workflow.md',
+  WorkflowRunInfo: 'workflow.md',
+  WorkflowStartRequest: 'workflow.md',
+}
+
+/** TypeScript lib and pinned framework types that have no repository-owned data page. */
+const FOUNDATION_TYPE_NAMES = new Set([
+  'AbortSignal',
+  'AsyncIterable',
+  'Context',
+  'Error',
+  'Pick',
+  'Promise',
+  'Readonly',
+])
+
+/** Project types deliberately documented outside the core-data catalog. */
+const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
+  AgentFactory: 'agent creation seam is owned by packages/core/agent/README.md',
+  AgentHandle: 'agent ownership handle is owned by packages/core/agent/README.md',
+  BashEnvContributor: 'service-local extension type is owned by packages/bash/tool-bash/src/index.ts',
+  BashEnvVariableInfo: 'service-local metadata type is owned by packages/bash/tool-bash/src/index.ts',
+  CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
+  CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
+  PresetOption: 'deployment menu metadata is owned by packages/ui/permission/README.md',
+  PresetSpec: 'deployment preset composition is owned by packages/ui/permission/README.md',
+  PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
+  ResumeAgentOptions: 'agent resume contract is owned by packages/core/agent/README.md',
+  SessionForkSource: 'service-local fork input is owned by packages/core/session/src/index.ts',
+  SubagentRunEndInfo: 'event-local snapshot is owned by packages/subagent/subagent/src/index.ts',
+  SubagentRunInfo: 'event-local snapshot is owned by packages/subagent/subagent/src/index.ts',
+  WorkflowAgentEndInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
+  WorkflowAgentInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
+  WorkflowResultInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
+}
+
+/** 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()
+}
+
+/** 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. */
@@ -71,6 +223,8 @@ interface EventEntry {
  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. */
@@ -79,6 +233,14 @@ interface EventEntry {
  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`. */
@@ -89,8 +251,8 @@ interface ServiceEntry {
  abstract: boolean
  /** Class-level JSDoc prose, one line per paragraph. */
  doc: string
-  /** Public method signatures (bodies stripped), in source order. */
-  methods: string[]
+  /** Public methods (bodies stripped), in source order. */
+  methods: ServiceMethodEntry[]
  /** Source pointer of the class declaration. */
  source: string
 }
@@ -114,6 +276,22 @@ function memberSignature(member: ts.TypeElement | ts.ClassElement, sf: ts.Source
  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.
+ */
+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
@@ -121,6 +299,7 @@ function memberSignature(member: ts.TypeElement | ts.ClassElement, sf: ts.Source
 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')
@@ -134,6 +313,7 @@ export function collectEvents(scanRoot: string = root): EventEntry[] {
      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' to its JSDoc (see AGENTS.md).`)
      }
@@ -154,10 +334,11 @@ export function collectEvents(scanRoot: string = root): EventEntry[] {
      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, mode, doc, source: src })
+      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
 }

@@ -170,6 +351,7 @@ export function collectEvents(scanRoot: string = root): EventEntry[] {
 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')
@@ -179,7 +361,7 @@ export function collectServices(scanRoot: string = root): ServiceEntry[] {
    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: string[] = []
+      const methods: ServiceMethodEntry[] = []
      for (const member of cls.members) {
        if (!ts.isMethodDeclaration(member)) continue
        // Only instance methods callable through `ctx.<key>` are surface;
@@ -192,9 +374,10 @@ export function collectServices(scanRoot: string = root): ServiceEntry[] {
        if (nonPublic) continue
        const memberName = member.name.getText(sf)
        if (memberName.startsWith('[')) continue // computed/symbol members
-        methods.push(memberSignature(member, sf))
        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)
@@ -216,6 +399,7 @@ export function collectServices(scanRoot: string = root): ServiceEntry[] {
    }
  }
  reportViolations('gen-cordis-catalog', violations)
+  reportTypeLinkViolations('gen-cordis-catalog', typeLinkViolations)
  return entries.sort((a, b) => a.key.localeCompare(b.key))
 }

@@ -274,7 +458,7 @@ function typeLinks(signature: string): string {
 function renderEvent(e: EventEntry): string[] {
  const out = [`### \`${e.name}\` — ${e.mode}`, '']
  if (e.doc) out.push(e.doc, '')
-  out.push('```' + FENCE, e.signature, '```', '')
+  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]})`, '')
@@ -287,8 +471,13 @@ function renderService(s: ServiceEntry): string[] {
  const out = [`## \`ctx.${s.key}\` — \`${s.type}\`${kind}`, '']
  if (s.doc) out.push(s.doc, '')
  if (s.methods.length) {
-    out.push('```' + FENCE, ...s.methods, '```', '')
-    const links = typeLinks(s.methods.join('\n'))
+    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]})`, '')
@@ -303,15 +492,15 @@ const BANNER = [
 ]

 /** 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 (skipped by doc-typecheck, since a bare signature is not standalone-compilable). Type names in a signature link to the page that documents them.'
+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). */
-function renderEvents(events: EventEntry[]): string {
+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 the declaration\'s 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.',
+    '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,
    '',
@@ -341,12 +530,12 @@ function renderEvents(events: EventEntry[]): string {
 }

 /** Render the services catalog (pure, deterministic given sorted inputs). */
-function renderServices(services: ServiceEntry[]): string {
+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 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.',
+    '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,
    '',
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -100,7 +100,7 @@ const SERVICE_ROLES: ServiceRole[] = [
    pkg: 'session',
    title: 'In-memory session store',
    mode: 'core',
-    consumers: ['agent-loop', 'agent', 'session-persistence', 'session-query', 'subagent-inprocess', 'invariants'],
+    consumers: ['agent-loop', 'agent', 'cli-demo', 'session-persistence', 'session-query', 'subagent-inprocess', 'invariants'],
    note: 'Owns append-only Session instances and emits the durable session event feed.',
  },
  {
@@ -156,10 +156,10 @@ const SERVICE_ROLES: ServiceRole[] = [
  {
    key: 'agents',
    pkg: 'agent',
-    title: 'Agent registry',
+    title: 'Agent service',
    mode: 'core',
-    consumers: ['agent-loop', 'acp', 'subagent-inprocess', 'stdio-demo', 'invariants'],
-    note: 'Owns live Agent handles and the create/resume factory seam.',
+    consumers: ['agent-loop', 'acp', 'cli-demo', 'subagent-inprocess', 'stdio-demo', 'invariants'],
+    note: 'Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation.',
  },
  {
    key: 'agentLoop',
@@ -238,14 +238,14 @@ const SERVICE_ROLES: ServiceRole[] = [
    mode: 'seam',
    implementations: ['compact-basic'],
    consumers: ['compact-basic'],
-    note: 'The basic backend currently consumes the pre-step event directly; a model-facing compact tool remains deferred.',
+    note: 'The basic backend consumes post-step pressure and request-error recovery events; a model-facing compact tool remains deferred.',
  },
  {
    key: 'subagents',
    pkg: 'subagent',
    title: 'Subagent provider registry',
    mode: 'seam',
-    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp', 'subagent-mock'],
+    implementations: ['subagent-spawn', 'subagent-fork', 'subagent-acp'],
    consumers: ['tool-subagent'],
    note: 'Providers implement transports; tool-subagent exposes one configured provider as a model-facing tool name.',
  },
@@ -427,12 +427,28 @@ const APP_EXAMPLES = [
    summary: 'The echo demo swaps in a local mock LLM and teaching echo tool, then loads the stdio app package for the shared spine and terminal front door.',
  },
  {
-    id: 'coding',
-    rel: 'examples/coding-agent/composition.md',
-    title: 'Coding Agent App Composition',
-    label: 'examples/coding-agent',
-    config: 'examples/coding-agent/cordis.yml',
-    summary: 'The coding REPL demo adds the real DeepSeek adapter, filesystem tools, todo_write, compaction, and both subagent transports on top of the stdio app package.',
+    id: 'repl',
+    rel: 'examples/repl-agent/composition.md',
+    title: 'REPL Agent App Composition',
+    label: 'examples/repl-agent',
+    config: 'examples/repl-agent/cordis.yml',
+    summary: 'The REPL agent demo adds the real DeepSeek adapter, filesystem tools, todo_write, compaction, and both subagent transports on top of the stdio app package.',
+  },
+  {
+    id: 'tui',
+    rel: 'examples/tui-agent/composition.md',
+    title: 'TUI Agent App Composition',
+    label: 'examples/tui-agent',
+    config: 'examples/tui-agent/cordis.yml',
+    summary: 'The TUI agent reuses the repl-agent backend and tool composition while fixing the shared terminal app to the full-screen dsh-tui front door.',
+  },
+  {
+    id: 'headless',
+    rel: 'examples/headless-agent/composition.md',
+    title: 'Headless Agent App Composition',
+    label: 'examples/headless-agent',
+    config: 'examples/headless-agent/cordis.yml',
+    summary: 'The headless demo combines the real DeepSeek adapter and coding capabilities with the one-shot app package, format-pure stdout, and one fresh persisted top-level session.',
  },
  {
    id: 'cordis',
@@ -454,13 +470,20 @@ const APP_EXAMPLES = [

 type AppExample = typeof APP_EXAMPLES[number]

-function renderAppExpansion(lines: string[], appNode: string, pluginName: string): void {
+function renderAppExpansion(lines: string[], appNode: string, pluginName: string, exampleId: string): void {
  const agentCore = nodeId('bundle', 'agent_core')
  const jsonl = nodeId('bundle', 'jsonl')
  lines.push(`  ${appNode} --> ${agentCore}["@deepseek-ai/dsh-agent-spine-demo"]`)
  lines.push(`  ${appNode} --> ${jsonl}["@deepseek-ai/dsh-session-persistence-jsonl"]`)
  if (pluginName === '@deepseek-ai/dsh-stdio-demo') {
-    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'stdio')}["readline UI<br/>console logger<br/>pre-created main agent"]`)
+    const frontDoor = exampleId === 'tui'
+      ? '@deepseek-ai/dsh-tui<br/>pre-created main agent'
+      : exampleId === 'repl'
+        ? '@deepseek-ai/dsh-stdio<br/>pre-created main agent'
+        : 'dsh-tui (TTY) / dsh-stdio (pipes)<br/>pre-created main agent'
+    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'stdio')}["${frontDoor}"]`)
+  } else if (pluginName === '@deepseek-ai/dsh-cli-demo') {
+    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'cli')}["one-shot driver<br/>format-pure stdout<br/>fresh top-level agent"]`)
  } else if (pluginName === '@deepseek-ai/dsh-acp-demo') {
    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'acp')}["@deepseek-ai/dsh-acp<br/>JSON-RPC stdio bridge<br/>sessions created by client"]`)
  }
@@ -487,8 +510,8 @@ function renderAppComposition(example: AppExample): string {
    const pluginNode = nodeId(`plugin_${example.id}`, plugin.id)
    lines.push(`  ${pluginNode}["${escLabel(plugin.id)}<br/>${escLabel(plugin.name)}"]`)
    lines.push(`  cfg --> ${pluginNode}`)
-    if (plugin.name === '@deepseek-ai/dsh-stdio-demo' || plugin.name === '@deepseek-ai/dsh-acp-demo') {
-      renderAppExpansion(lines, pluginNode, plugin.name)
+    if (plugin.name === '@deepseek-ai/dsh-stdio-demo' || plugin.name === '@deepseek-ai/dsh-cli-demo' || plugin.name === '@deepseek-ai/dsh-acp-demo') {
+      renderAppExpansion(lines, pluginNode, plugin.name, example.id)
    }
  }
  lines.push(
@@ -845,14 +868,31 @@ function renderLifecycle(): string {
    '  LLM-->>Driver: StreamChunk*',
    `  Driver->>Session: ${mermaidCode('assistant/chunk')}*`,
    `  Session-->>SDK: ${mermaidCode('session/event')} ${mermaidCode('assistant/chunk')}*`,
+    '  alt final adapter or terminal in-band request failure',
+    `    Driver->>Session: ${mermaidCode('step/end')}`,
+    `    Driver->>Hooks: ${mermaidCode('agent/request-error')} waterfall`,
+    '    Hooks-->>Driver: retry in a new step or preserve the original error',
+    '  else model request succeeded',
    `  Driver->>Hooks: ${mermaidCode('agent/step-result')} waterfall`,
    `  Driver->>Session: ${mermaidCode('assistant/message')}`,
-    `  Driver->>Session: ${mermaidCode('tool/call')}`,
-    '  Driver->>Tools: execute through pre and post waterfalls',
-    '  Tools-->>Session: tool-owned events when applicable',
-    `  Driver->>Session: ${mermaidCode('tool/result')} and ${mermaidCode('step/end')}`,
+    '  Driver->>Tools: classify pending call by executionMode',
+    '  loop barriers and bounded rolling pool, reclassify before start',
+    '    opt call starts',
+    `      Driver->>Session: ${mermaidCode('tool/call')}`,
+    '      Driver->>Tools: ordered pre, concurrent execute',
+    '      Tools-->>Session: tool-owned events when applicable',
+    '    end',
+    '    opt next model-order result ready',
+    '      Driver->>Tools: ordered post',
+    `      Driver->>Session: ${mermaidCode('tool/result')}`,
+    '    end',
+    '  end',
+    '  Driver->>Session: post-tool context and steering',
+    `  Driver->>Hooks: ${mermaidCode('agent/post-step')} serial checkpoint`,
+    `  Driver->>Session: ${mermaidCode('step/end')}`,
    `  Driver->>Hooks: ${mermaidCode('agent/turn-continuation')} waterfall`,
    `  Driver->>Hooks: ${mermaidCode('agent/turn-stop')} serial terminal checkpoint`,
+    '  end',
    `  Driver->>Session: ${mermaidCode('turn/end')}`,
    `  Driver->>Persistence: ${mermaidCode('session/flush')} parallel checkpoint`,
    `  Driver-->>SDK: ${mermaidCode('agent/status')} idle`,
@@ -860,6 +900,8 @@ function renderLifecycle(): string {
    '',
    'The `assistant/message` edge records every successful provider call, including content-less and `max-tokens` finishes. Empty content stays out of derived history while the durable anchor retains usage and exact chunk provenance, including an explicit empty source set.',
    '',
+    '`dsh-compact-basic` uses `agent/post-step` for pressure after those durable facts and `agent/request-error` only for canonical context overflow. Recovery compacts between the closed failed step and a fresh retry step, and returns retry only when the surface replacement generation advances; otherwise the original request error remains authoritative.',
+    '',
    'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination surface for queue/status, prompt interception, request shaping, steering, continuation, and errors.',
    '',
    ...maintenanceFooter(maintenance),
@@ -968,7 +1010,9 @@ function renderIndex(docs: GraphDoc[]): string {
  const labels: Record<string, string> = {
    'docs/capability-seams.md': 'capability seams and core services',
    'examples/echo-agent/composition.md': 'echo-agent app composition',
-    'examples/coding-agent/composition.md': 'coding-agent app composition',
+    'examples/repl-agent/composition.md': 'repl-agent app composition',
+    'examples/headless-agent/composition.md': 'headless-agent app composition',
+    'examples/tui-agent/composition.md': 'tui-agent app composition',
    'examples/cordis-agent/composition.md': 'cordis-agent app composition',
    'examples/acp-agent/composition.md': 'acp-agent app composition',
    'docs/event-producer-consumer.md': 'event producer/consumer matrix',
@@ -979,7 +1023,9 @@ function renderIndex(docs: GraphDoc[]): string {
  const modes: Record<string, string> = {
    'docs/capability-seams.md': 'hybrid generated',
    'examples/echo-agent/composition.md': 'hybrid generated',
-    'examples/coding-agent/composition.md': 'hybrid generated',
+    'examples/repl-agent/composition.md': 'hybrid generated',
+    'examples/headless-agent/composition.md': 'hybrid generated',
+    'examples/tui-agent/composition.md': 'hybrid generated',
    'examples/cordis-agent/composition.md': 'hybrid generated',
    'examples/acp-agent/composition.md': 'hybrid generated',
    'docs/event-producer-consumer.md': 'hybrid generated',
--- a/scripts/gen-persistence-catalog.ts
+++ b/scripts/gen-persistence-catalog.ts
@@ -1,7 +1,7 @@
 /**
 * Generate `docs/persistence-catalog.md` from every `SessionEventMap` merge and
- * the owning `SurfaceEventType` union. This is the durable-record vocabulary,
- * not the live Cordis bus. Event declarations must be unique, explicitly typed,
+ * the owning event-envelope types. This is the durable-record vocabulary, not
+ * the live Cordis bus. Event declarations must be unique, explicitly typed,
 * documented, inheritance-free, and free of Cordis-only `@mode` tags; every
 * surface-union member must resolve to one. `--check` verifies the artifact.
 */
@@ -14,13 +14,23 @@ import { parseJsDoc, pointer, rawJsDoc, reportViolations } from './jsdoc.ts'
 const root = resolve(import.meta.dirname, '..')
 const OUT = 'docs/persistence-catalog.md'

-/** The fenced-block info string for generated payload blocks (skipped by
- * doc-typecheck, since a bare payload fragment is not standalone-compilable). */
+/** The fenced-block info string for generated declaration blocks (skipped by
+ * doc-typecheck, since their imported types are not standalone-compilable). */
 const FENCE = 'ts persistence-catalog'

 /** The package whose module id plugin merges augment (`declare module '…'`). */
 const SESSION_MODULE = '@deepseek-ai/dsh-session'

+/** Event-envelope declarations rendered before the per-event vocabulary. */
+const EVENT_ENVELOPE_TYPE_NAMES = [
+  'SessionEventType',
+  'SurfaceEventType',
+  'SurfaceOp',
+  'SessionEvent',
+] as const
+
+type EventEnvelopeTypeName = typeof EVENT_ENVELOPE_TYPE_NAMES[number]
+
 /** Primary core-data-structures page for linked payload types. */
 const LINK_MAP: Record<string, string> = {
  CallId: 'core.md',
@@ -41,6 +51,8 @@ export interface LogEventEntry {
  scope: string
  /** Payload type text (the member's type annotation, whitespace-collapsed). */
  payload: string
+  /** Source member declaration and complete JSDoc, dedented from its container. */
+  declaration: string
  /** Description prose (the member's JSDoc), one line per paragraph. */
  doc: string
  /** Source pointer `packages/…/file.ts:line` of the declaration. */
@@ -53,6 +65,16 @@ export interface AnnotatedLogEventEntry extends LogEventEntry {
  surface: boolean
 }

+/** One owning event-envelope declaration pasted into the generated catalog. */
+export interface EventEnvelopeTypeEntry {
+  /** Exported declaration name. */
+  name: EventEnvelopeTypeName
+  /** Verbatim type declaration, including its complete leading JSDoc. */
+  declaration: string
+  /** Source pointer `packages/…/file.ts:line` of the declaration. */
+  source: string
+}
+
 const printer = ts.createPrinter({ removeComments: true })

 /**
@@ -67,6 +89,24 @@ function payloadText(type: ts.TypeNode, sf: ts.SourceFile): string {
    .trim()
 }

+/**
+ * Copy a declaration from its leading JSDoc through its closing token while
+ * removing only the indentation imposed by its containing interface/module.
+ */
+function declarationText(text: string, sf: ts.SourceFile, node: ts.Node): string {
+  const raw = rawJsDoc(text, node)
+  const nodeStart = node.getStart(sf)
+  const start = raw ? text.lastIndexOf(raw, nodeStart) : nodeStart
+  const { line } = sf.getLineAndCharacterOfPosition(start)
+  const lineStart = sf.getPositionOfLineAndCharacter(line, 0)
+  const indent = text.slice(lineStart, start)
+  return text.slice(lineStart, node.end)
+    .split('\n')
+    .map(lineText => lineText.startsWith(indent) ? lineText.slice(indent.length) : lineText)
+    .join('\n')
+    .trimEnd()
+}
+
 /**
 * Every `interface SessionEventMap` declaration in a source file: the owning
 * top-level declaration (in `@deepseek-ai/dsh-session`) and any declaration
@@ -177,7 +217,8 @@ export function collectLogEvents(scanRoot: string = root): LogEventEntry[] {
        if (!doc) {
          violations.push(`${where} has no description prose. Say what the event records and what its payload means — the JSDoc becomes the catalog entry.`)
        }
-        entries.push({ name, scope: name.split('/')[0] ?? name, payload, doc, source: src })
+        const declaration = declarationText(text, sf, member)
+        entries.push({ name, scope: name.split('/')[0] ?? name, payload, declaration, doc, source: src })
      }
    }
  }
@@ -185,6 +226,51 @@ export function collectLogEvents(scanRoot: string = root): LogEventEntry[] {
  return entries
 }

+/**
+ * Collect the exported declarations that compose the persisted event envelope,
+ * preserving their source JSDoc and declaration text.
+ */
+export function collectEventEnvelopeTypes(scanRoot: string = root): EventEnvelopeTypeEntry[] {
+  const found = new Map<EventEnvelopeTypeName, EventEnvelopeTypeEntry>()
+  const violations: string[] = []
+  const wanted = new Set<string>(EVENT_ENVELOPE_TYPE_NAMES)
+  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 (!EVENT_ENVELOPE_TYPE_NAMES.some(name => text.includes(name))) continue
+    if (packageNameFor(rel, scanRoot) !== SESSION_MODULE) continue
+    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
+    for (const stmt of sf.statements) {
+      if (!ts.isTypeAliasDeclaration(stmt) || !wanted.has(stmt.name.text)) continue
+      const name = stmt.name.text as EventEnvelopeTypeName
+      const src = pointer(rel, sf, stmt)
+      const where = `event-envelope type '${name}' (${src})`
+      const prior = found.get(name)
+      if (prior) {
+        violations.push(`${where} is already declared at ${prior.source}; the persisted envelope type has exactly one owner.`)
+        continue
+      }
+      if (!(stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false)) {
+        violations.push(`${where} is not exported.`)
+      }
+      const { doc, hasMode } = parseJsDoc(rawJsDoc(text, stmt))
+      if (hasMode) violations.push(`${where} carries an @mode tag, but a persisted type has no dispatch mode.`)
+      if (!doc) violations.push(`${where} has no description prose. The full JSDoc is part of the generated catalog.`)
+      found.set(name, { name, declaration: declarationText(text, sf, stmt), source: src })
+    }
+  }
+  const missing = EVENT_ENVELOPE_TYPE_NAMES.filter(name => !found.has(name))
+  if (missing.length > 0) {
+    violations.push(`missing event-envelope declaration(s): ${missing.join(', ')}.`)
+  }
+  reportViolations('gen-persistence-catalog', violations)
+  return EVENT_ENVELOPE_TYPE_NAMES.map((name) => {
+    const entry = found.get(name)
+    if (!entry) throw new Error(`gen-persistence-catalog: missing checked event-envelope declaration '${name}'.`)
+    return entry
+  })
+}
+
 /**
 * Parse the `SurfaceEventType` union — the surface-eligible subset of event
 * types — from source. Hard-errors when the alias is missing, declared more
@@ -246,8 +332,7 @@ function typeLinks(payload: string): string {
 /** Render one log event entry. */
 function renderEvent(e: AnnotatedLogEventEntry): string[] {
  const out = [`#### \`${e.name}\` — ${e.surface ? 'surface' : 'log-only'}`, '']
-  if (e.doc) out.push(e.doc, '')
-  out.push('```' + FENCE, `'${e.name}': ${e.payload}`, '```', '')
+  out.push('```' + FENCE, e.declaration, '```', '')
  const links = typeLinks(e.payload)
  if (links) out.push(links, '')
  out.push(`Source: [\`${e.source}\`](../${e.source.split(':')[0]})`, '')
@@ -255,18 +340,26 @@ function renderEvent(e: AnnotatedLogEventEntry): string[] {
 }

 /** Render the full catalog (pure, deterministic given the collected inputs). */
-export function render(events: AnnotatedLogEventEntry[]): string {
+export function render(events: AnnotatedLogEventEntry[], envelopeTypes: EventEnvelopeTypeEntry[]): string {
  const lines: string[] = [
    '<!-- Generated by scripts/gen-persistence-catalog.ts — do not edit by hand.',
    '     Run `pnpm run gen-persistence-catalog` to regenerate. -->',
    '',
-    '# Persistence Log Event Catalog',
+    '# Session Persistence Event Catalog',
    '',
-    'Every event type that can appear in a session\'s durable event log: each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with the payload it carries, its surface badge, and the declaration it comes from. It complements [session.md](core-data-structures/session.md) (the `SessionEvent` envelope, surface list, and `deriveMessages()` projection), [persistence.md](core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
+    'Every event type that can appear in a session\'s durable event log: the complete persisted `SessionEvent` envelope and each member of the merge-extensible `SessionEventMap` — the owning vocabulary in `@deepseek-ai/dsh-session` plus every plugin declaration merge in this repo — with source JSDoc, full payload declaration, surface badge, and declaration site. It complements [session.md](core-data-structures/session.md) (surface ordering and the `deriveMessages()` projection), [persistence.md](core-data-structures/persistence.md) (how the log is made durable), and the [cordis events catalog](cordis-catalog/events.md) (the live bus wiring — a log event is NOT a cordis event; it reaches listeners via the single `session/event` emit).',
    '',
-    'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Payload blocks use a `ts persistence-catalog` fence (skipped by doc-typecheck, since a bare payload fragment is not standalone-compilable). Type names in a payload link to the page that documents them. See [the persistence-log-catalog RFC](rfc/implemented/process/2026-07-04-persistence-log-catalog.md).',
+    'This file is GENERATED from source (`scripts/gen-persistence-catalog.ts`) and verified fresh by `pnpm run verify-persistence-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks retain the source declaration and nested property JSDoc, removing only the indentation imposed by a containing interface/module, and use a `ts persistence-catalog` fence (skipped by doc-typecheck because declarations reference types from their owning modules). Type names in a payload link to the page that documents them. See [the persistence-log-catalog RFC](rfc/implemented/process/2026-07-04-persistence-log-catalog.md).',
    '',
-    'The on-disk envelope around every payload is `SessionEvent` — `type`, monotonic `seq`, epoch-ms `time`, the `data` documented here, plus `surfaceOp`/`sourceEventSeqs` on **surface** events only ([envelope](core-data-structures/session.md#sessioneventt--one-log-entry)). **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](core-data-structures/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.',
+    'The envelope declarations below compose each event\'s `type`, monotonic `seq`, epoch-ms `time`, `data`, and the conditional `surfaceOp`/`sourceEventSeqs` fields. **surface** marks a `SurfaceEventType` member: it produces an LLM message and declares how it joins the surface list. **log-only** marks everything else: a durable, replayable record with no derived-history contribution. Every payload is JSON-serializable (enforced at `Session.append`), and the whole format is pinned at `SESSION_FORMAT_VERSION = 0` — pre-release, no compatibility implied ([the version stance](core-data-structures/persistence.md)). Scope: the packages in this repo; a downstream plugin can merge further event types, which are outside this catalog by construction.',
+    '',
+    '## Event envelope',
+    '',
+    '```' + FENCE,
+    envelopeTypes.map(entry => entry.declaration).join('\n\n'),
+    '```',
+    '',
+    `Sources: ${envelopeTypes.map(entry => `[\`${entry.source}\`](../${entry.source.split(':')[0]})`).join(' · ')}`,
    '',
    '## Events',
    '',
@@ -285,7 +378,7 @@ export function render(events: AnnotatedLogEventEntry[]): string {
 * 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(annotateSurface(collectLogEvents(), collectSurfaceEventTypes()))
+  const content = render(annotateSurface(collectLogEvents(), collectSurfaceEventTypes()), collectEventEnvelopeTypes())
  if (process.argv.includes('--check')) {
    let committed: string | null = null
    try {
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -19,7 +19,7 @@ import WebService from '@deepseek-ai/dsh-web'
 import * as WebSearchExa from '@deepseek-ai/dsh-web-search-exa'
 import * as WebFetchLocal from '@deepseek-ai/dsh-web-fetch-local'
 import SubagentService from '@deepseek-ai/dsh-subagent'
-import * as SubagentMock from '@deepseek-ai/dsh-subagent-mock'
+import type { SubagentProvider } from '@deepseek-ai/dsh-subagent'
 import SkillService from '@deepseek-ai/dsh-skill'
 import * as SkillLocal from '@deepseek-ai/dsh-skill-local'
 import TaskService from '@deepseek-ai/dsh-tasks'
@@ -39,6 +39,17 @@ import * as ToolWorkflow from '@deepseek-ai/dsh-tool-workflow'
 const root = resolve(import.meta.dirname, '..')
 const OUT = 'docs/tool-catalog.md'

+/** Register the descriptor needed to mount schema-producing consumers. */
+function registerCatalogSubagentProvider(ctx: Context, name: string): void {
+  const provider: SubagentProvider = {
+    name,
+    capabilities: { outputSchema: false, depthLimit: false, toolFilter: false, persona: false },
+    inheritsParentContext: false,
+    start: () => Promise.reject(new Error('tool-catalog provider cannot start a child')),
+  }
+  ctx.subagents.registerProvider(provider)
+}
+
 /**
 * Tool package plus its hand-maintained boot recipe. The caller mounts the
 * prompt and registry; each recipe supplies only package-specific seams and
@@ -191,12 +202,11 @@ const TOOL_PACKAGES: ToolPackage[] = [
    shippedNames: ['subagent', 'subagent_fork'],
    async mount(ctx) {
      await ctx.plugin(SubagentService)
-      // Register a scripted provider under the name the tool delegates to.
-      await ctx.plugin(SubagentMock, { name: 'mock' })
+      registerCatalogSubagentProvider(ctx, 'mock')
      await ctx.plugin(ToolSubagent, { provider: 'mock' })
    },
    note:
-      'The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/coding-agent/cordis.yml` and `examples/acp-agent/cordis.yml`.',
+      'The registered tool name is the load-time `toolName` config (default `subagent`); the schema above is that default. The shipped example agents load this package once per subagent backend, so the model additionally sees `subagent_fork` (bound to the fork backend) with an identical schema — see `examples/repl-agent/cordis.yml` and `examples/acp-agent/cordis.yml`.',
  },
  {
    pkg: '@deepseek-ai/dsh-tool-tasks',
@@ -234,7 +244,7 @@ const TOOL_PACKAGES: ToolPackage[] = [
      // subagent provider to satisfy it. The schema does not depend on which
      // provider backs the engine.
      await ctx.plugin(SubagentService)
-      await ctx.plugin(SubagentMock, { name: 'mock' })
+      registerCatalogSubagentProvider(ctx, 'mock')
      await ctx.plugin(VmWorkflowEngine, { provider: 'mock' })
      await ctx.plugin(ToolWorkflow)
    },
--- a/scripts/gen-website-api.ts
+++ b/scripts/gen-website-api.ts
@@ -20,11 +20,12 @@
 * cannot land undocumented without CI going red. Pages are English (the
 * planned zh translation flow arrives separately; see docs/i18n/README.md).
 *
- * Signature fences use the ` ```ts website-api ` info string: doc-typecheck
- * only processes its known info strings, so these bare (non-compilable)
- * signature fragments are skipped there, while VitePress still highlights the
- * `ts` token. The sidebar fragment `website/.vitepress/config/api-sidebar.json`
- * is generated alongside so navigation can never drift from the page set.
+ * Signature fences use the ` ```ts website-api ` info string and retain the
+ * declaration's original source JSDoc. doc-typecheck only processes its known
+ * info strings, so these bare (non-compilable) fragments are skipped there,
+ * while VitePress still highlights the `ts` token. The sidebar fragment
+ * `website/.vitepress/config/api-sidebar.json` is generated alongside so
+ * navigation can never drift from the page set.
 *
 *   `tsx scripts/gen-website-api.ts`          → write pages + sidebar
 *   `tsx scripts/gen-website-api.ts --check`  → exit 1 if committed copies are
@@ -64,6 +65,8 @@ interface MemberDoc {
  heading: string
  /** All overload signature lines (bodies stripped). */
  signatures: string[]
+  /** Original source JSDoc, dedented only from its containing declaration. */
+  jsDoc: string
  /** Description prose, one paragraph per line. */
  doc: string
  /** Parameter name → `@param` text, in declaration order. */
@@ -166,6 +169,20 @@ function load(rel: string): { sf: ts.SourceFile; text: string } {
 // The module-merge walk (cordisModuleBody / eventMembers / serviceClasses) is
 // shared with gen-cordis-catalog.ts via cordis-walk.ts.

+/** Original JSDoc with only the source container's indentation removed. */
+function sourceJSDoc(text: string, sf: ts.SourceFile, node: ts.Node): string {
+  const raw = rawJsDoc(text, node)
+  if (raw === '') return ''
+  const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf))
+  const lineStart = sf.getPositionOfLineAndCharacter(line, 0)
+  const indent = text.slice(lineStart, node.getStart(sf))
+  return raw.split('\n')
+    .map((sourceLine, index) => index > 0 && sourceLine.startsWith(indent)
+      ? sourceLine.slice(indent.length)
+      : sourceLine)
+    .join('\n')
+}
+
 /** Signature text of a member: full text minus body/initializer, whitespace
 * collapsed, trailing semicolon stripped. */
 function signatureOf(member: ts.Node, sf: ts.SourceFile): string {
@@ -219,7 +236,7 @@ function memberDoc(
  const first = group[0]
  if (!first) throw new Error(`gen-website-api: empty member group for ${name}`)
  // Doc from the first overload that carries JSDoc prose.
-  const rawDocs = group.map(m => rawJsDoc(text, m))
+  const rawDocs = group.map(m => sourceJSDoc(text, sf, m))
  const docIndex = rawDocs.findIndex(r => parseJsDoc(r).doc !== '')
  const raw = docIndex === -1 ? '' : (rawDocs[docIndex] ?? '')
  const doc = parseJsDoc(raw).doc
@@ -255,6 +272,7 @@ function memberDoc(
    signatures: (ts.isMethodDeclaration(first) && funcLike.length > 1
      ? funcLike.filter(m => ts.isMethodDeclaration(m) && !m.body)
      : group).map(m => signatureOf(m, sf)),
+    jsDoc: raw,
    doc,
    params,
    returns: returnsText,
@@ -424,8 +442,13 @@ function declPaste(rel: string, symbol: string): { doc: string; code: string; so
  if (matches.length === 0) throw new Error(`gen-website-api: declaration ${symbol} not found in ${rel}`)
  const first = matches[0]
  if (!first) throw new Error(`gen-website-api: declaration ${symbol} not found in ${rel}`)
-  const doc = parseJsDoc(rawJsDoc(text, first)).doc
-  const code = matches.map(s => stripBodies(s, sf).replace(/^export\s+(default\s+)?/, '')).join('\n\n')
+  const firstJSDoc = sourceJSDoc(text, sf, first)
+  const doc = parseJsDoc(firstJSDoc).doc
+  const code = matches.map((statement) => {
+    const jsDoc = sourceJSDoc(text, sf, statement)
+    const declaration = stripBodies(statement, sf).replace(/^export\s+(default\s+)?/, '')
+    return jsDoc === '' ? declaration : `${jsDoc}\n${declaration}`
+  }).join('\n\n')
  return { doc, code, source: pointer(rel, sf, first) }
 }

@@ -480,6 +503,8 @@ interface HarnessEvent {
  scope: string
  mode: Mode | null
  signature: string
+  /** Original source event JSDoc, dedented from its module/interface. */
+  jsDoc: string
  doc: string
  params: { name: string; text: string }[]
  source: string
@@ -494,7 +519,7 @@ function collectHarnessEvents(violations: string[]): HarnessEvent[] {
    const body = cordisModuleBody(sf)
    if (!body) continue
    for (const { name, member } of eventMembers(body, sf)) {
-      const raw = rawJsDoc(text, member)
+      const raw = sourceJSDoc(text, sf, member)
      const { doc, mode } = parseJsDoc(raw)
      if (!mode) violations.push(`event '${name}' (${pointer(rel, sf, member)}) is missing @mode.`)
      if (!doc) violations.push(`event '${name}' (${pointer(rel, sf, member)}) has no JSDoc prose.`)
@@ -509,7 +534,7 @@ function collectHarnessEvents(violations: string[]): HarnessEvent[] {
        const tag = tags.get(pname)
        if (tag) params.push({ name: pname, text: tag })
      }
-      events.push({ name, scope: name.split('/')[0] ?? name, mode, signature: signatureOf(member, sf), doc, params, source: pointer(rel, sf, member) })
+      events.push({ name, scope: name.split('/')[0] ?? name, mode, signature: signatureOf(member, sf), jsDoc: raw, doc, params, source: pointer(rel, sf, member) })
    }
  }
  return events.sort((a, b) => a.name.localeCompare(b.name))
@@ -548,6 +573,7 @@ function renderMember(prefix: string, m: MemberDoc): string[] {
  const call = m.heading === '' ? '' : m.heading
  lines.push(`### ${prefix}${m.name}${call}`, '')
  lines.push('```' + FENCE)
+  lines.push(m.jsDoc)
  for (const sig of m.signatures) lines.push(sig)
  lines.push('```', '')
  lines.push(...prose(m.doc), '')
@@ -620,7 +646,7 @@ function renderEventsPage(events: HarnessEvent[]): string {
    for (const e of events.filter(ev => ev.scope === scope)) {
      lines.push(`### ${e.name}`, '')
      lines.push(`**Mode:** \`${e.mode ?? 'unknown'}\``, '')
-      lines.push('```' + FENCE, e.signature, '```', '')
+      lines.push('```' + FENCE, e.jsDoc, e.signature, '```', '')
      lines.push(...prose(e.doc), '')
      if (e.params.length > 0) {
        for (const p of e.params) lines.push(`- \`${p.name}\` — ${unlink(p.text)}`)
@@ -653,6 +679,16 @@ export function generate(): Map<string, string> {
  const events = collectHarnessEvents(violations)
  files.set(`${PAGES_DIR}/harness/events.md`, renderEventsPage(events))

+  for (const [rel, content] of files) {
+    if (!rel.endsWith('.md')) continue
+    for (const match of content.matchAll(/^```ts website-api\n([\s\S]*?)\n```$/gm)) {
+      const body = match[1] ?? ''
+      if (!body.startsWith('/**')) {
+        violations.push(`${rel}: a ts website-api fence does not begin with original source JSDoc.`)
+      }
+    }
+  }
+
  reportViolations('gen-website-api', violations)

  const sidebar = {
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -399,7 +399,9 @@ function builtBinSmokeGate(): Gate {
    '--config',
    'vitest.e2e.config.ts',
    'packages/examples/stdio-demo/tests/built-bin.e2e.ts',
+    'packages/examples/cli-demo/tests/built-bin.e2e.ts',
    'packages/examples/acp-demo/tests/built-bin.e2e.ts',
+    'packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts',
    // The worker-entry packages' built bundles: the only automated proof
    // that lib/index.js resolves its sibling lib/worker.cjs under plain node
    // (the e2e lane runs unbuilt, so these files self-skip there).
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1,5 +1,5 @@
 {
-  "comment": "Maps each ` ```ts type-equiv ` block (by doc + declared symbol) to the source symbol it must match verbatim. verify-type-equiv.ts enforces a 1:1 correspondence: every type-equiv block has exactly one entry here, and every entry resolves to exactly one block. Add an entry when you add a type-equiv block; remove it when you remove the block.",
+  "comment": "Maps each ` ```ts type-equiv ` or ` ```ts public-api ` block (by doc + declared symbol + projection) to the source declaration and original JSDoc it must match. Omit projection for the complete declaration; use public-api with a ` ```ts public-api ` block for a body-stripped public class declaration. verify-type-equiv.ts enforces a 1:1 correspondence: every source-equivalence block has exactly one entry here, and every entry resolves to exactly one block. Add an entry when you add a source-equivalence block; remove it when you remove the block.",
  "entries": [
    { "doc": "docs/core-data-structures/core.md", "symbol": "Branded", "source": "packages/util/brand/src/index.ts" },
    { "doc": "docs/core-data-structures/core.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" },
@@ -18,6 +18,8 @@
    { "doc": "docs/core-data-structures/core.md", "symbol": "HookContext", "source": "packages/core/agent/src/types.ts" },
    { "doc": "docs/core-data-structures/core.md", "symbol": "PromptDecision", "source": "packages/core/agent/src/types.ts" },
    { "doc": "docs/core-data-structures/core.md", "symbol": "ContinuationDecision", "source": "packages/core/agent/src/types.ts" },
+    { "doc": "docs/core-data-structures/core.md", "symbol": "RequestError", "source": "packages/core/agent/src/types.ts" },
+    { "doc": "docs/core-data-structures/core.md", "symbol": "RequestErrorDecision", "source": "packages/core/agent/src/types.ts" },
    { "doc": "docs/core-data-structures/core.md", "symbol": "ContinuationStop", "source": "packages/core/agent/src/types.ts" },
    { "doc": "docs/core-data-structures/core.md", "symbol": "SessionStartSource", "source": "packages/core/agent/src/types.ts" },

@@ -33,6 +35,8 @@
    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "TokenUsage", "source": "packages/llm/llm/src/types.ts" },
    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" },
    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "AppIdentity", "source": "packages/llm/llm/src/attribution.ts" },
+    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "BlockAssembler", "source": "packages/llm/llm/src/assembler.ts", "projection": "public-api" },
+    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "LlmAdapter", "source": "packages/llm/llm/src/index.ts", "projection": "public-api" },

    { "doc": "docs/core-data-structures/token-meter.md", "symbol": "TokenMeasurement", "source": "packages/llm/token-meter/src/types.ts" },
    { "doc": "docs/core-data-structures/token-meter.md", "symbol": "TokenSurfaceNode", "source": "packages/llm/token-meter/src/types.ts" },
@@ -47,8 +51,10 @@
    { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceEventType", "source": "packages/core/session/src/types.ts" },
    { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceOp", "source": "packages/core/session/src/types.ts" },
    { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceIntent", "source": "packages/core/session/src/types.ts" },
+    { "doc": "docs/core-data-structures/session.md", "symbol": "SessionSurface", "source": "packages/core/session/src/surface.ts" },
    { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceFoldReplacement", "source": "packages/core/session/src/surface.ts" },
    { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceFoldResult", "source": "packages/core/session/src/surface.ts" },
+    { "doc": "docs/core-data-structures/session.md", "symbol": "Session", "source": "packages/core/session/src/index.ts", "projection": "public-api" },

    { "doc": "docs/core-data-structures/persistence.md", "symbol": "SessionHeader", "source": "packages/core/session/src/types.ts" },
    { "doc": "docs/core-data-structures/persistence.md", "symbol": "CreateSessionOptions", "source": "packages/core/session/src/types.ts" },
@@ -72,6 +78,7 @@
    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionToken", "source": "packages/core/tools/src/index.ts" },
    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionInput", "source": "packages/core/tools/src/index.ts" },
    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecution", "source": "packages/core/tools/src/index.ts" },
+    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolExecutionMode", "source": "packages/core/tools/src/index.ts" },
    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolRunContext", "source": "packages/core/tools/src/index.ts" },
    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolGuard", "source": "packages/core/tools/src/index.ts" },
    { "doc": "docs/core-data-structures/tools.md", "symbol": "ToolRestriction", "source": "packages/core/tools/src/index.ts" },
@@ -150,6 +157,7 @@
    { "doc": "docs/core-data-structures/skills.md", "symbol": "Config", "source": "packages/skill/skill/src/index.ts" },

    { "doc": "docs/core-data-structures/compaction.md", "symbol": "CompactionResult", "source": "packages/compact/compact/src/types.ts" },
+    { "doc": "docs/core-data-structures/compaction.md", "symbol": "CompactionTrigger", "source": "packages/compact/compact/src/index.ts" },

    { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentCapabilities", "source": "packages/subagent/subagent/src/types.ts" },
    { "doc": "docs/core-data-structures/subagent.md", "symbol": "SubagentStartRequest", "source": "packages/subagent/subagent/src/types.ts" },
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -1,7 +1,7 @@
 /**
 * Doc-sync gate for package README Model Experience sections. It validates
- * audited package classifications, context-surface fields, package-owned text
- * blocks, generated-catalog links, and final-section order. See the
+ * audited package classifications, model/token/KV-cache fields, package-owned
+ * text blocks, generated-catalog links, and final-section order. See the
 * [Model Experience RFC](../docs/rfc/implemented/process/2026-07-12-package-model-experience-contract.md).
 */

@@ -12,8 +12,10 @@ import { markdownHeadingLines, markdownProseLines, type MarkdownProseLine } from
 const root = resolve(import.meta.dirname, '..')
 const HEADING = '## Model Experience'
 const LIMITATIONS_HEADING = '## Known Limitations and Deferred Work'
-const MODEL_VIEW_LABEL = '**What the model sees**'
-const TOKEN_EFFECT_LABEL = '**Token effect**'
+const MODEL_VIEW_HEADING = '#### What the model sees'
+const TOKEN_EFFECT_HEADING = '#### Token effect'
+const KV_CACHE_EFFECT_HEADING = '#### KV Cache effect'
+const FIELD_HEADINGS = [MODEL_VIEW_HEADING, TOKEN_EFFECT_HEADING, KV_CACHE_EFFECT_HEADING] as const

 type SentenceKind = 'none' | 'indirect'

@@ -34,9 +36,9 @@ const NO_MODEL_EXPERIENCE_SECTION: Readonly<Record<string, string>> = {
 }

 /**
- * Packages whose Model Experience is simple enough for one gated sentence.
- * Every other package must carry canonical context-surface blocks. A package
- * moves on or off this list with the change to its context behavior.
+ * Packages whose Model Experience is simple enough for one gated sentence plus
+ * a KV-cache field. Every other package must carry canonical context-surface
+ * blocks. A package moves on or off this list with its context behavior.
 */
 const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
  'packages/bash/bash': { kind: 'indirect', reason: 'The service interface delegates all model rendering to dsh-tool-bash.' },
@@ -66,7 +68,6 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
  'packages/support/invariants': { kind: 'none', reason: 'The observer validates requests but never rewrites their context.' },
  'packages/support/loader-smoke': { kind: 'none', reason: 'The test harness observes child-process streams without changing live requests.' },
  'packages/support/llm-replay': { kind: 'none', reason: 'The keyless adapter invokes no provider model.' },
-  'packages/support/subagent-mock': { kind: 'indirect', reason: 'Only dsh-tool-subagent renders its configured test outcome.' },
  'packages/tasks/tasks': { kind: 'indirect', reason: 'Producer and control-surface plugins own all model rendering over the task registry.' },
  'packages/examples/acp-demo': { kind: 'indirect', reason: 'The app bundle delegates request composition to dsh-agent-spine-demo and dsh-acp.' },
  'packages/ui/app-boot': { kind: 'indirect', reason: 'Only the loaded plugin tree contributes model context.' },
@@ -93,35 +94,41 @@ interface ContextSurface {
  heading: Line
  modelView: Line
  tokenEffect: Line
+  kvCacheEffect: Line
  title: string
+  modelViewVerbatimBlocks: number
  verbatimBlocks: number
 }

-/** Validate H4-plus-markdown literals nested after one context surface's fields. */
-function validateNestedVerbatim(raw: readonly string[]): { blocks: number; error?: string } {
+interface ParsedField {
+  value: Line
+  verbatimBlocks: number
+}
+
+/** Validate H5-plus-markdown literals nested under one Model Experience field. */
+function validateNestedVerbatim(raw: readonly string[], fragments: Set<string>): { blocks: number; error?: string } {
  let cursor = 0
  while (raw[cursor]?.trim().length === 0) cursor += 1
  if (cursor === raw.length) return { blocks: 0 }

  let blocks = 0
-  const fragments = new Set<string>()
  while (true) {
    while (raw[cursor]?.trim().length === 0) cursor += 1
    if (cursor === raw.length) break
-    if (!/^#### \S/.test(raw[cursor] ?? '')) {
-      return { blocks, error: 'content after Token effect must be a titled H4 verbatim block' }
+    if (!/^##### \S/.test(raw[cursor] ?? '')) {
+      return { blocks, error: 'content after a field paragraph must be a titled H5 verbatim block' }
    }
-    const title = (raw[cursor] as string).slice('#### '.length)
+    const title = (raw[cursor] as string).slice('##### '.length)
    const fragment = headingFragment(title)
-    if (fragment.length === 0) return { blocks, error: 'verbatim H4 title must be non-empty' }
+    if (fragment.length === 0) return { blocks, error: 'verbatim H5 title must be non-empty' }
    if (fragments.has(fragment)) {
-      return { blocks, error: `verbatim H4 title ${JSON.stringify(title)} is duplicated within its context surface` }
+      return { blocks, error: `verbatim H5 title ${JSON.stringify(title)} is duplicated within its context surface` }
    }
    fragments.add(fragment)
    cursor += 1
    while (raw[cursor]?.trim().length === 0) cursor += 1
    if (raw[cursor] !== '```markdown') {
-      return { blocks, error: 'each nested verbatim H4 requires an exact ```markdown fence' }
+      return { blocks, error: 'each nested verbatim H5 requires an exact ```markdown fence' }
    }
    cursor += 1
    const contentStart = cursor
@@ -134,7 +141,7 @@ function validateNestedVerbatim(raw: readonly string[]): { blocks: number; error
  return { blocks }
 }

-/** GitHub-style fragment for the simple ASCII H4 titles allowed by this contract. */
+/** GitHub-style fragment for the simple ASCII nested titles allowed by this contract. */
 function headingFragment(title: string): string {
  return title.toLowerCase().replaceAll('`', '').replaceAll(/[^a-z0-9 _-]/g, '').trim().replaceAll(/\s+/g, '-')
 }
@@ -167,6 +174,7 @@ let indirectCount = 0
 let verbatimBlockCount = 0
 let systemPromptSurfaceCount = 0
 let toolSchemaSurfaceCount = 0
+let kvCacheEffectCount = 0

 for (const [pkg, reason] of Object.entries(NO_MODEL_EXPERIENCE_SECTION)) {
  if (!scannedPackages.has(pkg)) {
@@ -260,13 +268,31 @@ for (const packageJson of packageJsons) {
  if (sentenceContract !== undefined) {
    const pattern = sentenceContract.kind === 'none' ? /^None, as .+\.$/ : /^Indirectly, through .+\.$/
    const rawContent = rawSection.filter(line => line.trim().length > 0)
-    if (content.length !== 1 || rawContent.length !== 1 || !pattern.test(content[0]?.raw ?? '')) {
+    const sentence = content[0]
+    const kvCacheHeading = content[1]
+    const kvCacheEffect = content[2]
+    if (content.length !== 3 || rawContent.length !== 3 || !pattern.test(sentence?.raw ?? '')) {
      const prefix = sentenceContract.kind === 'none' ? 'None, as ' : 'Indirectly, through '
-      failures.push({ path: readme, message: `must contain exactly one sentence beginning ${JSON.stringify(prefix)} and ending with a period` })
+      failures.push({ path: readme, message: `must contain exactly one sentence beginning ${JSON.stringify(prefix)} and ending with a period, followed by ${KV_CACHE_EFFECT_HEADING} and one non-empty paragraph` })
+      continue
+    }
+    if (kvCacheHeading?.raw !== KV_CACHE_EFFECT_HEADING
+      || kvCacheEffect === undefined
+      || /^#{1,6} /.test(kvCacheEffect.raw)
+      || kvCacheEffect.raw.trim().length === 0) {
+      failures.push({ path: readme, message: `line ${kvCacheHeading?.index ?? sentence?.index ?? modelHeading.index}: short Model Experience form requires exact ${KV_CACHE_EFFECT_HEADING} and one non-empty paragraph` })
+      continue
+    }
+    if (sentence === undefined
+      || sentence.index !== modelHeading.index + 2
+      || kvCacheHeading.index !== sentence.index + 2
+      || kvCacheEffect.index !== kvCacheHeading.index + 2) {
+      failures.push({ path: readme, message: 'short Model Experience sentence, KV-cache H4, and paragraph require one blank line between each element' })
      continue
    }
    if (sentenceContract.kind === 'none') explainedNoneCount += 1
    else indirectCount += 1
+    kvCacheEffectCount += 1
    continue
  }

@@ -292,8 +318,6 @@ for (const packageJson of packageJsons) {
    const end = surfaceStarts[surfaceIndex + 1]?.index ?? content.length
    const entries = content.slice(start.index, end)
    const heading = entries[0] as Line
-    const modelView = entries[1]
-    const tokenEffect = entries[2]
    const title = heading.raw.slice('### '.length)
    const fragment = headingFragment(title)
    if (fragment.length === 0) {
@@ -306,56 +330,100 @@ for (const packageJson of packageJsons) {
      surfaceError = true
      break
    }
-    if (modelView === undefined || !modelView.raw.startsWith(`${MODEL_VIEW_LABEL}: `) || modelView.raw.slice(`${MODEL_VIEW_LABEL}: `.length).trim().length === 0) {
-      failures.push({ path: readme, message: `line ${modelView?.index ?? heading.index}: context surface requires non-empty ${MODEL_VIEW_LABEL}: text` })
-      surfaceError = true
-      break
-    }
-    if (tokenEffect === undefined || !tokenEffect.raw.startsWith(`${TOKEN_EFFECT_LABEL}: `) || tokenEffect.raw.slice(`${TOKEN_EFFECT_LABEL}: `.length).trim().length === 0) {
-      failures.push({ path: readme, message: `line ${tokenEffect?.index ?? heading.index}: context surface requires non-empty ${TOKEN_EFFECT_LABEL}: text` })
+    const fieldStarts = entries
+      .map((line, index) => ({ line, index }))
+      .filter(entry => /^#### \S/.test(entry.line.raw))
+    if (fieldStarts.length !== FIELD_HEADINGS.length || fieldStarts[0]?.index !== 1) {
+      failures.push({ path: readme, message: `line ${heading.index}: context surface requires exactly three ordered H4 fields: ${FIELD_HEADINGS.join(', ')}` })
      surfaceError = true
      break
    }
    if ((surfaceIndex === 0 && heading.index !== modelHeading.index + 2)
      || rawLines[heading.index - 2]?.trim().length !== 0
-      || modelView.index !== heading.index + 2
-      || tokenEffect.index !== modelView.index + 2) {
-      failures.push({ path: readme, message: `line ${heading.index}: context-surface heading and fields require one blank line between each element` })
+      || fieldStarts[0].line.index !== heading.index + 2) {
+      failures.push({ path: readme, message: `line ${heading.index}: context-surface heading and first field require one blank line between them` })
      surfaceError = true
      break
    }
-    const unexpected = entries.slice(3).find(line => !/^#### \S/.test(line.raw))
-    if (unexpected !== undefined) {
-      failures.push({ path: readme, message: `line ${unexpected.index}: content after ${TOKEN_EFFECT_LABEL} must be a titled H4 plus \`markdown\` fence inside this context surface` })
-      surfaceError = true
-      break
+    const parsedFields: ParsedField[] = []
+    const verbatimFragments = new Set<string>()
+    for (let fieldIndex = 0; fieldIndex < FIELD_HEADINGS.length; fieldIndex += 1) {
+      const fieldStart = fieldStarts[fieldIndex] as { line: Line; index: number }
+      const expectedHeading = FIELD_HEADINGS[fieldIndex] as string
+      if (fieldStart.line.raw !== expectedHeading) {
+        failures.push({ path: readme, message: `line ${fieldStart.line.index}: expected exact field heading ${JSON.stringify(expectedHeading)}, found ${JSON.stringify(fieldStart.line.raw)}` })
+        surfaceError = true
+        break
+      }
+      const fieldEnd = fieldStarts[fieldIndex + 1]?.index ?? entries.length
+      const fieldEntries = entries.slice(fieldStart.index, fieldEnd)
+      const value = fieldEntries[1]
+      if (value === undefined || /^#{1,6} /.test(value.raw) || value.raw.trim().length === 0) {
+        failures.push({ path: readme, message: `line ${fieldStart.line.index}: ${expectedHeading} requires one non-empty paragraph` })
+        surfaceError = true
+        break
+      }
+      if (value.index !== fieldStart.line.index + 2) {
+        failures.push({ path: readme, message: `line ${fieldStart.line.index}: ${expectedHeading} and its paragraph require one blank line between them` })
+        surfaceError = true
+        break
+      }
+      const unexpected = fieldEntries.slice(2).find(line => !/^##### \S/.test(line.raw))
+      if (unexpected !== undefined) {
+        failures.push({ path: readme, message: `line ${unexpected.index}: content after ${expectedHeading} paragraph must be a titled H5 plus \`markdown\` fence owned by that field` })
+        surfaceError = true
+        break
+      }
+      const nextHeadingLine = fieldStarts[fieldIndex + 1]?.line.index
+        ?? surfaceStarts[surfaceIndex + 1]?.line.index
+        ?? nextH2Line
+      if (rawLines[nextHeadingLine - 2]?.trim().length !== 0) {
+        failures.push({ path: readme, message: `line ${nextHeadingLine}: Model Experience headings require a preceding blank line` })
+        surfaceError = true
+        break
+      }
+      const verbatim = validateNestedVerbatim(rawLines.slice(value.index, nextHeadingLine - 1), verbatimFragments)
+      if (verbatim.error !== undefined) {
+        failures.push({ path: readme, message: `line ${value.index}: ${verbatim.error}` })
+        surfaceError = true
+        break
+      }
+      if (fieldEntries.length - 2 !== verbatim.blocks) {
+        failures.push({ path: readme, message: `line ${value.index}: every nested H5 must own exactly one \`markdown\` fence` })
+        surfaceError = true
+        break
+      }
+      parsedFields.push({ value, verbatimBlocks: verbatim.blocks })
    }
-    const nextHeadingLine = surfaceStarts[surfaceIndex + 1]?.line.index ?? nextH2Line
-    const verbatim = validateNestedVerbatim(rawLines.slice(tokenEffect.index, nextHeadingLine - 1))
-    if (verbatim.error !== undefined) {
-      failures.push({ path: readme, message: `line ${tokenEffect.index}: ${verbatim.error}` })
-      surfaceError = true
-      break
-    }
-    if (entries.length - 3 !== verbatim.blocks) {
-      failures.push({ path: readme, message: `line ${tokenEffect.index}: every nested H4 must own exactly one \`markdown\` fence` })
-      surfaceError = true
-      break
-    }
-    if (/\]\(#[^)]+\)/.test(modelView.raw) || /\]\(#[^)]+\)/.test(tokenEffect.raw)) {
-      failures.push({ path: readme, message: `line ${heading.index}: Model Experience fields must not link between local subsections; nest the H4 in its owning H3` })
+    if (surfaceError) break
+    const modelViewField = parsedFields[0] as ParsedField
+    const tokenEffectField = parsedFields[1] as ParsedField
+    const kvCacheEffectField = parsedFields[2] as ParsedField
+    const modelView = modelViewField.value
+    const tokenEffect = tokenEffectField.value
+    const kvCacheEffect = kvCacheEffectField.value
+    if (/\]\(#[^)]+\)/.test(modelView.raw) || /\]\(#[^)]+\)/.test(tokenEffect.raw) || /\]\(#[^)]+\)/.test(kvCacheEffect.raw)) {
+      failures.push({ path: readme, message: `line ${heading.index}: Model Experience fields must not link between local subsections; nest the H5 in its owning H4 field` })
      surfaceError = true
      break
    }
    surfaceFragments.add(fragment)
-    surfaces.push({ heading, modelView, tokenEffect, title, verbatimBlocks: verbatim.blocks })
+    surfaces.push({
+      heading,
+      modelView,
+      tokenEffect,
+      kvCacheEffect,
+      title,
+      modelViewVerbatimBlocks: modelViewField.verbatimBlocks,
+      verbatimBlocks: parsedFields.reduce((total, field) => total + field.verbatimBlocks, 0),
+    })
  }
  if (surfaceError) continue

  const promptWithoutVerbatim = surfaces.find(surface => isDirectSystemPromptSurface(surface.title)
-    && surface.verbatimBlocks === 0)
+    && surface.modelViewVerbatimBlocks === 0)
  if (promptWithoutVerbatim !== undefined) {
-    failures.push({ path: readme, message: `line ${promptWithoutVerbatim.heading.index}: system-prompt surface must contain a titled H4 plus verbatim \`markdown\` block` })
+    failures.push({ path: readme, message: `line ${promptWithoutVerbatim.heading.index}: system-prompt surface must contain a titled H5 plus verbatim \`markdown\` block under ${MODEL_VIEW_HEADING}` })
    continue
  }
  const hasConcreteLiteral = surfaces.some(surface => surface.verbatimBlocks > 0
@@ -387,11 +455,12 @@ for (const packageJson of packageJsons) {
  contextSurfaceCount += surfaces.length
  systemPromptSurfaceCount += surfaces.filter(surface => isDirectSystemPromptSurface(surface.title)).length
  toolSchemaSurfaceCount += surfaces.filter(surface => /\bschemas?\b/i.test(surface.title)).length
+  kvCacheEffectCount += surfaces.length
  structuredCount += 1
 }

 if (failures.length === 0) {
-  console.log(`verify-package-readme-model-experience: ${packageJsons.length} README(s) checked (${omittedSectionCount} audited omissions, ${structuredCount} structured, ${contextSurfaceCount} context surfaces, ${systemPromptSurfaceCount} fenced system-prompt surfaces, ${toolSchemaSurfaceCount} catalog-linked tool-schema surfaces, ${explainedNoneCount} explained none, ${indirectCount} indirect, ${verbatimBlockCount} verbatim markdown blocks), all conform.`)
+  console.log(`verify-package-readme-model-experience: ${packageJsons.length} README(s) checked (${omittedSectionCount} audited omissions, ${structuredCount} structured, ${contextSurfaceCount} context surfaces, ${kvCacheEffectCount} KV-cache fields, ${systemPromptSurfaceCount} fenced system-prompt surfaces, ${toolSchemaSurfaceCount} catalog-linked tool-schema surfaces, ${explainedNoneCount} explained none, ${indirectCount} indirect, ${verbatimBlockCount} verbatim markdown blocks), all conform.`)
  process.exit(0)
 }

--- a/scripts/verify-type-equiv.ts
+++ b/scripts/verify-type-equiv.ts
@@ -1,7 +1,10 @@
 /**
- * Verify every `ts type-equiv` block against the source symbol named by the
- * manifest. Blocks and entries have a one-to-one relationship; comparison
- * ignores comments and whitespace but preserves declaration structure.
+ * Verify every `ts type-equiv` and `ts public-api` block against the source
+ * symbol named by the manifest. Ordinary entries preserve the complete
+ * declaration; `public-api` entries preserve a class's body-stripped public
+ * declaration. Blocks and entries have a one-to-one relationship; comparison
+ * ignores whitespace and non-JSDoc comments but preserves declaration
+ * structure and every original JSDoc comment.
 */

 import { globSync, readFileSync, existsSync } from 'node:fs'
@@ -13,33 +16,33 @@ const root = resolve(import.meta.dirname, '..')
 /** Scan doc-typecheck's full Markdown scope so unmanifested blocks also fail. */
 const MARKDOWN_GLOBS = ['README.md', 'docs/**/*.md', 'packages/*/*.md', 'packages/*/*/*.md', 'website/zh-CN/**/*.md']

-/** One manifest entry: a documented type-equiv block and its source symbol. */
+/** One manifest entry: a source-equivalence block and its source symbol. */
 interface ManifestEntry {
-  /** Doc file (repo-relative) containing the ` ```ts type-equiv ` block. */
+  /** Doc file (repo-relative) containing the source-equivalence block. */
  doc: string
  /** The declared symbol the block must match (e.g. `SessionEvent`). */
  symbol: string
  /** Source file (repo-relative) that exports the symbol. */
  source: string
+  /** Complete declaration (default), or a body-stripped public class API. */
+  projection?: 'public-api'
 }

-/** One extracted ` ```ts type-equiv ` block. */
+/** One extracted ` ```ts type-equiv ` or ` ```ts public-api ` block. */
 interface EquivBlock {
  doc: string
  /** 1-based line of the opening fence (for diagnostics). */
  line: number
  /** Symbol name parsed from the block's declaration. */
  symbol: string
+  /** Complete declaration (default), or a body-stripped public class API. */
+  projection?: 'public-api'
  /** Block body (the pasted declaration). */
  code: string
 }

-/**
- * Remove comments and normalize whitespace so prose-only edits do not drift
- * structural copies. This is intentionally not a general tokenizer: repo type
- * declarations do not contain comment delimiters inside string literals.
- */
-function normalize(code: string): string {
+/** Normalize declaration structure independently of comments and whitespace. */
+function normalizeStructure(code: string): string {
  return code
    .replace(/\/\*[\s\S]*?\*\//g, '')
    .replace(/(^|[^:])\/\/.*$/gm, '$1')
@@ -47,23 +50,38 @@ function normalize(code: string): string {
    .trim()
 }

+/**
+ * Extract normalized JSDoc comments in source order. Type declarations in this
+ * repository do not contain comment delimiters inside string literals.
+ */
+function normalizeJSDoc(code: string): string[] {
+  return [...code.matchAll(/\/\*\*[\s\S]*?\*\//g)]
+    .map(match => match[0].replace(/\s+/g, ' ').trim())
+}
+
 /** Strip source-only export modifiers. */
 function stripExport(code: string): string {
  return code.replace(/^export\s+(default\s+)?/, '')
 }

-/** Parse the declared symbol name from a type-equiv block body. */
+/** Parse the declared symbol name from a source-equivalence block body. */
 function blockSymbol(code: string): string | null {
-  const m = /(?:export\s+(?:default\s+)?)?(?:abstract\s+)?(?:interface|type|class|enum)\s+([A-Za-z0-9_]+)/.exec(code)
-  return m?.[1] ?? null
+  const sf = ts.createSourceFile('type-equiv.ts', code, ts.ScriptTarget.Latest, /* setParentNodes */ false, ts.ScriptKind.TS)
+  for (const stmt of sf.statements) {
+    const named =
+      ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt)
+      || ts.isClassDeclaration(stmt) || ts.isEnumDeclaration(stmt)
+    if (named && stmt.name) return stmt.name.text
+  }
+  return null
 }

-/** Extract every ` ```ts type-equiv ` block from one Markdown file. */
+/** Extract every source-equivalence block from one Markdown file. */
 function extractEquivBlocks(docRel: string): EquivBlock[] {
  const text = readFileSync(resolve(root, docRel), 'utf8')
  const lines = text.split('\n')
  const blocks: EquivBlock[] = []
-  let open: { line: number; body: string[] } | null = null
+  let open: { line: number; body: string[]; projection?: 'public-api' } | null = null

  for (let i = 0; i < lines.length; i++) {
    const raw = lines[i] ?? ''
@@ -78,21 +96,33 @@ function extractEquivBlocks(docRel: string): EquivBlock[] {
      if (!symbol) {
        throw new Error(`verify-type-equiv: ${docRel}:${open.line} — type-equiv block has no parseable interface/type/class declaration`)
      }
-      blocks.push({ doc: docRel, line: open.line, symbol, code })
+      blocks.push({
+        doc: docRel,
+        line: open.line,
+        symbol,
+        code,
+        ...(open.projection === undefined ? {} : { projection: open.projection }),
+      })
      open = null
      continue
    }
-    if ((fence[2] ?? '').trim() === 'ts type-equiv') open = { line: i + 1, body: [] }
+    const info = (fence[2] ?? '').trim()
+    if (info === 'ts type-equiv public-api') {
+      throw new Error(`verify-type-equiv: ${docRel}:${i + 1} — use the concise \`ts public-api\` fence`)
+    }
+    if (info === 'ts type-equiv') open = { line: i + 1, body: [] }
+    if (info === 'ts public-api') open = { line: i + 1, body: [], projection: 'public-api' }
  }
  if (open) throw new Error(`verify-type-equiv: ${docRel}:${open.line} — unterminated type-equiv block`)
  return blocks
 }

-/** The declaration text of `symbol` in `sourceRel`, with `export` stripped, or
+/**
+ * The declaration text of `symbol` in `sourceRel`, with `export` stripped, or
 * null when the symbol is not declared there. Uses the TS parser so it spans
 * interfaces, type aliases (including mapped/generic ones), classes, and enums
- * uniformly, and excludes the leading JSDoc (getStart skips leading trivia)
- * while keeping inline member comments. */
+ * uniformly while including declaration and member JSDoc.
+ */
 function sourceDeclaration(sourceRel: string, symbol: string): string | null {
  const abs = resolve(root, sourceRel)
  const text = readFileSync(abs, 'utf8')
@@ -102,19 +132,89 @@ function sourceDeclaration(sourceRel: string, symbol: string): string | null {
      ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt)
      || ts.isClassDeclaration(stmt) || ts.isEnumDeclaration(stmt)
    if (named && stmt.name?.text === symbol) {
-      return stripExport(stmt.getText(sf))
+      const declarationStart = stmt.getStart(sf)
+      const jsDoc = ts.getJSDocCommentsAndTags(stmt)
+        .filter(ts.isJSDoc)
+        .map(doc => text.slice(doc.pos, doc.end))
+        .join('\n')
+      const declaration = stripExport(text.slice(declarationStart, stmt.getEnd()))
+      return jsDoc === '' ? declaration : `${jsDoc}\n${declaration}`
    }
  }
  return null
 }

+/** Leading source JSDoc attached to one declaration or member. */
+function sourceJSDoc(text: string, node: ts.Node): string {
+  return ts.getJSDocCommentsAndTags(node)
+    .filter(ts.isJSDoc)
+    .map(doc => text.slice(doc.pos, doc.end))
+    .join('\n')
+}
+
+/** Whether a class member is part of its public declaration. */
+function isPublicMember(member: ts.ClassElement): boolean {
+  if (ts.isClassStaticBlockDeclaration(member)) return false
+  const name = ts.getNameOfDeclaration(member)
+  if (name && ts.isPrivateIdentifier(name)) return false
+  const modifiers = ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined
+  return !(modifiers?.some(modifier =>
+    modifier.kind === ts.SyntaxKind.PrivateKeyword
+    || modifier.kind === ts.SyntaxKind.ProtectedKeyword,
+  ) ?? false)
+}
+
+/** Remove an implementation body while retaining the source signature. */
+function bodylessMember(text: string, sf: ts.SourceFile, member: ts.ClassElement): string {
+  const start = member.getStart(sf)
+  let end = member.end
+  if (ts.isConstructorDeclaration(member) || ts.isMethodDeclaration(member)
+    || ts.isGetAccessorDeclaration(member) || ts.isSetAccessorDeclaration(member)) {
+    if (member.body) end = member.body.getStart(sf)
+  }
+  if (ts.isPropertyDeclaration(member) && member.initializer) end = member.initializer.getStart(sf)
+  const signature = text.slice(start, end).trimEnd().replace(/;$/, '').replace(/=\s*$/, '').trimEnd()
+  return `${signature};`
+}
+
+/**
+ * Render a class as an ambient declaration containing only its public fields,
+ * constructor, accessors, and methods. Implementation bodies and private or
+ * protected members are deliberately absent; original class/member JSDoc is
+ * retained so the projection is the source-owned public contract.
+ */
+function sourcePublicApi(sourceRel: string, symbol: string): string | null {
+  const abs = resolve(root, sourceRel)
+  const text = readFileSync(abs, 'utf8')
+  const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, /* setParentNodes */ true)
+  for (const stmt of sf.statements) {
+    if (!ts.isClassDeclaration(stmt) || stmt.name?.text !== symbol) continue
+    const classDoc = sourceJSDoc(text, stmt)
+    const abstract = stmt.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AbstractKeyword) ? 'abstract ' : ''
+    const typeParameters = stmt.typeParameters?.map(parameter => parameter.getText(sf)).join(', ')
+    const heritage = stmt.heritageClauses?.map(clause => clause.getText(sf)).join(' ')
+    const header = `declare ${abstract}class ${symbol}${typeParameters ? `<${typeParameters}>` : ''}${heritage ? ` ${heritage}` : ''} {`
+    const members = stmt.members
+      .filter(isPublicMember)
+      .map((member) => {
+        const jsDoc = sourceJSDoc(text, member)
+        const declaration = bodylessMember(text, sf, member)
+        return jsDoc === '' ? declaration : `${jsDoc}\n${declaration}`
+      })
+    const declaration = [header, ...members.map(member => member.split('\n').map(line => `  ${line}`).join('\n')), '}'].join('\n')
+    return classDoc === '' ? declaration : `${classDoc}\n${declaration}`
+  }
+  return null
+}
+
 const manifestRaw = readFileSync(resolve(root, 'scripts/type-equiv.manifest.json'), 'utf8')
 const manifest = JSON.parse(manifestRaw) as { entries: ManifestEntry[] }
 const entries = manifest.entries

-// Key a block/entry by doc + symbol (a symbol may be documented in more than one
-// doc, but at most once per doc).
-const keyOf = (x: { doc: string; symbol: string }): string => `${x.doc}::${x.symbol}`
+// Key a block/entry by doc + symbol + projection. A symbol may be documented in
+// more than one doc, and a doc may carry both complete and projected forms.
+const keyOf = (x: { doc: string; symbol: string; projection?: 'public-api' }): string =>
+  `${x.doc}::${x.symbol}::${x.projection ?? 'declaration'}`

 // Collect every type-equiv block across ALL docs in scope — not only the docs
 // the manifest names — so a block in an unmanifested doc is found and reported
@@ -133,7 +233,7 @@ for (const d of [...new Set(entries.map(e => e.doc))]) {
  else if (!docSet.has(d)) errors.push(`manifest references ${d}, which is outside the scanned markdown scope (${MARKDOWN_GLOBS.join(', ')})`)
 }

-// Duplicate-block guard: the same symbol twice in one doc is ambiguous.
+// Duplicate-block guard: the same projected symbol twice in one doc is ambiguous.
 const blockByKey = new Map<string, EquivBlock>()
 for (const b of blocks) {
  const k = keyOf(b)
@@ -173,16 +273,25 @@ let verified = 0
 for (const e of entries) {
  const b = blockByKey.get(keyOf(e))
  if (!b) continue // already reported as an orphan entry
-  const decl = sourceDeclaration(e.source, e.symbol)
+  const decl = e.projection === 'public-api'
+    ? sourcePublicApi(e.source, e.symbol)
+    : sourceDeclaration(e.source, e.symbol)
  if (decl === null) {
    errors.push(`symbol ${e.symbol} not found in ${e.source} (manifest entry for ${e.doc})`)
    continue
  }
-  if (normalize(decl) !== normalize(stripExport(b.code))) {
+  const doc = stripExport(b.code)
+  const sourceStructure = normalizeStructure(decl)
+  const docStructure = normalizeStructure(doc)
+  const sourceJSDoc = normalizeJSDoc(decl)
+  const docJSDoc = normalizeJSDoc(doc)
+  if (sourceStructure !== docStructure || JSON.stringify(sourceJSDoc) !== JSON.stringify(docJSDoc)) {
    errors.push(
      `DRIFT: ${e.doc}:${b.line} — type-equiv block for ${e.symbol} does not match ${e.source}.\n`
-      + `    source: ${normalize(decl)}\n`
-      + `    doc:    ${normalize(stripExport(b.code))}`,
+      + `    source structure: ${sourceStructure}\n`
+      + `    doc structure:    ${docStructure}\n`
+      + `    source JSDoc:     ${JSON.stringify(sourceJSDoc)}\n`
+      + `    doc JSDoc:        ${JSON.stringify(docJSDoc)}`,
    )
    continue
  }
@@ -190,7 +299,7 @@ for (const e of entries) {
 }

 if (errors.length === 0) {
-  console.log(`verify-type-equiv: ${verified} type-equiv block(s) match source (1:1 with manifest).`)
+  console.log(`verify-type-equiv: ${verified} type-equiv block(s) match source structure and JSDoc (1:1 with manifest).`)
  process.exit(0)
 }