Merge remote-tracking branch 'origin/master' into xtr/react-loop-simplification

# Conflicts: # .agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.i18n.yaml # .agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.md # .agents/notes/implemented/architecture/2026-07-22-unified-send-and-coalesced-user-messages.zh.md # .agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.i18n.yaml # .agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.md # .agents/notes/implemented/feature/2026-07-21-tui-skill-slash-command.zh.md # .agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.i18n.yaml # .agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.md # .agents/notes/implemented/simplification/2026-07-17-one-send-one-turn.zh.md # docs/architecture.i18n.yaml # docs/cordis-catalog/events.md # docs/cordis-catalog/services.md # docs/core-data-structures/core.i18n.yaml # docs/core-data-structures/core.md # docs/core-data-structures/core.zh.md # docs/defensive-patterns.i18n.yaml # packages/client/runtime/src/client/sessions/session.ts # packages/client/runtime/tests/queue-store.spec.ts # packages/context/time-context/tests/time-context.spec.ts # packages/context/workspace-context/tests/workspace-context.spec.ts # packages/cordis/tool-cordis/src/api-catalog.ts # packages/core/agent-loop/README.i18n.yaml # packages/core/agent-loop/README.md # packages/core/agent-loop/README.zh.md # packages/core/agent-loop/src/agent.ts # packages/core/agent/README.i18n.yaml # packages/core/agent/README.md # packages/core/agent/README.zh.md # packages/core/agent/src/types.ts # packages/core/agent/tests/agent.spec.ts # packages/core/scope/src/scoped-events.generated.ts # packages/goal/command-goal/tests/command-goal.spec.ts # packages/goal/goal-session/src/index.ts # packages/goal/goal-session/tests/goal-session.spec.ts # packages/goal/goal/tests/goal.spec.ts # packages/goal/goal/tests/projection.spec.ts # packages/goal/tool-goal/tests/tool-goal.spec.ts # packages/host/apiproxy/src/api-proxy.ts # packages/host/apiproxy/src/api/events.schema.ts # packages/host/apiproxy/src/api/events.ts # packages/host/apiproxy/tests/api-proxy-workspace.spec.ts # packages/llm/llm/README.i18n.yaml # packages/llm/llm/README.zh.md # packages/llm/llm/src/index.ts # packages/pty/pty-local/tests/index.spec.ts # packages/pty/pty-local/tests/local.spec.ts # packages/pty/pty/tests/service.spec.ts # packages/pty/tool-pty/tests/loader-composition.spec.ts # packages/pty/tool-pty/tests/tools.spec.ts # packages/skill/tool-skill/tests/tool-skill.spec.ts # packages/tasks/tasks-local/tests/tasks.spec.ts # packages/ui/tui/src/index.ts # packages/ui/tui/tests/harness.ts # packages/ui/tui/tests/tui.spec.ts # scripts/gen-cordis-catalog.ts # scripts/type-equiv.manifest.json
2026-07-30 14:04:53 +08:00
parent f2e20c1ef0 1db976210f
commit c0ef93efc8
1175 changed files with 49683 additions and 8452 deletions
@@ -0,0 +1,47 @@
+/**
+ * CSS Modules enter client bundles through virtual modules, so the loader must
+ * explicitly register the underlying stylesheet as a watch dependency.
+ */
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { clientBundle } from '../packages/client/tsdown.client.ts'
+
+interface CssPlugin {
+  name: string
+  resolveId?: (source: string, importer?: string) => string | null
+  load?: (this: { addWatchFile(id: string): void }, id: string) => Promise<string | null>
+}
+
+function cssPlugin(): CssPlugin {
+  const configs = clientBundle('@deepseek-ai/dsh-client-test', ['lib/types/index.js', 'lib/types/invariant.js'])
+  const plugins = (configs[1] as { plugins: CssPlugin[] }).plugins
+  const plugin = plugins.find(candidate => candidate.name === 'dsh-css-modules-inline')
+  if (plugin === undefined) throw new Error('CSS Modules plugin missing from client config')
+  return plugin
+}
+
+describe('client bundle CSS Modules', () => {
+  it('registers the source stylesheet as a watch dependency', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-client-css-watch-'))
+    try {
+      const stylesheet = join(root, 'Fixture.module.css')
+      const importer = join(root, 'index.ts')
+      await writeFile(stylesheet, '.root { color: red; }\n')
+      const plugin = cssPlugin()
+      const virtualId = plugin.resolveId?.('./Fixture.module.css', importer)
+      if (typeof virtualId !== 'string' || plugin.load === undefined) {
+        throw new Error('CSS Modules plugin hooks are incomplete')
+      }
+      const watched: string[] = []
+
+      const output = await plugin.load.call({ addWatchFile: id => watched.push(id) }, virtualId)
+
+      expect(watched).toEqual([stylesheet])
+      expect(output).toContain('data-plugin-css')
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
+})
@@ -1,16 +1,19 @@
 /**
- * Pins the client-bundle purity gate (tsdown preset resolveId classifier),
- * the build-time mirror of the module-edge rules: platform module-table
- * entries stay external, inline-safe wire layers inline, and every other
- * @deepseek-ai value import — including a bare plugin-package name and a
- * cross-plugin /client subpath — must fail the build loudly (cross-plugin
- * collaboration goes through cordis services, never module imports).
+ * Pins shared client-bundle preset contracts: the module-edge purity gate and
+ * the physical watch dependencies hidden behind virtual CSS Modules.
 */
-import { describe, expect, it } from 'vitest'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it, vi } from 'vitest'
 import { CLIENT_EXTERNALS, clientBundle } from '../packages/client/tsdown.client.ts'

 type ResolveId = (source: string) => null | { id: string; external: boolean }

+interface CssModulePlugin {
+  name: string
+  resolveId?: (source: string, importer: string | undefined) => null | string
+  load?: (this: { addWatchFile: (id: string) => void }, id: string) => Promise<unknown>
+}
+
 function purityResolveId(): ResolveId {
  // libEntry is spelled at every call site (no default) so the
  // package-invariants text check can see the invariant entry per package.
@@ -21,6 +24,16 @@ function purityResolveId(): ResolveId {
  return gate.resolveId as ResolveId
 }

+function cssModulePlugin(): CssModulePlugin {
+  const configs = clientBundle('@deepseek-ai/dsh-client-test', ['lib/types/index.js', 'lib/types/invariant.js'])
+  const plugins = (configs[1] as { plugins: CssModulePlugin[] }).plugins
+  const plugin = plugins.find(candidate => candidate.name === 'dsh-css-modules-inline')
+  if (plugin?.resolveId === undefined || plugin.load === undefined) {
+    throw new Error('CSS Modules plugin missing from client config')
+  }
+  return plugin
+}
+
 describe('client bundle purity gate', () => {
  const resolveId = purityResolveId()

@@ -60,3 +73,24 @@ describe('client bundle purity gate', () => {
    expect(dshClientChannels).toEqual(['@deepseek-ai/dsh-client-runtime/client'])
  })
 })
+
+describe('client bundle CSS Modules watch graph', () => {
+  it('registers the physical stylesheet read behind a virtual module', async () => {
+    const plugin = cssModulePlugin()
+    const importer = fileURLToPath(new URL(
+      '../packages/client/ui-conversation/src/client/queue/QueueDock.tsx',
+      import.meta.url,
+    ))
+    const stylesheet = fileURLToPath(new URL(
+      '../packages/client/ui-conversation/src/client/queue/QueueDock.module.css',
+      import.meta.url,
+    ))
+    const virtualId = plugin.resolveId?.('./QueueDock.module.css', importer)
+    if (virtualId === null || virtualId === undefined) throw new Error('CSS Modules import was not resolved')
+    const addWatchFile = vi.fn()
+
+    await plugin.load?.call({ addWatchFile }, virtualId)
+
+    expect(addWatchFile).toHaveBeenCalledExactlyOnceWith(stylesheet)
+  })
+})
@@ -1,11 +1,6 @@
-/**
- * AST walkers for the Cordis catalog generator: locate the Cordis module merge
- * in a source file, enumerate its `interface Events` members, and resolve the
- * `interface Context` service keys to their service classes.
- */
+/** Locate the Cordis module merge used by the vendored core API projector. */

 import ts from 'typescript'
-import { parseJsDoc, pointer, rawJsDoc } from './jsdoc.ts'

 /** The body of the cordis module merge in `sf`: `declare module 'cordis'`
 * (harness packages) or `declare module './context.ts'` (vendor core), or
@@ -18,74 +13,3 @@ export function cordisModuleBody(sf: ts.SourceFile): ts.ModuleBlock | null {
  }
  return null
 }
-
-/** Every `interface Events` method member of a cordis module merge, with the
- * event name resolved from its (possibly string-literal) property name. */
-export function eventMembers(body: ts.ModuleBlock, sf: ts.SourceFile): { name: string; member: ts.MethodSignature }[] {
-  const out: { name: string; member: ts.MethodSignature }[] = []
-  for (const stmt of body.statements) {
-    if (!ts.isInterfaceDeclaration(stmt) || stmt.name.text !== 'Events') continue
-    for (const member of stmt.members) {
-      if (!ts.isMethodSignature(member)) continue
-      const name = ts.isStringLiteral(member.name) ? member.name.text : member.name.getText(sf)
-      out.push({ name, member })
-    }
-  }
-  return out
-}
-
-/** The `ctx.<key> → type name` map declared by a merge's `interface Context`. */
-function contextKeyMap(body: ts.ModuleBlock, sf: ts.SourceFile): Map<string, string> {
-  const keyToType = new Map<string, string>()
-  for (const stmt of body.statements) {
-    if (!ts.isInterfaceDeclaration(stmt) || stmt.name.text !== 'Context') continue
-    for (const member of stmt.members) {
-      if (!ts.isPropertySignature(member) || !member.type) continue
-      keyToType.set(member.name.getText(sf), member.type.getText(sf))
-    }
-  }
-  return keyToType
-}
-
-/** One `ctx.<key>` service class resolved from a Context merge. */
-export interface ServiceClass {
-  key: string
-  type: string
-  cls: ts.ClassDeclaration
-  abstract: boolean
-  /** Class-level JSDoc prose (empty string when missing — also reported). */
-  doc: string
-}
-
-/**
- * Resolve each `ctx.<key>` of a merge to the service class declared in the
- * same file. A key whose type is not a class here (a Pick-mixin member, e.g.
- * timer helpers) is skipped. A class without JSDoc prose is reported into
- * `violations` (named `where` by the caller's gate).
- *
- * @param body — the cordis module merge body.
- * @param sf — the source file containing the merge.
- * @param rel — repo-relative path of `sf`, for violation pointers.
- * @param violations — sink for JSDoc-completeness violations.
- * @returns the resolved service classes, in Context-declaration order.
- */
-export function serviceClasses(
-  body: ts.ModuleBlock,
-  sf: ts.SourceFile,
-  rel: string,
-  violations: string[],
-): ServiceClass[] {
-  const text = sf.getFullText()
-  const out: ServiceClass[] = []
-  for (const [key, type] of contextKeyMap(body, sf)) {
-    const cls = sf.statements.find(
-      (s): s is ts.ClassDeclaration => ts.isClassDeclaration(s) && s.name?.text === type,
-    )
-    if (!cls) continue // a Pick-mixin member, not a class here
-    const abstract = cls.modifiers?.some(m => m.kind === ts.SyntaxKind.AbstractKeyword) ?? false
-    const doc = parseJsDoc(rawJsDoc(text, cls)).doc
-    if (!doc) violations.push(`service ctx.${key} (${pointer(rel, sf, cls)}): class ${type} has no JSDoc.`)
-    out.push({ key, type, cls, abstract, doc })
-  }
-  return out
-}
@@ -8,9 +8,8 @@ import { spawn } from 'node:child_process'
 // Each UI's node invocation matches its base demo script plus the overlay config.
 const UIS = new Map([
  ['tui', [
-    '--experimental-transform-types',
    '--import',
-    './scripts/tspath-loader.ts',
+    'tsx/esm',
    'apps/cli/src/bin.ts',
    '--config',
    'examples/tui-agent/code-mode.cordis.yml',
@@ -1,11 +1,11 @@
 {
-  "AGENTS.md": 1750,
+  "AGENTS.md": 1755,
  "docs/AGENTS.md": 1150,
-  "docs/architecture.md": 1800,
+  "docs/architecture.md": 1920,
  "docs/cordis-primer.md": 600,
  "docs/defensive-patterns.md": 550,
  "docs/testing.md": 1100,
  "examples/AGENTS.md": 310,
  "packages/AGENTS.md": 675,
-  "packages/README.md": 870
+  "packages/README.md": 900
 }
@@ -1,282 +1,9 @@
 /**
- * Generate the model-facing Cordis API data module from the same event/service
- * collector as the documentation catalogs. It emits original declaration
- * JSDoc, first-sentence summaries, raw signatures, transitive public type
- * shapes, and inherited context entries, without source pointers; output is
- * deterministic and `--check` verifies it.
+ * Compatibility entry point for the unified Typert-backed Cordis catalog
+ * projection. The generated API module retains this command in its banner,
+ * while all extraction, validation, and rendering live in one implementation.
 */

-import { globSync, readFileSync, writeFileSync } from 'node:fs'
-import { resolve } from 'node:path'
-import ts from 'typescript'
-import { collectEvents, collectServices, INHERITED_SERVICES } from './gen-cordis-catalog.ts'
+import { main } from './gen-cordis-catalog.ts'

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

-import { globSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
-import { dirname, resolve, sep } from 'node:path'
-import ts from 'typescript'
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import {
+  projectCordisCatalog,
+  renderEvents,
+  renderServices,
+} from '@deepseek-ai/dsh-typert-generator'
+import type { CordisCatalogPolicy } from '@deepseek-ai/dsh-typert-generator'
 import { renderCordisCoreApiPages } from './cordis-core-api.ts'
-import { checkParams, checkReturns, parseJsDoc, parseTags, pointer, rawJsDoc, reportViolations, type Mode } from './jsdoc.ts'
-import { cordisModuleBody, eventMembers, serviceClasses } from './cordis-walk.ts'

 const root = resolve(import.meta.dirname, '..')
 const OUT_EVENTS = 'docs/cordis-catalog/events.md'
 const OUT_SERVICES = 'docs/cordis-catalog/services.md'
+const OUT_RUNTIME_API = 'packages/cordis/tool-cordis/src/api-catalog.ts'

-/** The fenced-block info string for generated signature blocks (skipped by
- * doc-typecheck, since a bare signature fragment is not standalone-compilable). */
-const FENCE = 'ts cordis-catalog'
-
-/**
- * One primary core-data-structures page per project type used by a generated
- * signature. This stays curated because union names intentionally do not
- * reuse the type-equivalence manifest's map-symbol entries and some symbols
- * appear on more than one page.
- */
-export const LINK_MAP: Record<string, string> = {
+/** One primary core-data-structures page per project type used by a generated signature. */
+export const LINK_MAP: Readonly<Record<string, string>> = {
  Agent: 'core.md',
  AgentCancelCause: 'core.md',
  AgentOptions: 'core.md',
@@ -35,6 +28,8 @@ export const LINK_MAP: Record<string, string> = {
  ContinuationDecision: 'core.md',
  ContinuationStop: 'core.md',
  GenerateOptions: 'core.md',
+  InboxItem: 'core.md',
+  InboxPlacement: 'core.md',
  MessageId: 'core.md',
  HookContext: 'core.md',
  LlmCallConfig: 'core.md',
@@ -103,6 +98,7 @@ export const LINK_MAP: Record<string, string> = {
  PreparedLlmCall: 'llm-streaming.md',
  LlmService: 'llm-streaming.md',
  StreamChunk: 'llm-streaming.md',
+  SkillProviderControl: 'skills.md',
  CreateSessionOptions: 'persistence.md',
  SessionHeader: 'persistence.md',
  SessionLocation: 'persistence.md',
@@ -152,9 +148,11 @@ export const LINK_MAP: Record<string, string> = {
  SessionTitleObservationResult: 'session-query.md',
  SessionTitleProvider: 'session-title.md',
  SessionTitleSnapshot: 'session-title.md',
+  SkillCatalogSnapshot: 'skills.md',
  SkillDefinition: 'skills.md',
  SkillLookupOptions: 'skills.md',
  SkillProvider: 'skills.md',
+  SkillProviderObservation: 'skills.md',
  SkillRegistration: 'skills.md',
  SkillSummary: 'skills.md',
  SaveTextSpill: 'spill.md',
@@ -201,12 +199,13 @@ export const LINK_MAP: Record<string, string> = {
  WorkflowStartRequest: 'workflow.md',
 }

-/** TypeScript lib and pinned framework types that have no repository-owned data page. */
-const FOUNDATION_TYPE_NAMES = new Set([
+/** TypeScript lib and pinned framework types with no repository-owned data page. */
+export const FOUNDATION_TYPE_NAMES: ReadonlySet<string> = new Set([
  'AbortSignal',
  'AsyncIterable',
  'Context',
  'Error',
+  'Map',
  'Partial',
  'Pick',
  'Promise',
@@ -214,7 +213,7 @@ const FOUNDATION_TYPE_NAMES = new Set([
 ])

 /** Project types deliberately documented outside the core-data catalog. */
-const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
+export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
  AgentFactory: 'agent creation seam is owned by packages/core/agent/README.md',
  BeginCommandRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
  InsertReferenceRequest: 'event-local request contract is owned by packages/client/ui-slash/src/types.ts',
@@ -239,6 +238,14 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
  ProjectionSnapshot: 'watermark snapshot shape is owned by packages/session-projection/session-projection/src/index.ts',
  ProjectionCheckpoint: 'persisted checkpoint row map is owned by packages/session-projection/session-projection/src/index.ts',
  CommandExecution: 'executor return contract is owned by packages/ui/commands/src/index.ts',
+  TypertContribution: 'registry contribution contract is owned by packages/typert/registry/README.md',
+  TypertFace: 'registry face identity is owned by packages/typert/registry/README.md',
+  TypertPackageFilter: 'registry package query filter is owned by packages/typert/registry/README.md',
+  TypertPackageRecord: 'registry package record is owned by packages/typert/registry/README.md',
+  TypertSchemaFilter: 'registry schema query filter is owned by packages/typert/registry/README.md',
+  TypertSchemaRecord: 'registry schema record is owned by packages/typert/registry/README.md',
+  'z.core.JSONSchema.BaseSchema': 'zod projection output is owned by the zod v4 API',
+  'z.core.ToJSONSchemaParams': 'zod projection parameters are owned by the zod v4 API',
  InvariantInstaller: 'service-local contribution contract is owned by packages/support/invariants/README.md',
  LocaleDict: 'service-local dictionary shape is owned by packages/client/i18n/src/index.ts',
  WebBootGraph: 'web boot graph wire shape is owned by packages/client/modules/src/client/index.ts',
@@ -250,6 +257,8 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
  InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/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',
+  KnobState: 'projection unit state shape is owned by packages/ui/permission/README.md',
+  PermissionSelect: 'permissions projection payload is owned by packages/ui/permission/src/types.ts',
  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',
@@ -263,401 +272,51 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
  WorkspaceId: 'branded id is owned by packages/workspace/workspace/README.md',
 }

-/** Collect named references from parameter, generic-constraint/default, and return types. */
-function signatureTypeNames(member: ts.MethodSignature | ts.MethodDeclaration, sf: ts.SourceFile): string[] {
-  const declared = new Set(member.typeParameters?.map(parameter => parameter.name.text) ?? [])
-  const referenced = new Set<string>()
-  const visit = (node: ts.Node): void => {
-    if (ts.isTypeReferenceNode(node)) referenced.add(node.typeName.getText(sf))
-    if (ts.isTypeQueryNode(node)) referenced.add(node.exprName.getText(sf))
-    ts.forEachChild(node, visit)
-  }
-  for (const parameter of member.typeParameters ?? []) {
-    if (parameter.constraint) visit(parameter.constraint)
-    if (parameter.default) visit(parameter.default)
-  }
-  for (const parameter of member.parameters) {
-    if (parameter.type) visit(parameter.type)
-  }
-  if (member.type) visit(member.type)
-  return [...referenced].filter(name => !declared.has(name)).sort()
+/** Repository data policy consumed by the Cordis catalog projector. */
+export const CORDIS_CATALOG_POLICY: CordisCatalogPolicy = {
+  linkedTypePages: LINK_MAP,
+  foundationTypeNames: FOUNDATION_TYPE_NAMES,
+  typeLinkExemptions: TYPE_LINK_EXEMPTIONS,
+  inheritedEvents: [
+    { name: 'internal/plugin', summary: 'A plugin fiber was created.', source: 'vendor/cordis/src/events.ts:328' },
+    { name: 'internal/status', summary: 'A fiber changed lifecycle state.', source: 'vendor/cordis/src/events.ts:330' },
+    { name: 'internal/service', summary: 'Interception hook for a service binding (no core producer).', source: 'vendor/cordis/src/events.ts:332' },
+    { name: 'internal/update', summary: 'Waterfall: a fiber config update is being applied.', source: 'vendor/cordis/src/events.ts:334' },
+    { name: 'internal/get', summary: 'Waterfall: a service is being read from the store.', source: 'vendor/cordis/src/events.ts:336' },
+    { name: 'internal/set', summary: 'Waterfall: a service is being written to the store.', source: 'vendor/cordis/src/events.ts:338' },
+    { name: 'internal/listener', summary: 'A listener was registered.', source: 'vendor/cordis/src/events.ts:340' },
+    { name: 'internal/dispatch', summary: 'An event is being dispatched to listeners.', source: 'vendor/cordis/src/events.ts:342' },
+    { name: 'hmr/change', summary: 'A watched source file changed on disk.', source: 'vendor/hmr/src/index.ts:20' },
+    { name: 'hmr/reload', summary: 'Plugins are being reloaded after a change.', source: 'vendor/hmr/src/index.ts:21' },
+    { name: 'exit', summary: 'The process is exiting on a signal.', source: 'vendor/loader/src/index.ts:23' },
+    { name: 'loader/config-update', summary: 'The loader config tree changed.', source: 'vendor/loader/src/index.ts:24' },
+    { name: 'loader/entry-init', summary: 'A config entry is being initialized.', source: 'vendor/loader/src/index.ts:25' },
+    { name: 'loader/partial-dispose', summary: 'An entry is being partially disposed on reload.', source: 'vendor/loader/src/index.ts:26' },
+    { name: 'loader/patch-context', summary: 'A context is being patched during a reload.', source: 'vendor/loader/src/index.ts:27' },
+  ],
+  inheritedServices: [
+    { name: 'ctx.on / ctx.once', summary: 'Register an event listener (disposable).', source: 'vendor/cordis/src/events.ts:34' },
+    { name: 'ctx.emit / ctx.parallel / ctx.serial / ctx.bail / ctx.waterfall', summary: 'Dispatch an event (sync / awaited / first-bail / veto-chain).', source: 'vendor/cordis/src/events.ts:34' },
+    { name: 'ctx.plugin / ctx.inject', summary: 'Load a plugin / declare required services.', source: 'vendor/cordis/src/registry.ts:164' },
+    { name: 'ctx.effect', summary: 'Register a disposable side effect tied to the fiber.', source: 'vendor/cordis/src/fiber.ts:9' },
+    { name: 'ctx.get / ctx.set / ctx.provide / ctx.accessor / ctx.mixin', summary: 'Low-level service-store access and binding.', source: 'vendor/cordis/src/reflect.ts:7' },
+    { name: 'ctx.extend / ctx.isolate / ctx.intercept', summary: 'Derive a child context (scoped services / isolation / interception).', source: 'vendor/cordis/src/context.ts:42' },
+    { name: 'ctx.root / ctx.scope / ctx.fiber / ctx.registry / ctx.reflect / ctx.events / ctx.logger', summary: 'Ambient handles onto the running context graph.', source: 'vendor/cordis/src/context.ts:16' },
+    { name: 'ctx.timer (+ interval / timeout / throttle / debounce / setTimeout / setInterval)', summary: 'Disposable timer helpers. The `timer` key is provided at runtime; the six helpers are mixed onto ctx directly (declared via Pick).', source: 'vendor/timer/src/index.ts:4' },
+    { name: 'ctx.loader', summary: 'The config Loader that booted the app (present under the loader).', source: 'vendor/loader/src/index.ts:30' },
+    { name: 'ctx.hmr', summary: 'The hot-module-reload watcher (present under the hmr plugin).', source: 'vendor/hmr/src/index.ts:15' },
+  ],
 }

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

-// Run only when invoked as a script, not when imported by a test.
-if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
-  main()
-}
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) main()
@@ -8,7 +8,9 @@
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { dirname, relative, resolve } from 'node:path'
 import ts from 'typescript'
-import { collectEvents, collectServices } from './gen-cordis-catalog.ts'
+import { projectCordisCatalog } from '@deepseek-ai/dsh-typert-generator'
+import { CORDIS_CATALOG_POLICY } from './gen-cordis-catalog.ts'
+import type { EventEntry, ServiceEntry } from '@deepseek-ai/dsh-typert-generator'
 import {
  collectPackageGraph,
  escapeMermaidLabel as escLabel,
@@ -58,6 +60,7 @@ const GROUP_ORDER = [
  'util',
  'llm',
  'core',
+  'typert',
  'goal',
  'process',
  'bash',
@@ -128,6 +131,14 @@ const SERVICE_ROLES: ServiceRole[] = [
    consumers: ['session', 'agent', 'scope', 'agent-loop'],
    note: 'Companion subpaths register owner-local checks; the service owns selection, uniqueness, child fibers, and package-attributed failures.',
  },
+  {
+    key: 'typert',
+    pkg: 'typert-registry',
+    title: 'Runtime type registry',
+    mode: 'core',
+    consumers: ['typert-loader'],
+    note: 'Plugins register live zod contributions directly or through dsh-typert-loader; runtime consumers query schemas and reflection metadata at their own edges.',
+  },
  {
    key: 'sessionPersistence',
    pkg: 'session-persistence',
@@ -507,8 +518,8 @@ function tableCell(value: string): string {
  return value.replace(/\|/g, '\\|').replace(/\n/g, '<br>')
 }

-function assertServiceRolesComplete(): void {
-  const discovered = new Set(collectServices().map(service => service.key))
+function assertServiceRolesComplete(services: readonly ServiceEntry[]): void {
+  const discovered = new Set(services.map(service => service.key))
  const classified = new Set(SERVICE_ROLES.map(role => role.key))
  const missing = [...discovered].filter(key => !classified.has(key)).sort()
  const stale = [...classified].filter(key => !discovered.has(key)).sort()
@@ -520,8 +531,8 @@ function assertServiceRolesComplete(): void {
  }
 }

-function renderCapabilitySeams(pkgs: Pkg[]): string {
-  assertServiceRolesComplete()
+function renderCapabilitySeams(pkgs: Pkg[], services: readonly ServiceEntry[]): string {
+  assertServiceRolesComplete(services)
  const pkgsByShort = new Map(pkgs.map(pkg => [pkg.short, pkg]))
  const maintenance = 'hybrid: services are discovered from Cordis declarations; interface/implementation/consumer roles are classified in `scripts/gen-doc-graphs.ts` with a completeness guard'
  const nodes = new Map<string, string>()
@@ -970,8 +981,7 @@ function listenerPackages(listeners: Set<string>, pkgsByShort: Map<string, Pkg>)
  return [...listeners].sort().map(pkg => pkgLink(pkgsByShort.get(pkg), pkg)).join(', ')
 }

-function renderEventRelations(pkgs: Pkg[]): string {
-  const events = collectEvents()
+function renderEventRelations(pkgs: Pkg[], events: readonly EventEntry[]): string {
  const relations = collectEventRelations()
  const pkgsByShort = new Map(pkgs.map(pkg => [pkg.short, pkg]))
  const maintenance = 'generated: Cordis event declarations and producer/listener edges are resolved from the repository TypeScript Program'
@@ -1160,10 +1170,11 @@ function renderToolPipeline(): string {

 function renderDocs(): GraphDoc[] {
  const pkgs = collectPackageGraph(root, GROUP_ORDER, 'gen-doc-graphs')
+  const { model } = projectCordisCatalog(root, CORDIS_CATALOG_POLICY)
  const docs: GraphDoc[] = [
-    { rel: 'docs/capability-seams.md', content: renderCapabilitySeams(pkgs) },
+    { rel: 'docs/capability-seams.md', content: renderCapabilitySeams(pkgs, model.services) },
    ...APP_EXAMPLES.map(example => ({ rel: example.rel, content: renderAppComposition(example) })),
-    { rel: 'docs/event-producer-consumer.md', content: renderEventRelations(pkgs) },
+    { rel: 'docs/event-producer-consumer.md', content: renderEventRelations(pkgs, model.events) },
    { rel: 'docs/agent-lifecycle.md', content: renderLifecycle() },
    { rel: 'docs/tool-execution-pipeline.md', content: renderToolPipeline() },
  ]
@@ -310,9 +310,10 @@ const TOOL_PACKAGES: ToolPackage[] = [
    pkg: '@deepseek-ai/dsh-tool-skill',
    dir: 'tool-skill',
    source: 'packages/skill/tool-skill/src/index.ts',
-    requires: ['ctx.tools', 'ctx.skills'],
-    writes: ['tool/call', 'tool/result'],
+    requires: ['ctx.tools', 'ctx.agents', 'ctx.skills'],
+    writes: ['tool/call', 'tool/result', 'user/message replacement catalogs via agent.inject()'],
    async mount(ctx) {
+      await ctx.plugin(AgentRegistry)
      await ctx.plugin(SkillService)
      await ctx.plugin(SkillLocal, {
        dshHome: resolve(root, '.tmp/tool-catalog/.dsh'),
@@ -2,7 +2,7 @@
 import { randomUUID } from 'node:crypto'
 import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
 import { spawnSync } from 'node:child_process'
-import { isAbsolute, join, resolve } from 'node:path'
+import { dirname, isAbsolute, join, resolve } from 'node:path'

 const MINIMUM_GIT = [2, 26, 0]
 const HOOKS_DIRECTORY = 'dsh-hooks'
@@ -437,6 +437,15 @@ function inspectOwnedHooksDirectory(hooksPath) {
  return { markerPath, ...marker }
 }

+function isRegisteredOwnedHooksPath(commonDirectory, hooksPath) {
+  const normalizedHooksPath = normalizedPath(hooksPath)
+  const isRegistered = registeredWorktreeConfigPaths(commonDirectory).some(
+    configPath => normalizedPath(join(dirname(configPath), HOOKS_DIRECTORY)) === normalizedHooksPath,
+  )
+  if (!isRegistered) return false
+  return inspectOwnedHooksDirectory(hooksPath)?.hooksPath === hooksPath
+}
+
 function ensureOwnedHooksDirectory(hooksPath) {
  const inspected = inspectOwnedHooksDirectory(hooksPath)
  if (inspected !== undefined) return inspected
@@ -561,14 +570,22 @@ async function main() {
      'worktree core.hooksPath',
    )
    let ownedHooksDirectory
+    let copiedWorktreePathIsOwned = false
    if (worktreePath !== undefined && worktreePath !== hooksPath) {
      ownedHooksDirectory = inspectOwnedHooksDirectory(hooksPath)
-      if (ownedHooksDirectory === undefined || ownedHooksDirectory.hooksPath !== worktreePath) {
+      const worktreePathIsRelocated = ownedHooksDirectory?.hooksPath === worktreePath
+      copiedWorktreePathIsOwned = !worktreePathIsRelocated
+        && isRegisteredOwnedHooksPath(commonDirectory, worktreePath)
+      if (!worktreePathIsRelocated && !copiedWorktreePathIsOwned) {
        refuseScopedHooksPath({ origin: `file:${worktreeConfigPath}`, scope: 'worktree', value: worktreePath })
      }
    }
    const directWorktreePathIsOwned = worktreePath !== undefined
-      && (worktreePath === hooksPath || ownedHooksDirectory?.hooksPath === worktreePath)
+      && (
+        worktreePath === hooksPath
+        || ownedHooksDirectory?.hooksPath === worktreePath
+        || copiedWorktreePathIsOwned
+      )
    const effectiveEntry = effectiveConfigEntry(root, 'core.hooksPath')
    if (effectiveEntry !== undefined) {
      const effectivePathIsOwned = effectiveEntry.scope === 'worktree'
@@ -593,6 +610,7 @@ async function main() {
      worktreePath !== undefined
      && worktreePath !== hooksPath
      && ownedHooksDirectory.hooksPath !== worktreePath
+      && !copiedWorktreePathIsOwned
    ) {
      throw new Error(`hooks directory ownership changed while relocating ${JSON.stringify(worktreePath)}`)
    }
@@ -262,6 +262,30 @@ describe('worktree-local Lefthook installer', () => {
    expect(readFileSync(legacyHook, 'utf8')).toBe('#!/bin/sh\n# legacy hook\n')
  })

+  it('replaces the owned hook path Git copies into a newly added worktree', async () => {
+    const fixture = createFixture()
+    const mainInstall = await runInstaller(fixture, fixture.main)
+    expect(mainInstall.status, mainInstall.stderr).toBe(0)
+    const mainHooks = hooksPath(fixture, fixture.main)
+    const mainHookBefore = readFileSync(join(mainHooks, 'pre-commit'), 'utf8')
+    const lateLinked = join(fixture.container, 'late-linked')
+    git(fixture, fixture.main, ['worktree', 'add', '-b', 'late-linked', lateLinked])
+    write(join(lateLinked, 'lefthook.yml'), 'late-linked-worktree-config\n')
+    installFakeLefthook(lateLinked)
+    expect(git(fixture, lateLinked, ['config', '--worktree', '--get', 'core.hooksPath'])).toBe(mainHooks)
+
+    const linkedInstall = await runInstaller(fixture, lateLinked)
+
+    expect(linkedInstall.status, linkedInstall.stderr).toBe(0)
+    const linkedHooks = hooksPath(fixture, lateLinked)
+    expect(linkedHooks).not.toBe(mainHooks)
+    expect(git(fixture, lateLinked, ['config', '--worktree', '--get', 'core.hooksPath'])).toBe(linkedHooks)
+    expect(readFileSync(join(linkedHooks, 'pre-commit'), 'utf8')).toContain(
+      '# config=late-linked-worktree-config',
+    )
+    expect(readFileSync(join(mainHooks, 'pre-commit'), 'utf8')).toBe(mainHookBefore)
+  })
+
  it('serializes concurrent installs and keeps repeated output stable', async () => {
    const fixture = createFixture()
    const delayed = { DSH_TEST_LEFTHOOK_DELAY_MS: '150' }
@@ -509,6 +533,30 @@ describe('worktree-local Lefthook installer', () => {
    expect(git(fixture, fixture.linked, ['config', '--worktree', '--get', 'core.hooksPath'])).toBe('linked-custom-hooks')
  })

+  it('does not trust an ownership marker outside a registered worktree hook path', async () => {
+    const fixture = createFixture()
+    const mainInstall = await runInstaller(fixture, fixture.main)
+    expect(mainInstall.status, mainInstall.stderr).toBe(0)
+    const externalHooks = join(fixture.container, 'external-owned-hooks')
+    write(
+      join(externalHooks, '.dsh-lefthook-owned'),
+      `${JSON.stringify({
+        version: 1,
+        owner: 'deepseek-harness worktree-local lefthook hooks',
+        hooksPath: externalHooks,
+      })}\n`,
+      0o600,
+    )
+    git(fixture, fixture.linked, ['config', '--worktree', 'core.hooksPath', externalHooks])
+
+    const result = await runInstaller(fixture, fixture.linked)
+
+    expect(result.status).toBe(1)
+    expect(result.stderr).toContain('worktree-scoped core.hooksPath')
+    expect(git(fixture, fixture.linked, ['config', '--worktree', '--get', 'core.hooksPath'])).toBe(externalHooks)
+    expect(existsSync(hooksPath(fixture, fixture.linked))).toBe(false)
+  })
+
  it('refuses to activate a sibling worktree dormant hook path', async () => {
    const fixture = createFixture()
    const linkedConfig = join(gitDirectory(fixture, fixture.linked), 'config.worktree')
@@ -0,0 +1,98 @@
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { fileURLToPath } from 'node:url'
+import { flattenDiagnosticMessageText, parseConfigFileTextToJson } from 'typescript'
+import { describe, expect, it } from 'vitest'
+
+type Rules = Record<string, unknown>
+
+interface Profile {
+  readonly count: number
+  readonly indexes: readonly number[]
+  readonly sha256: string
+}
+
+// A one-time audit against eslint.config.mjs blob 696b08282885296830189fdafe7051a356806fc2
+// mapped @typescript-eslint/* to typescript/* and four extension rules to their
+// Oxlint core equivalents. These fingerprints pin the resulting repository
+// contract; they do not re-evaluate that deleted baseline or track its preset.
+const profiles = {
+  source: {
+    count: 88,
+    indexes: [0, 1, 4, 5],
+    sha256: 'da1dfd77cb6eb66be93d8d3820f9b9b68b7aa391c24680f8851c0910298f9e3b',
+  },
+  example: {
+    count: 87,
+    indexes: [0, 1, 2, 4, 5],
+    sha256: '6a2606053bc1ec1de3b02611de88ea51d201dac13a1f193e4934d33c08b95f08',
+  },
+  test: {
+    count: 83,
+    indexes: [0, 3, 4, 5],
+    sha256: '7995e14926a36c40bd65c474637735222a95fb030395681685f03060e50a7b78',
+  },
+} as const satisfies Record<string, Profile>
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isUnknownArray(value: unknown): value is unknown[] {
+  return Array.isArray(value)
+}
+
+function severity(value: unknown): 0 | 1 | 2 {
+  const level = isUnknownArray(value) ? value[0] : value
+  if (level === 'off' || level === 0) return 0
+  if (level === 'warn' || level === 'warning' || level === 1) return 1
+  if (level === 'error' || level === 2) return 2
+  throw new Error(`unsupported lint severity: ${JSON.stringify(level)}`)
+}
+
+function normalizedRules(rules: Rules): Rules {
+  return Object.fromEntries(Object.entries(rules)
+    .filter(([, value]) => severity(value) > 0)
+    .sort(([left], [right]) => left.localeCompare(right))
+    .map(([name, value]) => {
+      const options = isUnknownArray(value) ? value.slice(1) : []
+      return [name, [severity(value), ...options]]
+    }))
+}
+
+function mergedRules(overrides: readonly unknown[], indexes: readonly number[]): Rules {
+  const merged: Rules = {}
+  for (const index of indexes) {
+    const override = overrides[index]
+    if (!isRecord(override) || !isRecord(override.rules)) {
+      throw new Error(`.oxlintrc.json override ${index} must contain a rules object`)
+    }
+    Object.assign(merged, override.rules)
+  }
+  return normalizedRules(merged)
+}
+
+describe('Oxlint repository rule fingerprint', () => {
+  const path = fileURLToPath(new URL('../.oxlintrc.json', import.meta.url))
+  const result = parseConfigFileTextToJson(path, readFileSync(path, 'utf8'))
+  if (result.error !== undefined) {
+    throw new Error(flattenDiagnosticMessageText(result.error.messageText, '\n'))
+  }
+  const parsed: unknown = result.config
+  if (!isRecord(parsed) || !Array.isArray(parsed.overrides)) {
+    throw new Error('.oxlintrc.json must contain an overrides array')
+  }
+  const overrides: readonly unknown[] = parsed.overrides
+
+  it('pins the complete override shape', () => {
+    expect(overrides).toHaveLength(6)
+  })
+
+  it.each(Object.entries(profiles))('pins the %s rule profile', (_name, profile) => {
+    const rules = mergedRules(overrides, profile.indexes)
+    const fingerprint = createHash('sha256').update(JSON.stringify(rules)).digest('hex')
+
+    expect(Object.keys(rules)).toHaveLength(profile.count)
+    expect(fingerprint).toBe(profile.sha256)
+  })
+})
@@ -0,0 +1,250 @@
+import { spawnSync } from 'node:child_process'
+import { randomUUID } from 'node:crypto'
+import { mkdir, readFile, rm, writeFile } from 'node:fs/promises'
+import { join, relative } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { flattenDiagnosticMessageText, parseConfigFileTextToJson } from 'typescript'
+import { describe, expect, it } from 'vitest'
+
+const repositoryRoot = fileURLToPath(new URL('..', import.meta.url))
+const eslintCli = fileURLToPath(new URL('../node_modules/eslint/bin/eslint.js', import.meta.url))
+const oxlintCli = fileURLToPath(new URL('../node_modules/oxlint/bin/oxlint', import.meta.url))
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+function isUnknownArray(value: unknown): value is unknown[] {
+  return Array.isArray(value)
+}
+
+function runStagedFormatter(paths: readonly string[]) {
+  return spawnSync(process.execPath, [eslintCli, '--config', 'eslint.format.config.mjs', '--fix', '--no-warn-ignored', ...paths], {
+    cwd: repositoryRoot,
+    encoding: 'utf8',
+    env: { ...process.env, NO_COLOR: '1' },
+  })
+}
+
+function runOxlint(args: readonly string[], env: NodeJS.ProcessEnv = {}) {
+  return spawnSync(process.execPath, [oxlintCli, ...args], {
+    cwd: repositoryRoot,
+    encoding: 'utf8',
+    env: { ...process.env, NO_COLOR: '1', ...env },
+  })
+}
+
+function normalizedOutput(result: ReturnType<typeof runOxlint>): string {
+  return `${result.stdout}${result.stderr}`.replaceAll('\\', '/')
+}
+
+async function writeContractConfig(suffix: string): Promise<string> {
+  const path = join(repositoryRoot, `.oxlintrc.contract-${suffix}.json`)
+  await writeFile(path, JSON.stringify({ extends: ['./.oxlintrc.json'], ignorePatterns: [] }))
+  return path
+}
+
+describe('Oxlint executable contract', () => {
+  it('discovers the owning TypeScript project for every file class', async () => {
+    const suffix = randomUUID()
+    const configPath = await writeContractConfig(suffix)
+    const probes = [
+      ['host package source', 'packages/fs/fs-policy/src', 'packages/fs/fs-policy/tsconfig.json'],
+      ['host package test', 'packages/fs/fs-policy/tests', 'tsconfig.host.json'],
+      ['client package source', 'packages/client/ui-primitives/src', 'packages/client/ui-primitives/tsconfig.json'],
+      ['client package test', 'packages/client/ui-trajectory/tests', 'tsconfig.client.json'],
+      ['example', 'examples/headless-agent/tests', 'tsconfig.host.json'],
+      ['website', 'website', 'tsconfig.host.json'],
+    ] as const
+    const source = `export function probePromise(): Promise<void> {
+  return Promise.resolve()
+}
+
+probePromise()
+`
+
+    try {
+      const paths: Array<readonly [label: string, path: string, tsconfig: string]> = []
+      for (const [label, parent, tsconfig] of probes) {
+        const path = join(repositoryRoot, parent, `oxlint-contract-${suffix}.ts`)
+        await writeFile(path, source)
+        paths.push([label, relative(repositoryRoot, path), tsconfig])
+      }
+      const clientScript = 'scripts/client-bundle-purity.spec.ts'
+
+      const result = runOxlint([
+        '--config',
+        relative(repositoryRoot, configPath),
+        '--format',
+        'unix',
+        ...paths.map(([, path]) => path),
+        clientScript,
+      ], { OXC_LOG: 'debug' })
+      const output = normalizedOutput(result)
+
+      expect(result.error).toBeUndefined()
+      expect(result.status, output).toBe(1)
+      for (const [label, path, tsconfig] of paths) {
+        expect(output, label).toContain(`${path.replaceAll('\\', '/')}:5:1: Promises must be awaited`)
+        expect(output, `${label} project`).toContain(
+          `Got tsconfig for file ${join(repositoryRoot, path).replaceAll('\\', '/')}: ${join(repositoryRoot, tsconfig).replaceAll('\\', '/')}`,
+        )
+      }
+      expect(output.match(/typescript\(no-floating-promises\)/g)).toHaveLength(probes.length)
+      expect(output, 'client aggregate script project').toContain(
+        `Got tsconfig for file ${join(repositoryRoot, clientScript).replaceAll('\\', '/')}: ${join(repositoryRoot, 'tsconfig.client.json').replaceAll('\\', '/')}`,
+      )
+      expect(output).not.toContain('Unmatched file:')
+    } finally {
+      await Promise.all([
+        ...probes.map(([, parent]) => rm(join(repositoryRoot, parent, `oxlint-contract-${suffix}.ts`), { force: true })),
+        rm(configPath, { force: true }),
+      ])
+    }
+  }, 20_000)
+
+  it('runs JavaScript compatibility and nursery rules', async () => {
+    const suffix = randomUUID()
+    const configPath = await writeContractConfig(suffix)
+    const path = join(repositoryRoot, 'scripts', `oxlint-contract-${suffix}.ts`)
+    const source = `export function firstProbe(): number {
+  const first = 1
+  const second = 2
+  return first + second
+}
+
+export function secondProbe(): number {
+  const first = 1
+  const second = 2
+  return first + second
+}
+
+export function hasValue(value: string): boolean {
+  return value !== undefined
+}
+
+export const longProbe = 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1
+`
+
+    try {
+      await writeFile(path, source)
+      const result = runOxlint([
+        '--config',
+        relative(repositoryRoot, configPath),
+        '--format',
+        'unix',
+        relative(repositoryRoot, path),
+      ])
+      const output = normalizedOutput(result)
+
+      expect(result.error).toBeUndefined()
+      expect(result.status, output).toBe(1)
+      expect(output).toContain('@stylistic(max-len)')
+      expect(output).toContain('sonarjs(no-identical-functions)')
+      expect(output).toContain('typescript(no-unnecessary-condition)')
+    } finally {
+      await Promise.all([
+        rm(path, { force: true }),
+        rm(configPath, { force: true }),
+      ])
+    }
+  }, 20_000)
+
+  it('keeps formatter rules aligned with Oxlint validation', async () => {
+    const oxlintPath = join(repositoryRoot, '.oxlintrc.json')
+    const result = parseConfigFileTextToJson(oxlintPath, await readFile(oxlintPath, 'utf8'))
+    if (result.error !== undefined) {
+      throw new Error(flattenDiagnosticMessageText(result.error.messageText, '\n'))
+    }
+    const parsed = result.config as unknown
+    if (!isRecord(parsed) || !isUnknownArray(parsed.overrides)) {
+      throw new Error('.oxlintrc.json must contain an overrides array')
+    }
+    const stylisticOverride = parsed.overrides.find((value: unknown) =>
+      isRecord(value) && isRecord(value.rules) && '@stylistic/max-len' in value.rules)
+    if (!isRecord(stylisticOverride) || !isRecord(stylisticOverride.rules)) {
+      throw new Error('.oxlintrc.json must contain the @stylistic validator override')
+    }
+    const validatorRules = { ...stylisticOverride.rules }
+    const maxLen = validatorRules['@stylistic/max-len']
+    delete validatorRules['@stylistic/max-len']
+
+    const formatterUrl = pathToFileURL(join(repositoryRoot, 'eslint.format.config.mjs')).href
+    const formatterModule = await import(formatterUrl) as unknown
+    if (!isRecord(formatterModule) || !isUnknownArray(formatterModule.default)) {
+      throw new Error('eslint.format.config.mjs must default-export a config array')
+    }
+    const formatterOverride = formatterModule.default.find((value: unknown) => isRecord(value) && isRecord(value.rules))
+    if (!isRecord(formatterOverride) || !isRecord(formatterOverride.rules)) {
+      throw new Error('eslint.format.config.mjs must contain a rules object')
+    }
+
+    expect(validatorRules).toStrictEqual(formatterOverride.rules)
+    expect(maxLen).toStrictEqual(['error', { code: 140, ignoreUrls: true, ignoreStrings: true, ignoreTemplateLiterals: true }])
+  })
+
+  it('reports an unused suppression', async () => {
+    const suffix = randomUUID()
+    const configPath = await writeContractConfig(suffix)
+    const path = join(repositoryRoot, 'scripts', `oxlint-contract-${suffix}.ts`)
+
+    try {
+      await writeFile(path, '// oxlint-disable-next-line no-console\nexport const value = 1\n')
+      const result = runOxlint([
+        '--config',
+        relative(repositoryRoot, configPath),
+        '--format',
+        'unix',
+        relative(repositoryRoot, path),
+      ])
+      const output = normalizedOutput(result)
+
+      expect(result.error).toBeUndefined()
+      expect(result.status, output).toBe(0)
+      expect(output).toContain('Unused oxlint-disable directive')
+    } finally {
+      await Promise.all([
+        rm(path, { force: true }),
+        rm(configPath, { force: true }),
+      ])
+    }
+  })
+
+  it('accepts an ignored-only staged selection', () => {
+    const result = runOxlint([
+      '--fix',
+      '--no-error-on-unmatched-pattern',
+      'scripts/install-lefthook.mjs',
+    ])
+
+    expect(result.error).toBeUndefined()
+    expect(result.status, normalizedOutput(result)).toBe(0)
+  })
+
+  it('applies staged stylistic fixes before Oxlint validation', async () => {
+    const suffix = randomUUID()
+    const configPath = await writeContractConfig(suffix)
+    const directory = join(repositoryRoot, 'scripts', `.oxlint-contract-${suffix}`)
+    const path = join(directory, 'fix.ts')
+
+    try {
+      await mkdir(directory, { recursive: true })
+      await writeFile(path, 'const value={answer:1};  \nconsole.log(value)\n')
+
+      const relativePath = relative(repositoryRoot, path)
+      const formatResult = runStagedFormatter([relativePath])
+      const lintResult = runOxlint(['--config', relative(repositoryRoot, configPath), '--fix', relativePath])
+
+      expect(formatResult.error).toBeUndefined()
+      expect(formatResult.status, normalizedOutput(formatResult)).toBe(0)
+      expect(lintResult.error).toBeUndefined()
+      expect(lintResult.status, normalizedOutput(lintResult)).toBe(0)
+      await expect(readFile(path, 'utf8')).resolves.toBe('const value={ answer:1 }\nconsole.log(value)\n')
+    } finally {
+      await Promise.all([
+        rm(directory, { recursive: true, force: true }),
+        rm(configPath, { force: true }),
+      ])
+    }
+  }, 20_000)
+})
@@ -42,6 +42,18 @@ function withPnpmEntrypoint<T>(action: () => T): T {
  }
 }

+function withEnv<T>(name: string, value: string | undefined, action: () => T): T {
+  const previous = process.env[name]
+  if (value === undefined) Reflect.deleteProperty(process.env, name)
+  else process.env[name] = value
+  try {
+    return action()
+  } finally {
+    if (previous === undefined) Reflect.deleteProperty(process.env, name)
+    else process.env[name] = previous
+  }
+}
+
 describe('gate graph validation', () => {
  it.each([
    'ci-primary',
@@ -96,6 +108,32 @@ describe('gate graph validation', () => {
  })
 })

+describe('Oxlint gate', () => {
+  it('uses the package script when no worker bound is configured', () => {
+    const subject = withEnv('DSH_OXLINT_THREADS', undefined, () =>
+      withPnpmEntrypoint(() => gatesForMode('ci-lint')[0]))
+
+    expect(subject).toMatchObject({
+      id: 'lint',
+      displayCommand: 'pnpm run lint',
+      command: process.execPath,
+      args: ['/private/pnpm.cjs', 'run', 'lint'],
+    })
+  })
+
+  it('surfaces the configured worker bound on the shared package script', () => {
+    const subject = withEnv('DSH_OXLINT_THREADS', '4', () =>
+      withPnpmEntrypoint(() => gatesForMode('ci-lint')[0]))
+
+    expect(subject).toMatchObject({
+      id: 'lint',
+      displayCommand: 'DSH_OXLINT_THREADS=4 pnpm run lint',
+      command: process.execPath,
+      args: ['/private/pnpm.cjs', 'run', 'lint'],
+    })
+  })
+})
+
 describe('Node 24 consumer graph', () => {
  it('owns the seven-command pool and orders restored-artifact consumers', () => {
    const subject = withPnpmEntrypoint(() => gatesForMode('ci-consumers'))
@@ -181,10 +181,6 @@ function pnpmInvocation(args: string[]): Pick<Gate, 'command' | 'args'> {
  return { command: process.execPath, args: [entrypoint, ...args] }
 }

-function nodeOptions(...options: string[]): string {
-  return [process.env.NODE_OPTIONS, ...options].filter(option => option !== undefined && option !== '').join(' ')
-}
-
 /**
 * Construct the complete gate list for a named aggregate.
 * @param selected - aggregate mode to construct.
@@ -287,6 +283,11 @@ function nodeCompatSmokeGates(): Gate[] {
      'run',
      'packages/session-persistence/session-persistence-jsonl/tests/zstd.compat.spec.ts',
    ], { label: 'JSONL Zstandard smoke' }),
+    pnpmExec('dsh-source-launch-smoke', [
+      'vitest',
+      'run',
+      'apps/cli/tests/source-launch.compat.spec.ts',
+    ], { label: 'dsh source-launch smoke' }),
  ]
 }

@@ -375,43 +376,11 @@ function ciWindowsObservationalGates(): Gate[] {
  ]
 }

-function lintGate(eslintTargets: readonly string[] = ['.']): Gate {
-  const concurrencyArgs = eslintConcurrencyArgs()
-  if (process.env.DSH_ESLINT_CACHE === '1') {
-    return pnpmExec('lint', [
-      'eslint',
-      ...eslintTargets,
-      ...concurrencyArgs,
-      '--cache',
-      '--cache-location',
-      '.cache/eslint/',
-      '--cache-strategy',
-      'content',
-    ], {
-      label: 'lint',
-      env: { NODE_OPTIONS: nodeOptions('--max-old-space-size=8192') },
-    })
-  }
-  if (concurrencyArgs.length > 0) {
-    return pnpmExec('lint', ['eslint', ...eslintTargets, ...concurrencyArgs], {
-      label: 'lint',
-      env: { NODE_OPTIONS: nodeOptions('--max-old-space-size=8192') },
-    })
-  }
-  return pnpmScript('lint', 'lint', {
-    env: { NODE_OPTIONS: nodeOptions('--max-old-space-size=8192') },
-  })
-}
-
-function eslintConcurrencyArgs(): string[] {
-  const raw = process.env.DSH_ESLINT_CONCURRENCY
-  if (raw === undefined || raw === '') return []
-  if (raw === 'auto') return ['--concurrency=auto']
-  const parsed = Number.parseInt(raw, 10)
-  if (!Number.isSafeInteger(parsed) || parsed < 1 || String(parsed) !== raw) {
-    throw new Error(`run-gates: DSH_ESLINT_CONCURRENCY must be a positive integer or auto, got ${JSON.stringify(raw)}.`)
-  }
-  return [`--concurrency=${raw}`]
+function lintGate(): Gate {
+  const raw = process.env.DSH_OXLINT_THREADS
+  return pnpmScript('lint', 'lint', raw === undefined || raw === ''
+    ? {}
+    : { displayCommand: `DSH_OXLINT_THREADS=${raw} pnpm run lint` })
 }

 function coverageGate(): Gate {
@@ -485,7 +454,6 @@ function docSyncLeafGates(options: {
  return [
    pnpmScript('doc-typecheck', 'doc-typecheck', docTypecheckOptions),
    pnpmScript('cordis-catalog', 'verify-cordis-catalog', { label: 'cordis catalog' }),
-    pnpmScript('cordis-api', 'verify-cordis-api', { label: 'cordis api' }),
    pnpmScript('export-jsdoc', 'verify-export-jsdoc', { label: 'export jsdoc' }),
    pnpmScript('tool-catalog', 'verify-tool-catalog', { label: 'tool catalog' }),
    pnpmScript('config-catalog', 'verify-config-catalog', { label: 'config catalog' }),
@@ -0,0 +1,28 @@
+import { describe, expect, it } from 'vitest'
+import { resolveOxlintInvocation } from './run-oxlint.ts'
+
+describe('Oxlint invocation', () => {
+  it('preserves the ordinary default invocation', () => {
+    expect(resolveOxlintInvocation(['.'], { PATH: '/bin' })).toEqual({
+      args: ['.'],
+      env: { PATH: '/bin' },
+    })
+  })
+
+  it('bounds both worker pools from one setting', () => {
+    expect(resolveOxlintInvocation(['.', '--fix'], { DSH_OXLINT_THREADS: '4', GOMAXPROCS: '12' })).toEqual({
+      args: ['.', '--fix', '--threads=4'],
+      env: { DSH_OXLINT_THREADS: '4', GOMAXPROCS: '4' },
+    })
+  })
+
+  it.each(['0', '-1', '1.5', 'auto'])('rejects invalid worker bound %s', (value) => {
+    expect(() => resolveOxlintInvocation(['.'], { DSH_OXLINT_THREADS: value }))
+      .toThrow('DSH_OXLINT_THREADS must be a positive integer')
+  })
+
+  it('rejects a competing direct worker bound', () => {
+    expect(() => resolveOxlintInvocation(['.', '--threads=2'], { DSH_OXLINT_THREADS: '4' }))
+      .toThrow('use DSH_OXLINT_THREADS instead')
+  })
+})
@@ -0,0 +1,46 @@
+import { spawnSync } from 'node:child_process'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const oxlintCli = fileURLToPath(new URL('../node_modules/oxlint/bin/oxlint', import.meta.url))
+
+/** Complete Oxlint child-process arguments and environment. */
+export interface OxlintInvocation {
+  readonly args: readonly string[]
+  readonly env: NodeJS.ProcessEnv
+}
+
+/**
+ * Apply the repository worker bound to both Oxlint backends.
+ * @param args - Oxlint CLI arguments requested by the caller.
+ * @param env - Environment inherited by the Oxlint process.
+ * @returns the complete CLI arguments and child environment.
+ */
+export function resolveOxlintInvocation(args: readonly string[], env: NodeJS.ProcessEnv): OxlintInvocation {
+  const raw = env.DSH_OXLINT_THREADS
+  if (raw === undefined || raw === '') return { args: [...args], env: { ...env } }
+  const parsed = Number.parseInt(raw, 10)
+  if (!Number.isSafeInteger(parsed) || parsed < 1 || String(parsed) !== raw) {
+    throw new Error(`run-oxlint: DSH_OXLINT_THREADS must be a positive integer, got ${JSON.stringify(raw)}.`)
+  }
+  if (args.some(arg => arg === '--threads' || arg.startsWith('--threads='))) {
+    throw new Error('run-oxlint: use DSH_OXLINT_THREADS instead of passing --threads directly.')
+  }
+  return {
+    args: [...args, `--threads=${raw}`],
+    env: { ...env, GOMAXPROCS: raw },
+  }
+}
+
+function main(): void {
+  const invocation = resolveOxlintInvocation(process.argv.slice(2), process.env)
+  const result = spawnSync(process.execPath, [oxlintCli, ...invocation.args], {
+    env: invocation.env,
+    stdio: 'inherit',
+  })
+  if (result.error !== undefined) throw result.error
+  process.exitCode = result.status ?? 1
+}
+
+const entrypoint = process.argv[1]
+if (entrypoint !== undefined && resolve(entrypoint) === fileURLToPath(import.meta.url)) main()
@@ -44,7 +44,7 @@ interface InvariantHost {
 type PluginFiber = ReturnType<RegistryService['plugin']>

 const hosts = new WeakMap<Context, InvariantHost>()
-// eslint-disable-next-line @typescript-eslint/unbound-method -- every call below supplies its RegistryService receiver explicitly.
+// oxlint-disable-next-line typescript/unbound-method -- every call below supplies its RegistryService receiver explicitly.
 const originalPlugin = RegistryService.prototype.plugin

 RegistryService.prototype.plugin = function(plugin: Plugin, config?: unknown, getOuterStack?: () => string[]) {
@@ -0,0 +1,50 @@
+/** Git-blob operations owned by the bilingual pairing workflow. */
+
+import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+
+const SNAPSHOT_REF_PREFIX = 'refs/dsh/translation-pairing/snapshots'
+
+/** Full SHA-1 Git blob hash (the 40-hex format used by pairing records). */
+export function gitBlobHash(content: Buffer): string {
+  const hash = createHash('sha1')
+  hash.update(`blob ${content.byteLength}\0`)
+  hash.update(content)
+  return hash.digest('hex')
+}
+
+function runGit(root: string, args: string[], operation: string, input?: Buffer): Buffer {
+  const result = spawnSync('git', ['-C', root, ...args], {
+    input,
+    maxBuffer: 1 << 26,
+  })
+  if (result.error) {
+    throw new Error(`${operation} failed: ${result.error.message}`, { cause: result.error })
+  }
+  if (result.status !== 0) {
+    throw new Error(`${operation} failed with status ${String(result.status)}: ${result.stderr.toString('utf8').trim()}`)
+  }
+  return result.stdout
+}
+
+/**
+ * Persist exact working-tree bytes so a pairing record can later recover them
+ * with `git cat-file`, even when they have never appeared in the index or a
+ * commit. The returned object ID is checked against the pairing format's own
+ * content hash before the caller writes a sidecar.
+ */
+export function storeGitBlob(root: string, content: Buffer): string {
+  const expected = gitBlobHash(content)
+  const stored = runGit(root, ['hash-object', '-w', '--stdin'], 'git hash-object -w --stdin', content)
+    .toString('utf8')
+    .trim()
+  if (stored !== expected) {
+    throw new Error(`git hash-object -w --stdin returned unexpected object ID ${JSON.stringify(stored)}; expected ${expected}`)
+  }
+  runGit(
+    root,
+    ['update-ref', `${SNAPSHOT_REF_PREFIX}/${stored}`, stored],
+    'git update-ref for translation snapshot',
+  )
+  return stored
+}
@@ -1,6 +1,11 @@
-/** Regression tests for the bilingual corpus scope and structural signature. */
+/** Regression tests for bilingual snapshots, corpus scope, and structure. */

+import { execFileSync, spawnSync } from 'node:child_process'
+import { mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
+import { gitBlobHash, storeGitBlob } from './translation-pairing-git.ts'
 import {
  isTranslationScopeFile,
  pairAnchorOfArgument,
@@ -15,6 +20,71 @@ function signature(markdown: string) {
  return translationStructureSignature(parseTranslationMarkdown(markdown), 'counterpart.zh.md')
 }

+function gitSupportsObjectFormat(format: 'sha256'): boolean {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-git-object-format-'))
+  try {
+    return spawnSync('git', ['init', '--quiet', `--object-format=${format}`, root], {
+      stdio: 'ignore',
+    }).status === 0
+  } finally {
+    rmSync(root, { recursive: true, force: true })
+  }
+}
+
+const supportsSha256ObjectFormat = gitSupportsObjectFormat('sha256')
+
+describe('translation pairing snapshots', () => {
+  it('stores exact uncommitted bytes for later recovery by object ID', () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-'))
+    try {
+      execFileSync('git', ['init', '--quiet', root], {
+        env: { ...process.env, GIT_DEFAULT_HASH: 'sha1' },
+      })
+      const content = Buffer.from([0x75, 0x6e, 0x63, 0x6f, 0x6d, 0x6d, 0x69, 0x74, 0x74, 0x65, 0x64, 0x0a, 0xff])
+
+      const objectId = storeGitBlob(root, content)
+
+      expect(objectId).toBe(gitBlobHash(content))
+      expect(execFileSync('git', [
+        '-C', root, 'rev-parse', `refs/dsh/translation-pairing/snapshots/${objectId}`,
+      ], { encoding: 'utf8' }).trim()).toBe(objectId)
+      execFileSync('git', ['-C', root, 'gc', '--prune=now'])
+      expect(execFileSync('git', ['-C', root, 'cat-file', '-p', objectId])).toEqual(content)
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('fails before a sidecar can reference an unavailable object', () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-'))
+    try {
+      expect(() => storeGitBlob(root, Buffer.from('snapshot'))).toThrow('git hash-object -w --stdin failed')
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('fails clearly when Git cannot be started', () => {
+    const previousPath = process.env.PATH
+    try {
+      process.env.PATH = ''
+      expect(() => storeGitBlob('.', Buffer.from('snapshot'))).toThrow('git hash-object -w --stdin failed')
+    } finally {
+      process.env.PATH = previousPath
+    }
+  })
+
+  it.skipIf(!supportsSha256ObjectFormat)('rejects an object format that pairing records cannot represent', () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-translation-pairing-'))
+    try {
+      execFileSync('git', ['init', '--quiet', '--object-format=sha256', root])
+      expect(() => storeGitBlob(root, Buffer.from('snapshot'))).toThrow('returned unexpected object ID')
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+})
+
 describe('translation pairing manifest', () => {
  it('accepts an exclusions-only manifest', () => {
    expect(parseTranslationPairingManifest(JSON.stringify({
@@ -1,14 +0,0 @@
-/** Register source-only tsconfig paths resolution before a TypeScript entry loads. */
-
-import { register } from 'node:module'
-import { resolve } from 'node:path'
-import { fileURLToPath } from 'node:url'
-
-const tsconfigPath = process.env.TSX_TSCONFIG_PATH === undefined
-  ? fileURLToPath(new URL('../tsconfig.json', import.meta.url))
-  : resolve(process.env.TSX_TSCONFIG_PATH)
-
-register(new URL('../apps/cli/src/tsconfig-paths-loader.ts', import.meta.url), {
-  parentURL: import.meta.url,
-  data: { tsconfigPath },
-})
@@ -91,6 +91,26 @@
      "symbol": "InboxPlacement",
      "source": "packages/core/agent/src/types.ts"
    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "InboxItem",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "InboxAction",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "InboxActionResult",
+      "source": "packages/core/agent/src/types.ts"
+    },
+    {
+      "doc": "docs/core-data-structures/core.md",
+      "symbol": "SendOptions",
+      "source": "packages/core/agent/src/types.ts"
+    },
    {
      "doc": "docs/core-data-structures/core.md",
      "symbol": "CancelOptions",
@@ -954,11 +974,21 @@
      "symbol": "SkillResourceBase",
      "source": "packages/skill/skill/src/index.ts"
    },
+    {
+      "doc": "docs/core-data-structures/skills.md",
+      "symbol": "SkillInvocationPolicy",
+      "source": "packages/skill/skill/src/index.ts"
+    },
    {
      "doc": "docs/core-data-structures/skills.md",
      "symbol": "SkillSummary",
      "source": "packages/skill/skill/src/index.ts"
    },
+    {
+      "doc": "docs/core-data-structures/skills.md",
+      "symbol": "SkillCatalogSnapshot",
+      "source": "packages/skill/skill/src/index.ts"
+    },
    {
      "doc": "docs/core-data-structures/skills.md",
      "symbol": "SkillCandidate",
@@ -979,11 +1009,21 @@
      "symbol": "SkillLookupOptions",
      "source": "packages/skill/skill/src/index.ts"
    },
+    {
+      "doc": "docs/core-data-structures/skills.md",
+      "symbol": "SkillProviderObservation",
+      "source": "packages/skill/skill/src/index.ts"
+    },
    {
      "doc": "docs/core-data-structures/skills.md",
      "symbol": "SkillProvider",
      "source": "packages/skill/skill/src/index.ts"
    },
+    {
+      "doc": "docs/core-data-structures/skills.md",
+      "symbol": "SkillProviderControl",
+      "source": "packages/skill/skill/src/index.ts"
+    },
    {
      "doc": "docs/core-data-structures/skills.md",
      "symbol": "Config",
@@ -126,7 +126,7 @@ function heritageExemption(
          returnType = d.type.type
        } else continue
        baseParams ??= new Set()
-        // Leading underscores are the deliberately-unused marker (eslint
+        // Leading underscores are the deliberately-unused marker (lint
        // argsIgnorePattern), not a rename: `_cwd` overriding `cwd` is the
        // same parameter, so compare underscore-stripped on both sides.
        for (const p of params) if (ts.isIdentifier(p.name)) baseParams.add(p.name.text.replace(/^_+/, ''))
@@ -45,6 +45,8 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
  'packages/bash/bash-local': { kind: 'indirect', reason: 'The executor backend delegates model rendering to dsh-tool-bash.' },
  'packages/code-runtime/code-runtime': { kind: 'indirect', reason: 'The service interface delegates model rendering to Code Mode in dsh-tools.' },
  'packages/code-runtime/code-runtime-worker': { kind: 'indirect', reason: 'The worker backend delegates model rendering to Code Mode in dsh-tools.' },
+  'packages/typert/registry': { kind: 'none', reason: 'Runtime type registry; consumers (cordis_inspect, wire faces, gates) own any model-visible projection of registry contents.' },
+  'packages/typert/loader': { kind: 'none', reason: 'Loader integration only registers generated artifacts; consumers own any model-visible projection.' },
  'packages/client/hmr': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
  'packages/client/modules': { kind: 'none', reason: 'Browser-side module-loading kernel machinery; registers no model surface.' },
  'packages/client/test-runtime': { kind: 'none', reason: 'Browser-side test infrastructure (jsdom bench); registers no model surface.' },
@@ -60,6 +62,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
  'packages/client/ui-command': { kind: 'indirect', reason: 'The dispatch paths trigger the host command.execute RPC; each command handler\'s host package owns any model-visible effect.' },
  'packages/client/ui-model': { kind: 'indirect', reason: 'Selection routes session.selectModel; the host snapshots the target at the next prompt-assembly boundary and owns the model-visible effect.' },
  'packages/client/ui-goal': { kind: 'indirect', reason: 'The strip verbs route goal.* mutations; the host GoalService owns the model-visible goal/change context message.' },
+  'packages/client/ui-permission': { kind: 'indirect', reason: 'The picker submits the host /permission command; the knob events it appends own the model-visible effect through the sandbox/approval consumers.' },
  'packages/client/ui-plan': { kind: 'indirect', reason: 'The chip dispatches /plan off; dsh-plan-mode owns the model-visible policy, exit tool, and logged state.' },
  'packages/client/ui-question': { kind: 'indirect', reason: 'The package mounts dsh-tool-ask-user; that tool owns the model-visible schema and answer rendering.' },
  'packages/client/ui-trajectory': { kind: 'none', reason: 'Browser-side UI plugin layer; registers no model surface.' },
@@ -111,6 +114,7 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
  'packages/support/loader-smoke': { kind: 'none', reason: 'The test harness observes child-process streams without changing live requests.' },
  'packages/support/llm-mock-server': { kind: 'none', reason: 'The test server substitutes provider wire behavior without invoking a real model.' },
  'packages/support/llm-replay': { kind: 'none', reason: 'The keyless adapter invokes no provider model.' },
+  'packages/typert/generator': { kind: 'none', reason: 'The build-time generator runs outside any agent runtime and touches no model request.' },
  'packages/tasks/tasks': { kind: 'indirect', reason: 'Producer and control-surface plugins own all model rendering over the task registry.' },
  'packages/tasks/tasks-local': { kind: 'indirect', reason: 'The registry backend delegates model rendering to producer plugins and dsh-tool-tasks.' },
  'packages/examples/acp-demo': { kind: 'indirect', reason: 'The app bundle delegates request composition to dsh-agent-spine-demo and dsh-acp.' },
@@ -9,9 +9,9 @@
 * See `docs/i18n/README.md` for the owning contract.
 */

-import { createHash } from 'node:crypto'
 import { existsSync, globSync, readFileSync, writeFileSync } from 'node:fs'
 import { basename, join, resolve, sep } from 'node:path'
+import { gitBlobHash, storeGitBlob } from './translation-pairing-git.ts'
 import {
  linksTo,
  parseTranslationMarkdown,
@@ -54,14 +54,6 @@ function isExcluded(file: string): boolean {
  return manifest.excluded.some(entry => (entry.endsWith('/') ? file.startsWith(entry) : file === entry))
 }

-/** Full git blob hash (what `git hash-object` prints). */
-function blobHash(content: Buffer): string {
-  const hash = createHash('sha1')
-  hash.update(`blob ${content.byteLength}\0`)
-  hash.update(content)
-  return hash.digest('hex')
-}
-
 /** The three paths of a pair, derived from the English-file path. */
 function pairPaths(source: string): { zh: string; meta: string } {
  return { zh: source.replace(/\.md$/, '.zh.md'), meta: source.replace(/\.md$/, '.i18n.yaml') }
@@ -148,7 +140,12 @@ if (writeMode) {
      }
      continue
    }
-    const record = renderMeta(source, blobHash(readFileSync(join(root, source))), zh, blobHash(readFileSync(join(root, zh))))
+    const sourceContent = readFileSync(join(root, source))
+    const zhContent = readFileSync(join(root, zh))
+    // A consistency record is also a recovery pointer for the briefing
+    // generator. Persist both snapshots even when the sidecar text is already
+    // current, because the bytes may exist only in this working tree.
+    const record = renderMeta(source, storeGitBlob(root, sourceContent), zh, storeGitBlob(root, zhContent))
    if (existsSync(join(root, meta)) && readFileSync(join(root, meta), 'utf8') === record) continue
    writeFileSync(join(root, meta), record)
    console.log(`verify-translation-pairing: recorded ${meta}`)
@@ -203,7 +200,7 @@ for (const source of [...pairAnchors].sort()) {

  let consistent = true
  for (const [file, content] of [[source, sourceContent], [zh, zhContent]] as const) {
-    const current = blobHash(content)
+    const current = gitBlobHash(content)
    if (record.get(basename(file)) !== current) {
      errors.push(`${file}: out of sync — content no longer matches the pair's last confirmed-consistent state in ${meta} (bring the other side along, then re-record with --write)`)
      consistent = false