Add files using upload-large-folder tool

scripts/archived-agent-notes.spec.ts

@@ -0,0 +1,95 @@
+import { describe, expect, it } from 'vitest'
+import {
+  extendArchiveManifest,
+  gitBlobHash,
+  parseArchiveManifest,
+  renderArchiveManifest,
+  validateArchiveArtifacts,
+  validateArchiveManifestExtension,
+  type ArchiveManifest,
+} from './archived-agent-notes.ts'
+import { isArchivedAgentNotePath } from './repo-files.ts'
+
+function fixture(): Map<string, Buffer> {
+  const base = '2026-07-26-example'
+  const source = Buffer.from(`# Agent Note: Example\n\nStatus: implemented\nArchived: 2026-07-26\n\nEnglish | [中文](${base}.zh.md)\n\n## Problem\n\nExample.\n`)
+  const zh = Buffer.from(`# Agent Note: 示例\n\nStatus: implemented\nArchived: 2026-07-26\n\n[English](${base}.md) | 中文\n\n## 问题\n\n示例。\n`)
+  const meta = Buffer.from(`${base}.md: ${gitBlobHash(source)}\n${base}.zh.md: ${gitBlobHash(zh)}\n`)
+  return new Map([
+    [`process/${base}.md`, source],
+    [`process/${base}.zh.md`, zh],
+    [`process/${base}.i18n.yaml`, meta],
+  ])
+}
+
+describe('archived Agent Notes', () => {
+  it('recognizes archived paths with POSIX and Windows separators', () => {
+    expect(isArchivedAgentNotePath('.agents/notes/archived/process/example.md')).toBe(true)
+    expect(isArchivedAgentNotePath('.agents\\notes\\archived\\process\\example.md')).toBe(true)
+    expect(isArchivedAgentNotePath('.agents/notes/implemented/process/example.md')).toBe(false)
+  })
+
+  it('accepts one complete implemented triplet with matching archive metadata', () => {
+    expect(validateArchiveArtifacts(fixture())).toEqual([])
+  })
+
+  it('rejects incomplete triplets and invalid archive headers', () => {
+    const artifacts = fixture()
+    artifacts.delete('process/2026-07-26-example.i18n.yaml')
+    artifacts.set(
+      'process/2026-07-26-example.md',
+      Buffer.from('# Agent Note: Example\n\nStatus: proposed\nArchived: yesterday\n'),
+    )
+    expect(validateArchiveArtifacts(artifacts).join('\n')).toMatch(/incomplete archived triplet/)
+  })
+
+  it('extends the manifest without permitting a sealed change or removal', () => {
+    const artifacts = fixture()
+    const empty: ArchiveManifest = { version: 1, files: {} }
+    const first = extendArchiveManifest(empty, artifacts)
+    expect(first.errors).toEqual([])
+    expect(first.added).toHaveLength(3)
+
+    const sealed: ArchiveManifest = { version: 1, files: first.files }
+    const changed = new Map(artifacts)
+    changed.set('process/2026-07-26-example.md', Buffer.from('changed'))
+    expect(extendArchiveManifest(sealed, changed).errors).toEqual([
+      'process/2026-07-26-example.md: sealed content hash changed',
+    ])
+    changed.delete('process/2026-07-26-example.zh.md')
+    expect(extendArchiveManifest(sealed, changed).errors).toContain(
+      'process/2026-07-26-example.zh.md: sealed artifact is missing',
+    )
+  })
+
+  it('rejects replacing manifest seals alongside changed archive content', () => {
+    const artifacts = fixture()
+    const initial = extendArchiveManifest({ version: 1, files: {} }, artifacts)
+    const baseline: ArchiveManifest = { version: 1, files: initial.files }
+    const path = 'process/2026-07-26-example.md'
+    const changedArtifacts = new Map(artifacts)
+    changedArtifacts.set(path, Buffer.from('changed'))
+    const replacement = extendArchiveManifest({ version: 1, files: {} }, changedArtifacts)
+    const current: ArchiveManifest = { version: 1, files: replacement.files }
+
+    expect(extendArchiveManifest(current, changedArtifacts).errors).toEqual([])
+    expect(validateArchiveManifestExtension(baseline, current)).toEqual([
+      `${path}: sealed manifest hash changed`,
+    ])
+    const removed: ArchiveManifest = {
+      version: 1,
+      files: Object.fromEntries(Object.entries(current.files).filter(([candidate]) => candidate !== path)),
+    }
+    expect(validateArchiveManifestExtension(baseline, removed)).toContain(
+      `${path}: sealed manifest entry is missing`,
+    )
+  })
+
+  it('round-trips the deterministic manifest schema', () => {
+    const content = renderArchiveManifest({ 'process/z.md': `sha256:${'a'.repeat(64)}` })
+    expect(parseArchiveManifest(content)).toEqual({
+      version: 1,
+      files: { 'process/z.md': `sha256:${'a'.repeat(64)}` },
+    })
+  })
+})

scripts/benchmark-npm-resolution.ts

@@ -0,0 +1,551 @@
+/** Benchmark npm's dependency-tree resolution against an all-local registry. */
+
+import { execFileSync, spawn, spawnSync, type ChildProcess } from 'node:child_process'
+import { globSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { createServer, type Server } from 'node:http'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { performance } from 'node:perf_hooks'
+import { parseArgs } from 'node:util'
+
+const TARGET_PACKAGE = '@deepseek-ai/dsh'
+const DEFAULT_TIMEOUT_MS = 300_000
+const TERMINATION_GRACE_MS = 1_000
+const FORCED_EXIT_TIMEOUT_MS = 5_000
+const WORKSPACE_MANIFEST_GLOBS = [
+  'apps/*/package.json',
+  'packages/*/*/package.json',
+  'vendor/*/package.json',
+  'native/system/package.json',
+  'native/system/packages/*/package.json',
+]
+const INSTALLED_MANIFEST_GLOBS = [
+  'node_modules/.pnpm/*/node_modules/*/package.json',
+  'node_modules/.pnpm/*/node_modules/@*/*/package.json',
+]
+const PUBLISHED_FIELDS = [
+  'dependencies',
+  'optionalDependencies',
+  'peerDependencies',
+  'peerDependenciesMeta',
+  'engines',
+  'os',
+  'cpu',
+  'bin',
+] as const
+
+interface PackageManifest {
+  readonly name?: unknown
+  readonly version?: unknown
+  readonly dependencies?: Record<string, string>
+  readonly optionalDependencies?: Record<string, string>
+  readonly peerDependencies?: Record<string, string>
+  readonly peerDependenciesMeta?: Record<string, unknown>
+  readonly engines?: unknown
+  readonly os?: unknown
+  readonly cpu?: unknown
+  readonly bin?: unknown
+}
+
+interface RegistryVersion extends PackageManifest {
+  readonly name: string
+  readonly version: string
+}
+
+/** Package versions served by the local benchmark registry. */
+export type RegistryIndex = ReadonlyMap<string, ReadonlyMap<string, RegistryVersion>>
+
+/** Parsed command-line options for one benchmark invocation. */
+export interface BenchmarkOptions {
+  readonly ref?: string
+  readonly runs: number
+  readonly timeoutMs: number
+  readonly maxMs?: number
+}
+
+/** One measured npm resolution. */
+export interface BenchmarkRun {
+  readonly durationMs: number
+  readonly registryRequests: number
+  readonly archiveRequests: number
+  readonly unknownPackages: readonly string[]
+}
+
+/** Published-package fields retained in npm's package-lock layout. */
+export interface NpmLockPackage {
+  readonly name?: string
+  readonly version?: string
+  readonly dependencies?: Readonly<Record<string, string>>
+  readonly optionalDependencies?: Readonly<Record<string, string>>
+  readonly peerDependencies?: Readonly<Record<string, string>>
+  readonly peerDependenciesMeta?: Readonly<Record<string, { readonly optional?: boolean }>>
+}
+
+/** The installed paths selected by npm without materializing package archives. */
+export interface NpmPackageLock {
+  readonly lockfileVersion: number
+  readonly packages: Readonly<Record<string, NpmLockPackage>>
+}
+
+/** npm resolution observations together with its computed install layout. */
+export interface NpmPackageLockResolution extends BenchmarkRun {
+  readonly packageLock: NpmPackageLock
+}
+
+/** Parse one positive-integer command-line option or use its default. */
+export function parsePositiveIntegerOption(raw: string | undefined, fallback: number, name: string): number {
+  if (raw === undefined) return fallback
+  const value = Number.parseInt(raw, 10)
+  if (!Number.isSafeInteger(value) || value < 1 || String(value) !== raw) {
+    throw new Error(`${name} must be a positive integer, got ${JSON.stringify(raw)}`)
+  }
+  return value
+}
+
+/**
+ * Parse supported benchmark arguments.
+ * @param args - Command-line arguments after the script path.
+ * @returns Validated benchmark options.
+ */
+export function parseBenchmarkOptions(args: readonly string[]): BenchmarkOptions {
+  const normalized = args[0] === '--' ? args.slice(1) : args
+  const { values } = parseArgs({
+    args: [...normalized],
+    options: {
+      ref: { type: 'string' },
+      runs: { type: 'string' },
+      'timeout-ms': { type: 'string' },
+      'max-ms': { type: 'string' },
+    },
+    allowPositionals: false,
+  })
+  const maxMs = values['max-ms'] === undefined
+    ? undefined
+    : parsePositiveIntegerOption(values['max-ms'], 0, '--max-ms')
+  return {
+    runs: parsePositiveIntegerOption(values.runs, 1, '--runs'),
+    timeoutMs: parsePositiveIntegerOption(values['timeout-ms'], DEFAULT_TIMEOUT_MS, '--timeout-ms'),
+    ...(values.ref === undefined ? {} : { ref: values.ref }),
+    ...(maxMs === undefined ? {} : { maxMs }),
+  }
+}
+
+function workspaceManifestPath(path: string): boolean {
+  return /^(?:apps\/[^/]+|packages\/[^/]+\/[^/]+|vendor\/[^/]+|native\/system(?:\/packages\/[^/]+)?)\/package\.json$/.test(path)
+}
+
+function workspaceManifestPaths(root: string, ref: string | undefined): string[] {
+  if (ref === undefined) return globSync(WORKSPACE_MANIFEST_GLOBS, { cwd: root }).sort()
+  return execFileSync('git', ['ls-tree', '-r', '--name-only', ref, '--', 'apps', 'packages', 'vendor', 'native'], {
+    cwd: root,
+    encoding: 'utf8',
+  }).split('\n').filter(workspaceManifestPath).sort()
+}
+
+function readGitFiles(root: string, ref: string, paths: readonly string[]): ReadonlyMap<string, string> {
+  const output = execFileSync('git', ['cat-file', '--batch'], {
+    cwd: root,
+    input: paths.map(path => `${ref}:${path}\n`).join(''),
+    maxBuffer: 64 * 1024 * 1024,
+  })
+  const contents = new Map<string, string>()
+  let offset = 0
+  for (const path of paths) {
+    const headerEnd = output.indexOf(0x0a, offset)
+    if (headerEnd < 0) throw new Error(`git cat-file returned no header for ${ref}:${path}`)
+    const header = output.subarray(offset, headerEnd).toString('utf8')
+    if (header.endsWith(' missing')) throw new Error(`git ref ${ref} has no ${path}`)
+    const size = Number.parseInt(header.split(' ')[2] ?? '', 10)
+    if (!Number.isSafeInteger(size) || size < 0) {
+      throw new Error(`git cat-file returned an invalid size for ${ref}:${path}`)
+    }
+    const contentStart = headerEnd + 1
+    const contentEnd = contentStart + size
+    if (output[contentEnd] !== 0x0a) throw new Error(`git cat-file truncated ${ref}:${path}`)
+    contents.set(path, output.subarray(contentStart, contentEnd).toString('utf8'))
+    offset = contentEnd + 1
+  }
+  return contents
+}
+
+/**
+ * Convert a workspace protocol range to the range published by pnpm pack.
+ * @param range - Dependency range from a workspace manifest.
+ * @param targetVersion - Current version of the referenced workspace package.
+ * @returns The registry-facing semver range.
+ */
+export function publishWorkspaceRange(range: string, targetVersion: string): string {
+  if (range === 'workspace:*') return targetVersion
+  if (range === 'workspace:^') return `^${targetVersion}`
+  if (range === 'workspace:~') return `~${targetVersion}`
+  if (range.startsWith('workspace:')) return range.slice('workspace:'.length)
+  return range
+}
+
+function copyPublishedManifest(
+  source: PackageManifest,
+  workspaceVersions: ReadonlyMap<string, string>,
+): RegistryVersion | undefined {
+  if (typeof source.name !== 'string' || typeof source.version !== 'string') return undefined
+  const output: Record<string, unknown> = { name: source.name, version: source.version }
+  for (const field of PUBLISHED_FIELDS) {
+    const value = source[field]
+    if (value === undefined) continue
+    if (field === 'dependencies' || field === 'optionalDependencies' || field === 'peerDependencies') {
+      output[field] = Object.fromEntries(Object.entries(value as Record<string, string>).map(([name, range]) => {
+        const targetVersion = workspaceVersions.get(name)
+        return [name, targetVersion === undefined ? range : publishWorkspaceRange(range, targetVersion)]
+      }))
+    } else {
+      output[field] = structuredClone(value)
+    }
+  }
+  return output as unknown as RegistryVersion
+}
+
+function addManifest(index: Map<string, Map<string, RegistryVersion>>, manifest: RegistryVersion): void {
+  const versions = index.get(manifest.name) ?? new Map<string, RegistryVersion>()
+  versions.set(manifest.version, manifest)
+  index.set(manifest.name, versions)
+}
+
+/**
+ * Build registry metadata from installed external packages and workspace manifests.
+ * @param root - Repository root containing the pnpm virtual store.
+ * @param ref - Optional Git ref used instead of working-tree workspace manifests.
+ * @returns Package metadata served by the benchmark registry.
+ */
+export function buildRegistryIndex(root: string, ref?: string): RegistryIndex {
+  const index = new Map<string, Map<string, RegistryVersion>>()
+  for (const path of globSync(INSTALLED_MANIFEST_GLOBS, { cwd: root }).sort()) {
+    const manifest = JSON.parse(readFileSync(resolve(root, path), 'utf8')) as PackageManifest
+    const copied = copyPublishedManifest(manifest, new Map())
+    if (copied !== undefined) addManifest(index, copied)
+  }
+
+  const paths = workspaceManifestPaths(root, ref)
+  const refContents = ref === undefined ? undefined : readGitFiles(root, ref, paths)
+  const workspace = paths.map(path =>
+    JSON.parse(refContents?.get(path) ?? readFileSync(resolve(root, path), 'utf8')) as PackageManifest)
+  const workspaceVersions = new Map(workspace.flatMap(manifest =>
+    typeof manifest.name === 'string' && typeof manifest.version === 'string'
+      ? [[manifest.name, manifest.version] as const]
+      : []))
+  for (const manifest of workspace) {
+    const copied = copyPublishedManifest(manifest, workspaceVersions)
+    if (copied !== undefined) addManifest(index, copied)
+  }
+  return index
+}
+
+function latestVersion(versions: ReadonlyMap<string, RegistryVersion>): string {
+  const sorted = [...versions.keys()].sort((left, right) => left.localeCompare(right, 'en', { numeric: true }))
+  const latest = sorted.at(-1)
+  if (latest === undefined) throw new Error('local registry package has no versions')
+  return latest
+}
+
+function listen(server: Server): Promise<number> {
+  return new Promise((resolveListen, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', () => {
+      server.off('error', reject)
+      const address = server.address()
+      if (address === null || typeof address === 'string') {
+        reject(new Error('local registry did not expose a TCP port'))
+        return
+      }
+      resolveListen(address.port)
+    })
+  })
+}
+
+function close(server: Server): Promise<void> {
+  return new Promise((resolveClose, reject) => {
+    server.close((error) => {
+      if (error === undefined) resolveClose()
+      else reject(error)
+    })
+  })
+}
+
+function npmExecutable(): string {
+  return process.platform === 'win32' ? 'npm.cmd' : 'npm'
+}
+
+function delay(ms: number): Promise<void> {
+  return new Promise(resolveDelay => setTimeout(resolveDelay, ms))
+}
+
+function signalProcessTree(child: ChildProcess, signal: 'SIGTERM' | 'SIGKILL'): void {
+  if (child.pid === undefined) {
+    child.kill(signal)
+    return
+  }
+  if (process.platform === 'win32') {
+    const force = signal === 'SIGKILL' ? ['/F'] : []
+    const result = spawnSync('taskkill', ['/PID', String(child.pid), '/T', ...force], {
+      stdio: 'ignore',
+      windowsHide: true,
+    })
+    if (result.error !== undefined) throw result.error
+    if (result.status !== 0 && child.exitCode === null && child.signalCode === null) child.kill(signal)
+    return
+  }
+  try {
+    process.kill(-child.pid, signal)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code !== 'ESRCH') throw error
+  }
+}
+
+/**
+ * Run one command with bounded process-tree termination after its deadline.
+ * @param command - Executable path or name.
+ * @param args - Arguments passed without shell interpolation on POSIX.
+ * @param options - Working directory, environment, timeout, and termination grace.
+ * @returns Exit facts, captured output, duration, and whether timeout handling began.
+ */
+export async function runCommandWithTimeout(
+  command: string,
+  args: readonly string[],
+  options: {
+    readonly cwd: string
+    readonly env: NodeJS.ProcessEnv
+    readonly timeoutMs: number
+    readonly terminationGraceMs?: number
+  },
+): Promise<{ status: number | null; signal: NodeJS.Signals | null; durationMs: number; output: string; timedOut: boolean }> {
+  const started = performance.now()
+  const child = spawn(command, [...args], {
+    cwd: options.cwd,
+    detached: process.platform !== 'win32',
+    env: options.env,
+    shell: process.platform === 'win32',
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  let output = ''
+  child.stdout.setEncoding('utf8')
+  child.stderr.setEncoding('utf8')
+  child.stdout.on('data', (chunk) => { output += String(chunk) })
+  child.stderr.on('data', (chunk) => { output += String(chunk) })
+  const exited = new Promise<{ status: number | null; signal: NodeJS.Signals | null }>((resolveExit, reject) => {
+    child.once('error', reject)
+    child.once('close', (status, signal) => { resolveExit({ status, signal }) })
+  })
+  let timeout: NodeJS.Timeout | undefined
+  try {
+    const first = await Promise.race([
+      exited.then(outcome => ({ type: 'exit' as const, outcome })),
+      new Promise<{ type: 'timeout' }>((resolveTimeout) => {
+        timeout = setTimeout(() => { resolveTimeout({ type: 'timeout' }) }, options.timeoutMs)
+      }),
+    ])
+    if (first.type === 'exit') {
+      return { ...first.outcome, durationMs: performance.now() - started, output, timedOut: false }
+    }
+
+    signalProcessTree(child, 'SIGTERM')
+    await delay(options.terminationGraceMs ?? TERMINATION_GRACE_MS)
+    signalProcessTree(child, 'SIGKILL')
+    const forced = await Promise.race([
+      exited,
+      delay(FORCED_EXIT_TIMEOUT_MS).then(() => undefined),
+    ])
+    if (forced === undefined) throw new Error('timed-out process tree did not exit after SIGKILL')
+    return { ...forced, durationMs: performance.now() - started, output, timedOut: true }
+  } finally {
+    if (timeout !== undefined) clearTimeout(timeout)
+  }
+}
+
+function readNpmPackageLock(path: string): NpmPackageLock {
+  const parsed: unknown = JSON.parse(readFileSync(path, 'utf8'))
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error('npm produced an invalid package-lock.json')
+  }
+  const { lockfileVersion, packages } = parsed as Record<string, unknown>
+  if (!Number.isSafeInteger(lockfileVersion) || packages === null
+    || typeof packages !== 'object' || Array.isArray(packages)) {
+    throw new Error('npm produced an invalid package-lock.json')
+  }
+  return parsed as NpmPackageLock
+}
+
+async function runNpm(
+  cwd: string,
+  registry: string,
+  timeoutMs: number,
+): Promise<{ durationMs: number; output: string; timedOut: boolean }> {
+  const npmrc = join(cwd, '.npmrc')
+  const globalNpmrc = join(cwd, '.npmrc-global')
+  writeFileSync(npmrc, `registry=${registry}\n@deepseek-ai:registry=${registry}\n`)
+  writeFileSync(globalNpmrc, '')
+  const inheritedEnvironment = Object.fromEntries(Object.entries(process.env)
+    .filter(([name]) => !name.toLowerCase().startsWith('npm_config_')))
+  const result = await runCommandWithTimeout(npmExecutable(), [
+    'install',
+    '--package-lock-only',
+    '--ignore-scripts',
+    '--no-audit',
+    '--no-fund',
+    '--loglevel=error',
+    '--include=peer',
+    '--install-strategy=hoisted',
+    '--legacy-peer-deps=false',
+    `--registry=${registry}`,
+  ], {
+    cwd,
+    env: {
+      ...inheritedEnvironment,
+      npm_config_cache: join(cwd, '.npm-cache'),
+      npm_config_globalconfig: globalNpmrc,
+      npm_config_userconfig: npmrc,
+      npm_config_update_notifier: 'false',
+    },
+    timeoutMs,
+  })
+  if (result.timedOut) return result
+  if (result.status !== 0) {
+    throw new Error(`npm install exited ${String(result.status)} after ${result.durationMs.toFixed(0)} ms\n${result.output.trim()}`)
+  }
+  return result
+}
+
+/**
+ * Ask npm to compute an install layout without downloading package archives.
+ * @param index - Package metadata exposed through the local registry.
+ * @param dependencies - Root dependencies whose install layout npm computes.
+ * @param timeoutMs - Hard wall-clock limit for the npm child process.
+ * @returns The package lock plus timing and registry-request observations.
+ */
+export async function resolveNpmPackageLock(
+  index: RegistryIndex,
+  dependencies: Readonly<Record<string, string>>,
+  timeoutMs: number,
+): Promise<NpmPackageLockResolution> {
+  let registryRequests = 0
+  let archiveRequests = 0
+  const unknownPackages = new Set<string>()
+  let registry = ''
+  const server = createServer((request, response) => {
+    registryRequests++
+    const pathname = new URL(request.url ?? '/', registry).pathname
+    if (pathname.startsWith('/tarballs/')) {
+      archiveRequests++
+      response.writeHead(500, { 'content-type': 'application/json' })
+      response.end(JSON.stringify({ error: 'package-lock-only benchmark requested an archive' }))
+      return
+    }
+    const name = decodeURIComponent(pathname.slice(1))
+    const versions = index.get(name)
+    if (versions === undefined) {
+      unknownPackages.add(name)
+      response.writeHead(404, { 'content-type': 'application/json' })
+      response.end(JSON.stringify({ error: 'not_found' }))
+      return
+    }
+    const materialized = Object.fromEntries([...versions].map(([version, manifest]) => [version, {
+      ...manifest,
+      dist: { tarball: `${registry}tarballs/${encodeURIComponent(name)}-${version}.tgz` },
+    }]))
+    const body = JSON.stringify({
+      name,
+      'dist-tags': { latest: latestVersion(versions) },
+      versions: materialized,
+    })
+    response.writeHead(200, {
+      'content-type': 'application/json',
+      'content-length': Buffer.byteLength(body),
+    })
+    response.end(body)
+  })
+  const port = await listen(server)
+  registry = `http://127.0.0.1:${String(port)}/`
+  const consumer = mkdtempSync(join(tmpdir(), 'dsh-npm-resolution-'))
+  try {
+    writeFileSync(join(consumer, 'package.json'), `${JSON.stringify({
+      name: 'dsh-npm-resolution-benchmark',
+      version: '0.0.0',
+      private: true,
+      dependencies,
+    }, null, 2)}\n`)
+    const result = await runNpm(consumer, registry, timeoutMs)
+    if (result.timedOut) throw new Error(`npm resolution exceeded ${String(timeoutMs)} ms`)
+    return {
+      durationMs: result.durationMs,
+      registryRequests,
+      archiveRequests,
+      unknownPackages: [...unknownPackages].sort(),
+      packageLock: readNpmPackageLock(join(consumer, 'package-lock.json')),
+    }
+  } finally {
+    server.closeAllConnections()
+    await close(server)
+    rmSync(consumer, { recursive: true, force: true })
+  }
+}
+
+/**
+ * Resolve the CLI install graph once without downloading package archives.
+ * @param index - Package metadata exposed through the local registry.
+ * @param targetVersion - Version of `@deepseek-ai/dsh` to install.
+ * @param timeoutMs - Hard wall-clock limit for the npm child process.
+ * @returns Timing and registry-request observations.
+ */
+export async function benchmarkNpmResolution(
+  index: RegistryIndex,
+  targetVersion: string,
+  timeoutMs: number,
+): Promise<BenchmarkRun> {
+  const result = await resolveNpmPackageLock(index, { [TARGET_PACKAGE]: targetVersion }, timeoutMs)
+  return {
+    durationMs: result.durationMs,
+    registryRequests: result.registryRequests,
+    archiveRequests: result.archiveRequests,
+    unknownPackages: result.unknownPackages,
+  }
+}
+
+async function main(): Promise<void> {
+  const options = parseBenchmarkOptions(process.argv.slice(2))
+  const root = resolve(import.meta.dirname, '..')
+  const started = performance.now()
+  const index = buildRegistryIndex(root, options.ref)
+  const targetVersions = index.get(TARGET_PACKAGE)
+  if (targetVersions === undefined) throw new Error(`local registry contains no ${TARGET_PACKAGE}`)
+  const targetVersion = latestVersion(targetVersions)
+  const npmVersion = execFileSync(npmExecutable(), ['--version'], { encoding: 'utf8' }).trim()
+  console.log(
+    `benchmark-npm-resolution: npm ${npmVersion}, ${options.ref === undefined ? 'working tree' : options.ref}, `
+    + `${String(index.size)} package name(s), setup ${(performance.now() - started).toFixed(0)} ms.`,
+  )
+  const durations: number[] = []
+  for (let run = 1; run <= options.runs; run++) {
+    const result = await benchmarkNpmResolution(index, targetVersion, options.timeoutMs)
+    durations.push(result.durationMs)
+    console.log(
+      `benchmark-npm-resolution: run ${String(run)}/${String(options.runs)} resolved ${TARGET_PACKAGE}@${targetVersion}`
+      + ` in ${(result.durationMs / 1000).toFixed(2)} s with ${String(result.registryRequests)} metadata request(s)`
+      + ` and ${String(result.unknownPackages.length)} local 404 package name(s).`,
+    )
+    if (result.archiveRequests > 0) throw new Error('npm requested package archives during the metadata-only benchmark')
+  }
+  const minimum = Math.min(...durations)
+  const maximum = Math.max(...durations)
+  console.log(
+    `benchmark-npm-resolution: ${String(options.runs)} run(s), min ${(minimum / 1000).toFixed(2)} s, max ${(maximum / 1000).toFixed(2)} s.`,
+  )
+  if (options.maxMs !== undefined && maximum > options.maxMs) {
+    throw new Error(`npm resolution exceeded --max-ms=${String(options.maxMs)} (max ${maximum.toFixed(0)} ms)`)
+  }
+}
+
+if (import.meta.main) {
+  try {
+    await main()
+  } catch (error) {
+    console.error(`benchmark-npm-resolution: ${error instanceof Error ? error.message : String(error)}`)
+    process.exitCode = 1
+  }
+}

scripts/build-exe-for-python-sdk-native-pty.spec.ts

@@ -0,0 +1,67 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { resolveLinuxNodePtyAddon, resolveWindowsNodePtyAddons } from './build-exe-for-python-sdk-native-pty.ts'
+
+const roots: string[] = []
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+describe('resolveLinuxNodePtyAddon', () => {
+  it('prefers the manylinux build produced by the release workflow', () => {
+    const root = temporaryPackage()
+    const built = createAddon(root, 'build', 'Release', 'pty.node')
+    createAddon(root, 'prebuilds', 'linux-x64', 'pty.node')
+
+    expect(resolveLinuxNodePtyAddon(root, 'x64')).toBe(built)
+  })
+
+  it('uses the target prebuild after an ordinary beta install', () => {
+    const root = temporaryPackage()
+    const prebuilt = createAddon(root, 'prebuilds', 'linux-arm64', 'pty.node')
+
+    expect(resolveLinuxNodePtyAddon(root, 'arm64')).toBe(prebuilt)
+  })
+
+  it('reports both expected locations when no addon is installed', () => {
+    const root = temporaryPackage()
+
+    expect(() => resolveLinuxNodePtyAddon(root, 'x64')).toThrow(
+      `node-pty addon is absent from both ${join(root, 'build', 'Release', 'pty.node')} and ${join(root, 'prebuilds', 'linux-x64', 'pty.node')}`,
+    )
+  })
+})
+
+describe('resolveWindowsNodePtyAddons', () => {
+  it('requires both ConPTY addons from the x64 prebuild', () => {
+    const root = temporaryPackage()
+    const conpty = createAddon(root, 'prebuilds', 'win32-x64', 'conpty.node')
+    const consoleList = createAddon(root, 'prebuilds', 'win32-x64', 'conpty_console_list.node')
+
+    expect(resolveWindowsNodePtyAddons(root, 'x64')).toEqual([conpty, consoleList])
+  })
+
+  it('names every missing Windows addon', () => {
+    const root = temporaryPackage()
+
+    expect(() => resolveWindowsNodePtyAddons(root, 'x64')).toThrow(
+      `Windows node-pty addons are missing: ${join(root, 'prebuilds', 'win32-x64', 'conpty.node')}, ${join(root, 'prebuilds', 'win32-x64', 'conpty_console_list.node')}`,
+    )
+  })
+})
+
+function temporaryPackage(): string {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-node-pty-addon-'))
+  roots.push(root)
+  return root
+}
+
+function createAddon(root: string, ...segments: string[]): string {
+  const path = join(root, ...segments)
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, '')
+  return path
+}

scripts/bundle-input-isolation.ts

@@ -0,0 +1,95 @@
+/** Experimental ownership of the actual filesystem and package inputs supplied to a bundler. */
+
+import { existsSync, readFileSync, realpathSync } from 'node:fs'
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+/** Package identities are cached only within one build. */
+export class BundleInputIsolation {
+  private readonly packages = new Map<string, string | undefined>()
+  private readonly repository: string
+  private readonly label: string
+
+  constructor(repository: string, label: string) {
+    this.repository = repository
+    this.label = label
+  }
+
+  /** Discard package metadata before a new build or watch rebuild. */
+  reset(): void { this.packages.clear() }
+
+  /**
+   * Require a recorded input to have non-experimental physical and package ownership.
+   * @param id - bundler module id, filesystem path, or filesystem URL.
+   */
+  assertInput(id: string): void {
+    this.checkInput(id, false)
+  }
+
+  /**
+   * Check declared source-map ownership; dependency tarballs may omit their upstream sources.
+   * @param id - source-map source resolved relative to its map.
+   */
+  assertSourceMapInput(id: string): void {
+    this.checkInput(id, true)
+  }
+
+  private checkInput(id: string, allowMissing: boolean): void {
+    if (/(?:^|[/:\u0000])@deepseek-ai\/dsh-experimental-[^/?#]+/.test(id)) {
+      throw new Error(`${this.label}: experimental input ${id}`)
+    }
+    const file = physicalBundleInput(id)
+    if (file === undefined) return
+    const lexical = relative(resolve(this.repository, 'packages/experimental'), file)
+    if (lexical === '' || lexical !== '..' && !lexical.startsWith(`..${sep}`) && !isAbsolute(lexical)) {
+      throw new Error(`${this.label}: experimental input ${id}`)
+    }
+    let existing = file
+    if (!allowMissing && !existsSync(file)) throw new Error(`${this.label}: input ${id} is missing`)
+    while (!existsSync(existing)) {
+      const parent = dirname(existing)
+      if (parent === existing) throw new Error(`${this.label}: input ${id} has no existing filesystem root`)
+      existing = parent
+    }
+    const canonical = resolve(realpathSync(existing), relative(existing, file))
+    if (canonical !== file) this.checkInput(canonical, allowMissing)
+    const name = this.packageName(dirname(canonical))
+    if (name?.startsWith('@deepseek-ai/dsh-experimental-')) {
+      throw new Error(`${this.label}: ${id} belongs to experimental package ${name}`)
+    }
+  }
+
+  private packageName(directory: string): string | undefined {
+    if (this.packages.has(directory)) return this.packages.get(directory)
+    const manifest = resolve(directory, 'package.json')
+    let name: string | undefined
+    if (existsSync(manifest)) {
+      const value: unknown = JSON.parse(readFileSync(manifest, 'utf8'))
+      if (value !== null && typeof value === 'object' && 'name' in value && typeof value.name === 'string') name = value.name
+    }
+    if (name === undefined && dirname(directory) !== directory) name = this.packageName(dirname(directory))
+    this.packages.set(directory, name)
+    return name
+  }
+}
+
+/**
+ * Recover physical ownership from queries, filesystem URLs, and virtual path wrappers.
+ * @param id - bundler module id or recorded filesystem input.
+ * @returns absolute file path, or undefined for a virtual id without a physical path.
+ */
+export function physicalBundleInput(id: string): string | undefined {
+  let clean = id.replaceAll('\\', '/').split(/[?#]/, 1)[0] ?? ''
+  clean = clean.replace(/^\u0000/, '')
+  if (clean.startsWith('file://')) return fileURLToPath(clean)
+  if (clean.startsWith('/@fs/')) {
+    clean = clean.slice('/@fs/'.length)
+    if (!isAbsolute(clean) && !/^[a-zA-Z]:\//.test(clean)) clean = `/${clean}`
+  }
+  if (!isAbsolute(clean) && !/^[a-zA-Z]:\//.test(clean)) {
+    const wrapped = /:(\/.*|[a-zA-Z]:\/.*)$/.exec(clean)?.[1]
+    if (wrapped === undefined) return undefined
+    clean = wrapped
+  }
+  return resolve(clean)
+}

scripts/check-macos-deployment-target.py

@@ -0,0 +1,111 @@
+#!/usr/bin/env python3
+"""Reject runtime executables that require newer macOS than their wheel tag."""
+
+from __future__ import annotations
+
+import argparse
+import re
+import runpy
+import subprocess
+from pathlib import Path
+
+
+ROOT = Path(__file__).resolve().parents[1]
+RELEASE = runpy.run_path(str(ROOT / "scripts" / "build-python-release.py"))
+MACOS_PLATFORMS = {
+    name: details[0]
+    for name, details in RELEASE["PLATFORMS"].items()
+    if name.startswith("macos-")
+}
+
+
+def parse_version(value: str) -> tuple[int, ...]:
+    """Parse a dot-separated numeric deployment version."""
+    if re.fullmatch(r"\d+(?:\.\d+)*", value) is None:
+        raise ValueError(f"invalid macOS deployment version: {value!r}")
+    return tuple(int(part) for part in value.split("."))
+
+
+def claimed_version(platform_tag: str) -> tuple[int, ...]:
+    """Return the minimum macOS version encoded by a wheel platform tag."""
+    match = re.fullmatch(r"macosx_(\d+)_(\d+)_(?:arm64|x86_64)", platform_tag)
+    if match is None:
+        raise ValueError(f"unsupported macOS wheel platform tag: {platform_tag!r}")
+    return int(match.group(1)), int(match.group(2))
+
+
+def parse_otool_deployment_target(output: str) -> tuple[int, ...]:
+    """Return the newest deployment target from one or more Mach-O slices."""
+    versions: list[tuple[int, ...]] = []
+    command: str | None = None
+    for line in output.splitlines():
+        stripped = line.strip()
+        if re.fullmatch(r"Load command \d+", stripped):
+            command = None
+        elif stripped == "cmd LC_BUILD_VERSION":
+            command = "build"
+        elif stripped == "cmd LC_VERSION_MIN_MACOSX":
+            command = "minimum"
+        elif command == "build" and (match := re.fullmatch(r"minos\s+(\d+(?:\.\d+)*)", stripped)):
+            versions.append(parse_version(match.group(1)))
+        elif command == "minimum" and (match := re.fullmatch(r"version\s+(\d+(?:\.\d+)*)", stripped)):
+            versions.append(parse_version(match.group(1)))
+    if not versions:
+        raise ValueError("otool output contains no macOS deployment target load command")
+    return max(versions)
+
+
+def deployment_target(executable: Path) -> tuple[int, ...]:
+    """Read one Mach-O executable's deployment target with ``otool``."""
+    if not executable.is_file():
+        raise FileNotFoundError(f"runtime executable does not exist: {executable}")
+    result = subprocess.run(
+        ["otool", "-l", str(executable)],
+        check=True,
+        capture_output=True,
+        text=True,
+    )
+    try:
+        return parse_otool_deployment_target(result.stdout)
+    except ValueError as error:
+        raise ValueError(f"{executable}: {error}") from error
+
+
+def ensure_compatible(
+    executable: Path, actual: tuple[int, ...], platform_tag: str
+) -> None:
+    """Reject an executable whose deployment target exceeds its wheel claim."""
+    claimed = claimed_version(platform_tag)
+    width = max(len(actual), len(claimed))
+    padded_actual = actual + (0,) * (width - len(actual))
+    padded_claimed = claimed + (0,) * (width - len(claimed))
+    if padded_actual > padded_claimed:
+        rendered = ".".join(str(part) for part in actual)
+        raise RuntimeError(
+            f"{executable} requires macOS {rendered} but the wheel claims {platform_tag}"
+        )
+
+
+def validate_deployment_targets(
+    executables: list[Path], platform_tag: str
+) -> list[tuple[Path, tuple[int, ...]]]:
+    """Validate every executable and return its measured deployment target."""
+    measured = [(executable, deployment_target(executable)) for executable in executables]
+    for executable, actual in measured:
+        ensure_compatible(executable, actual, platform_tag)
+    return measured
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--platform", choices=tuple(MACOS_PLATFORMS), required=True)
+    parser.add_argument("executables", type=Path, nargs="+")
+    args = parser.parse_args()
+    platform_tag = MACOS_PLATFORMS[args.platform]
+    for executable, version in validate_deployment_targets(args.executables, platform_tag):
+        rendered = ".".join(str(part) for part in version)
+        print(f"{executable}: macOS {rendered} <= {platform_tag}")
+
+
+if __name__ == "__main__":
+    main()

scripts/check-vendor-manifest.sh

@@ -0,0 +1,17 @@
+#!/usr/bin/env bash
+# Vendoring discipline, mechanized: any staged change under vendor/*/src or a
+# vendored bin.js must come with a vendor/README.md change in the same commit
+# (the manifest's local-modification log is the contract — see vendor/README.md).
+set -euo pipefail
+
+staged=$(git diff --cached --name-only)
+
+vendor_src_changed=$(echo "$staged" | grep -E '^vendor/[^/]+/(src/|bin\.js)' || true)
+manifest_changed=$(echo "$staged" | grep -x 'vendor/README.md' || true)
+
+if [[ -n "$vendor_src_changed" && -z "$manifest_changed" ]]; then
+  echo 'vendor manifest guard: vendored SOURCE changed without updating vendor/README.md:'
+  echo "$vendor_src_changed" | sed 's/^/  /'
+  echo 'Log the modification in vendor/README.md ("Local modifications") and stage it.'
+  exit 1
+fi

scripts/ci-compatible-toolcache.mjs

@@ -0,0 +1,8 @@
+import assert from 'node:assert/strict'
+import { isAbsolute, join } from 'node:path'
+
+// The Actions runner exports RUNNER_TOOL_CACHE after step env. Run inside the
+// setup-node process so version installs use runner temp rather than shared state.
+const temp = process.env.RUNNER_TEMP
+assert(temp && isAbsolute(temp), 'Node compatibility setup requires an absolute RUNNER_TEMP')
+process.env.RUNNER_TOOL_CACHE = join(temp, 'node-compat-toolcache')

scripts/ci-workflow.spec.ts

@@ -0,0 +1,1164 @@
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { runInNewContext } from 'node:vm'
+import * as yaml from 'js-yaml'
+import { describe, expect, it } from 'vitest'
+
+function evaluateRunsOn(selector: unknown, context: Record<string, unknown>): unknown {
+  if (typeof selector !== 'string') throw new TypeError('Runner selector must be a string')
+  return runInNewContext(selector.trim().slice(3, -2), context, { timeout: 1000 })
+}
+
+const root = resolve(import.meta.dirname, '..')
+const runnerPrivatePnpmDestination = /^\$\{\{ runner\.temp \}\}\/setup-pnpm-\$\{\{ github\.run_id \}\}-\$\{\{ github\.run_attempt \}\}$/
+const nativeWindowsPnpmDestination = '${{ runner.temp }}/setup-pnpm-js-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}'
+
+describe('CI workflow', () => {
+  it('prepares confinement before Node compatibility smokes', () => {
+    const job = workflowJob(loadWorkflow('.github/workflows/ci.yml'), 'node-compat')
+    if (!Array.isArray(job.steps)) throw new TypeError('Node compatibility job must define steps')
+    const steps = job.steps.filter(isRecord)
+    const preparation = steps.findIndex(step => step.run === 'bash scripts/prepare-ci-bubblewrap.sh')
+    const smoke = steps.findIndex(step => step.run === 'pnpm run check:node-compat')
+    expect(preparation).toBeGreaterThanOrEqual(0)
+    expect(smoke).toBeGreaterThan(preparation)
+    expect(steps[preparation]).not.toHaveProperty('continue-on-error', true)
+  })
+
+  it.each(['ci.yml', 'ci-master.yml', 'e2e.yml', 'release.yml', 'release-vendor.yml'])(
+    '%s cancels superseded validation runs without crossing workflow or ref boundaries', (name) => {
+      const workflow = loadWorkflow('.github/workflows/' + name)
+      expect(workflow.concurrency).toEqual({
+        group: '${{ github.workflow }}-${{ github.ref }}',
+        'cancel-in-progress': true,
+      })
+    },
+  )
+
+  it('cancels reusable CI builds without cancelling release-owned builds', () => {
+    const workflow = loadWorkflow('.github/workflows/build-exe-for-python-sdk.yml')
+    expect(workflow.concurrency).toEqual({
+      group: 'build-single-exe-${{ github.workflow }}-${{ github.ref }}',
+      'cancel-in-progress': '${{ !inputs.release }}',
+    })
+  })
+
+  it('does not cancel protected publication or deployment transactions', () => {
+    for (const name of ['release-publish.yml', 'release-vendor-publish.yml']) {
+      const publish = workflowJob(loadWorkflow('.github/workflows/' + name), 'publish')
+      expect(publish.concurrency).toMatchObject({ 'cancel-in-progress': false })
+    }
+    for (const name of ['python-release.yml', 'node-addon-system-release.yml', 'docs-pages.yml']) {
+      expect(loadWorkflow('.github/workflows/' + name).concurrency).toMatchObject({ 'cancel-in-progress': false })
+    }
+  })
+
+  it('skips coverage-history uploads on cancellation but retains Wine cleanup', () => {
+    const coverage = workflowJob(loadWorkflow('.github/workflows/ci.yml'), 'windows-coverage')
+    const wine = workflowJob(loadWorkflow('.github/workflows/ci-master.yml'), 'windows')
+    expect(coverage.steps).toContainEqual(expect.objectContaining({
+      name: 'Save coverage duration history', if: '${{ !cancelled() }}',
+    }))
+    expect(wine.steps).toContainEqual(expect.objectContaining({ name: 'Shut down wineserver', if: 'always()' }))
+  })
+
+  it('isolates every pnpm action setup destination per runner', () => {
+    const files = ['.github/workflows/ci.yml', '.github/workflows/ci-master.yml']
+    const setups: Array<{ jobName: string; step: unknown }> = []
+    for (const file of files) {
+      const workflow: unknown = yaml.load(readFileSync(resolve(root, file), 'utf8'))
+      if (!isRecord(workflow) || !isRecord(workflow.jobs)) throw new TypeError(`${file} must define jobs`)
+      for (const [jobName, job] of Object.entries(workflow.jobs)) {
+        if (!isRecord(job) || !Array.isArray(job.steps)) continue
+        for (const step of job.steps) {
+          if (!isRecord(step) || typeof step.uses !== 'string' || !step.uses.startsWith('pnpm/action-setup@')) continue
+          setups.push({ jobName, step })
+        }
+      }
+    }
+
+    expect(setups.length).toBeGreaterThan(0)
+    for (const { jobName, step } of setups) {
+      const stepDest = (step as { with?: { dest?: unknown } }).with?.dest
+      if (jobName.startsWith('windows-')) {
+        expect(stepDest, `${jobName} must use the native Windows pnpm destination`).toBe(nativeWindowsPnpmDestination)
+        expect(step).not.toMatchObject({ with: { standalone: true } })
+      } else {
+        expect(typeof stepDest, `${jobName} must use a runner-and-run-private pnpm destination`).toBe('string')
+        expect(stepDest as string).toMatch(runnerPrivatePnpmDestination)
+      }
+    }
+  })
+
+  it.each(['node-24', 'node-24-coverage', 'node-24-consumers'])(
+    '%s keeps tool and fixture temporary files under runner cleanup',
+    (jobName) => {
+      const job = workflowJob(loadWorkflow('.github/workflows/ci.yml'), jobName)
+      if (!Array.isArray(job.steps)) throw new TypeError(`${jobName} must define steps`)
+      expect(job.steps[0]).toEqual({
+        name: 'Use runner-owned temporary storage',
+        run: [
+          'echo "TMPDIR=${{ runner.temp }}" >> "$GITHUB_ENV"',
+          ...(jobName === 'node-24-consumers'
+            ? ['echo "PLAYWRIGHT_BROWSERS_PATH=${RUNNER_TEMP%/*}/ms-playwright" >> "$GITHUB_ENV"']
+            : []),
+          '',
+        ].join('\n'),
+      })
+      if (jobName === 'node-24-consumers') {
+        const browserCache: unknown = job.steps.find(step => isRecord(step) && isRecord(step.with)
+          && step.with.path === '${{ env.PLAYWRIGHT_BROWSERS_PATH }}')
+        expect(browserCache).toMatchObject({ uses: 'actions/cache/restore@v4' })
+      }
+      const store: unknown = job.steps.find(step => isRecord(step) && step.name === 'Configure pnpm store path')
+      expect(store).toMatchObject({
+        run: [
+          'store_root="$HOME/.local/share/pnpm/store"',
+          'echo "PNPM_CONFIG_STORE_DIR=$store_root" >> "$GITHUB_ENV"',
+          'store_path=$(PNPM_CONFIG_STORE_DIR="$store_root" pnpm store path --silent)',
+          'echo "path=$store_path" >> "$GITHUB_OUTPUT"',
+          '',
+        ].join('\n'),
+      })
+      for (const step of job.steps) {
+        if (isRecord(step) && isRecord(step.env)) {
+          expect(step.env.TMPDIR).toBeUndefined()
+          expect(step.env.npm_config_cache).toBeUndefined()
+        }
+      }
+    },
+  )
+
+  it('isolates the python SDK exe pnpm setup destination per job', () => {
+    const workflow: unknown = yaml.load(readFileSync(resolve(root, '.github/workflows/build-exe-for-python-sdk.yml'), 'utf8'))
+    if (!isRecord(workflow) || !isRecord(workflow.jobs)) throw new TypeError('build-exe-for-python-sdk.yml must define jobs')
+    const setups: Array<{ step: unknown }> = []
+    for (const job of Object.values(workflow.jobs)) {
+      if (!isRecord(job) || !Array.isArray(job.steps)) continue
+      for (const step of job.steps) {
+        if (!isRecord(step) || typeof step.uses !== 'string' || !step.uses.startsWith('pnpm/action-setup@')) continue
+        setups.push({ step })
+      }
+    }
+    expect(setups.length).toBeGreaterThan(0)
+    for (const { step } of setups) {
+      expect(step).toMatchObject({
+        with: { dest: nativeWindowsPnpmDestination },
+      })
+    }
+  })
+
+  it('keeps split native Windows PR jobs with failover, plus a master-only standby', () => {
+    const workflow = loadWorkflow('.github/workflows/ci.yml')
+    const masterWorkflow = loadWorkflow('.github/workflows/ci-master.yml')
+    if (!isRecord(workflow.jobs)
+      || !isRecord(workflow.jobs['windows-build'])
+      || !isRecord(workflow.jobs['windows-coverage'])
+      || !isRecord(workflow.jobs['windows-native-tests'])
+      || !isRecord(workflow.jobs['windows-observational'])
+      || !isRecord(workflow.jobs['node-24'])
+      || !isRecord(workflow.jobs['node-24-coverage'])
+      || !isRecord(workflow.jobs['node-24-bench'])
+      || !isRecord(workflow.jobs['node-24-consumers'])
+      || !isRecord(workflow.jobs['node-compat'])
+      || !isRecord(workflow.jobs['all-checks-passed'])
+      || !isRecord(masterWorkflow.jobs)
+      || !isRecord(masterWorkflow.jobs['serial-windows'])) {
+      throw new TypeError('CI workflow must define windows-build, windows-coverage, windows-native-tests, windows-observational, node-24, node-24-coverage, node-24-bench, node-24-consumers, node-compat, and all-checks-passed; ci-master must define serial-windows')
+    }
+
+    const windowsBuild = workflow.jobs['windows-build']
+    const windowsCoverage = workflow.jobs['windows-coverage']
+    const windowsNativeTests = workflow.jobs['windows-native-tests']
+    const windowsObservational = workflow.jobs['windows-observational']
+    const serialWindows = masterWorkflow.jobs['serial-windows']
+    const node24 = workflow.jobs['node-24']
+    const node24Coverage = workflow.jobs['node-24-coverage']
+    const node24Bench = workflow.jobs['node-24-bench']
+    const node24Consumers = workflow.jobs['node-24-consumers']
+    const nodeCompat = workflow.jobs['node-compat']
+    const aggregate = workflow.jobs['all-checks-passed']
+    if (!Array.isArray(aggregate.needs)) {
+      throw new TypeError('CI aggregate must define needs')
+    }
+    // The split native jobs all resolve their pool through the Windows switch.
+    for (const [jobName, job] of [['windows-build', windowsBuild], ['windows-coverage', windowsCoverage], ['windows-native-tests', windowsNativeTests], ['windows-observational', windowsObservational]] as const) {
+      expect(typeof job['runs-on']).toBe('string')
+      expect(job['runs-on'], `${jobName} runs-on must use the Windows failover switch`).toContain('DSH_CI_FAILOVER_WINDOWS')
+      expect(job['runs-on'], `${jobName} runs-on must not use the Linux failover switch`).not.toContain('DSH_CI_FAILOVER_LINUX')
+      expect(job['runs-on']).toContain('self-hosted')
+      expect(job['runs-on']).toContain('dsh-win-ci')
+      expect(job['runs-on']).toContain('dsh-windows-2025-16core')
+      expect(job['runs-on']).toContain('blacksmith-16vcpu-windows-2025')
+      expect(job.if).toBe("github.event_name == 'pull_request'")
+    }
+
+    // windows-build runs the blocking build/site pair.
+    expect(windowsBuild.name).toBe('windows node 24 / build')
+    const buildSteps = windowsBuild.steps as unknown[]
+    const buildCommands = buildSteps.filter((step): step is Record<string, unknown> & { run: string } => (
+      isRecord(step) && typeof step.run === 'string'
+    ))
+    expect(buildCommands.map(step => step.run)).toContain('pnpm run check:ci:windows-blocking')
+
+    // The four native Windows installs branch on the workspace filesystem:
+    // clone (ReFS block clone) only on ReFS, plain install elsewhere. This
+    // keeps the TS6231 store-path leak (see the Windows ReFS store note) out
+    // of the self-hosted pool without forcing clone onto hosted NTFS, which
+    // rejects copy-on-write. The branch must stay, or a hosted fallback would
+    // fail installs with ERR_PNPM_LINKING_FAILED.
+    for (const [jobName, job] of [['windows-build', windowsBuild], ['windows-coverage', windowsCoverage], ['windows-native-tests', windowsNativeTests], ['windows-observational', windowsObservational]] as const) {
+      const steps = job.steps as unknown[]
+      const install = steps.find((step): step is Record<string, unknown> & { run: string } => (
+        isRecord(step) && step.name === 'Install (immutable)' && typeof step.run === 'string'
+      ))
+      expect(install, `${jobName} must define the filesystem-branched install`).toBeDefined()
+      expect(install!.run).toContain("$fs -eq 'ReFS'")
+      expect(install!.run).toContain('--package-import-method=clone')
+      expect(install!.run).toContain('corepack pnpm install')
+      // The else branch must keep the plain hosted install as a distinct line
+      // (not the corepack clone line, which contains the same substring);
+      // dropping it or making both branches clone would force clone onto
+      // NTFS, which rejects copy-on-write (ERR_PNPM_LINKING_FAILED). The
+      // YAML folded block keeps the first statement on line 1 and folds the
+      // rest with leading two-space indents.
+      const installLines = install!.run.split('\n').map(line => line.trim())
+      expect(installLines).toContain('} else {')
+      expect(installLines.some(line => line === 'pnpm install --frozen-lockfile'), `${jobName} else branch must keep the plain hosted install`).toBe(true)
+      // The ReFS branch must not use the interpolated empty-flag form, which
+      // passes a stray "" positional argument to pnpm.
+      expect(install!.run).not.toContain('$cloneFlag')
+    }
+
+    // windows-coverage uses the lower 4-partition profile.
+    expect(windowsCoverage.name).toBe('windows node 24 / coverage')
+    expect(windowsCoverage.env).toMatchObject({ DSH_COVERAGE_PARTITIONS: '4' })
+    const coverageSteps = windowsCoverage.steps as unknown[]
+    const coverageCommands = coverageSteps.filter((step): step is Record<string, unknown> & { run: string } => (
+      isRecord(step) && typeof step.run === 'string'
+    ))
+    expect(coverageCommands.map(step => step.run)).toContain('pnpm run check:ci:coverage')
+    // Windows coverage runs zero-build like the Linux lane: workspace imports
+    // resolve to src through the tsconfig paths map, and the lib-consuming
+    // suites (webworker-packer image-loadable, webworker-runtime
+    // transform-corpus, client ui-trajectory client-bundle) self-skip on
+    // unbuilt checkouts. The regex catches a regression spelled as
+    // 'corepack pnpm run build' or folded into a multi-line run block, which
+    // an exact string match would miss.
+    expect(coverageCommands.every(step => !/\bpnpm\s+run\s+build(?:\s|$)/.test(step.run))).toBe(true)
+
+    // windows-native-tests runs the Windows-specific specs.
+    expect(windowsNativeTests.name).toBe('windows node 24 / native tests')
+    const nativeTestSteps = windowsNativeTests.steps as unknown[]
+    const nativeTestCommands = nativeTestSteps.filter((step): step is Record<string, unknown> & { run: string } => (
+      isRecord(step) && typeof step.run === 'string'
+    ))
+    const nativeTestCommand = nativeTestCommands.map(step => step.run).join('\n')
+    expect(nativeTestCommand).toContain('--no-file-parallelism')
+    expect(nativeTestCommand).toContain('--testTimeout 90000')
+    expect(nativeTestCommand).toContain('tool-pwsh/tests/loader.spec.ts')
+    expect(nativeTestCommand).toContain('workflow-ptc.spec.ts')
+
+    // windows-observational is non-blocking.
+    expect(windowsObservational.name).toBe('windows node 24 / observational')
+    expect(windowsObservational['continue-on-error']).toBe(true)
+
+    // serial-windows: master-only standby, self-hosted, non-blocking, lives in ci-master.
+    expect(serialWindows.if).toBe("github.event_name == 'push' && github.ref == 'refs/heads/master'")
+    expect(serialWindows['runs-on']).toEqual(['self-hosted', 'dsh-win-ci', 'windows'])
+    expect(serialWindows.name).toBe('serial / windows (self-hosted standby)')
+    // Its store must share the ReFS workspace volume for clone; the install
+    // must carry the same filesystem branch as the PR jobs.
+    const serialSteps = serialWindows.steps as unknown[]
+    const serialStore = serialSteps.find((step): step is Record<string, unknown> & { run: string } => (
+      isRecord(step) && step.name === 'Configure persistent pnpm store' && typeof step.run === 'string'
+    ))
+    expect(serialStore).toBeDefined()
+    expect(serialStore!.run).toContain('[IO.Path]::GetPathRoot($env:GITHUB_WORKSPACE)')
+    expect(serialStore!.run).toContain("'.pnpm-store'")
+    const serialInstall = serialSteps.find((step): step is Record<string, unknown> & { run: string } => (
+      isRecord(step) && step.name === 'Install (immutable)' && typeof step.run === 'string'
+    ))
+    expect(serialInstall).toBeDefined()
+    expect(serialInstall!.run).toContain("$fs -eq 'ReFS'")
+    expect(serialInstall!.run).toContain('--package-import-method=clone')
+    expect(serialInstall!.run).toContain('corepack pnpm install')
+    // Distinct else-branch line, as for the PR jobs: the corepack clone line
+    // contains the plain-install substring too.
+    expect(serialInstall!.run.split('\n').map(line => line.trim())).toContain('} else {')
+    expect(serialInstall!.run.split('\n').map(line => line.trim())).toContain('pnpm install --frozen-lockfile')
+    expect(serialInstall!.run).not.toContain('$cloneFlag')
+    // The unsharded reference runs the whole coverage inventory at the same
+    // per-test budget the PR coverage lane grants; the default 5000ms times
+    // out load-sensitive store scans (e.g. gen-third-party-notices).
+    const serialGate = serialSteps.find((step): step is Record<string, unknown> & { env?: Record<string, unknown> } => (
+      isRecord(step) && step.name === 'Run complete unsharded Windows gate inventory serially'
+    ))
+    expect(serialGate).toBeDefined()
+    expect(serialGate!.env).toMatchObject({ DSH_COVERAGE_TEST_TIMEOUT_MS: '90000' })
+
+    // windows-coverage is temporarily non-blocking while Windows ACP
+    // half-close tests are stabilized; observational stays out too.
+    expect(aggregate.needs).not.toContain('windows')
+    expect(aggregate.needs).toContain('windows-build')
+    // The benchmark lane is a required verdict input and runs alone so its
+    // wall-clock budgets never share a runner with a concurrent aggregate.
+    expect(aggregate.needs).toContain('node-24-bench')
+    expect(node24Bench.name).toBe('node 24 / benchmarks')
+    expect(node24Bench.env).toBeUndefined()
+    expect(node24Bench.steps).toContainEqual({
+      name: 'Install benchmark browser and hosted dependencies',
+      run: 'pnpm --filter @deepseek-ai/dsh-benchmarks exec playwright install --with-deps chromium',
+    })
+    expect(JSON.stringify(node24Bench.steps)).not.toContain('DSH_CI_FAILOVER_LINUX')
+    expect(node24Bench.steps).toContainEqual({
+      name: 'Run performance benchmarks',
+      env: { DSH_GATE_VERBOSE: '1' },
+      run: 'pnpm run check:ci:bench',
+    })
+    expect(aggregate.needs).not.toContain('windows-coverage')
+    expect(aggregate.needs).toContain('windows-native-tests')
+    expect(aggregate.needs).not.toContain('windows-observational')
+    expect(aggregate.needs).not.toContain('serial-windows')
+
+    // Linux failover is a separate switch: the three enterprise Linux workers
+    // and the verdict job resolve their pool through DSH_CI_FAILOVER_LINUX,
+    // never the Windows switch.
+    for (const [jobName, job] of [['node-24', node24], ['node-24-coverage', node24Coverage], ['node-24-consumers', node24Consumers]] as const) {
+      expect(typeof job['runs-on']).toBe('string')
+      expect(job['runs-on'], `${jobName} runs-on must use the Linux failover switch`).toContain('DSH_CI_FAILOVER_LINUX')
+      expect(job['runs-on'], `${jobName} runs-on must not use the Windows failover switch`).not.toContain('DSH_CI_FAILOVER_WINDOWS')
+      expect(job['runs-on']).toContain('vm-backup')
+      expect(job['runs-on']).toContain('blacksmith-16vcpu-ubuntu-2404')
+    }
+    expect(aggregate['runs-on']).toContain('DSH_CI_FAILOVER_LINUX')
+    expect(aggregate['runs-on']).not.toContain('DSH_CI_FAILOVER_WINDOWS')
+    expect(aggregate['runs-on']).toContain('vm-backup')
+    expect(aggregate['runs-on']).toContain('blacksmith-4vcpu-ubuntu-2404')
+
+    // Evaluating the full selector, not just substring containment, proves the
+    // blacksmith branch is standalone: it must not fall through to the
+    // self-hosted pool when the two values are mutually exclusive.
+    const selectors = {
+      linux: node24['runs-on'] as string,
+      linuxAggregate: aggregate['runs-on'] as string,
+      windows: windowsBuild['runs-on'] as string,
+    }
+    const evaluate = (expression: string, vars: Record<string, string>, login = 'maintainer'): unknown => {
+      return evaluateRunsOn(expression, {
+        vars,
+        fromJSON: JSON.parse,
+        github: { event: { pull_request: { user: { login } } } },
+      })
+    }
+    for (const [name, selector, variable, pool, hosted] of [
+      ['linux gates', selectors.linux, 'DSH_CI_FAILOVER_LINUX', ['self-hosted', 'linux', 'x64', 'vm-backup'], 'dsh-ubuntu-24-04-16core'],
+      ['linux aggregate', selectors.linuxAggregate, 'DSH_CI_FAILOVER_LINUX', ['self-hosted', 'linux', 'x64', 'vm-backup'], 'ubuntu-latest'],
+      ['windows lanes', selectors.windows, 'DSH_CI_FAILOVER_WINDOWS', ['self-hosted', 'dsh-win-ci', 'windows'], 'dsh-windows-2025-16core'],
+    ] as const) {
+      expect(evaluate(selector, { [variable]: 'blacksmith' }), `${name} blacksmith value`).toMatch(/^blacksmith-/)
+      expect(evaluate(selector, { [variable]: 'selfhosted' }), `${name} selfhosted value`).toEqual(pool)
+      // The blacksmith branch must not capture the selfhosted pool, and the
+      // dependabot exclusion applies to the pool, not to the blacksmith tier.
+      expect(evaluate(selector, { [variable]: 'selfhosted' }, 'dependabot[bot]'), `${name} dependabot on selfhosted`).toBe(hosted)
+      for (const mode of ['', 'hosted', 'unexpected']) {
+        expect(evaluate(selector, { [variable]: mode }), `${name} default on ${mode}`).toBe(hosted)
+      }
+    }
+
+    // The run-gates aggregate lanes stop at the first blocking gate failure so
+    // a red aggregate does not keep burning runner time on the remaining
+    // gates. Removing the flag silently reverts to running every independent
+    // gate to completion.
+    for (const [jobName, job] of [['node-24', node24], ['node-24-coverage', node24Coverage], ['node-24-consumers', node24Consumers], ['node-compat', nodeCompat]] as const) {
+      expect(job.env, `${jobName} must enable fail-fast`).toMatchObject({ DSH_GATE_FAIL_FAST: '1' })
+    }
+
+    // The native Windows lanes with run-gates aggregates fail fast for the
+    // same reason: a failing gate aborts the sibling gate instead of waiting
+    // out the multi-minute instrumented coverage run.
+    expect(windowsBuild.env, 'windows-build must enable fail-fast').toMatchObject({ DSH_GATE_FAIL_FAST: '1' })
+    expect(windowsCoverage.env, 'windows-coverage must enable fail-fast').toMatchObject({ DSH_GATE_FAIL_FAST: '1' })
+
+    // The observational lane stays complete: it is continue-on-error by design
+    // and exists to collect as much Windows-native evidence per run as
+    // possible, so the first failure must not truncate the rest.
+    expect(windowsObservational.env).toBeDefined()
+    expect(windowsObservational.env).not.toMatchObject({ DSH_GATE_FAIL_FAST: '1' })
+  })
+
+  it('gates standalone keyless blacksmith jobs and benchmark tiers on the failover variables', () => {
+    const expectedFilenames = workflowJob(loadWorkflow('.github/workflows/expected-filenames.yml'), 'expected-filenames')
+    const sandbox = workflowJob(loadWorkflow('.github/workflows/sandbox.yml'), 'sandbox-e2e')
+    expect(expectedFilenames['runs-on']).toContain('DSH_CI_FAILOVER_LINUX')
+    expect(expectedFilenames['runs-on']).toContain("== 'blacksmith'")
+    expect(expectedFilenames['runs-on']).toContain('blacksmith-4vcpu-ubuntu-2404')
+    expect(expectedFilenames['runs-on']).toContain("'ubuntu-latest'")
+    expect(sandbox['runs-on']).toContain("matrix.runner == 'bwrap'")
+    expect(sandbox['runs-on']).toContain('DSH_CI_FAILOVER_LINUX')
+    expect(sandbox['runs-on']).toContain('blacksmith-4vcpu-ubuntu-2404')
+    for (const name of ['larger-runner-benchmark', 'consolidated-runner-benchmark'] as const) {
+      const benchmark = workflowJob(loadWorkflow('.github/workflows/ci-master.yml'), name)
+      if (!isRecord(benchmark.strategy) || !isRecord(benchmark.strategy.matrix) || !Array.isArray(benchmark.strategy.matrix.include)) {
+        throw new TypeError(`${name} must define a matrix include list`)
+      }
+      expect(benchmark['runs-on']).toContain('matrix.blacksmith')
+      expect(benchmark['runs-on']).toContain('DSH_CI_FAILOVER_LINUX')
+      expect(benchmark['runs-on']).toContain('DSH_CI_FAILOVER_WINDOWS')
+      for (const row of benchmark.strategy.matrix.include as Array<Record<string, string>>) {
+        expect(typeof row.blacksmith, `${name} ${row.cores}-core row must declare a blacksmith label`).toBe('string')
+        if (row.cores === '64' || row.cores === '96') {
+          expect(row.blacksmith, `${name} ${row.cores}-core row has no Blacksmith tier`).toBe('')
+        } else {
+          expect(row.blacksmith).toContain(`blacksmith-${row.cores}vcpu`)
+        }
+      }
+    }
+  })
+
+  it('runs required benchmarks on standard hosted Linux independently of failover', () => {
+    const workflow = loadWorkflow('.github/workflows/ci.yml')
+    const benchmark = workflowJob(workflow, 'node-24-bench')
+    const aggregate = workflowJob(workflow, 'all-checks-passed')
+
+    expect(benchmark['runs-on']).toBe('ubuntu-24.04')
+    expect(benchmark.if).toBe("github.event_name == 'pull_request'")
+    expect(benchmark.needs).toBeUndefined()
+    expect(benchmark['continue-on-error']).toBeUndefined()
+    expect(benchmark.env).toBeUndefined()
+    expect(aggregate.needs).toContain('node-24-bench')
+  })
+
+  it('always restores the hosted benchmark pnpm cache', () => {
+    const benchmark = workflowJob(loadWorkflow('.github/workflows/ci.yml'), 'node-24-bench')
+    if (!Array.isArray(benchmark.steps)) throw new TypeError('benchmark job must define steps')
+    const caches = benchmark.steps.filter(step => isRecord(step) && step.uses === 'actions/cache/restore@v4')
+
+    expect(caches).toHaveLength(1)
+    expect(caches[0]).not.toHaveProperty('if')
+    expect(caches[0]).toMatchObject({
+      with: {
+        path: '${{ steps.pnpm-store.outputs.path }}',
+        key: "${{ runner.os }}-node-${{ env.PRIMARY_NODE_VERSION }}-pnpm-${{ hashFiles('pnpm-lock.yaml') }}",
+      },
+    })
+  })
+
+  it('bounds the complete benchmark job to fifteen minutes', () => {
+    const benchmark = workflowJob(loadWorkflow('.github/workflows/ci.yml'), 'node-24-bench')
+
+    expect(benchmark['timeout-minutes']).toBe(15)
+    expect(benchmark.steps).toContainEqual({
+      name: 'Run performance benchmarks',
+      env: { DSH_GATE_VERBOSE: '1' },
+      run: 'pnpm run check:ci:bench',
+    })
+  })
+
+  it('gives the Wine Host TypeScript compile the repository heap budget', () => {
+    const wineGates = readFileSync(resolve(root, 'scripts/wine-windows-gates.sh'), 'utf8')
+
+    expect(wineGates).toContain(
+      'wine_node "$scratch/logs/host-tsc.log" --max-old-space-size=4096 "$tsc_js" -b tsconfig.host.json --pretty false',
+    )
+  })
+
+  it('cancels superseded master runs without changing the post-merge job inventory', () => {
+    const workflow = loadWorkflow('.github/workflows/ci-master.yml')
+    const prWorkflow = loadWorkflow('.github/workflows/ci.yml')
+    if (!isRecord(workflow.jobs) || !isRecord(workflow.concurrency)) {
+      throw new TypeError('ci-master workflow must define jobs and a workflow-level concurrency block')
+    }
+    if (!isRecord(prWorkflow.jobs)) {
+      throw new TypeError('ci workflow must define jobs')
+    }
+
+    expect(workflow.concurrency).toEqual({
+      group: '${{ github.workflow }}-${{ github.ref }}',
+      'cancel-in-progress': true,
+    })
+    expect(prWorkflow.concurrency).toEqual(workflow.concurrency)
+
+    // The exact event sets are what keep master-only jobs out of the PR check
+    // panel: ci-master triggers only on push(master) + workflow_dispatch and
+    // never on pull_request; ci.yml is exactly pull_request-only. Assert the
+    // full sets so losing the wrong event, or gaining an extra one, fails.
+    if (!isRecord(workflow.on) || !isRecord(prWorkflow.on)) {
+      throw new TypeError('both CI workflows must define on')
+    }
+    expect(Object.keys(workflow.on).sort()).toEqual(['push', 'workflow_dispatch'])
+    expect(Object.keys(prWorkflow.on)).toEqual(['pull_request'])
+
+    // Drills share the parent run’s supersession policy.
+    for (const name of ['serial-linux-selfhosted', 'serial-windows']) {
+      const job = workflow.jobs[name]
+      if (!isRecord(job)) throw new TypeError(`${name} must be defined`)
+      expect(job.concurrency).toBeUndefined()
+      // Standby drills remain post-merge work, but share run cancellation.
+      expect(job.if).toBe("github.event_name == 'push' && github.ref == 'refs/heads/master'")
+    }
+
+    // Pin the post-merge runtime, Wine, and standby inventory.
+    const NOT_PUSH_REACHABLE = new Set([
+      "github.event_name == 'workflow_dispatch' && inputs.suite == 'larger-runner-benchmark'",
+      "github.event_name == 'workflow_dispatch' && inputs.suite == 'consolidated-runner-benchmark'",
+    ])
+    const pushReachable = Object.entries(workflow.jobs)
+      .filter(([, job]) => {
+        if (!isRecord(job)) return false
+        if (job.if === undefined) return true // unconditional: runs on every event
+        if (job.if === false) return false // `if: false` parses as a boolean
+        if (typeof job.if !== 'string') return true // unrecognized shape: surface it
+        return !NOT_PUSH_REACHABLE.has(job.if.trim())
+      })
+      .map(([name]) => name)
+      .sort()
+    expect(pushReachable).toEqual(['python-runtime', 'serial-linux-selfhosted', 'serial-windows', 'windows'])
+
+    // Manual benchmarks retain their bounded fan-out.
+    for (const name of ['larger-runner-benchmark', 'consolidated-runner-benchmark']) {
+      const job = workflow.jobs[name]
+      if (!isRecord(job) || !isRecord(job.strategy)) {
+        throw new TypeError(`${name} must define a matrix strategy`)
+      }
+      expect(job.strategy['max-parallel']).toBe(12)
+      expect(job['timeout-minutes']).toBe(15)
+    }
+  })
+
+  it('redirects the Node compile cache to the data-volume runner temp before the first pnpm call', () => {
+    const prWorkflow = loadWorkflow('.github/workflows/ci.yml')
+    const masterWorkflow = loadWorkflow('.github/workflows/ci-master.yml')
+    const redirectLanes = [
+      [prWorkflow, 'node-24'],
+      [prWorkflow, 'node-24-coverage'],
+      [prWorkflow, 'node-24-consumers'],
+      [masterWorkflow, 'serial-linux-selfhosted'],
+    ] as const
+    for (const [workflow, jobKey] of redirectLanes) {
+      const job = workflowJob(workflow, jobKey)
+      if (!Array.isArray(job.steps)) throw new TypeError(`${jobKey} must define steps`)
+      const redirectStepIndex = job.steps.findIndex((step): step is Record<string, unknown> & { run: string } => (
+        isRecord(step) && typeof step.run === 'string'
+          && step.run.includes('NODE_COMPILE_CACHE=${{ runner.temp }}/node-compile-cache')
+          && step.run.includes('"$GITHUB_ENV"')
+      ))
+      // Removing this injection would send every pnpm call in the lane (setup,
+      // store-path probe, install, and the gate) back to the root partition's
+      // /tmp; rationale in
+      // .agents/notes/implemented/process/2026-08-28-ci-node-compile-cache-data-disk.md.
+      expect(redirectStepIndex, `${jobKey} must inject NODE_COMPILE_CACHE into GITHUB_ENV`).toBeGreaterThan(-1)
+      const pnpmSetupIndex = job.steps.findIndex((step): step is Record<string, unknown> & { uses: string } => (
+        isRecord(step) && typeof step.uses === 'string' && step.uses.includes('pnpm/action-setup')
+      ))
+      expect(pnpmSetupIndex, `${jobKey} must run pnpm/action-setup`).toBeGreaterThan(-1)
+      expect(redirectStepIndex, `${jobKey} must redirect before pnpm/action-setup runs pnpm`).toBeLessThan(pnpmSetupIndex)
+    }
+  })
+
+  it('keeps supported LSP source under native Windows coverage', () => {
+    const config = readFileSync(resolve(root, 'vitest.config.ts'), 'utf8')
+
+    expect(config).not.toContain('packages/lsp/lsp-stdio/src/connection.ts')
+    expect(config).not.toContain('packages/lsp/lsp-stdio/src/index.ts')
+    expect(config).not.toContain('packages/lsp/lsp-stdio/src/instance.ts')
+  })
+
+  it('requires release-shaped Python runtime validation on Linux and Windows x64', () => {
+    const workflow = loadWorkflow('.github/workflows/ci.yml')
+    const pythonRuntime = workflowJob(workflow, 'python-runtime')
+    const aggregate = workflowJob(workflow, 'all-checks-passed')
+    if (!Array.isArray(aggregate.needs)) {
+      throw new TypeError('CI aggregate must define required job dependencies')
+    }
+
+    expect(pythonRuntime).toMatchObject({
+      if: "github.event_name == 'pull_request'",
+      name: 'python runtime / release-shaped matrix',
+      uses: './.github/workflows/build-exe-for-python-sdk.yml',
+      with: {
+        targets: 'node24-linux-x64,node24-win-x64',
+        ci: true,
+      },
+      secrets: {
+        DEEPSEEK_API_KEY_EXTERNAL: '${{ secrets.DEEPSEEK_API_KEY_EXTERNAL }}',
+      },
+    })
+    expect(aggregate.needs).toContain('python-runtime')
+  })
+
+  it('keeps every Vitest project process-isolated on native Windows', () => {
+    const config = readFileSync(resolve(root, 'vitest.config.ts'), 'utf8')
+
+    expect(config).not.toContain("pool: process.platform === 'win32' ? 'threads' : 'forks'")
+    expect(config.match(/pool: 'forks'/g)).toHaveLength(2)
+  })
+})
+
+describe('Runtime and LLM e2e Blacksmith routing', () => {
+  it('routes DeepSeek e2e only through the Linux Blacksmith switch', () => {
+    const job = workflowJob(loadWorkflow('.github/workflows/e2e.yml'), 'e2e')
+    for (const mode of ['', 'selfhosted', 'unexpected', 'blacksmith']) {
+      expect(evaluateRunsOn(job['runs-on'], { vars: { DSH_CI_FAILOVER_LINUX: mode, DSH_CI_FAILOVER_WINDOWS: 'blacksmith' } }))
+        .toBe(mode === 'blacksmith' ? 'blacksmith-4vcpu-ubuntu-2404' : 'ubuntu-latest')
+    }
+  })
+
+  it('keeps native release and dispatch builders hosted while routing x64 CI by platform', () => {
+    const workflow = loadWorkflow('.github/workflows/build-exe-for-python-sdk.yml')
+    const build = workflowJob(workflow, 'build')
+    for (const [target, runner, variable, blacksmith] of [
+      ['node24-linux-x64', 'ubuntu-latest', 'DSH_CI_FAILOVER_LINUX', 'blacksmith-16vcpu-ubuntu-2404'],
+      ['node24-win-x64', 'windows-2025', 'DSH_CI_FAILOVER_WINDOWS', 'blacksmith-16vcpu-windows-2025'],
+      ['node24-linux-arm64', 'ubuntu-24.04-arm', 'DSH_CI_FAILOVER_LINUX', 'ubuntu-24.04-arm'],
+      ['node24-macos-arm64', 'macos-latest', 'DSH_CI_FAILOVER_LINUX', 'macos-latest'],
+      ['node24-macos-x64', 'macos-15-intel', 'DSH_CI_FAILOVER_LINUX', 'macos-15-intel'],
+    ] as const) {
+      for (const ci of [false, true]) {
+        for (const release of [false, true]) {
+          for (const mode of ['', 'selfhosted', 'unexpected', 'blacksmith']) {
+            const vars = { DSH_CI_FAILOVER_LINUX: 'blacksmith', DSH_CI_FAILOVER_WINDOWS: 'blacksmith', [variable]: mode }
+            expect(evaluateRunsOn(build['runs-on'], { inputs: { ci, release }, vars, matrix: { target, runner } }), `${target} ci=${ci} release=${release} mode=${mode}`)
+              .toBe(ci && !release && mode === 'blacksmith' ? blacksmith : runner)
+          }
+        }
+      }
+    }
+  })
+
+  it.each(['plan', 'sdk-wheel'])('routes runtime %s only for non-release CI', (name) => {
+    const job = workflowJob(loadWorkflow('.github/workflows/build-exe-for-python-sdk.yml'), name)
+    for (const ci of [false, true]) {
+      for (const release of [false, true]) {
+        for (const mode of ['', 'selfhosted', 'unexpected', 'blacksmith']) {
+          expect(evaluateRunsOn(job['runs-on'], { inputs: { ci, release }, vars: { DSH_CI_FAILOVER_LINUX: mode } }))
+            .toBe(ci && !release && mode === 'blacksmith' ? 'blacksmith-4vcpu-ubuntu-2404' : 'ubuntu-latest')
+        }
+      }
+    }
+  })
+})
+
+describe('DeepSeek e2e workflow', () => {
+  it('prepares bubblewrap from the pinned payload without a package transaction', () => {
+    const workflow = loadWorkflow('.github/workflows/e2e.yml')
+    const e2e = workflowJob(workflow, 'e2e')
+    if (!Array.isArray(e2e.steps)) throw new TypeError('DeepSeek e2e workflow must define steps')
+
+    const steps = e2e.steps.filter(isRecord)
+    expect(steps.find(step => step.name === 'Prepare bubblewrap (unrestrict userns)')).toMatchObject({
+      run: 'bash scripts/prepare-ci-bubblewrap.sh',
+    })
+    expect(JSON.stringify(steps)).not.toContain('apt-get')
+  })
+
+  it('bounds profile subprocess fan-out to the tested e2e default', () => {
+    const workflow = loadWorkflow('.github/workflows/e2e.yml')
+    const e2e = workflowJob(workflow, 'e2e')
+    if (!Array.isArray(e2e.steps)) throw new TypeError('DeepSeek e2e workflow must define steps')
+
+    const step = e2e.steps.filter(isRecord).find(candidate => candidate.name === 'E2E tests (real DeepSeek API)')
+    expect(step).toMatchObject({ env: { DSH_E2E_MAX_WORKERS: 4 } })
+  })
+})
+
+describe('Python release workflows', () => {
+  it('keeps complete wheel validation separate from protected public publication', () => {
+    const workflow = loadWorkflow('.github/workflows/python-release.yml')
+    const dispatch = workflowEvent(workflow, 'workflow_dispatch')
+    const build = workflowJob(workflow, 'build')
+    const pythonCompat = workflowJob(workflow, 'python-compat')
+    const validate = workflowJob(workflow, 'validate')
+    const publishRuntime = workflowJob(workflow, 'publish-runtime')
+    const publishSdk = workflowJob(workflow, 'publish-sdk')
+    if (!isRecord(dispatch.inputs)
+      || !isRecord(dispatch.inputs.publish)
+      || !Array.isArray(pythonCompat.steps)
+      || !Array.isArray(validate.steps)
+      || !Array.isArray(publishRuntime.steps)
+      || !Array.isArray(publishSdk.steps)) {
+      throw new TypeError('Python release workflow must define publish input and release steps')
+    }
+
+    expect(dispatch.inputs.publish).toMatchObject({ type: 'boolean', default: false })
+    if (!isRecord(workflow.on)) throw new TypeError('python-release workflow must define on')
+    expect(Object.keys(workflow.on)).toEqual(['workflow_dispatch'])
+    expect(build).toMatchObject({
+      uses: './.github/workflows/build-exe-for-python-sdk.yml',
+      with: {
+        targets: 'node24-linux-x64,node24-linux-arm64,node24-macos-arm64,node24-macos-x64,node24-win-x64',
+        release: true,
+      },
+    })
+    expect(pythonCompat.strategy).toMatchObject({ matrix: { python: ['3.10', '3.14'] } })
+    const pythonCompatSteps = JSON.stringify(pythonCompat.steps)
+    expect(pythonCompatSteps).toContain('dist/deepseek_harness_sdk-$VERSION-py3-none-any.whl')
+    expect(pythonCompatSteps).toContain('dist/deepseek_harness_runtime_bin-$VERSION-py3-none-manylinux_2_28_x86_64.whl')
+    expect(pythonCompatSteps).not.toContain('--find-links')
+    const validateSteps = JSON.stringify(validate.steps)
+    const authorize = validate.steps.filter(isRecord).find(step => step.name === 'Authorize publication request')
+    if (!isRecord(authorize) || typeof authorize.run !== 'string') {
+      throw new TypeError('Python release validation must authorize publication requests')
+    }
+    expect(validateSteps).toContain('PUBLIC_PYPI_RELEASE_ENABLED')
+    expect(authorize).toMatchObject({
+      env: {
+        PYPI_PUBLISHER_REPOSITORY: '${{ vars.PYPI_PUBLISHER_REPOSITORY }}',
+        REPOSITORY: '${{ github.repository }}',
+      },
+    })
+    expect(authorize.run).toContain('[ "$REPOSITORY" = "$PYPI_PUBLISHER_REPOSITORY" ]')
+    expect(validateSteps).toContain('100000000')
+    expect(publishRuntime).toMatchObject({
+      if: "github.event_name == 'workflow_dispatch' && inputs.publish",
+      needs: 'validate',
+      environment: 'pypi-runtime',
+      permissions: { contents: 'read', 'id-token': 'write' },
+    })
+    expect(publishSdk).toMatchObject({
+      if: "github.event_name == 'workflow_dispatch' && inputs.publish",
+      needs: ['validate', 'publish-runtime'],
+      environment: 'pypi',
+      permissions: { contents: 'read', 'id-token': 'write' },
+    })
+    const runtimeSteps = publishRuntime.steps.filter(isRecord)
+    const sdkSteps = publishSdk.steps.filter(isRecord)
+    const runtimePublish = runtimeSteps.find(step => step.name === 'Publish runtime wheels')
+    const sdkPublish = sdkSteps.find(step => step.name === 'Publish SDK wheel')
+    const runtimeHashes = runtimeSteps.find(step => step.name === 'Verify release artifact hashes')
+    const sdkHashes = sdkSteps.find(step => step.name === 'Verify release artifact hashes')
+    expect([...runtimeSteps, ...sdkSteps].some(
+      step => typeof step.uses === 'string' && step.uses.startsWith('actions/checkout@'),
+    )).toBe(false)
+    expect([...runtimeSteps, ...sdkSteps].filter(
+      step => step.uses === 'pypa/gh-action-pypi-publish@release/v1',
+    )).toHaveLength(2)
+    expect(runtimePublish).toMatchObject({
+      with: { 'packages-dir': 'dist/runtime/', attestations: false },
+    })
+    expect(sdkPublish).toMatchObject({
+      with: { 'packages-dir': 'dist/sdk/', attestations: false },
+    })
+    expect(runtimeHashes).toMatchObject({ run: 'cd dist && sha256sum -c SHA256SUMS' })
+    expect(sdkHashes).toMatchObject({ run: 'cd dist && sha256sum -c SHA256SUMS' })
+  })
+
+  it('exposes the native wheel builder to the release caller with normalized versions', () => {
+    const workflow = loadWorkflow('.github/workflows/build-exe-for-python-sdk.yml')
+    expect(Object.keys(workflow.on as Record<string, unknown>).sort()).toEqual(['workflow_call', 'workflow_dispatch'])
+    const call = workflowEvent(workflow, 'workflow_call')
+    const plan = workflowJob(workflow, 'plan')
+    const build = workflowJob(workflow, 'build')
+    if (!isRecord(call.inputs) || !isRecord(call.secrets) || !Array.isArray(plan.steps) || !Array.isArray(build.steps)) {
+      throw new TypeError('Python wheel builder must define workflow_call inputs and plan steps')
+    }
+
+    const buildSteps: unknown[] = build.steps
+    const manylinuxAddon = buildSteps.find(step => isRecord(step) && step.name === 'Rebuild Linux node-pty against manylinux 2.28')
+    const macosCheck = buildSteps.find(step => isRecord(step) && step.name === 'Check macOS payload architecture and deployment target')
+    const manylinuxSmoke = buildSteps.find(step => isRecord(step) && step.name === 'Run wheel in a manylinux 2.28 container')
+    const cleanVenvPosix = buildSteps.find(step => isRecord(step) && step.name === 'Install local SDK and runtime wheels into a clean venv (POSIX)')
+    const cleanVenvWindows = buildSteps.find(step => isRecord(step) && step.name === 'Install local SDK and runtime wheels into a clean venv (Windows)')
+    const installedKeylessPosix = buildSteps.find(step => isRecord(step) && step.name === 'Run installed-wheel keyless black-box tests (POSIX)')
+    const installedKeylessWindows = buildSteps.find(step => isRecord(step) && step.name === 'Run installed-wheel keyless black-box tests (Windows)')
+    const realApiPreflightPosix = buildSteps.find(step => isRecord(step) && step.name === 'Preflight installed-wheel real API test (POSIX)')
+    const realApiPreflightWindows = buildSteps.find(step => isRecord(step) && step.name === 'Preflight installed-wheel real API test (Windows)')
+    const installedRealApiPosix = buildSteps.find(step => isRecord(step) && step.name === 'Run installed-wheel real API black-box test (POSIX)')
+    const installedRealApiWindows = buildSteps.find(step => isRecord(step) && step.name === 'Run installed-wheel real API black-box test (Windows)')
+    if (!isRecord(macosCheck) || typeof macosCheck.run !== 'string'
+      || !isRecord(cleanVenvPosix) || !isRecord(cleanVenvWindows)
+      || !isRecord(installedKeylessPosix) || !isRecord(installedKeylessWindows)
+      || !isRecord(realApiPreflightPosix) || !isRecord(realApiPreflightWindows)
+      || !isRecord(installedRealApiPosix) || !isRecord(installedRealApiWindows)) {
+      throw new TypeError('Python wheel builder must define native POSIX and Windows installed-wheel steps')
+    }
+    expect(call.inputs).toHaveProperty('targets')
+    expect(call.inputs).toMatchObject({
+      ci: { type: 'boolean', default: false },
+      release: { type: 'boolean', default: false },
+    })
+    expect(call.secrets).toMatchObject({
+      DEEPSEEK_API_KEY_EXTERNAL: { required: false },
+    })
+    expect(workflow.concurrency).toMatchObject({
+      group: 'build-single-exe-${{ github.workflow }}-${{ github.ref }}',
+    })
+    expect(build.defaults).toBeUndefined()
+    expect(plan.if).toContain('inputs.ci')
+    expect(plan.if).toContain('inputs.release')
+    expect(JSON.stringify(plan.steps)).toContain('pep440_version')
+    const workflowJson = JSON.stringify(workflow)
+    expect(workflowJson).toContain('macosx_14_0_arm64')
+    expect(workflowJson).toContain('macosx_14_0_x86_64')
+    expect(workflowJson).toContain('node24-macos-x64')
+    expect(workflowJson).toContain('macos-15-intel')
+    expect(workflowJson).toContain('win_amd64')
+    expect(workflowJson).toContain('node24-win-x64')
+    expect(workflowJson).toContain('windows-2025')
+    expect(workflowJson).toContain('dist-python/$SDK_WHEEL')
+    expect(workflowJson).toContain('dist-python/$RUNTIME_WHEEL')
+    expect(workflowJson).toContain('/work/dist-python/$SDK_WHEEL')
+    expect(workflowJson).toContain('/work/dist-python/$RUNTIME_WHEEL')
+    expect(workflowJson).not.toContain('--find-links dist-python')
+    expect(workflowJson).not.toContain('--find-links /work/dist-python')
+    expect(workflowJson).not.toContain('cygpath')
+    expect(manylinuxAddon).toMatchObject({ if: "runner.os == 'Linux'" })
+    expect(JSON.stringify(manylinuxAddon)).toContain('manylinux_2_28_x86_64')
+    expect(JSON.stringify(manylinuxAddon)).toContain('manylinux_2_28_aarch64')
+    expect(JSON.stringify(manylinuxAddon)).toContain('npm_config_build_from_source=true pnpm run install')
+    expect(JSON.stringify(manylinuxAddon)).toContain('pnpm_setup_root')
+    expect(JSON.stringify(manylinuxAddon)).toContain('$pnpm_setup_root:$pnpm_setup_root:ro')
+    expect(JSON.stringify(manylinuxAddon)).toContain('node-pty-glibc-versions.txt')
+    expect(JSON.stringify(manylinuxAddon)).toContain('le 2.28')
+    expect(macosCheck).toMatchObject({ if: "runner.os == 'macOS'" })
+    expect(macosCheck.run).toContain('scripts/check-macos-deployment-target.py')
+    expect(macosCheck.run).toContain('lipo "$payload" -verify_arch')
+    expect(macosCheck.run).toContain('$EXE-rg')
+    expect(macosCheck.run).toContain('$EXE-spawn-helper')
+    expect(JSON.stringify(installedKeylessPosix)).toContain('--scenario all')
+    expect(JSON.stringify(installedKeylessPosix)).toContain('env -u PYTHONPATH')
+    expect(JSON.stringify(installedKeylessWindows)).toContain('--scenario all --installed-wheel')
+    expect(installedKeylessWindows).toMatchObject({ if: "runner.os == 'Windows'", shell: 'pwsh' })
+    expect(cleanVenvWindows).toMatchObject({ if: "runner.os == 'Windows'", shell: 'pwsh' })
+    expect(JSON.stringify(cleanVenvWindows)).toContain('Scripts\\\\python.exe')
+    expect(realApiPreflightPosix).toMatchObject({
+      env: { DEEPSEEK_API_KEY: '${{ secrets.DEEPSEEK_API_KEY_EXTERNAL }}' },
+    })
+    expect(String(realApiPreflightPosix.if)).toContain('inputs.ci')
+    expect(String(realApiPreflightPosix.if)).toContain('head.repo.fork')
+    expect(String(realApiPreflightPosix.if)).toContain('dependabot[bot]')
+    expect(realApiPreflightWindows).toMatchObject({ shell: 'pwsh' })
+    for (const step of [installedRealApiPosix, installedRealApiWindows]) {
+      expect(step).toMatchObject({
+        env: {
+          DEEPSEEK_API_KEY: '${{ secrets.DEEPSEEK_API_KEY_EXTERNAL }}',
+          DEEPSEEK_BASE_URL: 'https://api.deepseek.com/anthropic',
+        },
+      })
+    }
+    expect(JSON.stringify(installedRealApiPosix)).toContain('--scenario sdk-live')
+    expect(JSON.stringify(installedRealApiPosix)).toContain('-u DSH_RUNTIME_MODE')
+    expect(installedRealApiWindows).toMatchObject({ shell: 'pwsh' })
+    expect(JSON.stringify(installedRealApiWindows)).toContain('--scenario sdk-live --installed-wheel')
+    expect(manylinuxSmoke).toMatchObject({ if: "runner.os == 'Linux'" })
+    expect(JSON.stringify(manylinuxSmoke)).toContain('-e DSH_TELEMETRY_DISABLED')
+  })
+
+  it('uses the shared macOS deployment-target check in GitLab', () => {
+    const workflow = loadWorkflow('.gitlab-ci.yml')
+    const runtimeWheel = workflow['.runtime-wheel']
+    if (!isRecord(runtimeWheel) || !Array.isArray(runtimeWheel.script)) {
+      throw new TypeError('GitLab CI must define the runtime wheel script')
+    }
+    const runtimeScript: unknown[] = runtimeWheel.script
+    const macosCheck = runtimeScript.find(
+      step => typeof step === 'string' && step.includes('${PLATFORM#macos-}'),
+    )
+    if (typeof macosCheck !== 'string') {
+      throw new TypeError('GitLab CI must check the macOS deployment target')
+    }
+
+    expect(macosCheck).toContain('scripts/check-macos-deployment-target.py')
+    expect(macosCheck).toContain('lipo "$payload" -verify_arch')
+    expect(macosCheck).toContain('"$EXE" "$EXE-rg" "$EXE-spawn-helper"')
+  })
+
+  it('builds the macOS x64 wheel on the matching GitLab runner', () => {
+    const workflow = loadWorkflow('.gitlab-ci.yml')
+    const macosX64 = workflow['runtime-macos-x64']
+    const publish = workflow['publish-python']
+    if (!isRecord(macosX64) || !isRecord(publish) || !Array.isArray(publish.needs)) {
+      throw new TypeError('GitLab CI must define the macOS x64 runtime and publication jobs')
+    }
+
+    expect(macosX64.tags).toEqual(['macos-x64'])
+    expect(macosX64.variables).toMatchObject({ PKG_TARGET: 'node24-macos-x64', PLATFORM: 'macos-x64' })
+    expect(publish.needs).toContainEqual({ job: 'runtime-macos-x64', artifacts: true })
+    expect(JSON.stringify(publish.script)).toContain('macosx_14_0_x86_64.whl')
+  })
+
+  it('builds and black-box tests the Windows x64 wheel in GitLab', () => {
+    const workflow = loadWorkflow('.gitlab-ci.yml')
+    const windows = workflow['runtime-windows-x64']
+    const publish = workflow['publish-python']
+    if (!isRecord(windows) || !Array.isArray(windows.before_script) || !Array.isArray(windows.script)
+      || !isRecord(publish) || !Array.isArray(publish.needs)) {
+      throw new TypeError('GitLab CI must define the Windows runtime and aggregate publication jobs')
+    }
+
+    expect(windows.tags).toEqual(['windows-x64'])
+    expect(windows.variables).toMatchObject({ PKG_TARGET: 'node24-win-x64', PLATFORM: 'win-x64' })
+    expect(JSON.stringify(windows.before_script)).toContain('.ci-python\\\\Scripts')
+    expect(JSON.stringify(windows.before_script)).toContain('[IO.Path]::PathSeparator')
+    expect(JSON.stringify(windows.script)).toContain('win_amd64.whl')
+    expect(JSON.stringify(windows.script)).toContain('--scenario all --installed-wheel')
+    expect(publish.needs).toContainEqual({ job: 'runtime-windows-x64', artifacts: true })
+  })
+})
+
+describe('Weighted approval workflow', () => {
+  it('publishes from the trusted default branch after pull request and review updates', () => {
+    const publisher = loadWorkflow('.github/workflows/weighted-approval.yml')
+    const reviewEvent = loadWorkflow('.github/workflows/weighted-approval-review-event.yml')
+    const pullRequest = workflowEvent(publisher, 'pull_request_target')
+    const workflowRun = workflowEvent(publisher, 'workflow_run')
+    const review = workflowEvent(reviewEvent, 'pull_request_review')
+    const job = workflowJob(publisher, 'publish-status')
+    const recordJob = workflowJob(reviewEvent, 'record-review-event')
+    if (!isRecord(publisher.on)) throw new TypeError('weighted-approval workflow must define events')
+    if (!isRecord(reviewEvent.on)) throw new TypeError('weighted-approval review event workflow must define events')
+    if (!Array.isArray(job.steps)) throw new TypeError('weighted-approval job must define steps')
+    if (!Array.isArray(recordJob.steps)) throw new TypeError('weighted-approval review event job must define steps')
+    const steps = job.steps.filter(isRecord)
+    const checkout = steps.find(step => step.name === 'Check out trusted approval policy')
+    const publish = steps.find(step => step.name === 'Publish weighted approval status')
+    const recordSteps = recordJob.steps.filter(isRecord)
+    const record = recordSteps.find(step => step.name === 'Record review event')
+
+    expect(publisher.name).toBe('weighted-approval')
+    expect(Object.keys(publisher.on)).toEqual(['pull_request_target', 'workflow_run'])
+    expect(pullRequest.types).toEqual(['opened', 'synchronize', 'reopened', 'ready_for_review', 'converted_to_draft'])
+    expect(workflowRun).toEqual({ workflows: ['weighted-approval-review-event'], types: ['completed'] })
+    expect(reviewEvent.name).toBe('weighted-approval-review-event')
+    expect(reviewEvent['run-name']).toBe('weighted-approval-review-event:${{ github.event.pull_request.number }}')
+    expect(Object.keys(reviewEvent.on)).toEqual(['pull_request_review'])
+    expect(review.types).toEqual(['submitted', 'edited', 'dismissed'])
+    expect(reviewEvent.permissions).toEqual({})
+    expect(publisher.permissions).toEqual({
+      contents: 'read',
+      'pull-requests': 'read',
+      statuses: 'write',
+    })
+    expect(publisher.concurrency).toEqual({
+      group: 'weighted-approval-${{ github.event.pull_request.number || github.event.workflow_run.head_sha }}',
+      'cancel-in-progress': false,
+    })
+    expect(job).toMatchObject({
+      if: "github.event_name != 'workflow_run' || github.event.workflow_run.conclusion == 'success'",
+      name: 'weighted approval publisher',
+      'runs-on': 'ubuntu-latest',
+      'timeout-minutes': 5,
+    })
+    expect(checkout).toMatchObject({
+      uses: 'actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1',
+      with: {
+        ref: '${{ github.event.repository.default_branch }}',
+        'persist-credentials': false,
+      },
+    })
+    expect(publish).toMatchObject({
+      env: {
+        GITHUB_TOKEN: '${{ github.token }}',
+        GITHUB_RUN_URL: '${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}',
+      },
+      run: 'node .github/review-ownership/check-approval.mjs',
+    })
+    expect(recordJob).toMatchObject({
+      name: 'record weighted approval review event',
+      'runs-on': 'ubuntu-latest',
+      'timeout-minutes': 2,
+    })
+    expect(record).toBeDefined()
+    expect(record?.run).toBe("echo 'Recorded a weighted approval review event.'")
+    expect(recordSteps).toHaveLength(1)
+    expect(JSON.stringify(publisher)).not.toContain('github.event.pull_request.head')
+    expect(JSON.stringify(publisher)).not.toContain('secrets.')
+    expect(JSON.stringify(reviewEvent)).not.toContain('github.token')
+    expect(JSON.stringify(reviewEvent)).not.toContain('secrets.')
+  })
+})
+
+describe('Issue lifecycle workflow', () => {
+  it('allocates lifecycle runners only for events that can change the board', () => {
+    const lifecycle = loadWorkflow('.github/workflows/issue-lifecycle.yml')
+    const policy = loadWorkflow('.github/workflows/issue-policy.yml')
+    const lifecycleJob = workflowJob(lifecycle, 'lifecycle')
+    if (!Array.isArray(lifecycleJob.steps)) throw new TypeError('Issue lifecycle job must define steps')
+
+    expect(lifecycle.on).toHaveProperty('pull_request')
+    expect(lifecycle.on).toHaveProperty('pull_request_review')
+    expect(lifecycleJob.if).toContain("github.event.review.state == 'changes_requested'")
+    expect(lifecycleJob.if).toContain('github.event.changes.body != null')
+    // Keep the subscription-type gates: issue-lifecycle does not re-subscribe
+    // ready_for_review (issue-policy owns that) and only reacts to submitted
+    // review events.
+    const lifecyclePullRequest = workflowEvent(lifecycle, 'pull_request')
+    const lifecycleReview = workflowEvent(lifecycle, 'pull_request_review')
+    expect(lifecyclePullRequest.types).toContain('opened')
+    expect(lifecyclePullRequest.types).not.toContain('ready_for_review')
+    expect(lifecyclePullRequest.types).toContain('review_requested')
+    expect(lifecycleReview.types).toEqual(['submitted'])
+    expect(lifecyclePullRequest.types).not.toContain('synchronize')
+    expect(lifecyclePullRequest.types).not.toContain('labeled')
+    expect(lifecyclePullRequest.types).not.toContain('unlabeled')
+    const issueEvents = workflowEvent(lifecycle, 'issues')
+    expect(issueEvents.types).not.toContain('assigned')
+    expect(issueEvents.types).not.toContain('unassigned')
+    expect(issueEvents.types).toContain('typed')
+    expect(issueEvents.types).toContain('untyped')
+    const steps = lifecycleJob.steps.filter(isRecord)
+    const tokenStep = steps.find(s => s.name === 'Create project token')
+    const handleStep = steps.find(s => s.name === 'Handle repository event')
+    expect(tokenStep?.if).toBeUndefined()
+    expect(handleStep?.if).toBeUndefined()
+
+    // issue-policy owns PR validation; it is read-only and a real gate.
+    const policyPullRequest = workflowEvent(policy, 'pull_request')
+    expect(policyPullRequest.types).toContain('ready_for_review')
+  })
+
+  it('mints Project credentials only after preflight and always revalidates current metadata', () => {
+    const policy = loadWorkflow('.github/workflows/issue-policy.yml')
+    const policyJob = workflowJob(policy, 'policy')
+    if (!Array.isArray(policyJob.steps)) throw new TypeError('Issue policy job must define steps')
+    const steps = policyJob.steps.filter(isRecord)
+    const tokenStep = steps.find(step => step.name === 'Create Project read token')
+    const validateStep = steps.find(step => step.name === 'Validate pull request')
+    const preflightStep = steps.find(step => step.id === 'preflight')
+    expect(preflightStep).toMatchObject({ shell: 'bash' })
+    expect(preflightStep?.run).toContain('if [ -f .github/issue-management/selective-preflight.json ]; then')
+    expect(preflightStep?.run).toContain('node .github/issue-management/policy.mjs pr-preflight')
+    expect(preflightStep?.if).toBeUndefined()
+    expect(policyJob.if).toBeUndefined()
+    expect(validateStep?.if).toBe("${{ steps.preflight.outputs.legacy-automated != 'true' }}")
+
+    expect(tokenStep).toMatchObject({
+      id: 'app-token',
+      if: "${{ steps.preflight.outputs.needs-project == 'true' }}",
+      uses: 'actions/create-github-app-token@bcd2ba49218906704ab6c1aa796996da409d3eb1',
+      with: {
+        'client-id': '${{ vars.DSH_ISSUE_APP_CLIENT_ID }}',
+        'private-key': '${{ secrets.DSH_ISSUE_APP_PRIVATE_KEY }}',
+        owner: 'deepseek-harness',
+        repositories: 'deepseek-harness',
+        'permission-issues': 'read',
+        'permission-organization-projects': 'read',
+      },
+    })
+    expect(validateStep).toMatchObject({
+      env: {
+        GITHUB_TOKEN: '${{ github.token }}',
+        PROJECT_TOKEN: '${{ steps.app-token.outputs.token }}',
+      },
+    })
+  })
+})
+
+describe('npm release workflows', () => {
+  it('keeps publication dispatch-only and pack in the PR workflow', () => {
+    // pack stays in the PR/master release workflows so a PR proves the set packs.
+    for (const file of ['release.yml', 'release-vendor.yml']) {
+      const workflow = loadWorkflow(`.github/workflows/${file}`)
+      if (!isRecord(workflow.jobs)) throw new TypeError(`${file} must define jobs`)
+      expect(Object.keys(workflow.jobs).sort()).toEqual(file === 'release.yml' ? ['dependencies', 'pack'] : ['pack'])
+    }
+
+    // publication is workflow_dispatch-only (never a PR check) and keeps the
+    // npm-publish environment plus the shared dist-tag group.
+    for (const file of ['release-publish.yml', 'release-vendor-publish.yml']) {
+      const workflow = loadWorkflow(`.github/workflows/${file}`)
+      if (!isRecord(workflow.on) || !isRecord(workflow.jobs)) throw new TypeError(`${file} must define on and jobs`)
+      expect(Object.keys(workflow.on)).toEqual(['workflow_dispatch'])
+      const publish = workflow.jobs.publish
+      if (!isRecord(publish)) throw new TypeError(`${file} must define a publish job`)
+      expect(publish.environment).toBe('npm-publish')
+      expect(publish.concurrency).toMatchObject({ group: 'Release-publish' })
+    }
+  })
+
+  it('runs dependency policy and npm layout checks in the DSH release workflow', () => {
+    const workflow = loadWorkflow('.github/workflows/release.yml')
+    const dependencies = workflowJob(workflow, 'dependencies')
+    if (!isRecord(workflow.on) || !Array.isArray(dependencies.steps)) {
+      throw new TypeError('DSH release workflow must define triggers and dependency steps')
+    }
+    const commands = dependencies.steps.flatMap(step =>
+      isRecord(step) && typeof step.run === 'string' ? [step.run] : [])
+
+    expect(Object.keys(workflow.on).sort()).toEqual(['pull_request', 'push', 'workflow_dispatch'])
+    expect(commands).toContain('pnpm run verify-package-dependencies')
+    expect(commands).toContain('pnpm run verify-npm-install-layout')
+  })
+})
+
+describe('Documentation site publication', () => {
+  it('keeps Pages deployment dispatch-only from a dsh-v* tag', () => {
+    const workflow = loadWorkflow('.github/workflows/docs-pages.yml')
+    const build = workflowJob(workflow, 'build')
+    const deploy = workflowJob(workflow, 'deploy')
+    if (!isRecord(workflow.on) || !isRecord(workflow.env) || !Array.isArray(build.steps)) {
+      throw new TypeError('Documentation deployment must define on, env, and build steps')
+    }
+
+    // The site presents a released snapshot: a merge must never publish it, and
+    // publication must never appear as a PR check.
+    expect(Object.keys(workflow.on)).toEqual(['workflow_dispatch'])
+
+    // RELEASE_PUBLISH makes release:verify reject every ref that is not a dsh-v*
+    // tag naming this tree's version, so the site and the npm sequence share one
+    // definition of a released version.
+    const steps = build.steps.filter(isRecord)
+    const verify = steps.find(step => step.name === 'Verify release version')
+    const checkout = steps.find(
+      step => typeof step.uses === 'string' && step.uses.startsWith('actions/checkout@'),
+    )
+    expect(verify).toMatchObject({
+      env: { RELEASE_PUBLISH: 'true' },
+      run: 'pnpm run release:verify --family dsh',
+    })
+    // Complete history: the release scripts read tags.
+    expect(checkout).toMatchObject({ with: { 'fetch-depth': 0 } })
+
+    // Projected source links stay on the public repository's master. That
+    // repository advances only to each release commit, so its master never
+    // carries unreleased work, while it retains only the most recent tags:
+    // following the dispatched tag would leave every source link on a deploy
+    // from an older tag unresolvable.
+    expect(workflow.env.DOCS_REPOSITORY_REF).toBe('master')
+
+    // The environment owns the deployment tag policy and the required reviewers.
+    expect(deploy.environment).toMatchObject({ name: 'github-pages' })
+  })
+})
+
+describe('Git hooks', () => {
+  it('leaves frozen Agent Note sidecars to the archive verifier', () => {
+    const lefthook = loadWorkflow('lefthook.yml')
+
+    for (const hookName of ['pre-commit', 'pre-merge-commit']) {
+      const hook = lefthook[hookName]
+      if (!isRecord(hook) || !Array.isArray(hook.jobs)) {
+        throw new TypeError(`lefthook must define ${hookName} jobs`)
+      }
+      const pairing: unknown = hook.jobs.find(
+        (job: unknown) => isRecord(job) && job.name === 'translation pairing (staged records)',
+      )
+
+      expect(pairing).toMatchObject({ exclude: ['.agents/notes/archived/**'] })
+    }
+  })
+})
+
+function loadWorkflow(path: string): Record<string, unknown> {
+  const workflow: unknown = yaml.load(readFileSync(resolve(root, path), 'utf8'))
+  if (!isRecord(workflow)) throw new TypeError(`${path} must define a workflow`)
+  return workflow
+}
+
+function workflowEvent(workflow: Record<string, unknown>, event: string): Record<string, unknown> {
+  if (!isRecord(workflow.on) || !isRecord(workflow.on[event])) {
+    throw new TypeError(`workflow must define the ${event} event`)
+  }
+  return workflow.on[event]
+}
+
+function workflowJob(workflow: Record<string, unknown>, job: string): Record<string, unknown> {
+  if (!isRecord(workflow.jobs) || !isRecord(workflow.jobs[job])) {
+    throw new TypeError(`workflow must define the ${job} job`)
+  }
+  return workflow.jobs[job]
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}

scripts/client-bundle-purity.spec.ts

@@ -0,0 +1,442 @@
+/**
+ * Pins shared client-bundle preset rules: module-edge purity, source-map
+ * chaining, and physical watch dependencies hidden behind virtual CSS Modules.
+ */
+import { existsSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join, relative } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { build, type TsdownBundle, type UserConfig } from 'tsdown'
+import { describe, expect, it, onTestFinished, vi } from 'vitest'
+import { clientBundle, requestedExternals, staticLinked } 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>
+}
+
+interface SourceMapPlugin {
+  name: string
+  load?: (id: string) => Promise<unknown>
+}
+
+interface InputIsolationPlugin {
+  name: string
+  generateBundle: (this: {
+    getModuleInfo(id: string): { importedIds: string[]; dynamicallyImportedIds: string[] } | null
+  }, options: unknown, bundle: Record<string, {
+      type: 'chunk'
+      modules: Record<string, object>
+      imports: string[]
+      dynamicImports: string[]
+    }>) => void
+}
+
+/** A representative dynamic bundle using the shared client baseline. */
+const REQUESTING_PACKAGE = '@deepseek-ai/dsh-client-ui-conversation'
+
+function clientConfigs(id = REQUESTING_PACKAGE) {
+  return clientBundle(id, ['lib/types/index.js', 'lib/types/invariant.js'])(
+    { env: { DSH_BUILD_FACE: 'client' } },
+  ).filter(config => config.platform === 'browser')
+}
+
+describe('client bundle build faces', () => {
+  it('watches source in development and consumes emitted JavaScript in the Client build', () => {
+    const bundle = clientBundle('@deepseek-ai/dsh-client-test', ['lib/types/index.js'])
+    const development = bundle({ env: {} }).find(config => config.platform === 'browser')
+    const artifact = bundle({ env: { DSH_BUILD_FACE: 'client' } })
+      .find(config => config.platform === 'browser')
+
+    expect(development?.entry).toEqual({ client: 'src/client/index.ts' })
+    expect(artifact?.entry).toEqual({ client: 'lib/types/client/index.js' })
+  })
+})
+
+function clientSourceMapPath(packagePath: string): string {
+  return fileURLToPath(new URL(`../packages/${packagePath}/lib/client.js.map`, import.meta.url))
+}
+
+function purityResolveId(id = REQUESTING_PACKAGE): ResolveId {
+  // libEntry is spelled at every call site (no default) so the
+  // package-invariants text check can see the invariant entry per package.
+  const configs = clientConfigs(id)
+  const plugins = (configs[0] as { plugins: { name: string; resolveId?: unknown }[] }).plugins
+  const gate = plugins.find(p => p.name === 'dsh-client-bundle-purity')
+  if (gate?.resolveId === undefined) throw new Error('purity plugin missing from client config')
+  return gate.resolveId as ResolveId
+}
+
+function cssModulePlugin(): CssModulePlugin {
+  const configs = clientConfigs()
+  const plugins = (configs[0] 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
+}
+
+function sourceMapPlugin(): SourceMapPlugin {
+  const configs = clientConfigs()
+  const plugins = (configs[0] as { plugins: SourceMapPlugin[] }).plugins
+  const plugin = plugins.find(candidate => candidate.name === 'dsh-tsc-sourcemap')
+  if (plugin?.load === undefined) throw new Error('tsc sourcemap plugin missing from client config')
+  return plugin
+}
+
+describe('client bundle purity gate', () => {
+  const resolveId = purityResolveId()
+
+  it('leaves default externals and non-scoped specifiers alone', () => {
+    expect(resolveId('@deepseek-ai/dsh-client-store')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-client-ui-slots')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-client-ui-primitives')).toBeNull()
+    expect(resolveId('react')).toBeNull()
+    expect(resolveId('zod')).toBeNull()
+  })
+
+  it('rejects the retired web-react platform package', () => {
+    expect(() => resolveId('@deepseek-ai/dsh-client-web-react')).toThrow(/purity/)
+    expect(() => resolveId('@deepseek-ai/dsh-client-web-react/store')).toThrow(/purity/)
+  })
+
+  it('lets inline-safe libraries inline', () => {
+    expect(resolveId('@deepseek-ai/dsh-session/surface')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-brand')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-deque')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-util-values')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-token-meter/client')).toBeNull()
+    expect(() => resolveId('@deepseek-ai/dsh-token-meter')).toThrow(/purity/)
+    expect(() => resolveId('@deepseek-ai/dsh-token-meter/client/internal')).toThrow(/purity/)
+    expect(resolveId('@deepseek-ai/dsh-host-open-in-app/shared')).toBeNull()
+    expect(() => resolveId('@deepseek-ai/dsh-host-open-in-app')).toThrow(/purity/)
+  })
+
+  it('admits only the pure spill notice entry, not its Host policy', () => {
+    expect(resolveId('@deepseek-ai/dsh-spill-policy/notice')).toBeNull()
+    expect(resolveId('@deepseek-ai/dsh-output-retention')).toBeNull()
+    expect(() => resolveId('@deepseek-ai/dsh-spill-policy')).toThrow(/purity/)
+    expect(() => resolveId('@deepseek-ai/dsh-spill-policy/notice/internal')).toThrow(/purity/)
+  })
+
+  it('lets exact generated Remote contributions inline without admitting their package implementation', () => {
+    expect(resolveId('@deepseek-ai/dsh-goal/remote')).toBeNull()
+    expect(() => resolveId('@deepseek-ai/dsh-goal')).toThrow(/purity/)
+    expect(() => resolveId('@deepseek-ai/dsh-goal/client')).toThrow(/purity/)
+    expect(() => resolveId('@deepseek-ai/dsh-goal/remote/nested')).toThrow(/purity/)
+  })
+
+  it('throws on any other @deepseek-ai leak', () => {
+    expect(() => resolveId('@deepseek-ai/dsh-agent')).toThrow(/purity/)
+    expect(() => resolveId('@deepseek-ai/dsh-client-web')).toThrow(/purity/)
+  })
+
+  it('throws on cross-plugin value imports — bare plugin names and /client subpaths alike', () => {
+    expect(() => resolveId('@deepseek-ai/dsh-client-connection')).toThrow(/purity/)
+    expect(() => resolveId('@deepseek-ai/dsh-client-ui-session')).toThrow(/purity/)
+    expect(() => resolveId('@deepseek-ai/dsh-client-ui-layout/client')).toThrow(/purity/)
+  })
+
+  it('admits package-specific requests only for the declaring bundle', () => {
+    const requesting = purityResolveId('@deepseek-ai/dsh-api-session-controller')
+    expect(requesting('@deepseek-ai/dsh-api-gateway/client')).toBeNull()
+    expect(() => resolveId('@deepseek-ai/dsh-api-gateway/client')).toThrow(/purity/)
+  })
+
+  it('externalizes the baseline independently of each package manifest', () => {
+    const requesting = clientConfigs()[0]?.deps as { neverBundle: (specifier: string) => boolean }
+    const plain = clientConfigs('@deepseek-ai/dsh-client-connection')[0]?.deps as {
+      neverBundle: (specifier: string) => boolean
+    }
+
+    expect(requesting.neverBundle('react')).toBe(true)
+    expect(requesting.neverBundle('zod')).toBe(false)
+    expect(plain.neverBundle('react')).toBe(true)
+    expect(plain.neverBundle('@deepseek-ai/dsh-client-store')).toBe(true)
+  })
+})
+
+describe('client bundle experimental input isolation', () => {
+  const experimental = '@deepseek-ai/dsh-experimental-client-ui-agent-team'
+
+  function fixture() {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-client-inputs-'))
+    onTestFinished(() => { rmSync(root, { recursive: true, force: true }) })
+    const owner = join(root, 'client')
+    const entry = join(owner, 'lib/types/client/index.js')
+    const prototype = join(root, 'prototype/src/index.js')
+    for (const file of [entry, prototype]) mkdirSync(dirname(file), { recursive: true })
+    writeFileSync(join(owner, 'package.json'), JSON.stringify({ name: REQUESTING_PACKAGE, type: 'module' }))
+    writeFileSync(join(root, 'prototype/package.json'), JSON.stringify({ name: experimental, type: 'module' }))
+    writeFileSync(prototype, 'export const marker = "experimental sentinel"\n')
+    return { root, owner, entry, prototype }
+  }
+
+  function config(kind: 'static' | 'dynamic', id = REQUESTING_PACKAGE): UserConfig {
+    const configs = kind === 'static'
+      ? staticLinked(id, ['lib/types/client/index.js'])({ env: { DSH_BUILD_FACE: 'client' } })
+      : clientConfigs(id)
+    const browser = configs.find(config => config.platform === 'browser')
+    if (browser === undefined) throw new Error('client config missing')
+    return browser
+  }
+
+  async function bundle(owner: string, config: UserConfig): Promise<string> {
+    let builds: TsdownBundle[] = []
+    try {
+      builds = await build({
+        ...config, cwd: owner, config: false, tsconfig: false,
+        write: false, clean: false, exports: false, report: false, logLevel: 'silent',
+      })
+      return builds.flatMap(build => build.chunks.filter(chunk => chunk.type === 'chunk').map(chunk => chunk.code)).join('\n')
+    } finally {
+      for (const build of builds) await build[Symbol.asyncDispose]()
+    }
+  }
+
+  function importPath(from: string, to: string): string {
+    return relative(dirname(from), to).replaceAll('\\', '/')
+  }
+
+  function checkCompilerModule(module: string, imports?: string[]): void {
+    const plugins = config('dynamic').plugins as InputIsolationPlugin[]
+    const plugin = plugins.find(plugin => plugin.name === 'dsh-client-input-isolation')
+    if (plugin === undefined) throw new Error('client input isolation plugin missing')
+    plugin.generateBundle.call({
+      getModuleInfo: () => imports === undefined ? null : { importedIds: imports, dynamicallyImportedIds: [] },
+    }, {}, {
+      'client.js': { type: 'chunk', modules: { [module]: {} }, imports: [], dynamicImports: [] },
+    })
+  }
+
+  it('accepts the exact compiler runtime helper without a source module record', () => {
+    expect(() => { checkCompilerModule('\0rolldown/runtime.js') }).not.toThrow()
+  })
+
+  it.each(['\0rolldown/other.js', '\0rolldown/runtime.js?user', '\0other/runtime.js'])(
+    'rejects the unrecorded module %j',
+    (module) => {
+      expect(() => { checkCompilerModule(module) }).toThrow(/has no bundler module record/)
+    },
+  )
+
+  it('checks runtime helper dependencies when the compiler supplies a module record', () => {
+    expect(() => { checkCompilerModule('\0rolldown/runtime.js', [experimental]) })
+      .toThrow(/client bundle isolation.*experimental/)
+  })
+
+  it.each(['static', 'dynamic'] as const)('rejects experimental files folded into a %s client artifact', async (kind) => {
+    const { owner, entry, prototype } = fixture()
+    writeFileSync(entry, `export { marker } from ${JSON.stringify(importPath(entry, prototype))}\n`)
+
+    await expect(bundle(owner, config(kind))).rejects.toThrow(/client bundle isolation.*experimental/)
+    expect(existsSync(join(owner, 'lib/client.js'))).toBe(false)
+    expect(existsSync(join(owner, 'lib/index.js'))).toBe(false)
+  })
+
+  it('proves the static library otherwise hides the experimental input in its emitted JavaScript', async () => {
+    const { owner, entry, prototype } = fixture()
+    writeFileSync(entry, `export { marker } from ${JSON.stringify(importPath(entry, prototype))}\n`)
+    const guarded = config('static')
+    const plugins = guarded.plugins as Array<{ name: string }>
+    const unguarded: UserConfig = {
+      ...guarded,
+      plugins: plugins.filter(plugin => plugin.name !== 'dsh-client-input-isolation'),
+      outputOptions: { sourcemapExcludeSources: false },
+    }
+
+    await expect(bundle(owner, unguarded)).resolves.toContain('experimental sentinel')
+    await expect(bundle(owner, guarded)).rejects.toThrow(/client bundle isolation.*experimental/)
+  })
+
+  it.each(['static', 'dynamic'] as const)('allows an experimental %s artifact to keep its own inputs', async (kind) => {
+    const { owner, entry, prototype } = fixture()
+    writeFileSync(entry, `export { marker } from ${JSON.stringify(importPath(entry, prototype))}\n`)
+
+    await expect(bundle(owner, config(kind, experimental))).resolves.toContain('experimental sentinel')
+  })
+
+  it('rejects experimental ownership preserved only by an emitted compiler source map', async () => {
+    const { owner, entry, prototype } = fixture()
+    writeFileSync(entry, 'export const marker = "experimental sentinel"\n//# sourceMappingURL=index.js.map\n')
+    writeFileSync(`${entry}.map`, JSON.stringify({
+      version: 3, names: [], mappings: 'AAAA', sources: [importPath(entry, prototype)],
+      sourcesContent: ['export const marker = "experimental sentinel"\n'],
+    }))
+
+    await expect(bundle(owner, config('static'))).rejects.toThrow(/client bundle isolation.*experimental/)
+  })
+
+  it('checks the resolved module when an import alias conceals its experimental package', async () => {
+    const { owner, entry, prototype } = fixture()
+    writeFileSync(entry, 'export { marker } from "./ordinary.js"\n')
+
+    await expect(bundle(owner, { ...config('static'), alias: { './ordinary.js': prototype } }))
+      .rejects.toThrow(/client bundle isolation.*experimental/)
+  })
+
+  it('rejects an experimental runtime import left external by a static client library', async () => {
+    const { owner, entry } = fixture()
+    writeFileSync(entry, `export * from ${JSON.stringify(experimental)}\n`)
+
+    await expect(bundle(owner, config('static'))).rejects.toThrow(/client bundle isolation.*experimental/)
+  })
+
+  it.each([false, true])('checks omitted source-map files against their package owner (experimental: %s)', async (experimentalSource) => {
+    const { root, owner, entry } = fixture()
+    const dependency = join(root, 'dependency')
+    mkdirSync(dependency)
+    writeFileSync(join(dependency, 'package.json'), JSON.stringify({ name: experimentalSource ? experimental : 'ordinary-library' }))
+    writeFileSync(entry, 'export const marker = "mapped sentinel"\n//# sourceMappingURL=index.js.map\n')
+    writeFileSync(`${entry}.map`, JSON.stringify({
+      version: 3, names: [], mappings: 'AAAA', sourceRoot: importPath(entry, dependency),
+      sources: ['unshipped.ts'], sourcesContent: ['export const marker = "mapped sentinel"\n'],
+    }))
+
+    const result = bundle(owner, config('static'))
+    if (experimentalSource) await expect(result).rejects.toThrow(/client bundle isolation.*experimental/)
+    else await expect(result).resolves.toContain('mapped sentinel')
+  })
+
+  it.each(['.css', '.module.css', '.css?inline'])('rejects experimental %s inputs behind client CSS virtual loaders', async (extension) => {
+    const { owner, entry, prototype } = fixture()
+    const css = join(dirname(prototype), `style${extension.replace('?inline', '')}`)
+    writeFileSync(css, 'body { color: red; }\n')
+    const specifier = `${importPath(entry, css)}${extension.endsWith('?inline') ? '?inline' : ''}`
+    writeFileSync(entry, extension === '.css'
+      ? `import ${JSON.stringify(specifier)}\nexport const marker = true\n`
+      : `export { default as style } from ${JSON.stringify(specifier)}\n`)
+
+    await expect(bundle(owner, config('dynamic'))).rejects.toThrow(/client bundle isolation.*experimental/)
+  })
+
+  it.each(['static', 'dynamic'] as const)('keeps ordinary %s bundles and source maps buildable', async (kind) => {
+    const { owner, entry } = fixture()
+    const source = join(owner, 'src/client/index.ts')
+    mkdirSync(dirname(source), { recursive: true })
+    writeFileSync(source, 'export const marker = "stable sentinel"\n')
+    writeFileSync(entry, 'export const marker = "stable sentinel"\n//# sourceMappingURL=index.js.map\n')
+    writeFileSync(`${entry}.map`, JSON.stringify({
+      version: 3, names: [], mappings: 'AAAA', sources: [importPath(entry, source)],
+      sourcesContent: ['export const marker = "stable sentinel"\n'],
+    }))
+
+    await expect(bundle(owner, config(kind))).resolves.toContain('stable sentinel')
+  })
+})
+
+describe('client bundle module requests', () => {
+  it('requests what the declaration lists', () => {
+    const requests = requestedExternals('@deepseek-ai/dsh-client-fixture', {
+      external: ['react', 'react/jsx-runtime', '@deepseek-ai/dsh-client-ui-slots'],
+    })
+
+    expect([...requests].sort()).toEqual([
+      '@deepseek-ai/dsh-client-ui-slots', 'react', 'react/jsx-runtime',
+    ])
+  })
+
+  it('requests nothing when the declaration is absent', () => {
+    expect(requestedExternals('@deepseek-ai/dsh-client-fixture', {}).size).toBe(0)
+  })
+
+  it('rejects a malformed declaration instead of reading past it', () => {
+    expect(() => requestedExternals('@deepseek-ai/dsh-client-fixture', { external: 'react' }))
+      .toThrow(/dsh\.client\.external must be a string array/)
+  })
+})
+
+describe('client bundle debug artifacts', () => {
+  it('emits source maps for plugin TS and TSX outside the Vite module graph', () => {
+    const configs = clientConfigs()
+    expect(configs[0]?.sourcemap).toBe(true)
+    expect(configs[0]?.outputOptions).toMatchObject({ sourcemapExcludeSources: false })
+  })
+
+  it('chains emitted tsc maps when the production Client build consumes lib/types', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-client-sourcemap-'))
+    try {
+      const entry = join(root, 'lib', 'types', 'client', 'index.js')
+      const source = join(root, 'src', 'client', 'index.ts')
+      const map = { version: 3, names: [], mappings: 'AAAA', sources: ['../../../src/client/index.ts'] }
+      mkdirSync(join(root, 'lib', 'types', 'client'), { recursive: true })
+      mkdirSync(join(root, 'src', 'client'), { recursive: true })
+      writeFileSync(entry, 'export const marker = true\n//# sourceMappingURL=index.js.map\n')
+      writeFileSync(`${entry}.map`, JSON.stringify(map))
+      writeFileSync(source, 'export const marker: true = true\n')
+
+      await expect(sourceMapPlugin().load!(entry)).resolves.toEqual({
+        code: 'export const marker = true',
+        map: { ...map, sourcesContent: ['export const marker: true = true\n'] },
+      })
+    } finally {
+      rmSync(root, { recursive: true, force: true })
+    }
+  })
+
+  it('maps first-party sources to their repository package paths', () => {
+    const configs = clientConfigs('@deepseek-ai/dsh-client-ui-goal')
+    const outputOptions = configs[0]?.outputOptions
+    if (typeof outputOptions !== 'object' || outputOptions === null) throw new Error('client output options missing')
+    const transform = outputOptions.sourcemapPathTransform
+    if (transform === undefined) throw new Error('client sourcemap path transform missing')
+
+    const source = transform('../src/client/GoalBar.tsx', clientSourceMapPath('client/ui-goal'))
+    expect(source).toBe('../../../packages/client/ui-goal/src/client/GoalBar.tsx')
+    const resolved = new URL(source, 'https://dsh.test/plugins/@deepseek-ai/dsh-client-ui-goal/client.js.map')
+    expect(resolved.pathname).toBe('/packages/client/ui-goal/src/client/GoalBar.tsx')
+  })
+
+  it('maps dual-face host sources to the host package group', () => {
+    const configs = clientConfigs('@deepseek-ai/dsh-host-directory-picker-native')
+    const outputOptions = configs[0]?.outputOptions
+    if (typeof outputOptions !== 'object' || outputOptions === null) throw new Error('client output options missing')
+    const transform = outputOptions.sourcemapPathTransform
+    if (transform === undefined) throw new Error('client sourcemap path transform missing')
+
+    const source = transform('../src/client/index.ts', clientSourceMapPath('host/directory-picker-native'))
+    expect(source).toBe('../../../packages/host/directory-picker-native/src/client/index.ts')
+  })
+
+  it('maps inlined workspace sources to packages and leaves dependencies outside it unchanged', () => {
+    const configs = clientConfigs('@deepseek-ai/dsh-client-connection')
+    const outputOptions = configs[0]?.outputOptions
+    if (typeof outputOptions !== 'object' || outputOptions === null) throw new Error('client output options missing')
+    const transform = outputOptions.sourcemapPathTransform
+    if (transform === undefined) throw new Error('client sourcemap path transform missing')
+
+    const sourceMapPath = clientSourceMapPath('client/connection')
+    const workspaceSource = transform('../src/rpc.ts', sourceMapPath)
+    expect(workspaceSource).toBe('../../../packages/client/connection/src/rpc.ts')
+    const resolved = new URL(workspaceSource, 'https://dsh.test/plugins/@deepseek-ai/dsh-client-connection/client.js.map')
+    expect(resolved.pathname).toBe('/packages/client/connection/src/rpc.ts')
+
+    const dependencySource = '../../../../node_modules/.pnpm/zod@4.4.3/node_modules/zod/index.js'
+    expect(transform(dependencySource, sourceMapPath)).toBe(dependencySource)
+  })
+})
+
+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)
+  })
+})

scripts/cordis-walk.ts

@@ -0,0 +1,102 @@
+/**
+ * AST helpers shared by the Cordis generators: locate the Cordis module merge
+ * in a source file and enumerate the `interface Context` keys it declares.
+ * The vendored core API projector consumes the merge body; the per-subsystem
+ * region generator's exhaustiveness backstop consumes the key scan.
+ */
+
+import { globSync, readFileSync } from 'node:fs'
+import { resolve, sep } from 'node:path'
+import ts from 'typescript'
+
+/** Cheap textual prefilter for a cordis module merge, quote-style agnostic
+ * (the AST match below reads `stmt.name.text` and never sees the quotes). */
+const MERGE_HEAD = /declare module ['"](?:@deepseek-ai\/cordis|\.\/context\.ts)['"]/
+
+/**
+ * Parse every file matching `patterns` (repo-relative, sorted, `/`-normalized)
+ * that textually contains a cordis module merge, yielding one entry per merge
+ * BLOCK — a file may legally hold several `declare module '@deepseek-ai/cordis'` blocks
+ * (the Typert analyzer reads them all), so the exhaustiveness scan must too.
+ * Files without a merge are skipped.
+ * @param scanRoot - Repository root the patterns are resolved against.
+ * @param patterns - Glob(s) selecting the TypeScript files to scan.
+ * @returns One entry per cordis module block, in path then source order.
+ */
+export function contextMergeFiles(
+  scanRoot: string,
+  patterns: string | readonly string[],
+): { rel: string; sf: ts.SourceFile; text: string; body: ts.ModuleBlock }[] {
+  const out: { rel: string; sf: ts.SourceFile; text: string; body: ts.ModuleBlock }[] = []
+  const rels = [...new Set(globSync(patterns as string | string[], { cwd: scanRoot }).map(s => s.split(sep).join('/')))].sort()
+  for (const rel of rels) {
+    const abs = resolve(scanRoot, rel)
+    const text = readFileSync(abs, 'utf8')
+    if (!MERGE_HEAD.test(text)) continue
+    const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
+    for (const body of cordisModuleBodies(sf)) out.push({ rel, sf, text, body })
+  }
+  return out
+}
+
+/** Every cordis module-merge body in `sf`: `declare module '@deepseek-ai/cordis'` (harness
+ * packages) or `declare module './context.ts'` (vendor core), in source order.
+ * Module-local: consumers walk blocks through {@link contextMergeFiles}. */
+function cordisModuleBodies(sf: ts.SourceFile): ts.ModuleBlock[] {
+  const bodies: ts.ModuleBlock[] = []
+  for (const stmt of sf.statements) {
+    if (!ts.isModuleDeclaration(stmt) || !ts.isStringLiteral(stmt.name)) continue
+    if (stmt.name.text !== '@deepseek-ai/cordis' && stmt.name.text !== './context.ts') continue
+    if (stmt.body && ts.isModuleBlock(stmt.body)) bodies.push(stmt.body)
+  }
+  return bodies
+}
+
+/** The FIRST cordis module-merge body in `sf`, or null without one — for the
+ * vendor core-API renderer whose input files carry exactly one merge; the
+ * exhaustiveness scan uses {@link cordisModuleBodies} to read them all. */
+export function cordisModuleBody(sf: ts.SourceFile): ts.ModuleBlock | null {
+  return cordisModuleBodies(sf)[0] ?? null
+}
+
+/**
+ * Every `key: Type` property a `declare module '@deepseek-ai/cordis'` Context merge
+ * declares in one module body.
+ * @param body - The cordis module augmentation block.
+ * @param sf - Owning source file (for text extraction).
+ * @returns key → declared type-name text, in declaration order.
+ */
+export 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
+}
+
+/**
+ * Every event name a `declare module '@deepseek-ai/cordis'` Events merge declares in one
+ * module body. Names are the literal member keys (`'agent/created'`), read
+ * from method and property members alike so a declaration form the projector
+ * would reject still enters the exhaustiveness scan.
+ * @param body - The cordis module augmentation block.
+ * @param sf - Owning source file (for computed-name text extraction).
+ * @returns Declared event names, in declaration order.
+ */
+export function eventNameList(body: ts.ModuleBlock, sf: ts.SourceFile): string[] {
+  const names: string[] = []
+  for (const stmt of body.statements) {
+    if (!ts.isInterfaceDeclaration(stmt) || stmt.name.text !== 'Events') continue
+    for (const member of stmt.members) {
+      if (!member.name) continue
+      names.push(ts.isStringLiteral(member.name) || ts.isIdentifier(member.name)
+        ? member.name.text
+        : member.name.getText(sf))
+    }
+  }
+  return names
+}

scripts/cordis-yaml.ts

@@ -0,0 +1,54 @@
+/**
+ * Cordis YAML parsing and Loader-entry classification shared by repository checks.
+ * @module scripts/cordis-yaml
+ */
+
+import * as yaml from 'js-yaml'
+
+/** A Loader `!!js` expression preserved as data instead of executed. */
+export interface JsExpr {
+  __jsExpr: string
+}
+
+const jsExprType = new yaml.Type('tag:yaml.org,2002:js', {
+  kind: 'scalar',
+  resolve: data => typeof data === 'string',
+  construct: (data: unknown): JsExpr => {
+    if (typeof data !== 'string') throw new TypeError('!!js requires a scalar string')
+    return { __jsExpr: data }
+  },
+})
+const schema = yaml.JSON_SCHEMA.extend(jsExprType)
+
+/**
+ * Parse a Cordis config while preserving Loader `!!js` expressions as data.
+ * @param source - Cordis YAML source text.
+ * @returns the parsed YAML value.
+ */
+export function loadCordisYaml(source: string): unknown {
+  return yaml.load(source, { schema })
+}
+
+/**
+ * Test whether a value is a preserved Loader `!!js` expression.
+ * @param value - parsed YAML value.
+ * @returns whether the value contains one preserved expression.
+ */
+export function isJsExpr(value: unknown): value is JsExpr {
+  return typeof value === 'object'
+    && value !== null
+    && typeof (value as Record<string, unknown>).__jsExpr === 'string'
+}
+
+/**
+ * Test whether a Loader entry owns nested entries in its `config` array.
+ * @param value - parsed Loader entry.
+ * @returns whether the entry is an explicit or package-named Cordis group.
+ */
+export function isCordisGroupEntry(value: unknown): value is Record<string, unknown> & { config: unknown[] } {
+  return typeof value === 'object'
+    && value !== null
+    && Array.isArray((value as Record<string, unknown>).config)
+    && ((value as Record<string, unknown>).group === true
+      || (value as Record<string, unknown>).name === '@deepseek-ai/cordis-plugin-group')
+}

scripts/coverage-exempt.spec.ts

@@ -0,0 +1,62 @@
+/**
+ * Mechanical guard for the coverage-exempt roster: each entry's positional
+ * filter and exclude glob must select the same non-empty file set out of the
+ * repository's spec inventory, so a renamed suite cannot silently fall out of
+ * the uninstrumented gate while its exclude goes stale.
+ */
+
+import { globSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { describe, expect, it } from 'vitest'
+import { coverageExemptHeavySuites } from './coverage-exempt.ts'
+
+const root = resolve(import.meta.dirname, '..')
+
+/** The spec inventory mirrored from vitest.config.ts testIncludes. */
+const allSpecs = new Set([
+  ...globSync('packages/*/*/tests/**/*.spec.ts', { cwd: root }),
+  ...globSync('packages/*/*/tests/**/*.spec.tsx', { cwd: root }),
+  ...globSync('apps/*/tests/**/*.spec.ts', { cwd: root }),
+  ...globSync('scripts/**/*.spec.ts', { cwd: root }),
+].map(path => path.replaceAll('\\', '/')))
+
+function excludeMatches(exclude: string): string[] {
+  return globSync(exclude, { cwd: root })
+    .map(path => path.replaceAll('\\', '/'))
+    .filter(path => allSpecs.has(path))
+    .sort()
+}
+
+function filterMatches(filter: string): string[] {
+  return [...allSpecs].filter(spec => spec.startsWith(filter)).sort()
+}
+
+describe('coverage-exempt roster', () => {
+  it('selects every Typert suite for the uninstrumented gate', () => {
+    const typertSpecs = filterMatches('packages/typert/')
+    const exemptSpecs = coverageExemptHeavySuites.flatMap(suite => excludeMatches(suite.exclude))
+      .filter(spec => spec.startsWith('packages/typert/')).sort()
+    expect(typertSpecs.length).toBeGreaterThan(0)
+    expect(exemptSpecs).toEqual(typertSpecs)
+  })
+
+  it.each(coverageExemptHeavySuites.map(suite => [suite.filter, suite] as const))(
+    'filter and exclude select the same non-empty spec set for %s',
+    (_filter, suite) => {
+      const fromExclude = excludeMatches(suite.exclude)
+      const fromFilter = filterMatches(suite.filter)
+      expect(fromExclude.length).toBeGreaterThan(0)
+      expect(fromFilter).toEqual(fromExclude)
+    },
+  )
+
+  it('entries never overlap, so no suite is double-run or double-excluded', () => {
+    const seen = new Map<string, string>()
+    for (const suite of coverageExemptHeavySuites) {
+      for (const spec of excludeMatches(suite.exclude)) {
+        expect(seen.get(spec), `${spec} matched by ${seen.get(spec) ?? ''} and ${suite.exclude}`).toBeUndefined()
+        seen.set(spec, suite.exclude)
+      }
+    }
+  })
+})

scripts/coverage-exempt.ts

@@ -0,0 +1,60 @@
+/**
+ * Heavy suites the coverage aggregate runs uninstrumented in a parallel gate.
+ * Membership rule: a suite qualifies only when every coverage-measured
+ * file it executes in-process (`coverage.include` spans package src trees;
+ * Typert src is threshold-excluded in vitest.config.ts) is already
+ * fully covered by other suites, so removing it from the instrumented run
+ * changes no threshold outcome. The aggregate still runs every listed suite
+ * plain beside the instrumented gate, so correctness signal is unchanged —
+ * only the v8 instrumentation tax on compiler- and subprocess-heavy fixtures
+ * is dropped.
+ */
+
+/** One coverage-exempt suite: a Vitest CLI filter and its exclude glob. */
+export interface CoverageExemptSuite {
+  /** Positional file filter selecting the suite in the uninstrumented gate. */
+  readonly filter: string
+  /** Exclude glob removing the suite from the instrumented gate. */
+  readonly exclude: string
+}
+
+/**
+ * Set to `1` by the instrumented coverage gate; vitest.config.ts then drops
+ * the exempt suites from every project. CLI `--exclude` cannot express this:
+ * it does not reach per-project include resolution.
+ */
+export const COVERAGE_EXEMPT_ENV = 'DSH_COVERAGE_EXEMPT_HEAVY'
+
+/** Coverage-exempt heavy suites; keep filter and exclude selecting the same files. */
+export const coverageExemptHeavySuites: readonly CoverageExemptSuite[] = [
+  // Typert src is threshold-excluded; compiler analysis runs uninstrumented.
+  // The generator's tools-catalog registry and
+  // tool-cordis imports are fully covered by those packages' own tests.
+  {
+    filter: 'packages/typert/',
+    exclude: 'packages/typert/*/tests/**',
+  },
+  // The webworker-runtime package is outside the coverage requirement by
+  // decision: vitest.config.ts threshold-excludes its src, so every suite
+  // runs uninstrumented. This tree includes the full-corpus import gate, a
+  // single 900s-budget case that spawns a child sweep over every built
+  // bundle; inside an instrumented partition it exceeds the Windows
+  // partition budget under load.
+  {
+    filter: 'packages/experimental/webworker-runtime/tests/',
+    exclude: 'packages/experimental/webworker-runtime/tests/**',
+  },
+  // Real child-process fixtures over scripts/ sources, which coverage never measures.
+  { filter: 'scripts/install-lefthook.spec.ts', exclude: 'scripts/install-lefthook.spec.ts' },
+  { filter: 'scripts/oxlint-contract.spec.ts', exclude: 'scripts/oxlint-contract.spec.ts' },
+  { filter: 'scripts/change-scope.spec.ts', exclude: 'scripts/change-scope.spec.ts' },
+  { filter: 'scripts/translation-pairing-merge.spec.ts', exclude: 'scripts/translation-pairing-merge.spec.ts' },
+  // Built-artifact proof. Packer/runtime src is threshold-excluded, and the
+  // suite self-skips on unbuilt checkouts; the serial-windows complete
+  // reference still starts this uninstrumented gate after its build gate, so
+  // the assertions execute against complete real artifacts there.
+  {
+    filter: 'packages/experimental/webworker-packer/tests/image-loadable.spec.ts',
+    exclude: 'packages/experimental/webworker-packer/tests/image-loadable.spec.ts',
+  },
+]

scripts/dev-web.ts

@@ -0,0 +1,266 @@
+/**
+ * Watch-build for the web dev loop: rebuilds every artifact the browser reads
+ * from a source edit. Reload signaling is not this script's business — the host
+ * webserver stat-polls the bundles it serves and broadcasts `rebuilt` frames
+ * itself (`dsh web`), so any process that rewrites `lib/client.js` files
+ * triggers reloads; this script is merely the convenient way to keep them all
+ * rebuilt on source change.
+ *
+ * Three stages, because the compile shell links built lib products rather than
+ * sources: `tsc -b tsconfig.client.json` emits `lib/types` (the tsdown lib
+ * entries are that emit, not `src`), tsdown bundles `lib/index.js` and
+ * `lib/client.js`, and `vite build` rewrites `apps/web/dist`, which `dsh web`
+ * serves. A missing stage does not fail — it silently shows the previous
+ * artifact, so an edit appears to do nothing.
+ *
+ * MUST NOT run concurrently with `pnpm run build`: both write the same
+ * `lib/` and `apps/web/dist/` trees.
+ *
+ * Usage: `pnpm exec tsx scripts/dev-web.ts [--poll[=ms]]`. Requires one prior
+ * `pnpm run build`: every stage is incremental over the previous stage's output
+ * and none of them bootstraps a missing tree. `--poll` switches the source
+ * watchers to polling (default 500ms): network mounts (weka) deliver no inotify
+ * events, so native watching sees the initial build only and never a source
+ * change. Polling has to reach tsc too — a native-watching tsc never re-emits
+ * `lib/types`, which strands the other two stages on stale input.
+ *
+ * Each package keeps its own tsdown.config.ts untouched: this script layers
+ * `watch` through API-level inline config (tsdown workspace mode fills inline
+ * keys under each package's file config, and no package config defines it).
+ */
+import { globSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve, sep } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { execa } from 'execa'
+import { build } from 'tsdown'
+import type { TsdownBundle } from 'tsdown'
+import {
+  CLIENT_BUILD_PROFILE_SELECTOR,
+  clientBuildProcessEnvironment,
+  repositoryClientBuildEnvironment,
+} from './client-build-environment.ts'
+
+const repoRoot = fileURLToPath(new URL('..', import.meta.url))
+
+/** Client-face type emit feeding every tsdown lib entry in the watch set. */
+const CLIENT_TYPE_PROGRAM = 'tsconfig.client.json'
+
+/** Compile-shell workspace whose dist `dsh web` serves. */
+const SHELL_PACKAGE = '@deepseek-ai/dsh-web-frontend'
+
+/**
+ * Test infrastructure builds through the client preset but never enters the
+ * shell's module graph, so it is not a dev-loop artifact.
+ */
+const TEST_INFRASTRUCTURE_PREFIX = 'packages/test-support/'
+
+/**
+ * Sample one local public environment for every long-lived watcher stage.
+ * @param root - repository root supplying version and Git metadata.
+ * @param environment - watcher launch environment supplying public extensions.
+ * @returns process environment shared by tsdown and spawned watcher stages.
+ */
+export function devWebBuildEnvironment(
+  root: string,
+  environment: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+  return clientBuildProcessEnvironment(environment, repositoryClientBuildEnvironment(root, environment))
+}
+
+/**
+ * Discover the watch workspace by declaration: every packages/<group>/<name>
+ * whose package.json carries `dsh.client` with platform "web" is a client
+ * plugin bundle emitter. Scanned once at startup — a package added while
+ * watching means restarting this script.
+ * @param root - repository root containing the grouped package directories.
+ * @returns workspace-relative plugin package directories.
+ */
+export function discoverPluginDirs(root = repoRoot): string[] {
+  const dirs: string[] = []
+  for (const manifestPath of globSync('packages/*/*/package.json', { cwd: root }).sort()) {
+    const manifest = JSON.parse(readFileSync(join(root, manifestPath), 'utf8')) as {
+      dsh?: { client?: { platform?: unknown } }
+    }
+    if (manifest.dsh?.client?.platform === 'web') dirs.push(dirname(manifestPath).split(sep).join('/'))
+  }
+  return dirs
+}
+
+/**
+ * Discover the statically linked library packages: the other half of the same
+ * partition {@link discoverPluginDirs} takes. A package that builds through the
+ * client preset without declaring `dsh.client` has no loader-delivered browser
+ * half, so the compile shell links its `lib/index.js` instead — and an edit to
+ * its source reaches the browser only once that bundle is rewritten. Deriving
+ * the set from the build preset rather than a hand list keeps it correct when
+ * dependency sections move around; deriving it from `dependencies` would not,
+ * because client packages declare their build inputs as devDependencies.
+ * @param root - repository root containing the grouped package directories.
+ * @returns workspace-relative library package directories.
+ */
+export function discoverLibraryDirs(root = repoRoot): string[] {
+  const dirs: string[] = []
+  for (const configPath of globSync('packages/*/*/tsdown.config.ts', { cwd: root }).sort()) {
+    const dir = dirname(configPath).split(sep).join('/')
+    if (dir.startsWith(TEST_INFRASTRUCTURE_PREFIX)) continue
+    if (!readFileSync(join(root, configPath), 'utf8').includes('tsdown.client.ts')) continue
+    const manifest = JSON.parse(readFileSync(join(root, dir, 'package.json'), 'utf8')) as {
+      dsh?: { client?: unknown }
+    }
+    if (manifest.dsh?.client === undefined) dirs.push(dir)
+  }
+  return dirs
+}
+
+/**
+ * Start the tsdown watch build used by `pnpm run dev:web`.
+ * @param root - repository or fixture root passed to tsdown.
+ * @param pluginDirs - workspace-relative package directories to watch.
+ * @param pollInterval - optional source-watcher polling interval in milliseconds.
+ * @returns live bundles after every watcher has completed its initial build.
+ */
+export async function watchClientPlugins(
+  root: string,
+  pluginDirs: readonly string[],
+  pollInterval?: number,
+): Promise<TsdownBundle[]> {
+  let resolveInitialBuilds: (() => void) | undefined
+  const initialBuilds = new Promise<void>((resolve) => { resolveInitialBuilds = resolve })
+  const initialized = new WeakSet<object>()
+  const readiness: { expectedBuilds?: number; initializedBuilds: number } = { initializedBuilds: 0 }
+  const bundles = await build({
+    cwd: root,
+    workspace: [...pluginDirs],
+    watch: true,
+    hooks: {
+      'build:done': ({ options }) => {
+        if (initialized.has(options)) return
+        initialized.add(options)
+        readiness.initializedBuilds += 1
+        if (
+          readiness.expectedBuilds !== undefined
+          && readiness.initializedBuilds >= readiness.expectedBuilds
+        ) resolveInitialBuilds?.()
+      },
+    },
+    ...pollInterval !== undefined
+      ? { inputOptions: { watch: { watcher: { usePolling: true, pollInterval } } } }
+      : {},
+  })
+  readiness.expectedBuilds = bundles.length
+  if (readiness.initializedBuilds >= readiness.expectedBuilds) resolveInitialBuilds?.()
+  await initialBuilds
+  return bundles
+}
+
+/**
+ * Live watcher processes to terminate when this script is interrupted. Stages
+ * register themselves as they start, so the set is complete from the first
+ * spawn: an interrupt during a later stage's startup still tears down the
+ * earlier ones instead of orphaning them.
+ */
+const stages: StageHandle[] = []
+
+/**
+ * Spawn one watcher stage, inheriting stdio, registering it for teardown, and
+ * failing loud if it ever exits: a dead stage leaves the artifact chain silently
+ * stale, which reads as "my edit did nothing" — the one failure this script
+ * exists to prevent.
+ * @param stage - command label used in the exit diagnostic.
+ * @param command - executable, resolved from the workspace bin when local.
+ * @param args - command arguments.
+ * @param local - whether to resolve `command` from the workspace's installed bins.
+ */
+function spawnStage(stage: string, command: string, args: readonly string[], local: boolean): void {
+  const child = execa(command, [...args], {
+    cwd: repoRoot,
+    stdio: 'inherit',
+    preferLocal: local,
+    reject: false,
+  })
+  stages.push({ kill: () => { child.kill() } })
+  void child.then((result) => {
+    console.error(`dev-web: ${stage} exited (code ${String(result.exitCode)}); the artifact chain is now stale`)
+    process.exit(1)
+  })
+}
+
+/** The only capability this script needs from a live watcher process. */
+interface StageHandle {
+  readonly kill: () => void
+}
+
+const invokedPath = process.argv[1]
+const isMain = invokedPath !== undefined && import.meta.url === pathToFileURL(resolve(invokedPath)).href
+if (isMain) {
+  const buildEnvironment = devWebBuildEnvironment(repoRoot, process.env)
+  for (const name of Object.keys(process.env)) {
+    if (name === CLIENT_BUILD_PROFILE_SELECTOR || name.startsWith('DSH_CLIENT_')) {
+      Reflect.deleteProperty(process.env, name)
+    }
+  }
+  for (const [name, value] of Object.entries(buildEnvironment)) {
+    if (name.startsWith('DSH_CLIENT_') && value !== undefined) process.env[name] = value
+  }
+
+  const pluginDirs = discoverPluginDirs()
+  const libraryDirs = discoverLibraryDirs()
+  if (pluginDirs.length === 0) {
+    console.error('dev-web: no dsh.client (platform "web") packages found under packages/')
+    process.exit(1)
+  }
+  if (libraryDirs.length === 0) {
+    console.error('dev-web: no client-preset library packages found under packages/ — the compile shell links their lib products, so an empty set means the discovery predicate is stale')
+    process.exit(1)
+  }
+
+  const args = process.argv.slice(2)
+  const pollArg = args.find(a => a === '--poll' || a.startsWith('--poll='))
+  if (args.some(a => a !== pollArg)) {
+    console.error('dev-web: usage: tsx scripts/dev-web.ts [--poll[=ms]]')
+    process.exit(1)
+  }
+  const pollInterval = pollArg === undefined ? undefined : Number(pollArg.split('=')[1] ?? '500')
+  if (pollInterval !== undefined && (!Number.isInteger(pollInterval) || pollInterval <= 0)) {
+    console.error(`dev-web: invalid --poll interval "${pollArg ?? ''}"`)
+    process.exit(1)
+  }
+
+  // Registered before any stage starts: `stages` is read at signal time, so an
+  // interrupt during tsdown's initial builds still kills whatever is running.
+  const stop = (): void => { for (const stage of stages) stage.kill() }
+  process.once('SIGINT', stop)
+  process.once('SIGTERM', stop)
+
+  // tsc has no polling interval flag, so `--poll` selects its fixed-interval
+  // watchers rather than an interval. Dropping that translation leaves tsc
+  // natively watching on a network mount where inotify never fires: it stops
+  // re-emitting lib/types, and the two later stages then rebuild forever from
+  // stale input without printing anything.
+  spawnStage(`tsc -b ${CLIENT_TYPE_PROGRAM} --watch`, 'tsc', [
+    '-b', CLIENT_TYPE_PROGRAM, '--watch', '--preserveWatchOutput',
+    ...pollInterval !== undefined
+      ? ['--watchFile', 'fixedPollingInterval', '--watchDirectory', 'fixedPollingInterval']
+      : [],
+  ], true)
+
+  // tsdown's initial builds are awaited before the dist watcher starts so vite's
+  // first build reads current lib bundles rather than whatever the last full
+  // build left. Its own watch then covers later lib rewrites — those files are
+  // in its module graph.
+  await watchClientPlugins(repoRoot, [...pluginDirs, ...libraryDirs], pollInterval)
+  // Through the shell's own `watch` script rather than vite's API: vite is not a
+  // repository-root dependency, and more importantly the vite root is its
+  // working directory — `resolve.dedupe` resolves react from that root, so
+  // running vite from anywhere but apps/web silently switches which react copy
+  // the bundle gets.
+  spawnStage('vite build --watch', 'pnpm', ['--filter', SHELL_PACKAGE, 'run', 'watch'], false)
+
+  console.log(
+    `dev-web: watching ${String(pluginDirs.length)} dsh.client plugin packages`
+    + ` and ${String(libraryDirs.length)} statically linked library packages`
+    + (pollInterval !== undefined ? ` (polling ${String(pollInterval)}ms)` : '')
+    + `, plus tsc -b ${CLIENT_TYPE_PROGRAM} and the ${SHELL_PACKAGE} dist build:\n  `
+    + [...pluginDirs, ...libraryDirs].join('\n  '),
+  )
+}

scripts/doc-budgets.manifest.json

@@ -0,0 +1,10 @@
+{
+  "AGENTS.md": 1950,
+  "docs/AGENTS.md": 1320,
+  "docs/architecture.md": 2400,
+  "docs/cordis-primer.md": 600,
+  "docs/defensive-patterns.md": 550,
+  "docs/testing.md": 1350,
+  "packages/AGENTS.md": 750,
+  "packages/README.md": 994
+}

scripts/doc-typecheck-paths.ts

@@ -0,0 +1,22 @@
+/** Map one workspace source alias target to its declaration-build target. */
+export function builtDeclarationPath(candidate: string): string {
+  // Two workspace path forms exist: whole-package entries end in /src, subpath
+  // wildcards (browser-safe /types and /client channels) in /src/*.
+  if (candidate.endsWith('/src')) {
+    return `${candidate.slice(0, -'/src'.length)}/lib/types`
+  }
+  if (candidate.endsWith('/src/*')) {
+    return `${candidate.slice(0, -'/src/*'.length)}/lib/types/*`
+  }
+  const sourceFile = /^(.*)\/src\/(.+)\.ts$/.exec(candidate)
+  if (sourceFile?.[1] && sourceFile[2]) {
+    return `${sourceFile[1]}/lib/types/${sourceFile[2]}.d.ts`
+  }
+  // Directory subpath entries (for example, runtime's /client): the
+  // source dir maps to the same dir under lib/types (index resolution applies).
+  const sourceDir = /^(.*)\/src\/(.+)$/.exec(candidate)
+  if (sourceDir?.[1] && sourceDir[2]) {
+    return `${sourceDir[1]}/lib/types/${sourceDir[2]}`
+  }
+  throw new Error(`doc-typecheck: cannot map workspace source path to built declarations: ${candidate}`)
+}

scripts/gen-config-catalog.ts

@@ -0,0 +1,976 @@
+/**
+ * Generate `docs/config-catalog.md` from package entry points, config types,
+ * JSDoc, and static Schemastery schemas. Every package must classify, referenced
+ * types must resolve without collisions, and every enumerable schema path must
+ * exist on the declared config type. External and dynamic types stay unknown;
+ * declared runtime-only fields need not appear in the schema. `--check` verifies
+ * the committed artifact.
+ */
+
+import { globSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path'
+import ts from 'typescript'
+import { LINK_MAP } from './gen-cordis-catalog.ts'
+import { parseJsDoc, pointer, rawJsDoc } from './jsdoc.ts'
+import { githubSlug } from './verify-md-links.ts'
+
+const root = resolve(import.meta.dirname, '..')
+const OUT = 'docs/config-catalog.md'
+
+/** The fenced-block info string for pasted config declarations (skipped by
+ * doc-typecheck, since a lone declaration referencing imports is not
+ * standalone-compilable). */
+const FENCE = 'ts config-catalog'
+
+/** TypeScript/Node global type names a config declaration may reference
+ * without importing; never treated as unresolved. Extend when a new global
+ * legitimately appears — the generator hard-errors on unknown names, so an
+ * omission is loud, not silent. */
+const GLOBAL_TYPES = new Set([
+  'Array', 'ReadonlyArray', 'Record', 'Partial', 'Required', 'Readonly', 'Pick', 'Omit',
+  'Promise', 'Map', 'Set', 'Date', 'Error', 'RegExp', 'Exclude', 'Extract', 'NonNullable',
+  'ReturnType', 'Parameters', 'AbortSignal', 'URL', 'Buffer', 'NodeJS', 'Iterable', 'AsyncIterable',
+])
+
+/** How a package classifies for the catalog. */
+type Kind = 'config' | 'no-config' | 'seam' | 'library'
+
+/** One name a pasted declaration references but the paste does not contain. */
+interface TypeRef {
+  /** The name as it appears in the pasted text (the local import alias). */
+  alias: string
+  /** The name the source module exports it under (pre-alias). */
+  imported: string
+  /** The import module specifier (package name or external module). */
+  specifier: string
+}
+
+/** One verbatim declaration paste. */
+interface Paste {
+  /** Full source text: leading JSDoc (when present) through the closing token. */
+  text: string
+  /** Source pointer `packages/…/file.ts:line` of the declaration. */
+  source: string
+}
+
+/** One package's catalog entry. */
+export interface CatalogEntry {
+  /** npm package name, e.g. `@deepseek-ai/dsh-agent-loop`. */
+  pkg: string
+  /** Repo-relative package dir, e.g. `packages/core/agent-loop`. */
+  dir: string
+  /** Repo-relative entry file, `<dir>/src/index.ts`. */
+  entry: string
+  kind: Kind
+  /** Service keys the plugin `inject`s (empty when none declared). */
+  inject: string[]
+  /** Seam/service class name (kinds `seam` and class-based plugins). */
+  className?: string
+  /** Name of the config type (kind `config`). */
+  configTypeName?: string
+  /** Verbatim declaration pastes, the config type first (kind `config`). */
+  pastes?: Paste[]
+  /** References the pastes leave unresolved locally (kind `config`). */
+  refs?: TypeRef[]
+  /** Top-level keys and nested key paths (`agents[].id`) of the runtime
+   * schema, `null` when no schema exists (kind `config`). */
+  schemaKeys?: string[] | null
+  /** Package names whose schemas an intersect composes (kind `config`). */
+  schemaComposes?: string[]
+}
+
+/** A parsed source file plus its import map (local name → origin). */
+interface FileCtx {
+  abs: string
+  rel: string
+  text: string
+  sf: ts.SourceFile
+  /** Local binding name → `{ imported, specifier }`; default imports record
+   * `imported: 'default'`. */
+  imports: Map<string, { imported: string; specifier: string; typeOnly?: boolean }>
+}
+
+/** Throw one aggregate error for every violation the walk collected. */
+function report(violations: string[]): void {
+  if (violations.length === 0) return
+  throw new Error(
+    `gen-config-catalog: ${violations.length} violation(s):\n`
+    + violations.map(v => `  ${v}`).join('\n'),
+  )
+}
+
+/** Parse a source file and index its import declarations. */
+function loadFile(abs: string, rel: string, cache: Map<string, FileCtx>): FileCtx {
+  const cached = cache.get(abs)
+  if (cached) return cached
+  const text = readFileSync(abs, 'utf8')
+  const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true)
+  const imports: FileCtx['imports'] = new Map()
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue
+    const specifier = stmt.moduleSpecifier.text
+    const clause = stmt.importClause
+    if (!clause) continue
+    if (clause.name) imports.set(clause.name.text, { imported: 'default', specifier })
+    if (clause.namedBindings && ts.isNamedImports(clause.namedBindings)) {
+      for (const el of clause.namedBindings.elements) {
+        imports.set(el.name.text, {
+          imported: (el.propertyName ?? el.name).text,
+          specifier,
+          typeOnly: clause.phaseModifier === ts.SyntaxKind.TypeKeyword || el.isTypeOnly,
+        })
+      }
+    }
+    if (clause.namedBindings && ts.isNamespaceImport(clause.namedBindings)) {
+      imports.set(clause.namedBindings.name.text, { imported: '*', specifier })
+    }
+  }
+  const ctx = { abs, rel, text, sf, imports }
+  cache.set(abs, ctx)
+  return ctx
+}
+
+/** A type declaration a paste can contain. */
+type TypeDecl = ts.InterfaceDeclaration | ts.TypeAliasDeclaration | ts.EnumDeclaration
+
+/** Find a pasteable type declaration by name in a file, or null. */
+function findTypeDecl(ctx: FileCtx, name: string): TypeDecl | null {
+  for (const stmt of ctx.sf.statements) {
+    if ((ts.isInterfaceDeclaration(stmt) || ts.isTypeAliasDeclaration(stmt) || ts.isEnumDeclaration(stmt))
+      && stmt.name.text === name) return stmt
+  }
+  return null
+}
+
+/**
+ * Resolve a type name from a file to its declaration (following package-local
+ * relative imports transitively) or to the import that brings it in. Returns
+ * `null` when the name is neither declared, imported, nor a known global.
+ */
+function resolveTypeName(
+  ctx: FileCtx,
+  name: string,
+  cache: Map<string, FileCtx>,
+  violations: string[],
+): { decl: TypeDecl; ctx: FileCtx } | { ref: TypeRef } | null {
+  const local = findTypeDecl(ctx, name)
+  if (local) return { decl: local, ctx }
+  const imp = ctx.imports.get(name)
+  if (!imp) return null
+  if (imp.specifier.startsWith('.')) {
+    if (!imp.specifier.endsWith('.ts')) {
+      violations.push(`${ctx.rel}: relative import '${imp.specifier}' lacks the explicit .ts extension the repo convention requires.`)
+      return null
+    }
+    if (imp.imported !== name) {
+      violations.push(`${ctx.rel}: '${name}' aliases '${imp.imported}' across a package-local import; the catalog pastes declarations verbatim, so keep package-local config types unaliased.`)
+      return null
+    }
+    const abs = resolve(dirname(ctx.abs), imp.specifier)
+    const rel = ctx.rel.slice(0, ctx.rel.lastIndexOf('/') + 1) + imp.specifier.replace(/^\.\//, '')
+    const target = loadFile(abs, rel, cache)
+    return resolveTypeName(target, imp.imported, cache, violations)
+  }
+  return { ref: { alias: name, imported: imp.imported, specifier: imp.specifier } }
+}
+
+/** Collect every type NAME referenced in type positions under a node. */
+function collectTypeNames(node: ts.Node, out: Set<string>): void {
+  const visit = (n: ts.Node): void => {
+    if (ts.isTypeReferenceNode(n)) {
+      let head: ts.EntityName = n.typeName
+      while (ts.isQualifiedName(head)) head = head.left
+      out.add(head.text)
+    } else if (ts.isExpressionWithTypeArguments(n) && ts.isIdentifier(n.expression)) {
+      out.add(n.expression.text) // heritage clause: `extends X`
+    }
+    ts.forEachChild(n, visit)
+  }
+  visit(node)
+}
+
+/** The verbatim paste text of a declaration: leading JSDoc through the end. */
+function pasteText(ctx: FileCtx, decl: TypeDecl): string {
+  const raw = rawJsDoc(ctx.text, decl)
+  const start = raw ? ctx.text.indexOf(raw, decl.getFullStart()) : decl.getStart(ctx.sf)
+  return ctx.text.slice(start, decl.end)
+}
+
+/** Enforce non-empty JSDoc prose on every property of a pasted declaration,
+ * recursing into nested type literals (e.g. an array-of-objects field). */
+function checkMemberDocs(ctx: FileCtx, decl: TypeDecl, violations: string[]): void {
+  const walkMembers = (members: ts.NodeArray<ts.TypeElement>, path: string): void => {
+    for (const member of members) {
+      if (!ts.isPropertySignature(member)) continue
+      const name = member.name.getText(ctx.sf)
+      const where = `config field '${path}.${name}' (${pointer(ctx.rel, ctx.sf, member)})`
+      if (!parseJsDoc(rawJsDoc(ctx.text, member)).doc) violations.push(`${where} has no JSDoc prose.`)
+      if (member.type) walkNested(member.type, `${path}.${name}`)
+    }
+  }
+  const walkNested = (type: ts.Node, path: string): void => {
+    if (ts.isTypeLiteralNode(type)) walkMembers(type.members, path)
+    else ts.forEachChild(type, (n) => { walkNested(n, path) })
+  }
+  if (ts.isInterfaceDeclaration(decl)) walkMembers(decl.members, decl.name.text)
+  else if (ts.isTypeAliasDeclaration(decl)) walkNested(decl.type, decl.name.text)
+}
+
+/** Cross-file resolution context for the schema-path check. */
+interface World {
+  scanRoot: string
+  cache: Map<string, FileCtx>
+  /** Workspace package name → repo-relative package dir. */
+  pkgDirByName: Map<string, string>
+  /** Exact public export declarations used to verify shared schema imports. */
+  pkgExportsByName: Map<string, unknown>
+  /** Source-plane TypeScript resolution, loaded only for shared schema imports. */
+  compilerOptions?: ts.CompilerOptions
+}
+
+/** Resolve an explicitly exported workspace module to its mapped source file. */
+function loadWorkspaceSource(world: World, from: FileCtx, specifier: string): FileCtx {
+  const pkg = specifier.split('/').slice(0, specifier.startsWith('@') ? 2 : 1).join('/')
+  const dir = world.pkgDirByName.get(pkg)
+  if (dir === undefined) throw new Error(`schema import '${specifier}' is not a workspace package`)
+  const subpath = specifier === pkg ? '.' : `.${specifier.slice(pkg.length)}`
+  const exports = world.pkgExportsByName.get(pkg)
+  if (typeof exports !== 'object' || exports === null || Array.isArray(exports)
+    || !Object.hasOwn(exports, subpath) || (exports as Record<string, unknown>)[subpath] == null) {
+    throw new Error(`workspace package '${pkg}' does not explicitly export '${subpath}'`)
+  }
+  if (world.compilerOptions === undefined) {
+    const parsed = ts.getParsedCommandLineOfConfigFile(resolve(world.scanRoot, 'tsconfig.json'), {}, {
+      ...ts.sys,
+      onUnRecoverableConfigFileDiagnostic(diagnostic) {
+        throw new Error(ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n'))
+      },
+    })
+    if (parsed === undefined || parsed.errors.length > 0) {
+      throw new Error(`cannot resolve schema import '${specifier}' through the workspace source tsconfig`)
+    }
+    world.compilerOptions = parsed.options
+  }
+  const resolved = ts.resolveModuleName(specifier, from.abs, world.compilerOptions, ts.sys).resolvedModule
+  if (resolved === undefined) throw new Error(`schema import '${specifier}' has no workspace source mapping`)
+  const sourcePath = relative(resolve(world.scanRoot, dir, 'src'), resolved.resolvedFileName)
+  if (isAbsolute(sourcePath) || sourcePath === '..' || sourcePath.startsWith(`..${sep}`)
+    || !sourcePath.endsWith('.ts') || sourcePath.endsWith('.d.ts')) {
+    throw new Error(`schema import '${specifier}' must resolve inside ${dir}/src to a TypeScript source file`)
+  }
+  const rel = relative(world.scanRoot, resolved.resolvedFileName).split(sep).join('/')
+  return loadFile(resolved.resolvedFileName, rel, world.cache)
+}
+
+/** Find a directly declared const schema, requiring public exports at imported entries. */
+function schemaConst(ctx: FileCtx, name: string, exported: boolean): ts.Expression | null {
+  for (const statement of ctx.sf.statements) {
+    if (!ts.isVariableStatement(statement) || !(statement.declarationList.flags & ts.NodeFlags.Const)) continue
+    if (exported && !statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue
+    const declaration = statement.declarationList.declarations.find(item => ts.isIdentifier(item.name) && item.name.text === name)
+    if (declaration?.initializer !== undefined) return declaration.initializer
+  }
+  return null
+}
+
+/** Follow only const identities and named value imports; never execute schema factories. */
+function schemaAlias(world: World, ctx: FileCtx, name: string): { ctx: FileCtx; expr: ts.Expression } {
+  const local = schemaConst(ctx, name, false)
+  if (local !== null) return { ctx, expr: local }
+  const imported = ctx.imports.get(name)
+  if (imported === undefined || imported.typeOnly || imported.imported === '*' || imported.imported === 'default') {
+    throw new Error(`schema alias '${name}' must name a const or named value import`)
+  }
+  const target = loadWorkspaceSource(world, ctx, imported.specifier)
+  const expr = schemaConst(target, imported.imported, true)
+  if (expr === null) throw new Error(`schema import '${imported.specifier}' has no exported const '${imported.imported}'`)
+  return { ctx: target, expr }
+}
+
+/** How a schema key path fared against the declared config type: definitely
+ * present, definitely absent, or crossing a type the walk cannot enumerate
+ * (only `missing` is a violation — `unknown` must never mis-report). */
+type PathLookup = 'found' | 'missing' | 'unknown'
+
+/** One step of a schema key path: a named member, or an array-element hop. */
+type PathStep = { member: string } | { array: true }
+
+/** Parse a schema key path (`agents[].id`) into member/array steps. */
+function parsePath(path: string): PathStep[] {
+  const steps: PathStep[] = []
+  for (const seg of path.split('.')) {
+    let name = seg
+    let arrays = 0
+    while (name.endsWith('[]')) {
+      name = name.slice(0, -2)
+      arrays += 1
+    }
+    steps.push({ member: name })
+    for (let i = 0; i < arrays; i += 1) steps.push({ array: true })
+  }
+  return steps
+}
+
+/** Load a package-relative import target as a FileCtx. */
+function loadRelative(world: World, from: FileCtx, specifier: string): FileCtx {
+  const abs = resolve(dirname(from.abs), specifier)
+  const rel = from.rel.slice(0, from.rel.lastIndexOf('/') + 1) + specifier.replace(/^\.\//, '')
+  return loadFile(abs, rel, world.cache)
+}
+
+/** Find a type declaration EXPORTED (directly or via re-export chains) from a
+ * file, following `export … from './x.ts'` and `export * from './x.ts'`. */
+function findExportedTypeDecl(world: World, ctx: FileCtx, name: string, seen = new Set<string>()): { decl: TypeDecl; ctx: FileCtx } | null {
+  const key = `${ctx.abs}#${name}`
+  if (seen.has(key)) return null
+  seen.add(key)
+  const local = findTypeDecl(ctx, name)
+  if (local) return { decl: local, ctx }
+  for (const stmt of ctx.sf.statements) {
+    if (!ts.isExportDeclaration(stmt) || !stmt.moduleSpecifier || !ts.isStringLiteral(stmt.moduleSpecifier)) continue
+    const spec = stmt.moduleSpecifier.text
+    if (!spec.startsWith('.') || !spec.endsWith('.ts')) continue
+    let lookFor: string | null = null
+    if (!stmt.exportClause) {
+      lookFor = name // export * from './x.ts'
+    } else if (ts.isNamedExports(stmt.exportClause)) {
+      const el = stmt.exportClause.elements.find(e => e.name.text === name)
+      if (el) lookFor = (el.propertyName ?? el.name).text
+    }
+    if (lookFor === null) continue
+    const hit = findExportedTypeDecl(world, loadRelative(world, ctx, spec), lookFor, seen)
+    if (hit) return hit
+  }
+  return null
+}
+
+/** Resolve a referenced type NAME to its declaration: declared locally, via a
+ * package-relative import, or via a workspace-package import (entry file +
+ * re-export chains). `'unknown'` = external or otherwise out of reach. */
+function declForTypeName(world: World, ctx: FileCtx, name: string): { decl: TypeDecl; ctx: FileCtx } | 'unknown' {
+  const local = findTypeDecl(ctx, name)
+  if (local) return { decl: local, ctx }
+  const imp = ctx.imports.get(name)
+  if (!imp) return 'unknown'
+  if (imp.specifier.startsWith('.')) {
+    if (!imp.specifier.endsWith('.ts')) return 'unknown'
+    return findExportedTypeDecl(world, loadRelative(world, ctx, imp.specifier), imp.imported) ?? 'unknown'
+  }
+  const dir = world.pkgDirByName.get(imp.specifier)
+  if (dir === undefined) {
+    try {
+      const target = loadWorkspaceSource(world, ctx, imp.specifier)
+      return findExportedTypeDecl(world, target, imp.imported) ?? 'unknown'
+    } catch {
+      // External or unsupported declarations remain unknown for type presence;
+      // a runtime schema alias reports the same resolution failure separately.
+      return 'unknown'
+    }
+  }
+  const entryRel = `${dir}/src/index.ts`
+  let entry: FileCtx
+  try {
+    entry = loadFile(resolve(world.scanRoot, entryRel), entryRel, world.cache)
+  } catch {
+    // A workspace package without a readable entry is reported by its own
+    // classification pass; for a lookup it is out of reach.
+    return 'unknown'
+  }
+  return findExportedTypeDecl(world, entry, imp.imported) ?? 'unknown'
+}
+
+/** Utility wrappers that pass a member lookup through to their type argument. */
+const PASSTHROUGH_WRAPPERS = new Set(['Partial', 'Required', 'Readonly', 'NonNullable'])
+
+/**
+ * Walk a schema key path against a declared type. This is a PRESENCE check,
+ * not a runtime value check: it answers "does the declared config type have a member
+ * here", resolving interfaces (heritage included), type aliases, literals,
+ * intersections, unions, arrays, indexed access, pass-through utility
+ * wrappers, and type references across package-local and workspace imports.
+ * Anything it cannot see through resolves `'unknown'`, never `'missing'`.
+ */
+function lookupPath(world: World, ctx: FileCtx, node: ts.Node, steps: PathStep[], seen: Set<string>): PathLookup {
+  if (steps.length === 0) return 'found'
+  // Guard only named declarations, where recursive types can loop. Structural
+  // children can share a source position with their parent, so guarding them
+  // would mistake ordinary descent for a cycle.
+  if (ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node)) {
+    const key = `${ctx.abs}:${node.pos}:${steps.length}`
+    if (seen.has(key)) return 'unknown' // recursive type — bail rather than loop
+    seen.add(key)
+  }
+  const step = steps[0]
+  if (step === undefined) return 'found'
+  // Combine branch results: any found wins, else any unknown taints, else missing.
+  const combine = (results: PathLookup[]): PathLookup => {
+    if (results.includes('found')) return 'found'
+    if (results.includes('unknown')) return 'unknown'
+    return 'missing'
+  }
+  const intoMembers = (members: ts.NodeArray<ts.TypeElement>): PathLookup | null => {
+    if (!('member' in step)) return null
+    for (const m of members) {
+      if (!ts.isPropertySignature(m) || m.name.getText(ctx.sf) !== step.member) continue
+      if (steps.length === 1) return 'found'
+      return m.type ? lookupPath(world, ctx, m.type, steps.slice(1), seen) : 'unknown'
+    }
+    return null // not among these members; caller consults heritage/parts
+  }
+  if (ts.isInterfaceDeclaration(node)) {
+    if (!('member' in step)) return 'unknown' // an array step cannot land on an interface
+    const direct = intoMembers(node.members)
+    if (direct !== null) return direct
+    const bases: PathLookup[] = []
+    for (const clause of node.heritageClauses ?? []) {
+      for (const base of clause.types) {
+        if (!ts.isIdentifier(base.expression)) {
+          bases.push('unknown')
+          continue
+        }
+        const resolved = declForTypeName(world, ctx, base.expression.text)
+        bases.push(resolved === 'unknown' ? 'unknown' : lookupPath(world, resolved.ctx, resolved.decl, steps, seen))
+      }
+    }
+    return bases.length ? combine(bases) : 'missing'
+  }
+  if (ts.isTypeAliasDeclaration(node)) return lookupPath(world, ctx, node.type, steps, seen)
+  if (ts.isTypeLiteralNode(node)) {
+    if (!('member' in step)) return 'unknown'
+    return intoMembers(node.members) ?? 'missing'
+  }
+  if (ts.isParenthesizedTypeNode(node)) return lookupPath(world, ctx, node.type, steps, seen)
+  if (ts.isIntersectionTypeNode(node)) {
+    return combine(node.types.map(t => lookupPath(world, ctx, t, steps, seen)))
+  }
+  if (ts.isUnionTypeNode(node)) {
+    // Presence on a union is only definite when every branch agrees.
+    const results = node.types.map(t => lookupPath(world, ctx, t, steps, seen))
+    if (results.every(r => r === 'found')) return 'found'
+    if (results.every(r => r === 'missing')) return 'missing'
+    return 'unknown'
+  }
+  if (ts.isArrayTypeNode(node)) {
+    return 'array' in step ? lookupPath(world, ctx, node.elementType, steps.slice(1), seen) : 'unknown'
+  }
+  if (ts.isTypeOperatorNode(node)) return lookupPath(world, ctx, node.type, steps, seen)
+  if (ts.isIndexedAccessTypeNode(node)) {
+    const index = node.indexType
+    if (ts.isLiteralTypeNode(index) && ts.isStringLiteral(index.literal)) {
+      return lookupPath(world, ctx, node.objectType, [{ member: index.literal.text }, ...steps], seen)
+    }
+    return 'unknown'
+  }
+  if (ts.isTypeReferenceNode(node)) {
+    let head: ts.EntityName = node.typeName
+    while (ts.isQualifiedName(head)) head = head.left
+    const name = head.text
+    if (PASSTHROUGH_WRAPPERS.has(name) && node.typeArguments?.[0]) {
+      return lookupPath(world, ctx, node.typeArguments[0], steps, seen)
+    }
+    if ((name === 'Array' || name === 'ReadonlyArray') && node.typeArguments?.[0]) {
+      return 'array' in step ? lookupPath(world, ctx, node.typeArguments[0], steps.slice(1), seen) : 'unknown'
+    }
+    if (!ts.isIdentifier(node.typeName)) return 'unknown' // namespace-qualified: out of reach
+    const resolved = declForTypeName(world, ctx, name)
+    return resolved === 'unknown' ? 'unknown' : lookupPath(world, resolved.ctx, resolved.decl, steps, seen)
+  }
+  return 'unknown'
+}
+
+/** Unwrap `as` / `satisfies` / parenthesized wrappers around an expression. */
+function unwrapExpr(expr: ts.Expression): ts.Expression {
+  let e = expr
+  while (ts.isAsExpression(e) || ts.isSatisfiesExpression(e) || ts.isParenthesizedExpression(e)) e = e.expression
+  return e
+}
+
+/**
+ * Statically walk a schemastery schema expression to its key paths plus the
+ * packages whose schemas an intersect composes. A key path is the top-level
+ * key or a nested path through object/array compositions (`agents[].id`).
+ * Handles object/union calls, chained refinements, named const schema imports
+ * through public workspace source paths, and `z.intersect([X.Config, …])`; errors on
+ * anything else, so a schema the walk cannot see fails the gate instead of
+ * silently thinning it. Nested values that are neither `object` nor `array`
+ * compositions (primitives, unions, dynamic-key dicts) contribute no paths.
+ */
+function walkSchemaExpr(
+  world: World,
+  ctx: FileCtx,
+  expr: ts.Expression,
+  where: string,
+  violations: string[],
+  aliases = new Set<string>(),
+): { keys: string[]; composes: string[] } {
+  const keys: string[] = []
+  const composes: string[] = []
+  // Nested paths under one object property's VALUE expression: recurse through
+  // chained refinements toward the base call, descending into object/array.
+  const collectValuePaths = (value: ts.Expression, base: string): void => {
+    const call = unwrapExpr(value)
+    if (!ts.isCallExpression(call) || !ts.isPropertyAccessExpression(call.expression)) return
+    const method = call.expression.name.text
+    if (method === 'object' && call.arguments[0] && ts.isObjectLiteralExpression(call.arguments[0])) {
+      for (const prop of call.arguments[0].properties) {
+        if (!ts.isPropertyAssignment(prop)) continue
+        const key = ts.isStringLiteral(prop.name) ? prop.name.text : prop.name.getText(ctx.sf)
+        keys.push(`${base}.${key}`)
+        collectValuePaths(prop.initializer, `${base}.${key}`)
+      }
+      return
+    }
+    if (method === 'array' && call.arguments[0]) {
+      collectValuePaths(call.arguments[0], `${base}[]`)
+      return
+    }
+    const inner = unwrapExpr(call.expression.expression)
+    if (ts.isCallExpression(inner)) collectValuePaths(inner, base)
+  }
+  const visit = (e: ts.Expression): void => {
+    const call = unwrapExpr(e)
+    if (ts.isIdentifier(call)) {
+      const identity = `${ctx.abs}#${call.text}`
+      if (aliases.has(identity)) {
+        violations.push(`${where}: cyclic schema alias '${call.text}' in ${ctx.rel}.`)
+        return
+      }
+      try {
+        const target = schemaAlias(world, ctx, call.text)
+        const result = walkSchemaExpr(world, target.ctx, target.expr, where, violations, new Set([...aliases, identity]))
+        keys.push(...result.keys)
+        composes.push(...result.composes)
+      } catch (error) {
+        violations.push(`${where}: ${error instanceof Error ? error.message : String(error)}.`)
+      }
+      return
+    }
+    if (!ts.isCallExpression(call) || !ts.isPropertyAccessExpression(call.expression)) {
+      violations.push(`${where}: schema expression is not a statically walkable schemastery call.`)
+      return
+    }
+    const method = call.expression.name.text
+    if (method === 'object' && call.arguments[0] && ts.isObjectLiteralExpression(call.arguments[0])) {
+      for (const prop of call.arguments[0].properties) {
+        if (ts.isPropertyAssignment(prop) || ts.isShorthandPropertyAssignment(prop)) {
+          const key = ts.isStringLiteral(prop.name) ? prop.name.text : prop.name.getText(ctx.sf)
+          keys.push(key)
+          if (ts.isPropertyAssignment(prop)) collectValuePaths(prop.initializer, key)
+        } else {
+          violations.push(`${where}: schema object property '${prop.getText(ctx.sf)}' is not a plain key.`)
+        }
+      }
+      return
+    }
+    if (method === 'intersect' && call.arguments[0] && ts.isArrayLiteralExpression(call.arguments[0])) {
+      for (const el of call.arguments[0].elements) {
+        const part = unwrapExpr(el)
+        if (ts.isPropertyAccessExpression(part) && part.name.text === 'Config' && ts.isIdentifier(part.expression)) {
+          const imp = ctx.imports.get(part.expression.text)
+          if (imp && !imp.specifier.startsWith('.')) { composes.push(imp.specifier); continue }
+        }
+        if (ts.isCallExpression(part) || ts.isIdentifier(part)) { visit(part); continue }
+        violations.push(`${where}: intersect element '${part.getText(ctx.sf)}' is neither a workspace plugin's Config nor an inline schema call.`)
+      }
+      return
+    }
+    // A union of objects (discriminated union config): collect keys from all
+    // variants. Each variant is visited the same way as an intersect element.
+    if (method === 'union' && call.arguments[0] && ts.isArrayLiteralExpression(call.arguments[0])) {
+      for (const el of call.arguments[0].elements) {
+        const part = unwrapExpr(el)
+        if (ts.isCallExpression(part) || ts.isIdentifier(part)) { visit(part); continue }
+        violations.push(`${where}: union element '${part.getText(ctx.sf)}' is not a schema call or const alias.`)
+      }
+      return
+    }
+    // A chained refinement (`z.object({…}).default(…)` etc.): the keys live on
+    // the call the chain hangs off — keep unwrapping toward it.
+    const base = unwrapExpr(call.expression.expression)
+    if (ts.isCallExpression(base)) { visit(base); return }
+    violations.push(`${where}: schema call '${method}' is not object/intersect and hangs off no walkable base call.`)
+  }
+  visit(expr)
+  return { keys, composes }
+}
+
+/** Find a plugin's schemastery schema expression: an exported `const Config`
+ * in the entry file, else a `static Config` on the plugin class. */
+function findSchemaExpr(ctx: FileCtx, pluginClass: ts.ClassDeclaration | null): ts.Expression | null {
+  for (const stmt of ctx.sf.statements) {
+    if (!ts.isVariableStatement(stmt)) continue
+    if (!stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword)) continue
+    for (const decl of stmt.declarationList.declarations) {
+      if (ts.isIdentifier(decl.name) && decl.name.text === 'Config' && decl.initializer) return decl.initializer
+    }
+  }
+  for (const member of pluginClass?.members ?? []) {
+    if (!ts.isPropertyDeclaration(member) || member.name.getText() !== 'Config') continue
+    if (!member.modifiers?.some(m => m.kind === ts.SyntaxKind.StaticKeyword)) continue
+    if (member.initializer) return member.initializer
+  }
+  return null
+}
+
+/** Read an `inject` service-key list: `export const inject = […]` in the entry
+ * file, else `static inject = […]` on the plugin class. */
+function findInject(ctx: FileCtx, pluginClass: ts.ClassDeclaration | null, violations: string[]): string[] {
+  const fromArray = (expr: ts.Expression, where: string): string[] => {
+    if (!ts.isArrayLiteralExpression(expr)) {
+      violations.push(`${where}: inject is not a plain string-array literal; teach the generator the new declaration form.`)
+      return []
+    }
+    return expr.elements.map(el => ts.isStringLiteral(el) ? el.text : el.getText(ctx.sf))
+  }
+  for (const stmt of ctx.sf.statements) {
+    if (!ts.isVariableStatement(stmt)) continue
+    for (const decl of stmt.declarationList.declarations) {
+      if (ts.isIdentifier(decl.name) && decl.name.text === 'inject' && decl.initializer) {
+        return fromArray(decl.initializer, ctx.rel)
+      }
+    }
+  }
+  for (const member of pluginClass?.members ?? []) {
+    if (ts.isPropertyDeclaration(member) && member.name.getText() === 'inject' && member.initializer) {
+      return fromArray(member.initializer, ctx.rel)
+    }
+  }
+  return []
+}
+
+/** Resolve the entry file's default export to its class/function declaration
+ * (mirroring the Loader's `unwrapExports`), or null when there is none. */
+function defaultExport(ctx: FileCtx): ts.ClassDeclaration | ts.FunctionDeclaration | null {
+  for (const stmt of ctx.sf.statements) {
+    if (ts.isExportAssignment(stmt) && !stmt.isExportEquals && ts.isIdentifier(stmt.expression)) {
+      const name = stmt.expression.text
+      for (const s of ctx.sf.statements) {
+        if ((ts.isClassDeclaration(s) || ts.isFunctionDeclaration(s)) && s.name?.text === name) return s
+      }
+      return null
+    }
+    if ((ts.isClassDeclaration(stmt) || ts.isFunctionDeclaration(stmt))
+      && stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.DefaultKeyword)) return stmt
+  }
+  return null
+}
+
+/** Find the exported `apply` function declaration in the entry file, or null. */
+function applyExport(ctx: FileCtx): ts.FunctionDeclaration | null {
+  for (const stmt of ctx.sf.statements) {
+    if (ts.isFunctionDeclaration(stmt) && stmt.name?.text === 'apply'
+      && stmt.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword)) return stmt
+  }
+  return null
+}
+
+/**
+ * Walk every `packages/<group>/<pkg>` entry and build the catalog entries.
+ * Hard-errors (aggregated) on any violation listed in the module doc.
+ * `scanRoot` defaults to the repo root; tests pass a fixture dir.
+ */
+export function collectConfigCatalog(scanRoot: string = root): CatalogEntry[] {
+  const violations: string[] = []
+  const cache = new Map<string, FileCtx>()
+  const entries: CatalogEntry[] = []
+
+  // Pre-pass: package name → dir, so schema-path lookups can follow
+  // workspace-package imports while individual packages are still being walked.
+  const pkgDirByName = new Map<string, string>()
+  const pkgExportsByName = new Map<string, unknown>()
+  const manifests: { dir: string; pkg: string }[] = []
+  for (const manifestRel of globSync('packages/*/*/package.json', { cwd: scanRoot }).map(path => path.split(sep).join('/')).sort()) {
+    const dir = manifestRel.slice(0, -'/package.json'.length)
+    const manifest = JSON.parse(readFileSync(resolve(scanRoot, manifestRel), 'utf8')) as { name?: string; os?: string[]; cpu?: string[]; exports?: unknown }
+    const pkg = manifest.name
+    if (!pkg) {
+      violations.push(`${manifestRel} has no "name".`)
+      continue
+    }
+    if (manifest.os !== undefined && manifest.cpu !== undefined) {
+      // A per-platform native-binary package (npm os/cpu selection) ships no
+      // JavaScript at all — nothing to classify, no Config to catalog.
+      continue
+    }
+    pkgDirByName.set(pkg, dir)
+    pkgExportsByName.set(pkg, manifest.exports)
+    manifests.push({ dir, pkg })
+  }
+  const world: World = { scanRoot, cache, pkgDirByName, pkgExportsByName }
+
+  for (const { dir, pkg } of manifests) {
+    const entryRel = `${dir}/src/index.ts`
+    let ctx: FileCtx
+    try {
+      ctx = loadFile(resolve(scanRoot, entryRel), entryRel, cache)
+    } catch {
+      // A package without src/index.ts cannot be classified — that is the
+      // violation itself; nothing else in this loop body can run without it.
+      violations.push(`${pkg}: entry ${entryRel} is missing or unreadable.`)
+      continue
+    }
+
+    // Classify, mirroring the Loader's unwrapExports: the default export IS
+    // the plugin when present; else an exported `apply` makes the module
+    // namespace the plugin; else the package is a plain library.
+    const dflt = defaultExport(ctx)
+    const apply = applyExport(ctx)
+    let pluginClass: ts.ClassDeclaration | null = null
+    let configParam: ts.ParameterDeclaration | undefined
+    let kind: Kind
+    let className: string | undefined
+    if (dflt && ts.isClassDeclaration(dflt)) {
+      className = dflt.name?.text
+      if (dflt.modifiers?.some(m => m.kind === ts.SyntaxKind.AbstractKeyword)) {
+        kind = 'seam'
+      } else {
+        pluginClass = dflt
+        const ctor = dflt.members.find(ts.isConstructorDeclaration)
+        configParam = ctor?.parameters[1]
+        kind = configParam ? 'config' : 'no-config'
+      }
+    } else if (dflt) {
+      configParam = dflt.parameters[1]
+      kind = configParam ? 'config' : 'no-config'
+    } else if (apply) {
+      configParam = apply.parameters[1]
+      kind = configParam ? 'config' : 'no-config'
+    } else {
+      kind = 'library'
+    }
+
+    const entry: CatalogEntry = {
+      pkg,
+      dir,
+      entry: entryRel,
+      kind,
+      inject: kind === 'library' || kind === 'seam' ? [] : findInject(ctx, pluginClass, violations),
+      ...className !== undefined ? { className } : {},
+    }
+    entries.push(entry)
+    if (kind !== 'config' || !configParam) continue
+
+    // Resolve the config type and paste its package-local transitive closure.
+    if (!configParam.type || !ts.isTypeReferenceNode(configParam.type) || !ts.isIdentifier(configParam.type.typeName)) {
+      violations.push(`${pkg}: config parameter type (${pointer(entryRel, ctx.sf, configParam)}) is not a plain type-name reference; declare a named config type.`)
+      continue
+    }
+    const typeName = configParam.type.typeName.text
+    entry.configTypeName = typeName
+    const pastes: Paste[] = []
+    const refs = new Map<string, TypeRef>()
+    // A bare name is the fence's whole namespace: two DIFFERENT declarations
+    // (or a declaration in one file and an import in another) sharing a name
+    // cannot both render unambiguously, so every resolution is identity-checked
+    // by source pointer and a collision is a violation, never a silent skip.
+    const pastedDeclByName = new Map<string, string>()
+    const queue: { name: string; from: FileCtx }[] = [{ name: typeName, from: ctx }]
+    for (let item = queue.shift(); item !== undefined; item = queue.shift()) {
+      const { name, from } = item
+      const resolved = resolveTypeName(from, name, cache, violations)
+      if (resolved === null) {
+        violations.push(`${pkg}: config declaration references '${name}' (via ${from.rel}), which is neither declared in the package, imported, nor a known global type.`)
+        continue
+      }
+      if ('ref' in resolved) {
+        if (name === typeName) {
+          violations.push(`${pkg}: config type '${name}' is imported from '${resolved.ref.specifier}'; a plugin's config type must live in its own package.`)
+          continue
+        }
+        if (pastedDeclByName.has(name)) {
+          violations.push(`${pkg}: '${name}' resolves to a package-local declaration (${pastedDeclByName.get(name) ?? ''}) in one file and an import from '${resolved.ref.specifier}' in another; rename one so the fence is unambiguous.`)
+          continue
+        }
+        const existing = refs.get(name)
+        if (existing && (existing.specifier !== resolved.ref.specifier || existing.imported !== resolved.ref.imported)) {
+          violations.push(`${pkg}: '${name}' is imported from both '${existing.specifier}' (${existing.imported}) and '${resolved.ref.specifier}' (${resolved.ref.imported}) across the pasted closure; disambiguate the aliases.`)
+          continue
+        }
+        refs.set(name, resolved.ref)
+        continue
+      }
+      const declKey = pointer(resolved.ctx.rel, resolved.ctx.sf, resolved.decl)
+      const prior = pastedDeclByName.get(name)
+      if (prior === declKey) continue // same declaration reached again — benign
+      if (prior !== undefined) {
+        violations.push(`${pkg}: type name '${name}' resolves to two different declarations (${prior} and ${declKey}) across the pasted closure; rename one — a verbatim fence cannot carry two same-named declarations.`)
+        continue
+      }
+      if (refs.has(name)) {
+        violations.push(`${pkg}: '${name}' resolves to an import from '${refs.get(name)?.specifier ?? ''}' in one file and a package-local declaration (${declKey}) in another; rename one so the fence is unambiguous.`)
+        continue
+      }
+      pastedDeclByName.set(name, declKey)
+      pastes.push({ text: pasteText(resolved.ctx, resolved.decl), source: declKey })
+      checkMemberDocs(resolved.ctx, resolved.decl, violations)
+      const names = new Set<string>()
+      collectTypeNames(resolved.decl, names)
+      for (const n of names) {
+        if (GLOBAL_TYPES.has(n)) continue
+        queue.push({ name: n, from: resolved.ctx })
+      }
+    }
+    entry.pastes = pastes
+    entry.refs = [...refs.values()].sort((a, b) => a.alias.localeCompare(b.alias))
+
+    // Statically walk the runtime schema (when one exists) for the subset check.
+    const schemaExpr = findSchemaExpr(ctx, pluginClass)
+    if (schemaExpr) {
+      const { keys, composes } = walkSchemaExpr(world, ctx, unwrapExpr(schemaExpr), `${pkg} (${entryRel})`, violations)
+      entry.schemaKeys = keys
+      entry.schemaComposes = composes
+    } else {
+      entry.schemaKeys = null
+    }
+  }
+
+  // Fold composed schemas' key paths in, then check each path against the type.
+  // Only a definite miss fails; types the walk cannot enumerate stay unknown.
+  const byName = new Map(entries.map(e => [e.pkg, e]))
+  for (const entry of entries) {
+    if (entry.kind !== 'config' || entry.schemaKeys === null || entry.schemaKeys === undefined) continue
+    const seen = new Set<string>()
+    const foldComposed = (e: CatalogEntry): string[] => {
+      if (seen.has(e.pkg)) return []
+      seen.add(e.pkg)
+      const keys = [...e.schemaKeys ?? []]
+      for (const composed of e.schemaComposes ?? []) {
+        const target = byName.get(composed)
+        if (!target) {
+          violations.push(`${entry.pkg}: schema intersects '${composed}', which is not a workspace package the walk collected.`)
+          continue
+        }
+        keys.push(...foldComposed(target))
+      }
+      return keys
+    }
+    const allKeys = foldComposed(entry)
+    const mainPaste = entry.pastes?.[0]
+    const mainFile = mainPaste?.source.split(':')[0]
+    const mainCtx = mainFile !== undefined ? cache.get(resolve(scanRoot, mainFile)) : undefined
+    const mainDecl = mainCtx && entry.configTypeName !== undefined ? findTypeDecl(mainCtx, entry.configTypeName) : null
+    if (!mainCtx || !mainDecl) {
+      violations.push(`${entry.pkg}: cannot locate config type '${entry.configTypeName ?? ''}' for the schema-path check.`)
+      continue
+    }
+    for (const keyPath of allKeys) {
+      if (lookupPath(world, mainCtx, mainDecl, parsePath(keyPath), new Set()) === 'missing') {
+        violations.push(`${entry.pkg}: schema validates key '${keyPath}' but config type '${entry.configTypeName ?? ''}' declares no such member — the catalog paste would hide a loader-accepted field.`)
+      }
+    }
+  }
+
+  report(violations)
+  return entries.sort((a, b) => a.pkg.localeCompare(b.pkg))
+}
+
+/** Render the `Requires:` service-key line, or '' when the plugin injects nothing. */
+function requiresLine(inject: string[]): string {
+  return inject.length ? `Requires: ${inject.map(k => `\`${k}\``).join(' · ')}` : ''
+}
+
+/** Render one reference as a link: another plugin's config type → its section,
+ * a curated subsystems name → its page, any other workspace type →
+ * its source file, an external type → named with its module, unlinked. */
+function refLink(ref: TypeRef, byName: Map<string, CatalogEntry>): string {
+  const target = byName.get(ref.specifier)
+  if (target?.kind === 'config' && ref.imported === target.configTypeName) {
+    return `[\`${ref.alias}\`](#${githubSlug(target.pkg)})`
+  }
+  const page = LINK_MAP[ref.imported]
+  if (page) return `[\`${ref.alias}\`](subsystems/${page})`
+  if (target) return `[\`${ref.alias}\`](../${target.entry})`
+  return `\`${ref.alias}\` (\`${ref.specifier}\`)`
+}
+
+/** Render one configurable plugin's section. */
+function renderConfigEntry(entry: CatalogEntry, byName: Map<string, CatalogEntry>): string[] {
+  const out = [`<a id="${githubSlug(entry.pkg)}"></a>`, '', `## \`${entry.pkg}\``, '']
+  const requires = requiresLine(entry.inject)
+  if (requires) out.push(requires, '')
+  out.push('```' + FENCE, ...(entry.pastes ?? []).map(p => p.text).join('\n\n').split('\n'), '```', '')
+  if (entry.refs && entry.refs.length > 0) {
+    out.push(`Depends on: ${entry.refs.map(r => refLink(r, byName)).join(' · ')}`, '')
+  }
+  const source = entry.pastes?.[0]?.source ?? entry.entry
+  out.push(`Source: [\`${source}\`](../${source.split(':')[0]})`, '')
+  return out
+}
+
+/** Render one terse list line (the no-config / seam / library sections). */
+function renderTerse(entry: CatalogEntry, detail: string): string {
+  const requires = entry.inject.length ? ` — requires ${entry.inject.map(k => `\`${k}\``).join(' · ')}` : ''
+  return `- \`${entry.pkg}\`${detail}${requires} ([\`${entry.entry}\`](../${entry.entry}))`
+}
+
+/** Render the full catalog (pure, deterministic given sorted entries). */
+export function render(entries: CatalogEntry[]): string {
+  const byName = new Map(entries.map(e => [e.pkg, e]))
+  const lines: string[] = [
+    '<!-- Generated by scripts/gen-config-catalog.ts — do not edit by hand.',
+    '     Run `pnpm run gen-config-catalog` to regenerate. -->',
+    '',
+    '# Plugin Config Catalog',
+    '',
+    'Every `config:` block a `cordis.yml` entry can set: for each loadable harness package, the verbatim config declaration (JSDoc included) its `apply` function or service constructor receives, with every referenced type pasted alongside (package-local types) or linked (everything else). The paste is the plugin\'s full declared config type — a field the runtime schema deliberately excludes is a runtime-only seam (its own JSDoc says so) and is not settable from `cordis.yml`. This is the **deployment**-axis reference — the wiring a plugin author works against is the generated Cordis API region on each [subsystem page](subsystems/core.md), the model-facing tool schemas are the [tool catalog](tool-catalog.md), and [subsystems/](subsystems/core.md) documents the types these declarations reference.',
+    '',
+    'This file is GENERATED from source (`scripts/gen-config-catalog.ts`) and verified fresh by `pnpm run verify-config-catalog` (part of `doc-sync`) — do not edit it by hand. Declaration blocks use a `ts config-catalog` fence (skipped by doc-typecheck, since a lone declaration referencing imports is not standalone-compilable). The generator also cross-checks the runtime schemastery schema against the pasted declaration — every schema-validated key, nested keys included, must be locatable on the declared config type — so the paste cannot hide a loader-accepted field.',
+    '',
+    'A `Requires:` line lists the service keys the plugin `inject`s: its `cordis.yml` tree must also load providers for those services. Scope is the harness tier (`packages/`); the vendored cordis plugins a config tree may also load (`hmr`, the console logger, …) are pinned upstream source ([vendoring policy](../vendor/README.md)) and not catalogued here.',
+    '',
+  ]
+  for (const entry of entries.filter(e => e.kind === 'config')) {
+    lines.push(...renderConfigEntry(entry, byName))
+  }
+  lines.push(
+    '## Loadable plugins with no config',
+    '',
+    'These load from a `cordis.yml` entry with no `config:` block; they declare no configuration API.',
+    '',
+    ...entries.filter(e => e.kind === 'no-config').map(e => renderTerse(e, '')),
+    '',
+    '## Seam packages (not directly loadable)',
+    '',
+    'Abstract service classes — a deployment loads a concrete implementation package instead ([capability seams](../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md)).',
+    '',
+    ...entries.filter(e => e.kind === 'seam').map(e => renderTerse(e, ` — abstract \`${e.className ?? ''}\``)),
+    '',
+    '## Library packages (no plugin entry)',
+    '',
+    'Imported as libraries by other packages; a `cordis.yml` cannot load them.',
+    '',
+    ...entries.filter(e => e.kind === 'library').map(e => renderTerse(e, '')),
+    '',
+  )
+  return lines.join('\n')
+}
+
+/** CLI entry: default writes the catalog, `--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(collectConfigCatalog())
+  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-config-catalog: ${OUT} is up to date.`)
+      process.exit(0)
+    }
+    console.error(`gen-config-catalog: ${OUT} is stale. Run \`pnpm run gen-config-catalog\` and commit ${OUT}.`)
+    process.exit(1)
+  }
+  writeFileSync(resolve(root, OUT), content)
+  console.log(`gen-config-catalog: wrote ${OUT}.`)
+}
+
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
+  main()
+}

scripts/gen-dependency-catalog.spec.ts

@@ -0,0 +1,188 @@
+/** Production dependency selection and offline catalog freshness regressions. */
+
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { runCommandWithTimeout } from './benchmark-npm-resolution.ts'
+import {
+  collectDependencies, computeDependencyCatalog, createNpmResolutionEnvironment,
+  deduplicateDependencies, isDependencyCatalogCurrent,
+} from './gen-dependency-catalog.ts'
+
+const roots: string[] = []
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true, maxRetries: 3 })
+})
+
+function lockfile() {
+  const lock = {
+    lockfileVersion: 3,
+    packages: {
+      '': { dependencies: { '@deepseek-ai/dsh': 'latest' } },
+      'node_modules/@deepseek-ai/dsh': {
+        version: '1.0.0', dependencies: { library: '^2.0.0', alias: 'npm:original@1.0.0' },
+        optionalDependencies: { unavailable: '1.0.0' },
+      },
+      'node_modules/library': { version: '1.0.0' },
+      'node_modules/@deepseek-ai/dsh/node_modules/library': { version: '2.0.0', dependencies: { plugin: '*' } },
+      'node_modules/alias': { name: 'original', version: '1.0.0' },
+      'node_modules/plugin': {
+        version: '1.0.0', dependencies: { library: '^1.0.0' }, peerDependencies: { peer: '*' },
+        optionalDependencies: { 'native-linux': '*', 'native-helper': '*' },
+      },
+      'node_modules/peer': { version: '3.0.0', peer: true },
+      'node_modules/native-linux': { version: '1.0.0', optional: true, os: ['linux'], cpu: ['arm64'], libc: ['glibc'] },
+      'node_modules/native-helper': { version: '1.0.0', optional: true, devOptional: true },
+      'node_modules/test-only': { version: '1.0.0', dev: true },
+    },
+  }
+  for (const [location, entry] of Object.entries(lock.packages)) {
+    if (location !== '') Object.assign(entry, { resolved: `https://registry.npmjs.org/${location}/package.tgz` })
+  }
+  return lock
+}
+
+function fixture(): string {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-dependency-catalog-test-'))
+  roots.push(root)
+  mkdirSync(join(root, 'scripts/dependency-catalog'), { recursive: true })
+  writeFileSync(join(root, 'scripts/dependency-catalog/package-lock.json'), JSON.stringify(lockfile()))
+  writeFileSync(join(root, 'scripts/dependency-catalog/resolution.json'), JSON.stringify({
+    capturedAt: '2026-09-12T00:00:00.000Z', npm: '11.17.0', node: '24.19.0',
+    platform: 'darwin', arch: 'arm64', registry: 'https://registry.npmjs.org/', installStrategy: 'hoisted',
+  }))
+  return root
+}
+
+describe('published npm dependency catalog', () => {
+  it('retains nested versions, aliases, peers, and optional candidates while excluding development-only packages', () => {
+    const { version, rows } = collectDependencies(lockfile())
+    expect(version).toBe('1.0.0')
+    expect(rows).toHaveLength(7)
+    expect(rows.filter(row => row.direct).map(row => [row.name, row.version])).toEqual([
+      ['library', '2.0.0'], ['original', '1.0.0'],
+    ])
+    expect(rows.find(row => row.name === 'peer')).toMatchObject({ peer: true, optional: false })
+    expect(rows.find(row => row.name === 'native-linux')).toMatchObject({
+      optional: true, os: ['linux'], cpu: ['arm64'], libc: ['glibc'],
+    })
+    expect(rows.find(row => row.name === 'native-helper')).toMatchObject({ optional: true })
+    expect(rows.map(row => row.name)).not.toContain('test-only')
+    expect(rows.map(row => row.name)).not.toContain('unavailable')
+  })
+
+  it('does not silently produce an incomplete catalog from invalid or unrelated resolutions', () => {
+    expect(() => collectDependencies({ lockfileVersion: 2 })).toThrow('lockfileVersion 3')
+    expect(() => collectDependencies({ lockfileVersion: 3, packages: {} })).toThrow('consumer must be an object')
+    const input = lockfile()
+    input.packages[''].dependencies['@deepseek-ai/dsh'] = 'next'
+    expect(() => collectDependencies(input)).toThrow('must request only @deepseek-ai/dsh@latest')
+    const missing = lockfile()
+    Reflect.deleteProperty(missing.packages, 'node_modules/alias')
+    expect(() => collectDependencies(missing)).toThrow('missing direct dependency alias')
+    const linked = lockfile()
+    Object.assign(linked.packages['node_modules/library'], { link: true })
+    expect(() => collectDependencies(linked)).toThrow('is a local link')
+  })
+
+  it('sorts packages independently of lockfile object order and keeps duplicate installation locations', () => {
+    const input = lockfile()
+    const reordered = { ...input, packages: Object.fromEntries(Object.entries(input.packages).reverse()) }
+    expect(collectDependencies(reordered)).toEqual(collectDependencies(input))
+    Object.assign(input.packages, {
+      'node_modules/plugin/node_modules/library': {
+        version: '1.0.0', resolved: 'https://registry.npmjs.org/library/-/library-1.0.0.tgz',
+      },
+    })
+    expect(collectDependencies(input).rows.filter(row => row.name === 'library' && row.version === '1.0.0')).toHaveLength(2)
+  })
+
+  it('deduplicates identical versions without losing installation locations or optional flags', () => {
+    const input = lockfile()
+    Object.assign(input.packages, {
+      'node_modules/plugin/node_modules/library': {
+        version: '1.0.0', optional: true, resolved: 'https://registry.npmjs.org/library/-/library-1.0.0.tgz',
+      },
+    })
+    const rows = collectDependencies(input).rows
+    const packages = deduplicateDependencies(rows)
+    const repeated = packages.filter(entry => entry.name === 'library' && entry.version === '1.0.0')
+    expect(repeated).toHaveLength(1)
+    expect(repeated[0]?.installations).toEqual([
+      { location: 'node_modules/library', direct: false, optional: false, peer: false },
+      { location: 'node_modules/plugin/node_modules/library', direct: false, optional: true, peer: false },
+    ])
+    expect(packages.filter(entry => entry.name === 'library').map(entry => entry.version)).toEqual(['1.0.0', '2.0.0'])
+    expect(deduplicateDependencies([...rows].reverse())).toEqual(packages)
+    expect(packages.flatMap(entry => entry.installations)).toHaveLength(rows.length)
+  })
+
+  it('rejects missing, edited, or stale JSON without rewriting it', () => {
+    const root = fixture()
+    const output = computeDependencyCatalog(root)
+    const path = join(root, 'docs/dependency-catalog.json')
+    expect(isDependencyCatalogCurrent(root)).toBe(false)
+    mkdirSync(join(root, 'docs'))
+    writeFileSync(path, output)
+    expect(isDependencyCatalogCurrent(root)).toBe(true)
+    writeFileSync(path, `${output}stale\n`)
+    expect(isDependencyCatalogCurrent(root)).toBe(false)
+    expect(readFileSync(path, 'utf8')).toBe(`${output}stale\n`)
+    writeFileSync(path, output)
+    const updated = lockfile()
+    updated.packages['node_modules/peer'].version = '3.1.0'
+    writeFileSync(join(root, 'scripts/dependency-catalog/package-lock.json'), JSON.stringify(updated))
+    expect(isDependencyCatalogCurrent(root)).toBe(false)
+  })
+
+  it('rejects non-public package sources and incorrect registry metadata', () => {
+    const input = lockfile()
+    Object.assign(input.packages['node_modules/library'], { resolved: 'https://private.invalid/library.tgz' })
+    expect(() => collectDependencies(input)).toThrow('not resolved from the public npm registry')
+    const root = fixture()
+    const metadataPath = join(root, 'scripts/dependency-catalog/resolution.json')
+    writeFileSync(metadataPath, JSON.stringify({ registry: 'https://private.invalid/', installStrategy: 'hoisted' }))
+    expect(() => computeDependencyCatalog(root)).toThrow('expected the public npm registry and hoisted install strategy')
+  })
+
+  it('isolates scoped registries, resolver settings, and caches from user, global, and environment configuration', async () => {
+    const root = fixture()
+    const userConfig = join(root, 'user.npmrc')
+    const globalConfig = join(root, 'global.npmrc')
+    writeFileSync(userConfig, '@deepseek-ai:registry=https://user-override.invalid/\nstrict-peer-deps=true\n')
+    writeFileSync(globalConfig, '@other:registry=https://global-override.invalid/\nprefer-dedupe=true\n')
+    const inherited: NodeJS.ProcessEnv = {
+      ...Object.fromEntries(Object.entries(process.env).filter(([name]) => !name.toLowerCase().startsWith('npm_config_'))),
+      npm_config_userconfig: userConfig,
+      NPM_CONFIG_GLOBALCONFIG: globalConfig,
+      NPM_CONFIG_INSTALL_STRATEGY: 'nested',
+      NPM_CONFIG_OFFLINE: 'true',
+      NPM_CONFIG_CACHE: join(root, 'inherited-cache'),
+      NPM_CONFIG_USER_AGENT: 'inherited-agent',
+    }
+    const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm'
+    const args = ['config', 'list', '--json', '--registry=https://registry.npmjs.org/', '--loglevel=error']
+    const before = await runCommandWithTimeout(npm, args, { cwd: root, env: inherited, timeoutMs: 30_000 })
+    expect(before).toMatchObject({ status: 0, signal: null, timedOut: false })
+    expect(JSON.parse(before.output)).toMatchObject({
+      '@deepseek-ai:registry': 'https://user-override.invalid/', 'install-strategy': 'nested',
+    })
+    const isolated = createNpmResolutionEnvironment(root, inherited)
+    const after = await runCommandWithTimeout(npm, args, { cwd: root, env: isolated, timeoutMs: 30_000 })
+    expect(after).toMatchObject({ status: 0, signal: null, timedOut: false })
+    const settings = JSON.parse(after.output) as Record<string, unknown>
+    expect(settings).toMatchObject({
+      registry: 'https://registry.npmjs.org/', '@deepseek-ai:registry': 'https://registry.npmjs.org/',
+      'install-strategy': 'hoisted', 'strict-peer-deps': false, 'prefer-dedupe': false, offline: false,
+      cache: join(root, '.npm-cache'), userconfig: join(root, '.npmrc-user'), globalconfig: join(root, '.npmrc-global'),
+    })
+    expect(settings['@other:registry']).toBeUndefined()
+    expect(isolated['NPM_CONFIG_USER_AGENT']).toBeUndefined()
+    expect(inherited['npm_config_userconfig']).toBe(userConfig)
+  })
+
+  it('keeps the checked-in JSON synchronized with its recorded npm resolution', () => {
+    expect(isDependencyCatalogCurrent(resolve(import.meta.dirname, '..'))).toBe(true)
+  })
+})

scripts/gen-doc-graphs.spec.ts

@@ -0,0 +1,98 @@
+/**
+ * Tests for the event-relation collector's demand-driven call-site indexing:
+ * the single-file fast path and the global fallback must recover the same
+ * helper-parameter event names, including shapes that defeat the locality
+ * proof (alias escapes and global script files).
+ */
+
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { afterAll, describe, expect, it } from 'vitest'
+import { collectPackageSources, EventRelationCollector } from './gen-doc-graphs.ts'
+import { TypeScriptProject } from './ts-project.ts'
+
+const FIXTURE: Record<string, string> = {
+  'tsconfig.host.json': JSON.stringify({
+    compilerOptions: {
+      target: 'es2022',
+      module: 'esnext',
+      moduleResolution: 'bundler',
+      allowImportingTsExtensions: true,
+      noEmit: true,
+      skipLibCheck: true,
+      types: [],
+    },
+    include: ['vendor/**/*.ts', 'packages/**/*.ts'],
+  }),
+  'vendor/cordis/src/context.ts': 'export class Context { private brand!: void }\n',
+  'vendor/cordis/src/events.ts': [
+    'export class EventsService {',
+    '  dispatch(type: string, args: unknown[]): unknown[] { return [type, args] }',
+    '}',
+    '',
+  ].join('\n'),
+  'packages/core/agent/src/dispatch.ts':
+    'export interface AgentEventDispatch { emit(...args: unknown[]): void }\n',
+  // fireLocal: every same-file reference is a direct callee, so the locality
+  // proof holds and only this file is indexed. fireAliased: the exported
+  // const is a value-position reference, so the proof fails and the global
+  // fallback must find the cross-file call in pkgb.
+  'packages/fix/pkga/src/index.ts': [
+    "import { EventsService } from '../../../../vendor/cordis/src/events.ts'",
+    'declare const events: EventsService',
+    "function fireLocal(args: [string]): void { void events.dispatch('emit', args) }",
+    "fireLocal(['pkga/local-event'])",
+    "function fireAliased(args: [string]): void { void events.dispatch('emit', args) }",
+    'export const aliased = fireAliased',
+    '',
+  ].join('\n'),
+  'packages/fix/pkgb/src/index.ts': [
+    "import { aliased } from '../../pkga/src/index.ts'",
+    "aliased(['pkgb/aliased-event'])",
+    '',
+  ].join('\n'),
+  // Global script files (no import/export): scriptFire is program-visible, so
+  // the cross-file call in caller.ts leaves no same-file reference. Only the
+  // module-ness premise check routes this helper to the global index; without
+  // it the proof would pass and the event would silently drop.
+  'packages/fix/pkgc/src/globals.ts':
+    "declare var gEvents: import('../../../../vendor/cordis/src/events.ts').EventsService\n",
+  'packages/fix/pkgc/src/helper.ts':
+    "function scriptFire(args: [string]): void { void gEvents.dispatch('emit', args) }\n",
+  'packages/fix/pkgc/src/caller.ts': "scriptFire(['pkgc/script-event'])\n",
+}
+
+const root = mkdtempSync(join(tmpdir(), 'gen-doc-graphs-'))
+for (const [rel, content] of Object.entries(FIXTURE)) {
+  mkdirSync(dirname(join(root, rel)), { recursive: true })
+  writeFileSync(join(root, rel), content)
+}
+const project = new TypeScriptProject(root)
+const sources = collectPackageSources(project)
+
+afterAll(() => {
+  rmSync(root, { recursive: true, force: true })
+})
+
+function dispatchersOf(pkgs: readonly string[], event: string): string[] {
+  const subset = sources.filter(source => pkgs.includes(source.pkg))
+  const relations = new EventRelationCollector(project, subset).collect()
+  return [...(relations.get(event)?.dispatchers.keys() ?? [])]
+}
+
+describe('event relation call-site indexing', () => {
+  it('recovers a proven-local helper through the single-file fast path', () => {
+    expect(dispatchersOf(['pkga', 'pkgb'], 'pkga/local-event')).toEqual(['pkga'])
+  })
+
+  it('recovers an alias-escaped helper through the global fallback', () => {
+    expect(dispatchersOf(['pkga', 'pkgb'], 'pkgb/aliased-event')).toEqual(['pkga'])
+  })
+
+  it('rejects the locality proof for global script files', () => {
+    // pkgc alone: the script helper is the first demand, so a wrongly passing
+    // proof would index helper.ts only and lose the caller.ts call site.
+    expect(dispatchersOf(['pkgc'], 'pkgc/script-event')).toEqual(['pkgc'])
+  })
+})

scripts/gen-doc-graphs.ts

@@ -0,0 +1,1586 @@
+/**
+ * Generate the relationship layer above the module, Cordis, and tool catalogs.
+ * Enumerable facts come from source; hybrid graphs add manifests for policy the
+ * source cannot infer, while curated graphs explain flow and ownership.
+ * `--check` verifies the generated set.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, relative, resolve } from 'node:path'
+import ts from 'typescript'
+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,
+  graphNodeId as nodeId,
+  type PackageGraphNode,
+} from './package-graph.ts'
+import { TypeScriptProject } from './ts-project.ts'
+
+const root = resolve(import.meta.dirname, '..')
+type Pkg = PackageGraphNode
+
+interface GraphDoc {
+  rel: string
+  content: string
+}
+
+interface ServiceRole {
+  key: string
+  pkg: string
+  title: string
+  mode: 'core' | 'seam' | 'bundle'
+  implementations?: string[]
+  consumers?: string[]
+  companions?: string[]
+  note: string
+}
+
+interface ExamplePlugin {
+  id: string
+  name: string
+}
+
+interface EventRelation {
+  dispatchers: Map<string, Set<string>>
+  listeners: Set<string>
+}
+
+/** One scanned package source file and its owning package short name. */
+export interface PackageSource {
+  /** Repository-relative path. */
+  rel: string
+  /** Package short name from the `packages/<group>/<pkg>/src` path. */
+  pkg: string
+  /** The bound program source file. */
+  sourceFile: ts.SourceFile
+}
+
+type EventReceiverKind = 'context' | 'agent-dispatch' | 'events-service'
+
+const GROUP_ORDER = [
+  'util',
+  'attachment',
+  'llm',
+  'core',
+  'typert',
+  'goal',
+  'experimental',
+  'process',
+  'bash',
+  'pty',
+  'sandbox',
+  'ssh',
+  'fs',
+  'skill',
+  'compact',
+  'subagent',
+  'tasks',
+  'workflow',
+  'web',
+  'webhook',
+  'spill',
+  'todo',
+  'plan',
+  'cordis',
+  'hooks',
+  'session-persistence',
+  'session-query',
+  'session-title',
+  'telemetry',
+  'storage',
+  'workspace',
+  'support',
+  'acp',
+  'ui',
+]
+
+const SERVICE_ROLES: ServiceRole[] = [
+  {
+    key: 'mcpResources',
+    pkg: 'mcp-resources',
+    title: 'Scoped MCP resource access',
+    mode: 'seam',
+    implementations: ['mcp-client'],
+    consumers: ['mcp-resources'],
+    note: 'Connection-owned providers serve shared resource tools in the calling agent scope.',
+  },
+  {
+    key: 'browserUse',
+    pkg: 'browser-use',
+    title: 'Browser-use provider registration',
+    mode: 'seam',
+    implementations: ['experimental-browser-use-playwright-mcp', 'experimental-browser-use-chrome-devtools-mcp', 'experimental-browser-use-stagehand-native'],
+    consumers: ['experimental-browser-use-playwright-mcp', 'experimental-browser-use-chrome-devtools-mcp', 'experimental-browser-use-stagehand-native'],
+    note: 'One provider-owned name per service instance. Providers own their tools and browser resources per live Session; the shared service has no browser operation API.',
+  },
+  {
+    key: 'computerUse',
+    pkg: 'computer-use',
+    title: 'Computer-use provider registration',
+    mode: 'seam',
+    implementations: ['experimental-computer-use-cua-driver-mcp', 'experimental-computer-use-cua-driver-native'],
+    consumers: ['experimental-computer-use-cua-driver-mcp', 'experimental-computer-use-cua-driver-native'],
+    note: 'One provider-owned name per service instance. Each provider also owns its model tools; the service has no common action API, runtime selection, or Session workflow lock.',
+  },
+  {
+    key: 'attachments',
+    pkg: 'attachment',
+    title: 'Durable binary attachment storage',
+    mode: 'seam',
+    implementations: ['attachment-local'],
+    consumers: ['api-session-controller', 'tool-fs', 'llm-pi-ai', 'llm-deepseek'],
+    note: 'The host commits accepted images before session events; provider adapters resolve authorized durable references into provider-native content.',
+  },
+  {
+    key: 'fileUploads',
+    pkg: 'client-file-upload',
+    title: 'Agent-scoped staged file uploads',
+    mode: 'core',
+    consumers: ['api-session-controller'],
+    note: 'Owns streaming intake, durable storage, and staged receipt lifetime; the Session controller binds receipts to accepted submissions.',
+  },
+  {
+    key: 'llm',
+    pkg: 'llm',
+    title: 'LLM adapter registry',
+    mode: 'seam',
+    implementations: ['llm-deepseek', 'llm-pi-ai', 'llm-replay'],
+    consumers: ['agent-loop', 'compaction-basic'],
+    note: 'Adapters register provider implementations; the loop and compaction call the provider-neutral stream service.',
+  },
+  {
+    key: 'deepseekLlmApiExtensions',
+    pkg: 'deepseek-llm-api-extensions',
+    title: 'Official DeepSeek request extensions',
+    mode: 'seam',
+    implementations: ['session-log-deepseek', 'plugin-package-inventory-deepseek'],
+    consumers: ['llm-deepseek'],
+    note: 'Plugins prepare independent top-level fields; the official adapter merges them and commits their delivery state after HTTP acceptance.',
+  },
+  {
+    key: 'tokenMeter',
+    pkg: 'token-meter',
+    title: 'Replay token measurement',
+    mode: 'core',
+    consumers: ['compaction-basic'],
+    note: 'Owns isolated per-session replay folds; pressure consumers share immutable revisioned measurements.',
+  },
+  {
+    key: 'toolResultPruner',
+    pkg: 'compaction-tool-result-pruner',
+    title: 'Model-free tool-result pruning',
+    mode: 'core',
+    consumers: ['compaction-basic'],
+    note: 'Rewrites oversized current tool results through replayable single-node surface replacements before summary compaction.',
+  },
+  {
+    key: 'sessions',
+    pkg: 'session',
+    title: 'In-memory session store',
+    mode: 'core',
+    consumers: ['agent-loop', 'agent', 'session-persistence', 'session-query', 'session-query-sqlite', 'subagent-in-process-driver', 'invariants', 'message-feedback'],
+    note: 'Owns append-only Session instances and emits the durable session event feed.',
+  },
+  {
+    key: 'sessionController',
+    pkg: 'api-session-controller',
+    title: 'Host Session Remote controller',
+    mode: 'core',
+    note: 'Owns Session commands, cold reads, durable-event following, live control state, model catalogs, workspace opening, and Agent activation policy.',
+  },
+  {
+    key: 'sessionFileReferences',
+    pkg: 'api-session-controller',
+    title: 'Session-addressed file-reference Remote adapter',
+    mode: 'core',
+    note: 'Delegates file-reference discovery through the Session Controller\'s established Agent lookup policy.',
+  },
+  {
+    key: 'sessionSkillCatalog',
+    pkg: 'api-session-controller',
+    title: 'Session-addressed skill Remote adapter',
+    mode: 'core',
+    note: 'Lists the Session composition\'s user-invocable skills without activating a cold Agent.',
+  },
+  {
+    key: 'credentialsController',
+    pkg: 'api-settings-controller',
+    title: 'Host credential-surface Remote controller',
+    mode: 'core',
+    note: 'Projects the credential-reference seam onto the generated Remote namespace: batch fan-out, view projection, and refusal mapping live here, not on the seam Definition.',
+  },
+  {
+    key: 'settingsController',
+    pkg: 'api-settings-controller',
+    title: 'Host settings-surface Remote controller',
+    mode: 'core',
+    note: 'Projects the user-settings seam onto the generated Remote namespace: the read is always redacted and every refusal is classified here, not on the seam Definition.',
+  },
+  {
+    key: 'workspaceFiles',
+    pkg: 'api-workspace-files',
+    title: 'Host workspace file Remote service',
+    mode: 'core',
+    note: 'Serves stat, paged text, byte windows, directory listings, and the change feed for files inside a Session\'s workspace root, confined by lstat, containment, and a stat re-check.',
+  },
+  {
+    key: 'terminalController',
+    pkg: 'api-terminal-controller',
+    title: 'Session interactive terminal Remote controller',
+    mode: 'core',
+    note: 'Owns user terminal processes, default shell resolution and bounded screen recovery through the subprocess provider and typed Remote transport.',
+  },
+  {
+    key: 'workspaceController',
+    pkg: 'api-workspace-controller',
+    title: 'Host Workspace Remote controller',
+    mode: 'core',
+    note: 'Owns Workspace commands and reconnect-safe Workspace state delivery through the generated Remote namespace.',
+  },
+  {
+    key: 'directoryPickerController',
+    pkg: 'api-workspace-controller',
+    title: 'Host directory-picking Remote controller',
+    mode: 'core',
+    note: 'Carries the picking seam onto the wire: capability gating, cancellation, and the seam-coded failures a browser directory flow discriminates on.',
+  },
+  {
+    key: 'invariants',
+    pkg: 'invariants',
+    title: 'Package-owned invariant registry',
+    mode: 'core',
+    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', 'api-gateway'],
+    note: 'Plugins register live zod contributions directly or through dsh-typert-loader; the API gateway consumes invocation descriptors and providers, while other runtime consumers query schemas and reflection metadata at their own edges.',
+  },
+  {
+    key: 'typertGateway',
+    pkg: 'api-gateway',
+    title: 'Typert Host invocation gateway',
+    mode: 'core',
+    note: 'Associates generated Remote descriptors with live Cordis services, resolves registered identities, and exposes unary calls through the shared Connection RPC carrier.',
+  },
+  {
+    key: 'sessionPersistence',
+    pkg: 'session-persistence',
+    title: 'Durable session persistence seam',
+    mode: 'seam',
+    implementations: ['session-persistence-jsonl'],
+    consumers: ['agent-loop', 'tool-bash', 'hooks-claude-code', 'hooks-codex', 'session-query', 'session-query-sqlite', 'message-feedback'],
+    note: 'The JSONL backend persists the SessionEvent vocabulary as one artifact per Session.',
+  },
+  {
+    key: 'settings',
+    pkg: 'settings',
+    title: 'User-settings seam',
+    mode: 'seam',
+    implementations: ['settings-file'],
+    consumers: ['api-settings-controller', 'llm-deepseek', 'llm-pi-ai'],
+    note: 'Plugins register namespace schemas and resolve layered values; providers store the raw document. The LLM adapters register their entry config as the composition base under the user section; the settings controller serves redacted layered descriptors and writes the user layer.',
+  },
+  {
+    key: 'subagentModelSelection',
+    pkg: 'tool-subagent',
+    title: 'Subagent model-selection preference',
+    mode: 'core',
+    consumers: ['tool-subagent'],
+    note: 'Owns the default-off settings namespace that Agent-scoped delegation tools sample when composing a new top-level Session.',
+  },
+  {
+    key: 'credentials',
+    pkg: 'credentials',
+    title: 'Credential seam',
+    mode: 'seam',
+    implementations: ['credentials-local'],
+    consumers: ['api-settings-controller', 'llm-deepseek', 'llm-pi-ai'],
+    note: 'Configuration carries references to secrets; providers own the values. Consumers resolve per operation, so a rotated credential reaches the very next request; the settings controller exposes value-free views and write-only storage.',
+  },
+  {
+    key: 'authorization',
+    pkg: 'authorization',
+    title: 'Authorization flow registry',
+    mode: 'seam',
+    implementations: [],
+    consumers: ['llm-pi-ai'],
+    note: 'Flows are registered by the plugin that knows how to obtain one credential and keyed by the record they write; the seam owns the conversation and the one-attempt-per-key lifecycle, never the protocol.',
+  },
+  {
+    key: 'sessionTelemetry',
+    pkg: 'session-telemetry',
+    title: 'Session telemetry seam',
+    mode: 'seam',
+    implementations: ['session-telemetry-otel'],
+    consumers: [],
+    note: 'The seam captures, redacts, and hands session records to one backend; nothing else consumes the service — its output leaves the process.',
+  },
+  {
+    key: 'storage',
+    pkg: 'storage',
+    title: 'Non-session storage hub',
+    mode: 'seam',
+    implementations: ['storage-json', 'storage-sqlite'],
+    consumers: ['storage-domain'],
+    note: 'Backends register side by side under names; data forms (domain first) mount on the hub and translate typed operations into opaque KV-unit primitives.',
+  },
+  {
+    key: 'storageDomain',
+    pkg: 'storage-domain',
+    title: 'Domain data facility',
+    mode: 'core',
+    consumers: ['workspace'],
+    note: 'Waits for every configured backend, then publishes the domain form as one lifecycle-bound service for typed durable state.',
+  },
+  {
+    key: 'messageFeedback',
+    pkg: 'message-feedback',
+    title: 'Lifecycle-bound message feedback',
+    mode: 'core',
+    note: 'Owns per-assistant-message feedback in the canonical Session log, target validation, per-item compare-and-set, and the Host unary Remote contract. Feedback stays outside model history; log export follows the consumer policy.',
+  },
+  {
+    key: 'sessionFeedback',
+    pkg: 'command-feedback',
+    title: 'Session-level feedback recorder',
+    mode: 'core',
+    note: 'Records one Session-level remark with its category as a log-only feedback/record event on a live Session through the Host unary Remote contract; the /feedback command shares the same producer.',
+  },
+  {
+    key: 'workspaceRegistry',
+    pkg: 'workspace',
+    title: 'Workspace entity registry',
+    mode: 'core',
+    consumers: ['api-workspace-controller', 'api-session-controller'],
+    note: 'Owns WorkspaceId-branded records over the domain facility; stable sessionIds accounts drive Host RPC and GUI projections.',
+  },
+  {
+    key: 'sessionQuery',
+    pkg: 'session-query',
+    title: 'Session reads, traces, filters, and search',
+    mode: 'seam',
+    implementations: ['session-query-sqlite'],
+    consumers: ['session-reference', 'tool-session-query'],
+    note: 'The interface supplies exact reads, filters, and traces; its concrete backend adds full-text reconciliation, ranking, snippets, and cursor generations, while the model consumer owns workspace authority and cursor-free rendering.',
+  },
+  {
+    key: 'fileReferences',
+    pkg: 'file-reference',
+    title: 'File reference discovery',
+    mode: 'seam',
+    implementations: ['file-reference-local'],
+    consumers: ['api-session-controller'],
+    note: 'The interface returns path-only completion candidates within an Agent cwd; providers own namespace access and ranking without reading file contents.',
+  },
+  {
+    key: 'sessionReferenceResolver',
+    pkg: 'session-reference',
+    title: 'Cross-session snapshot preparation',
+    mode: 'core',
+    note: 'Projects bounded current-surface conversation snapshots into durable untrusted message context; host adapters own mention syntax.',
+  },
+  {
+    key: 'sessionTitle',
+    pkg: 'session-title',
+    title: 'Log-backed session titles',
+    mode: 'seam',
+    implementations: ['session-title-first-prompt-llm', 'session-title-all-prompts-llm'],
+    note: 'Owns the deterministic fallback, latest-title fold, and sole optional asynchronous provider registration.',
+  },
+  {
+    key: 'systemPrompt',
+    pkg: 'system-prompt',
+    title: 'System prompt assembly registry',
+    mode: 'core',
+    consumers: ['agent-loop', 'tools', 'tool-fs', 'tool-terminal', 'tool-web'],
+    note: 'Collects prompt sections and model-facing tool schemas for each step.',
+  },
+  {
+    key: 'tools',
+    pkg: 'tools',
+    title: 'Tool registry and guarded execution pipeline',
+    mode: 'core',
+    consumers: ['agent-loop', 'tool-ask-user', 'tool-bash', 'tool-cordis', 'tool-fs', 'tool-terminal', 'tool-skill', 'tool-subagent', 'tool-todo', 'tool-web'],
+    note: 'Registers capabilities, owns PTC mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation.',
+  },
+  {
+    key: 'userQuestions',
+    pkg: 'user-questions',
+    title: 'Human question/answer seam',
+    mode: 'seam',
+    consumers: ['tool-ask-user'],
+    note: 'UI front ends provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise.',
+  },
+  {
+    key: 'planMode',
+    pkg: 'plan-mode',
+    title: 'Plan collaboration state',
+    mode: 'core',
+    note: 'Folds logged plan/mode state, flushes user selections at turn boundaries, renders deployment-owned guidance, registers /plan, and keeps the plan-exit schema stable across transitions.',
+  },
+  {
+    key: 'agentPresets',
+    pkg: 'agent-presets',
+    title: 'Per-session agent composition',
+    mode: 'core',
+    note: 'Discovers preset directories over trusted and user-authored roots and mounts one preset cordis.yml under an agent scope during creation, rejecting a row that never activates or that publishes into the root service realm.',
+  },
+  {
+    key: 'commands',
+    pkg: 'commands',
+    title: 'Human command registry',
+    mode: 'core',
+    note: 'Plugins register direct human commands without sending invocations to the model.',
+  },
+  {
+    key: 'sessionProjections',
+    pkg: 'session-projection',
+    title: 'Session projection units',
+    mode: 'core',
+    consumers: ['api-session-controller', 'tool-todo', 'session-title'],
+    note: 'Domains register state-driven fold units; the eager drive keeps per-session watermark states and the Session controller serves baselines and pushes changed values.',
+  },
+  {
+    key: 'sessionProjectionCache',
+    pkg: 'session-projection-cache',
+    title: 'Persisted projection cache',
+    mode: 'core',
+    consumers: ['api-session-controller', 'session-query', 'session-reference', 'subagent'],
+    note: 'Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs.',
+  },
+  {
+    key: 'skills',
+    pkg: 'skill',
+    title: 'Skill provider registry',
+    mode: 'seam',
+    implementations: ['skill-badge', 'skill-filesystem'],
+    consumers: ['tool-skill'],
+    note: 'Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies.',
+  },
+  {
+    key: 'agents',
+    pkg: 'agent',
+    title: 'Agent service',
+    mode: 'core',
+    consumers: ['agent-loop', 'acp', 'subagent-in-process-driver'],
+    note: 'Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation.',
+  },
+  {
+    key: 'agentDefaultModel',
+    pkg: 'agent-default-model',
+    title: 'Default Agent model selection',
+    mode: 'core',
+    consumers: ['api-session-controller', 'headless'],
+    note: 'Layers the default ModelSelection through settings so direct and Host-backed Agent entry points share one state owner.',
+  },
+  {
+    key: 'agentLoop',
+    pkg: 'agent-loop',
+    title: 'Concrete loop driver',
+    mode: 'bundle',
+    consumers: ['base', 'sdk-minimal'],
+    note: 'The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package.',
+  },
+  {
+    key: 'goals',
+    pkg: 'goal',
+    title: 'Same-session goal domain',
+    mode: 'core',
+    note: 'Folds revisioned objective state from the session log and keeps live continuation activation process-local.',
+  },
+  {
+    key: 'ssh',
+    pkg: 'ssh',
+    title: 'POSIX SSH connection owner',
+    mode: 'core',
+    consumers: ['fs-ssh', 'subprocess-ssh', 'sandbox-ssh'],
+    note: 'Owns one authenticated OpenSSH connection, installed helper identity, independent program streams and disconnect cleanup for the paired remote providers.',
+  },
+  {
+    key: 'subprocess',
+    pkg: 'subprocess',
+    title: 'Subprocess seam',
+    mode: 'seam',
+    implementations: ['subprocess-local', 'subprocess-ssh'],
+    consumers: ['bash-local', 'bash-sandbox', 'terminal-bash', 'lsp-stdio', 'subagent-acp', 'subagent-codex', 'subagent-claude-code'],
+    note: 'The bash executors, the PTY shell backend, the LSP host, and the out-of-process ACP, Codex, and Claude Code subagent backends spawn through ctx.subprocess; the service owns process coordinates, tree/session lifetime, stdio dispositions, terminal mechanics, and kill escalation.',
+  },
+  {
+    key: 'shell',
+    pkg: 'shell',
+    title: 'Bash executor seam',
+    mode: 'seam',
+    implementations: ['bash-local', 'bash-sandbox', 'pwsh-local'],
+    consumers: ['tool-bash', 'tool-pwsh', 'hooks-claude-code', 'hooks-codex'],
+    note: 'The model-facing shell tools and hook bridges consume this seam; sandboxed, remote, or PowerShell executors replace bash-local without touching them.',
+  },
+  {
+    key: 'shellEnv',
+    pkg: 'shell-env',
+    title: 'Managed bash environment registry',
+    mode: 'core',
+    consumers: ['tool-bash', 'tool-pwsh'],
+    note: 'Plugins declare effect-scoped DSH_* facts; each shell tool collects one trusted snapshot per execution and its executor rebuilds the namespace.',
+  },
+  {
+    key: 'terminals',
+    pkg: 'terminal',
+    title: 'Persistent PTY session registry',
+    mode: 'seam',
+    implementations: ['terminal-bash'],
+    consumers: ['tool-terminal'],
+    note: 'The registry owns exact-Agent session identity and cleanup; backends own terminal mechanics, while tool-terminal exposes the owner-scoped model tools.',
+  },
+  {
+    key: 'sandbox',
+    pkg: 'sandbox',
+    title: 'Process-sandbox seam',
+    mode: 'seam',
+    implementations: ['sandbox-local', 'sandbox-ssh'],
+    consumers: ['bash-sandbox', 'terminal-bash'],
+    note: 'Consumers hand over the exact argv they are about to spawn; same-world backends wrap it under a per-call policy and report enforcement.',
+  },
+  {
+    key: 'sandboxPolicy',
+    pkg: 'sandbox-policy',
+    title: 'Sandbox policy home',
+    mode: 'core',
+    implementations: [],
+    consumers: ['bash-sandbox', 'fs-sandbox', 'terminal-bash'],
+    note: 'The one home for the deployment default mode + workspace root; only the sandboxed executor and provider read the service (the tool layers use the pure `sandbox/mode` fold it also exports). Both enforcing families read it so bash and fs cannot confine to different roots.',
+  },
+  {
+    key: 'approval',
+    pkg: 'user-approval',
+    title: 'Approval seam',
+    mode: 'seam',
+    implementations: [],
+    consumers: ['tools', 'tool-bash', 'acp'],
+    note: 'One-shot permission decisions dispatched over the `approval/request` waterfall; answerers are listeners (the ACP bridge for its own agents), absence fails closed to `unavailable`.',
+  },
+  {
+    key: 'permissionPresets',
+    pkg: 'permission-presets',
+    title: 'Permission presets',
+    mode: 'core',
+    implementations: [],
+    note: 'User-facing preset table (`workspace-write`/`danger-full-access`) bundling the sandbox-mode and approval-policy knobs; a switch writes one `permission/preset` event through to both knob events.',
+  },
+  {
+    key: 'ptcRuntime',
+    pkg: 'ptc-runtime',
+    title: 'PTC execution seam',
+    mode: 'seam',
+    implementations: ['ptc-runtime-node', 'experimental-ptc-runtime-python'],
+    consumers: ['tools', 'workflow-ptc'],
+    note: 'Runs programs against host-provided async bindings; tools owns PTC presentation and workflow-ptc owns workflow orchestration.',
+  },
+  {
+    key: 'fs',
+    pkg: 'fs',
+    title: 'Filesystem provider seam',
+    mode: 'seam',
+    implementations: ['fs-local', 'fs-sandbox', 'fs-ssh'],
+    consumers: ['tool-fs'],
+    companions: ['fs-observation-policy'],
+    note: 'tool-fs executes read/write/edit through ctx.fs; fs-sandbox fences mutations by the shared sandbox mode; fs-observation-policy contributes observed-state checks through the fs/* event gate.',
+  },
+  {
+    key: 'compaction',
+    pkg: 'compaction',
+    title: 'Compaction seam',
+    mode: 'seam',
+    implementations: ['compaction-basic'],
+    consumers: ['compaction-basic'],
+    note: 'The basic backend consumes post-step pressure and request-error recovery events; there is no model-facing compact tool.',
+  },
+  {
+    key: 'subagents',
+    pkg: 'subagent',
+    title: 'Subagent provider and continuation service',
+    mode: 'seam',
+    implementations: ['subagent-spawn-in-process', 'subagent-fork-in-process', 'subagent-acp', 'subagent-codex', 'subagent-claude-code', 'subagent-dsh-sdk'],
+    consumers: ['tool-subagent', 'tool-subagent-control', 'tool-ralph'],
+    note: 'Providers implement transports; the service also owns optional Activation-based continuation orchestration, tool-subagent selects one-shot or continuable delegation, tool-subagent-control delivers follow-ups, and tool-ralph requires one fresh structured-output route.',
+  },
+  {
+    key: 'agentTeams',
+    pkg: 'experimental-agent-team',
+    title: 'Agent Teams coordination domain',
+    mode: 'core',
+    consumers: ['experimental-tool-agent-team', 'experimental-client-ui-agent-team'],
+    note: 'Owns the implicit-root roster, durable peer mailbox, shared task DAG, continuable-child lifecycle, and generated Team Remote methods; tool-agent-team contributes model controls and client-ui-agent-team mounts the browser contribution.',
+  },
+  {
+    key: 'inspector',
+    pkg: 'inspector',
+    title: 'Cross-realm runtime inspection',
+    mode: 'core',
+    note: 'Owns the Worker-hosted CDP target and the transport-independent Host and Client observation and Cordis-tree query API.',
+  },
+  {
+    key: 'jobs',
+    pkg: 'jobs',
+    title: 'Background job registry',
+    mode: 'seam',
+    implementations: ['jobs-local'],
+    consumers: ['tool-bash', 'tool-terminal', 'tool-subagent', 'tool-jobs'],
+    note: 'Producers (background bash, PTY sends, and subagent delegations) register running work; tool-jobs is the model-facing controller that reads, lists, and kills it; jobs-local is the process-local registry.',
+  },
+  {
+    key: 'web',
+    pkg: 'web',
+    title: 'Web access provider registry',
+    mode: 'seam',
+    implementations: ['web-search-exa', 'web-search-perplexity', 'web-search-deepseek', 'web-fetch-http'],
+    consumers: ['tool-web'],
+    note: 'Search and fetch providers register into one ctx.web seam; tool-web owns the stable model-facing names.',
+  },
+  {
+    key: 'spillStore',
+    pkg: 'spill',
+    title: 'Spill storage seam',
+    mode: 'seam',
+    implementations: ['spill-local'],
+    consumers: ['spill-policy'],
+    note: 'The backend saves oversized tool text and returns a model-facing locator plus retrieval hint; spill-policy is the tools/post-execute consumer that decides when to spill.',
+  },
+  {
+    key: 'directoryPicker',
+    pkg: 'host-directory-picker',
+    title: 'Workspace-directory picking seam',
+    mode: 'seam',
+    implementations: ['host-directory-picker-native', 'host-directory-picker-browse'],
+    consumers: ['api-workspace-controller'],
+    note: 'Discriminated interaction capability: the native backend opens one OS chooser on the host display, the browse backend serves listing/creation primitives for the in-app browser; dual-face backends fill ui-workspace directory-flow slots from their browser halves (no wire advertisement).',
+  },
+  {
+    key: 'webServer',
+    pkg: 'host-webserver',
+    title: 'HTTP route registration',
+    mode: 'core',
+    consumers: ['client-connection', 'client-modules', 'client-hmr'],
+    note: 'Plain node:http carrier: named-route registry, index transform taps, and the static dist fallback; web-transport plugins register their own routes.',
+  },
+  {
+    key: 'clientModules',
+    pkg: 'client-modules',
+    title: 'Client plugin graph host',
+    mode: 'core',
+    consumers: ['client-hmr'],
+    note: 'Composes the __DSH_BOOT__ entry graph from an incremental dsh.client scan, serves plugin bundles, and notifies rebuilt/graph-changed subscribers.',
+  },
+  {
+    key: 'workflowEngine',
+    pkg: 'workflow',
+    title: 'Workflow script engine',
+    mode: 'seam',
+    implementations: ['workflow-ptc'],
+    consumers: ['tool-workflow', 'tool-ralph'],
+    note: 'One engine per context, as in bash, with no named-provider registry; the general workflow and fixed Ralph consumers start runs whose agent() calls fan out through ctx.subagents.',
+  },
+  {
+    key: 'webhookRuntime',
+    pkg: 'webhook',
+    title: 'Webhook rule runtime',
+    mode: 'core',
+    consumers: ['webhook-github'],
+    note: 'Provider adapters dispatch authenticated deliveries; trusted plugins register independent process-local rules, and the runtime turns non-null results into ordinary Workspace-backed Sessions without delivery or completion state.',
+  },
+  {
+    key: 'lsp',
+    pkg: 'lsp',
+    title: 'Language-server navigation seam',
+    mode: 'seam',
+    implementations: ['lsp-stdio'],
+    consumers: ['tool-lsp'],
+    note: 'Provider registration and selection plus normalized query execution over exactly four operations; the seam offers no protocol escape hatch, so a backend translates into the normalized request and result.',
+  },
+  {
+    key: 'dynamicCordisRunner',
+    pkg: 'cordis-host-runner',
+    title: 'Dynamic Cordis package host runner',
+    mode: 'core',
+    consumers: ['tool-cordis'],
+    note: 'Owns the in-memory definition registry, the vm sandbox for host halves, and the request-run round trip; browser pages reach the same service over the wire through its remote namespace.',
+  },
+  {
+    key: 'cordisInspect',
+    pkg: 'cordis-host-runner',
+    title: 'Dynamic Cordis inspect registry',
+    mode: 'core',
+    consumers: ['tool-cordis'],
+    note: 'Registers host inspect providers, mirrors the client provider manifest, and routes client queries through the dynamic Cordis transport.',
+  },
+]
+
+function generatedHeader(title: string): string[] {
+  return [
+    '<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.',
+    '     Run `pnpm run gen-doc-graphs` to regenerate. -->',
+    '',
+    `# ${title}`,
+    '',
+  ]
+}
+
+function maintenanceFooter(source: string): string[] {
+  return [`Maintenance mode: ${source}.`, '']
+}
+
+function graphIndexLink(rel: string): string {
+  return relative('docs', rel).replaceAll('\\', '/')
+}
+
+function linkFromDoc(docRel: string, targetRel: string): string {
+  return relative(dirname(docRel), targetRel).replaceAll('\\', '/')
+}
+
+function mermaidCode(value: string): string {
+  return `<code>${value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')}</code>`
+}
+
+function repoLink(path: string, label: string, up = '..'): string {
+  return `[${label}](${up}/${path})`
+}
+
+function sourceLink(source: string, up = '..'): string {
+  return repoLink(source.split(':')[0] ?? source, `\`${source}\``, up)
+}
+
+function pkgLink(pkg: Pkg | undefined, fallback: string, up = '..'): string {
+  return pkg ? repoLink(pkg.rel, `\`${pkg.short}\``, up) : `\`${fallback}\``
+}
+
+function pkgList(names: string[] | undefined, pkgsByShort: Map<string, Pkg>): string {
+  if (!names || names.length === 0) return '-'
+  return names.map(name => pkgLink(pkgsByShort.get(name), name)).join(', ')
+}
+
+function tableCell(value: string): string {
+  return value.replace(/\|/g, '\\|').replace(/\n/g, '<br>')
+}
+
+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()
+  if (missing.length || stale.length) {
+    throw new Error([
+      missing.length ? `missing service role classification: ${missing.join(', ')}` : '',
+      stale.length ? `stale service role classification: ${stale.join(', ')}` : '',
+    ].filter(Boolean).join('; '))
+  }
+}
+
+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>()
+  const edges = new Set<string>()
+  const companionEdges = new Set<string>()
+  const addNode = (id: string, label: string): void => {
+    if (!nodes.has(id)) nodes.set(id, `  ${id}["${escLabel(label)}"]`)
+  }
+  const addEdge = (from: string, to: string): void => { edges.add(`  ${from} --> ${to}`) }
+  const lines = generatedHeader('Capability Seams And Core Services')
+  lines.push(
+    'A service can be a core spine service, a swappable capability seam, or a bundle/composition point. The graph shows the package that owns the service declaration, known implementation packages, and packages that consume the service directly.',
+    '',
+    '```mermaid',
+    'flowchart LR',
+  )
+  for (const role of SERVICE_ROLES) {
+    const svc = nodeId('svc', role.key)
+    const owner = nodeId('pkg', role.pkg)
+    addNode(owner, role.pkg)
+    addNode(svc, `ctx.${role.key}<br/>${role.title}`)
+    addEdge(owner, svc)
+    for (const impl of role.implementations ?? []) {
+      addNode(nodeId('pkg', impl), impl)
+      addEdge(nodeId('pkg', impl), svc)
+    }
+    for (const consumer of role.consumers ?? []) {
+      addNode(nodeId('pkg', consumer), consumer)
+      addEdge(svc, nodeId('pkg', consumer))
+    }
+    for (const companion of role.companions ?? []) {
+      addNode(nodeId('pkg', companion), companion)
+      companionEdges.add(`  ${svc} -. event gate .-> ${nodeId('pkg', companion)}`)
+    }
+  }
+  lines.push(...nodes.values(), ...[...edges].sort(), ...[...companionEdges].sort())
+  lines.push('```', '', '| ctx key | Role | Owner | Implementations | Direct consumers | Companion plugins | Note |', '| --- | --- | --- | --- | --- | --- | --- |')
+  for (const role of SERVICE_ROLES) {
+    lines.push(`| \`ctx.${role.key}\` | \`${role.mode}\` | ${pkgLink(pkgsByShort.get(role.pkg), role.pkg)} | ${pkgList(role.implementations, pkgsByShort)} | ${pkgList(role.consumers, pkgsByShort)} | ${pkgList(role.companions, pkgsByShort)} | ${tableCell(role.note)} |`)
+  }
+  lines.push('', ...maintenanceFooter(maintenance))
+  return lines.join('\n')
+}
+
+function parseExampleCordis(rel: string): ExamplePlugin[] {
+  const text = readFileSync(resolve(root, rel), 'utf8')
+  const plugins: ExamplePlugin[] = []
+  let current: { id: string; name?: string } | null = null
+  const flush = (): void => {
+    if (current?.name) plugins.push({ id: current.id, name: current.name })
+  }
+  for (const line of text.split('\n')) {
+    // Top-level rows (`- id:`) and bundle-patch insert rows (`    - id:`).
+    const id = /^\s*-\s+id:\s+(.+?)\s*$/.exec(line)
+    if (id?.[1] !== undefined) {
+      flush()
+      current = { id: stripYamlScalar(id[1]) }
+      continue
+    }
+    const name = /^\s+name:\s+(.+?)\s*$/.exec(line)
+    if (name?.[1] !== undefined && current) current.name = stripYamlScalar(name[1])
+  }
+  flush()
+  return plugins
+}
+
+function stripYamlScalar(value: string): string {
+  return value.trim().replace(/^['"]|['"]$/g, '')
+}
+
+const APP_EXAMPLES = [
+  {
+    id: 'dsh_base',
+    rel: 'apps/cli/composition.md',
+    title: 'DSH Base Composition',
+    label: 'packages/bundle/base/cordis.patch.yml',
+    config: 'packages/bundle/base/cordis.patch.yml',
+    summary: 'The dsh-base bundle patch shared by the web, headless, sdk, and acp profiles; their mode bundles and user layers patch over it, while sdk-minimal owns a separate standalone tree.',
+  },
+]
+
+type AppExample = typeof APP_EXAMPLES[number]
+
+function renderAppComposition(example: AppExample): string {
+  const plugins = parseExampleCordis(example.config)
+  const maintenance = 'hybrid: the patch row list is parsed from its `cordis.yml`; app package expansion is curated from package source'
+  const lines = generatedHeader(example.title)
+  lines.push(
+    example.summary,
+    '',
+    '```mermaid',
+    'flowchart LR',
+    `  cfg["${escLabel(example.label)}<br/>cordis.yml"]`,
+  )
+  for (const plugin of plugins) {
+    const pluginNode = nodeId(`plugin_${example.id}`, plugin.id)
+    lines.push(`  ${pluginNode}["${escLabel(plugin.id)}<br/>${escLabel(plugin.name)}"]`)
+    lines.push(`  cfg --> ${pluginNode}`)
+  }
+  lines.push(
+    '```',
+    '',
+    '| Plugin id | Package / module |',
+    '| --- | --- |',
+    ...plugins.map(plugin => `| \`${plugin.id}\` | \`${plugin.name}\` |`),
+    '',
+    `Source config: [\`${example.config}\`](${linkFromDoc(example.rel, example.config)}).`,
+  )
+  lines.push('', ...maintenanceFooter(maintenance))
+  return lines.join('\n')
+}
+
+type CallSiteIndex = Map<ts.SignatureDeclaration | ts.JSDocSignature, ts.CallExpression[]>
+
+/**
+ * The only method names visitSource classifies; receiver typing runs on these
+ * alone. Obligation: every method name matched by a branch inside visitSource
+ * must appear here — the prefilter drops non-members before any branch runs,
+ * so a branch for an unlisted name is silently dead.
+ */
+const EVENT_API_METHODS = new Set(['on', 'once', 'emit', 'parallel', 'serial', 'waterfall', 'dispatch'])
+
+/**
+ * Collect event dispatch/listener relations from real cross-file receiver types.
+ *
+ * TODO: the program is seeded from the host aggregate alone (ts-project.ts
+ * documents why: one program cannot hold both faces' Context merges), so a
+ * Client package enters only when a host file imports it. Client-face
+ * listeners on client-face events are therefore under-reported —
+   * `connection/reset` omits `ui-skill`/`ui-agent-preset`. Closing it needs a
+   * second Client program whose relations merge into these, not a wider seed.
+ */
+export class EventRelationCollector {
+  private readonly relations = new Map<string, EventRelation>()
+  private readonly fileCallSites = new Map<ts.SourceFile, CallSiteIndex>()
+  private readonly localCalleeProofs = new Map<ts.FunctionDeclaration, boolean>()
+  private globalCallSites: CallSiteIndex | null = null
+  private readonly contextType: ts.Type
+  private readonly agentDispatchType: ts.Type
+  private readonly eventsServiceType: ts.Type
+  private readonly packageSourceFiles: ReadonlySet<ts.SourceFile>
+
+  constructor(
+    private readonly project: TypeScriptProject,
+    private readonly sources: readonly PackageSource[],
+  ) {
+    this.contextType = this.declaredType('vendor/cordis/src/context.ts', 'Context')
+    this.agentDispatchType = this.declaredType('packages/core/agent/src/dispatch.ts', 'AgentEventDispatch')
+    this.eventsServiceType = this.declaredType('vendor/cordis/src/events.ts', 'EventsService')
+    this.packageSourceFiles = new Set(sources.map(source => source.sourceFile))
+  }
+
+  /** Return all event relations discovered from the Program. */
+  collect(): Map<string, EventRelation> {
+    for (const source of this.sources) this.visitSource(source)
+    return this.relations
+  }
+
+  /** Resolve one named class/interface declaration to its merged instance type. */
+  private declaredType(relativePath: string, name: string): ts.Type {
+    const sourceFile = this.project.sourceFile(relativePath)
+    const declaration = sourceFile.statements.find((statement): statement is ts.ClassDeclaration | ts.InterfaceDeclaration => {
+      return (ts.isClassDeclaration(statement) || ts.isInterfaceDeclaration(statement)) && statement.name?.text === name
+    })
+    const symbol = declaration?.name && this.project.checker.getSymbolAtLocation(declaration.name)
+    if (!symbol) throw new Error(`cannot resolve TypeScript type ${name} from ${relativePath}`)
+    return this.project.checker.getDeclaredTypeOfSymbol(symbol)
+  }
+
+  /** Index resolved function calls in the given files for narrow argument-flow recovery. */
+  private buildCallSiteIndex(files: Iterable<ts.SourceFile>): CallSiteIndex {
+    const index: CallSiteIndex = new Map()
+    const visit = (node: ts.Node): void => {
+      if (ts.isCallExpression(node)) {
+        const declaration = this.project.checker.getResolvedSignature(node)?.declaration
+        if (declaration) {
+          const calls = index.get(declaration) ?? []
+          calls.push(node)
+          index.set(declaration, calls)
+        }
+      }
+      ts.forEachChild(node, visit)
+    }
+    for (const file of files) visit(file)
+    return index
+  }
+
+  /**
+   * Return every indexed call resolving to one local helper declaration.
+   * Fast path: when every same-file reference to the non-exported helper is
+   * provably a direct callee, module scoping confines all of its calls to that
+   * file, so only that file is indexed. Any other reference form may alias
+   * the function value outward, so the original full package-source index
+   * decides instead.
+   */
+  private callSitesFor(owner: ts.FunctionDeclaration): ts.CallExpression[] {
+    if (!this.globalCallSites && !this.provenLocalCallee(owner)) {
+      this.globalCallSites = this.buildCallSiteIndex(this.packageSourceFiles)
+    }
+    if (this.globalCallSites) return this.globalCallSites.get(owner) ?? []
+    const file = owner.getSourceFile()
+    let index = this.fileCallSites.get(file)
+    if (!index) {
+      index = this.buildCallSiteIndex([file])
+      this.fileCallSites.set(file, index)
+    }
+    return index.get(owner) ?? []
+  }
+
+  /**
+   * Prove every same-file reference to one helper is a direct callee. The
+   * proof owns its premises: an exported helper or a helper in a global
+   * script file (no import/export means program-wide scope, callable from
+   * another file with no same-file reference at all) fails immediately.
+   * Alias escapes (re-export statements, default exports, value reads)
+   * resolve back to the owner symbol at a non-callee position and fail the
+   * proof, as does anything the scan cannot positively classify.
+   */
+  private provenLocalCallee(owner: ts.FunctionDeclaration): boolean {
+    const cached = this.localCalleeProofs.get(owner)
+    if (cached !== undefined) return cached
+    if (hasExportModifier(owner) || !ts.isExternalModule(owner.getSourceFile())) {
+      this.localCalleeProofs.set(owner, false)
+      return false
+    }
+    const name = owner.name
+    const ownerSymbol = name && this.project.checker.getSymbolAtLocation(name)
+    let proven = !!ownerSymbol
+    const refersToOwner = (identifier: ts.Identifier): boolean => {
+      // Shorthand properties resolve to the property symbol; ask for the value side.
+      const local = ts.isShorthandPropertyAssignment(identifier.parent)
+        ? this.project.checker.getShorthandAssignmentValueSymbol(identifier.parent)
+        : this.project.checker.getSymbolAtLocation(identifier)
+      if (!local) return false
+      const symbol = local.flags & ts.SymbolFlags.Alias
+        ? this.project.checker.getAliasedSymbol(local)
+        : local
+      return symbol === ownerSymbol
+    }
+    const visit = (node: ts.Node): void => {
+      if (!proven) return
+      if (ts.isIdentifier(node) && node !== name && node.text === name?.text
+        && !isDirectCallee(node) && refersToOwner(node)) {
+        proven = false
+        return
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(owner.getSourceFile())
+    this.localCalleeProofs.set(owner, proven)
+    return proven
+  }
+
+  /** Walk one package source file and classify event API calls by receiver type. */
+  private visitSource(source: PackageSource): void {
+    const visit = (node: ts.Node): void => {
+      if (ts.isCallExpression(node)) {
+        if (this.isAgentEventEmitter(node.expression)) {
+          const event = node.arguments[2]
+          if (event) {
+            for (const name of this.finiteStringValues(event) ?? []) {
+              this.addDispatcher(name, source.pkg, 'emitAgentEvent')
+            }
+          }
+        } else if (ts.isPropertyAccessExpression(node.expression) && EVENT_API_METHODS.has(node.expression.name.text)) {
+          const receiverKind = this.receiverKind(node.expression.expression)
+          const method = node.expression.name.text
+          if (receiverKind === 'events-service' && method === 'dispatch') {
+            const argumentList = node.arguments[1]
+            if (argumentList) {
+              for (const event of this.eventNamesFromArgumentList(argumentList, new Set())) {
+                this.addDispatcher(event, source.pkg, 'events.dispatch')
+              }
+            }
+          } else if (receiverKind === 'context' || receiverKind === 'agent-dispatch') {
+            const eventNames = this.eventNamesFromCall(node, receiverKind)
+            if (method === 'on' || method === 'once') {
+              for (const event of eventNames) this.ensure(event).listeners.add(source.pkg)
+            } else if (method === 'emit' || method === 'parallel' || method === 'serial' || method === 'waterfall') {
+              for (const event of eventNames) this.addDispatcher(event, source.pkg, method)
+            }
+          }
+        }
+      }
+      ts.forEachChild(node, visit)
+    }
+    visit(source.sourceFile)
+  }
+
+  /** Match the exported contained-notification helper by declaration identity. */
+  private isAgentEventEmitter(expression: ts.Expression): boolean {
+    if (!ts.isIdentifier(expression)) return false
+    const local = this.project.checker.getSymbolAtLocation(expression)
+    if (!local) return false
+    const symbol = local.flags & ts.SymbolFlags.Alias
+      ? this.project.checker.getAliasedSymbol(local)
+      : local
+    const declarations = symbol.declarations ?? []
+    return declarations.some((declaration) => {
+      return ts.isFunctionDeclaration(declaration)
+        && declaration.name?.text === 'emitAgentEvent'
+        && this.project.relativePath(declaration.getSourceFile()) === 'packages/core/agent/src/dispatch.ts'
+    })
+  }
+
+  /** Classify a receiver using assignability to the repository's actual event API types. */
+  private receiverKind(receiver: ts.Expression): EventReceiverKind | undefined {
+    const type = this.project.checker.getTypeAtLocation(receiver)
+    if (type.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown | ts.TypeFlags.Never)) return undefined
+    if (this.project.checker.isTypeAssignableTo(type, this.eventsServiceType)) return 'events-service'
+    if (this.project.checker.isTypeAssignableTo(type, this.contextType)) return 'context'
+    if (this.project.checker.isTypeAssignableTo(type, this.agentDispatchType)) return 'agent-dispatch'
+    return undefined
+  }
+
+  /** Resolve the event-name argument for Context and fused agent dispatch calls. */
+  private eventNamesFromCall(call: ts.CallExpression, receiverKind: Exclude<EventReceiverKind, 'events-service'>): Set<string> {
+    const candidates = receiverKind === 'context' ? call.arguments.slice(0, 2) : call.arguments.slice(0, 1)
+    for (const candidate of candidates) {
+      const values = this.finiteStringValues(candidate)
+      if (values) return values
+    }
+    return new Set()
+  }
+
+  /** Recover the event slot from the argument array handed to EventsService.dispatch(). */
+  private eventNamesFromArgumentList(expression: ts.Expression, seen: Set<ts.Node>): Set<string> {
+    const current = unwrapExpression(expression)
+    if (seen.has(current)) return new Set()
+    seen.add(current)
+
+    if (ts.isArrayLiteralExpression(current)) {
+      for (const element of current.elements.slice(0, 2)) {
+        if (ts.isOmittedExpression(element) || ts.isSpreadElement(element)) continue
+        const values = this.finiteStringValues(element)
+        if (values) return values
+      }
+      return new Set()
+    }
+    if (ts.isConditionalExpression(current)) {
+      return unionSets(
+        this.eventNamesFromArgumentList(current.whenTrue, new Set(seen)),
+        this.eventNamesFromArgumentList(current.whenFalse, new Set(seen)),
+      )
+    }
+    if (!ts.isIdentifier(current)) return new Set()
+
+    const symbol = this.project.checker.getSymbolAtLocation(current)
+    if (!symbol) return new Set()
+    const events = new Set<string>()
+    for (const declaration of symbol.declarations ?? []) {
+      if (ts.isVariableDeclaration(declaration) && declaration.initializer && isConstDeclaration(declaration)) {
+        addAll(events, this.eventNamesFromArgumentList(declaration.initializer, new Set(seen)))
+      } else if (ts.isParameter(declaration)) {
+        addAll(events, this.eventNamesFromParameter(declaration, seen))
+      }
+    }
+    return events
+  }
+
+  /** Follow a non-exported local helper parameter back to every resolved call site. */
+  private eventNamesFromParameter(parameter: ts.ParameterDeclaration, seen: Set<ts.Node>): Set<string> {
+    const owner = parameter.parent
+    if (!ts.isFunctionDeclaration(owner) || hasExportModifier(owner)) return new Set()
+    const index = owner.parameters.indexOf(parameter)
+    if (index < 0) return new Set()
+    const events = new Set<string>()
+    for (const call of this.callSitesFor(owner)) {
+      const argument = call.arguments[index]
+      if (argument) addAll(events, this.eventNamesFromArgumentList(argument, new Set(seen)))
+    }
+    return events
+  }
+
+  /** Return a finite string-literal value set, rejecting widened and generic strings. */
+  private finiteStringValues(expression: ts.Expression): Set<string> | undefined {
+    const current = unwrapExpression(expression)
+    if (ts.isStringLiteralLike(current)) return new Set([current.text])
+    if (this.isForwardedAgentEventParameter(current)) return undefined
+    return finiteStringTypeValues(this.project.checker.getTypeAtLocation(current))
+  }
+
+  /** Reject the contextual parameter inside the AgentEventDispatch forwarding object. */
+  private isForwardedAgentEventParameter(expression: ts.Expression): boolean {
+    if (!ts.isIdentifier(expression)) return false
+    const declarations = this.project.checker.getSymbolAtLocation(expression)?.declarations ?? []
+    return declarations.some((declaration) => {
+      if (!ts.isParameter(declaration)) return false
+      const method = declaration.parent
+      if (!ts.isMethodDeclaration(method) || !ts.isObjectLiteralExpression(method.parent)) return false
+      const contextualType = this.project.checker.getContextualType(method.parent)
+      return contextualType !== undefined
+        && this.project.checker.isTypeAssignableTo(contextualType, this.agentDispatchType)
+    })
+  }
+
+  /** Get or create one relation row. */
+  private ensure(event: string): EventRelation {
+    const existing = this.relations.get(event)
+    if (existing) return existing
+    const relation = { dispatchers: new Map<string, Set<string>>(), listeners: new Set<string>() }
+    this.relations.set(event, relation)
+    return relation
+  }
+
+  /** Add one dispatcher method without duplicating package/method labels. */
+  private addDispatcher(event: string, pkg: string, method: string): void {
+    const relation = this.ensure(event)
+    const methods = relation.dispatchers.get(pkg) ?? new Set<string>()
+    methods.add(method)
+    relation.dispatchers.set(pkg, methods)
+  }
+}
+
+/** Return whether an identifier is the callee of a call, seen through value-preserving wrappers. */
+function isDirectCallee(identifier: ts.Identifier): boolean {
+  let current: ts.Node = identifier
+  while (
+    ts.isParenthesizedExpression(current.parent)
+    || ts.isAsExpression(current.parent)
+    || ts.isTypeAssertionExpression(current.parent)
+    || ts.isNonNullExpression(current.parent)
+    || ts.isSatisfiesExpression(current.parent)
+  ) {
+    current = current.parent
+  }
+  return ts.isCallExpression(current.parent) && current.parent.expression === current
+}
+
+/** Peel syntax-only wrappers that do not change an expression's runtime value. */
+function unwrapExpression(expression: ts.Expression): ts.Expression {
+  let current = expression
+  while (
+    ts.isParenthesizedExpression(current)
+    || ts.isAsExpression(current)
+    || ts.isTypeAssertionExpression(current)
+    || ts.isNonNullExpression(current)
+    || ts.isSatisfiesExpression(current)
+  ) {
+    current = current.expression
+  }
+  return current
+}
+
+/** Return every value only when a type is a closed string-literal union. */
+function finiteStringTypeValues(type: ts.Type): Set<string> | undefined {
+  if (type.flags & ts.TypeFlags.StringLiteral) {
+    return new Set([(type as ts.StringLiteralType).value])
+  }
+  if (type.flags & ts.TypeFlags.Never) return new Set()
+  if (!type.isUnion()) return undefined
+  const values = new Set<string>()
+  for (const member of type.types) {
+    const memberValues = finiteStringTypeValues(member)
+    if (!memberValues) return undefined
+    addAll(values, memberValues)
+  }
+  return values
+}
+
+/** Return whether a variable declaration belongs to a const declaration list. */
+function isConstDeclaration(declaration: ts.VariableDeclaration): boolean {
+  return (declaration.parent.flags & ts.NodeFlags.Const) !== 0
+}
+
+/** Return whether a declaration is visible to callers outside its source module. */
+function hasExportModifier(node: ts.Node): boolean {
+  return ts.canHaveModifiers(node) && (ts.getModifiers(node)?.some((modifier) => {
+    return modifier.kind === ts.SyntaxKind.ExportKeyword || modifier.kind === ts.SyntaxKind.DefaultKeyword
+  }) ?? false)
+}
+
+/** Add every member of source to target. */
+function addAll<T>(target: Set<T>, source: ReadonlySet<T>): void {
+  for (const value of source) target.add(value)
+}
+
+/** Return the union of two sets without mutating either input. */
+function unionSets<T>(left: ReadonlySet<T>, right: ReadonlySet<T>): Set<T> {
+  const out = new Set(left)
+  addAll(out, right)
+  return out
+}
+
+/**
+ * Select the package source files of one project in deterministic order.
+ * @param project - the loaded repository TypeScript project.
+ * @returns `packages/<group>/<pkg>/src` files tagged with their package name.
+ */
+export function collectPackageSources(project: TypeScriptProject): PackageSource[] {
+  return project.sourceFiles().flatMap((sourceFile): PackageSource[] => {
+    const rel = project.relativePath(sourceFile)
+    const match = /^packages\/[^/]+\/([^/]+)\/src\/.+\.ts$/.exec(rel)
+    return match?.[1] ? [{ rel, pkg: match[1], sourceFile }] : []
+  }).sort((left, right) => left.rel.localeCompare(right.rel))
+}
+
+function collectEventRelations(): Map<string, EventRelation> {
+  const project = new TypeScriptProject(root)
+  return new EventRelationCollector(project, collectPackageSources(project)).collect()
+}
+
+function relationPackages(map: Map<string, Set<string>>, pkgsByShort: Map<string, Pkg>): string {
+  if (map.size === 0) return '-'
+  return [...map.entries()]
+    .sort(([a], [b]) => a.localeCompare(b))
+    .map(([pkg, methods]) => `${pkgLink(pkgsByShort.get(pkg), pkg)} (${[...methods].sort().map(m => `\`${m}\``).join(', ')})`)
+    .join(', ')
+}
+
+function listenerPackages(listeners: Set<string>, pkgsByShort: Map<string, Pkg>): string {
+  if (listeners.size === 0) return '-'
+  return [...listeners].sort().map(pkg => pkgLink(pkgsByShort.get(pkg), pkg)).join(', ')
+}
+
+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'
+  const lines = generatedHeader('Event Producer And Consumer Matrix')
+  lines.push(
+    'This matrix shows which packages dispatch each harness-owned event and which packages listen to it. Events are many-to-many, so the dense relation data is presented as a table rather than one large graph. Receiver and event-name types also cover contained dispatch sites that deliberately bypass `ctx.emit`, such as subagent lifecycle containment.',
+    '',
+    '| Event | Mode | Declared in | Dispatchers | Listeners |',
+    '| --- | --- | --- | --- | --- |',
+  )
+  for (const event of [...events].sort((a, b) => a.name.localeCompare(b.name))) {
+    const relation = relations.get(event.name) ?? { dispatchers: new Map<string, Set<string>>(), listeners: new Set<string>() }
+    lines.push(`| \`${event.name}\` | \`${event.mode}\` | ${sourceLink(event.source)} | ${relationPackages(relation.dispatchers, pkgsByShort)} | ${listenerPackages(relation.listeners, pkgsByShort)} |`)
+  }
+  // Every declared event needs a dispatcher: zero means dead vocabulary or an
+  // unrecognized semantic dispatch form. Listener-free extension points remain
+  // valid. Client-declared events are exempt: the relation scan seeds the HOST
+  // aggregate program only (host+client cannot share one program — the cordis
+  // Context merges collide), so client dispatch sites are structurally
+  // invisible here; their rows stay in the table for the declarations' sake.
+  const undispatched = [...events]
+    .filter(event => !event.source.startsWith('packages/client/'))
+    .filter(event => (relations.get(event.name)?.dispatchers.size ?? 0) === 0)
+    .map(event => event.name)
+    .sort()
+  if (undispatched.length > 0) {
+    throw new Error(
+      `event-producer-consumer matrix: no dispatcher found for declared event${undispatched.length > 1 ? 's' : ''} `
+      + `${undispatched.map(name => `"${name}"`).join(', ')} — dead vocabulary, or a dispatch form the semantic scan misses `
+      + '(teach scripts/gen-doc-graphs.ts that form)',
+    )
+  }
+  const declared = new Set(events.map(event => event.name))
+  const extra = [...relations.keys()].filter(event => !declared.has(event)).sort()
+  if (extra.length > 0) {
+    lines.push('', '## Non-harness or undeclared event strings seen in package source', '', '| Event string | Dispatchers | Listeners |', '| --- | --- | --- |')
+    for (const event of extra) {
+      const relation = relations.get(event)
+      if (!relation) continue
+      lines.push(`| \`${event}\` | ${relationPackages(relation.dispatchers, pkgsByShort)} | ${listenerPackages(relation.listeners, pkgsByShort)} |`)
+    }
+  }
+  lines.push('', ...maintenanceFooter(maintenance))
+  return lines.join('\n')
+}
+
+function renderLifecycle(): string {
+  const maintenance = 'curated Mermaid sequence; exact event signatures live in the generated Cordis catalog'
+  return [
+    ...generatedHeader('Agent Turn And Step Lifecycle'),
+    'This sequence is the visual companion to [architecture.md](architecture.md#turn-flow). It keeps durable replay facts on `session/event` and live control/status on `agent/*`.',
+    '',
+    '```mermaid',
+    'sequenceDiagram',
+    '  participant User',
+    '  participant Agent',
+    '  participant Driver',
+    '  participant Hooks as hook listeners',
+    '  participant Prompt as ctx.systemPrompt',
+    '  participant LLM as ctx.llm',
+    '  participant Tools as ctx.tools',
+    '  participant Session',
+    '  participant SDK as UI or SDK listener',
+    '  User->>Agent: followup(content)',
+    `  Agent-->>SDK: ${mermaidCode('agent/inbox/spliced')}`,
+    `  Agent-->>SDK: ${mermaidCode('agent/inbox/inserted')} { message }`,
+    '  Agent->>Driver: queued work wakes driver',
+    `  Driver-->>SDK: ${mermaidCode('agent/status')} running`,
+    `  Driver->>Session: ${mermaidCode('turn/start')}`,
+    '  Note over Agent,Driver: claim pending next-step input plus one queued prompt',
+    `  Driver-->>SDK: ${mermaidCode('agent/inbox/spliced')} pure deletion`,
+    `  Driver-->>SDK: ${mermaidCode('agent/inbox/claimed')} { message, turn } per message`,
+    `  Driver->>Prompt: ${mermaidCode('system-prompt/assemble')} waterfall`,
+    `  Driver->>Hooks: ${mermaidCode('agent/pre-step')} waterfall`,
+    '  Hooks-->>Driver: authoritative reject or enter(messages)',
+    '  alt proposed step rejected, first batch empty, or pre-step failed',
+    '    Driver-->>Driver: claimed batch stays removed, the open turn spends no step',
+    '  else enter proposed step',
+    `  Driver->>Session: ${mermaidCode('step/start')}`,
+    `  Driver->>Hooks: ${mermaidCode('agent/request')} waterfall`,
+    '  Driver->>LLM: prepareCall(config, signal)',
+    '  Note over Driver,LLM: cancellation during either async phase commits neither system nor users',
+    '  Note over Driver,Session: synchronous admission using the prepared call capability',
+    `  Driver->>Session: ${mermaidCode('system/message')} ordered per-node reconciliation`,
+    `  Driver->>Session: ${mermaidCode('user/message')} per entered message`,
+    `  Driver->>Session: ${mermaidCode('request/header')} and ${mermaidCode('request/context')} as needed`,
+    '  Driver->>Driver: derive and freeze request from the log',
+    `  Driver->>LLM: bound prepared call through ${mermaidCode('llm/stream')} waterfall`,
+    '  LLM-->>Driver: StreamChunk*',
+    `  Driver-->>SDK: ${mermaidCode('agent/assistant-stream')} chunk*`,
+    '  alt final adapter or terminal in-band request failure',
+    `    Driver->>Session: ${mermaidCode('assistant/attempt')}`,
+    `    Driver-->>SDK: ${mermaidCode('agent/assistant-stream')} committed end`,
+    `    Driver->>Hooks: ${mermaidCode('agent/request-error')} waterfall`,
+    '    Hooks-->>Driver: return retry action or preserve the original error',
+    '    Note over Driver,LLM: retry in the open step: prepare and reconcile the same rendered assembly without repeating pre-step or users',
+    '  else model request succeeded',
+    `  Driver->>Session: ${mermaidCode('assistant/message')}`,
+    `  Driver-->>SDK: ${mermaidCode('agent/assistant-stream')} committed end`,
+    '  Driver->>Tools: classify pending call by executionMode',
+    '  loop barriers and bounded rolling pool, reclassify before start',
+    '    opt call starts',
+    `      Driver->>Session: ${mermaidCode('tool/call')}`,
+    '      Driver->>Tools: ordered pre, concurrent execute',
+    '      Tools-->>Session: tool-owned events when applicable',
+    '    end',
+    '    opt next model-order result ready',
+    '      Driver->>Tools: ordered post',
+    `      Driver->>Session: ${mermaidCode('tool/result')}`,
+    '    end',
+    '  end',
+    `  Driver->>Session: ${mermaidCode('step/end')}`,
+    '  opt natural stop and next-step inbox empty',
+    `    Driver->>Hooks: ${mermaidCode('agent/turn-stopping')} serial terminal checkpoint`,
+    '  end',
+    '  opt next-step input is pending',
+    '    Driver-->>Driver: claim pending next-step input',
+    `    Driver-->>SDK: ${mermaidCode('agent/inbox/claimed')} { message, turn } per message`,
+    `    Driver->>Hooks: ${mermaidCode('agent/pre-step')} waterfall`,
+    '    Hooks-->>Driver: authoritative reject or enter(messages)',
+    '  end',
+    '  end',
+    '  end',
+    `  Driver->>Session: ${mermaidCode('turn/end')}`,
+    `  Driver-->>SDK: ${mermaidCode('agent/status')} idle`,
+    '```',
+    '',
+    'The `assistant/message` event records every successful provider call, including content-less and `max-tokens` finishes, and embeds the exact compact timed stream. Empty content stays out of derived history. A failed, retried, cancelled, or stream-error attempt that reaches settlement without a surface message records its stream as `assistant/attempt`. Live `agent/assistant-stream` chunk frames are transient; replay reads either durable settlement, and a hard process loss before settlement leaves no durable attempt stream.',
+    '',
+    '`dsh-compaction-basic` uses `agent/pre-step` for pressure before request derivation and `agent/request-error` only for canonical context overflow. Once either trigger qualifies, optional tool-result pruning runs before summary selection. Recovery runs within the open step and retries only when pruning or summarization advances the surface replacement generation; otherwise the original request error remains authoritative. Each retry prepares its call and reconciles the retained rendered assembly before request derivation, without repeating assembly, pre-step, or user admission.',
+    '',
+    'The returned `agent/pre-step` decision is authoritative; listeners wrapping `next()` preserve downstream messages and `startsRequestSeries` unless replacement is intentional. Steering and injected context pass through the same waterfall after a later claim operation takes their next-step batch.',
+    '',
+    'SDK users that need replayable transcript data should consume `session/event`; `agent/*` is the live coordination API for queue/status, prompt interception, request construction, steering, continuation, and errors.',
+    '',
+    ...maintenanceFooter(maintenance),
+  ].join('\n')
+}
+
+function renderToolPipeline(): string {
+  const maintenance = 'curated Mermaid flow; exact tool schemas and event signatures live in generated catalogs'
+  return [
+    ...generatedHeader('Tool Execution Pipeline'),
+    'This graph shows where policy, hooks, sandboxing, filesystem guards, result rewriting, final-outcome observation, and UI rendering run without changing the loop. The `tools/pre-execute` waterfall runs first, monotonic guards run next, and the `tools/execute` and `tools/post-execute` waterfalls follow; the three waterfalls may transform a call. Definition-owned `finalizeContent` and `tools/result` run afterward.',
+    '',
+    '```mermaid',
+    'flowchart TD',
+    '  model["Assistant message contains tool-call block"]',
+    `  toolCall["Session event: ${mermaidCode('tool/call')}<br/>logged before execution"]`,
+    '  presentCall["UI pending card<br/>presentCall(args)"]',
+    `  pre["${mermaidCode('tools/pre-execute')} waterfall<br/>hooks, permission, sandbox"]`,
+    '  guards["Registered monotonic guards<br/>deny or abstain; identity protected"]',
+    '  denied["denied or approval refused<br/>tool body skipped"]',
+    `  approval["${mermaidCode('ctx.approval')} one-shot prompt<br/>absent or unanswerable: deny"]`,
+    `  around["${mermaidCode('tools/execute')} waterfall<br/>timeout, retry, metrics (around dispatch)"]`,
+    '  toolBody["Registered tool execute() body"]',
+    `  fsGate["${mermaidCode('fs/write-intent')} or ${mermaidCode('fs/edit-intent')}<br/>tool-fs mutations only"]`,
+    `  owned["Tool-owned session events<br/>${mermaidCode('todo/write')}, ${mermaidCode('fs/observed')}, ${mermaidCode('hook/invoked')}, ${mermaidCode('hook/result')}, ${mermaidCode('tool/ptc-dispatch')}"]`,
+    `  post["${mermaidCode('tools/post-execute')} waterfall<br/>accept, block, replace, add context"]`,
+    '  normalized["Registry outer normalization<br/>pipeline/result snapshot throws become isError"]',
+    '  finalize["ToolDefinition.finalizeContent<br/>last content-only invariant"]',
+    `  final["${mermaidCode('tools/result')} synchronous notification<br/>frozen authoritative outcome"]`,
+    '  context["Active-batch additionalContexts FIFO<br/>injected user/message after recorded tool results"]',
+    `  toolResult["Session event: ${mermaidCode('tool/result')}<br/>single model-facing outcome"]`,
+    '  allResults["Tool batch settled<br/>recorded tool/result events complete"]',
+    '  presentResult["UI completed card<br/>presentResult(args, result)"]',
+    '  model --> toolCall',
+    '  toolCall --> presentCall',
+    '  toolCall --> pre',
+    '  pre -->|allow| guards',
+    '  guards -->|allow| around',
+    '  guards -->|deny| denied',
+    '  guards -.->|throw| normalized',
+    '  around --> toolBody',
+    '  pre -->|deny| denied',
+    '  pre -->|ask| approval',
+    '  approval -->|allowed-once| guards',
+    '  approval -->|rejected, cancelled, unavailable| denied',
+    '  approval -.->|throw| normalized',
+    '  denied --> post',
+    '  pre -.->|throw| normalized',
+    '  toolBody --> fsGate',
+    '  fsGate --> toolBody',
+    '  toolBody --> owned',
+    '  toolBody --> around',
+    '  around --> post',
+    '  around -.->|wrapper throws| normalized',
+    '  post -.->|throw| normalized',
+    '  post --> finalize',
+    '  normalized --> finalize',
+    '  finalize --> final',
+    '  final --> toolResult',
+    '  toolResult --> presentResult',
+    '  toolResult --> allResults',
+    '  allResults --> context',
+    '```',
+    '',
+    'Filesystem read-before-edit checks stay below `tool-fs` on `fs/*` events. Generic pre/post waterfalls host hooks and approval policy; `ctx.approval` resolves asks before monotonic guards, and owner policy that must not be reordered remains a registered guard. Around-dispatch concerns such as timeouts wrap `tools/execute`. The registry losslessly snapshots the candidate result and normalizes a snapshot failure before the visible definition\'s snapshotted `finalizeContent` callback enforces its synchronous content-only invariant. `tools/result` then observes the immutable, lossless-JSON outcome. This lets hooks span tool families without coupling the tools to one policy service. PTC mode sends both the reserved `run_code` transport and its serialized sub-calls through the pipeline; sub-calls carry the parent token, log `tool/ptc-dispatch`, return denials as binding rejections, and omit `additionalContexts` to preserve call/result adjacency.',
+    '',
+    ...maintenanceFooter(maintenance),
+  ].join('\n')
+}
+
+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, model.services) },
+    ...APP_EXAMPLES.map(example => ({ rel: example.rel, content: renderAppComposition(example) })),
+    { 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() },
+  ]
+  docs.unshift({ rel: 'docs/graph-atlas.md', content: renderIndex(docs) })
+  return docs
+}
+
+function renderIndex(docs: GraphDoc[]): string {
+  const labels: Record<string, string> = {
+    'docs/capability-seams.md': 'capability seams and core services',
+    'apps/cli/composition.md': 'dsh shared base composition',
+    'docs/event-producer-consumer.md': 'event producer/consumer matrix',
+    'docs/agent-lifecycle.md': 'agent turn and step lifecycle',
+    'docs/tool-execution-pipeline.md': 'tool execution pipeline',
+  }
+  const modes: Record<string, string> = {
+    'docs/capability-seams.md': 'hybrid generated',
+    'apps/cli/composition.md': 'hybrid generated',
+    'docs/event-producer-consumer.md': 'hybrid generated',
+    'docs/agent-lifecycle.md': 'curated',
+    'docs/tool-execution-pipeline.md': 'curated',
+  }
+  const rows = [
+    '| [module dependency graph](module-graph.md) | `generated` |',
+    '| [tool schema catalog and package map](tool-catalog.md) | `generated` |',
+    ...docs.map((doc) => {
+      const link = graphIndexLink(doc.rel)
+      return `| [${labels[doc.rel] ?? link}](${link}) | \`${modes[doc.rel] ?? 'generated'}\` |`
+    }),
+  ]
+  const maintenance = 'mixed: each linked page declares generated, hybrid, or curated mode'
+  return [
+    ...generatedHeader('Documentation Graph Index'),
+    'These diagrams show relationships that the generated catalogs do not. Use them to find package relationships, capability seams, event flow, model-facing tools, app composition, and runtime lifecycle paths. Exact signatures and type definitions still live in the [subsystem pages](subsystems/core.md) (types + the generated Cordis API regions) and [tool-catalog.md](tool-catalog.md).',
+    '',
+    'The process decision behind this index is recorded in [the documentation graph Agent Note](../.agents/notes/archived/process/2026-07-03-documentation-graph-atlas.md).',
+    '',
+    '| Graph | Mode |',
+    '| --- | --- |',
+    ...rows,
+    '',
+    'Regenerate with `pnpm run gen-doc-graphs`; verify freshness with `pnpm run verify-doc-graphs`.',
+    '',
+    ...maintenanceFooter(maintenance),
+  ].join('\n')
+}
+
+function main(): void {
+  const docs = renderDocs()
+  if (process.argv.includes('--check')) {
+    const stale: string[] = []
+    for (const doc of docs) {
+      const abs = resolve(root, doc.rel)
+      const committed = existsSync(abs) ? readFileSync(abs, 'utf8') : null
+      if (committed !== doc.content) stale.push(doc.rel)
+    }
+    if (stale.length === 0) {
+      console.log(`gen-doc-graphs: ${docs.length} graph doc(s) are up to date.`)
+      return
+    }
+    console.error(`gen-doc-graphs: stale graph doc(s): ${stale.join(', ')}. Run \`pnpm run gen-doc-graphs\` and commit the result.`)
+    process.exit(1)
+  }
+
+  for (const doc of docs) {
+    mkdirSync(dirname(resolve(root, doc.rel)), { recursive: true })
+    writeFileSync(resolve(root, doc.rel), doc.content)
+  }
+  console.log(`gen-doc-graphs: wrote ${docs.length} graph doc(s).`)
+}
+
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
+  main()
+}

scripts/gen-scoped-events.ts

@@ -0,0 +1,399 @@
+/**
+ * Generate dsh-scope's invariant resolver map from the repository TypeScript
+ * Program.
+ *
+ * A scoped event declares `this: Scoped<Base>`. Real `scopeTarget(base, key)`
+ * calls establish the routing-key type for that base. The generator searches
+ * every event payload parameter and one property level for exactly one type
+ * equivalent to that key. Each generated resolver compiles against the merged
+ * `Events` parameter tuple. Zero matches require `@dshScopeScan unsupported`;
+ * multiple matches are ambiguous and always fail loud.
+ *
+ *   `tsx scripts/gen-scoped-events.ts`          -> write the generated source
+ *   `tsx scripts/gen-scoped-events.ts --check`  -> exit 1 when it is stale
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import ts from 'typescript'
+import { pointer, rawJsDoc } from './jsdoc.ts'
+import { TypeScriptProject } from './ts-project.ts'
+
+const root = resolve(import.meta.dirname, '..')
+const OUT = 'packages/core/scope/src/scoped-events.generated.ts'
+const SCOPE_DOC_MARKER = 'Scope-filtered dispatch'
+
+interface ScopeTargetContract {
+  baseType: ts.Type
+  keyType: ts.Type
+  source: string
+}
+
+interface SubjectCandidate {
+  path: string
+  parameter: number
+  property?: string
+  type: ts.Type
+}
+
+interface ScopedEventResolver {
+  event: string
+  candidate: SubjectCandidate | null
+}
+
+interface ScopeTag {
+  present: boolean
+  unsupported: boolean
+}
+
+/** Program-backed analyzer and renderer for the generated scoped-event resolvers. */
+class ScopedEventGenerator {
+  private readonly checker: ts.TypeChecker
+  private readonly packageSources: ts.SourceFile[]
+  private readonly scopeTargetDeclaration: ts.FunctionDeclaration
+  private readonly scopedSymbol: ts.Symbol
+  private readonly violations: string[] = []
+
+  constructor(private readonly project: TypeScriptProject) {
+    this.checker = project.checker
+    this.packageSources = project.sourceFiles().filter((sourceFile) => {
+      return /^packages\/[^/]+\/[^/]+\/src\/.+\.ts$/.test(project.relativePath(sourceFile))
+    })
+    this.scopeTargetDeclaration = this.functionDeclaration(
+      'packages/core/scope/src/index.ts',
+      'scopeTarget',
+    )
+    this.scopedSymbol = this.typeAliasSymbol(
+      'packages/core/scope/src/index.ts',
+      'Scoped',
+    )
+  }
+
+  /** Render the complete generated TypeScript module or throw every contract violation. */
+  render(): string {
+    const contracts = this.collectScopeTargetContracts()
+    const resolvers = this.collectScopedEventResolvers(contracts)
+    if (this.violations.length > 0) {
+      throw new Error(
+        `gen-scoped-events: ${this.violations.length} scoped-event contract violation(s):\n`
+        + this.violations.map(violation => `  - ${violation}`).join('\n'),
+      )
+    }
+    return [
+      '/**',
+      ' * Generated scoped-event routing-subject resolvers for dsh-scope invariants.',
+      ' * Do not edit by hand; run `pnpm run gen-scoped-events`.',
+      ' *',
+      ' * @module @deepseek-ai/dsh-scope/scoped-events.generated',
+      ' */',
+      '',
+      'type ScopedSubjectResolver = (args: readonly unknown[]) => unknown',
+      '',
+      'const scopedSubjectResolvers: Readonly<Record<string, ScopedSubjectResolver | null>> = Object.freeze({',
+      ...resolvers.map(({ event, candidate }) => {
+        if (candidate === null) return `  '${event}': null,`
+        const subject = candidate.property === undefined
+          ? `args[${candidate.parameter}]`
+          : `(args[${candidate.parameter}] as Record<string, unknown>)[${quote(candidate.property)}]`
+        return `  '${event}': args => ${subject},`
+      }),
+      '})',
+      '',
+      '/**',
+      ' * Resolve the routing key named by one scoped event payload. A null',
+      ' * resolver means the payload cannot expose its external routing key, so the',
+      ' * invariant checks carrier presence only.',
+      ' * @param event - runtime Cordis event name.',
+      ' * @returns the generated subject resolver, null for presence-only,',
+      ' *   or undefined when the event is not scope-filtered.',
+      ' */',
+      'export function scopedSubjectResolverFor(event: string): ScopedSubjectResolver | null | undefined {',
+      '  return scopedSubjectResolvers[event]',
+      '}',
+      '',
+    ].join('\n')
+  }
+
+  /** Resolve one named function declaration from a known source file. */
+  private functionDeclaration(relativePath: string, name: string): ts.FunctionDeclaration {
+    const sourceFile = this.project.sourceFile(relativePath)
+    const declaration = sourceFile.statements.find((statement): statement is ts.FunctionDeclaration => {
+      return ts.isFunctionDeclaration(statement) && statement.name?.text === name
+    })
+    if (!declaration) throw new Error(`gen-scoped-events: cannot resolve function ${name} from ${relativePath}`)
+    return declaration
+  }
+
+  /** Resolve one named type-alias symbol from a known source file. */
+  private typeAliasSymbol(relativePath: string, name: string): ts.Symbol {
+    const sourceFile = this.project.sourceFile(relativePath)
+    const declaration = sourceFile.statements.find((statement): statement is ts.TypeAliasDeclaration => {
+      return ts.isTypeAliasDeclaration(statement) && statement.name.text === name
+    })
+    const symbol = declaration && this.checker.getSymbolAtLocation(declaration.name)
+    if (!symbol) throw new Error(`gen-scoped-events: cannot resolve type ${name} from ${relativePath}`)
+    return symbol
+  }
+
+  /** Collect every real scopeTarget(base, key) base/key type contract. */
+  private collectScopeTargetContracts(): ScopeTargetContract[] {
+    const contracts: ScopeTargetContract[] = []
+    const visit = (sourceFile: ts.SourceFile, node: ts.Node): void => {
+      if (ts.isCallExpression(node)
+        && this.checker.getResolvedSignature(node)?.declaration === this.scopeTargetDeclaration) {
+        const base = node.arguments[0]
+        const key = node.arguments[1]
+        if (!base || !key) {
+          const source = pointer(this.project.relativePath(sourceFile), sourceFile, node)
+          this.violations.push(`${source} calls scopeTarget without base and key arguments`)
+        } else {
+          contracts.push({
+            baseType: this.checker.getTypeAtLocation(base),
+            keyType: this.checker.getTypeAtLocation(key),
+            source: pointer(this.project.relativePath(sourceFile), sourceFile, node),
+          })
+        }
+      }
+      ts.forEachChild(node, (child) => { visit(sourceFile, child) })
+    }
+    for (const sourceFile of this.packageSources) visit(sourceFile, sourceFile)
+    return contracts
+  }
+
+  /** Collect every Events member and derive its generated resolver. */
+  private collectScopedEventResolvers(contracts: readonly ScopeTargetContract[]): ScopedEventResolver[] {
+    const resolvers: ScopedEventResolver[] = []
+    for (const sourceFile of this.packageSources) {
+      const rel = this.project.relativePath(sourceFile)
+      const visit = (node: ts.Node): void => {
+        if (ts.isInterfaceDeclaration(node) && node.name.text === 'Events' && isCordisModuleInterface(node)) {
+          for (const member of node.members) {
+            if (!ts.isMethodSignature(member) || !ts.isStringLiteral(member.name)) continue
+            const event = member.name.text
+            const raw = rawJsDoc(sourceFile.text, member)
+            const where = `event '${event}' (${pointer(rel, sourceFile, member)})`
+            const tag = parseScopeTag(raw, where, this.violations)
+            const thisParameter = member.parameters.find(isThisParameter)
+            const scopedBase = thisParameter && this.scopedBaseType(thisParameter)
+            if (!scopedBase) {
+              if (raw.includes(SCOPE_DOC_MARKER)) {
+                this.violations.push(
+                  `${where} documents scope-filtered dispatch but its signature has no this: Scoped<...> receiver`,
+                )
+              }
+              if (tag.present) {
+                this.violations.push(`${where} has @dshScopeScan metadata but is not a Scoped event`)
+              }
+              continue
+            }
+            if (!raw.includes(SCOPE_DOC_MARKER)) {
+              this.violations.push(
+                `${where} has this: Scoped<...> but its JSDoc does not explain "${SCOPE_DOC_MARKER}"`,
+              )
+            }
+            const keyType = this.routingKeyType(where, scopedBase, contracts)
+            if (!keyType) continue
+            const candidates = this.subjectCandidates(member)
+              .filter(candidate => this.typesEquivalent(candidate.type, keyType))
+            if (candidates.length > 1) {
+              this.violations.push(
+                `${where} has multiple routing-key candidates for ${this.typeText(keyType)}: `
+                + candidates.map(candidate => `${candidate.path}: ${this.typeText(candidate.type)}`).join(', '),
+              )
+              continue
+            }
+            if (candidates.length === 0) {
+              if (!tag.unsupported) {
+                const keyLabel = this.typeText(keyType)
+                this.violations.push(
+                  `${where} exposes no parameter or one-level property equivalent to routing key type ${keyLabel}; `
+                  + 'add @dshScopeScan unsupported only when the key is intentionally absent from the payload',
+                )
+              }
+              resolvers.push({ event, candidate: null })
+              continue
+            }
+            if (tag.unsupported) {
+              this.violations.push(
+                `${where} has unnecessary @dshScopeScan unsupported; ${candidates[0]?.path} exposes the routing key`,
+              )
+              continue
+            }
+            resolvers.push({ event, candidate: candidates[0] ?? null })
+          }
+        }
+        ts.forEachChild(node, visit)
+      }
+      visit(sourceFile)
+    }
+    return resolvers.sort((left, right) => left.event.localeCompare(right.event))
+  }
+
+  /** Extract the Base type from one exact this: Scoped<Base> parameter. */
+  private scopedBaseType(parameter: ts.ParameterDeclaration): ts.Type | undefined {
+    const type = this.checker.getTypeAtLocation(parameter)
+    if (type.aliasSymbol !== this.scopedSymbol) return undefined
+    return type.aliasTypeArguments?.[0]
+  }
+
+  /** Resolve one unambiguous key type for a scoped carrier base. */
+  private routingKeyType(
+    where: string,
+    scopedBase: ts.Type,
+    contracts: readonly ScopeTargetContract[],
+  ): ts.Type | undefined {
+    const matches = contracts.filter((contract) => {
+      return this.checker.isTypeAssignableTo(this.normalizedType(contract.baseType), this.normalizedType(scopedBase))
+    })
+    if (matches.length === 0) {
+      this.violations.push(
+        `${where} has no matching scopeTarget(base, key) call for carrier base ${this.typeText(scopedBase)}`,
+      )
+      return undefined
+    }
+    const keyTypes: ts.Type[] = []
+    for (const match of matches) {
+      if (!keyTypes.some(type => this.typesEquivalent(type, match.keyType))) keyTypes.push(match.keyType)
+    }
+    if (keyTypes.length > 1) {
+      this.violations.push(
+        `${where} carrier base ${this.typeText(scopedBase)} has inconsistent routing-key types: `
+        + matches.map(match => `${this.typeText(match.keyType)} at ${match.source}`).join(', '),
+      )
+      return undefined
+    }
+    return keyTypes[0]
+  }
+
+  /** Enumerate every payload parameter and every accessible one-level property. */
+  private subjectCandidates(member: ts.MethodSignature): SubjectCandidate[] {
+    const candidates: SubjectCandidate[] = []
+    let runtimeIndex = 0
+    for (const parameter of member.parameters) {
+      if (isThisParameter(parameter)) continue
+      const directPath = `args[${runtimeIndex}]`
+      const parameterType = this.checker.getTypeAtLocation(parameter)
+      candidates.push({ path: directPath, parameter: runtimeIndex, type: parameterType })
+      for (const property of this.checker.getPropertiesOfType(this.normalizedType(parameterType))) {
+        const name = property.getName()
+        if (name.startsWith('__@') || hasNonPublicDeclaration(property)) continue
+        candidates.push({
+          path: `${directPath}.${name}`,
+          parameter: runtimeIndex,
+          property: name,
+          type: this.checker.getTypeOfSymbolAtLocation(property, parameter),
+        })
+      }
+      runtimeIndex += 1
+    }
+    return dedupeCandidates(candidates)
+  }
+
+  /** Compare exact Program type identities after removing null and undefined. */
+  private typesEquivalent(left: ts.Type, right: ts.Type): boolean {
+    const normalizedLeft = this.normalizedType(left)
+    const normalizedRight = this.normalizedType(right)
+    if (normalizedLeft.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) return false
+    if (normalizedRight.flags & (ts.TypeFlags.Any | ts.TypeFlags.Unknown)) return false
+    return normalizedLeft === normalizedRight
+  }
+
+  /** Remove null and undefined from a routing or candidate type. */
+  private normalizedType(type: ts.Type): ts.Type {
+    return this.checker.getNonNullableType(type)
+  }
+
+  /** Render a stable diagnostic type label. */
+  private typeText(type: ts.Type): string {
+    return this.checker.typeToString(type, undefined, ts.TypeFormatFlags.NoTruncation)
+  }
+}
+
+/** Return whether an Events interface is inside declare module '@deepseek-ai/cordis'. */
+function isCordisModuleInterface(node: ts.InterfaceDeclaration): boolean {
+  const block = node.parent
+  const declaration = block.parent
+  return ts.isModuleBlock(block)
+    && ts.isModuleDeclaration(declaration)
+    && ts.isStringLiteral(declaration.name)
+    && declaration.name.text === '@deepseek-ai/cordis'
+}
+
+/** Return whether a parameter is the explicit TypeScript this receiver. */
+function isThisParameter(parameter: ts.ParameterDeclaration): boolean {
+  return ts.isIdentifier(parameter.name) && parameter.name.text === 'this'
+}
+
+/** Parse and validate the optional @dshScopeScan unsupported tag. */
+function parseScopeTag(raw: string, where: string, violations: string[]): ScopeTag {
+  const tags = raw
+    .replace(/^\/\*\*/, '')
+    .replace(/\*\/$/, '')
+    .split('\n')
+    .map(line => line.replace(/^\s*\*?\s?/, '').trim())
+    .filter(line => line.startsWith('@dshScopeScan'))
+  if (tags.length > 1) violations.push(`${where} has multiple @dshScopeScan tags`)
+  if (tags.length === 0) return { present: false, unsupported: false }
+  const unsupported = tags[0] === '@dshScopeScan unsupported'
+  if (!unsupported) {
+    violations.push(
+      `${where} has invalid scoped-event scan metadata '${tags[0]}'; expected '@dshScopeScan unsupported'`,
+    )
+  }
+  return { present: true, unsupported }
+}
+
+/** Return whether a property has a private or protected declaration. */
+function hasNonPublicDeclaration(symbol: ts.Symbol): boolean {
+  return (symbol.declarations ?? []).some((declaration) => {
+    if (!ts.canHaveModifiers(declaration)) return false
+    return ts.getModifiers(declaration)?.some((modifier) => {
+      return modifier.kind === ts.SyntaxKind.PrivateKeyword || modifier.kind === ts.SyntaxKind.ProtectedKeyword
+    }) ?? false
+  })
+}
+
+/** Deduplicate candidate paths contributed by merged/intersection types. */
+function dedupeCandidates(candidates: readonly SubjectCandidate[]): SubjectCandidate[] {
+  const seen = new Set<string>()
+  return candidates.filter((candidate) => {
+    if (seen.has(candidate.path)) return false
+    seen.add(candidate.path)
+    return true
+  })
+}
+
+/** Quote a generated property key as a single-quoted TypeScript string. */
+function quote(value: string): string {
+  return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`
+}
+
+/**
+ * Render the generated scoped-event resolver module for one repository root.
+ * @param projectRoot - repository root carrying tsconfig.host.json.
+ * @returns complete generated TypeScript source.
+ */
+export function renderScopedEvents(projectRoot: string = root): string {
+  return new ScopedEventGenerator(new TypeScriptProject(projectRoot)).render()
+}
+
+/** Generate or freshness-check the fixed dsh-scope source file. */
+function main(): void {
+  const content = renderScopedEvents()
+  const output = resolve(root, OUT)
+  if (process.argv.includes('--check')) {
+    const committed = existsSync(output) ? readFileSync(output, 'utf8') : null
+    if (committed === content) {
+      console.log(`gen-scoped-events: ${OUT} is up to date.`)
+      return
+    }
+    console.error(`gen-scoped-events: ${OUT} is stale. Run \`pnpm run gen-scoped-events\` and commit it.`)
+    process.exit(1)
+  }
+  writeFileSync(output, content)
+  console.log(`gen-scoped-events: wrote ${OUT}.`)
+}
+
+if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
+  main()
+}

scripts/jsdoc.ts

@@ -0,0 +1,201 @@
+/**
+ * Shared JSDoc parsing and completeness checks for the Cordis, persistence,
+ * and config catalogs and the exported-API gate.
+ */
+
+import ts from 'typescript'
+
+/** Repo-relative source pointer `file:line` for a node's first character. */
+export function pointer(rel: string, sf: ts.SourceFile, node: ts.Node): string {
+  const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf))
+  return `${rel}:${line + 1}`
+}
+
+/** The raw `/** … *​/` JSDoc block immediately preceding a node, or '' if none. */
+export function rawJsDoc(text: string, node: ts.Node): string {
+  const ranges = ts.getLeadingCommentRanges(text, node.getFullStart()) ?? []
+  const jsdoc = ranges.filter(r => text.slice(r.pos, r.pos + 3) === '/**').at(-1)
+  return jsdoc ? text.slice(jsdoc.pos, jsdoc.end) : ''
+}
+
+/** A dispatch mode, rendered as the badge after an event name in the catalog. */
+export type Mode = 'emit' | 'waterfall' | 'parallel' | 'serial' | 'bail'
+
+/**
+ * Parse a raw JSDoc block into description prose and an optional `@mode`. Prose
+ * ends at the first block tag, paragraphs collapse to one line, bullet items
+ * remain separate lines, and `{@link X}` renders as `X`.
+ * @param raw - the raw comment text including the JSDoc delimiters.
+ * @returns the collapsed description prose, parsed valid `@mode` (or null),
+ *   and whether any `@mode` tag was present.
+ */
+export function parseJsDoc(raw: string): { doc: string; mode: Mode | null; hasMode: boolean } {
+  const inner = raw
+    .replace(/^\/\*\*/, '')
+    .replace(/\*\/$/, '')
+    .split('\n')
+    .map(l => l.replace(/^\s*\*?\s?/, '').replace(/\s+$/, ''))
+  let mode: Mode | null = null
+  let hasMode = false
+  let inTags = false
+  const blocks: string[] = []
+  let para: string[] = []
+  let list: string[] = []
+  let item: string[] = []
+  const join = (parts: string[]): string => parts.join(' ').replace(/\s+/g, ' ').trim()
+  const flushItem = (): void => {
+    if (item.length) list.push(join(item))
+    item = []
+  }
+  const flushList = (): void => {
+    flushItem()
+    if (list.length) blocks.push(list.join('\n')) // one block, items on own lines
+    list = []
+  }
+  const flushPara = (): void => {
+    flushList()
+    if (para.length) blocks.push(join(para))
+    para = []
+  }
+  for (const line of inner) {
+    const tagLine = line.trimStart()
+    const m = /^@mode\s+(emit|waterfall|parallel|serial|bail)\s*$/.exec(tagLine)
+    if (m) { mode = m[1] as Mode; hasMode = true; flushPara(); inTags = true; continue }
+    if (/^@mode\b/.test(tagLine)) { hasMode = true; flushPara(); inTags = true; continue }
+    if (tagLine.startsWith('@')) { flushPara(); inTags = true; continue }
+    if (inTags) continue // block-tag territory: continuations are never prose
+    if (line.trim() === '') { flushPara(); continue }
+    if (/^-\s+/.test(line)) {
+      // A list item starts: a pending paragraph (e.g. an intro line directly
+      // above the list, no blank between) flushes FIRST so it renders above.
+      flushItem()
+      if (para.length) { blocks.push(join(para)); para = [] }
+      item.push(line)
+      continue
+    }
+    if (item.length) { item.push(line); continue } // continuation of current item
+    para.push(line)
+  }
+  flushPara()
+  const doc = blocks.join('\n\n').replace(/\{@link\s+([^}]+)\}/g, '$1').trim()
+  return { doc, mode, hasMode }
+}
+
+/**
+ * Parse `@param` and `@returns` descriptions, including continuation lines.
+ * Parameter separators are optional and `[optional]` names unwrap.
+ * @param raw - the raw comment text including the JSDoc delimiters.
+ * @returns the `@param` name→description map plus the `@returns` description
+ * (null when the tag is absent, '' when present but empty).
+ */
+export function parseTags(raw: string): { params: Map<string, string>; returns: string | null } {
+  const inner = raw
+    .replace(/^\/\*\*/, '')
+    .replace(/\*\/$/, '')
+    .split('\n')
+    .map(l => l.replace(/^\s*\*?\s?/, '').replace(/\s+$/, ''))
+  const params = new Map<string, string>()
+  let returns: string | null = null
+  let sink: ((text: string) => void) | null = null
+  for (const line of inner) {
+    const param = /^@param\s+(\[?[\w$]+\]?)\s*(?:[-—–]\s*)?(.*)$/.exec(line)
+    if (param) {
+      const name = (param[1] ?? '').replace(/^\[|\]$/g, '')
+      let acc = param[2] ?? ''
+      params.set(name, acc)
+      sink = (t) => { acc = acc ? `${acc} ${t}` : t; params.set(name, acc) }
+      continue
+    }
+    const ret = /^@returns?(?:\s+[-—–]?\s*(.*))?$/.exec(line)
+    if (ret) {
+      let acc = ret[1] ?? ''
+      returns = acc
+      sink = (t) => { acc = acc ? `${acc} ${t}` : t; returns = acc }
+      continue
+    }
+    if (line.startsWith('@') || line.trim() === '') { sink = null; continue }
+    sink?.(line.trim())
+  }
+  return { params, returns }
+}
+
+/**
+ * Require a non-empty tag for each non-exempt identifier parameter, reject
+ * binding-pattern parameters, and reject stale tags. Exempt parameters may
+ * still be documented.
+ * @param where - the offender label violations open with, e.g. `event 'x' (file:1)`.
+ * @param apiKind - API kind used in binding-pattern diagnostics.
+ * @param parameters - the declaration's parameter list.
+ * @param tags - the parsed `@param` name→description map from parseTags.
+ * @param sf - source file used to render binding patterns.
+ * @param isExempt - parameters whose tag is optional, such as `this` or waterfall `next`.
+ * @param violations - the aggregate list violations append to.
+ */
+export function checkParams(
+  where: string,
+  apiKind: string,
+  parameters: readonly ts.ParameterDeclaration[],
+  tags: Map<string, string>,
+  sf: ts.SourceFile,
+  isExempt: (p: ts.ParameterDeclaration) => boolean,
+  violations: string[],
+): void {
+  for (const p of parameters) {
+    if (!ts.isIdentifier(p.name)) {
+      violations.push(`${where}: parameter '${p.name.getText(sf)}' is a binding pattern; the ${apiKind} API needs simple identifier parameters so @param can name them.`)
+      continue
+    }
+    if (isExempt(p)) continue
+    const desc = tags.get(p.name.text)
+    if (desc === undefined) violations.push(`${where} is missing @param ${p.name.text}.`)
+    else if (!desc.trim()) violations.push(`${where}: @param ${p.name.text} has an empty description.`)
+  }
+  for (const tag of tags.keys()) {
+    if (!parameters.some(p => ts.isIdentifier(p.name) && p.name.text === tag)) {
+      violations.push(`${where}: @param ${tag} does not match any parameter (stale tag?).`)
+    }
+  }
+}
+
+/**
+ * Check the `@returns` half of the completeness contract: a non-`void` / `Promise<void>`
+ * return needs a non-empty `@returns`, and the return type must be ANNOTATED — a pure-AST
+ * walk cannot classify an inferred return. Void returns may still carry an
+ * optional tag, for example to document resolution timing.
+ * @param where - the offender label violations open with.
+ * @param typeNode - the declared return type annotation, or undefined when inferred.
+ * @param returns - the parsed `@returns` description from parseTags (null when absent).
+ * @param sf - the source file (for rendering the annotation's text).
+ * @param violations - the aggregate list violations append to.
+ */
+export function checkReturns(
+  where: string,
+  typeNode: ts.TypeNode | undefined,
+  returns: string | null,
+  sf: ts.SourceFile,
+  violations: string[],
+): void {
+  if (typeNode === undefined) {
+    violations.push(`${where} has no return type annotation; annotate it explicitly so the gate can classify the result.`)
+    return
+  }
+  const rt = typeNode.getText(sf).replace(/\s+/g, ' ')
+  if (/^(void|Promise<void>)$/.test(rt)) return
+  if (returns === null) violations.push(`${where} is missing @returns (return type: ${rt}).`)
+  else if (!returns.trim()) violations.push(`${where}: @returns has an empty description.`)
+}
+
+/**
+ * Throw one aggregate error for every completeness violation a walk collected.
+ * Aggregation (vs failing fast) is deliberate: a remediation pass sees the
+ * whole list at once instead of replaying the gate once per offender.
+ * @param gate - the reporting gate's name, prefixed to the error message.
+ * @param violations - the collected violation lines; no-op when empty.
+ */
+export function reportViolations(gate: string, violations: string[]): void {
+  if (violations.length === 0) return
+  throw new Error(
+    `${gate}: ${violations.length} JSDoc completeness violation(s) (see AGENTS.md):\n`
+    + violations.map(v => `  ${v}`).join('\n'),
+  )
+}

scripts/lint-rule-fingerprint.spec.ts

@@ -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
+// snapshot; they do not re-evaluate that deleted baseline or track its preset.
+const profiles = {
+  source: {
+    count: 89,
+    indexes: [0, 1, 4, 5],
+    sha256: '3e8b8455827254d6da59afb803d30f062b9fe1264b4df75ce4c8cd6e742b93dd',
+  },
+  example: {
+    count: 88,
+    indexes: [0, 1, 2, 4, 5],
+    sha256: 'e2b944c028ef1971302d47b2eb0e95c05e740623c7cbaebb4b1312dbf73bf156',
+  },
+  test: {
+    count: 84,
+    indexes: [0, 3, 4, 5],
+    sha256: '7e4e1ed0cfca06ac94eeb26081195b5f753e7527775d5f5b95ccfefac9d2b137',
+  },
+} 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 every override field', () => {
+    expect(overrides).toHaveLength(9)
+  })
+
+  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)
+  })
+})

scripts/locale-dictionary-parity.spec.ts

@@ -0,0 +1,308 @@
+/**
+ * Gate for the invariant `FALLBACK_LOCALE` rests on: every shipped dictionary
+ * declares the same keys in `zh` and `en`.
+ *
+ * The locale runtime resolves a key through the active locale, then through
+ * the single fallback locale (`en`), then surfaces the key itself. With
+ * symmetric dictionaries that middle step always resolves, so one constant can
+ * serve as both the opening locale and the dictionary fallback. A key added to
+ * only one side breaks that: a reader of the other language sees a bare key
+ * such as `list.aria` instead of text. This gate fails on the asymmetry rather
+ * than waiting for the bare key to reach a UI.
+ *
+ * Discovery is deliberately broad, because a gate that silently narrows is
+ * worse than no gate. It sweeps every workspace package (not just
+ * `packages/client`), reads dictionaries wherever they are declared —
+ * `locales.ts`, a `locales/` directory, or inline in the plugin body — and
+ * pairs `zh`/`en` across sibling files as well as within one module. A `zh`
+ * dictionary whose `en` counterpart cannot be found anywhere is an error, not
+ * a skip.
+ */
+
+import type { Dirent } from 'node:fs'
+import { readdirSync, readFileSync } from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import ts from 'typescript'
+import { describe, expect, it } from 'vitest'
+
+const root = fileURLToPath(new URL('..', import.meta.url))
+
+/** Repo-relative path with `/` separators, so messages and suffix tests match on every OS. */
+function relative(file: string): string {
+  return file.slice(root.length).replaceAll('\\', '/')
+}
+
+/** Every `.ts` source file under each workspace package's `src`, excluding declarations. */
+function sourceFiles(): string[] {
+  const files: string[] = []
+  const packagesRoot = resolve(root, 'packages')
+  for (const group of directories(packagesRoot)) {
+    for (const pkg of directories(resolve(packagesRoot, group))) {
+      walk(resolve(packagesRoot, group, pkg, 'src'), files)
+    }
+  }
+  return files.sort()
+}
+
+/** Immediate subdirectory names, or none when the path is not a directory. */
+function directories(dir: string): string[] {
+  return readEntries(dir).filter(entry => entry.isDirectory()).map(entry => entry.name)
+}
+
+/**
+ * Directory entries, treating only a genuinely absent directory as empty.
+ * Any other failure (`EACCES`, I/O) rethrows: silently reading it as "absent"
+ * would narrow the sweep and let the gate pass while checking less.
+ * @param dir - absolute directory path.
+ * @returns entries, or none when the directory does not exist.
+ */
+function readEntries(dir: string): Dirent[] {
+  try {
+    return readdirSync(dir, { withFileTypes: true })
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return []
+    throw error
+  }
+}
+
+function walk(dir: string, out: string[]): void {
+  for (const entry of readEntries(dir)) {
+    const full = resolve(dir, entry.name)
+    if (entry.isDirectory()) walk(full, out)
+    else if (entry.name.endsWith('.ts') && !entry.name.endsWith('.d.ts')) out.push(full)
+  }
+}
+
+/** One discovered dictionary: which file and export name declared it. */
+interface Dictionary {
+  /** Repo-relative declaring file. */
+  file: string
+  /** Export name, or the registration site for an inline literal. */
+  name: string
+  /** Declared keys, sorted. */
+  keys: string[]
+}
+
+/**
+ * Keys of every top-level `export const <name> = { ... }` object literal whose
+ * name identifies a locale dictionary, plus inline `register(ns, locale, {...})`
+ * literals. Read from the AST so the gate never executes package code.
+ * @param file - absolute path of a candidate module.
+ * @returns discovered dictionaries, keyed by locale-bearing name.
+ */
+function dictionariesIn(file: string): Dictionary[] {
+  const text = readFileSync(file, 'utf8')
+  // Cheap pre-filter: parsing every package source is wasteful. The pattern
+  // must admit every shape `localeOf` accepts, or a file would be skipped
+  // before parsing — the silent narrowing this gate exists to prevent. A bare
+  // `\b(zh|en)\b` misses `zhSettings`/`accessZh`, because `\b` does not hold
+  // between `h` and an uppercase letter.
+  if (!/\b(zh|en)\b|\b(zh|en)[A-Z]|(Zh|En)\b/.test(text)) return []
+  const source = ts.createSourceFile(file, text, ts.ScriptTarget.ESNext, true)
+  const found: Dictionary[] = []
+  const rel = relative(file)
+
+  // Module-scope variable declarations, keyed by name. A 3-arg
+  // `register(NS, 'zh'|'en', dict)` whose third argument is an identifier —
+  // e.g. a local dictionary variable rather than an inline literal — resolves
+  // through here so the gate still verifies its symmetry.
+  const moduleConsts = new Map<string, ts.Expression>()
+  for (const statement of source.statements) {
+    if (!ts.isVariableStatement(statement)) continue
+    for (const decl of statement.declarationList.declarations) {
+      if (ts.isIdentifier(decl.name) && decl.initializer !== undefined) {
+        moduleConsts.set(decl.name.text, decl.initializer)
+      }
+    }
+  }
+
+  for (const statement of source.statements) {
+    if (!ts.isVariableStatement(statement)) continue
+    if (statement.modifiers?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) !== true) continue
+    for (const decl of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(decl.name)) continue
+      const literal = unwrap(decl.initializer)
+      if (literal === undefined || !ts.isObjectLiteralExpression(literal)) continue
+      if (localeOf(decl.name.text) === undefined) continue
+      found.push({ file: rel, name: decl.name.text, keys: keysOf(literal) })
+    }
+  }
+
+  // A 3-arg `register(ns, 'zh'|'en', dict)` call whose dictionary argument we
+  // cannot turn into an object literal. We refuse instead of skipping: a
+  // registration we cannot measure is exactly the silent narrowing this gate
+  // exists to catch.
+  const refuse = (ns: string, tag: string, why: string): never => {
+    throw new Error(`cannot verify register('${ns}', '${tag}', ...) in ${rel}: ${why}`)
+  }
+
+  // Inline registrations, two shapes. A `[['zh', {...}], ['en', {...}]]` pair
+  // handed to a registration loop keys off the enclosing array; separate
+  // `register(NS, 'zh', {...})` / `register(NS, 'en', {...})` calls key off the
+  // namespace argument, so the two calls pair with each other.
+  const visit = (node: ts.Node): void => {
+    if (ts.isCallExpression(node)) {
+      const callee = node.expression
+      const name = ts.isPropertyAccessExpression(callee)
+        ? callee.name.text
+        : ts.isIdentifier(callee) && callee.text === 'register' ? 'register' : undefined
+      if (name === 'register' && node.arguments.length >= 3) {
+        const [ns, tag, dict] = node.arguments
+        if (ns === undefined || tag === undefined || !ts.isStringLiteral(tag)) return
+        if (tag.text !== 'zh' && tag.text !== 'en') return
+        const raw = unwrap(dict)
+        const literal = raw !== undefined && ts.isIdentifier(raw)
+          ? (() => {
+            const resolved = moduleConsts.get(raw.text)
+            return resolved === undefined ? undefined : unwrap(resolved)
+          })()
+          : raw
+        const why = raw !== undefined && ts.isIdentifier(raw)
+          ? `third argument ${raw.text} does not resolve to an inline or module-scope object literal`
+          : 'third argument is neither an object literal nor a resolvable dictionary variable'
+        if (literal === undefined || !ts.isObjectLiteralExpression(literal)) {
+          // The dictionary argument must resolve to an object literal; the
+          // gate refuses rather than skips, so the symmetry it verifies never
+          // silently narrows.
+          refuse(ns.getText(source), tag.text, why)
+        }
+        const dictionary: ts.ObjectLiteralExpression = literal as ts.ObjectLiteralExpression
+        // The namespace expression's source text identifies the pair, so the
+        // zh and en calls for one namespace meet and calls for different
+        // namespaces stay apart.
+        found.push({ file: rel, name: `${tag.text}@register:${ns.getText(source)}`, keys: keysOf(dictionary) })
+      }
+    }
+    if (ts.isArrayLiteralExpression(node) && node.elements.length === 2) {
+      const site = source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1
+      for (const element of node.elements) {
+        if (!ts.isArrayLiteralExpression(element) || element.elements.length !== 2) continue
+        const [tag, dict] = element.elements
+        const literal = unwrap(dict)
+        if (tag === undefined || !ts.isStringLiteral(tag)) continue
+        if (literal === undefined || !ts.isObjectLiteralExpression(literal)) continue
+        if (tag.text !== 'zh' && tag.text !== 'en') continue
+        found.push({ file: rel, name: `${tag.text}@inline:${site}`, keys: keysOf(literal) })
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(source)
+  return found
+}
+
+/** Declared property names of an object literal, sorted. */
+function keysOf(literal: ts.ObjectLiteralExpression): string[] {
+  const keys: string[] = []
+  for (const prop of literal.properties) {
+    if (!ts.isPropertyAssignment(prop)) continue
+    if (ts.isIdentifier(prop.name) || ts.isStringLiteral(prop.name)) keys.push(prop.name.text)
+  }
+  return keys.sort()
+}
+
+/** Look through `satisfies`/`as`/parenthesized wrappers to the literal. */
+function unwrap(node: ts.Expression | undefined): ts.Expression | undefined {
+  let current = node
+  while (
+    current !== undefined
+    && (ts.isSatisfiesExpression(current) || ts.isAsExpression(current) || ts.isParenthesizedExpression(current))
+  ) {
+    current = current.expression
+  }
+  return current
+}
+
+/**
+ * The locale a dictionary name declares, and the namespace-ish remainder that
+ * identifies which pair it belongs to. `zh`/`en`, `zhSettings`/`enSettings`,
+ * and `settingsZh`/`settingsEn` are the shapes this repo uses. A name-prefix
+ * shape requires an uppercase ASCII letter at the third position (`[A-Z]`),
+ * matching the admission of the cheap pre-filter, so `zh2Foo`/`zh_probe`
+ * cannot be treated as dictionaries in one place and skipped in another.
+ * @param name - export name or synthetic inline name.
+ * @returns locale plus pair key, or undefined when the name names no locale.
+ */
+function localeOf(name: string): { locale: 'zh' | 'en'; pair: string } | undefined {
+  for (const locale of ['zh', 'en'] as const) {
+    const other = locale === 'zh' ? 'Zh' : 'En'
+    if (name === locale) return { locale, pair: '' }
+    // Synthetic names for inline shapes carry their own pair key after the
+    // first ':' (the enclosing array's line, or the namespace expression).
+    if (name.startsWith(`${locale}@`)) return { locale, pair: name.slice(name.indexOf(':')) }
+    if (name.startsWith(locale) && name.length > 2 && /[A-Z]/.test(name[2] ?? '')) {
+      return { locale, pair: name.slice(2) }
+    }
+    if (name.endsWith(other)) return { locale, pair: name.slice(0, -2) }
+  }
+  return undefined
+}
+
+describe('shipped locale dictionaries', () => {
+  it('declares the same keys in zh and en, so the single fallback locale always resolves', () => {
+    const files = sourceFiles()
+    // Guard the discovery itself: an empty or narrowed sweep would pass every
+    // assertion below while checking nothing.
+    expect(files.length).toBeGreaterThan(500)
+
+    // Pair within a file first; a dictionary whose counterpart is not in the
+    // same module then pairs with a sibling in the same directory. Both shapes
+    // ship here: `locales/settings.ts` exports zh+en together, while
+    // `locales/zh.ts` + `locales/en.ts` split the common pair across files.
+    const perFile = new Map<string, Dictionary[]>()
+    for (const file of files) {
+      const dicts = dictionariesIn(file)
+      if (dicts.length > 0) perFile.set(relative(file), dicts)
+    }
+
+    const groups = new Map<string, Map<'zh' | 'en', Dictionary>>()
+    const place = (key: string, locale: 'zh' | 'en', dict: Dictionary): void => {
+      const slot = groups.get(key) ?? new Map<'zh' | 'en', Dictionary>()
+      if (slot.has(locale)) {
+        throw new Error(`two ${locale} dictionaries claim pair ${key}: ${slot.get(locale)?.file} and ${dict.file}`)
+      }
+      slot.set(locale, dict)
+      groups.set(key, slot)
+    }
+
+    for (const [rel, dicts] of perFile) {
+      for (const dict of dicts) {
+        const parsed = localeOf(dict.name)
+        if (parsed === undefined) continue
+        const sameFileCounterpart = dicts.some((other) => {
+          const otherParsed = localeOf(other.name)
+          return otherParsed !== undefined
+            && otherParsed.pair === parsed.pair
+            && otherParsed.locale !== parsed.locale
+        })
+        // Same-file pairs key by file so two pairs in one directory stay
+        // distinct; split pairs key by directory so siblings meet.
+        const key = sameFileCounterpart ? `${rel}::${parsed.pair}` : `${dirname(rel)}::${parsed.pair}`
+        place(key, parsed.locale, dict)
+      }
+    }
+
+    const problems: string[] = []
+    let comparedPairs = 0
+    for (const [key, slot] of [...groups].sort()) {
+      const zh = slot.get('zh')
+      const en = slot.get('en')
+      if (zh === undefined || en === undefined) {
+        const present = zh ?? en
+        problems.push(`${present?.file} declares ${present?.name} with no counterpart for pair ${key}`)
+        continue
+      }
+      comparedPairs++
+      const zhOnly = zh.keys.filter(k => !en.keys.includes(k))
+      const enOnly = en.keys.filter(k => !zh.keys.includes(k))
+      if (zhOnly.length > 0) problems.push(`${zh.file} ${zh.name} has keys absent from ${en.name}: ${zhOnly.join(', ')}`)
+      if (enOnly.length > 0) problems.push(`${en.file} ${en.name} has keys absent from ${zh.name}: ${enOnly.join(', ')}`)
+    }
+
+    // The shipped dictionary count only grows; a collapse means discovery or
+    // pairing broke, which would hide real asymmetry.
+    expect(comparedPairs).toBeGreaterThan(25)
+    expect(problems).toEqual([])
+  })
+})

scripts/merge-translation-pairing-driver.sh

@@ -0,0 +1,35 @@
+#!/bin/sh
+
+if [ "$#" -ne 4 ]; then
+  echo 'merge-translation-pairing: expected <ancestor> <current> <other> <repository-path>' >&2
+  exit 129
+fi
+
+ancestor_path=$1
+current_path=$2
+other_path=$3
+meta_path=$4
+driver_directory=$(CDPATH= cd -P "$(dirname "$0")" && pwd) || exit 129
+driver_path=$driver_directory/merge-translation-pairing.ts
+
+if command -v node >/dev/null 2>&1 \
+  && node --import tsx/esm "$driver_path" --probe >/dev/null 2>&1; then
+  exec node --import tsx/esm "$driver_path" \
+    "$ancestor_path" "$current_path" "$other_path" "$meta_path"
+fi
+
+echo "merge-translation-pairing: runtime is unavailable; leaving an ordinary text conflict in $meta_path" >&2
+git merge-file \
+  -L "$meta_path:current" \
+  -L "$meta_path:ancestor" \
+  -L "$meta_path:other" \
+  -- "$current_path" "$ancestor_path" "$other_path"
+fallback_status=$?
+echo 'merge-translation-pairing: restore Node dependencies, then rerun the merge or `pnpm run resolve-translation-pairing-conflicts`; use `git merge --abort` to cancel' >&2
+
+# A clean text merge is still unverified pairing metadata, so the driver must
+# leave Git's index stages unresolved until the repository-aware resolver runs.
+if [ "$fallback_status" -gt 127 ]; then
+  exit "$fallback_status"
+fi
+exit 1

scripts/migrate-packed-session-fixtures.ts

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * Temporary branch-convergence command for canonical projected session fixtures.
+ *
+ * @see ../.agents/notes/proposed/process/2026-07-26-remove-packed-session-fixture-migrator.md
+ */
+
+import { writeFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { inspectSessionFixtureLayouts } from './session-fixture-layout.ts'
+
+if (process.argv.length > 2) throw new Error('migrate:packed-session-fixtures takes no arguments')
+
+const root = resolve(import.meta.dirname, '..')
+const fixtures = inspectSessionFixtureLayouts(root)
+const changed = fixtures.filter(fixture => fixture.source !== fixture.canonical)
+for (const fixture of changed) {
+  writeFileSync(resolve(root, fixture.path), fixture.canonical)
+  console.log(fixture.path)
+}
+console.log(`session snapshot fixtures: ${changed.length} rewritten, ${fixtures.length} inspected`)

scripts/package-invariants.ts

@@ -0,0 +1,418 @@
+/**
+ * Package-invariant companion discovery and structural checks.
+ * The runtime registry stays product-independent; this gate keeps each
+ * published companion complete without requiring synthetic empty companions.
+ */
+
+import { existsSync, globSync, readFileSync } from 'node:fs'
+import { dirname, relative, resolve, sep } from 'node:path'
+import ts from 'typescript'
+import { usesFlattenedPackageDependencies } from './package-dependency-policy.ts'
+
+/** Package README sentence that records why an invariant companion is omitted. */
+const OMITTED_COMPANION_REASON = /No (?:(?:runtime )?invariant )?companion is published(?: because|[.:;—])\s+\S/i
+
+interface PackageManifest {
+  name?: string
+  dsh?: unknown
+  exports?: Record<string, { types?: string; default?: string } | string | null | undefined>
+  files?: string[]
+  peerDependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+}
+
+/** One package and the files participating in its invariant publication rules. */
+export interface PackageInvariantOwner {
+  readonly dir: string
+  readonly manifestPath: string
+  readonly sourcePath: string
+  readonly packageName: string
+}
+
+/** One gate violation with a repo-relative owner path. */
+export interface PackageInvariantViolation {
+  readonly path: string
+  readonly message: string
+}
+
+/** Discover packages that own an invariant companion. */
+export function packageInvariantOwners(root: string): PackageInvariantOwner[] {
+  return packageInvariantPackages(root)
+    .filter(owner => existsSync(resolve(root, owner.sourcePath)))
+}
+
+/** Discover every package under the repository package tree. */
+function packageInvariantPackages(root: string): PackageInvariantOwner[] {
+  return globSync('packages/*/*/package.json', { cwd: root })
+    .map(path => path.split(sep).join('/'))
+    .sort()
+    .map((manifestPath) => {
+      const manifest = readManifest(resolve(root, manifestPath))
+      if (manifest.name === undefined || manifest.name === '') {
+        throw new Error(`${manifestPath}: package invariant owner must declare a package name`)
+      }
+      const dir = dirname(manifestPath)
+      return {
+        dir,
+        manifestPath,
+        sourcePath: `${dir}/src/invariant.ts`,
+        packageName: manifest.name,
+      }
+    })
+}
+
+/** Return all violations of the package-invariant companion rules. */
+export function collectPackageInvariantViolations(root: string): PackageInvariantViolation[] {
+  const violations: PackageInvariantViolation[] = []
+  for (const owner of packageInvariantPackages(root)) {
+    const manifest = readManifest(resolve(root, owner.manifestPath))
+    const hasCompanion = existsSync(resolve(root, owner.sourcePath))
+    checkManifest(owner, manifest, hasCompanion, violations)
+    checkBuild(owner, root, hasCompanion, violations)
+    if (hasCompanion) {
+      checkSource(owner, root, violations)
+    } else {
+      checkOmissionReason(owner, root, violations)
+    }
+  }
+  return violations
+}
+
+function readManifest(path: string): PackageManifest {
+  return JSON.parse(readFileSync(path, 'utf8')) as PackageManifest
+}
+
+function addViolation(
+  violations: PackageInvariantViolation[],
+  path: string,
+  message: string,
+): void {
+  violations.push({ path, message })
+}
+
+function checkManifest(
+  owner: PackageInvariantOwner,
+  manifest: PackageManifest,
+  hasCompanion: boolean,
+  violations: PackageInvariantViolation[],
+): void {
+  const invariantExport = manifest.exports?.['./invariant']
+  if (!hasCompanion) {
+    if (invariantExport !== undefined) {
+      addViolation(
+        violations,
+        owner.manifestPath,
+        'exports["./invariant"] must be omitted when src/invariant.ts is absent',
+      )
+    }
+    if (manifest.files?.includes('lib/invariant.js')) {
+      addViolation(
+        violations,
+        owner.manifestPath,
+        'files must omit lib/invariant.js when src/invariant.ts is absent',
+      )
+    }
+    return
+  }
+  if (typeof invariantExport !== 'object'
+    || invariantExport === null
+    || invariantExport.types !== './lib/types/invariant.d.ts'
+    || invariantExport.default !== './lib/invariant.js') {
+    addViolation(
+      violations,
+      owner.manifestPath,
+      'exports["./invariant"] must target ./lib/types/invariant.d.ts and ./lib/invariant.js',
+    )
+  }
+  if (!manifest.files?.includes('lib/invariant.js')) {
+    addViolation(violations, owner.manifestPath, 'files must publish lib/invariant.js')
+  }
+  if (owner.packageName === '@deepseek-ai/dsh-invariants') return
+  const developmentOnlyInvariant = usesFlattenedPackageDependencies(
+    owner.manifestPath,
+    owner.packageName,
+    manifest.dsh,
+  )
+  const expectedRange = 'workspace:^'
+  const peerRange = manifest.peerDependencies?.['@deepseek-ai/dsh-invariants']
+  if (developmentOnlyInvariant ? peerRange !== undefined : peerRange !== expectedRange) {
+    addViolation(violations, owner.manifestPath, developmentOnlyInvariant
+      ? '@deepseek-ai/dsh-invariants must not be a peerDependency under this package dependency policy'
+      : '@deepseek-ai/dsh-invariants must be a workspace:^ peerDependency')
+  }
+  if (manifest.devDependencies?.['@deepseek-ai/dsh-invariants'] !== expectedRange) {
+    addViolation(
+      violations,
+      owner.manifestPath,
+      `@deepseek-ai/dsh-invariants must be a ${expectedRange} devDependency`,
+    )
+  }
+}
+
+function checkBuild(
+  owner: PackageInvariantOwner,
+  root: string,
+  hasCompanion: boolean,
+  violations: PackageInvariantViolation[],
+): void {
+  const tsconfigPath = `${owner.dir}/tsconfig.json`
+  if (hasCompanion
+    && owner.packageName !== '@deepseek-ai/dsh-invariants'
+    && !projectReferencesInvariants(root, owner.dir, tsconfigPath)) {
+    addViolation(
+      violations,
+      tsconfigPath,
+      'TypeScript project references must include ../../runtime-diagnostics/invariants',
+    )
+  } else if (!hasCompanion && projectReferencesInvariants(root, owner.dir, tsconfigPath)) {
+    addViolation(
+      violations,
+      tsconfigPath,
+      'TypeScript project references must omit ../../runtime-diagnostics/invariants when src/invariant.ts is absent',
+    )
+  }
+
+  const configPath = `${owner.dir}/tsdown.config.ts`
+  if (!existsSync(resolve(root, configPath))) return
+  const source = readFileSync(resolve(root, configPath), 'utf8')
+  const bundlesCompanion = source.includes('lib/types/invariant.js')
+  if (hasCompanion && !bundlesCompanion) {
+    addViolation(violations, configPath, 'package build override must bundle lib/types/invariant.js')
+  } else if (!hasCompanion && bundlesCompanion) {
+    addViolation(
+      violations,
+      configPath,
+      'package build override must omit lib/types/invariant.js when src/invariant.ts is absent',
+    )
+  }
+}
+
+function checkOmissionReason(
+  owner: PackageInvariantOwner,
+  root: string,
+  violations: PackageInvariantViolation[],
+): void {
+  const readmePath = `${owner.dir}/README.md`
+  const absolutePath = resolve(root, readmePath)
+  if (!existsSync(absolutePath) || !OMITTED_COMPANION_REASON.test(readFileSync(absolutePath, 'utf8'))) {
+    addViolation(
+      violations,
+      readmePath,
+      'omitted companion requires a README "No ... companion is published" reason sentence',
+    )
+  }
+}
+
+function projectReferencesInvariants(root: string, ownerDir: string, entryPath: string): boolean {
+  const ownerRoot = resolve(root, ownerDir)
+  const target = resolve(root, 'packages/runtime-diagnostics/invariants')
+  const pending = [resolve(root, entryPath)]
+  const visited = new Set<string>()
+  while (pending.length > 0) {
+    const configPath = pending.pop()
+    if (configPath === undefined) break
+    if (visited.has(configPath)) continue
+    visited.add(configPath)
+    const config = JSON.parse(readFileSync(configPath, 'utf8')) as {
+      references?: Array<{ path?: string }>
+    }
+    for (const reference of config.references ?? []) {
+      if (reference.path === undefined) continue
+      const referenced = resolve(dirname(configPath), reference.path)
+      if (referenced === target) return true
+      if (!referenced.startsWith(`${ownerRoot}${sep}`)) continue
+      const childConfig = referenced.endsWith('.json') ? referenced : resolve(referenced, 'tsconfig.json')
+      if (existsSync(childConfig)) pending.push(childConfig)
+    }
+  }
+  return false
+}
+
+function checkSource(
+  owner: PackageInvariantOwner,
+  root: string,
+  violations: PackageInvariantViolation[],
+): void {
+  const absolutePath = resolve(root, owner.sourcePath)
+  const sourceText = readFileSync(absolutePath, 'utf8')
+  if (sourceText.includes('@generated')) {
+    addViolation(
+      violations,
+      owner.sourcePath,
+      'invariant companions must be hand-owned and may not carry @generated markers',
+    )
+  }
+
+  const sourceFile = ts.createSourceFile(
+    absolutePath,
+    sourceText,
+    ts.ScriptTarget.Latest,
+    true,
+    ts.ScriptKind.TS,
+  )
+  const constants = topLevelStringConstants(sourceFile)
+  const registrations: string[] = []
+  const unresolved: number[] = []
+  const mismatchedInstallers: number[] = []
+  const visit = (node: ts.Node): void => {
+    if (ts.isCallExpression(node) && isInvariantRegistration(node.expression)) {
+      const line = sourceFile.getLineAndCharacterOfPosition(node.getStart()).line + 1
+      const argument = node.arguments[0]
+      const packageName = argument === undefined ? undefined : stringValue(argument, constants)
+      if (packageName === undefined) unresolved.push(line)
+      else registrations.push(packageName)
+      const installer = node.arguments[1]
+      if (installer === undefined || !ts.isIdentifier(installer) || installer.text !== 'install') {
+        mismatchedInstallers.push(line)
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(sourceFile)
+
+  for (const line of unresolved) {
+    addViolation(
+      violations,
+      owner.sourcePath,
+      `line ${line}: ctx.invariants.register package name must resolve to a local string constant`,
+    )
+  }
+  for (const line of mismatchedInstallers) {
+    addViolation(
+      violations,
+      owner.sourcePath,
+      `line ${line}: ctx.invariants.register must use the checked local install function`,
+    )
+  }
+  if (registrations.length !== 1 || registrations[0] !== owner.packageName) {
+    addViolation(
+      violations,
+      owner.sourcePath,
+      `must register exactly its own package name ${JSON.stringify(owner.packageName)}; saw ${JSON.stringify(registrations)}`,
+    )
+  }
+  for (const exportedName of ['name', 'inject', 'apply']) {
+    if (!hasNamedExport(sourceFile, exportedName)) {
+      addViolation(violations, owner.sourcePath, `must named-export ${exportedName}`)
+    }
+  }
+  if (hasDefaultExport(sourceFile)) {
+    addViolation(violations, owner.sourcePath, 'must not default-export; Loader must retain the companion namespace')
+  }
+  checkInstaller(owner, sourceFile, violations)
+}
+
+function checkInstaller(
+  owner: PackageInvariantOwner,
+  sourceFile: ts.SourceFile,
+  violations: PackageInvariantViolation[],
+): void {
+  let initializer: ts.Expression | undefined
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement)) continue
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name)
+        && declaration.name.text === 'install'
+        && declaration.initializer !== undefined) {
+        initializer = declaration.initializer
+      }
+    }
+  }
+  const installer = initializer === undefined ? undefined : installerFunction(initializer)
+  if (installer === undefined) {
+    addViolation(violations, owner.sourcePath, 'must declare a local install function for package-owned checks')
+    return
+  }
+  if (ts.isBlock(installer.body) && installer.body.statements.length === 0) {
+    addViolation(
+      violations,
+      owner.sourcePath,
+      'empty install function is unnecessary; omit the companion and its publication wiring',
+    )
+    return
+  }
+  const reporter = installer.parameters[1]?.name
+  if (reporter === undefined || !ts.isIdentifier(reporter)) {
+    addViolation(violations, owner.sourcePath, 'install function must accept the bound failure reporter as its second parameter')
+    return
+  }
+  if (!usesIdentifier(installer.body, reporter.text)) {
+    addViolation(violations, owner.sourcePath, 'install function must use its bound failure reporter')
+  }
+}
+
+function usesIdentifier(node: ts.Node, name: string): boolean {
+  return ts.isIdentifier(node) && node.text === name
+    || node.getChildren().some(child => usesIdentifier(child, name))
+}
+
+function installerFunction(
+  initializer: ts.Expression,
+): ts.ArrowFunction | ts.FunctionExpression | undefined {
+  if (ts.isArrowFunction(initializer) || ts.isFunctionExpression(initializer)) return initializer
+  if (ts.isCallExpression(initializer)
+    && ts.isPropertyAccessExpression(initializer.expression)
+    && ts.isIdentifier(initializer.expression.expression)
+    && initializer.expression.expression.text === 'Object'
+    && initializer.expression.name.text === 'assign') {
+    const target = initializer.arguments[0]
+    if (target !== undefined && (ts.isArrowFunction(target) || ts.isFunctionExpression(target))) return target
+  }
+  return undefined
+}
+
+function topLevelStringConstants(sourceFile: ts.SourceFile): ReadonlyMap<string, string> {
+  const constants = new Map<string, string>()
+  for (const statement of sourceFile.statements) {
+    if (!ts.isVariableStatement(statement)) continue
+    for (const declaration of statement.declarationList.declarations) {
+      if (!ts.isIdentifier(declaration.name) || declaration.initializer === undefined) continue
+      const value = stringValue(declaration.initializer, constants)
+      if (value !== undefined) constants.set(declaration.name.text, value)
+    }
+  }
+  return constants
+}
+
+function stringValue(node: ts.Expression, constants: ReadonlyMap<string, string>): string | undefined {
+  if (ts.isStringLiteral(node) || ts.isNoSubstitutionTemplateLiteral(node)) return node.text
+  if (ts.isIdentifier(node)) return constants.get(node.text)
+  return undefined
+}
+
+function isInvariantRegistration(expression: ts.LeftHandSideExpression): boolean {
+  return ts.isPropertyAccessExpression(expression)
+    && expression.name.text === 'register'
+    && ts.isPropertyAccessExpression(expression.expression)
+    && expression.expression.name.text === 'invariants'
+}
+
+function hasNamedExport(sourceFile: ts.SourceFile, name: string): boolean {
+  return sourceFile.statements.some((statement) => {
+    if (!ts.isVariableStatement(statement)
+      || !statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)) return false
+    return statement.declarationList.declarations.some(declaration => ts.isIdentifier(declaration.name) && declaration.name.text === name)
+  })
+}
+
+function hasDefaultExport(sourceFile: ts.SourceFile): boolean {
+  return sourceFile.statements.some((statement) => {
+    if (ts.isExportAssignment(statement)) return true
+    const modifiers = ts.canHaveModifiers(statement) ? ts.getModifiers(statement) : undefined
+    if (modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.DefaultKeyword)) return true
+    if (!ts.isExportDeclaration(statement) || statement.exportClause === undefined) return false
+    if (ts.isNamespaceExport(statement.exportClause)) {
+      return statement.exportClause.name.text === 'default'
+    }
+    return statement.exportClause.elements.some(element => element.name.text === 'default')
+  })
+}
+
+/** Format violations for the command-line gate. */
+export function formatPackageInvariantViolation(
+  root: string,
+  violation: PackageInvariantViolation,
+): string {
+  const path = resolve(root, violation.path)
+  return `${relative(root, path)}: ${violation.message}`
+}

scripts/paired-markdown-derivatives.spec.ts

@@ -0,0 +1,66 @@
+import { describe, expect, it } from 'vitest'
+import { partitionPairedMarkdownDerivatives } from './paired-markdown-derivatives.ts'
+
+interface Block {
+  doc: string
+  kind: string
+  code: string
+}
+
+const partition = (blocks: Block[]) => partitionPairedMarkdownDerivatives(
+  blocks,
+  block => block.doc,
+  block => `${block.kind}\0${block.code}`,
+)
+
+describe('partitionPairedMarkdownDerivatives', () => {
+  it('treats a complete byte-identical Chinese sequence as derivative', () => {
+    const english = [
+      { doc: 'docs/example.md', kind: 'ts', code: 'const one = 1' },
+      { doc: 'docs/example.md', kind: 'type-equiv', code: 'interface Example {}' },
+    ]
+    const chinese = english.map(block => ({ ...block, doc: 'docs/example.zh.md' }))
+    const unrelated = { doc: 'docs/other.md', kind: 'ts', code: 'const other = 2' }
+
+    expect(partition([...english, ...chinese, unrelated])).toEqual({
+      primary: [...english, unrelated],
+      derivatives: chinese,
+    })
+  })
+
+  it('keeps reordered, changed, partial, and orphan Chinese sequences primary', () => {
+    const sequence = (doc: string) => [
+      { doc, kind: 'ts', code: 'const one = 1' },
+      { doc, kind: 'ts', code: 'const two = 2' },
+    ]
+    const english = sequence('docs/example.md')
+    const changed = english.map((block, index) => ({
+      ...block,
+      doc: 'docs/example.zh.md',
+      code: index === 0 ? 'const one = 0' : block.code,
+    }))
+    const reorderedEnglish = sequence('docs/reordered.md')
+    const reordered = [...reorderedEnglish].reverse().map(block => ({ ...block, doc: 'docs/reordered.zh.md' }))
+    const partialEnglish = sequence('docs/partial.md')
+    const partial = [{ ...partialEnglish[0]!, doc: 'docs/partial.zh.md' }]
+    const orphan = [{ doc: 'docs/orphan.zh.md', kind: 'ts', code: 'const orphan = true' }]
+    const blocks = [
+      ...english,
+      ...changed,
+      ...reorderedEnglish,
+      ...reordered,
+      ...partialEnglish,
+      ...partial,
+      ...orphan,
+    ]
+
+    expect(partition(blocks)).toEqual({ primary: blocks, derivatives: [] })
+  })
+
+  it('requires the fence kind to match as well as the body', () => {
+    const english = { doc: 'docs/example.md', kind: 'type-equiv', code: 'interface Example {}' }
+    const chinese = { ...english, doc: 'docs/example.zh.md', kind: 'public-api' }
+
+    expect(partition([english, chinese])).toEqual({ primary: [english, chinese], derivatives: [] })
+  })
+})

scripts/persistence-catalog-text.ts

@@ -0,0 +1,43 @@
+/** Authored language pairs for generated persistence reference prose. */
+
+/** Language of a generated persistence reference. */
+export type PersistenceCatalogLocale = 'en' | 'zh'
+
+const english = {
+  title: 'Session Persistence Event Catalog',
+  intro: 'Every repository-declared durable Session event appears here with its source declaration and resolved types. The catalog covers the logical and physical headers, event envelopes, and every plugin declaration merge. See [Session](subsystems/session.md) for replay and [persistence](subsystems/persistence.md) for storage.',
+  generation: 'Run `pnpm run gen-persistence-catalog` to regenerate both catalog languages, their pairing record, the known-event module, and the machine schema inventory. `pnpm run verify-persistence-catalog` checks all generated files. Declaration fences preserve source JSDoc and type references; resolved definitions expose their transitive structure.',
+  envelopeIntro: 'The envelope carries `type`, `seq`, `time`, `data`, optional `ignorable`, and conditional `surfaceOp` / `sourceEventSeqs`. A **surface** event produces model history; a **log-only** event does not. The inventory covers this repository; external plugin types require their own declarations and are outside this catalog.',
+  envelope: 'Event envelope', events: 'Events', sources: 'Sources: ', source: 'Source: ', types: 'Types: ',
+  fingerprints: 'Persistence type fingerprints',
+  fingerprintsIntro: 'The [machine inventory](persistence-schema.json) contains every reachable normalized type and its SHA-256 digest. Root digests include referenced types. Comments, source locations, alias names, erased brands, readonly markers, and harmless field, union, or intersection reordering do not affect these fingerprints. Tuple order, property names, value types, and optionality do. Catalog text and source locations can still produce a diff when digests stay unchanged.',
+  historyIntro: 'The [format references](persistence-changes/historical-formats/README.md) cover every historical Session format. The [change records](persistence-changes/README.md) acknowledge exact transitions using snapshots kept in this tree. Follow the [review workflow](cookbook/reviewing-persistence-type-changes.md) to classify a change and record it. These checks cover declared type structure; opaque payload contents and behavior without type changes are outside their scope.',
+  rootColumns: '| Root | Kind | SHA-256 | Resolved type |',
+  definitions: 'Resolved persistence types',
+  definitionsIntro: 'Each definition appears once. References preserve sharing and recursion; the digest beside a definition includes its complete reachable structure. Source names and locations identify its declarations but are excluded from its digest.',
+  propertyColumns: '| Property | Presence | Type |', positionColumns: '| Position | Presence | Type |',
+  optional: 'optional', required: 'required', rest: 'rest', index: 'index signature',
+  emptyObject: 'Object with no declared properties.', arrayPrefix: 'Array of ', arraySuffix: '.',
+  oneOf: 'One of:', opaque: ' (opaque)', opaqueExplanation: ": the declaration does not expose the stored value's internal fields.",
+}
+
+const chinese: Record<keyof typeof english, string> = {
+  title: '会话持久化事件目录',
+  intro: '本目录列出仓库声明的每个持久化 Session 事件及其源码声明和解析类型，覆盖逻辑与物理 header、事件信封以及各插件的声明合并。回放规则参见 [Session](subsystems/session.zh.md)，存储规则参见[持久化](subsystems/persistence.zh.md)。',
+  generation: '运行 `pnpm run gen-persistence-catalog` 可重新生成目录的两种语言、配对记录、已知事件模块和机器 schema 目录。`pnpm run verify-persistence-catalog` 检查所有生成文件。声明围栏保留源码 JSDoc 和类型引用；解析后的定义展开其传递引用结构。',
+  envelopeIntro: '信封包含 `type`、`seq`、`time`、`data`、可选的 `ignorable` 以及条件字段 `surfaceOp` / `sourceEventSeqs`。**surface** 事件产生模型历史，**log-only** 事件不产生模型历史。目录覆盖本仓库；外部插件类型需要独立声明，不属于本目录。',
+  envelope: '事件信封', events: '事件', sources: '来源：', source: '来源：', types: '类型：',
+  fingerprints: '持久化类型指纹',
+  fingerprintsIntro: '[机器可读目录](persistence-schema.json)包含所有可达的规范化类型及其 SHA-256 摘要。根类型的摘要涵盖引用类型。注释、源码位置、别名、擦除的品牌标记、readonly 标记以及无语义变化的字段、联合类型或交叉类型重排不影响摘要；元组顺序、属性名称、值类型和可选性会影响摘要。摘要不变时，目录文本和源码位置仍可能产生 diff。',
+  historyIntro: '[格式参考](persistence-changes/historical-formats/README.zh.md)覆盖每个历史 Session 格式。[变更记录](persistence-changes/README.zh.md)通过保存在本源码树中的快照确认精确的类型转��。按照[评审流程](cookbook/reviewing-persistence-type-changes.zh.md)分类并记录变更。这些检查覆盖已声明的类型结构；不透明载荷的内部内容和未改变类型的行为变更不在检查范围内。',
+  rootColumns: '| 根类型 | 类别 | SHA-256 | 已解析类型 |',
+  definitions: '已解析的持久化类型',
+  definitionsIntro: '每个类型定义仅列出一次。引用保留共享和递归关系；定义旁的摘要涵盖其完整可达结构。源码名称和位置标识声明来源，但不参与摘要计算。',
+  propertyColumns: '| 属性 | 存在性 | 类型 |', positionColumns: '| 位置 | 存在性 | 类型 |',
+  optional: '可选', required: '必需', rest: '剩余项', index: '索引签名',
+  emptyObject: '无已声明属性的对象。', arrayPrefix: '', arraySuffix: ' 的数组。',
+  oneOf: '以下类型之一：', opaque: '（不透明）', opaqueExplanation: '：此声明未暴露存储值的内部字段。',
+}
+
+/** Complete translated prose; adding an English key requires its Chinese counterpart. */
+export const persistenceCatalogText = { en: english, zh: chinese }

scripts/persistence-changes.spec.ts

@@ -0,0 +1,611 @@
+/** Current-tree persistence history rejects uncovered and incorrectly acknowledged type changes. */
+
+import { spawnSync } from 'node:child_process'
+import { mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { canonicalizeSchema, schemaDigest } from './persistence-schema-model.ts'
+import type { PersistenceRoot, PersistenceSchemaInventory, SchemaNode, SchemaProperty } from './persistence-schema-model.ts'
+import { extractPersistenceSchema } from './persistence-schema.ts'
+import { persistenceCatalogArtifacts } from './gen-persistence-catalog.ts'
+import {
+  classifyPersistenceChange,
+  loadPersistenceHistory,
+  parseHistoricalPersistenceSnapshot,
+  parsePersistenceSnapshot,
+  runPersistenceChanges as executePersistenceChanges,
+  validatePersistenceHistory,
+  verifyPersistenceChanges,
+} from './persistence-changes.ts'
+import type { PersistenceChangeRecord, PersistenceHistoryEntry } from './persistence-changes.ts'
+
+function runPersistenceChanges(
+  args: readonly string[], root: string, extract: (root: string) => PersistenceSchemaInventory,
+): string {
+  return executePersistenceChanges(args, root, extract, (_root, current) => [{
+    path: 'docs/persistence-schema.json', content: JSON.stringify(current, null, 2) + '\n',
+  }])
+}
+
+function jsonResult(source: string): { ok: boolean; files: readonly string[] } {
+  return JSON.parse(source) as { ok: boolean; files: readonly string[] }
+}
+
+const AUTHORED_PROSE = {
+  en: { summary: 'Adds optional metadata.', compatibility: 'Readers may omit the metadata.', verification: 'The focused tests passed.' },
+  zh: { summary: '添加可选元数据。', compatibility: '读取方可省略元数据。', verification: '定向测试通过。' },
+}
+
+function proseFile(root: string): string {
+  const path = join(root, 'prose.json')
+  writeFileSync(path, JSON.stringify(AUTHORED_PROSE))
+  return path
+}
+
+const roots: string[] = []
+afterEach(() => { for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true }) })
+
+function fixture(): string {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-persistence-changes-'))
+  roots.push(root)
+  mkdirSync(join(root, 'docs/persistence-changes'), { recursive: true })
+  return root
+}
+
+type Shape = 'string' | 'number' | 'boolean' | { readonly [property: string]: Shape }
+
+function typeRoot(key: string, shape: Shape, version = 3): PersistenceRoot {
+  const nodes: SchemaNode[] = []
+  function add(shape: Shape): number {
+    const index = nodes.length
+    nodes.push({ kind: 'primitive', type: 'never' })
+    nodes[index] = typeof shape === 'string' ? { kind: 'primitive', type: shape } : {
+      kind: 'object', indices: [], properties: Object.entries(shape).map(([name, child]) => ({
+        name: name.replace(/\?$/u, ''), optional: name.endsWith('?'), type: add(child),
+      })),
+    }
+    return index
+  }
+  if (key === 'SessionHeader') {
+    const index = add(shape)
+    const node = nodes[index]!
+    if (node.kind !== 'object') throw new Error('header fixture requires an object')
+    nodes[index] = { ...node, properties: [...node.properties, { name: 'version', optional: false, type: nodes.length }] }
+    nodes.push({ kind: 'literal', value: version })
+  } else if (key.startsWith('event:')) {
+    add({ data: shape, type: 'string' })
+    const node = nodes[0]!
+    if (node.kind !== 'object') throw new Error('event fixture requires an object')
+    const type = node.properties.find(item => item.name === 'type')!.type
+    nodes[type] = { kind: 'literal', value: key.slice(6) }
+  } else add(shape)
+  const schema = canonicalizeSchema(nodes, 0)
+  return { key, kind: ['SessionHeader', 'JsonlHeaderLine'].includes(key) ? 'header' : key === 'SessionEventEnvelope' ? 'envelope' : 'event',
+    ...(key.startsWith('event:') ? { event: key.slice(6), surface: false } : {}), schema, digest: schemaDigest(schema) }
+}
+
+function inventory(eventShape: Shape = { value: 'string' }, version = 3): PersistenceSchemaInventory {
+  return { formatVersion: 1, types: [], roots: [typeRoot('SessionHeader', { id: 'string' }, version), typeRoot('SessionEventEnvelope', { type: 'string' }), typeRoot('event:example/value', eventShape), typeRoot('JsonlHeaderLine', { version: 'number' })] }
+}
+
+function entry(
+  id: string, schema: PersistenceSchemaInventory, previous: string | null,
+  baseline = false, decision: 'same-version' | 'version-bump' = 'same-version',
+): PersistenceHistoryEntry {
+  return {
+    record: { schemaVersion: 1, id, baseline, changes: schema.roots.map(root => ({
+      root: root.key, previous, after: root.digest, decision,
+    })) },
+    snapshot: schema,
+  }
+}
+
+const BASE_ID = '2026-09-11-baseline'
+const NEXT_ID = '2026-09-11-change'
+
+function historicalSurface(operation: 'required' | 'optional' | 'absent', event = 'example/value'): PersistenceSchemaInventory {
+  const nodes: SchemaNode[] = [
+    { kind: 'object', indices: [], properties: [
+      { name: 'type', type: 1, optional: false },
+      ...(operation === 'absent' ? [] : [{ name: 'surfaceOp', type: 2, optional: operation === 'optional' }]),
+    ] },
+    { kind: 'literal', value: event },
+    { kind: 'primitive', type: 'string' },
+  ]
+  const schema = canonicalizeSchema(nodes, 0)
+  return { formatVersion: 1, types: [], roots: [{
+    key: 'event:example/value', kind: 'event', event: 'example/value', surface: true, schema, digest: schemaDigest(schema),
+  }] }
+}
+
+describe('historical persistence snapshot parsing', () => {
+  it('preserves source paths and fingerprints in historical inventories', () => {
+    const snapshot = historicalSurface('required')
+    const root = snapshot.roots[0]!
+    const sources = ['packages/core/example/src/types.ts']
+    const complete = { ...snapshot, types: [{ schema: root.schema, digest: root.digest, names: ['Example'], sources }] }
+    expect(parseHistoricalPersistenceSnapshot(complete)).toEqual(complete)
+  })
+
+  it.each([':8', ':8:3', '#L8', '#L8-L12'])('rejects source coordinates %s only in historical inventories', (suffix) => {
+    const snapshot = historicalSurface('required')
+    const root = snapshot.roots[0]!
+    const sources = [`packages/core/example/src/types.ts${suffix}`]
+    const complete = { ...snapshot, types: [{ schema: root.schema, digest: root.digest, names: [], sources }] }
+    expect(() => parseHistoricalPersistenceSnapshot(complete)).toThrow('historical schema sources must omit line numbers')
+    expect(parsePersistenceSnapshot(complete)).toEqual(complete)
+  })
+
+  it('admits optional surface operations only through the historical parser', () => {
+    const snapshot = historicalSurface('optional')
+    expect(() => parsePersistenceSnapshot(snapshot)).toThrow('surface metadata')
+    expect(parseHistoricalPersistenceSnapshot(snapshot)).toEqual(snapshot)
+    expect(parsePersistenceSnapshot(historicalSurface('required'))).toEqual(historicalSurface('required'))
+  })
+
+  it('still rejects absent operations, mismatched event tags, and invalid roots', () => {
+    expect(() => parseHistoricalPersistenceSnapshot(historicalSurface('absent'))).toThrow('surface metadata')
+    expect(() => parseHistoricalPersistenceSnapshot(historicalSurface('optional', 'wrong/tag'))).toThrow('type does not match')
+    const snapshot = historicalSurface('optional')
+    expect(() => parseHistoricalPersistenceSnapshot({ ...snapshot, roots: snapshot.roots.map(root => ({ ...root, key: 'event:wrong/key' })) })).toThrow('invalid event root key')
+    expect(() => parseHistoricalPersistenceSnapshot({ ...snapshot, roots: snapshot.roots.map(root => ({ ...root, surface: false })) })).toThrow('surface metadata')
+  })
+
+  it('preserves graph and digest validation in historical mode', () => {
+    const snapshot = historicalSurface('optional')
+    expect(() => parseHistoricalPersistenceSnapshot({ ...snapshot, roots: snapshot.roots.map(root => ({ ...root, digest: 'f'.repeat(64) })) })).toThrow('digest mismatch')
+    expect(() => parseHistoricalPersistenceSnapshot({ ...snapshot, roots: snapshot.roots.map(root => ({ ...root, schema: { root: 0, nodes: [{ kind: 'array', element: 9 }] } })) })).toThrow('unknown schema node')
+  })
+})
+
+function onlyEvent(schema: PersistenceSchemaInventory): PersistenceSchemaInventory {
+  return { ...schema, roots: schema.roots.filter(root => root.kind === 'event') }
+}
+
+function finishDocuments(root: string, id: string): void {
+  for (const suffix of ['.md', '.zh.md']) {
+    const path = join(root, 'docs/persistence-changes', id + suffix)
+    writeFileSync(path, readFileSync(path, 'utf8').replaceAll('TODO: explain this change.', 'Optional payload metadata preserves the recorded value.')
+      .replaceAll('TODO: record validation evidence.', 'The focused persistence-history tests passed.'))
+  }
+}
+
+function commitCurrent(root: string, schema: PersistenceSchemaInventory): void {
+  writeFileSync(join(root, 'docs/persistence-schema.json'), JSON.stringify(schema, null, 2) + '\n')
+}
+
+function baseline(root: string, schema = inventory()): void {
+  runPersistenceChanges(['--baseline', BASE_ID], root, () => schema)
+  finishDocuments(root, BASE_ID)
+  commitCurrent(root, schema)
+}
+
+function unionBody(arms: readonly (readonly SchemaProperty[])[]): PersistenceRoot {
+  const nodes: SchemaNode[] = [
+    { kind: 'object', indices: [], properties: [{ name: 'data', type: 1, optional: false }] },
+    { kind: 'union', types: arms.map((_, index) => 5 + index) },
+    { kind: 'primitive', type: 'string' },
+    { kind: 'primitive', type: 'number' },
+    { kind: 'primitive', type: 'boolean' },
+    ...arms.map(properties => ({ kind: 'object' as const, indices: [], properties })),
+  ]
+  const schema = canonicalizeSchema(nodes, 0)
+  return { ...typeRoot('event:example/value', {}), schema, digest: schemaDigest(schema) }
+}
+
+describe('persistence change classification', () => {
+  it('treats a new optional payload subtree as one additive change even with required descendants', () => {
+    const before = typeRoot('event:example/value', { value: 'string' })
+    const after = typeRoot('event:example/value', { value: 'string', 'details?': { name: 'string', count: 'number' } })
+    expect(classifyPersistenceChange(before, after)).toEqual([{ path: 'event:example/value.data.details', kind: 'optional-property-added', description: 'optional property added', requiresVersionBump: false }])
+  })
+
+  it('permits required-to-optional payload properties while rejecting opposite changes, type changes, and removals', () => {
+    const required = typeRoot('event:example/value', { value: 'string' })
+    const optional = typeRoot('event:example/value', { 'value?': 'string' })
+    expect(classifyPersistenceChange(required, optional).every(change => !change.requiresVersionBump)).toBe(true)
+    for (const after of [required, typeRoot('event:example/value', { 'value?': 'number' }), typeRoot('event:example/value', {})]) {
+      expect(classifyPersistenceChange(optional, after).some(change => change.requiresVersionBump)).toBe(true)
+    }
+  })
+
+  it('pairs multiple discriminated union arms when a shared payload gains an optional property', () => {
+    function unionRoot(optional: boolean): PersistenceRoot {
+      const nodes: SchemaNode[] = [
+        { kind: 'object', indices: [], properties: [{ name: 'data', type: 1, optional: false }] },
+        { kind: 'union', types: [2, 3] },
+        { kind: 'object', indices: [], properties: [{ name: 'kind', type: 4, optional: false }, { name: 'payload', type: 6, optional: false }] },
+        { kind: 'object', indices: [], properties: [{ name: 'kind', type: 5, optional: false }, { name: 'payload', type: 6, optional: false }] },
+        { kind: 'literal', value: 'left' }, { kind: 'literal', value: 'right' },
+        { kind: 'object', indices: [], properties: [{ name: 'value', type: 7, optional: false }, ...(optional ? [{ name: 'label', type: 7, optional: true }] : [])] },
+        { kind: 'primitive', type: 'string' },
+      ]
+      const schema = canonicalizeSchema(nodes, 0)
+      return { ...typeRoot('event:example/value', {}), schema, digest: schemaDigest(schema) }
+    }
+    const differences = classifyPersistenceChange(unionRoot(false), unionRoot(true))
+    expect(differences.length).toBeGreaterThan(0)
+    expect(differences.every(change => !change.requiresVersionBump)).toBe(true)
+  })
+
+  it('allows optional additions across undiscriminated union arms', () => {
+    const first = [{ name: 'a', type: 2, optional: false }]
+    const second = [{ name: 'b', type: 3, optional: false }]
+    const extra = { name: 'x', type: 4, optional: true }
+    const differences = classifyPersistenceChange(unionBody([first, second]), unionBody([[...first, extra], [...second, extra]]))
+    expect(differences).toEqual([expect.objectContaining({ path: 'event:example/value.data.x', requiresVersionBump: false })])
+  })
+
+  it('allows required-to-optional fields across undiscriminated union arms', () => {
+    const before = unionBody([[{ name: 'a', type: 2, optional: false }], [{ name: 'b', type: 3, optional: false }]])
+    const after = unionBody([[{ name: 'a', type: 2, optional: true }], [{ name: 'b', type: 3, optional: true }]])
+    const differences = classifyPersistenceChange(before, after)
+    expect(differences.map(change => change.path).sort()).toEqual(['event:example/value.data.a', 'event:example/value.data.b'])
+    expect(differences.every(change => change.kind === 'property-made-optional' && !change.requiresVersionBump)).toBe(true)
+  })
+
+  it('finds a complete matching when one union arm has multiple additive successors', () => {
+    const required = [{ name: 'a', type: 2, optional: false }]
+    const optional = [{ name: 'a', type: 2, optional: true }]
+    const flexible = [{ name: '0', type: 4, optional: true }, ...optional]
+    const constrained = [...required, { name: 'z', type: 4, optional: true }]
+    const before = unionBody([required, optional])
+    for (const after of [unionBody([flexible, constrained]), unionBody([constrained, flexible])]) {
+      const differences = classifyPersistenceChange(before, after)
+      expect(differences.length).toBeGreaterThan(0)
+      expect(differences.every(change => !change.requiresVersionBump)).toBe(true)
+    }
+    const noCompleteMatching = unionBody([flexible, [{ name: 'different', type: 4, optional: true }]])
+    expect(classifyPersistenceChange(before, noCompleteMatching).some(change => change.requiresVersionBump)).toBe(true)
+  })
+
+  it('keeps union cardinality, property removal, new required fields, and value types strict', () => {
+    const first = [{ name: 'a', type: 2, optional: false }]
+    const second = [{ name: 'b', type: 3, optional: false }]
+    const third = [{ name: 'c', type: 4, optional: false }]
+    const before = unionBody([first, second])
+    const variants = [
+      unionBody([first, second, third]),
+      unionBody([first]),
+      unionBody([first, third]),
+      unionBody([[...first, { name: 'x', type: 4, optional: false }], [...second, { name: 'x', type: 4, optional: true }]]),
+      unionBody([[{ name: 'a', type: 3, optional: true }], [{ name: 'b', type: 3, optional: true }]]),
+    ]
+    for (const after of variants) expect(classifyPersistenceChange(before, after).some(change => change.requiresVersionBump)).toBe(true)
+  })
+
+  it('checks all recursive union arms without retaining provisional successes between candidates', () => {
+    const next = { name: 'next', type: 1, optional: true }
+    const first = [{ name: 'a', type: 2, optional: false }, next]
+    const second = [{ name: 'b', type: 3, optional: false }, next]
+    const extra = { name: 'x', type: 4, optional: true }
+    const before = unionBody([first, second])
+    const additive = unionBody([[...first, extra], [...second, extra]])
+    expect(classifyPersistenceChange(before, additive).every(change => !change.requiresVersionBump)).toBe(true)
+    const invalid = unionBody([[...first, extra], [{ name: 'b', type: 2, optional: false }, next, extra]])
+    expect(classifyPersistenceChange(before, invalid).some(change => change.requiresVersionBump)).toBe(true)
+    expect(classifyPersistenceChange(invalid, before).some(change => change.requiresVersionBump)).toBe(true)
+  })
+
+  it('preserves body scope through arrays and tuples and rejects a simultaneous value-type change', () => {
+    function wrapped(optional: boolean, primitive: 'string' | 'number' = 'string'): PersistenceRoot {
+      const nodes: SchemaNode[] = [
+        { kind: 'object', indices: [], properties: [{ name: 'data', type: 1, optional: false }] },
+        { kind: 'tuple', elements: [{ type: 2, optional: false, rest: false }] },
+        { kind: 'array', element: 3 },
+        { kind: 'object', indices: [], properties: [{ name: 'value', type: 4, optional }] },
+        { kind: 'primitive', type: primitive },
+      ]
+      const schema = canonicalizeSchema(nodes, 0)
+      return { ...typeRoot('event:example/value', {}), schema, digest: schemaDigest(schema) }
+    }
+    expect(classifyPersistenceChange(wrapped(false), wrapped(true)).every(change => !change.requiresVersionBump)).toBe(true)
+    expect(classifyPersistenceChange(wrapped(false), wrapped(true, 'number')).some(change => change.requiresVersionBump)).toBe(true)
+  })
+
+  it('keeps optional header/envelope properties and surface event additions strict', () => {
+    for (const key of ['SessionHeader', 'JsonlHeaderLine', 'SessionEventEnvelope']) {
+      expect(classifyPersistenceChange(typeRoot(key, {}), typeRoot(key, { 'metadata?': 'string' }))[0]?.requiresVersionBump).toBe(true)
+    }
+    const added = typeRoot('event:example/added', { value: 'string' })
+    expect(classifyPersistenceChange(null, added)[0]?.requiresVersionBump).toBe(false)
+    expect(classifyPersistenceChange(null, { ...added, surface: true })[0]?.requiresVersionBump).toBe(true)
+    expect(classifyPersistenceChange(added, null)[0]?.requiresVersionBump).toBe(true)
+  })
+})
+
+describe('persistence history verification', () => {
+  it('accepts a baseline and a successive optional addition without comparing the historical schema to current', () => {
+    const before = inventory()
+    const after = inventory({ value: 'string', 'label?': 'string' })
+    const history = validatePersistenceHistory([entry(BASE_ID, before, null, true), entry(NEXT_ID, onlyEvent(after), BASE_ID)])
+    expect(history.tips.get('event:example/value')?.root?.digest).toBe(after.roots[2]?.digest)
+    expect(history.tips.get('SessionHeader')?.id).toBe(BASE_ID)
+  })
+
+  it('rejects missing predecessors, forks, cycles, duplicates, and missing baseline', () => {
+    const base = entry(BASE_ID, inventory(), null, true)
+    const next = entry(NEXT_ID, onlyEvent(inventory({ value: 'string', 'label?': 'string' })), BASE_ID)
+    expect(() => validatePersistenceHistory([next])).toThrow('exactly one baseline')
+    expect(() => validatePersistenceHistory([base, entry(NEXT_ID, next.snapshot, '2026-09-11-missing')])).toThrow('missing predecessor')
+    expect(() => validatePersistenceHistory([base, next, entry('2026-09-11-fork', next.snapshot, BASE_ID)])).toThrow('forked')
+    expect(() => validatePersistenceHistory([base, base])).toThrow('exactly one baseline')
+    const cycle = entry('2026-09-11-cycle', { ...next.snapshot, roots: [typeRoot('event:cycle/event', {})] }, '2026-09-11-cycle')
+    expect(() => validatePersistenceHistory([base, cycle])).toThrow('cycle')
+  })
+
+  it('binds breaking decisions to the same record header version transition', () => {
+    const base = entry(BASE_ID, inventory(), null, true)
+    const breaking = inventory({ value: 'number' }, 4)
+    expect(() => validatePersistenceHistory([base, entry(NEXT_ID, onlyEvent(breaking), BASE_ID)])).toThrow('requires a format version bump')
+    expect(() => validatePersistenceHistory([base, entry(NEXT_ID, onlyEvent(breaking), BASE_ID, false, 'version-bump')])).toThrow("this record's own")
+    const touched = { ...breaking, roots: breaking.roots.filter(root => root.key === 'SessionHeader' || root.kind === 'event') }
+    expect(validatePersistenceHistory([base, entry(NEXT_ID, touched, BASE_ID, false, 'version-bump')]).tips.get('SessionHeader')?.id).toBe(NEXT_ID)
+    const later = entry('2026-09-11-later', onlyEvent(inventory({ value: 'boolean' }, 4)), NEXT_ID, false, 'version-bump')
+    expect(() => validatePersistenceHistory([base, entry(NEXT_ID, touched, BASE_ID, false, 'version-bump'), later])).toThrow("this record's own")
+  })
+
+  it('retains deletion tombstones and requires re-added roots to continue them', () => {
+    const base = entry(BASE_ID, inventory(), null, true)
+    const after = inventory({}, 4)
+    const header = after.roots[0]!
+    const record: PersistenceChangeRecord = { schemaVersion: 1, id: NEXT_ID, baseline: false, changes: [
+      { root: 'SessionHeader', previous: BASE_ID, after: header.digest, decision: 'version-bump' },
+      { root: 'event:example/value', previous: BASE_ID, after: null, decision: 'version-bump' },
+    ] }
+    const deletion = { record, snapshot: { ...after, roots: [header] } }
+    expect(validatePersistenceHistory([base, deletion]).tips.get('event:example/value')?.root).toBeNull()
+    const restored = entry('2026-09-11-restore', onlyEvent(inventory()), NEXT_ID)
+    expect(validatePersistenceHistory([base, deletion, restored]).tips.get('event:example/value')?.id).toBe(restored.record.id)
+    expect(() => validatePersistenceHistory([base, deletion, entry('2026-09-11-restore', restored.snapshot, null)])).toThrow('forked')
+  })
+
+  it('rejects malformed references, unknown schema variants, digest tampering, and extra snapshot roots', () => {
+    const schema = inventory()
+    const malformed = structuredClone(schema) as unknown as { roots: Array<{ schema: { nodes: unknown[] }; digest: string }> }
+    malformed.roots[0]!.schema.nodes = [{ kind: 'array', element: 99 }]
+    expect(() => parsePersistenceSnapshot(malformed)).toThrow('unknown schema node')
+    malformed.roots[0]!.schema.nodes = [{ kind: 'future' }]
+    expect(() => parsePersistenceSnapshot(malformed)).toThrow('unknown schema node kind')
+    const tampered = structuredClone(schema)
+    Object.assign(tampered.roots[0]!, { digest: '0'.repeat(64) })
+    expect(() => parsePersistenceSnapshot(tampered)).toThrow('digest mismatch')
+    expect(() => parsePersistenceSnapshot({ ...schema, formatVersion: 2 })).toThrow('normalization version')
+    const next = entry(NEXT_ID, onlyEvent(inventory({ value: 'string', 'label?': 'string' })), BASE_ID)
+    expect(() => validatePersistenceHistory([entry(BASE_ID, schema, null, true), { ...next, snapshot: inventory() }])).toThrow('snapshot roots')
+  })
+})
+
+describe('persistence changes current-tree commands', () => {
+  it('requires completed record prose, rejects stale generated output, and reports unacknowledged paths', () => {
+    const root = fixture()
+    const before = inventory()
+    runPersistenceChanges(['--baseline', BASE_ID], root, () => before)
+    expect(() => loadPersistenceHistory(root)).toThrow('complete compatibility')
+    finishDocuments(root, BASE_ID)
+    rmSync(join(root, 'docs/persistence-schema.json'))
+    expect(() => verifyPersistenceChanges(root, before)).toThrow('is missing')
+    commitCurrent(root, before)
+    const after = inventory({ value: 'string', 'label?': 'string' })
+    expect(() => verifyPersistenceChanges(root, after)).toThrow('is stale')
+    commitCurrent(root, after)
+    expect(() => verifyPersistenceChanges(root, after)).toThrow('event:example/value.data.label: optional property added (same-version allowed)')
+    runPersistenceChanges(['--record', NEXT_ID, '--decision', 'same-version'], root, () => after)
+    finishDocuments(root, NEXT_ID)
+    expect(runPersistenceChanges([], root, () => after)).toContain('4 roots match 2 history records')
+    expect(() => runPersistenceChanges(['--baseline', '2026-09-11-reset'], root, () => after)).toThrow('cannot reset history')
+    expect(() => runPersistenceChanges(['--record', '2026-09-11-empty', '--decision', 'same-version'], root, () => after)).toThrow('no persistence type changes')
+  })
+
+  it('rejects changed bilingual machine declarations and unreferenced snapshots', () => {
+    const root = fixture()
+    baseline(root)
+    const chinese = join(root, 'docs/persistence-changes', `${BASE_ID}.zh.md`)
+    const original = readFileSync(chinese, 'utf8')
+    writeFileSync(chinese, original.replace('baseline: true', 'baseline: false'))
+    expect(() => loadPersistenceHistory(root)).toThrow('bilingual machine records differ')
+    writeFileSync(chinese, original)
+    writeFileSync(join(root, 'docs/persistence-changes/2026-09-11-orphan.schema.json'), '{}\n')
+    expect(() => loadPersistenceHistory(root)).toThrow('unreferenced')
+  })
+
+  it('excludes nested historical format documents and schemas from acknowledgements', () => {
+    const root = fixture()
+    baseline(root)
+    const directory = join(root, 'docs/persistence-changes/historical-formats')
+    mkdirSync(directory)
+    writeFileSync(join(directory, 'v0.md'), '---\nkind: persistence-format\n---\n')
+    writeFileSync(join(directory, 'v0.schema.json'), '{}\n')
+    expect(loadPersistenceHistory(root).entries.map(entry => entry.record.id)).toEqual([BASE_ID])
+  })
+
+  it.each([
+    ['optional field', inventory({ value: 'string', 'label?': 'string' })],
+    ['required-to-optional field', inventory({ 'value?': 'string' })],
+    ['ordinary event addition', { ...inventory(), roots: [...inventory().roots, typeRoot('event:example/added', { count: 'number' })] }],
+  ] as const)('infers same-version for %s', (_name, after) => {
+    const root = fixture()
+    baseline(root)
+    runPersistenceChanges(['--record', NEXT_ID, '--prose', proseFile(root)], root, () => after)
+    const changes = loadPersistenceHistory(root).entries.find(entry => entry.record.id === NEXT_ID)?.record.changes
+    expect(changes?.length).toBeGreaterThan(0)
+    expect(changes?.every(change => change.decision === 'same-version')).toBe(true)
+    verifyPersistenceChanges(root, after)
+  })
+
+  it('infers a version bump when the source includes its own increasing header version', () => {
+    const root = fixture()
+    baseline(root)
+    const after = inventory({ value: 'number' }, 4)
+    runPersistenceChanges(['--record', NEXT_ID, '--prose', proseFile(root)], root, () => after)
+    const changes = loadPersistenceHistory(root).entries.find(entry => entry.record.id === NEXT_ID)?.record.changes
+    expect(changes?.map(change => change.root).sort()).toEqual(['SessionHeader', 'event:example/value'])
+    expect(changes?.every(change => change.decision === 'version-bump')).toBe(true)
+    verifyPersistenceChanges(root, after)
+  })
+
+  it('rejects inferred bumps without a header transition and explicit incorrect assertions before writing', () => {
+    const root = fixture()
+    baseline(root)
+    const prose = proseFile(root)
+    const directory = join(root, 'docs/persistence-changes')
+    const files = readdirSync(directory).sort()
+    const inventoryPath = join(root, 'docs/persistence-schema.json')
+    const before = readFileSync(inventoryPath, 'utf8')
+    for (const [args, code] of [
+      [[], 'version-transition-required'],
+      [['--decision', 'same-version'], 'version-bump-required'],
+    ] as const) {
+      const result = jsonResult(runPersistenceChanges(['--record', NEXT_ID, '--prose', prose, '--json', ...args], root,
+        () => inventory({ value: 'number' })))
+      expect(result).toMatchObject({ ok: false, code, files: [], changes: [expect.objectContaining({ requiresVersionBump: true })] })
+      expect(readFileSync(inventoryPath, 'utf8')).toBe(before)
+      expect(readdirSync(directory).sort()).toEqual(files)
+    }
+  })
+
+  it('authors a complete pair from explicit prose and reports source changes even when generated artifacts are stale', () => {
+    const root = fixture()
+    baseline(root)
+    const after = inventory({ value: 'string', 'label?': 'string' })
+    const pending = jsonResult(runPersistenceChanges(['--check', '--json'], root, () => after))
+    expect(pending).toMatchObject({ ok: false, operation: 'check', code: 'stale-artifacts',
+      roots: [{ root: 'event:example/value', kind: 'event', before: inventory().roots[2]?.digest, after: after.roots[2]?.digest }], changes: [
+        { root: 'event:example/value', path: 'event:example/value.data.label', kind: 'optional-property-added', requiresVersionBump: false },
+      ] })
+    const written = jsonResult(runPersistenceChanges(['--record', NEXT_ID, '--decision', 'same-version', '--prose', proseFile(root), '--json'], root, () => after))
+    expect(written).toMatchObject({ ok: true, operation: 'record', recordId: NEXT_ID })
+    expect(written.files).toEqual([
+      'docs/persistence-schema.json', `docs/persistence-changes/${NEXT_ID}.md`, `docs/persistence-changes/${NEXT_ID}.zh.md`,
+      `docs/persistence-changes/${NEXT_ID}.i18n.yaml`, `docs/persistence-changes/${NEXT_ID}.schema.json`,
+    ])
+    expect(written).toMatchObject({ roots: [{ root: 'event:example/value', kind: 'event',
+      before: inventory().roots[2]?.digest, after: after.roots[2]?.digest }] })
+    expect(readFileSync(join(root, `docs/persistence-changes/${NEXT_ID}.md`), 'utf8')).toContain(AUTHORED_PROSE.en.compatibility)
+    expect(jsonResult(runPersistenceChanges(['--check', '--json'], root, () => after)).ok).toBe(true)
+  })
+
+  it('refreshes only a terminal acknowledgement while preserving its authored prose and predecessor', () => {
+    const root = fixture()
+    baseline(root)
+    const after = inventory({ value: 'string', 'label?': 'string' })
+    const prose = proseFile(root)
+    runPersistenceChanges(['--record', NEXT_ID, '--decision', 'same-version', '--prose', prose], root, () => after)
+    const path = join(root, `docs/persistence-changes/${NEXT_ID}.md`)
+    const beforeText = readFileSync(path, 'utf8')
+    const refreshed = inventory({ value: 'string', 'label?': 'string', 'extra?': 'number' })
+    runPersistenceChanges(['--update', NEXT_ID], root, () => refreshed)
+    const stripRecord = (value: string): string => value.replace(/```yaml persistence-change[\s\S]*?```/u, '')
+    expect(stripRecord(readFileSync(path, 'utf8'))).toBe(stripRecord(beforeText))
+    expect(loadPersistenceHistory(root).tips.get('event:example/value')?.id).toBe(NEXT_ID)
+    expect(loadPersistenceHistory(root).entries.find(entry => entry.record.id === NEXT_ID)?.record.changes[0]?.previous).toBe(BASE_ID)
+    expect(jsonResult(runPersistenceChanges(['--check', '--json'], root, () => refreshed)).ok).toBe(true)
+    const final = inventory({ value: 'string', 'label?': 'string', 'extra?': 'number', 'last?': 'boolean' })
+    runPersistenceChanges(['--record', '2026-09-11-successor', '--decision', 'same-version', '--prose', prose], root, () => final)
+    expect(() => runPersistenceChanges(['--update', NEXT_ID, '--decision', 'same-version'], root, () => final)).toThrow('with successors')
+    expect(() => runPersistenceChanges(['--update', BASE_ID, '--decision', 'same-version'], root, () => final)).toThrow('cannot update the persistence baseline')
+  })
+
+  it('completes a scaffold through update and rejects invalid prose or decisions before changing files', () => {
+    const root = fixture()
+    baseline(root)
+    const after = inventory({ value: 'string', 'label?': 'string' })
+    runPersistenceChanges(['--record', NEXT_ID, '--decision', 'same-version'], root, () => after)
+    const prose = proseFile(root)
+    runPersistenceChanges(['--update', NEXT_ID, '--decision', 'same-version', '--prose', prose], root, () => after)
+    expect(runPersistenceChanges(['--check'], root, () => after)).toContain('roots match')
+    expect(readFileSync(join(root, `docs/persistence-changes/${NEXT_ID}.md`), 'utf8')).not.toContain('TODO:')
+    const pairedPaths = ['.md', '.zh.md', '.i18n.yaml'].map(suffix => join(root, `docs/persistence-changes/${NEXT_ID}${suffix}`))
+    const completed = pairedPaths.map(path => readFileSync(path, 'utf8'))
+    runPersistenceChanges(['--update', NEXT_ID, '--decision', 'same-version', '--prose', prose], root, () => after)
+    expect(pairedPaths.map(path => readFileSync(path, 'utf8'))).toEqual(completed)
+    const path = join(root, `docs/persistence-changes/${NEXT_ID}.md`)
+    const before = readFileSync(path, 'utf8')
+    const invalid = inventory({ value: 'number' })
+    const result = jsonResult(runPersistenceChanges(['--update', NEXT_ID, '--decision', 'same-version', '--json'], root, () => invalid))
+    expect(result).toMatchObject({ ok: false, code: 'version-bump-required', changes: [expect.objectContaining({ kind: 'type-changed', requiresVersionBump: true })] })
+    expect(readFileSync(path, 'utf8')).toBe(before)
+    for (const value of [
+      { ...AUTHORED_PROSE, extra: 'unsupported' },
+      { ...AUTHORED_PROSE, en: { ...AUTHORED_PROSE.en, compatibility: '   ' } },
+      { ...AUTHORED_PROSE, zh: { ...AUTHORED_PROSE.zh, verification: 'TODO: record validation evidence.' } },
+      { ...AUTHORED_PROSE, zh: { ...AUTHORED_PROSE.zh, verification: '```text\nUnpaired code.\n```' } },
+    ]) {
+      writeFileSync(prose, JSON.stringify(value))
+      expect(() => runPersistenceChanges(['--update', NEXT_ID, '--decision', 'same-version', '--prose', prose], root, () => after)).toThrow()
+      expect(readFileSync(path, 'utf8')).toBe(before)
+    }
+  })
+
+  // Six real CLI processes and TypeScript extraction share the Windows coverage test budget.
+  it('executes the real CLI against a source-only temporary checkout without Git history', { timeout: 90_000 }, () => {
+    const root = fixture()
+    const physical = join(root, 'packages/session/session-persistence-jsonl/src')
+    mkdirSync(physical, { recursive: true })
+    writeFileSync(join(physical, 'format.ts'), "interface HeaderLine { type: 'session'; version: number; id: string; delegationDepth: number }; export {}\n")
+    const session = join(root, 'packages/core/session/src')
+    mkdirSync(session, { recursive: true })
+    writeFileSync(join(session, '../package.json'), JSON.stringify({ name: '@deepseek-ai/dsh-session' }))
+    writeFileSync(join(root, 'tsconfig.host.json'), JSON.stringify({ compilerOptions: {
+      target: 'ESNext', module: 'ESNext', moduleResolution: 'Bundler', types: [], skipLibCheck: true,
+      paths: { '@deepseek-ai/dsh-session/types': ['./packages/core/session/src/types.ts'] },
+    } }))
+    const source = [
+      '/** Stored header. */', 'export interface SessionHeader { version: 3; id: string }',
+      '/** Stored event payloads. */', 'export interface SessionEventMap {', '/** Saved value. */',
+      "'example/value': { value: string }", '}', '/** Surface event names. */', "export type SurfaceEventType = 'example/value'",
+      '/** Persisted event names. */', 'export type SessionEventType = keyof SessionEventMap',
+      '/** Surface placement. */', "export type SurfaceOp = 'append'", '/** Persisted event. */',
+      'export type SessionEvent<K extends keyof SessionEventMap = keyof SessionEventMap> =',
+      '  { [P in K]: { type: P; seq: number; data: SessionEventMap[P]; surfaceOp: SurfaceOp } }[K]', '',
+    ].join('\n')
+    writeFileSync(join(session, 'types.ts'), source)
+    const script = resolve(import.meta.dirname, 'persistence-changes.ts')
+    const cli = (...args: string[]): ReturnType<typeof spawnSync> => spawnSync(process.execPath, ['--import', import.meta.resolve('tsx/esm'), script, '--root', root, ...args], {
+      cwd: root, encoding: 'utf8', timeout: 120_000,
+    })
+    const prose = proseFile(root)
+    const initialized = cli('--baseline', BASE_ID, '--prose', prose)
+    expect(initialized.error).toBeUndefined()
+    expect(initialized.signal).toBeNull()
+    expect(initialized.status, String(initialized.stderr)).toBe(0)
+    const accepted = cli('--check')
+    expect(accepted.error).toBeUndefined()
+    expect(accepted.signal).toBeNull()
+    expect(accepted.status, String(accepted.stderr)).toBe(0)
+    const optional = source.replace('value: string', 'value: string; label?: string')
+    writeFileSync(join(session, 'types.ts'), optional)
+    const authored = cli('--record', NEXT_ID, '--prose', prose, '--json')
+    expect(authored.error).toBeUndefined()
+    expect(authored.signal).toBeNull()
+    expect(authored.status, String(authored.stderr)).toBe(0)
+    expect(JSON.parse(String(authored.stdout)) as unknown).toMatchObject({ ok: true, operation: 'record' })
+    const beforeUpdate = readFileSync(join(root, `docs/persistence-changes/${NEXT_ID}.md`), 'utf8')
+    writeFileSync(join(session, 'types.ts'), optional.replace('label?: string', 'label?: string; extra?: number'))
+    const updated = cli('--update', NEXT_ID, '--json')
+    expect(updated.error).toBeUndefined()
+    expect(updated.signal).toBeNull()
+    expect(updated.status, String(updated.stderr)).toBe(0)
+    expect(JSON.parse(String(updated.stdout)) as unknown).toMatchObject({ ok: true, operation: 'update' })
+    expect(readFileSync(join(root, `docs/persistence-changes/${NEXT_ID}.md`), 'utf8').replace(/```yaml persistence-change[\s\S]*?```/u, ''))
+      .toBe(beforeUpdate.replace(/```yaml persistence-change[\s\S]*?```/u, ''))
+    const generated = extractPersistenceSchema(root)
+    for (const file of persistenceCatalogArtifacts(root, generated)) expect(readFileSync(join(root, file.path), 'utf8')).toBe(file.content)
+    verifyPersistenceChanges(root, generated)
+    writeFileSync(join(session, 'types.ts'), optional.replace('label?: string', 'label?: string; extra?: number').replace('value: string', 'value: number'))
+    commitCurrent(root, extractPersistenceSchema(root))
+    const rejected = cli('--check')
+    expect(rejected.error).toBeUndefined()
+    expect(rejected.signal).toBeNull()
+    expect(rejected.status).toBe(1)
+    expect(String(rejected.stderr)).toContain('version-bump required')
+    const structured = cli('--check', '--json')
+    expect(structured.error).toBeUndefined()
+    expect(structured.signal).toBeNull()
+    expect(structured.status).toBe(1)
+    expect(JSON.parse(String(structured.stdout)) as unknown).toMatchObject({
+      ok: false, code: 'unacknowledged-changes', changes: [expect.objectContaining({ kind: 'type-changed', requiresVersionBump: true })],
+    })
+  })
+})

scripts/persistence-changes.ts

@@ -0,0 +1,812 @@
+/** Verify and acknowledge persistence type changes from current-tree schema history. */
+
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from 'node:fs'
+import { basename, join, resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+import { JSON_SCHEMA, load } from 'js-yaml'
+import { canonicalizeSchema, schemaDigest } from './persistence-schema-model.ts'
+import type { CanonicalSchema, PersistenceRoot, PersistenceSchemaInventory, SchemaNode, SchemaTupleElement } from './persistence-schema-model.ts'
+import { extractPersistenceSchema } from './persistence-schema.ts'
+import { persistenceCatalogArtifacts } from './gen-persistence-catalog.ts'
+import { renderPersistencePair } from './persistence-artifacts.ts'
+import type { PersistenceArtifact } from './persistence-artifacts.ts'
+
+const HISTORY_DIRECTORY = 'docs/persistence-changes'
+const CURRENT_SCHEMA = 'docs/persistence-schema.json'
+const ID_PATTERN = /^\d{4}-\d{2}-\d{2}-[a-z0-9]+(?:-[a-z0-9]+)*$/u
+const DIGEST_PATTERN = /^[a-f0-9]{64}$/u
+const EXPLANATION_PLACEHOLDER = 'TODO: explain this change.'
+const EVIDENCE_PLACEHOLDER = 'TODO: record validation evidence.'
+
+/** The author's acknowledgement of one mechanically classified transition. */
+export type PersistenceDecision = 'same-version' | 'version-bump'
+
+/** One root's successor; null after values preserve a deletion in its history. */
+export interface PersistenceChange {
+  readonly root: string
+  readonly previous: string | null
+  readonly after: string | null
+  readonly decision: PersistenceDecision
+}
+
+/** A document's machine record, independent of its translated prose. */
+export interface PersistenceChangeRecord {
+  readonly schemaVersion: 1
+  readonly id: string
+  readonly baseline: boolean
+  readonly changes: readonly PersistenceChange[]
+}
+
+/** A parsed acknowledgement and its self-contained after schemas. */
+export interface PersistenceHistoryEntry {
+  readonly record: PersistenceChangeRecord
+  readonly snapshot: PersistenceSchemaInventory
+}
+
+/** One detected type change, with a path that reviewers can locate. */
+export interface PersistenceTypeChange {
+  readonly kind: PersistenceTypeChangeKind
+  readonly path: string
+  readonly description: string
+  readonly requiresVersionBump: boolean
+}
+
+const CHANGE_DESCRIPTIONS = {
+  'root-added': 'root added',
+  'root-removed': 'root removed',
+  'root-classification-changed': 'root classification changed',
+  'type-changed': 'type changed',
+  'property-removed': 'property removed',
+  'property-made-optional': 'property made optional',
+  'property-made-required': 'property made required',
+  'optional-property-added': 'optional property added',
+  'required-property-added': 'required property added',
+  'index-signature-changed': 'index signature changed',
+  'tuple-length-changed': 'tuple length changed',
+  'tuple-element-cardinality-changed': 'tuple element cardinality changed',
+  'union-variants-changed': 'union variants changed',
+} as const
+
+/** Stable structural classification independent of diagnostic prose. */
+export type PersistenceTypeChangeKind = keyof typeof CHANGE_DESCRIPTIONS
+
+/** Author-supplied paragraphs used to complete one language of a change record. */
+export interface PersistenceChangeProse {
+  readonly summary: string
+  readonly compatibility: string
+  readonly verification: string
+}
+
+/** Explicit bilingual prose; the CLI supplies no compatibility or validation claims. */
+export interface PersistenceChangeProsePair {
+  readonly en: PersistenceChangeProse
+  readonly zh: PersistenceChangeProse
+}
+
+interface ReportedChange extends PersistenceTypeChange {
+  readonly root: string
+}
+
+interface RootTransition {
+  readonly root: string
+  readonly kind: PersistenceRoot['kind']
+  readonly before: string | null
+  readonly after: string | null
+}
+
+class PersistenceChangeFailure extends Error {
+  constructor(
+    message: string, readonly code: string, readonly changes: readonly ReportedChange[] = [],
+    readonly roots: readonly RootTransition[] = [],
+  ) {
+    super(message)
+  }
+}
+
+interface CommandResult {
+  readonly schemaVersion: 1
+  readonly ok: boolean
+  readonly operation: 'check' | 'baseline' | 'record' | 'update'
+  readonly message: string
+  readonly changes: readonly ReportedChange[]
+  readonly roots: readonly RootTransition[]
+  readonly files: readonly string[]
+  readonly recordId?: string
+  readonly code?: string
+}
+
+interface Tip {
+  readonly id: string
+  readonly root: PersistenceRoot | null
+}
+
+/** Verified per-root history tips; historical schemas need not match the current tree. */
+export interface PersistenceHistory {
+  readonly entries: readonly PersistenceHistoryEntry[]
+  readonly tips: ReadonlyMap<string, Tip>
+}
+
+function record(value: unknown, label: string): Record<string, unknown> {
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be an object`)
+  return value as Record<string, unknown>
+}
+
+function keys(value: Record<string, unknown>, expected: readonly string[], label: string, optional: readonly string[] = []): void {
+  const missing = expected.find(key => !Object.hasOwn(value, key))
+  const unexpected = Object.keys(value).find(key => !expected.includes(key) && !optional.includes(key))
+  if (missing !== undefined || unexpected !== undefined) throw new Error(`${label}: ${missing === undefined ? `unknown field ${unexpected}` : `missing field ${missing}`}`)
+}
+
+function array(value: unknown, label: string): unknown[] {
+  if (!Array.isArray(value)) throw new Error(`${label} must be an array`)
+  return value
+}
+
+function textValue(value: unknown, label: string): string {
+  if (typeof value !== 'string' || value.length === 0) throw new Error(`${label} must be a non-empty string`)
+  return value
+}
+
+function bool(value: unknown, label: string): boolean {
+  if (typeof value !== 'boolean') throw new Error(`${label} must be boolean`)
+  return value
+}
+
+function identifier(value: unknown, label: string): string {
+  const id = textValue(value, label)
+  if (!ID_PATTERN.test(id)) throw new Error(`${label} must be YYYY-MM-DD-slug`)
+  return id
+}
+
+function digest(value: unknown, label: string): string {
+  const result = textValue(value, label)
+  if (!DIGEST_PATTERN.test(result)) throw new Error(`${label} must be a SHA-256 digest`)
+  return result
+}
+
+function reference(value: unknown, count: number, label: string): number {
+  if (!Number.isSafeInteger(value) || (value as number) < 0 || (value as number) >= count) throw new Error(`${label} references an unknown schema node`)
+  return value as number
+}
+
+function parseSchema(value: unknown, label: string): CanonicalSchema {
+  const input = record(value, label)
+  keys(input, ['root', 'nodes'], label)
+  if (input.root !== 0) throw new Error(`${label}.root must be zero`)
+  const nodes = array(input.nodes, `${label}.nodes`)
+  if (nodes.length === 0) throw new Error(`${label}.nodes must not be empty`)
+  const ref = (value: unknown): number => reference(value, nodes.length, label)
+  for (const [index, raw] of nodes.entries()) {
+    const node = record(raw, `${label}.nodes[${index}]`)
+    switch (node.kind) {
+      case 'primitive':
+        keys(node, ['kind', 'type'], label)
+        if (!['null', 'boolean', 'number', 'string', 'never'].includes(String(node.type))) throw new Error(`${label}: invalid primitive`)
+        break
+      case 'literal':
+        keys(node, ['kind', 'value'], label)
+        if (!['string', 'boolean', 'number'].includes(typeof node.value)
+          || typeof node.value === 'number' && !Number.isFinite(node.value)) throw new Error(`${label}: invalid literal`)
+        break
+      case 'opaque':
+        keys(node, ['kind', 'reason'], label)
+        if (!['any', 'unknown'].includes(String(node.reason))) throw new Error(`${label}: invalid opaque reason`)
+        break
+      case 'array':
+        keys(node, ['kind', 'element'], label)
+        ref(node.element)
+        break
+      case 'tuple':
+        keys(node, ['kind', 'elements'], label)
+        for (const rawElement of array(node.elements, label)) {
+          const element = record(rawElement, label)
+          keys(element, ['type', 'optional', 'rest'], label)
+          ref(element.type)
+          bool(element.optional, label)
+          bool(element.rest, label)
+        }
+        break
+      case 'object': {
+        keys(node, ['kind', 'properties', 'indices'], label)
+        const names = new Set<string>()
+        for (const rawProperty of array(node.properties, label)) {
+          const property = record(rawProperty, label)
+          keys(property, ['name', 'type', 'optional'], label)
+          if (typeof property.name !== 'string') throw new Error(`${label}: property name must be a string`)
+          const name = property.name
+          if (names.has(name)) throw new Error(`${label}: duplicate property ${name}`)
+          names.add(name)
+          ref(property.type)
+          bool(property.optional, label)
+        }
+        for (const rawIndex of array(node.indices, label)) {
+          const entry = record(rawIndex, label)
+          keys(entry, ['key', 'value'], label)
+          ref(entry.key)
+          ref(entry.value)
+        }
+        break
+      }
+      case 'union':
+        keys(node, ['kind', 'types'], label)
+        if (array(node.types, label).length === 0) throw new Error(`${label}: empty union`)
+        for (const item of node.types as unknown[]) ref(item)
+        break
+      default:
+        throw new Error(`${label}: unknown schema node kind ${String(node.kind)}`)
+    }
+  }
+  const schema = input as unknown as CanonicalSchema
+  const canonical = canonicalizeSchema(schema.nodes, schema.root)
+  if (JSON.stringify(canonical) !== JSON.stringify(schema)) throw new Error(`${label}: schema is not canonical`)
+  return schema
+}
+
+/** Parse a persisted schema inventory, rejecting malformed graphs and digest drift.
+ * @param value - JSON read from the current inventory or an enforced acknowledgement snapshot.
+ * @returns the validated inventory.
+ */
+export function parsePersistenceSnapshot(value: unknown): PersistenceSchemaInventory {
+  return parseSnapshot(value, false)
+}
+
+/** Parse a historical inventory with path-only source references and optional surface operations.
+ * @param value - JSON captured from a historical source tree.
+ * @returns the validated inventory; current acknowledgements use the strict parser.
+ */
+export function parseHistoricalPersistenceSnapshot(value: unknown): PersistenceSchemaInventory {
+  return parseSnapshot(value, true)
+}
+
+function parseSnapshot(value: unknown, historical: boolean): PersistenceSchemaInventory {
+  const input = record(value, 'schema inventory')
+  keys(input, ['formatVersion', 'roots', 'types'], 'schema inventory')
+  if (input.formatVersion !== 1) throw new Error('unsupported persistence schema normalization version')
+  const names = new Set<string>()
+  for (const rawRoot of array(input.roots, 'schema roots')) {
+    const root = record(rawRoot, 'schema root')
+    keys(root, ['key', 'kind', 'digest', 'schema'], 'schema root', ['event', 'surface'])
+    const key = textValue(root.key, 'root key')
+    if (names.has(key)) throw new Error(`duplicate schema root ${key}`)
+    names.add(key)
+    if (root.kind === 'event') {
+      if (key !== `event:${textValue(root.event, 'event name')}`) throw new Error(`invalid event root key ${key}`)
+      bool(root.surface, 'event surface membership')
+    } else if ((root.kind !== 'header' || !['SessionHeader', 'JsonlHeaderLine'].includes(key))
+      && (root.kind !== 'envelope' || key !== 'SessionEventEnvelope')) throw new Error(`invalid schema root ${key}`)
+    if (root.kind !== 'event' && (root.event !== undefined || root.surface !== undefined)) throw new Error(`${key}: non-event metadata`)
+    const schema = parseSchema(root.schema, key)
+    if (root.kind === 'event') validateEventMetadata(schema, String(root.event), root.surface === true, historical)
+    if (digest(root.digest, `${key} digest`) !== schemaDigest(schema)) throw new Error(`${key}: schema digest mismatch`)
+  }
+  for (const rawType of array(input.types, 'schema types')) {
+    const type = record(rawType, 'schema type')
+    keys(type, ['digest', 'schema', 'names', 'sources'], 'schema type')
+    const schema = parseSchema(type.schema, 'shared schema')
+    if (digest(type.digest, 'shared digest') !== schemaDigest(schema)) throw new Error('shared schema digest mismatch')
+    for (const name of array(type.names, 'type names')) textValue(name, 'type name')
+    for (const source of array(type.sources, 'type sources')) {
+      const location = textValue(source, 'type source')
+      if (historical && /:\d+(?::\d+)?$|#L\d+(?:-L\d+)?$/u.test(location)) {
+        throw new Error('historical schema sources must omit line numbers')
+      }
+    }
+  }
+  return input as unknown as PersistenceSchemaInventory
+}
+
+function validateEventMetadata(schema: CanonicalSchema, event: string, surface: boolean, historical: boolean): void {
+  const pending = [0]
+  const visited = new Set<number>()
+  while (pending.length > 0) {
+    const index = pending.pop() as number
+    if (visited.has(index)) continue
+    visited.add(index)
+    const node = schema.nodes[index] as SchemaNode
+    if (node.kind === 'union') { pending.push(...node.types); continue }
+    if (node.kind !== 'object') throw new Error(`${event}: event schema must be an object`)
+    const tag = node.properties.find(property => property.name === 'type')
+    const value = tag === undefined ? undefined : schema.nodes[tag.type]
+    if (tag?.optional !== false || value?.kind !== 'literal' || value.value !== event) throw new Error(`${event}: event schema type does not match its root`)
+    const operation = node.properties.find(property => property.name === 'surfaceOp')
+    if (surface ? operation === undefined || !historical && operation.optional : operation !== undefined) throw new Error(`${event}: surface metadata does not match its schema`)
+  }
+}
+
+function subDigest(schema: CanonicalSchema, node: number): string {
+  return schemaDigest(canonicalizeSchema(schema.nodes, node))
+}
+
+function matchUnionVariants(candidates: readonly (readonly number[])[]): number[] | undefined {
+  const owners = new Map<number, number>()
+  function assign(previous: number, visited: Set<number>): boolean {
+    for (const next of candidates[previous] ?? []) {
+      if (visited.has(next)) continue
+      visited.add(next)
+      const owner = owners.get(next)
+      if (owner === undefined || assign(owner, visited)) {
+        owners.set(next, previous)
+        return true
+      }
+    }
+    return false
+  }
+  for (let previous = 0; previous < candidates.length; previous += 1) {
+    if (!assign(previous, new Set())) return undefined
+  }
+  const matches: number[] = []
+  for (const [next, previous] of owners) matches[previous] = next
+  return matches
+}
+
+/** Classify structural differences; only optional payload properties and ordinary event additions are additive.
+ * @param before - predecessor root, or absence for an addition.
+ * @param after - successor root, or absence for deletion.
+ * @returns concrete changes and their format-bump requirement.
+ */
+export function classifyPersistenceChange(before: PersistenceRoot | null, after: PersistenceRoot | null): PersistenceTypeChange[] {
+  if (before === null) {
+    return after === null ? [] : [{ path: after.key, kind: 'root-added', description: 'root added',
+      requiresVersionBump: after.kind !== 'event' || after.surface !== false }]
+  }
+  if (after === null) return [{ path: before.key, kind: 'root-removed', description: 'root removed', requiresVersionBump: true }]
+  const key = after.key
+  const oldRoot = before
+  const newRoot = after
+  const describe = (path: string, kind: PersistenceTypeChangeKind, requiresVersionBump = true): PersistenceTypeChange =>
+    ({ path, kind, description: CHANGE_DESCRIPTIONS[kind], requiresVersionBump })
+  const changes: PersistenceTypeChange[] = []
+  if (before.kind !== after.kind || before.surface !== after.surface) changes.push(describe(key, 'root-classification-changed'))
+  if (before.digest === after.digest) return changes
+  const fingerprints = [new Map<number, string>(), new Map<number, string>()] as const
+  const fingerprint = (schema: CanonicalSchema, index: number, side: 0 | 1): string => {
+    let result = fingerprints[side].get(index)
+    if (result === undefined) { result = subDigest(schema, index); fingerprints[side].set(index, result) }
+    return result
+  }
+  type Scope = 'event' | 'body' | 'strict'
+  function compare(
+    oldIndex: number, newIndex: number, path: string, scope: Scope, ancestors: ReadonlySet<string>,
+  ): PersistenceTypeChange[] {
+    if (fingerprint(oldRoot.schema, oldIndex, 0) === fingerprint(newRoot.schema, newIndex, 1)) return []
+    const pair = `${oldIndex}:${newIndex}:${scope}`
+    if (ancestors.has(pair)) return []
+    // Recursive pairs are assumptions for this candidate only. A failed sibling
+    // or unmatched union arm cannot leave a cached success for another candidate.
+    const active = new Set(ancestors).add(pair)
+    const differences: PersistenceTypeChange[] = []
+    const add = (path: string, kind: PersistenceTypeChangeKind, requiresVersionBump = true): void => {
+      differences.push(describe(path, kind, requiresVersionBump))
+    }
+    const descend = (oldType: number, newType: number, child: string, childScope: Scope): void => {
+      differences.push(...compare(oldType, newType, child, childScope, active))
+    }
+    const oldNode = oldRoot.schema.nodes[oldIndex] as SchemaNode
+    const newNode = newRoot.schema.nodes[newIndex] as SchemaNode
+    if (oldNode.kind !== newNode.kind) return [describe(path, 'type-changed')]
+    if (oldNode.kind === 'object' && newNode.kind === 'object') {
+      const oldProps = new Map(oldNode.properties.map(property => [property.name, property]))
+      const newProps = new Map(newNode.properties.map(property => [property.name, property]))
+      for (const [name, property] of oldProps) {
+        const next = newProps.get(name)
+        const child = `${path}.${name}`
+        if (next === undefined) { add(child, 'property-removed'); continue }
+        if (property.optional !== next.optional) add(child, next.optional ? 'property-made-optional' : 'property-made-required', scope !== 'body' || !next.optional)
+        descend(property.type, next.type, child, scope === 'body' || scope === 'event' && name === 'data' ? 'body' : 'strict')
+      }
+      for (const [name, property] of newProps) {
+        if (!oldProps.has(name)) add(`${path}.${name}`, property.optional ? 'optional-property-added' : 'required-property-added', scope !== 'body' || !property.optional)
+      }
+      const oldIndices = new Map(oldNode.indices.map(entry => [fingerprint(oldRoot.schema, entry.key, 0), entry]))
+      const newIndices = new Map(newNode.indices.map(entry => [fingerprint(newRoot.schema, entry.key, 1), entry]))
+      if (oldIndices.size !== newIndices.size || [...oldIndices.keys()].some(index => !newIndices.has(index))) add(path, 'index-signature-changed')
+      for (const [index, entry] of oldIndices) {
+        const next = newIndices.get(index)
+        if (next !== undefined) descend(entry.value, next.value, `${path}[*]`, scope === 'body' ? 'body' : 'strict')
+      }
+      return differences
+    }
+    if (oldNode.kind === 'array' && newNode.kind === 'array') {
+      return compare(oldNode.element, newNode.element, `${path}[]`, scope === 'body' ? 'body' : 'strict', active)
+    }
+    if (oldNode.kind === 'tuple' && newNode.kind === 'tuple') {
+      if (oldNode.elements.length !== newNode.elements.length) return [describe(path, 'tuple-length-changed')]
+      for (const [index, element] of oldNode.elements.entries()) {
+        const next = newNode.elements[index] as SchemaTupleElement
+        if (element.optional !== next.optional || element.rest !== next.rest) add(`${path}[${index}]`, 'tuple-element-cardinality-changed')
+        descend(element.type, next.type, `${path}[${index}]`, scope === 'body' ? 'body' : 'strict')
+      }
+      return differences
+    }
+    if (oldNode.kind === 'union' && newNode.kind === 'union') {
+      if (oldNode.types.length !== newNode.types.length) return [describe(path, 'union-variants-changed')]
+      const candidates = oldNode.types.map(oldType => newNode.types.map(newType => compare(oldType, newType, path, scope, active)))
+      const matching = matchUnionVariants(candidates.map(row => row.flatMap((candidate, index) =>
+        candidate.every(change => !change.requiresVersionBump) ? [index] : [])))
+      if (matching !== undefined) return matching.flatMap((next, previous) => candidates[previous]?.[next] ?? [])
+      const oldTypes = new Map(oldNode.types.map(index => [fingerprint(oldRoot.schema, index, 0), index]))
+      const newTypes = new Map(newNode.types.map(index => [fingerprint(newRoot.schema, index, 1), index]))
+      const removed = [...oldTypes].filter(([hash]) => !newTypes.has(hash)).map(([, index]) => index)
+      const added = [...newTypes].filter(([hash]) => !oldTypes.has(hash)).map(([, index]) => index)
+      if (removed.length === 1 && added.length === 1) return compare(removed[0] as number, added[0] as number, path, scope, active)
+      return [describe(path, 'union-variants-changed')]
+    }
+    return [describe(path, 'type-changed')]
+  }
+  changes.push(...compare(0, 0, key, before.kind === 'event' ? 'event' : 'strict', new Set()))
+  if (changes.length === 0) changes.push(describe(key, 'type-changed'))
+  return [...new Map(changes.map(change => [JSON.stringify([change.path, change.kind, change.requiresVersionBump]), change])).values()]
+}
+
+function parseDocument(source: string, filename: string, allowIncomplete = false): PersistenceChangeRecord {
+  const frontmatter = /^---\n([\s\S]*?)\n---\n/u.exec(source)
+  if (frontmatter === null || record(load(frontmatter[1] as string, { schema: JSON_SCHEMA }), filename).kind !== 'persistence-change') throw new Error(`${filename}: kind must be persistence-change`)
+  const openings = [...source.matchAll(/^```yaml persistence-change\s*$/gmu)]
+  const block = /^```yaml persistence-change[^\S\n]*\n([\s\S]*?)^```[^\S\n]*$/mu.exec(source)
+  if (openings.length !== 1 || block === null) throw new Error(`${filename}: expected exactly one persistence-change block`)
+  const input = record(load(block[1] as string, { schema: JSON_SCHEMA }), filename)
+  keys(input, ['schemaVersion', 'id', 'baseline', 'changes'], filename)
+  if (input.schemaVersion !== 1) throw new Error(`${filename}: unsupported acknowledgement schema version`)
+  const id = identifier(input.id, filename)
+  if (basename(filename) !== `${id}.md`) throw new Error(`${filename}: record id does not match filename`)
+  bool(input.baseline, filename)
+  const roots = new Set<string>()
+  for (const value of array(input.changes, `${filename} changes`)) {
+    const change = record(value, filename)
+    keys(change, ['root', 'previous', 'after', 'decision'], filename)
+    const root = textValue(change.root, 'changed root')
+    if (roots.has(root)) throw new Error(`${filename}: duplicate change for ${root}`)
+    roots.add(root)
+    if (change.previous !== null) identifier(change.previous, 'previous record')
+    if (change.after !== null) digest(change.after, 'after digest')
+    if (change.decision !== 'same-version' && change.decision !== 'version-bump') throw new Error(`${filename}: invalid compatibility decision`)
+  }
+  if (roots.size === 0) throw new Error(`${filename}: changes must not be empty`)
+  if (!allowIncomplete && (source.includes(EXPLANATION_PLACEHOLDER) || source.includes(EVIDENCE_PLACEHOLDER))) throw new Error(`${filename}: complete compatibility and verification prose`)
+  return input as unknown as PersistenceChangeRecord
+}
+
+function headerVersion(root: PersistenceRoot | null): number | undefined {
+  if (root === null) return undefined
+  const node = root.schema.nodes[0]
+  if (node?.kind !== 'object') return undefined
+  const property = node.properties.find(item => item.name === 'version')
+  if (property === undefined) return undefined
+  const version = root.schema.nodes[property.type]
+  return version?.kind === 'literal' && typeof version.value === 'number' && Number.isSafeInteger(version.value) ? version.value : undefined
+}
+
+/** Check every historical transition and return each root's unique current tip.
+ * @param entries - parsed documents and their self-contained schema snapshots.
+ * @returns validated history and tips, without consulting Git or current source.
+ */
+export function validatePersistenceHistory(entries: readonly PersistenceHistoryEntry[]): PersistenceHistory {
+  if (entries.filter(entry => entry.record.baseline).length !== 1) throw new Error('persistence history requires exactly one baseline')
+  const records = new Map<string, PersistenceHistoryEntry>()
+  for (const entry of entries) {
+    if (records.has(entry.record.id)) throw new Error(`duplicate persistence record ${entry.record.id}`)
+    records.set(entry.record.id, entry)
+    const expected = entry.record.changes.filter(change => change.after !== null).map(change => change.root).sort()
+    if (JSON.stringify(expected) !== JSON.stringify(entry.snapshot.roots.map(root => root.key).sort())) throw new Error(`${entry.record.id}: snapshot roots do not match acknowledged after schemas`)
+    for (const change of entry.record.changes) {
+      const root = entry.snapshot.roots.find(root => root.key === change.root)
+      if ((root?.digest ?? null) !== change.after) throw new Error(`${entry.record.id}: after digest mismatch for ${change.root}`)
+      if (entry.record.baseline && (change.previous !== null || change.after === null || change.decision !== 'same-version')) throw new Error(`${entry.record.id}: invalid baseline transition`)
+    }
+  }
+  const states = new Map<string, 'visiting' | 'visited'>()
+  const successors = new Map<string, string>()
+  const nodes = new Map<string, { entry: PersistenceHistoryEntry; change: PersistenceChange }>()
+  const tips = new Map<string, Tip>()
+  const nodeKey = (id: string | null, root: string): string => JSON.stringify([id, root])
+  for (const entry of entries) for (const change of entry.record.changes) {
+    const parentKey = nodeKey(change.previous, change.root)
+    if (successors.has(parentKey)) throw new Error(`forked persistence history for ${change.root}: ${successors.get(parentKey)} and ${entry.record.id}`)
+    successors.set(parentKey, entry.record.id)
+    nodes.set(nodeKey(entry.record.id, change.root), { entry, change })
+  }
+  function visit(id: string, root: string): PersistenceRoot | null {
+    const key = nodeKey(id, root)
+    const found = nodes.get(key)
+    if (found === undefined) throw new Error(`missing predecessor ${id} for ${root}`)
+    if (states.get(key) === 'visiting') throw new Error(`cycle in persistence history for ${root}`)
+    const after = found.entry.snapshot.roots.find(item => item.key === root) ?? null
+    if (states.get(key) === 'visited') return after
+    states.set(key, 'visiting')
+    const before = found.change.previous === null ? null : visit(found.change.previous, root)
+    if (!found.entry.record.baseline) {
+      const differences = classifyPersistenceChange(before, after)
+      if (differences.length === 0) throw new Error(`${id}: unchanged acknowledgement for ${root}`)
+      if (differences.some(change => change.requiresVersionBump) && found.change.decision !== 'version-bump') {
+        throw new PersistenceChangeFailure(
+          `${id}: ${root} requires a format version bump (${differences.filter(change => change.requiresVersionBump).map(change => change.path + ': ' + change.description).join('; ')})`,
+          'version-bump-required', differences.map(change => ({ root, ...change })), [rootTransition(before, after)],
+        )
+      }
+      if (found.change.decision === 'version-bump') {
+        const header = found.entry.record.changes.find(change => change.root === 'SessionHeader')
+        const oldHeader = header?.previous === null || header === undefined ? null : visit(header.previous, 'SessionHeader')
+        const from = headerVersion(oldHeader)
+        const to = headerVersion(found.entry.snapshot.roots.find(item => item.key === 'SessionHeader') ?? null)
+        if (from === undefined || to === undefined || to <= from) {
+          throw new PersistenceChangeFailure(`${id}: version-bump requires this record's own increasing SessionHeader.version transition`,
+            'version-transition-required', differences.map(change => ({ root, ...change })), [rootTransition(before, after)])
+        }
+      }
+    }
+    states.set(key, 'visited')
+    if (!successors.has(key)) tips.set(root, { id, root: after })
+    return after
+  }
+  for (const entry of entries) for (const change of entry.record.changes) visit(entry.record.id, change.root)
+  const baseline = entries.find(entry => entry.record.baseline) as PersistenceHistoryEntry
+  if (!baseline.snapshot.roots.some(root => root.key === 'SessionHeader')
+    || !baseline.snapshot.roots.some(root => root.key === 'SessionEventEnvelope')
+    || !baseline.snapshot.roots.some(root => root.key === 'JsonlHeaderLine')) {
+    throw new Error('baseline requires SessionHeader, JsonlHeaderLine, and SessionEventEnvelope roots')
+  }
+  return { entries, tips }
+}
+
+/** Read and validate all current-tree persistence acknowledgement files.
+ * @param root - checkout or isolated fixture root.
+ * @returns checked history without comparing its tips to current source.
+ */
+export function loadPersistenceHistory(root: string): PersistenceHistory {
+  return validatePersistenceHistory(readPersistenceEntries(root))
+}
+
+function readPersistenceEntries(root: string, allowIncompleteId?: string): PersistenceHistoryEntry[] {
+  const directory = join(root, HISTORY_DIRECTORY)
+  if (!existsSync(directory)) throw new Error('persistence history is missing; use pnpm run persistence-changes --baseline ID for explicit initialization')
+  const files = readdirSync(directory).sort()
+  const documents = files.filter(file => file.endsWith('.md') && !file.endsWith('.zh.md') && file !== 'README.md' && file !== 'AGENTS.md')
+  const snapshots = new Set(files.filter(file => file.endsWith('.schema.json')))
+  const entries = documents.map((filename) => {
+    const source = readFileSync(join(directory, filename), 'utf8').replaceAll('\r\n', '\n')
+    const allowIncomplete = filename === `${allowIncompleteId}.md`
+    const change = parseDocument(source, filename, allowIncomplete)
+    const snapshotName = `${change.id}.schema.json`
+    if (!snapshots.delete(snapshotName)) throw new Error(`${filename}: missing schema snapshot ${snapshotName}`)
+    const snapshot = parsePersistenceSnapshot(JSON.parse(readFileSync(join(directory, snapshotName), 'utf8')))
+    const translatedName = `${change.id}.zh.md`
+    if (!files.includes(translatedName)) throw new Error(`${filename}: missing Chinese counterpart`)
+    const translated = readFileSync(join(directory, translatedName), 'utf8').replaceAll('\r\n', '\n')
+    const englishBlock = source.match(/^```yaml persistence-change[^\S\n]*\n([\s\S]*?)^```[^\S\n]*$/mu)?.[1]
+    const chineseBlocks = [...translated.matchAll(/^```yaml persistence-change[^\S\n]*\n([\s\S]*?)^```[^\S\n]*$/gmu)]
+    if (chineseBlocks.length !== 1 || chineseBlocks[0]?.[1] !== englishBlock) throw new Error(`${filename}: bilingual machine records differ`)
+    if (!allowIncomplete && (translated.includes(EXPLANATION_PLACEHOLDER) || translated.includes(EVIDENCE_PLACEHOLDER))) throw new Error(`${translatedName}: complete compatibility and verification prose`)
+    return { record: change, snapshot }
+  })
+  if (snapshots.size !== 0) throw new Error(`unreferenced persistence schema snapshot: ${[...snapshots].join(', ')}`)
+  return entries
+}
+
+function currentDifferences(history: PersistenceHistory, current: PersistenceSchemaInventory): string[] {
+  const roots = new Map(current.roots.map(root => [root.key, root]))
+  const differences: string[] = []
+  for (const key of new Set([...history.tips.keys(), ...roots.keys()])) {
+    if (classifyPersistenceChange(history.tips.get(key)?.root ?? null, roots.get(key) ?? null).length !== 0) differences.push(key)
+  }
+  return differences.sort()
+}
+
+/** Verify current generated output and acknowledgement tips together.
+ * @param root - checkout or isolated fixture root.
+ * @param current - freshly extracted current-source inventory.
+ * @returns verified history.
+ */
+export function verifyPersistenceChanges(root: string, current: PersistenceSchemaInventory): PersistenceHistory {
+  const history = loadPersistenceHistory(root)
+  const differences = reportedDifferences(history, current)
+  const transitions = rootTransitions(history, current)
+  const committedPath = join(root, CURRENT_SCHEMA)
+  if (!existsSync(committedPath)) {
+    throw new PersistenceChangeFailure(`${CURRENT_SCHEMA} is missing; regenerate the persistence catalog`, 'generated-artifact-missing', differences, transitions)
+  }
+  const committed = parsePersistenceSnapshot(JSON.parse(readFileSync(committedPath, 'utf8')))
+  if (JSON.stringify(committed) !== JSON.stringify(current)) {
+    throw new PersistenceChangeFailure(`${CURRENT_SCHEMA} is stale; regenerate the persistence catalog`, 'stale-artifacts', differences, transitions)
+  }
+  if (differences.length !== 0) {
+    const details = differences.map(change => `  ${change.path}: ${change.description} (${change.requiresVersionBump ? 'version-bump required' : 'same-version allowed'})`)
+    throw new PersistenceChangeFailure(`unacknowledged persistence type changes:\n${details.join('\n')}`, 'unacknowledged-changes', differences, transitions)
+  }
+  return history
+}
+
+function rootTransition(before: PersistenceRoot | null, after: PersistenceRoot | null): RootTransition {
+  const root = (after ?? before) as PersistenceRoot
+  return { root: root.key, kind: root.kind, before: before?.digest ?? null, after: after?.digest ?? null }
+}
+
+function rootTransitions(history: PersistenceHistory | undefined, current: PersistenceSchemaInventory): RootTransition[] {
+  const changed = history === undefined ? current.roots.map(root => root.key) : currentDifferences(history, current)
+  return changed.map(root => rootTransition(history?.tips.get(root)?.root ?? null, current.roots.find(item => item.key === root) ?? null))
+}
+
+function reportedDifferences(history: PersistenceHistory, current: PersistenceSchemaInventory): ReportedChange[] {
+  return currentDifferences(history, current).flatMap(root => classifyPersistenceChange(
+    history.tips.get(root)?.root ?? null, current.roots.find(item => item.key === root) ?? null,
+  ).map(change => ({ root, ...change })))
+}
+
+function machineBlock(change: PersistenceChangeRecord): string {
+  return ['```yaml persistence-change', 'schemaVersion: 1', `id: ${change.id}`, `baseline: ${String(change.baseline)}`, 'changes:',
+    ...change.changes.flatMap(item => [`  - root: ${JSON.stringify(item.root)}`, `    previous: ${item.previous === null ? 'null' : JSON.stringify(item.previous)}`, `    after: ${item.after === null ? 'null' : JSON.stringify(item.after)}`, `    decision: ${item.decision}`]), '```'].join('\n')
+}
+
+function scaffold(change: PersistenceChangeRecord, chinese: boolean, prose?: PersistenceChangeProse): string {
+  const summary = chinese ? '概述' : 'Summary'
+  const compatibility = chinese ? '兼容性' : 'Compatibility'
+  const verification = chinese ? '验证' : 'Verification'
+  return ['---', `description: ${JSON.stringify(chinese ? '记录持久化类型更改及其兼容性确认。' : 'Records a persistence type transition and its compatibility acknowledgement.')}`, 'kind: persistence-change', '---', '',
+    `# ${change.id}`, '', chinese ? `[English](${change.id}.md) | 中文` : `English | [中文](${change.id}.zh.md)`, '',
+    `## ${summary}`, '', prose?.summary ?? EXPLANATION_PLACEHOLDER, '', '## ' + (chinese ? '目录' : 'Table of Contents'), '',
+    `- [${chinese ? '声明' : 'Declaration'}](#declaration)`, `- [${compatibility}](#compatibility)`, `- [${verification}](#verification)`, `- [${chinese ? '开发备注' : 'Dev Note'}](#dev-note)`, '',
+    '<a id="declaration"></a>', `## ${chinese ? '声明' : 'Declaration'}`, '', machineBlock(change), '',
+    '<a id="compatibility"></a>', `## ${compatibility}`, '', prose?.compatibility ?? EXPLANATION_PLACEHOLDER, '',
+    '<a id="verification"></a>', `## ${verification}`, '', prose?.verification ?? EVIDENCE_PLACEHOLDER, '', '<a id="dev-note"></a>', `## ${chinese ? '开发备注' : 'Dev Note'}`, '', chinese ? '无。' : 'None.', ''].join('\n')
+}
+
+/** Parse explicit authored prose without supplying compatibility or validation claims.
+ * @param value - decoded JSON supplied through --prose.
+ * @returns complete English and Chinese section text.
+ */
+export function parsePersistenceProse(value: unknown): PersistenceChangeProsePair {
+  const pair = record(value, 'persistence prose')
+  keys(pair, ['en', 'zh'], 'persistence prose')
+  for (const locale of ['en', 'zh']) {
+    const sections = record(pair[locale], `persistence prose ${locale}`)
+    keys(sections, ['summary', 'compatibility', 'verification'], `persistence prose ${locale}`)
+    for (const [name, value] of Object.entries(sections)) {
+      const text = textValue(value, `${locale}.${name}`)
+      if (text.trim().length === 0 || text.includes(EXPLANATION_PLACEHOLDER) || text.includes(EVIDENCE_PLACEHOLDER)) {
+        throw new Error(`${locale}.${name} requires authored prose without scaffold placeholders`)
+      }
+    }
+  }
+  return pair as unknown as PersistenceChangeProsePair
+}
+
+function updateDocument(source: string, change: PersistenceChangeRecord, chinese: boolean, prose?: PersistenceChangeProse): string {
+  source = source.replace(/^```yaml persistence-change[^\S\n]*\n[\s\S]*?^```[^\S\n]*$/mu, machineBlock(change))
+  if (prose === undefined) return source
+  const headings = chinese ? ['概述', '兼容性', '验证'] : ['Summary', 'Compatibility', 'Verification']
+  for (const [index, text] of [prose.summary, prose.compatibility, prose.verification].entries()) {
+    const lines = source.split('\n')
+    const heading = `## ${headings[index]}`
+    const start = lines.indexOf(heading)
+    if (start < 0 || lines.lastIndexOf(heading) !== start) throw new Error(`--prose requires one ${heading} section in the existing record`)
+    let end = lines.findIndex((line, lineIndex) => lineIndex > start && /^##? /u.test(line))
+    if (end < 0) end = lines.length
+    let anchor = end
+    while (anchor > start + 1 && lines[anchor - 1] === '') anchor -= 1
+    if (/^<a id="[^"]+"><\/a>$/u.test(lines[anchor - 1] ?? '')) end = anchor - 1
+    lines.splice(start + 1, end - start - 1, '', text.trim(), '')
+    source = lines.join('\n')
+  }
+  return source
+}
+
+function commandOperation(args: readonly string[]): CommandResult['operation'] {
+  if (args.some(arg => arg === '--baseline' || arg.startsWith('--baseline='))) return 'baseline'
+  if (args.some(arg => arg === '--record' || arg.startsWith('--record='))) return 'record'
+  if (args.some(arg => arg === '--update' || arg.startsWith('--update='))) return 'update'
+  return 'check'
+}
+
+function executeCommand(
+  args: readonly string[], root: string, extract: (root: string) => PersistenceSchemaInventory,
+  artifacts: (root: string, current: PersistenceSchemaInventory) => readonly PersistenceArtifact[],
+): CommandResult {
+  const { values } = parseArgs({ args: [...args], strict: true, allowPositionals: false, options: {
+    check: { type: 'boolean' }, baseline: { type: 'string' }, record: { type: 'string' }, update: { type: 'string' },
+    decision: { type: 'string' }, root: { type: 'string' }, prose: { type: 'string' }, json: { type: 'boolean' },
+  } })
+  if (values.root !== undefined) root = resolve(values.root)
+  const selected = [values.check === true, values.baseline !== undefined, values.record !== undefined, values.update !== undefined]
+  if (selected.filter(Boolean).length > 1) throw new Error('choose exactly one of --check, --baseline ID, --record ID, or --update ID')
+  if (values.record === undefined && values.update === undefined && values.decision !== undefined) throw new Error('--decision requires --record or --update')
+  const operation = commandOperation(args)
+  if (operation === 'check' && values.prose !== undefined) throw new Error('--prose requires --baseline, --record, or --update')
+  const prose = values.prose === undefined ? undefined : parsePersistenceProse(JSON.parse(readFileSync(resolve(root, values.prose), 'utf8')))
+  const current = parsePersistenceSnapshot(extract(root))
+  if (operation === 'check') {
+    const history = verifyPersistenceChanges(root, current)
+    return { schemaVersion: 1, ok: true, operation,
+      message: `persistence changes: ${current.roots.length} roots match ${history.entries.length} history records.`, changes: [], roots: [], files: [] }
+  }
+  const baseline = operation === 'baseline'
+  const update = operation === 'update'
+  const id = identifier(values.baseline ?? values.record ?? values.update, 'record id')
+  const directory = join(root, HISTORY_DIRECTORY)
+  if (baseline && existsSync(directory) && readdirSync(directory).some(file => file.endsWith('.schema.json') || ID_PATTERN.test(file.replace(/\.md$/u, '')))) throw new Error('persistence baseline already exists; baseline creation cannot reset history')
+  if (values.decision !== undefined && values.decision !== 'same-version' && values.decision !== 'version-bump') {
+    throw new Error('--decision must be same-version or version-bump')
+  }
+  const entries = baseline ? [] : readPersistenceEntries(root, update ? id : undefined)
+  const existing = update ? entries.find(entry => entry.record.id === id) : undefined
+  if (update && existing === undefined) throw new Error(`${id}: cannot update a missing acknowledgement`)
+  if (existing?.record.baseline === true) throw new Error('cannot update the persistence baseline')
+  if (existing !== undefined && entries.some(entry => entry.record.changes.some(change => change.previous === id))) {
+    throw new Error(`${id}: cannot update an acknowledgement with successors`)
+  }
+  const prior = entries.filter(entry => entry !== existing)
+  const history = baseline ? undefined : validatePersistenceHistory(prior)
+  const changed = baseline ? current.roots.map(root => root.key) : currentDifferences(history as PersistenceHistory, current)
+  if (changed.length === 0) throw new Error('no persistence type changes to acknowledge')
+  const differences = history === undefined ? [] : reportedDifferences(history, current)
+  const decision = values.decision ?? (differences.some(change => change.requiresVersionBump) ? 'version-bump' : 'same-version')
+  const roots = current.roots.filter(root => changed.includes(root.key))
+  const change: PersistenceChangeRecord = { schemaVersion: 1, id, baseline, changes: changed.sort().map(key => ({
+    root: key, previous: history?.tips.get(key)?.id ?? null,
+    after: roots.find(root => root.key === key)?.digest ?? null, decision,
+  })) }
+  const snapshot: PersistenceSchemaInventory = { formatVersion: 1, roots, types: [] }
+  validatePersistenceHistory([...prior, { record: change, snapshot }])
+  const document = (chinese: boolean): string => {
+    const supplied = chinese ? prose?.zh : prose?.en
+    return existing === undefined ? scaffold(change, chinese, supplied)
+      : updateDocument(readFileSync(join(directory, `${id}${chinese ? '.zh' : ''}.md`), 'utf8'), change, chinese, supplied)
+  }
+  const english = document(false)
+  const chinese = document(true)
+  parseDocument(english, `${id}.md`, prose === undefined && existing === undefined)
+  parseDocument(chinese, `${id}.md`, prose === undefined && existing === undefined)
+  const recordFiles = [
+    ...renderPersistencePair(root, `${HISTORY_DIRECTORY}/${id}.md`, english, chinese),
+    { path: `${HISTORY_DIRECTORY}/${id}.schema.json`, content: JSON.stringify(snapshot, null, 2) + '\n' },
+  ]
+  if (!update && recordFiles.some(file => existsSync(join(root, file.path)))) throw new Error(`${id}: acknowledgement file already exists`)
+  const outputs = [...artifacts(root, current), ...recordFiles]
+  for (const file of outputs) mkdirSync(resolve(root, file.path, '..'), { recursive: true })
+  for (const file of outputs) writeFileSync(resolve(root, file.path), file.content, { flag: recordFiles.includes(file) && !update ? 'wx' : 'w' })
+  const completion = baseline
+    ? 'Complete both record documents and refresh their translation pairing.'
+    : `Complete the compatibility and verification prose with --update ${id} --prose FILE.`
+  const message = existing === undefined && prose === undefined
+    ? `Created ${HISTORY_DIRECTORY}/${id}.md and paired schema files. ${completion}`
+    : `${update ? 'Updated' : 'Created'} ${HISTORY_DIRECTORY}/${id}.md; schema artifacts and bilingual pairing are current.`
+  return { schemaVersion: 1, ok: true, operation, recordId: id, message,
+    changes: differences,
+    roots: rootTransitions(history, current), files: outputs.map(file => file.path) }
+}
+
+/** Execute tree-only verification or author an explicit persistence acknowledgement.
+ * @param args - check, baseline, record, or update arguments; --json selects structured output.
+ * @param root - checkout root; defaults to this script's repository.
+ * @param extract - current-source extraction function; fixtures supply their own source reader.
+ * @param artifacts - renderer for current generated artifacts; fixtures may isolate the inventory artifact.
+ * @returns text or one JSON result; JSON failures retain ok:false for the process entry point.
+ */
+export function runPersistenceChanges(
+  args: readonly string[],
+  root: string = resolve(import.meta.dirname, '..'),
+  extract: (root: string) => PersistenceSchemaInventory = extractPersistenceSchema,
+  artifacts: (root: string, current: PersistenceSchemaInventory) => readonly PersistenceArtifact[] = persistenceCatalogArtifacts,
+): string {
+  try {
+    const result = executeCommand(args, root, extract, artifacts)
+    return args.includes('--json') ? JSON.stringify(result) : result.message
+  } catch (error: unknown) {
+    if (!args.includes('--json')) throw error
+    const result: CommandResult = { schemaVersion: 1, ok: false, operation: commandOperation(args),
+      message: error instanceof Error ? error.message : String(error),
+      code: error instanceof PersistenceChangeFailure ? error.code : 'verification-failed',
+      changes: error instanceof PersistenceChangeFailure ? error.changes : [],
+      roots: error instanceof PersistenceChangeFailure ? error.roots : [], files: [] }
+    return JSON.stringify(result)
+  }
+}
+
+if (process.argv[1] !== undefined && resolve(process.argv[1]) === import.meta.filename) {
+  try {
+    const output = runPersistenceChanges(process.argv.slice(2))
+    console.log(output)
+    if (process.argv.includes('--json') && !(JSON.parse(output) as { ok: boolean }).ok) process.exitCode = 1
+  } catch (error: unknown) {
+    console.error(error instanceof Error ? error.message : String(error))
+    process.exitCode = 1
+  }
+}

scripts/persistence-formats.spec.ts

@@ -0,0 +1,476 @@
+/** Format reference coverage follows the writer version and retains complete historical schemas. */
+
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { dump } from 'js-yaml'
+import { afterEach, describe, expect, it } from 'vitest'
+import { loadPersistenceFormats, runPersistenceFormats } from './persistence-formats.ts'
+import { parseHistoricalPersistenceSnapshot } from './persistence-changes.ts'
+import { canonicalizeSchema, schemaDigest } from './persistence-schema-model.ts'
+import type { PersistenceRoot, PersistenceSchemaInventory, PersistenceType, SchemaNode } from './persistence-schema-model.ts'
+
+const temporary: string[] = []
+afterEach(() => { for (const root of temporary.splice(0)) rmSync(root, { recursive: true, force: true }) })
+
+function rootSchema(metadata: Omit<PersistenceRoot, 'schema' | 'digest'>, nodes: readonly SchemaNode[]): PersistenceRoot {
+  const schema = canonicalizeSchema(nodes, 0)
+  return { ...metadata, schema, digest: schemaDigest(schema) }
+}
+
+function completeInventory(roots: readonly PersistenceRoot[]): PersistenceSchemaInventory {
+  const types = new Map<string, PersistenceType>()
+  for (const root of roots) {
+    root.schema.nodes.forEach((_, index) => {
+      const schema = canonicalizeSchema(root.schema.nodes, index)
+      const digest = schemaDigest(schema)
+      types.set(digest, { digest, schema, names: [], sources: [] })
+    })
+  }
+  return { formatVersion: 1, roots, types: [...types.values()] }
+}
+
+function header(key: string, version: number | 'number', optional = false): PersistenceRoot {
+  return rootSchema({ key, kind: 'header' }, [
+    { kind: 'object', indices: [], properties: [{ name: 'version', type: 1, optional }] },
+    version === 'number' ? { kind: 'primitive', type: 'number' } : { kind: 'literal', value: version },
+  ])
+}
+
+function inventory(version: number): PersistenceSchemaInventory {
+  return completeInventory([
+    header('SessionHeader', version), header('JsonlHeaderLine', 'number'),
+    rootSchema({ key: 'SessionEventEnvelope', kind: 'envelope' }, [{ kind: 'object', indices: [], properties: [] }]),
+    rootSchema({ key: 'event:example/value', kind: 'event', event: 'example/value', surface: false }, [
+      { kind: 'object', indices: [], properties: [{ name: 'type', type: 1, optional: false }, { name: 'data', type: 2, optional: false }] },
+      { kind: 'literal', value: 'example/value' }, { kind: 'primitive', type: 'string' },
+    ]),
+  ])
+}
+
+function write(root: string, path: string, content: string): void {
+  writeFileSync(join(root, path), content)
+}
+
+function schemaPath(version: number, currentVersion: number): string {
+  return version === currentVersion ? 'docs/persistence-schema.json' : `docs/persistence-changes/historical-formats/v${version}.schema.json`
+}
+
+function replaceSnapshot(root: string, version: number, currentVersion: number, snapshot: PersistenceSchemaInventory): void {
+  write(root, schemaPath(version, currentVersion), JSON.stringify(snapshot))
+}
+
+function saveReference(root: string, version: number, currentVersion: number, snapshot = inventory(version)): void {
+  const current = version === currentVersion
+  const filename = current ? 'persistence-catalog' : `persistence-changes/historical-formats/v${version}`
+  const schemaName = current ? 'persistence-schema.json' : `v${version}.schema.json`
+  const record = {
+    schemaVersion: 1, sessionFormatVersion: version,
+    source: version === 1 ? { pullRequest: 3349 } : { tag: 'dsh-v0.1.0-rc.5' },
+    roots: Object.fromEntries(snapshot.roots.map(root => [root.key, root.digest])),
+  }
+  const lines = [
+    ...current ? [] : ['---', 'kind: persistence-format', '---', '', '```yaml persistence-format', dump(record).trimEnd(), '```', ''],
+    `# Session format v${version}`, '', `[Inventory](${schemaName})`, '', '| Root | Kind | SHA-256 |', '|---|---|---|',
+    ...snapshot.roots.map(root => `| \`${root.key}\` | ${root.kind} | \`${root.digest}\` |`), '',
+  ]
+  for (const suffix of ['.md', '.zh.md']) write(root, `docs/${filename}${suffix}`, lines.join('\n'))
+  replaceSnapshot(root, version, currentVersion, snapshot)
+}
+
+function fixture(currentVersion = 3): string {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-persistence-formats-'))
+  temporary.push(root)
+  mkdirSync(join(root, 'packages/core/session/src'), { recursive: true })
+  mkdirSync(join(root, 'docs/persistence-changes/historical-formats'), { recursive: true })
+  write(root, 'packages/core/session/src/types.ts', `export const SESSION_FORMAT_VERSION = ${currentVersion} as const\n`)
+  for (let version = 0; version <= currentVersion; version += 1) saveReference(root, version, currentVersion)
+  return root
+}
+
+function edit(root: string, path: string, from: string, to: string): void {
+  const source = readFileSync(join(root, path), 'utf8')
+  expect(source).toContain(from)
+  write(root, path, source.replace(from, to))
+}
+
+function editPair(root: string, version: number, from: string, to: string): void {
+  for (const suffix of ['.md', '.zh.md']) edit(root, `docs/persistence-changes/historical-formats/v${version}${suffix}`, from, to)
+}
+
+function prepareFacts(root: string, currentVersion = 3): void {
+  for (const suffix of ['.md', '.zh.md']) {
+    for (let version = 0; version < currentVersion; version += 1) {
+      const path = `docs/persistence-changes/historical-formats/v${version}${suffix}`
+      const switcher = suffix === '.md' ? `English | [中文](v${version}.zh.md)` : `[English](v${version}.md) | 中文`
+      write(root, path, readFileSync(join(root, path), 'utf8') + `\n${switcher}\n\n<!-- persistence-format-schema:start -->\n\nPending schemas.\n\n<!-- persistence-format-schema:end -->\n`)
+    }
+    const switcher = suffix === '.md' ? 'English | [中文](README.zh.md)' : '[English](README.md) | 中文'
+    write(root, `docs/persistence-changes/historical-formats/README${suffix}`, `# Session formats\n\n${switcher}\n\nAuthored context.\n\n<!-- persistence-format-index:start -->\n\nPending formats.\n\n<!-- persistence-format-index:end -->\n`)
+  }
+}
+
+describe('archive current persistence format', () => {
+  it('keeps every reachable type and drops extractor-retained types and source line numbers', () => {
+    const root = fixture()
+    const original = inventory(3)
+    const sources = [
+      'packages/example/src/types.ts:12', 'packages/other/src/types.ts:8:2', 'packages/example/src/types.ts:34:5',
+      'packages/plain/src/types.ts', 'packages/fragment/src/types.ts#L8', 'packages/fragment/src/types.ts#L8-L12',
+    ]
+    const types = original.types.map(type => ({ ...type, names: ['Example'], sources }))
+    const schema = canonicalizeSchema([{ kind: 'literal', value: 'unreferenced' }], 0)
+    replaceSnapshot(root, 3, 3, { ...original, types: [...types, { schema, digest: schemaDigest(schema), names: [], sources: [] }] })
+    const before = readFileSync(join(root, 'docs/persistence-schema.json'), 'utf8')
+
+    expect(runPersistenceFormats(['--archive', '3'], root)).toBe('Archived Session format v3 to docs/persistence-changes/historical-formats/v3.schema.json.')
+    const serialized = readFileSync(join(root, 'docs/persistence-changes/historical-formats/v3.schema.json'), 'utf8')
+    const archived = parseHistoricalPersistenceSnapshot(JSON.parse(serialized))
+    expect(archived).toEqual({
+      ...original,
+      types: types.map(type => ({ ...type, sources: [
+        'packages/example/src/types.ts', 'packages/other/src/types.ts', 'packages/plain/src/types.ts', 'packages/fragment/src/types.ts',
+      ] })),
+    })
+    expect(serialized).toBe(JSON.stringify(archived, null, 2) + '\n')
+    expect(readFileSync(join(root, 'docs/persistence-schema.json'), 'utf8')).toBe(before)
+    expect(existsSync(join(root, 'docs/persistence-changes/historical-formats/v3.md'))).toBe(false)
+
+    saveReference(root, 3, 4, archived)
+    write(root, 'packages/core/session/src/types.ts', 'export const SESSION_FORMAT_VERSION = 4 as const\n')
+    saveReference(root, 4, 4)
+    expect(loadPersistenceFormats(root).entries[3]?.inventory).toEqual(archived)
+  })
+
+  it('creates the first archive directory and honors --root', () => {
+    const root = fixture(0)
+    rmSync(join(root, 'docs/persistence-changes/historical-formats'), { recursive: true })
+    expect(runPersistenceFormats(['--root', root, '--archive', '0'])).toBe('Archived Session format v0 to docs/persistence-changes/historical-formats/v0.schema.json.')
+    expect(JSON.parse(readFileSync(join(root, 'docs/persistence-changes/historical-formats/v0.schema.json'), 'utf8'))).toEqual(inventory(0))
+  })
+
+  it.each(['-1', '1.5', '01', '3junk', '9007199254740992'])('rejects an invalid archive version %s', (version) => {
+    const root = fixture()
+    expect(() => runPersistenceFormats([`--archive=${version}`], root)).toThrow('--archive must be a non-negative safe integer')
+    expect(existsSync(join(root, 'docs/persistence-changes/historical-formats/v3.schema.json'))).toBe(false)
+  })
+
+  it.each(['2', '4'])('rejects archive v%s when the current writer is v3', (version) => {
+    const root = fixture()
+    expect(() => runPersistenceFormats(['--archive', version], root)).toThrow(`Cannot archive v${version}: current writer is v3`)
+    expect(existsSync(join(root, 'docs/persistence-changes/historical-formats/v3.schema.json'))).toBe(false)
+  })
+
+  it('refuses to overwrite an existing archive', () => {
+    const root = fixture()
+    write(root, 'docs/persistence-changes/historical-formats/v3.schema.json', 'Retained history.\n')
+    expect(() => runPersistenceFormats(['--archive', '3'], root)).toThrow('docs/persistence-changes/historical-formats/v3.schema.json already exists')
+    expect(readFileSync(join(root, 'docs/persistence-changes/historical-formats/v3.schema.json'), 'utf8')).toBe('Retained history.\n')
+  })
+
+  it('rejects --archive with --write before writing', () => {
+    const root = fixture()
+    expect(() => runPersistenceFormats(['--archive', '3', '--write'], root)).toThrow('--archive and --write cannot be combined')
+    expect(existsSync(join(root, 'docs/persistence-changes/historical-formats/v3.schema.json'))).toBe(false)
+  })
+
+  it.each(['invalid-json', 'digest-drift', 'missing-type', 'missing-source-metadata', 'outdated-header'])('rejects %s before creating an archive', (variant) => {
+    const root = fixture()
+    const original = inventory(3)
+    if (variant === 'invalid-json') write(root, 'docs/persistence-schema.json', '{')
+    else if (variant === 'digest-drift') replaceSnapshot(root, 3, 3, { ...original, roots: [{ ...original.roots[0]!, digest: '0'.repeat(64) }, ...original.roots.slice(1)] })
+    else if (variant === 'missing-type') replaceSnapshot(root, 3, 3, { ...original, types: original.types.slice(1) })
+    else if (variant === 'missing-source-metadata') edit(root, 'docs/persistence-schema.json', ',"sources":[]', '')
+    else replaceSnapshot(root, 3, 3, inventory(2))
+    expect(() => runPersistenceFormats(['--archive', '3'], root)).toThrow(variant === 'invalid-json' ? SyntaxError
+      : variant === 'digest-drift' ? 'schema digest mismatch' : variant === 'missing-type' ? 'cover every reachable type'
+        : variant === 'missing-source-metadata' ? 'missing field sources' : 'SessionHeader.version must match')
+    expect(existsSync(join(root, 'docs/persistence-changes/historical-formats/v3.schema.json'))).toBe(false)
+  })
+})
+
+describe('complete persistence format references', () => {
+  it.each(['.md', '.zh.md'])('rejects source coordinates in authored format evidence in %s', (suffix) => {
+    const root = fixture()
+    const path = `docs/persistence-changes/historical-formats/v1${suffix}`
+    const original = readFileSync(join(root, path), 'utf8')
+    for (const position of [':36', ':36:2', '#L36', '#L36-L38']) {
+      write(root, path, original + `\nSource: \`packages/core/session/src/types.ts${position}\`.\n`)
+      expect(() => loadPersistenceFormats(root)).toThrow('historical source references must omit line numbers')
+    }
+    write(root, path, original + '\nSource: `packages/core/session/src/types.ts`.\n')
+    expect(loadPersistenceFormats(root).entries).toHaveLength(4)
+  })
+
+  it('loads a contiguous archive and the current catalog without Git or historical package sources', () => {
+    const formats = loadPersistenceFormats(fixture())
+    expect(formats.currentVersion).toBe(3)
+    expect(formats.entries.map(entry => entry.version)).toEqual([0, 1, 2, 3])
+    expect(formats.entries[0]?.source).toEqual({ tag: 'dsh-v0.1.0-rc.5' })
+    expect(formats.entries[1]?.source).toEqual({ pullRequest: 3349 })
+    expect(formats.entries[3]).toMatchObject({ document: 'docs/persistence-catalog.md', schemaPath: 'docs/persistence-schema.json' })
+    expect(formats.entries[3]?.source).toBeUndefined()
+  })
+
+  it('accepts a version-zero writer without a historical directory', () => {
+    const root = fixture(0)
+    rmSync(join(root, 'docs/persistence-changes/historical-formats'), { recursive: true })
+    expect(loadPersistenceFormats(root).entries).toHaveLength(1)
+  })
+
+  it.each(['.md', '.zh.md', '.schema.json'])('requires every historical companion %s', (suffix) => {
+    const root = fixture()
+    rmSync(join(root, `docs/persistence-changes/historical-formats/v1${suffix}`))
+    expect(() => loadPersistenceFormats(root)).toThrow(`missing persistence format artifact v1${suffix}`)
+  })
+
+  it('rejects a gap even when all remaining versions have complete companions', () => {
+    const root = fixture()
+    for (const suffix of ['.md', '.zh.md', '.schema.json']) rmSync(join(root, `docs/persistence-changes/historical-formats/v1${suffix}`))
+    expect(() => loadPersistenceFormats(root)).toThrow('v1: missing persistence format artifact')
+  })
+
+  it.each(['persistence-catalog.md', 'persistence-catalog.zh.md', 'persistence-schema.json'])('requires the current reference artifact %s', (filename) => {
+    const root = fixture()
+    rmSync(join(root, `docs/${filename}`))
+    expect(() => loadPersistenceFormats(root)).toThrow(`missing persistence format artifact docs/${filename}`)
+  })
+
+  it('requires a formerly current archive when the writer advances', () => {
+    const root = fixture()
+    write(root, 'packages/core/session/src/types.ts', 'export const SESSION_FORMAT_VERSION = 4 as const\n')
+    saveReference(root, 4, 4)
+    expect(() => loadPersistenceFormats(root)).toThrow('v3: missing persistence format artifact')
+    saveReference(root, 3, 4)
+    expect(loadPersistenceFormats(root).entries.map(entry => entry.version)).toEqual([0, 1, 2, 3, 4])
+  })
+
+  it.each(['v3.md', 'v9.schema.json', 'v01.md', 'v-1.md', 'v2.schema.yaml', 'v3.i18n.yaml'])('rejects unexpected or duplicate format filename %s', (filename) => {
+    const root = fixture()
+    write(root, `docs/persistence-changes/historical-formats/${filename}`, '{}')
+    expect(() => loadPersistenceFormats(root)).toThrow(`unexpected persistence format artifact ${filename}`)
+  })
+
+  it('rejects bilingual declarations that differ', () => {
+    const root = fixture()
+    edit(root, 'docs/persistence-changes/historical-formats/v1.zh.md', 'pullRequest: 3349', 'pullRequest: 3397')
+    expect(() => loadPersistenceFormats(root)).toThrow('bilingual machine records differ')
+  })
+
+  it.each([
+    ['kind: persistence-format', 'kind: persistence-release', 'frontmatter kind'],
+    ['sessionFormatVersion: 1', 'sessionFormatVersion: 0', 'must match its filename'],
+    ['schemaVersion: 1', 'schemaVersion: 2', 'unsupported persistence format record schema version'],
+    ['pullRequest: 3349', 'pullRequest: 0', 'positive integer'],
+    ['pullRequest: 3349', 'pullRequest: 1.5', 'positive integer'],
+    ['pullRequest: 3349', 'pullRequest: 3349\n  tag: dsh-v0.1.0', 'expected fields'],
+    ['pullRequest: 3349', 'other: 3349', 'expected fields'],
+    ['source:\n  pullRequest: 3349', 'source: null', 'expected an object'],
+    ['schemaVersion: 1', 'schemaVersion: 1\nunknown: true', 'expected fields'],
+  ])('rejects inconsistent machine data: %s', (from, to, error) => {
+    const root = fixture()
+    editPair(root, 1, from, to)
+    expect(() => loadPersistenceFormats(root)).toThrow(error)
+  })
+
+  it('rejects a source tag outside the DSH release namespace', () => {
+    const root = fixture()
+    editPair(root, 0, 'tag: dsh-v0.1.0-rc.5', 'tag: latest')
+    expect(() => loadPersistenceFormats(root)).toThrow('invalid source tag')
+  })
+
+  it.each(['missing', 'extra', 'wrong-digest'])('rejects a %s recorded root', (variant) => {
+    const root = fixture()
+    const digest = inventory(1).roots[0]!.digest
+    const from = variant === 'extra' ? 'roots:\n' : `  SessionHeader: ${digest}\n`
+    const to = variant === 'missing' ? '' : variant === 'extra' ? `roots:\n  event:undeclared: ${'f'.repeat(64)}\n`
+      : `  SessionHeader: ${'f'.repeat(64)}\n`
+    editPair(root, 1, from, to)
+    expect(() => loadPersistenceFormats(root)).toThrow('recorded roots do not match the complete schema inventory')
+  })
+
+  it.each(['unknown-key', 'invalid-digest', 'duplicate-key', 'not-a-mapping'])('rejects invalid recorded roots: %s', (variant) => {
+    const root = fixture()
+    const digest = inventory(1).roots[0]!.digest
+    const from = variant === 'not-a-mapping' ? dump({ roots: Object.fromEntries(inventory(1).roots.map(root => [root.key, root.digest])) })
+      : `  SessionHeader: ${digest}\n`
+    const to = variant === 'unknown-key' ? `  unknown: ${digest}\n` : variant === 'invalid-digest' ? '  SessionHeader: invalid\n'
+      : variant === 'duplicate-key' ? from + from : 'roots: []\n'
+    editPair(root, 1, from, to)
+    expect(() => loadPersistenceFormats(root)).toThrow(variant === 'duplicate-key' ? 'duplicated mapping key'
+      : variant === 'not-a-mapping' ? 'roots must be a mapping' : 'invalid recorded root')
+  })
+
+  it.each(['missing', 'duplicate'])('rejects a %s machine block', (variant) => {
+    const root = fixture()
+    for (const suffix of ['.md', '.zh.md']) {
+      const path = `docs/persistence-changes/historical-formats/v1${suffix}`
+      const text = readFileSync(join(root, path), 'utf8')
+      write(root, path, variant === 'missing' ? text.replace('```yaml persistence-format', '```yaml') : text + '\n```yaml persistence-format\n{}\n```\n')
+    }
+    expect(() => loadPersistenceFormats(root)).toThrow('expected exactly one persistence-format machine record')
+  })
+
+  it.each(['SessionHeader', 'JsonlHeaderLine', 'SessionEventEnvelope', 'event:example/value'])('rejects an inventory missing %s', (key) => {
+    const root = fixture()
+    replaceSnapshot(root, 1, 3, completeInventory(inventory(1).roots.filter(root => root.key !== key)))
+    expect(() => loadPersistenceFormats(root)).toThrow(key.startsWith('event:') ? 'must include an event root' : `missing schema root ${key}`)
+  })
+
+  it.each([0, 1, 2, 3])('rejects a mismatched header version at v%s', (version) => {
+    const root = fixture()
+    replaceSnapshot(root, version, 3, completeInventory(inventory(version).roots.map(root => root.key === 'SessionHeader' ? header(root.key, version + 1) : root)))
+    expect(() => loadPersistenceFormats(root)).toThrow('SessionHeader.version must match')
+  })
+
+  it('retains historical number declarations but requires the current logical header literal', () => {
+    const root = fixture()
+    for (const version of [0, 1, 2]) {
+      saveReference(root, version, 3, completeInventory(inventory(version).roots.map(root => root.key === 'SessionHeader' ? header(root.key, 'number') : root)))
+    }
+    expect(loadPersistenceFormats(root).entries).toHaveLength(4)
+    replaceSnapshot(root, 3, 3, completeInventory(inventory(3).roots.map(root => root.key === 'SessionHeader' ? header(root.key, 'number') : root)))
+    expect(() => loadPersistenceFormats(root)).toThrow('SessionHeader.version must match the current writer version')
+  })
+
+  it.each(['SessionHeader', 'JsonlHeaderLine'])('requires a present %s version property', (key) => {
+    const root = fixture()
+    replaceSnapshot(root, 1, 3, completeInventory(inventory(1).roots.map(root => root.key === key ? header(key, 1, true) : root)))
+    expect(() => loadPersistenceFormats(root)).toThrow(`${key}.version must match`)
+  })
+
+  it('uses historical surface rules only for historical references', () => {
+    const root = fixture()
+    const event = rootSchema({ key: 'event:example/value', kind: 'event', event: 'example/value', surface: true }, [
+      { kind: 'object', indices: [], properties: [
+        { name: 'type', type: 1, optional: false }, { name: 'surfaceOp', type: 2, optional: true },
+      ] },
+      { kind: 'literal', value: 'example/value' }, { kind: 'primitive', type: 'string' },
+    ])
+    saveReference(root, 1, 3, completeInventory(inventory(1).roots.map(root => root.kind === 'event' ? event : root)))
+    expect(loadPersistenceFormats(root).entries).toHaveLength(4)
+    replaceSnapshot(root, 3, 3, completeInventory(inventory(3).roots.map(root => root.kind === 'event' ? event : root)))
+    expect(() => loadPersistenceFormats(root)).toThrow('surface metadata does not match its schema')
+  })
+
+  it.each(['missing', 'duplicate', 'extra'])('rejects %s reachable type coverage', (variant) => {
+    const root = fixture()
+    const original = inventory(1)
+    const extraSchema = canonicalizeSchema([{ kind: 'literal', value: 'unreferenced' }], 0)
+    const types = variant === 'missing' ? original.types.slice(1)
+      : variant === 'duplicate' ? [...original.types, original.types[0]!]
+        : [...original.types, { schema: extraSchema, digest: schemaDigest(extraSchema), names: [], sources: [] }]
+    replaceSnapshot(root, 1, 3, { ...original, types })
+    expect(() => loadPersistenceFormats(root)).toThrow(variant === 'missing' ? 'cover every reachable type' : variant === 'duplicate' ? 'duplicate schema type' : 'unreferenced schema type')
+  })
+
+  it('permits extractor-retained unreachable types only in the current inventory', () => {
+    const root = fixture()
+    const original = inventory(3)
+    const schema = canonicalizeSchema([{ kind: 'literal', value: false }], 0)
+    replaceSnapshot(root, 3, 3, {
+      ...original, types: [...original.types, { schema, digest: schemaDigest(schema), names: [], sources: [] }],
+    })
+    expect(loadPersistenceFormats(root).entries).toHaveLength(4)
+  })
+
+  it.each(['duplicate-root', 'invalid-digest', 'invalid-graph', 'unexpected-field'])('rejects malformed schema inventory: %s', (variant) => {
+    const root = fixture()
+    const original = inventory(1)
+    const first = original.roots[0]!
+    const changed = variant === 'duplicate-root' ? { ...original, roots: [...original.roots, first] }
+      : variant === 'invalid-digest' ? { ...original, roots: [{ ...first, digest: '0'.repeat(64) }, ...original.roots.slice(1)] }
+        : variant === 'invalid-graph' ? { ...original, roots: [{ ...first, schema: { root: 0, nodes: [{ kind: 'array', element: 99 }] } }, ...original.roots.slice(1)] }
+          : { ...original, extra: true }
+    write(root, schemaPath(1, 3), JSON.stringify(changed))
+    expect(() => loadPersistenceFormats(root)).toThrow(variant === 'duplicate-root' ? 'duplicate schema root' : variant === 'invalid-digest' ? 'schema digest mismatch' : variant === 'invalid-graph' ? 'unknown schema node' : 'unknown field extra')
+  })
+
+  it.each(['persistence-changes/historical-formats/v1.md', 'persistence-changes/historical-formats/v1.zh.md', 'persistence-catalog.md', 'persistence-catalog.zh.md'])('requires the matching schema link in %s', (document) => {
+    const root = fixture()
+    const schema = document.startsWith('persistence-changes/historical-formats/') ? 'v1.schema.json' : 'persistence-schema.json'
+    edit(root, `docs/${document}`, `](${schema})`, '](wrong.schema.json)')
+    expect(() => loadPersistenceFormats(root)).toThrow(`missing link to ${schema}`)
+  })
+
+  it.each(['persistence-catalog.md', 'persistence-catalog.zh.md'])('rejects a placeholder current catalog in %s', (document) => {
+    const root = fixture()
+    write(root, `docs/${document}`, '# Placeholder\n\n[Inventory](persistence-schema.json)\n')
+    expect(() => loadPersistenceFormats(root)).toThrow('missing schema index entry for SessionHeader')
+  })
+
+  it('checks generated schema regions and refreshes them without changing the recorded schemas or authored context', () => {
+    const root = fixture()
+    prepareFacts(root)
+    const paths = [0, 1, 2, 3].map(version => schemaPath(version, 3))
+    const before = paths.map(path => readFileSync(join(root, path), 'utf8'))
+    expect(() => runPersistenceFormats([], root)).toThrow('Stale persistence format facts')
+    expect(runPersistenceFormats(['--write'], root)).toContain('Refreshed')
+    expect(runPersistenceFormats([], root)).toBe('Persistence formats: v0 through v3 verified (4 complete references).')
+    expect(paths.map(path => readFileSync(join(root, path), 'utf8'))).toEqual(before)
+    const index = readFileSync(join(root, 'docs/persistence-changes/historical-formats/README.md'), 'utf8')
+    expect(index).toContain('Authored context.')
+    expect(index).toContain('[V1](v1.md) | [JSON](v1.schema.json)')
+    expect(index).toContain('[Current catalog](../../persistence-catalog.md) | [JSON](../../persistence-schema.json)')
+    const translatedIndex = readFileSync(join(root, 'docs/persistence-changes/historical-formats/README.zh.md'), 'utf8')
+    expect(translatedIndex).toContain('[V1](v1.zh.md) | [JSON](v1.schema.json)')
+    expect(translatedIndex).toContain('[当前目录](../../persistence-catalog.zh.md) | [JSON](../../persistence-schema.json)')
+    const english = readFileSync(join(root, 'docs/persistence-changes/historical-formats/v1.md'), 'utf8')
+    expect(english).toContain('pullRequest: 3349')
+    const [visible, collapsed] = english.split('<details>')
+    expect(visible).toContain('\n## Complete schemas\n')
+    expect(visible).toContain('\n### Persistence type fingerprints\n')
+    expect(collapsed).toContain('\n### Resolved persistence types\n')
+    expect(collapsed).toContain('\n#### `SessionHeader`\n')
+    expect(english.match(/^## /gmu)).toHaveLength(1)
+    expect(english.match(/^### /gmu)).toHaveLength(2)
+    expect(english.match(/^#### /gmu)).toHaveLength(inventory(1).types.length)
+    edit(root, 'docs/persistence-changes/historical-formats/v1.md', '<summary>Complete resolved types</summary>', '<summary>Missing definitions</summary>')
+    expect(() => runPersistenceFormats([], root)).toThrow('Stale persistence format facts')
+  })
+
+  it('renders a format index for a current version-zero writer', () => {
+    const root = fixture(0)
+    prepareFacts(root, 0)
+    runPersistenceFormats(['--write'], root)
+    expect(runPersistenceFormats([], root)).toBe('Persistence formats: v0 through v0 verified (1 complete reference).')
+  })
+
+  it.each(['missing', 'stale'])('rejects a %s format pairing record and refreshes it with --write', (variant) => {
+    const root = fixture()
+    prepareFacts(root)
+    runPersistenceFormats(['--write'], root)
+    const sidecar = 'docs/persistence-changes/historical-formats/v1.i18n.yaml'
+    if (variant === 'missing') rmSync(join(root, sidecar))
+    else write(root, sidecar, 'schemaVersion: 1\n')
+    expect(() => runPersistenceFormats([], root)).toThrow(`Stale persistence format facts: ${sidecar}`)
+    runPersistenceFormats(['--write'], root)
+    expect(() => runPersistenceFormats([], root)).not.toThrow()
+  })
+
+  it('refuses to refresh facts until every format reference passes validation', () => {
+    const root = fixture()
+    prepareFacts(root)
+    const index = readFileSync(join(root, 'docs/persistence-changes/historical-formats/README.md'), 'utf8')
+    rmSync(join(root, 'docs/persistence-changes/historical-formats/v1.schema.json'))
+    expect(() => runPersistenceFormats(['--write'], root)).toThrow('missing persistence format artifact')
+    expect(readFileSync(join(root, 'docs/persistence-changes/historical-formats/README.md'), 'utf8')).toBe(index)
+  })
+
+  it('refuses to refresh an archive after an event and all its types are removed from its schema', () => {
+    const root = fixture()
+    const retained = rootSchema({ key: 'event:example/retained', kind: 'event', event: 'example/retained', surface: false }, [
+      { kind: 'object', indices: [], properties: [{ name: 'type', type: 1, optional: false }] },
+      { kind: 'literal', value: 'example/retained' },
+    ])
+    const complete = completeInventory([...inventory(1).roots, retained])
+    saveReference(root, 1, 3, complete)
+    prepareFacts(root)
+    runPersistenceFormats(['--write'], root)
+    const document = 'docs/persistence-changes/historical-formats/v1.md'
+    const before = readFileSync(join(root, document), 'utf8')
+    replaceSnapshot(root, 1, 3, completeInventory(complete.roots.filter(root => root.key !== 'event:example/value')))
+    expect(() => runPersistenceFormats(['--write'], root)).toThrow('recorded roots do not match the complete schema inventory')
+    expect(readFileSync(join(root, document), 'utf8')).toBe(before)
+  })
+})

scripts/persistence-schema-model.spec.ts

@@ -0,0 +1,89 @@
+import { describe, expect, it } from 'vitest'
+import { canonicalizeSchema, isArbitraryJsonSchema, schemaDigest, type SchemaNode } from './persistence-schema-model.ts'
+
+const string: SchemaNode = { kind: 'primitive', type: 'string' }
+const number: SchemaNode = { kind: 'primitive', type: 'number' }
+
+describe('canonical persisted type graphs', () => {
+  it('ignores source ordering and shared versus duplicated subtypes', () => {
+    const left: SchemaNode[] = [
+      { kind: 'object', properties: [{ name: 'b', type: 1, optional: false }, { name: 'a', type: 1, optional: true }], indices: [] }, string,
+    ]
+    const right: SchemaNode[] = [
+      string, string,
+      { kind: 'object', properties: [{ name: 'a', type: 0, optional: true }, { name: 'b', type: 1, optional: false }], indices: [] },
+    ]
+    expect(canonicalizeSchema(left, 0)).toEqual(canonicalizeSchema(right, 2))
+  })
+
+  it('minimizes differently factored recursive aliases to the same graph', () => {
+    const self: SchemaNode[] = [
+      { kind: 'object', properties: [{ name: 'next', type: 0, optional: true }, { name: 'value', type: 1, optional: false }], indices: [] }, string,
+    ]
+    const mutual: SchemaNode[] = [
+      { kind: 'object', properties: [{ name: 'value', type: 2, optional: false }, { name: 'next', type: 1, optional: true }], indices: [] },
+      { kind: 'object', properties: [{ name: 'next', type: 0, optional: true }, { name: 'value', type: 3, optional: false }], indices: [] }, string, string,
+    ]
+    const normalized = canonicalizeSchema(self, 0)
+    expect(canonicalizeSchema(mutual, 0)).toEqual(normalized)
+    expect(canonicalizeSchema(normalized.nodes, 0)).toEqual(normalized)
+    mutual[3] = number
+    expect(schemaDigest(canonicalizeSchema(mutual, 0))).not.toBe(schemaDigest(normalized))
+  })
+
+  it('flattens reordered unions and removes structurally equal alternatives', () => {
+    const flat: SchemaNode[] = [{ kind: 'union', types: [1, 2] }, string, number]
+    const factored: SchemaNode[] = [string, number, { kind: 'union', types: [0, 3] }, { kind: 'union', types: [1, 0] }]
+    expect(canonicalizeSchema(flat, 0)).toEqual(canonicalizeSchema(factored, 2))
+    expect(canonicalizeSchema([{ kind: 'union', types: [1, 2] }, string, string], 0)).toEqual(canonicalizeSchema([string], 0))
+    expect(canonicalizeSchema([{ kind: 'union', types: [1, 2] }, { kind: 'literal', value: true }, { kind: 'literal', value: false }], 0))
+      .toEqual(canonicalizeSchema([{ kind: 'primitive', type: 'boolean' }], 0))
+  })
+
+  it('ignores recursive union, field, index signature and graph numbering order together', () => {
+    const original: SchemaNode[] = [
+      { kind: 'union', types: [1, 2, 3] },
+      { kind: 'object', properties: [{ name: 'label', type: 5, optional: false }, { name: 'next', type: 0, optional: true }], indices: [] },
+      { kind: 'array', element: 0 },
+      { kind: 'object', properties: [], indices: [{ key: 5, value: 0 }, { key: 4, value: 1 }] },
+      number,
+      string,
+    ]
+    const reordered: SchemaNode[] = [
+      string,
+      { kind: 'object', properties: [], indices: [{ key: 3, value: 5 }, { key: 0, value: 4 }] },
+      { kind: 'array', element: 4 },
+      number,
+      { kind: 'union', types: [1, 2, 5] },
+      { kind: 'object', properties: [{ name: 'next', type: 4, optional: true }, { name: 'label', type: 0, optional: false }], indices: [] },
+    ]
+    expect(canonicalizeSchema(reordered, 4)).toEqual(canonicalizeSchema(original, 0))
+  })
+
+  it('preserves tuple positions, element absence, and rest elements', () => {
+    const baseline: SchemaNode[] = [{ kind: 'tuple', elements: [{ type: 1, optional: false, rest: false }, { type: 2, optional: true, rest: false }] }, string, number]
+    const reversed: SchemaNode[] = [{ kind: 'tuple', elements: [{ type: 2, optional: false, rest: false }, { type: 1, optional: true, rest: false }] }, string, number]
+    const rest: SchemaNode[] = [{ kind: 'tuple', elements: [{ type: 1, optional: false, rest: false }, { type: 2, optional: false, rest: true }] }, string, number]
+    const digest = schemaDigest(canonicalizeSchema(baseline, 0))
+    expect(schemaDigest(canonicalizeSchema(reversed, 0))).not.toBe(digest)
+    expect(schemaDigest(canonicalizeSchema(rest, 0))).not.toBe(digest)
+  })
+
+  it('recognizes arbitrary recursive JSON structurally and retains its definition', () => {
+    const json: SchemaNode[] = [
+      { kind: 'union', types: [1, 2, 3, 4, 5, 6] },
+      { kind: 'primitive', type: 'null' }, { kind: 'primitive', type: 'boolean' }, number, string,
+      { kind: 'array', element: 0 }, { kind: 'object', properties: [], indices: [{ key: 4, value: 0 }] },
+    ]
+    const schema = canonicalizeSchema(json, 0)
+    expect(isArbitraryJsonSchema(schema)).toBe(true)
+    expect(schema.nodes.some(node => node.kind === 'array' && node.element === 0)).toBe(true)
+    json[0] = { kind: 'union', types: [1, 2, 3, 4, 5] }
+    expect(isArbitraryJsonSchema(canonicalizeSchema(json, 0))).toBe(false)
+  })
+
+  it('rejects missing references and unproductive union cycles', () => {
+    expect(() => canonicalizeSchema([{ kind: 'array', element: 5 }], 0)).toThrow('missing node 5')
+    expect(() => canonicalizeSchema([{ kind: 'union', types: [0] }], 0)).toThrow('union cycle')
+  })
+})

scripts/persistence-schema.ts

@@ -0,0 +1,462 @@
+/** Extract complete persistent Session record types from one source-only compiler program. */
+
+import { readFileSync } from 'node:fs'
+import { dirname, extname, relative, resolve, sep } from 'node:path'
+import ts from 'typescript'
+import { collectLogEvents } from './persistence-catalog-source.ts'
+import {
+  canonicalizeSchema,
+  schemaChildren,
+  schemaDigest,
+  type PersistenceRoot,
+  type PersistenceSchemaInventory,
+  type PersistenceType,
+  type SchemaNode,
+  type SchemaProperty,
+} from './persistence-schema-model.ts'
+
+interface DeclarationMetadata {
+  readonly names: Set<string>
+  readonly sources: Set<string>
+}
+
+interface RootInput {
+  readonly key: string
+  readonly kind: PersistenceRoot['kind']
+  readonly event?: string
+  readonly surface?: boolean
+  readonly node: number
+}
+
+/** A reachable TypeScript type that cannot be represented as a persisted JSON type. */
+export class PersistenceSchemaError extends Error {
+  override name = 'PersistenceSchemaError'
+}
+
+/**
+ * Extract every repository event, its complete envelope, and the Session header.
+ * @param root - repository root, with source paths in tsconfig.host.json.
+ * @returns canonical root fingerprints and all reachable type definitions.
+ */
+export function extractPersistenceSchema(root: string): PersistenceSchemaInventory {
+  root = resolve(root)
+  const events = collectLogEvents(root).sort((left, right) => compare(left.name, right.name))
+  if (events.length === 0) throw new PersistenceSchemaError('persistence schema: no Session events were discovered')
+  const filename = resolve(root, 'scripts/__persistence_schema_roots__.ts')
+  const source = [
+    "import type { SessionHeader, SessionEvent, SessionEventMap, SurfaceEventType } from '@deepseek-ai/dsh-session/types'",
+    'export type HeaderRoot = SessionHeader',
+    'export type SurfaceRoot = SurfaceEventType',
+    'export type EventNamesRoot = keyof SessionEventMap',
+    ...events.map((event, index) => `export type EventRoot${String(index)} = SessionEvent<${JSON.stringify(event.name)}>`),
+    '',
+  ].join('\n')
+  const configPath = resolve(root, 'tsconfig.host.json')
+  const config = ts.readConfigFile(configPath, file => readFileSync(file, 'utf8'))
+  if (config.error !== undefined) throw new PersistenceSchemaError(diagnosticText(config.error))
+  const parsed = ts.parseJsonConfigFileContent(config.config, ts.sys, root)
+  const configErrors = parsed.errors.filter(error => error.code !== 18003)
+  if (configErrors.length > 0) throw new PersistenceSchemaError(configErrors.map(diagnosticText).join('\n'))
+  const options: ts.CompilerOptions = {
+    ...parsed.options,
+    composite: false,
+    incremental: false,
+    noEmit: true,
+    rootDir: root,
+    noUnusedLocals: false,
+    noUnusedParameters: false,
+    // Reachable declaration-file errors must not become opaque any values.
+    skipLibCheck: false,
+    strict: true,
+    exactOptionalPropertyTypes: true,
+  }
+  const host = ts.createCompilerHost(options)
+  const originalGetSourceFile = host.getSourceFile.bind(host)
+  host.getSourceFile = (path, languageVersion, onError, shouldCreateNewSourceFile) =>
+    resolve(path) === filename
+      ? ts.createSourceFile(filename, source, languageVersion, true)
+      : originalGetSourceFile(path, languageVersion, onError, shouldCreateNewSourceFile)
+  const files = [...new Set([
+    ...hostSourceFiles(root, configPath),
+    ...events.map(event => resolve(root, event.source.slice(0, event.source.lastIndexOf(':')))),
+  ])]
+  const program = ts.createProgram({ rootNames: [filename, ...files], options, host })
+  const rootSource = program.getSourceFile(filename)
+  if (rootSource === undefined) throw new PersistenceSchemaError('persistence schema: compiler omitted the requested roots')
+  const diagnostics = [
+    ...program.getOptionsDiagnostics(), ...program.getSyntacticDiagnostics(), ...program.getSemanticDiagnostics(rootSource),
+  ]
+  if (diagnostics.length > 0) throw new PersistenceSchemaError(diagnostics.map(diagnosticText).join('\n'))
+  const checker = program.getTypeChecker()
+  const declarations = new Map(rootSource.statements.filter(ts.isTypeAliasDeclaration)
+    .map(declaration => [declaration.name.text, declaration]))
+  const declaration = (name: string): ts.TypeAliasDeclaration => {
+    const found = declarations.get(name)
+    if (found === undefined) throw new PersistenceSchemaError(`persistence schema: missing compiler root ${name}`)
+    return found
+  }
+  const eventNamesDeclaration = declaration('EventNamesRoot')
+  const compiledEvents = stringLiterals(checker.getTypeFromTypeNode(eventNamesDeclaration.type), 'keyof SessionEventMap')
+  const discoveredEvents = new Set(events.map(event => event.name))
+  const omitted = [...compiledEvents].filter(name => !discoveredEvents.has(name))
+  const uncompiled = [...discoveredEvents].filter(name => !compiledEvents.has(name))
+  if (omitted.length > 0 || uncompiled.length > 0) {
+    throw new PersistenceSchemaError(`persistence schema: compiler and source event discovery disagree; omitted: ${omitted.join(', ')}; uncompiled: ${uncompiled.join(', ')}`)
+  }
+  const surfaceDeclaration = declaration('SurfaceRoot')
+  const surface = stringLiterals(checker.getTypeFromTypeNode(surfaceDeclaration.type), 'SurfaceEventType')
+  for (const name of surface) {
+    if (!events.some(event => event.name === name)) throw new PersistenceSchemaError(`persistence schema: surface event ${name} has no declaration`)
+  }
+  const header = declaration('HeaderRoot')
+  const physicalFile = resolve(root, 'packages/session/session-persistence-jsonl/src/format.ts')
+  const physical = program.getSourceFile(physicalFile)?.statements
+    .filter((node): node is ts.InterfaceDeclaration | ts.TypeAliasDeclaration =>
+      ts.isInterfaceDeclaration(node) || ts.isTypeAliasDeclaration(node))
+    .filter(declaration => declaration.name.text === 'HeaderLine')
+  if (physical?.length !== 1) throw new PersistenceSchemaError('persistence schema: expected one current JSONL HeaderLine declaration')
+  const physicalHeader = physical[0] as ts.InterfaceDeclaration | ts.TypeAliasDeclaration
+  const declarationSources = validateReachableDeclarations(program, root, [...declarations.values(), physicalHeader])
+  const extraction = new SchemaExtractor(root, program, declarationSources)
+  const roots: RootInput[] = [{
+    key: 'SessionHeader',
+    kind: 'header',
+    node: extraction.convert(checker.getTypeFromTypeNode(header.type), header),
+  }]
+  roots.push({ key: 'JsonlHeaderLine', kind: 'header', node: extraction.convert(checker.getTypeAtLocation(physicalHeader), physicalHeader) })
+  const envelopes: number[] = []
+  for (const [index, event] of events.entries()) {
+    const item = declaration(`EventRoot${String(index)}`)
+    const node = extraction.convert(checker.getTypeFromTypeNode(item.type), item)
+    roots.push({ key: `event:${event.name}`, kind: 'event', event: event.name, surface: surface.has(event.name), node })
+    envelopes.push(extraction.envelope(node, event.name))
+  }
+  roots.splice(2, 0, { key: 'SessionEventEnvelope', kind: 'envelope', node: extraction.union(envelopes) })
+  return extraction.inventory(roots)
+}
+
+function hostSourceFiles(root: string, configPath: string, seen = new Set<string>()): string[] {
+  configPath = resolve(configPath)
+  if (seen.has(configPath)) return []
+  seen.add(configPath)
+  const read = ts.readConfigFile(configPath, file => readFileSync(file, 'utf8'))
+  if (read.error !== undefined) throw new PersistenceSchemaError(diagnosticText(read.error))
+  const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, dirname(configPath), undefined, configPath)
+  const errors = parsed.errors.filter(error => error.code !== 18003)
+  if (errors.length > 0) throw new PersistenceSchemaError(errors.map(diagnosticText).join('\n'))
+  return [
+    ...parsed.fileNames.filter(file => /^packages\/[^/]+\/[^/]+\/src\//.test(slash(relative(root, file)))),
+    ...(parsed.projectReferences ?? []).flatMap(reference =>
+      hostSourceFiles(root, extname(reference.path) === '.json' ? reference.path : resolve(reference.path, 'tsconfig.json'), seen)),
+  ]
+}
+
+function validateReachableDeclarations(
+  program: ts.Program,
+  root: string,
+  roots: readonly ts.Node[],
+): ReadonlyMap<ts.Type, readonly ts.Node[]> {
+  const checker = program.getTypeChecker()
+  const visited = new Set<ts.Node>()
+  const declarations = new Map<ts.SourceFile, ts.Node[]>()
+  const definitions = new Map<ts.Type, ts.Node[]>()
+  const visit = (node: ts.Node): void => {
+    if (visited.has(node)) return
+    visited.add(node)
+    const file = node.getSourceFile()
+    if (trackedSource(slash(relative(root, file.fileName)))) {
+      const scopes = declarations.get(file) ?? []
+      scopes.push(node)
+      declarations.set(file, scopes)
+      if (isNamedTypeDeclaration(node) || ts.isTypeLiteralNode(node)) {
+        // Primitive aliases share checker types with unaliased properties.
+        const type = checker.getTypeAtLocation(node)
+        const entries = definitions.get(type) ?? []
+        entries.push(node)
+        definitions.set(type, entries)
+      }
+    }
+    const target = ts.isTypeReferenceNode(node) ? node.typeName
+      : ts.isExpressionWithTypeArguments(node) ? node.expression
+        : ts.isTypeQueryNode(node) ? node.exprName
+          : ts.isImportTypeNode(node) ? node.qualifier
+            : undefined
+    if (target !== undefined) {
+      let symbol = checker.getSymbolAtLocation(target)
+      if (symbol !== undefined && (symbol.flags & ts.SymbolFlags.Alias)) symbol = checker.getAliasedSymbol(symbol)
+      for (const declaration of symbol?.declarations ?? []) {
+        if (trackedSource(slash(relative(root, declaration.getSourceFile().fileName)))) visit(declaration)
+      }
+    }
+    if (ts.isClassDeclaration(node) || ts.isClassExpression(node)) return
+    ts.forEachChild(node, visit)
+  }
+  for (const root of roots) visit(root)
+  const errors = [...declarations].flatMap(([file, scopes]) => program.getSemanticDiagnostics(file)
+    .filter((error) => {
+      const start = error.start
+      return start !== undefined && scopes.some(scope => start >= scope.getStart() && start < scope.end)
+    }))
+  if (errors.length > 0) throw new PersistenceSchemaError(errors.map(diagnosticText).join('\n'))
+  return definitions
+}
+
+class SchemaExtractor {
+  readonly nodes: SchemaNode[] = []
+  private readonly cache = new Map<ts.Type, number>()
+  private readonly declarationMetadata = new Map<number, DeclarationMetadata>()
+
+  private readonly checker: ts.TypeChecker
+
+  constructor(
+    private readonly root: string,
+    program: ts.Program,
+    private readonly declarationSources: ReadonlyMap<ts.Type, readonly ts.Node[]>,
+  ) {
+    this.checker = program.getTypeChecker()
+  }
+
+  convert(type: ts.Type, site: ts.Node): number {
+    const cached = this.cache.get(type)
+    if (cached !== undefined) {
+      this.record(cached, type)
+      return cached
+    }
+    const id = this.nodes.length
+    this.nodes.push({ kind: 'primitive', type: 'never' })
+    this.cache.set(type, id)
+    this.record(id, type)
+    const add = (node: SchemaNode): number => { this.nodes[id] = node; return id }
+    const flags = type.flags
+    if (flags & ts.TypeFlags.Any) {
+      if ((type as ts.Type & { intrinsicName?: string }).intrinsicName === 'error') this.fail(type, site, 'unresolved compiler type')
+      return add({ kind: 'opaque', reason: 'any' })
+    }
+    if (flags & ts.TypeFlags.Unknown) return add({ kind: 'opaque', reason: 'unknown' })
+    if (flags & ts.TypeFlags.Never) return add({ kind: 'primitive', type: 'never' })
+    if (flags & ts.TypeFlags.Null) return add({ kind: 'primitive', type: 'null' })
+    if (flags & ts.TypeFlags.String) return add({ kind: 'primitive', type: 'string' })
+    if (flags & ts.TypeFlags.Number) return add({ kind: 'primitive', type: 'number' })
+    if (flags & ts.TypeFlags.Boolean) return add({ kind: 'primitive', type: 'boolean' })
+    if (flags & ts.TypeFlags.StringLiteral) return add({ kind: 'literal', value: (type as ts.StringLiteralType).value })
+    if (flags & ts.TypeFlags.NumberLiteral) return add({ kind: 'literal', value: (type as ts.NumberLiteralType).value })
+    if (flags & ts.TypeFlags.BooleanLiteral) return add({ kind: 'literal', value: this.checker.typeToString(type) === 'true' })
+    if (type.isUnion()) return add(this.unionNode(type.types.map(member => this.convert(member, site))))
+    if (type.isIntersection()) {
+      const material = type.types.filter(member => !this.phantom(member))
+      for (const member of material) this.rejectClass(member, site)
+      if (material.length === 1) {
+        const target = this.convert(material[0] as ts.Type, site)
+        return add({ kind: 'union', types: [target] })
+      }
+      if (material.length === 0 || material.some(member => (member.flags & ts.TypeFlags.Object) === 0)) {
+        this.fail(type, site, 'unsupported material intersection')
+      }
+      return add(this.object(type, site))
+    }
+    if (this.checker.isTupleType(type)) {
+      const reference = type as ts.TypeReference
+      const target = reference.target as ts.TupleType
+      return add({
+        kind: 'tuple',
+        elements: this.checker.getTypeArguments(reference).map((element, index) => {
+          const flags = target.elementFlags[index] ?? ts.ElementFlags.Required
+          const optional = (flags & ts.ElementFlags.Optional) !== 0
+          const rest = (flags & (ts.ElementFlags.Rest | ts.ElementFlags.Variadic)) !== 0
+          return { type: this.valueType(element, site, optional), optional, rest }
+        }),
+      })
+    }
+    if (this.checker.isArrayType(type) || this.checker.isArrayLikeType(type)) {
+      const element = this.checker.getIndexTypeOfType(type, ts.IndexKind.Number)
+      if (element === undefined) this.fail(type, site, 'array element is unavailable')
+      return add({ kind: 'array', element: this.convert(element, site) })
+    }
+    if (flags & ts.TypeFlags.Object) return add(this.object(type, site))
+    this.fail(type, site, 'type has no supported JSON representation')
+  }
+
+  private valueType(type: ts.Type, site: ts.Node, optional: boolean): number {
+    if (!optional) return this.convert(type, site)
+    const members = (type.isUnion() ? type.types : [type]).filter(member => !(member.flags & ts.TypeFlags.Undefined))
+    return this.union(members.map(member => this.convert(member, site)))
+  }
+
+  private object(type: ts.Type, site: ts.Node): SchemaNode {
+    this.rejectClass(type, site)
+    if (type.getCallSignatures().length > 0 || type.getConstructSignatures().length > 0) this.fail(type, site, 'callable data is not JSON')
+    const properties: SchemaProperty[] = []
+    for (const property of this.checker.getPropertiesOfType(type).sort((left, right) => compare(left.name, right.name))) {
+      if (property.getName().startsWith('__@')) this.fail(type, site, 'symbol-keyed data is not a JSON field')
+      const declaration = property.valueDeclaration ?? property.declarations?.[0] ?? site
+      const propertyType = this.checker.getTypeOfSymbolAtLocation(property, declaration)
+      const optional = (property.flags & ts.SymbolFlags.Optional) !== 0
+      if (optional && (propertyType.isUnion() ? propertyType.types : [propertyType])
+        .every(member => (member.flags & (ts.TypeFlags.Undefined | ts.TypeFlags.Never)) !== 0)) continue
+      const child = this.valueType(propertyType, declaration, optional)
+      properties.push({ name: property.getName(), type: child, optional })
+    }
+    const indices = this.checker.getIndexInfosOfType(type).map(info => ({
+      key: this.convert(info.keyType, site),
+      value: this.convert(info.type, site),
+    }))
+    if (properties.length === 0 && indices.length === 0) this.fail(type, site, 'unconstrained empty object type is not an explicit JSON record')
+    return { kind: 'object', properties, indices }
+  }
+
+  private rejectClass(type: ts.Type, site: ts.Node): void {
+    const symbol = type.getSymbol()
+    if (symbol?.declarations?.some(declaration => ts.isClassDeclaration(declaration) || ts.isClassExpression(declaration))) {
+      this.fail(type, site, 'class instances require an explicit persisted representation')
+    }
+  }
+
+  private phantom(type: ts.Type): boolean {
+    if (!(type.flags & ts.TypeFlags.Object)) return false
+    const properties = this.checker.getPropertiesOfType(type)
+    return properties.length > 0 && properties.every(property => property.getName().startsWith('__@'))
+      && type.getCallSignatures().length === 0 && type.getConstructSignatures().length === 0
+      && this.checker.getIndexInfosOfType(type).length === 0
+  }
+
+  union(types: readonly number[]): number {
+    const node = this.unionNode(types)
+    if (node.kind === 'union' && node.types.length === 1) return node.types[0] as number
+    this.nodes.push(node)
+    return this.nodes.length - 1
+  }
+
+  private unionNode(types: readonly number[]): SchemaNode {
+    if (types.length === 0) return { kind: 'primitive', type: 'never' }
+    return { kind: 'union', types: [...new Set(types)] }
+  }
+
+  envelope(id: number, event: string): number {
+    const node = this.nodes[id] as SchemaNode
+    if (node.kind === 'union') return this.union(node.types.map(type => this.envelope(type, event)))
+    if (node.kind !== 'object') throw new PersistenceSchemaError('persistence schema: SessionEvent must resolve to object alternatives')
+    const tag = node.properties.find(property => property.name === 'type')
+    const data = node.properties.find(property => property.name === 'data')
+    const literal = tag === undefined ? undefined : canonicalizeSchema(this.nodes, tag.type).nodes[0]
+    if (tag?.optional !== false || data?.optional !== false || literal?.kind !== 'literal' || literal.value !== event) {
+      throw new PersistenceSchemaError(`persistence schema: SessionEvent<${JSON.stringify(event)}> must retain its required type and data fields`)
+    }
+    const string = this.nodes.length
+    this.nodes.push({ kind: 'primitive', type: 'string' })
+    const envelope: SchemaNode = {
+      kind: 'object',
+      properties: node.properties.filter(property => property.name !== 'data')
+        .map(property => property.name === 'type' ? { ...property, type: string } : property),
+      indices: node.indices,
+    }
+    this.nodes.push(envelope)
+    return this.nodes.length - 1
+  }
+
+  inventory(inputs: readonly RootInput[]): PersistenceSchemaInventory {
+    const roots = inputs.map((input) => {
+      const schema = canonicalizeSchema(this.nodes, input.node)
+      return {
+        key: input.key,
+        kind: input.kind,
+        ...(input.event === undefined ? {} : { event: input.event }),
+        ...(input.surface === undefined ? {} : { surface: input.surface }),
+        digest: schemaDigest(schema),
+        schema,
+      }
+    })
+    const found = new Set<number>()
+    const paths = new Map<number, Set<string>>()
+    const visit = (id: number, path: string): void => {
+      const names = paths.get(id) ?? new Set<string>()
+      names.add(path)
+      paths.set(id, names)
+      if (found.has(id)) return
+      found.add(id)
+      const node = this.nodes[id] as SchemaNode
+      if (node.kind === 'object') {
+        for (const property of node.properties) visit(property.type, `${path}.${property.name}`)
+        for (const index of node.indices) { visit(index.key, `${path}.[key]`); visit(index.value, `${path}.[value]`) }
+      } else {
+        for (const [index, child] of schemaChildren(node).entries()) visit(child, `${path}[${String(index)}]`)
+      }
+    }
+    for (const input of inputs) visit(input.node, input.key)
+    const types = new Map<string, { schema: PersistenceType['schema']; names: Set<string>; sources: Set<string> }>()
+    for (const id of found) {
+      const schema = canonicalizeSchema(this.nodes, id)
+      const digest = schemaDigest(schema)
+      const item = types.get(digest) ?? { schema, names: new Set<string>(), sources: new Set<string>() }
+      const declarationMetadata = this.declarationMetadata.get(id)
+      for (const name of declarationMetadata?.names ?? []) item.names.add(name)
+      for (const source of declarationMetadata?.sources ?? []) item.sources.add(source)
+      const kind = schema.nodes[0]?.kind
+      if (kind !== 'primitive' && kind !== 'literal' && (declarationMetadata === undefined || declarationMetadata.names.size === 0)) {
+        for (const path of paths.get(id) ?? []) item.names.add(path)
+      }
+      types.set(digest, item)
+    }
+    return {
+      formatVersion: 1,
+      roots,
+      types: [...types].sort(([left], [right]) => compare(left, right)).map(([digest, item]) => ({
+        digest,
+        schema: item.schema,
+        names: [...item.names].sort(compare),
+        sources: [...item.sources].sort(compare),
+      })),
+    }
+  }
+
+  private record(id: number, type: ts.Type): void {
+    const item = this.declarationMetadata.get(id) ?? { names: new Set<string>(), sources: new Set<string>() }
+    const declarations = new Set([
+      ...this.declarationSources.get(type) ?? [],
+      ...type.aliasSymbol?.declarations ?? [],
+      ...type.getSymbol()?.declarations ?? [],
+    ])
+    for (const declaration of declarations) {
+      if (!isNamedTypeDeclaration(declaration) && !ts.isTypeLiteralNode(declaration) && !ts.isEnumMember(declaration)) continue
+      const source = declaration.getSourceFile()
+      const file = slash(relative(this.root, source.fileName))
+      if (!trackedSource(file)) continue
+      if (isNamedTypeDeclaration(declaration)) item.names.add(`${file}#${declaration.name.text}`)
+      const position = source.getLineAndCharacterOfPosition(declaration.getStart())
+      item.sources.add(`${file}:${String(position.line + 1)}`)
+    }
+    this.declarationMetadata.set(id, item)
+  }
+
+  private fail(type: ts.Type, site: ts.Node, reason: string): never {
+    const source = slash(relative(this.root, site.getSourceFile().fileName))
+    const position = site.getSourceFile().getLineAndCharacterOfPosition(site.getStart())
+    throw new PersistenceSchemaError(`persistence schema: ${source}:${String(position.line + 1)}: ${reason}: ${this.checker.typeToString(type)}`)
+  }
+}
+
+function isNamedTypeDeclaration(node: ts.Node): node is ts.TypeAliasDeclaration | ts.InterfaceDeclaration | ts.EnumDeclaration {
+  return ts.isTypeAliasDeclaration(node) || ts.isInterfaceDeclaration(node) || ts.isEnumDeclaration(node)
+}
+
+function stringLiterals(type: ts.Type, name: string): Set<string> {
+  if (type.flags & ts.TypeFlags.Never) return new Set()
+  const members = type.isUnion() ? type.types : [type]
+  if (members.some(member => !(member.flags & ts.TypeFlags.StringLiteral))) throw new PersistenceSchemaError(`persistence schema: ${name} is not a closed string-literal union`)
+  return new Set(members.map(member => (member as ts.StringLiteralType).value))
+}
+
+function diagnosticText(diagnostic: ts.Diagnostic): string {
+  return `persistence schema: TypeScript TS${String(diagnostic.code)}: ${ts.flattenDiagnosticMessageText(diagnostic.messageText, '\n')}`
+}
+
+function compare(left: string, right: string): number {
+  return left < right ? -1 : left > right ? 1 : 0
+}
+
+function slash(path: string): string {
+  return path.split(sep).join('/')
+}
+
+function trackedSource(file: string): boolean {
+  return (file.startsWith('packages/') || file.startsWith('vendor/')) && !file.includes('/node_modules/')
+}

scripts/pnpm-invocation.ts

@@ -0,0 +1,21 @@
+/** Resolve shell-free child-process invocations for the pnpm process that launched a package script. */
+
+/**
+ * Resolve pnpm's executable and arguments from its lifecycle environment.
+ * @param args - Arguments to pass to pnpm.
+ * @param environment - Lifecycle environment containing `npm_execpath`.
+ * @returns A command and argument array suitable for `spawn` or `spawnSync` without a shell.
+ */
+export function pnpmInvocation(
+  args: readonly string[],
+  environment: NodeJS.ProcessEnv = process.env,
+): { command: string; args: string[] } {
+  const entrypoint = environment.npm_execpath
+  if (entrypoint === undefined || entrypoint === '') {
+    throw new Error('pnpm invocation: npm_execpath is unavailable; invoke the script through pnpm run.')
+  }
+  if (/\.[cm]?js$/iu.test(entrypoint)) {
+    return { command: process.execPath, args: [entrypoint, ...args] }
+  }
+  return { command: entrypoint, args: [...args] }
+}

scripts/project-reference-faces.spec.ts

@@ -0,0 +1,100 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import { collectProjectReferenceFaceViolations } from './project-reference-faces.ts'
+
+const roots: string[] = []
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function writeJson(path: string, value: unknown): void {
+  writeFileSync(path, `${JSON.stringify(value, null, 2)}\n`)
+}
+
+function workspaceFixture(options: {
+  readonly host: readonly string[]
+  readonly client: readonly string[]
+}): string {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-project-reference-faces-'))
+  roots.push(root)
+  const shared = join(root, 'packages/core/shared')
+  const split = join(root, 'packages/api/split')
+  mkdirSync(shared, { recursive: true })
+  mkdirSync(split, { recursive: true })
+  writeJson(join(root, 'tsconfig.base.json'), {})
+  writeJson(join(root, 'tsconfig.base.client.json'), { extends: './tsconfig.base.json' })
+  writeJson(join(shared, 'package.json'), { name: '@deepseek-ai/dsh-shared' })
+  writeJson(join(shared, 'tsconfig.json'), {
+    extends: '../../../tsconfig.base.json',
+    references: [],
+  })
+  writeJson(join(split, 'package.json'), { name: '@deepseek-ai/dsh-split' })
+  writeJson(join(split, 'tsconfig.json'), {
+    files: [],
+    references: [{ path: './tsconfig.host.json' }, { path: './tsconfig.client.json' }],
+  })
+  writeJson(join(split, 'tsconfig.host.json'), { references: [{ path: '../../core/shared' }] })
+  writeJson(join(split, 'tsconfig.client.json'), { references: [{ path: '../../core/shared' }] })
+  writeJson(join(root, 'tsconfig.host.json'), {
+    references: options.host.map(path => ({ path })),
+  })
+  writeJson(join(root, 'tsconfig.client.json'), {
+    references: options.client.map(path => ({ path })),
+  })
+  return root
+}
+
+describe('Project Reference compiler faces', () => {
+  it('allows neutral projects in either graph and matching split leaves', () => {
+    const root = workspaceFixture({
+      host: ['./packages/core/shared', './packages/api/split/tsconfig.host.json'],
+      client: ['./packages/core/shared', './packages/api/split/tsconfig.client.json'],
+    })
+
+    expect(collectProjectReferenceFaceViolations(root)).toEqual([])
+  })
+
+  it('rejects the opposite leaf and the solution root of a split project', () => {
+    const root = workspaceFixture({
+      host: [
+        './packages/api/split/tsconfig.host.json',
+        './packages/api/split/tsconfig.client.json',
+      ],
+      client: ['./packages/api/split'],
+    })
+
+    expect(collectProjectReferenceFaceViolations(root)).toEqual([
+      'tsconfig.client.json: Project Reference "./packages/api/split" enters split project packages/api/split from a Client config; reference "packages/api/split/tsconfig.client.json" instead',
+      'tsconfig.host.json: Project Reference "./packages/api/split/tsconfig.client.json" enters split project packages/api/split from a Host config; reference "packages/api/split/tsconfig.host.json" instead',
+    ])
+  })
+
+  it('uses the referencing project face throughout the reachable graph', () => {
+    const root = workspaceFixture({
+      host: ['./packages/core/host-consumer'],
+      client: ['./packages/core/client-consumer'],
+    })
+    const hostConsumer = join(root, 'packages/core/host-consumer')
+    mkdirSync(hostConsumer, { recursive: true })
+    writeJson(join(hostConsumer, 'package.json'), { name: '@deepseek-ai/dsh-host-consumer' })
+    writeJson(join(hostConsumer, 'tsconfig.json'), {
+      extends: '../../../tsconfig.base.json',
+      references: [{ path: '../../api/split/tsconfig.client.json' }],
+    })
+    const clientConsumer = join(root, 'packages/core/client-consumer')
+    mkdirSync(clientConsumer, { recursive: true })
+    writeJson(join(clientConsumer, 'package.json'), { name: '@deepseek-ai/dsh-client-consumer' })
+    writeJson(join(clientConsumer, 'tsconfig.json'), {
+      extends: '../../../tsconfig.base.client.json',
+      references: [{ path: '../../api/split/tsconfig.host.json' }],
+    })
+
+    expect(collectProjectReferenceFaceViolations(root)).toEqual([
+      'packages/core/client-consumer/tsconfig.json: Project Reference "../../api/split/tsconfig.host.json" enters split project packages/api/split from a Client config; reference "packages/api/split/tsconfig.client.json" instead',
+      'packages/core/host-consumer/tsconfig.json: Project Reference "../../api/split/tsconfig.client.json" enters split project packages/api/split from a Host config; reference "packages/api/split/tsconfig.host.json" instead',
+    ])
+  })
+})

scripts/publication-payload.spec.ts

@@ -0,0 +1,81 @@
+import { describe, expect, it } from 'vitest'
+import {
+  hasTypertRemoteNavigation,
+  isForbiddenPublicationFile,
+  validateTarballPayload,
+} from './publication-payload.ts'
+
+function validateFixtureTarball(files: readonly string[]): () => void {
+  return () => {
+    validateTarballPayload(files, 'fixture.tgz')
+  }
+}
+
+describe('publication payload policy', () => {
+  it.each([
+    'lib/index.js',
+    'lib/types/index.d.ts',
+    'lib/styles/base.css',
+  ])('accepts %s', (file) => {
+    expect(isForbiddenPublicationFile(file)).toBe(false)
+  })
+
+  it.each([
+    'src',
+    './src',
+    'src/',
+    'src/index.ts',
+    './src/index.ts',
+    String.raw`src\index.ts`,
+    'lib/types/index.d.ts.map',
+    './lib/types/index.d.ts.map',
+    'lib/typert.remote-client.d.ts.map',
+    'lib/client.js.map',
+    './lib/client.js.map',
+  ])('rejects static manifest path %s', (file) => {
+    expect(isForbiddenPublicationFile(file)).toBe(true)
+  })
+
+  it('rejects source members in packed tarballs', () => {
+    expect(validateFixtureTarball([
+      'package/package.json',
+      'package/src/index.ts',
+    ])).toThrow('fixture.tgz publishes source file package/src/index.ts')
+  })
+
+  it('rejects source maps in packed tarballs', () => {
+    expect(validateFixtureTarball([
+      'package/package.json',
+      'package/lib/types/index.d.ts.map',
+    ])).toThrow('fixture.tgz publishes source map package/lib/types/index.d.ts.map')
+    expect(validateFixtureTarball([
+      'package/package.json',
+      'package/lib/typert.remote-client.d.ts.map',
+    ])).toThrow('fixture.tgz publishes source map package/lib/typert.remote-client.d.ts.map')
+    expect(validateFixtureTarball([
+      'package/package.json',
+      'package/lib/client.js.map',
+    ])).toThrow('fixture.tgz publishes source map package/lib/client.js.map')
+  })
+
+  it('accepts a clean packed tarball', () => {
+    expect(validateFixtureTarball([
+      'package/package.json',
+      'package/lib/index.js',
+      'package/lib/types/index.d.ts',
+      'package/lib/styles/base.css',
+    ])).not.toThrow()
+  })
+
+  it('recognizes only the canonical Host-for-Client export pair', () => {
+    expect(hasTypertRemoteNavigation({
+      exports: {
+        './remote': {
+          types: './lib/typert.remote-client.d.ts',
+          default: './lib/typert.remote-client.js',
+        },
+      },
+    })).toBe(true)
+    expect(hasTypertRemoteNavigation({ exports: { './remote': './lib/remote.js' } })).toBe(false)
+  })
+})

scripts/publication-payload.ts

@@ -0,0 +1,55 @@
+/** Publication payload policy shared by static manifests and packed tarballs. */
+
+/**
+ * Whether a package manifest exports generated Host-for-Client metadata.
+ * @param manifest - parsed package manifest to inspect.
+ * @returns whether the canonical `./remote` export pair is present.
+ */
+export function hasTypertRemoteNavigation(manifest: unknown): boolean {
+  if (manifest === null || typeof manifest !== 'object' || Array.isArray(manifest)) return false
+  const exportsField = (manifest as Record<string, unknown>).exports
+  if (exportsField === null || typeof exportsField !== 'object' || Array.isArray(exportsField)) return false
+  const remote = (exportsField as Record<string, unknown>)['./remote']
+  if (remote === null || typeof remote !== 'object' || Array.isArray(remote)) return false
+  const entry = remote as Record<string, unknown>
+  return entry.types === './lib/typert.remote-client.d.ts'
+    && entry.default === './lib/typert.remote-client.js'
+}
+
+/** Normalize a package manifest path or npm tarball member to its payload-relative path. */
+function payloadPath(file: string): string {
+  const normalized = file.replaceAll('\\', '/').replace(/^\.\/+/, '').replace(/\/+$/, '')
+  return normalized.startsWith('package/') ? normalized.slice('package/'.length) : normalized
+}
+
+/**
+ * Whether a package payload path exposes source or map intermediates. Maps
+ * serve editor navigation during development, where a workspace consumer
+ * resolves their source through the package link; a published map resolves
+ * nothing, so no payload publishes one.
+ * @param file - manifest path or tarball member to classify.
+ * @returns whether publishing this path is forbidden.
+ */
+export function isForbiddenPublicationFile(file: string): boolean {
+  const normalized = payloadPath(file)
+  return normalized === 'src'
+    || normalized.startsWith('src/')
+    || normalized.endsWith('.d.ts.map')
+    || normalized.endsWith('.js.map')
+}
+
+/**
+ * Reject source and map members in a packed npm tarball.
+ * @param files - tarball members to validate.
+ * @param context - tarball identity named in the failure.
+ */
+export function validateTarballPayload(files: readonly string[], context: string): void {
+  for (const file of files) {
+    if (!isForbiddenPublicationFile(file)) continue
+    const normalized = payloadPath(file)
+    if (normalized === 'src' || normalized.startsWith('src/')) {
+      throw new Error(`${context} publishes source file ${file}`)
+    }
+    throw new Error(`${context} publishes source map ${file}`)
+  }
+}

scripts/publint-all.spec.ts

@@ -0,0 +1,167 @@
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { once } from 'node:events'
+import { execa } from 'execa'
+import { afterEach, describe, expect, it } from 'vitest'
+
+const repositoryRoot = fileURLToPath(new URL('..', import.meta.url))
+const runner = fileURLToPath(new URL('./publint-all.ts', import.meta.url))
+const roots: string[] = []
+const children: Array<{ kill: () => void; closed: Promise<unknown> }> = []
+
+afterEach(async () => {
+  // A test timeout can reach teardown before the test's pending await settles.
+  const ownedRoots = roots.splice(0)
+  await Promise.all(children.splice(0).map(async ({ kill, closed }) => {
+    kill()
+    await closed
+  }))
+  for (const root of ownedRoots) rmSync(root, { recursive: true, force: true })
+})
+
+function fixture(options: {
+  exportPath?: string
+  indexSource?: string
+  files?: Record<string, string>
+} = {}): string {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-publint-all-'))
+  roots.push(root)
+  const packageDir = join(root, 'packages/core/probe')
+  mkdirSync(join(packageDir, 'lib'), { recursive: true })
+  writeFileSync(join(packageDir, 'package.json'), `${JSON.stringify({
+    name: '@deepseek-ai/dsh-probe',
+    version: '0.0.1',
+    type: 'module',
+    license: 'MIT',
+    engines: { node: '>=22.19' },
+    sideEffects: false,
+    files: ['lib'],
+    exports: { '.': { default: options.exportPath ?? './lib/index.js' } },
+  }, null, 2)}\n`)
+  writeFileSync(join(packageDir, 'README.md'), '# Probe\n')
+  writeFileSync(join(packageDir, 'lib/index.js'), options.indexSource ?? 'export const probe = true\n')
+  for (const [path, source] of Object.entries(options.files ?? {})) {
+    mkdirSync(join(packageDir, path, '..'), { recursive: true })
+    writeFileSync(join(packageDir, path), source)
+  }
+  writeFileSync(join(packageDir, 'unpublished.js'), 'export const hidden = true\n')
+  return root
+}
+
+/** Own direct Node children until close; Vitest's signal supplies the lane deadline. */
+function start(args: string[], signal: AbortSignal, cwd = repositoryRoot) {
+  const child = execa(process.execPath, args, {
+    cwd,
+    cancelSignal: signal,
+    killSignal: 'SIGKILL',
+    reject: false,
+    stdin: 'ignore',
+    stripFinalNewline: false,
+  })
+  // `error` is an outcome, not the completion edge for the process and its pipes.
+  const closed = new Promise<void>(resolve => child.nodeChildProcess.once('close', () => { resolve() }))
+  const result = Promise.all([child, closed]).then(([result]) => result)
+  children.push({ kill: () => { child.kill('SIGKILL') }, closed: result })
+  return { child, result }
+}
+
+function expectCompleted(result: Awaited<ReturnType<typeof start>['result']>) {
+  const diagnostics = [
+    `publint subprocess: error=${String(result.cause)}; signal=${String(result.signal)}; exitCode=${String(result.exitCode)}`,
+    `canceled=${result.isCanceled}; timedOut=${result.timedOut}`,
+    result.shortMessage ?? '',
+    `stdout:\n${result.stdout}`,
+    `stderr:\n${result.stderr}`,
+  ].join('\n')
+  expect(result.cause, diagnostics).toBeUndefined()
+  expect(result.isCanceled, diagnostics).toBe(false)
+  expect(result.timedOut, diagnostics).toBe(false)
+  expect(result.signal, diagnostics).toBeUndefined()
+}
+
+async function run(root: string, signal: AbortSignal) {
+  const { result } = start([
+    '--import', 'tsx', runner,
+    '--packages-root', root,
+  ], signal)
+  const completed = await result
+  expectCompleted(completed)
+  return completed
+}
+
+describe('publint package runner', () => {
+  it('reports deadline cancellation after every owned child closes', async ({ signal }) => {
+    const deadline = new AbortController()
+    const active = [0, 1].map(() => start([
+      '-e', "process.stderr.write('probe stderr\\n'); process.stdout.write('ready\\n'); setInterval(() => {}, 1000)",
+    ], AbortSignal.any([signal, deadline.signal])))
+    const closed = active.map(() => false)
+    active.forEach(({ child }, index) => child.nodeChildProcess.once('close', () => { closed[index] = true }))
+    await Promise.all(active.map(({ child }) => once(child.stdout, 'data', { signal })))
+    expect(closed).toEqual([false, false])
+    // Start the deadline only after both children announce readiness; startup speed is not the oracle.
+    const timer = setTimeout(() => { deadline.abort(new DOMException('fixture deadline expired', 'TimeoutError')) }, 0)
+    try {
+      const results = await Promise.all(active.map(({ result }) => result))
+      expect(closed).toEqual([true, true])
+      for (const [index, result] of results.entries()) {
+        expect(result.isCanceled).toBe(true)
+        expect(() => { expectCompleted(result) }).toThrow(/publint subprocess: error=TimeoutError: fixture deadline expired; signal=/)
+        expect(() => { expectCompleted(result) }).toThrow(/canceled=true/)
+        expect(() => { expectCompleted(result) }).toThrow(/ready/)
+        expect(() => { expectCompleted(result) }).toThrow(/probe stderr/)
+        expect(() => process.kill(active[index]!.child.pid!, 0)).toThrow(/ESRCH/)
+      }
+    } finally {
+      clearTimeout(timer)
+    }
+  })
+
+  it('reports spawn errors before checking the expected exit code', async ({ signal }) => {
+    const { result } = start(['-e', ''], signal, join(fixture(), 'missing-cwd'))
+    const completed = await result
+    expect(completed.cause).toMatchObject({ code: 'ENOENT' })
+    expect(() => { expectCompleted(completed) }).toThrow(/publint subprocess: error=.*ENOENT.*; signal=undefined/)
+  })
+
+  it('lints recursively declared files from an in-memory publication view', async ({ signal }) => {
+    const result = await run(fixture(), signal)
+    expect(result.exitCode, result.stderr).toBe(0)
+    expect(result.stdout).toContain('linting 1 package(s)')
+    expect(result.stdout).toContain('All good!')
+  })
+
+  it('rejects an export that exists in the workspace but is not published', async ({ signal }) => {
+    const result = await run(fixture({ exportPath: './unpublished.js' }), signal)
+    expect(result.exitCode).toBe(1)
+    expect(result.stdout).toContain('unpublished.js')
+  })
+
+  it('rejects a public export whose built file is missing', async ({ signal }) => {
+    const result = await run(fixture({ exportPath: './lib/missing.js' }), signal)
+    expect(result.exitCode).toBe(1)
+    expect(result.stdout).toContain('missing.js')
+  })
+
+  it('accepts published relative JavaScript and CSS targets', async ({ signal }) => {
+    const result = await run(fixture({
+      indexSource: "export { helper } from './helper.js'\nimport './theme.css'\n",
+      files: {
+        'lib/helper.js': 'export const helper = true\n',
+        'lib/theme.css': ':root {}\n',
+      },
+    }), signal)
+    expect(result.exitCode, result.stderr).toBe(0)
+  })
+
+  it('rejects unpublished relative JavaScript and CSS targets', async ({ signal }) => {
+    const result = await run(fixture({
+      indexSource: "export { helper } from './missing.js'\nimport './missing.css'\n",
+    }), signal)
+    expect(result.exitCode).toBe(1)
+    expect(result.stderr).toContain('imports "./missing.js"')
+    expect(result.stderr).toContain('imports "./missing.css"')
+  })
+})

scripts/publint-all.ts

@@ -0,0 +1,260 @@
+/** Run publint over the exact manifest-declared publication view of every package. */
+
+import {
+  globSync,
+  readdirSync,
+  readFileSync,
+  statSync,
+} from 'node:fs'
+import { availableParallelism } from 'node:os'
+import { dirname, posix, relative, resolve, sep } from 'node:path'
+import { parseArgs } from 'node:util'
+import { publint, type Message, type PackFile } from 'publint'
+import { formatMessage } from 'publint/utils'
+import ts from 'typescript'
+
+const CONCURRENCY_ENV = 'DSH_PUBLINT_CONCURRENCY'
+const repositoryRoot = resolve(import.meta.dirname, '..')
+const { values: options } = parseArgs({
+  args: process.argv.slice(2),
+  options: { 'packages-root': { type: 'string' } },
+})
+const packagesRoot = resolve(options['packages-root'] ?? repositoryRoot)
+
+interface PackageTarget {
+  path: string
+  directory: string
+  manifest: PackageManifest
+}
+
+interface PackageManifest {
+  name?: string
+  files?: unknown
+}
+
+type PublintResult =
+  | {
+    path: string
+    status: 'passed'
+    messages: Message[]
+    closureViolations: string[]
+    manifest: Record<string, unknown>
+  }
+  | {
+    path: string
+    status: 'failed'
+    messages: Message[]
+    closureViolations: string[]
+    manifest: Record<string, unknown>
+    failure?: string
+  }
+
+function workspacePackages(): PackageTarget[] {
+  return globSync('packages/*/*/package.json', { cwd: packagesRoot })
+    .sort()
+    .map((manifestPath) => {
+      const absoluteManifestPath = resolve(packagesRoot, manifestPath)
+      const manifest = JSON.parse(readFileSync(absoluteManifestPath, 'utf8')) as PackageManifest
+      return { path: dirname(manifestPath), directory: dirname(absoluteManifestPath), manifest }
+    })
+}
+
+function publintConcurrency(total: number): number {
+  if (total === 0) return 0
+
+  const raw = process.env[CONCURRENCY_ENV]
+  if (raw !== undefined && raw !== '') {
+    const parsed = Number.parseInt(raw, 10)
+    if (!Number.isSafeInteger(parsed) || parsed < 1 || String(parsed) !== raw) {
+      throw new Error(`publint-all: ${CONCURRENCY_ENV} must be a positive integer, got ${JSON.stringify(raw)}.`)
+    }
+    return Math.min(total, parsed)
+  }
+
+  return Math.min(total, availableParallelism())
+}
+
+function publicationFiles(target: PackageTarget): PackFile[] {
+  const paths = new Set<string>()
+  addPath(resolve(target.directory, 'package.json'), paths)
+  const declared = Array.isArray(target.manifest.files)
+    ? target.manifest.files.filter((value): value is string => typeof value === 'string')
+    : []
+  for (const pattern of [
+    ...declared,
+    'README*',
+    'LICENSE*',
+    'LICENCE*',
+    'CHANGELOG*',
+    'CHANGES*',
+    'HISTORY*',
+    'NOTICE*',
+  ]) {
+    for (const match of globSync(pattern, { cwd: target.directory })) {
+      addPath(resolve(target.directory, match), paths)
+    }
+  }
+
+  return [...paths]
+    .sort()
+    .map(path => ({
+      name: `package/${relative(target.directory, path).split(sep).join('/')}`,
+      data: readFileSync(path),
+    }))
+}
+
+function addPath(path: string, paths: Set<string>): void {
+  const stat = statSync(path)
+  if (stat.isDirectory()) {
+    // readdirSync, not globSync: `**/*` skips dot-prefixed segments, but npm
+    // pack publishes dotfiles inside included directories, and this view must
+    // match what npm publishes.
+    for (const entry of readdirSync(path, { recursive: true, withFileTypes: true })) {
+      if (entry.isFile()) paths.add(resolve(entry.parentPath, entry.name))
+    }
+  } else if (stat.isFile()) {
+    paths.add(path)
+  }
+}
+
+interface RelativeImport {
+  specifier: string
+  line: number
+}
+
+/** Return relative imports whose targets are absent from the publication view. */
+function publicationClosureViolations(target: PackageTarget, files: readonly PackFile[]): string[] {
+  const published = new Set(files.map(file => file.name))
+  const violations: string[] = []
+  for (const file of files) {
+    if (!/\.(?:js|mjs|cjs)$/.test(file.name)) continue
+    const bytes = file.data instanceof ArrayBuffer ? new Uint8Array(file.data) : file.data
+    const source = typeof bytes === 'string' ? bytes : Buffer.from(bytes).toString('utf8')
+    for (const imported of relativeImports(file.name, source)) {
+      const resolved = posix.normalize(posix.join(posix.dirname(file.name), imported.specifier))
+      if (resolutionCandidates(resolved).some(candidate => published.has(candidate))) continue
+      violations.push(
+        `${target.path}/${file.name.slice('package/'.length)}:${String(imported.line)}`
+        + ` imports ${JSON.stringify(imported.specifier)}, but ${target.manifest.name ?? target.path}`
+        + ` does not publish ${JSON.stringify(resolved.slice('package/'.length))}`,
+      )
+    }
+  }
+  return violations
+}
+
+/** Paths a relative JavaScript module request can resolve to in a published package. */
+function resolutionCandidates(target: string): string[] {
+  const base = target.replace(/\/+$/, '')
+  return [
+    target,
+    ...['.js', '.mjs', '.cjs', '/index.js', '/index.mjs', '/index.cjs'].map(suffix => base + suffix),
+  ]
+}
+
+/** Extract relative static imports, re-exports, dynamic imports, and requires. */
+function relativeImports(file: string, sourceText: string): RelativeImport[] {
+  const source = ts.createSourceFile(file, sourceText, ts.ScriptTarget.Latest, false, ts.ScriptKind.JS)
+  const imports: RelativeImport[] = []
+  const record = (node: ts.Node, literal: ts.Expression | undefined): void => {
+    if (literal === undefined || !ts.isStringLiteralLike(literal) || !literal.text.startsWith('.')) return
+    imports.push({
+      specifier: literal.text,
+      line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
+    })
+  }
+  const visit = (node: ts.Node): void => {
+    if (ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) {
+      record(node, node.moduleSpecifier)
+    } else if (ts.isCallExpression(node)
+      && (node.expression.kind === ts.SyntaxKind.ImportKeyword
+        || ts.isIdentifier(node.expression) && node.expression.text === 'require')) {
+      record(node, node.arguments[0])
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(source)
+  return imports
+}
+
+/**
+ * publint reads the CommonJS interop preamble inside the prebuilt browser
+ * bundles and reports CJS-written-as-ESM. Node never resolves those files:
+ * `lib/client.js` is evaluated by the page module system as a classic script,
+ * and `lib/worker.js` by `new Worker(url, { type: 'module' })` — both outside
+ * the Node resolution publint models. Exactly that verdict on exactly those
+ * files is suppressed; every other publint error stays fatal.
+ */
+function isBrowserBundleFormatFalsePositive(message: Message): boolean {
+  if (message.code !== 'FILE_INVALID_FORMAT') return false
+  const filePath = (message.args as { actualFilePath?: string }).actualFilePath ?? ''
+  const exportKey = Array.isArray(message.path) ? message.path.join('/') : ''
+  return /(^|\/)lib\/(client|worker)\.js$/.test(filePath)
+    || /(^|\/)\.\/(client|worker)$/.test(exportKey)
+}
+
+async function runPublint(target: PackageTarget): Promise<PublintResult> {
+  try {
+    const files = publicationFiles(target)
+    const closureViolations = publicationClosureViolations(target, files)
+    const result = await publint({
+      pkgDir: 'package',
+      pack: { files },
+    })
+    const manifest = result.pkg as Record<string, unknown>
+    const messages = result.messages.filter(message => !isBrowserBundleFormatFalsePositive(message))
+    return messages.some(message => message.type === 'error') || closureViolations.length > 0
+      ? { path: target.path, status: 'failed', messages, closureViolations, manifest }
+      : { path: target.path, status: 'passed', messages, closureViolations, manifest }
+  } catch (error: unknown) {
+    return {
+      path: target.path,
+      status: 'failed',
+      messages: [],
+      closureViolations: [],
+      manifest: target.manifest as Record<string, unknown>,
+      failure: error instanceof Error ? error.message : String(error),
+    }
+  }
+}
+
+async function runAll(targets: PackageTarget[], concurrency: number): Promise<PublintResult[]> {
+  let next = 0
+  const results: Array<PublintResult | undefined> = []
+  await Promise.all(Array.from({ length: concurrency }, async () => {
+    for (;;) {
+      const index = next
+      next += 1
+      const target = targets[index]
+      if (target === undefined) return
+      results[index] = await runPublint(target)
+    }
+  }))
+
+  return targets.map((target, index) => {
+    const result = results[index]
+    if (result === undefined) throw new Error(`publint-all: missing result for ${target.path}.`)
+    return result
+  })
+}
+
+function printResult(result: PublintResult): void {
+  console.log(`Running publint for ${result.path}...`)
+  if ('failure' in result) console.error(result.failure)
+  for (const message of result.messages) {
+    console.log(formatMessage(message, result.manifest, { color: false }) ?? message.code)
+  }
+  for (const violation of result.closureViolations) console.error(violation)
+  if (result.status === 'passed' && result.messages.length === 0 && result.closureViolations.length === 0) {
+    console.log('All good!')
+  }
+}
+
+const packages = workspacePackages()
+const concurrency = publintConcurrency(packages.length)
+console.log(`publint-all: linting ${packages.length} package(s) with ${concurrency} worker(s).`)
+
+const results = await runAll(packages, concurrency)
+for (const result of results) printResult(result)
+
+if (results.some(result => result.status === 'failed')) process.exit(1)

scripts/render-persistence-schema.ts

@@ -0,0 +1,202 @@
+/** Readable, linked persistence schemas rendered from the fingerprint inventory. */
+
+import { githubSlug } from './verify-md-links.ts'
+import { persistenceCatalogText, type PersistenceCatalogLocale } from './persistence-catalog-text.ts'
+import {
+  canonicalizeSchema,
+  schemaChildren,
+  schemaDigest,
+  type CanonicalSchema,
+  type PersistenceSchemaInventory,
+  type PersistenceType,
+  type SchemaNode,
+} from './persistence-schema-model.ts'
+
+interface TypeDisplay {
+  readonly type: PersistenceType
+  readonly label: string
+  readonly anchor: string
+}
+
+function code(text: string): string {
+  return '`' + text.replaceAll('`', '\\`').replaceAll('|', '\\|') + '`'
+}
+
+function sourcePath(source: string): string {
+  return source.replace(/:\d+(?::\d+)?$/u, '')
+}
+
+function nodeAt(schema: CanonicalSchema, index: number): SchemaNode {
+  const node = schema.nodes[index]
+  if (!node) throw new Error(`persistence catalog: missing schema node ${String(index)}`)
+  return node
+}
+
+function childPath(node: SchemaNode, position: number): string {
+  switch (node.kind) {
+    case 'object': return node.properties[position]?.name ?? `index-${String(position - node.properties.length)}`
+    case 'array': return 'item'
+    case 'tuple': return `item-${String(position)}`
+    case 'union': return `variant-${String(position)}`
+    case 'primitive':
+    case 'literal':
+    case 'opaque': return String(position)
+    default: return assertNever(node)
+  }
+}
+
+function displays(inventory: PersistenceSchemaInventory): Map<string, TypeDisplay> {
+  const paths = new Map<string, string>()
+  for (const root of inventory.roots) {
+    const seen = new Set<number>()
+    const visit = (index: number, path: string): void => {
+      if (seen.has(index)) return
+      seen.add(index)
+      const digest = schemaDigest(canonicalizeSchema(root.schema.nodes, index))
+      if (!paths.has(digest)) paths.set(digest, path)
+      const node = nodeAt(root.schema, index)
+      schemaChildren(node).forEach((child, position) => { visit(child, `${path}.${childPath(node, position)}`) })
+    }
+    visit(0, root.key)
+  }
+  const labels = inventory.types.map((type) => {
+    const node = nodeAt(type.schema, 0)
+    const label = node.kind === 'primitive' ? node.type
+      : node.kind === 'literal' ? JSON.stringify(node.value)
+        : node.kind === 'opaque' ? node.reason
+          : type.names[0] ?? paths.get(type.digest) ?? node.kind
+    return { type, label }
+  })
+  const counts = new Map<string, number>()
+  for (const { label } of labels) counts.set(label, (counts.get(label) ?? 0) + 1)
+  const used = new Set<string>()
+  return new Map(labels.map(({ type, label: original }) => {
+    const label = (counts.get(original) ?? 0) > 1
+      ? `${original} (${type.sources[0] ? sourcePath(type.sources[0]) : paths.get(type.digest) ?? 'anonymous'})`
+      : original
+    const base = `persistence-type-${githubSlug(label)}`
+    let anchor = base
+    for (let suffix = 2; used.has(anchor); suffix += 1) anchor = `${base}-${String(suffix)}`
+    used.add(anchor)
+    return [type.digest, { type, label, anchor }]
+  }))
+}
+
+function reference(digest: string, entries: ReadonlyMap<string, TypeDisplay>): string {
+  const entry = entries.get(digest)
+  if (!entry) throw new Error(`persistence catalog: reachable type ${digest} is absent from the inventory`)
+  return `[${code(entry.label)}](#${entry.anchor})`
+}
+
+function typeExpression(
+  schema: CanonicalSchema,
+  index: number,
+  entries: ReadonlyMap<string, TypeDisplay>,
+  locale: PersistenceCatalogLocale,
+): string {
+  const node = nodeAt(schema, index)
+  if (node.kind === 'primitive') return code(node.type)
+  if (node.kind === 'literal') return code(JSON.stringify(node.value))
+  if (node.kind === 'opaque') return `${code(node.reason)}${persistenceCatalogText[locale].opaque}`
+  return reference(schemaDigest(canonicalizeSchema(schema.nodes, index)), entries)
+}
+
+function definition(
+  entry: TypeDisplay,
+  entries: ReadonlyMap<string, TypeDisplay>,
+  locale: PersistenceCatalogLocale,
+  sourceLink: (source: string) => string | undefined,
+  headingLevel: number,
+): string[] {
+  const text = persistenceCatalogText[locale]
+  const schema = entry.type.schema
+  const node = nodeAt(schema, 0)
+  const lines = [`<a id="${entry.anchor}"></a>`, '', `${'#'.repeat(headingLevel)} ${code(entry.label)}`, '', `SHA-256: ${code(entry.type.digest)}`, '']
+  if (entry.type.sources.length > 0) {
+    lines.push(`${text.sources}${entry.type.sources.map((source) => {
+      const href = sourceLink(sourcePath(source))
+      return href === undefined ? code(source) : `[${code(source)}](${href})`
+    }).join(' · ')}`, '')
+  }
+  const expression = (index: number): string => typeExpression(schema, index, entries, locale)
+  switch (node.kind) {
+    case 'object':
+      if (node.properties.length === 0 && node.indices.length === 0) lines.push(text.emptyObject, '')
+      else {
+        lines.push(text.propertyColumns, '|---|---|---|')
+        for (const property of node.properties) {
+          lines.push(`| ${code(property.name)} | ${property.optional ? text.optional : text.required} | ${expression(property.type)} |`)
+        }
+        for (const index of node.indices) lines.push(`| [${expression(index.key)}] | ${text.index} | ${expression(index.value)} |`)
+        lines.push('')
+      }
+      break
+    case 'array': lines.push(`${text.arrayPrefix}${expression(node.element)}${text.arraySuffix}`, ''); break
+    case 'tuple':
+      lines.push(text.positionColumns, '|---|---|---|')
+      node.elements.forEach((element, index) => {
+        const presence = element.rest ? text.rest : element.optional ? text.optional : text.required
+        lines.push(`| ${String(index)} | ${presence} | ${expression(element.type)} |`)
+      })
+      lines.push('')
+      break
+    case 'union':
+      lines.push(text.oneOf, '', ...node.types.map(index => `- ${expression(index)}`), '')
+      break
+    case 'primitive': lines.push(code(node.type), ''); break
+    case 'literal': lines.push(code(JSON.stringify(node.value)), ''); break
+    case 'opaque': lines.push(`${code(node.reason)}${text.opaqueExplanation}`, ''); break
+    default: assertNever(node)
+  }
+  return lines
+}
+
+/**
+ * Render every tracked root with its exact digest and resolved type reference.
+ * @param inventory - complete current-source schemas and declaration metadata.
+ * @param locale - generated document language.
+ * @param introduction - paragraphs before the root table; defaults to current-source links.
+ * @param headingLevel - section depth within the containing reference.
+ * @returns Markdown index including the history and contributor workflow links.
+ */
+export function renderPersistenceSchemaIndex(
+  inventory: PersistenceSchemaInventory,
+  locale: PersistenceCatalogLocale = 'en',
+  introduction: readonly string[] = [persistenceCatalogText[locale].fingerprintsIntro, persistenceCatalogText[locale].historyIntro],
+  headingLevel: 2 | 3 = 2,
+): string {
+  const entries = displays(inventory)
+  const text = persistenceCatalogText[locale]
+  return [
+    `${'#'.repeat(headingLevel)} ${text.fingerprints}`, '', ...introduction.flatMap(paragraph => [paragraph, '']),
+    text.rootColumns, '|---|---|---|---|',
+    ...inventory.roots.map(root => `| ${code(root.key)} | ${root.kind} | ${code(root.digest)} | ${reference(root.digest, entries)} |`), '',
+  ].join('\n')
+}
+
+/**
+ * Render every reachable type once, with links for shared and recursive definitions.
+ * @param inventory - complete current-source schemas and declaration metadata.
+ * @param locale - generated document language.
+ * @param sourceLink - source path to URL; undefined keeps historical locations as text.
+ * @param headingLevel - section depth; individual definitions use the next heading level.
+ * @returns Markdown definitions whose anchors use names or owning paths instead of hashes.
+ */
+export function renderPersistenceSchemaDefinitions(
+  inventory: PersistenceSchemaInventory,
+  locale: PersistenceCatalogLocale = 'en',
+  sourceLink: (source: string) => string | undefined = source => `../${source}`,
+  headingLevel: 2 | 3 = 2,
+): string {
+  const entries = displays(inventory)
+  const text = persistenceCatalogText[locale]
+  const sorted = [...entries.values()].sort((left, right) => left.anchor < right.anchor ? -1 : left.anchor > right.anchor ? 1 : 0)
+  return [
+    `${'#'.repeat(headingLevel)} ${text.definitions}`, '', text.definitionsIntro, '',
+    ...sorted.flatMap(entry => definition(entry, entries, locale, sourceLink, headingLevel + 1)),
+  ].join('\n')
+}
+
+function assertNever(value: never): never {
+  throw new Error(`persistence catalog: unsupported type ${JSON.stringify(value)}`)
+}

scripts/repo-files.ts

@@ -0,0 +1,252 @@
+/** Shared repository file discovery and line-oriented reference scanning. */
+
+import { readdirSync, readFileSync, realpathSync, statSync } from 'node:fs'
+import { join, relative, resolve, sep } from 'node:path'
+
+/** One authored path plus its canonical target for symlink deduplication. */
+export interface RepoFile {
+  /** Absolute path matched by the caller's glob. */
+  abs: string
+  /** Absolute canonical path used only for deduplication. */
+  real: string
+}
+
+/** A rejected line-oriented repository reference. */
+export interface ReferenceViolation {
+  /** Repo-relative file containing the reference. */
+  file: string
+  /** 1-based line containing the reference. */
+  line: number
+  /** Normalized reference text. */
+  ref: string
+}
+
+/** Whether a repository path is frozen Agent Note history, not evolving source prose. */
+export function isArchivedAgentNotePath(path: string): boolean {
+  return path.replaceAll('\\', '/').startsWith('.agents/notes/archived/')
+}
+
+/**
+ * Whether a pattern segment matches a directory or file name. Supports `*` and
+ * `?` inside a segment and mirrors node's glob `dot: false`: a segment whose
+ * first character is a wildcard does not match dot names. `**` is handled as a
+ * whole segment by the walker, never here.
+ */
+function segmentMatches(pattern: string, name: string): boolean {
+  if (name.startsWith('.') && (pattern.startsWith('*') || pattern.startsWith('?'))) return false
+  let expression = ''
+  for (const character of pattern) {
+    if (character === '*') expression += '.*'
+    else if (character === '?') expression += '.'
+    else expression += character.replace(/[.*+?^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp(`^${expression}$`).test(name)
+}
+
+/**
+ * Reject glob syntax the walker does not model. Node's `fs.glob` understands
+ * character classes, brace alternation, and extglobs; expanding those
+ * silently as literals would match nothing and quietly shrink a gate's
+ * corpus, so a pattern segment using them fails loudly instead. Pure literal
+ * segments must therefore contain none of the rejected metacharacters
+ * either, even where node glob would read them literally.
+ */
+const UNSUPPORTED_GLOB = /[[\]{}()!+@\\]/
+
+function assertSupportedSegment(segment: string): void {
+  if (UNSUPPORTED_GLOB.test(segment)) {
+    throw new TypeError(`repo-files walker does not model glob syntax in segment: ${segment}`)
+  }
+}
+
+/**
+ * Walk `root` matching one repository-relative glob without node's `fs.glob`.
+ * The repository's own walker exists because node's internal glob, from some
+ * 24.x releases, lstat-probes `<matched>/<next segment>` for symlinked files
+ * while expanding `**` and throws ENOTDIR instead of skipping (observed on
+ * node 24.13.0 scanning `snapshots/acp/image-compaction`'s symlinked
+ * `system-prompt.expected.md`). The walker decides directoryhood from dirent
+ * types and stat results, never by probing a path under a file, so the same
+ * tree enumerates identically on every node version.
+ *
+ * Segment semantics: literal segments resolve through `stat`, so a literal
+ * naming a symlinked directory enters that directory exactly as node glob
+ * does — including a literal repeated across segments, which node glob
+ * resolves each time; wildcard segments and `**` resolve through dirent
+ * types, so they never enter symlinked directories and never match dot
+ * names. Node documents `follow: false` only for `**` expansion, so the
+ * wildcard-side behavior is this walker's own contract, pinned by
+ * repo-files.spec.ts, rather than a cross-version node guarantee; the four
+ * consuming gates' current patterns contain no wildcard segment over a
+ * symlinked directory, so the corpus is unchanged. `**` spans zero or more
+ * directories. The final segment matches files and symlinks; a broken or
+ * cyclic symlink then fails loudly in the caller's realpathSync rather than
+ * shrinking the scanned corpus, while a broken symlink under a literal
+ * non-final segment matches nothing, again as node glob does. Traversal
+ * terminates without a visited set: each literal segment consumes one pattern
+ * segment per recursion, and `**` recurses only into real directories, which
+ * form a finite tree because symlinked directories are never expanded by it.
+ * Pattern segments support `*`, `?`, and literals that contain none of
+ * `[]{}()!+@\`; other node-glob syntax, including a trailing `**`, `..`, and
+ * empty segments, is rejected loudly up front, while a `.` segment is folded
+ * away exactly as node glob normalizes it. Returns repository-relative slash
+ * paths, sorted.
+ */
+function expandGlob(root: string, pattern: string): string[] {
+  const segments: string[] = []
+  for (const segment of pattern.split('/')) {
+    if (segment === '.') {
+      // Node glob normalizes a `.` segment away; dropping it here keeps
+      // `./README.md` and `a/./b` matching exactly as node glob does instead
+      // of silently matching nothing.
+      continue
+    }
+    if (segment === '..') {
+      // A `..` segment escapes the scanned root and interacts with `**` in
+      // ways node glob special-cases; no gate pattern uses one, so the walker
+      // rejects the form loudly instead of silently matching nothing.
+      throw new TypeError(`repo-files walker does not model .. segments in pattern: ${pattern}`)
+    }
+    if (segment === '') {
+      // A leading, doubled, or trailing slash yields an empty segment that
+      // can never match an entry; node glob would tolerate the form, so the
+      // walker must reject it loudly instead of silently returning nothing.
+      throw new TypeError(`repo-files walker does not model empty segments in pattern: ${pattern}`)
+    }
+    segments.push(segment)
+  }
+  if (segments.length === 0) {
+    throw new TypeError(`repo-files walker does not model a pattern with no segments: ${pattern}`)
+  }
+  for (const segment of segments) {
+    if (segment !== '**') assertSupportedSegment(segment)
+  }
+  // A trailing `**` would match files, directories, and symlinks below the
+  // prefix; the walker models `**` only as a directory-spanning segment, so
+  // it must reject the form loudly instead of silently returning nothing.
+  if (segments[segments.length - 1] === '**') {
+    throw new TypeError(`repo-files walker does not model a trailing ** segment in pattern: ${pattern}`)
+  }
+  const out: string[] = []
+
+  const visit = (dirAbs: string, dirRel: string, index: number): void => {
+    if (index >= segments.length) return
+    if (segments[index] !== '**') {
+      visitSegment(dirAbs, dirRel, index)
+      return
+    }
+    // `**` consumes zero directories here and one directory per recursion.
+    visitSegment(dirAbs, dirRel, index + 1)
+    for (const entry of readdirSync(dirAbs, { withFileTypes: true })) {
+      if (entry.name.startsWith('.') || !entry.isDirectory()) continue
+      visit(join(dirAbs, entry.name), dirRel === '.' ? entry.name : `${dirRel}/${entry.name}`, index)
+    }
+  }
+
+  const visitSegment = (dirAbs: string, dirRel: string, index: number): void => {
+    if (index >= segments.length) return
+    const segment = segments[index]
+    if (segment === undefined) return
+    if (segment === '**') {
+      visit(dirAbs, dirRel, index)
+      return
+    }
+    const last = index === segments.length - 1
+    for (const entry of readdirSync(dirAbs, { withFileTypes: true })) {
+      if (!segmentMatches(segment, entry.name)) continue
+      const childAbs = join(dirAbs, entry.name)
+      const childRel = dirRel === '.' ? entry.name : `${dirRel}/${entry.name}`
+      if (last) {
+        // Files and symlinks match; a broken or cyclic symlink then fails
+        // loudly in the caller's realpathSync exactly as node glob did,
+        // rather than silently shrinking the scanned corpus.
+        if (entry.isFile() || entry.isSymbolicLink()) out.push(childRel)
+        continue
+      }
+      if (entry.isDirectory()) {
+        visitSegment(childAbs, childRel, index + 1)
+        continue
+      }
+      // A literal non-final segment resolves through stat like node glob's,
+      // so it enters a symlinked directory; wildcard segments never reach
+      // this branch because they are matched from dirent types above.
+      if (!entry.isSymbolicLink() || hasWildcard(segment)) continue
+      let target: ReturnType<typeof statSync>
+      try {
+        target = statSync(childAbs)
+      } catch {
+        // A broken symlink matches nothing under a literal segment, as node
+        // glob silently returns no match for it.
+        continue
+      }
+      if (!target.isDirectory()) continue
+      visitSegment(childAbs, childRel, index + 1)
+    }
+  }
+
+  visit(root, '.', 0)
+  return out.sort()
+}
+
+/** Whether a pattern segment contains `*` or `?` and is therefore wildcard. */
+function hasWildcard(segment: string): boolean {
+  return segment.includes('*') || segment.includes('?')
+}
+
+/**
+ * Expand repository-relative globs and deduplicate symlinked files.
+ * @param root - absolute repository root.
+ * @param patterns - repository-relative glob patterns, processed in order.
+ * @param isExcluded - optional predicate over each matched relative path.
+ * @returns matched files in stable first-seen order.
+ */
+export function uniqueRepoFiles(
+  root: string,
+  patterns: readonly string[],
+  isExcluded: (relativePath: string) => boolean = () => false,
+): RepoFile[] {
+  const seen = new Set<string>()
+  const files: RepoFile[] = []
+  for (const pattern of patterns) {
+    for (const repoPath of expandGlob(root, pattern)) {
+      if (isExcluded(repoPath)) continue
+      const abs = resolve(root, repoPath)
+      const real = realpathSync(abs)
+      if (seen.has(real)) continue
+      seen.add(real)
+      files.push({ abs, real })
+    }
+  }
+  return files
+}
+
+/**
+ * Scan regex matches line by line and return the normalized matches rejected by
+ * a caller predicate.
+ * @param root - absolute repository root used for violation paths.
+ * @param absPath - absolute text-file path to scan.
+ * @param pattern - global regex matched independently against each line.
+ * @param normalize - maps raw regex text to the reference the gate evaluates.
+ * @param isViolation - returns true when the normalized reference is invalid.
+ * @returns every rejected reference in source order.
+ */
+export function findReferenceViolations(
+  root: string,
+  absPath: string,
+  pattern: RegExp,
+  normalize: (raw: string) => string,
+  isViolation: (ref: string) => boolean,
+): ReferenceViolation[] {
+  const file = relative(root, absPath).split(sep).join('/')
+  const out: ReferenceViolation[] = []
+  const lines = readFileSync(absPath, 'utf8').split('\n')
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i]
+    if (line === undefined) continue
+    for (const match of line.matchAll(pattern)) {
+      const ref = normalize(match[0])
+      if (isViolation(ref)) out.push({ file, line: i + 1, ref })
+    }
+  }
+  return out
+}

scripts/run-gates.spec.ts

@@ -0,0 +1,1029 @@
+import { readFileSync } from 'node:fs'
+import { describe, expect, it, vi, type MockInstance } from 'vitest'
+import {
+  cliGateOptions,
+  collectDescendants,
+  defaultConcurrency,
+  formatGateResultReason,
+  gatesForMode,
+  parsePidPpidLines,
+  runGate,
+  runGates,
+  taskkillArgs,
+  type Gate,
+  type GateResult,
+} from './run-gates.ts'
+
+/**
+ * Capture output a gate streams through runGate's streamOutput path.
+ * @returns the accumulated chunks and the stdout spy to restore in finally.
+ */
+function captureStreamedOutput(): { writes: string[]; write: MockInstance } {
+  const writes: string[] = []
+  const write = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+    writes.push(String(chunk))
+    return true
+  })
+  return { writes, write }
+}
+
+/**
+ * A process has stopped executing when its /proc entry is gone, or when it
+ * lingers as a zombie ('Z') — an un-reaped but dead entry still answers
+ * kill(pid, 0), so existence is not a liveness check. Non-Linux falls back to
+ * kill(pid, 0), whose ESRCH means the process is gone.
+ */
+function procStopped(pid: number): boolean {
+  if (process.platform === 'linux') {
+    try {
+      const stat = readFileSync(`/proc/${pid}/stat`, 'utf8')
+      return /\)\s+Z\s/.test(stat)
+    } catch {
+      return true
+    }
+  }
+  try {
+    process.kill(pid, 0)
+    return false
+  } catch {
+    return true
+  }
+}
+
+/**
+ * Wait until the captured output contains `marker` and the grandchild pid the
+ * gate printed, then return that pid.
+ * @param writes - chunks captured from the gate's streamed stdout.
+ * @param marker - the output line that proves the gate reached the abort point.
+ * @param deadline - fail the wait when exceeded.
+ * @returns the grandchild pid printed by the gate script.
+ */
+async function waitForGrandchildPid(writes: string[], marker: string, deadline: number): Promise<number> {
+  let pid: number | undefined
+  while ((pid === undefined || !writes.join('').includes(marker)) && Date.now() < deadline) {
+    const match = writes.join('').match(/grandchild:(\d+)/)
+    if (match !== null) pid = Number(match[1])
+    await new Promise(resolve => setTimeout(resolve, 50))
+  }
+  expect(pid ?? 0).toBeGreaterThan(0)
+  expect(writes.join('')).toContain(marker)
+  return pid!
+}
+
+/**
+ * Abort the run and assert it settles marked aborted with the grandchild no
+ * longer executing — the abort path must have signalled it from the captured
+ * descendant list rather than settling over a live orphan.
+ * @param promise - the pending `runGate` promise.
+ * @param controller - the signal source to abort.
+ * @param pid - the grandchild pid the gate script printed.
+ */
+async function abortAndExpectTreeStopped(promise: Promise<GateResult>, controller: AbortController, pid: number): Promise<void> {
+  controller.abort()
+  const result = await promise
+  expect(result.aborted).toBe(true)
+  const stopDeadline = Date.now() + 8000
+  while (!procStopped(pid) && Date.now() < stopDeadline) {
+    await new Promise(resolve => setTimeout(resolve, 50))
+  }
+  expect(procStopped(pid)).toBe(true)
+}
+
+
+function gate(id: string, options: Partial<Gate> = {}): Gate {
+  return {
+    id,
+    label: id,
+    displayCommand: `run ${id}`,
+    command: process.execPath,
+    args: ['-e', ''],
+    ...options,
+  }
+}
+
+function resultFor(subject: Gate, status: GateResult['status'] = 'passed'): GateResult {
+  return {
+    gate: subject,
+    status,
+    durationMs: 10,
+    output: [],
+    exitCode: status === 'passed' ? 0 : 1,
+    signalCode: null,
+  }
+}
+
+function withPnpmEntrypoint<T>(action: () => T, entrypoint = '/private/pnpm.cjs'): T {
+  const previous = process.env.npm_execpath
+  process.env.npm_execpath = entrypoint
+  try {
+    return action()
+  } finally {
+    if (previous === undefined) Reflect.deleteProperty(process.env, 'npm_execpath')
+    else process.env.npm_execpath = previous
+  }
+}
+
+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',
+    'ci-linux-primary',
+    'ci-static',
+    'ci-lint-contracts-ready',
+    'ci-coverage',
+    'ci-bench',
+    'ci-snapshot',
+    'ci-artifacts',
+    'ci-consumers',
+    'ci-windows-blocking',
+    'ci-windows-complete',
+    'ci-windows-observational',
+    'node-compat',
+    'check-all',
+    'hygiene',
+    'doc-sync',
+    'doc-quick',
+  ] as const)('constructs and executes preflight for a valid non-empty %s graph', async (mode) => {
+    const subject = withPnpmEntrypoint(() => gatesForMode(mode))
+    const execute = vi.fn(async (item: Gate) => resultFor(item))
+
+    await expect(runGates(subject, subject.length, execute)).resolves.toHaveLength(subject.length)
+  })
+
+  it('builds the native addon before benchmarks through the ci-bench script chain', () => {
+    const subject = withPnpmEntrypoint(() => gatesForMode('ci-bench'))
+    const { scripts } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as {
+      scripts: Record<string, string>
+    }
+
+    expect(scripts['check:ci:bench']).toBe('tsx scripts/run-gates.ts ci-bench')
+    expect(subject).toHaveLength(1)
+    expect(subject[0]).toMatchObject({
+      id: 'bench',
+      displayCommand: 'pnpm run test:bench',
+      args: ['/private/pnpm.cjs', 'run', 'test:bench'],
+    })
+    expect(scripts['test:bench']).toBe('npm run build:bench && npm run build:web && npm run test:bench:built')
+    expect(scripts['build:bench']).toBe(
+      'npm run build:native-system && npm run build:lib && tsdown --config benchmarks/tsdown.config.ts',
+    )
+    expect(scripts['build:native-system']).toBe('tsx native/system/scripts/build.ts --host-addon-only')
+    expect(scripts['test:bench:built']).toBe('vitest run --config vitest.bench.config.ts')
+  })
+
+  it('checks all maintained repository references locally and in CI', () => {
+    const { scripts } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as {
+      scripts: Record<string, string>
+    }
+    for (const mode of ['doc-sync', 'doc-quick', 'ci-static'] as const) {
+      const gates = withPnpmEntrypoint(() => gatesForMode(mode))
+      expect(gates).toContainEqual(expect.objectContaining({
+        id: 'repository-references',
+        displayCommand: 'pnpm run verify-repository-references',
+      }))
+    }
+    expect(scripts['verify-repository-references']).toBe('tsx scripts/verify-repository-references.ts')
+  })
+
+  it('keeps the public repository link policy in the documentation gate', () => {
+    const ids = withPnpmEntrypoint(() => gatesForMode('doc-sync').map(subject => subject.id))
+
+    expect(ids).toContain('public-repository-links')
+  })
+
+  it('keeps the concrete terminology policy in the documentation gate', () => {
+    const ids = withPnpmEntrypoint(() => gatesForMode('doc-sync').map(subject => subject.id))
+
+    expect(ids).toContain('concrete-terms')
+  })
+
+  it('checks retrospective releases alongside the current persistence history', () => {
+    for (const mode of ['doc-sync', 'ci-static'] as const) {
+      const ids = withPnpmEntrypoint(() => gatesForMode(mode).map(subject => subject.id))
+      expect(ids).toEqual(expect.arrayContaining(['persistence-changes', 'persistence-releases']))
+    }
+  })
+
+  it('requires complete Session format references locally and in CI', () => {
+    const { scripts } = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as {
+      scripts: Record<string, string>
+    }
+    for (const mode of ['doc-sync', 'doc-quick', 'ci-static'] as const) {
+      expect(withPnpmEntrypoint(() => gatesForMode(mode))).toContainEqual(expect.objectContaining({
+        id: 'persistence-formats',
+        displayCommand: 'pnpm run verify-persistence-formats',
+      }))
+    }
+    expect(scripts['verify-persistence-formats']).toBe('tsx scripts/persistence-formats.ts')
+  })
+
+  it('keeps package-group subsystem ownership in the documentation gate', () => {
+    const ids = withPnpmEntrypoint(() => gatesForMode('doc-sync').map(subject => subject.id))
+
+    expect(ids).toContain('subsystem-pages')
+  })
+
+  it('keeps the package README Summary limit in the documentation gate', () => {
+    const ids = withPnpmEntrypoint(() => gatesForMode('doc-sync').map(subject => subject.id))
+
+    expect(ids).toContain('package-readme-summaries')
+  })
+
+  it('derives the quick documentation aggregate from marked doc-sync leaves', () => {
+    const full = withPnpmEntrypoint(() => gatesForMode('doc-sync'))
+    const quick = withPnpmEntrypoint(() => gatesForMode('doc-quick'))
+
+    expect(quick).toEqual(full.filter(gate => gate.quick === true))
+  })
+
+  it('checks the recorded npm dependency catalog in both documentation aggregates', () => {
+    for (const mode of ['doc-sync', 'doc-quick'] as const) {
+      expect(withPnpmEntrypoint(() => gatesForMode(mode).find(gate => gate.id === 'dependency-catalog')))
+        .toMatchObject({ args: ['/private/pnpm.cjs', 'run', 'verify-dependency-catalog'] })
+    }
+  })
+
+  it('keeps the hygiene aggregate aligned with the package script checks', () => {
+    const ids = withPnpmEntrypoint(() => gatesForMode('hygiene').map(subject => subject.id))
+
+    expect(ids).toEqual([
+      'rescope-vendor', 'publint', 'constraints', 'default-product-isolation', 'package-dependencies', 'application-entrypoints',
+      'dsh-package-licenses', 'package-invariants', 'built-package-invariants', 'node-next-types',
+      'optional-dependency-imports', 'client-packages', 'client-ui-i18n', 'no-bare-dispatcher', 'cordis-config',
+      'runtime-closure',
+    ])
+    expect(defaultConcurrency('hygiene', ids.length, 8)).toEqual({
+      workers: 4,
+      source: '8 available CPU(s), hygiene cap 4',
+    })
+  })
+
+  it('schedules the longest documentation leaves before short checks', () => {
+    const ids = withPnpmEntrypoint(() => gatesForMode('doc-sync').map(subject => subject.id))
+
+    expect(ids.slice(0, 11)).toEqual([
+      'doc-typecheck', 'docs-site-build', 'doc-graphs', 'markdown-links', 'type-equivalence',
+      'cordis-catalog', 'cordis-inspect-catalog', 'workflow-guest', 'mermaid', 'scoped-events', 'translation-pairing',
+    ])
+  })
+
+  it('launches a native pnpm entrypoint directly', () => {
+    const entrypoint = String.raw`C:\Program Files\pnpm\pnpm.exe`
+    const subject = withPnpmEntrypoint(() => gatesForMode('ci-windows-blocking')[0], entrypoint)
+
+    expect(subject).toMatchObject({
+      command: entrypoint,
+      args: ['run', 'build'],
+    })
+  })
+
+  it.each(['ci-primary', 'ci-static', 'check-all'] as const)(
+    'keeps the DSH package license policy in %s',
+    (mode) => {
+      const ids = withPnpmEntrypoint(() => gatesForMode(mode).map(subject => subject.id))
+
+      expect(ids).toContain('dsh-package-licenses')
+    },
+  )
+
+  it.each(['ci-primary', 'ci-static', 'check-all', 'hygiene'] as const)(
+    'keeps package dependency enforcement in %s',
+    (mode) => {
+      const ids = withPnpmEntrypoint(() => gatesForMode(mode).map(subject => subject.id))
+
+      expect(ids).toContain('package-dependencies')
+    },
+  )
+
+  it.each(['ci-primary', 'ci-static', 'check-all', 'hygiene'] as const)(
+    'executes default-product experimental isolation in %s',
+    (mode) => {
+      const gate = withPnpmEntrypoint(() => gatesForMode(mode)
+        .find(subject => subject.id === 'default-product-isolation'))
+
+      expect(gate?.args).toContain('verify-default-product-isolation')
+      expect(gate?.allowFailure).not.toBe(true)
+    },
+  )
+
+  it.each(['ci-primary', 'ci-static', 'check-all'] as const)(
+    'keeps the client dependency policy in %s',
+    (mode) => {
+      const ids = withPnpmEntrypoint(() => gatesForMode(mode).map(subject => subject.id))
+
+      expect(ids).toContain('client-packages')
+    },
+  )
+
+  it.each(['ci-primary', 'ci-static', 'check-all'] as const)(
+    'keeps weighted approval policy tests in %s',
+    (mode) => {
+      const ids = withPnpmEntrypoint(() => gatesForMode(mode).map(subject => subject.id))
+
+      expect(ids).toContain('approval-policy')
+    },
+  )
+
+  it.each(['ci-primary', 'ci-static', 'check-all', 'hygiene'] as const)(
+    'keeps hard-coded Client UI copy enforcement in %s',
+    (mode) => {
+      const ids = withPnpmEntrypoint(() => gatesForMode(mode).map(subject => subject.id))
+
+      expect(ids).toContain('client-ui-i18n')
+    },
+  )
+
+  it.each(['ci-primary', 'ci-static', 'check-all', 'hygiene'] as const)(
+    'keeps application entrypoint enforcement in %s',
+    (mode) => {
+      const ids = withPnpmEntrypoint(() => gatesForMode(mode).map(subject => subject.id))
+
+      expect(ids).toContain('application-entrypoints')
+    },
+  )
+
+  it('keeps native Windows coverage blocking and behind the complete build', () => {
+    const complete = withPnpmEntrypoint(() => gatesForMode('ci-windows-complete'))
+    const observational = withPnpmEntrypoint(() => gatesForMode('ci-windows-observational'))
+      .filter(gate => gate.id !== 'build' && gate.id !== 'docs-site-build')
+    const byId = new Map(complete.map(subject => [subject.id, subject]))
+
+    expect(byId.get('coverage')?.allowFailure).not.toBe(true)
+    expect(byId.get('coverage')?.needs).toContain('build')
+    expect(byId.get('coverage-exempt-heavy')?.allowFailure).not.toBe(true)
+    expect(byId.get('coverage')?.needs).toContain('build')
+    expect(byId.get('coverage-exempt-heavy')?.needs).toContain('build')
+    expect(byId.get('coverage-exempt-heavy')?.args).toContain(
+      'packages/experimental/webworker-packer/tests/image-loadable.spec.ts',
+    )
+    expect(observational).not.toHaveLength(0)
+    for (const gate of observational) {
+      const completeGate = byId.get(gate.id)
+      expect(completeGate?.allowFailure).toBe(true)
+      expect(completeGate?.after).toEqual(expect.arrayContaining([
+        'coverage',
+        'coverage-exempt-heavy',
+      ]))
+      expect(completeGate?.needs).toEqual(gate.needs)
+    }
+  })
+
+  it('runs the Windows built-bin smoke after other observational gates settle', () => {
+    const observational = withPnpmEntrypoint(() => gatesForMode('ci-windows-observational'))
+    const builtBin = observational.find(gate => gate.id === 'built-bin-smoke')
+
+    expect(builtBin?.after).toEqual(
+      observational.filter(gate => gate.id !== 'built-bin-smoke').map(gate => gate.id),
+    )
+
+    const completeBuiltBin = withPnpmEntrypoint(() => gatesForMode('ci-windows-complete'))
+      .find(gate => gate.id === 'built-bin-smoke')
+    expect(completeBuiltBin?.after).toContain('windows-site')
+    expect(completeBuiltBin?.after).not.toContain('docs-site-build')
+  })
+
+  it('applies one configured test, polling, and hook timeout to both coverage gates', () => {
+    const gates = withEnv('DSH_COVERAGE_TEST_TIMEOUT_MS', '15000', () =>
+      withPnpmEntrypoint(() => gatesForMode('ci-windows-complete')))
+
+    for (const id of ['coverage', 'coverage-exempt-heavy']) {
+      expect(gates.find(subject => subject.id === id)?.args).toEqual(expect.arrayContaining([
+        '--testTimeout=15000',
+        '--expect.poll.timeout=15000',
+        '--hookTimeout=15000',
+      ]))
+    }
+  })
+
+  it('keeps Vitest timeout defaults when the coverage override is absent', () => {
+    const gates = withEnv('DSH_COVERAGE_TEST_TIMEOUT_MS', undefined, () =>
+      withPnpmEntrypoint(() => gatesForMode('ci-windows-complete')))
+
+    for (const id of ['coverage', 'coverage-exempt-heavy']) {
+      expect(gates.find(subject => subject.id === id)?.args).not.toEqual(expect.arrayContaining([
+        expect.stringMatching(/^--(?:testTimeout|expect\.poll\.timeout|hookTimeout)=/),
+      ]))
+    }
+  })
+
+  it('rejects an invalid coverage timeout before starting a gate', () => {
+    expect(() => withEnv('DSH_COVERAGE_TEST_TIMEOUT_MS', '0', () =>
+      withPnpmEntrypoint(() => gatesForMode('ci-windows-complete'))))
+      .toThrow('DSH_COVERAGE_TEST_TIMEOUT_MS must be a positive integer')
+  })
+
+  it('selects partitioned coverage only when explicitly configured', () => {
+    const coverage = withEnv('DSH_COVERAGE_PARTITIONS', '3', () =>
+      withPnpmEntrypoint(() => gatesForMode('ci-windows-complete').find(subject => subject.id === 'coverage')))
+
+    expect(coverage).toMatchObject({
+      displayCommand: 'DSH_COVERAGE_PARTITIONS=3 pnpm run test:coverage:partitioned',
+      args: ['/private/pnpm.cjs', 'run', 'test:coverage:partitioned'],
+      env: { DSH_COVERAGE_EXEMPT_HEAVY: '1' },
+      streamOutput: true,
+    })
+  })
+
+  it('rejects an invalid coverage partition count before starting a gate', () => {
+    expect(() => withEnv('DSH_COVERAGE_PARTITIONS', '1', () =>
+      withPnpmEntrypoint(() => gatesForMode('ci-windows-complete'))))
+      .toThrow('DSH_COVERAGE_PARTITIONS must be an integer greater than 1')
+  })
+
+  it.each([
+    ['empty', [], /gate graph has no gates/],
+    ['duplicate ids', [gate('same'), gate('same')], /duplicate gate id "same"/],
+    ['unknown dependencies', [gate('subject', { needs: ['missing'] })], /depends on unknown gate "missing"/],
+    ['unknown ordering predecessors', [gate('subject', { after: ['missing'] })], /waits for unknown gate "missing"/],
+    ['cycles', [gate('first', { needs: ['second'] }), gate('second', { needs: ['first'] })], /dependency cycle: first -> second -> first/],
+    ['mixed cycles', [gate('first', { after: ['second'] }), gate('second', { needs: ['first'] })], /dependency cycle: first -> second -> first/],
+  ] as const)('rejects %s before starting a child', async (_label, invalid, message) => {
+    const execute = vi.fn(async (subject: Gate) => resultFor(subject))
+
+    await expect(runGates([...invalid], 1, execute)).rejects.toThrow(message)
+    expect(execute).not.toHaveBeenCalled()
+  })
+
+  it('rejects an invalid worker count before starting a child', async () => {
+    const execute = vi.fn(async (subject: Gate) => resultFor(subject))
+
+    await expect(runGates([gate('subject')], 0, execute)).rejects.toThrow('max concurrency must be a positive integer')
+    expect(execute).not.toHaveBeenCalled()
+  })
+
+  it('skips dependents after their prerequisite fails', async () => {
+    const dependent = gate('dependent', { needs: ['root'] })
+    const root = gate('root')
+    const execute = vi.fn(async (subject: Gate) => resultFor(subject, 'failed'))
+
+    const results = await runGates([dependent, root], 1, execute)
+
+    expect(execute).toHaveBeenCalledOnce()
+    expect(execute).toHaveBeenCalledWith(root, undefined)
+    expect(results[0]).toMatchObject({ gate: dependent, status: 'skipped', error: 'dependency failed or skipped: root' })
+  })
+
+  it('runs an ordered follower after its predecessor fails', async () => {
+    const follower = gate('follower', { after: ['root'] })
+    const root = gate('root')
+    const execute = vi.fn(async (subject: Gate) => resultFor(subject, subject === root ? 'failed' : 'passed'))
+
+    const results = await runGates([follower, root], 2, execute)
+
+    expect(execute.mock.calls.map(([subject]) => subject.id)).toEqual(['root', 'follower'])
+    expect(results.map(result => result.status)).toEqual(['passed', 'failed'])
+  })
+
+  it('runs an ordered follower after its predecessor is skipped', async () => {
+    const follower = gate('follower', { after: ['dependent'] })
+    const dependent = gate('dependent', { needs: ['root'] })
+    const root = gate('root')
+    const execute = vi.fn(async (subject: Gate) => resultFor(subject, subject === root ? 'failed' : 'passed'))
+
+    const results = await runGates([follower, dependent, root], 2, execute)
+
+    expect(execute.mock.calls.map(([subject]) => subject.id)).toEqual(['root', 'follower'])
+    expect(results.map(result => result.status)).toEqual(['passed', 'skipped', 'failed'])
+  })
+})
+
+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-contracts-ready')[0]))
+
+    expect(subject).toMatchObject({
+      id: 'lint',
+      displayCommand: 'pnpm run lint:contracts-ready',
+      command: process.execPath,
+      args: ['/private/pnpm.cjs', 'run', 'lint:contracts-ready'],
+    })
+  })
+
+  it('surfaces the configured worker bound on the shared package script', () => {
+    const subject = withEnv('DSH_OXLINT_THREADS', '4', () =>
+      withPnpmEntrypoint(() => gatesForMode('ci-lint-contracts-ready')[0]))
+
+    expect(subject).toMatchObject({
+      id: 'lint',
+      displayCommand: 'DSH_OXLINT_THREADS=4 pnpm run lint:contracts-ready',
+      command: process.execPath,
+      args: ['/private/pnpm.cjs', 'run', 'lint:contracts-ready'],
+    })
+  })
+})
+
+describe('Typert contract preparation', () => {
+  it('prepares primary source consumers once before they run', () => {
+    const subject = withEnv('DSH_OXLINT_THREADS', undefined, () =>
+      withPnpmEntrypoint(() => gatesForMode('ci-primary')))
+
+    expect(subject.find(item => item.id === 'typert-contracts')).toMatchObject({
+      displayCommand: 'pnpm run build:lib:host',
+      args: ['/private/pnpm.cjs', 'run', 'build:lib:host'],
+    })
+    for (const [id, script] of [
+      ['typecheck', 'typecheck:contracts-ready'],
+      ['lint', 'lint:contracts-ready'],
+      ['doc-typecheck', 'doc-typecheck:contracts-ready'],
+    ] as const) {
+      expect(subject.find(item => item.id === id)).toMatchObject({
+        displayCommand: `pnpm run ${script}`,
+        args: ['/private/pnpm.cjs', 'run', script],
+        needs: ['typert-contracts'],
+      })
+    }
+    expect(subject.find(item => item.id === 'build')?.needs).toEqual([
+      'typecheck',
+      'lint',
+      'doc-typecheck',
+    ])
+  })
+
+  it('reuses contracts from the validated consumer build', () => {
+    const subject = withPnpmEntrypoint(() => gatesForMode('ci-consumers'))
+
+    expect(subject.find(item => item.id === 'lint-and-duplication')).toMatchObject({
+      displayCommand: 'pnpm run check:ci:lint:contracts-ready',
+      args: ['/private/pnpm.cjs', 'run', 'check:ci:lint:contracts-ready'],
+    })
+    expect(subject.find(item => item.id === 'doc-typecheck')).toMatchObject({
+      displayCommand: 'pnpm run doc-typecheck:contracts-ready',
+      args: ['/private/pnpm.cjs', 'run', 'doc-typecheck:contracts-ready'],
+    })
+  })
+
+  it('keeps standalone doc sync responsible for preparation', () => {
+    const docTypecheck = withPnpmEntrypoint(() =>
+      gatesForMode('doc-sync').find(item => item.id === 'doc-typecheck'))
+
+    expect(docTypecheck?.displayCommand).toBe('pnpm run doc-typecheck')
+  })
+})
+
+describe('Node compatibility graph', () => {
+  it('runs the jsdom environment smoke on every advertised Node line', () => {
+    const subject = withPnpmEntrypoint(() => gatesForMode('node-compat'))
+
+    expect(subject.find(item => item.id === 'vitest-jsdom-smoke')).toMatchObject({
+      label: 'Vitest jsdom smoke',
+      args: [
+        '/private/pnpm.cjs',
+        'exec',
+        'vitest',
+        'run',
+        'scripts/vitest-environment.compat.spec.ts',
+      ],
+    })
+  })
+})
+
+describe('Node 24 lane ownership', () => {
+  it('keeps the static lane source-only', () => {
+    const subject = withPnpmEntrypoint(() => gatesForMode('ci-static'))
+
+    expect(subject.map(item => item.id)).not.toContain('build')
+    expect(subject.map(item => item.id)).not.toContain('doc-typecheck')
+  })
+
+  it('owns the build and orders its artifact consumers', () => {
+    const subject = withPnpmEntrypoint(() => gatesForMode('ci-consumers'))
+
+    expect(defaultConcurrency('ci-consumers', subject.length, 4)).toEqual({
+      workers: 11,
+      source: 'ci-consumers gate count',
+    })
+    expect(subject.map(item => item.id)).toEqual([
+      'build',
+      'node-compat',
+      'publint',
+      'built-package-invariants',
+      'lint-and-duplication',
+      'snapshot',
+      'expected-output',
+      'web-snapshot',
+      'doc-typecheck',
+      'node-next-types',
+      'built-bin-smoke',
+    ])
+    expect(subject.find(item => item.id === 'publint')?.needs).toEqual(['build'])
+    expect(subject.find(item => item.id === 'build')?.env).toEqual({
+      DSH_BUILD_CLIENT_PROFILE: 'official',
+    })
+    expect(subject.find(item => item.id === 'node-compat')?.env).toEqual({
+      DSH_BUILD_CLIENT_PROFILE: 'official',
+    })
+    expect(subject.find(item => item.id === 'built-package-invariants')?.needs).toEqual(['build'])
+    expect(subject.find(item => item.id === 'lint-and-duplication')?.needs).toEqual(['built-package-invariants'])
+    for (const id of [
+      'snapshot',
+      'expected-output',
+      'web-snapshot',
+      'doc-typecheck',
+      'node-next-types',
+      'built-bin-smoke',
+    ]) {
+      expect(subject.find(item => item.id === id)?.needs).toEqual(['built-package-invariants'])
+    }
+    expect(subject.find(item => item.id === 'snapshot')?.env).toEqual({ DSH_EXAMPLE_MODE: 'lib' })
+    expect(subject.find(item => item.id === 'expected-output')?.env).toEqual({ DSH_EXAMPLE_MODE: 'lib' })
+    expect(subject.find(item => item.id === 'doc-typecheck')?.env).toEqual({
+      DSH_DOC_TYPECHECK_USE_BUILD_OUTPUT: '1',
+    })
+    expect(subject.find(item => item.id === 'built-bin-smoke')?.args).toEqual(
+      expect.arrayContaining([
+        'packages/subprocess/subprocess-local/tests/spawn-runner-built.e2e.ts',
+        'packages/subagent/subagent-codex/tests/loader-composition.e2e.ts',
+        'packages/subagent/subagent-claude-code/tests/loader-composition.e2e.ts',
+        'packages/experimental/agent-team/tests/built-lib.e2e.ts',
+      ]),
+    )
+    expect(subject.find(item => item.id === 'web-snapshot')).toMatchObject({
+      displayCommand: 'DSH_SNAPSHOT=replay pnpm run test:web:built',
+      env: { DSH_SNAPSHOT: 'replay' },
+      after: [
+        'publint',
+        'lint-and-duplication',
+        'snapshot',
+        'expected-output',
+        'doc-typecheck',
+        'node-next-types',
+        'built-bin-smoke',
+      ],
+    })
+  })
+})
+
+describe('Linux primary graph', () => {
+  it('adds the same compare-only web gate after built client artifacts', () => {
+    const subject = withPnpmEntrypoint(() => gatesForMode('ci-linux-primary'))
+    const web = subject.find(item => item.id === 'web-snapshot')
+
+    expect(web).toMatchObject({
+      displayCommand: 'DSH_SNAPSHOT=replay pnpm run test:web:built',
+      env: { DSH_SNAPSHOT: 'replay' },
+      needs: ['built-package-invariants'],
+    })
+  })
+})
+
+describe('gate process outcomes', () => {
+  it('streams selected gate output without retaining it', async () => {
+    const write = vi.spyOn(process.stdout, 'write').mockReturnValue(true)
+    try {
+      const result = await runGate(gate('streamed', {
+        args: ['-e', "process.stdout.write('live output')"],
+        streamOutput: true,
+      }))
+
+      expect(result.status).toBe('passed')
+      expect(result.output).toEqual([])
+      expect(write).toHaveBeenCalledWith('live output')
+    } finally {
+      write.mockRestore()
+    }
+  })
+
+  it.skipIf(process.platform === 'win32')('reports signal termination independently from exit status', async () => {
+    const result = await runGate(gate('terminated', {
+      args: ['-e', "process.kill(process.pid, 'SIGTERM')"],
+    }))
+
+    expect(result.status).toBe('failed')
+    expect(result.exitCode).toBeNull()
+    expect(result.signalCode).toBe('SIGTERM')
+    expect(formatGateResultReason(result)).toBe('signal SIGTERM')
+  })
+})
+
+describe('fail-fast scheduling', () => {
+  it('aborts the aggregate at the first blocking failure', async () => {
+    const slow = gate('slow')
+    const fast = gate('fast')
+    const dependent = gate('dependent', { needs: ['slow'] })
+    const execute = vi.fn(async (subject: Gate, signal?: AbortSignal) => {
+      if (subject.id === 'fast') {
+        return new Promise<GateResult>((resolve) => {
+          signal?.addEventListener('abort', () => {
+            // The real runGate marks a gate the abort terminated; the drain
+            // must then record it skipped rather than keep the failure.
+            resolve({ ...resultFor(subject, 'failed'), aborted: true })
+          }, { once: true })
+        })
+      }
+      return resultFor(subject, subject.id === 'slow' ? 'failed' : 'passed')
+    })
+
+    const results = await runGates([slow, fast, dependent], 2, execute, () => {}, { failFast: true })
+
+    expect(execute.mock.calls.map(([subject]) => subject.id)).toEqual(['slow', 'fast'])
+    expect(results.map(result => result.status)).toEqual(['failed', 'skipped', 'skipped'])
+    expect(results[1]).toMatchObject({
+      status: 'skipped',
+      error: 'aborted by fail-fast: slow failed',
+    })
+    expect(results[2]).toMatchObject({
+      status: 'skipped',
+      error: 'aborted by fail-fast: slow failed',
+    })
+  })
+
+  it('does not abort on a non-blocking gate failure', async () => {
+    const observational = gate('observational', { allowFailure: true })
+    const root = gate('root')
+    const execute = vi.fn(async (subject: Gate) => (
+      resultFor(subject, subject.id === 'observational' ? 'failed' : 'passed')
+    ))
+
+    const results = await runGates([observational, root], 2, execute, () => {}, { failFast: true })
+
+    expect(execute).toHaveBeenCalledTimes(2)
+    expect(results.map(result => result.status)).toEqual(['failed', 'passed'])
+  })
+
+  it('runs independent gates to completion when fail-fast is disabled', async () => {
+    const root = gate('root')
+    const sibling = gate('sibling')
+    const execute = vi.fn(async (subject: Gate) => (
+      resultFor(subject, subject.id === 'root' ? 'failed' : 'passed')
+    ))
+
+    const results = await runGates([root, sibling], 2, execute, () => {}, { failFast: false })
+
+    expect(execute).toHaveBeenCalledTimes(2)
+    expect(results.map(result => result.status)).toEqual(['failed', 'passed'])
+  })
+
+  it('kills the child when the abort signal fires', async () => {
+    const controller = new AbortController()
+    const promise = runGate(gate('killable', { args: ['-e', 'setInterval(() => {}, 1000)'] }), controller.signal)
+    controller.abort()
+    const result = await promise
+
+    expect(result.status).toBe('failed')
+    expect(result.aborted).toBe(true)
+    if (process.platform !== 'win32') expect(result.signalCode).toBe('SIGTERM')
+  })
+
+  it.skipIf(process.platform === 'win32')('marks a zero-exit child as aborted when the signal fired', async () => {
+    const { writes, write } = captureStreamedOutput()
+    try {
+      const controller = new AbortController()
+      const child = gate('traps-signal', {
+        args: ['-e', "process.stdout.write('ready\\n'); process.on('SIGTERM', () => process.exit(0)); setInterval(() => {}, 1000)"],
+        streamOutput: true,
+      })
+      const promise = runGate(child, controller.signal)
+      // Wait for the child to register its SIGTERM trap before aborting, so
+      // the signal is caught and the child really exits zero.
+      const deadline = Date.now() + 5000
+      while (!writes.join('').includes('ready') && Date.now() < deadline) {
+        await new Promise(resolve => setTimeout(resolve, 10))
+      }
+      controller.abort()
+      const result = await promise
+
+      // The child trapped the signal and exited zero; the drain must not
+      // report this gate passed, so the raw outcome carries the abort mark.
+      expect(result.status).toBe('passed')
+      expect(result.aborted).toBe(true)
+    } finally {
+      write.mockRestore()
+    }
+  })
+
+  it.skipIf(process.platform === 'win32')('kills the whole gate process tree when the abort signal fires', async () => {
+    const { writes, write } = captureStreamedOutput()
+    const controller = new AbortController()
+    let promise: Promise<GateResult> | undefined
+    try {
+      const script = [
+        "const { spawn } = require('node:child_process')",
+        // Detached, so the grandchild leads its own process group: the gate
+        // group signal cannot reach it, and only the descendant enumeration in
+        // treeKill does — the shape of a nested run-gates' leaf gates.
+        "const grandchild = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { detached: true })",
+        "process.stdout.write('grandchild:' + grandchild.pid + '\\n')",
+        'setInterval(() => {}, 1000)',
+      ].join(';')
+      promise = runGate(gate('tree', { args: ['-e', script], streamOutput: true }), controller.signal)
+      const deadline = Date.now() + 5000
+      let pid: number | undefined
+      while (pid === undefined && Date.now() < deadline) {
+        const match = writes.join('').match(/grandchild:(\d+)/)
+        if (match !== null) pid = Number(match[1])
+        else await new Promise(resolve => setTimeout(resolve, 20))
+      }
+      expect(pid ?? 0).toBeGreaterThan(0)
+      controller.abort()
+      const result = await promise
+      expect(result.status).toBe('failed')
+      // The descendant enumeration signals the detached grandchild at the same
+      // time as the group signal reaches the direct child; the direct child's
+      // own death closes the gate pipes, so poll for the grandchild to stop
+      // executing rather than asserting on a fixed instant.
+      const stopDeadline = Date.now() + 5000
+      while (!procStopped(pid!) && Date.now() < stopDeadline) {
+        await new Promise(resolve => setTimeout(resolve, 20))
+      }
+      expect(procStopped(pid!)).toBe(true)
+    } finally {
+      // A failed wait or assertion must not leave the forever-looping detached
+      // grandchild behind on the host: abort the gate and wait for the
+      // process tree to settle before restoring the spy.
+      controller.abort()
+      await promise
+      write.mockRestore()
+    }
+  })
+
+  it('forwards host interruption signals to the abort path', async () => {
+    const slow = gate('slow')
+    const sibling = gate('sibling')
+    const execute = vi.fn(async (subject: Gate, signal?: AbortSignal) => {
+      if (subject.id === 'slow') {
+        return new Promise<GateResult>((resolve) => {
+          signal?.addEventListener('abort', () => {
+            // A child can trap the signal and exit zero; the drain must still
+            // record the gate skipped so the interrupted run fails.
+            resolve({ ...resultFor(subject, 'passed'), aborted: true })
+          }, { once: true })
+        })
+      }
+      return resultFor(subject)
+    })
+
+    const promise = runGates([slow, sibling], 1, execute, () => {}, { failFast: true, forwardProcessSignals: true })
+    // The first loop iteration starts `slow` synchronously, so its abort
+    // listener is registered before the signal is emitted.
+    process.emit('SIGTERM')
+    const results = await promise
+
+    expect(execute).toHaveBeenCalledOnce()
+    expect(results.map(result => result.status)).toEqual(['skipped', 'skipped'])
+    expect(results[0]).toMatchObject({
+      status: 'skipped',
+      error: 'aborted by fail-fast: host interruption',
+    })
+  })
+
+  it('pairs host signal forwarding with fail-fast at the CLI entrypoint', () => {
+    expect(cliGateOptions(true)).toEqual({ failFast: true, forwardProcessSignals: true })
+    expect(cliGateOptions(false)).toEqual({ failFast: false, forwardProcessSignals: false })
+  })
+
+  it('rejects host signal forwarding without fail-fast', async () => {
+    const execute = vi.fn(async (subject: Gate) => resultFor(subject))
+
+    await expect(runGates([gate('subject')], 1, execute, () => {}, { forwardProcessSignals: true }))
+      .rejects.toThrow('forwardProcessSignals requires failFast')
+    expect(execute).not.toHaveBeenCalled()
+  })
+
+  it('leaves an un-aborted child running to completion', async () => {
+    const result = await runGate(gate('settles', { args: ['-e', ''] }), new AbortController().signal)
+
+    expect(result.status).toBe('passed')
+    expect(result.aborted).toBe(false)
+  })
+
+  it.skipIf(process.platform === 'win32')('kills a detached descendant that outlived the child when the abort arrives later', async () => {
+    const writes: string[] = []
+    const write = vi.spyOn(process.stdout, 'write').mockImplementation((chunk) => {
+      writes.push(String(chunk))
+      return true
+    })
+    const controller = new AbortController()
+    let promise: Promise<GateResult> | undefined
+    try {
+      const script = [
+        "const { spawn } = require('node:child_process')",
+        // Detached with inherited stdio: the grandchild leads its own process
+        // group (the gate group signal misses it) and holds the gate's
+        // stdout write end (so `close` stays pending past the child exit).
+        "const grandchild = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { detached: true, stdio: 'inherit' })",
+        "process.stdout.write('grandchild:' + grandchild.pid + '\\n')",
+        // Outlive the first descendant-sampler tick with margin so the cache
+        // holds the grandchild even on a loaded runner, then exit normally
+        // before the abort arrives.
+        "setTimeout(() => { process.stdout.write('child-exit\\n'); process.exit(0) }, 8000)",
+      ].join(';')
+      promise = runGate(gate('late-abort', { args: ['-e', script], streamOutput: true }), controller.signal)
+      const pid = await waitForGrandchildPid(writes, 'child-exit', Date.now() + 10000)
+      // terminate must not re-enumerate over the sampler cache now that the
+      // child is gone; the detached grandchild is killed from the cached list.
+      await abortAndExpectTreeStopped(promise, controller, pid)
+    } finally {
+      // A failed wait or assertion must not leave the forever-looping detached
+      // grandchild behind on the host: abort the gate and wait for the
+      // process tree to settle before restoring the spy.
+      controller.abort()
+      await promise
+      write.mockRestore()
+    }
+  }, 20000)
+
+  it.skipIf(process.platform === 'win32')('keeps a reparented detached descendant tracked across a sampler tick', async () => {
+    const { writes, write } = captureStreamedOutput()
+    const controller = new AbortController()
+    let promise: Promise<GateResult> | undefined
+    try {
+      const script = [
+        "const { spawn } = require('node:child_process')",
+        // Wrapper spawns a detached grandchild with inherited stdio (its own
+        // process group, holding the gate's stdout write end), prints the pid,
+        // then exits after 7 seconds — after the first sampler tick, before
+        // the second. From then on the grandchild is reparented and
+        // unreachable by parent id.
+        "const wrapper = spawn(process.execPath, ['-e', \"const { spawn } = require('node:child_process'); const grandchild = spawn(process.execPath, ['-e', 'setInterval(() => {}, 1000)'], { detached: true, stdio: 'inherit' }); process.stdout.write('grandchild:' + grandchild.pid + '\\\\n'); setTimeout(() => process.exit(0), 7000)\"], { stdio: 'inherit' })",
+        "wrapper.on('exit', () => process.stdout.write('wrapper-exited\\n'))",
+        // Keep the root child alive past the abort with a heartbeat so the
+        // test can abort while it is still running.
+        "setInterval(() => process.stdout.write('hb\\n'), 1000)",
+      ].join(';')
+      promise = runGate(gate('sampler-merge', { args: ['-e', script], streamOutput: true }), controller.signal)
+      const pid = await waitForGrandchildPid(writes, 'wrapper-exited', Date.now() + 15000)
+      // Wait past the second sampler tick (t=10) with margin: a replacing tick
+      // would drop the reparented grandchild from the cache, after which the
+      // abort cannot reach it. The root child keeps running throughout.
+      const tickDeadline = Date.now() + 10000
+      const wrapperExitedAt = Date.now()
+      while (Date.now() - wrapperExitedAt < 5000 && Date.now() < tickDeadline) {
+        await new Promise(resolve => setTimeout(resolve, 50))
+      }
+      expect(Date.now() - wrapperExitedAt).toBeGreaterThanOrEqual(5000)
+      await abortAndExpectTreeStopped(promise, controller, pid)
+    } finally {
+      // A failed wait or assertion must not leave the forever-looping detached
+      // grandchild behind on the host: abort the gate and wait for the
+      // process tree to settle before restoring the spy.
+      controller.abort()
+      await promise
+      write.mockRestore()
+    }
+  }, 30000)
+})
+
+describe('process-table parsing', () => {
+  it('excludes the root when a parent link returns to it', () => {
+    expect(collectDescendants(100, [[200, 100], [100, 200], [300, 200]]))
+      .toEqual([200, 300])
+  })
+
+  it('visits duplicate and cyclic descendant links only once', () => {
+    expect(collectDescendants(100, [
+      [200, 100], [200, 100], [300, 100], [200, 200], [400, 200], [200, 400], [500, 300], [900, 800],
+    ])).toEqual([200, 300, 400, 500])
+  })
+
+  it('returns no descendants for an isolated or self-parented root', () => {
+    expect(collectDescendants(100, [])).toEqual([])
+    expect(collectDescendants(100, [[100, 100]])).toEqual([])
+  })
+
+  it('walks a wide child set without spreading it into call arguments', () => {
+    const children = Array.from({ length: 150_000 }, (_, i): [number, number] => [i + 3, 2])
+    const descendants = collectDescendants(1, [[2, 1], ...children])
+    expect(descendants).toHaveLength(children.length + 1)
+    expect(descendants[0]).toBe(2)
+    expect(descendants.at(-1)).toBe(150_002)
+  })
+
+  it('parses `pid ppid` rows from a POSIX ps dump', () => {
+    expect(parsePidPpidLines('  123   1\n456 123\n  789 456\n')).toEqual([[123, 1], [456, 123], [789, 456]])
+  })
+
+  it('parses Windows PowerShell Get-CimInstance output of the same shape', () => {
+    expect(parsePidPpidLines(' 123 1\r\n456 123\r\n')).toEqual([[123, 1], [456, 123]])
+  })
+
+  it('drops blank and malformed lines', () => {
+    expect(parsePidPpidLines('  123   1\n\ncommand not found\n999 abc\n')).toEqual([[123, 1]])
+  })
+})
+
+describe('Windows tree termination', () => {
+  it('targets the root first and each captured descendant after it', () => {
+    expect(taskkillArgs(100, [201, 302, 403])).toEqual([
+      ['/PID', '100', '/T', '/F'],
+      ['/PID', '201', '/T', '/F'],
+      ['/PID', '302', '/T', '/F'],
+      ['/PID', '403', '/T', '/F'],
+    ])
+  })
+
+  it('terminates the root alone when no descendant was captured', () => {
+    expect(taskkillArgs(100, [])).toEqual([['/PID', '100', '/T', '/F']])
+  })
+})

scripts/run-web-snapshots.ts

@@ -0,0 +1,44 @@
+/** Run serial browser owners before one bounded snapshot pool. */
+import { spawn } from 'node:child_process'
+import { pnpmInvocation } from './pnpm-invocation.ts'
+
+const serialFiles = [
+  'apps/web/tests/hmr-live.e2e.ts',
+  'apps/web/tests/cordis-tool-round.e2e.ts',
+]
+const workerRaw = process.env.DSH_WEB_SNAPSHOT_WORKERS
+const workers = Number.parseInt(workerRaw ?? '', 10)
+if (!Number.isSafeInteger(workers) || workers < 2 || String(workers) !== workerRaw) {
+  throw new Error(`DSH_WEB_SNAPSHOT_WORKERS must be an integer greater than 1, got ${JSON.stringify(workerRaw)}.`)
+}
+const invocation = pnpmInvocation(['exec', 'vitest', 'run', '--config', 'vitest.web.config.ts'])
+let serialStatus = 0
+for (const file of serialFiles) {
+  serialStatus = await run(invocation.command, [...invocation.args, file])
+  if (serialStatus !== 0) break
+}
+if (serialStatus === 0) {
+  process.exitCode = await run(invocation.command, [
+    ...invocation.args,
+    ...serialFiles.map(file => `--exclude=${file}`),
+    '--fileParallelism',
+    `--maxWorkers=${String(workers)}`,
+  ])
+} else {
+  process.exitCode = serialStatus
+}
+
+function run(command: string, args: string[]): Promise<number> {
+  return new Promise((resolveRun, reject) => {
+    const child = spawn(command, args, { stdio: 'inherit' })
+    child.once('error', reject)
+    child.once('exit', (exitCode, signalCode) => {
+      if (signalCode !== null) {
+        console.error(`web snapshots terminated by ${signalCode}`)
+        resolveRun(1)
+        return
+      }
+      resolveRun(exitCode ?? 1)
+    })
+  })
+}

scripts/session-query-spill-command.spec.ts

@@ -0,0 +1,67 @@
+import { Context } from '@deepseek-ai/cordis'
+import { LocalSpillStore } from '@deepseek-ai/dsh-spill-local'
+import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
+import LocalSubprocessRuntime from '@deepseek-ai/dsh-subprocess-local'
+import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import { ToolCallId } from '@deepseek-ai/dsh-llm'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { expect, it } from 'vitest'
+import * as locators from './snapshot-spill-locators.ts'
+import * as commands from '../snapshots/session/session-query-spill/resolve-spill-command.mjs'
+
+it.skipIf(process.platform === 'win32')('resolves the exact spill verifier, retains real failures, and restores the shell', async () => {
+  const root = await mkdtemp(join(tmpdir(), "query-spill-'quoted-"))
+  const ctx = new Context()
+  const disposers: (() => Promise<void>)[] = []
+  try {
+    for (const fiber of [
+      ctx.plugin(LocalSpillStore, { root, cleanupPeriodDays: 0 }),
+      ctx.plugin(LocalFileSystem, { cwd: root }),
+      ctx.plugin(LocalSubprocessRuntime),
+      ctx.plugin(LocalBashExecutor),
+    ]) {
+      disposers.push(() => fiber.dispose())
+      await fiber
+    }
+    const logical = resolve('/tmp/dsh-acp-snap-query-verifier')
+    const mapping = ctx.plugin(locators, { root, locatorRoot: logical })
+    disposers.push(() => mapping.dispose())
+    await mapping
+    const saved = await ctx.spillStore.saveText({
+      owner: { sessionId: SessionId('query-verifier') },
+      source: { kind: 'tool', toolName: 'session_event_read', callId: ToolCallId('query'), label: 'result' },
+      suggestedName: 'session_event_read.txt', content: 'request/header session_event_search',
+    })
+    const adapter = ctx.plugin(commands)
+    disposers.push(() => adapter.dispose())
+    await adapter
+    const command = 'file="' + saved.locator + '"' + "; grep -Fq request/header \"$file\" && grep -Fq session_event_search \"$file\" && printf 'SPILL_CANONICAL_OK\\n'"
+    const spec = ctx.shell.resolve({ command })
+    const output = await ctx.shell.run(spec)
+    expect(output.timedOut).toBe(false)
+    expect(output.exitCode).toBe(0)
+    expect(output.stdout.text).toBe('SPILL_CANONICAL_OK\n')
+    expect(spec.command).toBe(command)
+    const other = await ctx.shell.run(ctx.shell.resolve({ command: 'printf ordinary; exit 7' }))
+    expect(other.exitCode).toBe(7)
+    expect(other.stdout.text).toBe('ordinary')
+    const unmatched = await ctx.shell.run(ctx.shell.resolve({ command: command + '; exit 9' }))
+    expect(unmatched.exitCode).toBe(9)
+    expect(unmatched.stderr.text).toContain('No such file')
+    const physical = ctx.fs.processPath(await ctx.fs.resolve(saved.locator))
+    await rm(physical)
+    const missing = await ctx.shell.run(spec)
+    expect(missing.exitCode).not.toBe(0)
+    expect(missing.stdout.text).toBe('')
+    await adapter.dispose()
+    const restored = await ctx.shell.run(spec)
+    expect(restored.exitCode).not.toBe(0)
+    expect(restored.stderr.text).toContain(saved.locator)
+  } finally {
+    for (const dispose of disposers.reverse()) await dispose()
+    await rm(root, { recursive: true, force: true })
+  }
+})

scripts/slot-walk.ts

@@ -0,0 +1,429 @@
+/**
+ * AST helpers for the client slot surface: the `SlotMap` declaration merges
+ * that type every slot, and the `slots.register` call sites that say who
+ * already occupies one. Both readings are lexical (no type-checker program):
+ * the client catalog generator consumes them, and the same scan doubles as its
+ * own exhaustiveness backstop because it reads every source file rather than a
+ * reachable-export closure.
+ */
+
+import { globSync, readFileSync } from 'node:fs'
+import { dirname, join, resolve, sep } from 'node:path'
+import ts from 'typescript'
+
+/** The module whose `SlotMap` / standard-kit interfaces every slot owner merges into. */
+const SLOTS_MODULE = '@deepseek-ai/dsh-client-ui-slots'
+
+/** Cheap textual prefilter for a slot-contract merge, quote-style agnostic. */
+const MERGE_HEAD = /declare module ['"]@deepseek-ai\/dsh-client-ui-slots['"]/
+
+/** Cheap textual prefilter for a registration call site. */
+const REGISTER_HEAD = /\.register\(/
+
+/** One `SlotMap` member: the slot's contract as its owning package declares it. */
+export interface SlotDeclaration {
+  /** SlotMap key, e.g. `settings.section`. */
+  key: string
+  /** Cardinality literal (`single` / `list` / `keyed` / `chain`), or '' when not a literal. */
+  kind: string
+  /** Data-scope literal (`root` / `session` / `session-maybe`), or '' when not a literal. */
+  scope: string
+  /** Type name of the owner-supplied props share, absent when the slot declares none. */
+  ownerType?: string
+  /** Source text of the `keyProps` member (keyed slots), absent otherwise. */
+  keyProps?: string
+  /** Source text of the `hookContext` member, absent otherwise. */
+  hookContext?: string
+  /** Type name of the slot-level inject face, absent when the slot declares none. */
+  injectType?: string
+  /** The member's JSDoc with container indentation removed, '' when undocumented. */
+  jsDoc: string
+  /** Workspace package that declares the contract. */
+  package: string
+  /** Source pointer `packages/…/file.ts:line`. */
+  source: string
+}
+
+/** One `slots.register({ name, … }, Component)` call site. */
+export interface SlotRegistration {
+  /** Target SlotMap key the entry contributes into. */
+  key: string
+  /** Workspace package that registers the entry. */
+  package: string
+  /** Component argument as written (identifier, or a trimmed expression). */
+  component: string
+  /** `id` literal of a list entry, absent otherwise. */
+  id?: string
+  /** `key` literal of a keyed entry, absent otherwise. */
+  entryKey?: string
+  /** SlotMap keys this registration declares as children (they exist while it is mounted). */
+  children: string[]
+  /** Source pointer `packages/…/file.ts:line`. */
+  source: string
+}
+
+/** One exported type declaration, retained with its JSDoc for catalog projection. */
+export interface TypeDeclaration {
+  /** Declared name. */
+  name: string
+  /** Full declaration text INCLUDING its JSDoc (member docs are the teaching text). */
+  text: string
+  /** Source pointer `packages/…/file.ts:line`. */
+  source: string
+}
+
+/** One scanned source file with the artifacts the catalog reads from it. */
+export interface ScannedFile {
+  /** Repo-relative, `/`-normalized path. */
+  rel: string
+  /** Workspace package name that owns the file. */
+  package: string
+  /** Parsed source file. */
+  sf: ts.SourceFile
+}
+
+/**
+ * Parse every file matching `patterns`, keeping the ones that carry a slot
+ * contract merge or a registration call. Files without either are skipped so
+ * the scan stays cheap over the whole workspace.
+ * @param scanRoot - repository root the patterns resolve against.
+ * @param patterns - glob(s) selecting the TypeScript/TSX files to scan.
+ * @returns one entry per interesting file, in path order.
+ */
+export function scanSlotFiles(scanRoot: string, patterns: readonly string[]): ScannedFile[] {
+  const out: ScannedFile[] = []
+  const names = new Map<string, string>()
+  const rels = [...new Set(globSync(patterns as string[], { cwd: scanRoot })
+    .map(path => path.split(sep).join('/')))].sort()
+  for (const rel of rels) {
+    const abs = resolve(scanRoot, rel)
+    const text = readFileSync(abs, 'utf8')
+    if (!MERGE_HEAD.test(text) && !REGISTER_HEAD.test(text)) continue
+    out.push({
+      rel,
+      package: packageNameOf(scanRoot, rel, names),
+      sf: ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, true, scriptKindOf(rel)),
+    })
+  }
+  return out
+}
+
+/**
+ * Index every exported type declaration of the scanned packages, keeping JSDoc.
+ * The catalog resolves owner-props and inject-face shapes through this index
+ * instead of a type-checker program: the declaration text with its member
+ * documentation IS the teaching material a registrant needs.
+ * @param scanRoot - repository root the patterns resolve against.
+ * @param patterns - glob(s) selecting the TypeScript/TSX files to index.
+ * @returns name → declaration, with names declared more than once dropped as ambiguous.
+ */
+export function indexExportedTypes(scanRoot: string, patterns: readonly string[]): Map<string, TypeDeclaration> {
+  const index = new Map<string, TypeDeclaration>()
+  const ambiguous = new Set<string>()
+  const rels = [...new Set(globSync(patterns as string[], { cwd: scanRoot })
+    .map(path => path.split(sep).join('/')))].sort()
+  for (const rel of rels) {
+    const abs = resolve(scanRoot, rel)
+    const sf = ts.createSourceFile(abs, readFileSync(abs, 'utf8'), ts.ScriptTarget.Latest, true, scriptKindOf(rel))
+    for (const statement of sf.statements) {
+      if (!ts.isInterfaceDeclaration(statement) && !ts.isTypeAliasDeclaration(statement)) continue
+      if (!statement.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.ExportKeyword)) continue
+      const name = statement.name.text
+      if (index.has(name)) {
+        ambiguous.add(name)
+        continue
+      }
+      index.set(name, {
+        name,
+        text: declarationText(statement, sf),
+        source: `${rel}:${String(lineOf(sf, statement))}`,
+      })
+    }
+  }
+  for (const name of ambiguous) index.delete(name)
+  return index
+}
+
+/**
+ * Read every `SlotMap` member declared in one scanned file.
+ * @param file - a file returned by {@link scanSlotFiles}.
+ * @returns the declared slots, in source order.
+ */
+export function slotDeclarations(file: ScannedFile): SlotDeclaration[] {
+  const out: SlotDeclaration[] = []
+  for (const body of slotModuleBodies(file.sf)) {
+    for (const statement of body.statements) {
+      if (!ts.isInterfaceDeclaration(statement) || statement.name.text !== 'SlotMap') continue
+      for (const member of statement.members) {
+        if (!ts.isPropertySignature(member) || member.type === undefined) continue
+        const key = ts.isStringLiteral(member.name) || ts.isIdentifier(member.name)
+          ? member.name.text
+          : member.name.getText(file.sf)
+        const entry = ts.isTypeLiteralNode(member.type) ? member.type : undefined
+        const ownerType = memberTypeText(entry, 'owner', file.sf)
+        const keyProps = memberTypeText(entry, 'keyProps', file.sf)
+        const hookContext = memberTypeText(entry, 'hookContext', file.sf)
+        const injectType = memberTypeText(entry, 'inject', file.sf)
+        out.push({
+          key,
+          kind: literalMember(entry, 'kind'),
+          scope: literalMember(entry, 'scope'),
+          ...ownerType === undefined ? {} : { ownerType },
+          ...keyProps === undefined ? {} : { keyProps },
+          ...hookContext === undefined ? {} : { hookContext },
+          ...injectType === undefined ? {} : { injectType },
+          jsDoc: jsDocOf(member, file.sf),
+          package: file.package,
+          source: `${file.rel}:${String(lineOf(file.sf, member))}`,
+        })
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * Read every registration call site in one scanned file: which slot it
+ * occupies, with which component and cell identity, and which child slots it
+ * declares. A call whose `name` is not a string literal is skipped — the
+ * shipped composition always names its target literally, and a computed name
+ * carries no catalog fact.
+ * @param file - a file returned by {@link scanSlotFiles}.
+ * @returns the registrations, in source order.
+ */
+export function slotRegistrations(file: ScannedFile): SlotRegistration[] {
+  const out: SlotRegistration[] = []
+  const visit = (node: ts.Node): void => {
+    if (ts.isCallExpression(node)
+      && ts.isPropertyAccessExpression(node.expression)
+      && node.expression.name.text === 'register'
+      && isSlotsReceiver(node.expression.expression, file.sf)
+      && node.arguments.length >= 1) {
+      const options = node.arguments[0]
+      if (options !== undefined && ts.isObjectLiteralExpression(options)) {
+        const key = stringProperty(options, 'name')
+        if (key !== undefined) {
+          const id = stringProperty(options, 'id')
+          const entryKey = stringProperty(options, 'key')
+          out.push({
+            key,
+            package: file.package,
+            component: componentText(node.arguments[1], file.sf),
+            ...id === undefined ? {} : { id },
+            ...entryKey === undefined ? {} : { entryKey },
+            children: childKeys(options),
+            source: `${file.rel}:${String(lineOf(file.sf, node))}`,
+          })
+        }
+      }
+    }
+    ts.forEachChild(node, visit)
+  }
+  visit(file.sf)
+  return out
+}
+
+/**
+ * Read one standard-kit interface's members from the scanned files: the props
+ * a slot component receives for free from the framework at a given scope.
+ * @param files - scanned files to search.
+ * @param interfaceName - `GlobalStandardProps`, `SessionStandardProps`, or `SessionMaybeStandardProps`.
+ * @returns `member: type` texts in declaration order, merged across declaring files.
+ */
+export function standardKitMembers(files: readonly ScannedFile[], interfaceName: string): string[] {
+  const out: string[] = []
+  for (const file of files) {
+    for (const body of slotModuleBodies(file.sf)) {
+      for (const statement of body.statements) {
+        if (!ts.isInterfaceDeclaration(statement) || statement.name.text !== interfaceName) continue
+        for (const member of statement.members) {
+          if (!ts.isPropertySignature(member)) continue
+          const type = member.type === undefined ? 'unknown' : member.type.getText(file.sf)
+          out.push(`${member.name.getText(file.sf)}${member.questionToken === undefined ? '' : '?'}: ${collapse(type)}`)
+        }
+      }
+    }
+  }
+  return out
+}
+
+/**
+ * Names in the type index that seed texts mention, word-bounded — ONE level, not
+ * a transitive closure. The catalog expands an owner-props contract exactly one
+ * step: the owner interface carries the interaction protocol in its own member
+ * documentation, while the shapes its fields reference belong to the subsystems
+ * that own them and would otherwise drag the entire session model into a single
+ * slot's report.
+ * @param seeds - declaration or signature texts to search.
+ * @param index - the type index from {@link indexExportedTypes}.
+ * @returns the mentioned names, sorted.
+ */
+export function referencedTypeNames(
+  seeds: readonly string[],
+  index: ReadonlyMap<string, TypeDeclaration>,
+): string[] {
+  const found: string[] = []
+  for (const name of index.keys()) {
+    const pattern = new RegExp(`\\b${name}\\b`)
+    if (seeds.some(text => pattern.test(text))) found.push(name)
+  }
+  return found.sort()
+}
+
+/**
+ * Resolve declarations by name, dropping names the index does not hold.
+ * @param names - type names to resolve.
+ * @param index - the type index from {@link indexExportedTypes}.
+ * @returns the resolved declarations, sorted by name.
+ */
+export function declaredTypes(
+  names: readonly string[],
+  index: ReadonlyMap<string, TypeDeclaration>,
+): TypeDeclaration[] {
+  return [...names]
+    .flatMap(name => index.get(name) ?? [])
+    .sort((left, right) => left.name.localeCompare(right.name))
+}
+
+/** Every slot-contract module block in one file, in source order. */
+function slotModuleBodies(sf: ts.SourceFile): ts.ModuleBlock[] {
+  const bodies: ts.ModuleBlock[] = []
+  for (const statement of sf.statements) {
+    if (!ts.isModuleDeclaration(statement) || !ts.isStringLiteral(statement.name)) continue
+    if (statement.name.text !== SLOTS_MODULE) continue
+    if (statement.body !== undefined && ts.isModuleBlock(statement.body)) bodies.push(statement.body)
+  }
+  return bodies
+}
+
+/**
+ * Whether a `X.register(...)` receiver is the slots service. Every other
+ * registry in the repo (`ctx.tools`, `ctx.commands`, `ctx.settings`, …) also
+ * takes an options object with a `name`, so the receiver is what separates a
+ * slot occupancy fact from an unrelated registration.
+ */
+function isSlotsReceiver(receiver: ts.Expression, sf: ts.SourceFile): boolean {
+  const text = receiver.getText(sf)
+  return text === 'slots' || text.endsWith('.slots')
+}
+
+/** The workspace package name owning a repo-relative file, memoized per package root. */
+function packageNameOf(scanRoot: string, rel: string, cache: Map<string, string>): string {
+  let dir = dirname(resolve(scanRoot, rel))
+  while (dir.length > scanRoot.length) {
+    const cached = cache.get(dir)
+    if (cached !== undefined) return cached
+    try {
+      const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as { name?: unknown }
+      if (typeof manifest.name === 'string') {
+        cache.set(dir, manifest.name)
+        return manifest.name
+      }
+    } catch {
+      // No manifest at this level: keep walking up to the owning package root.
+    }
+    dir = dirname(dir)
+  }
+  return '(unknown package)'
+}
+
+/** TSX must parse as TSX; a `.ts` file with JSX-looking generics must not. */
+function scriptKindOf(rel: string): ts.ScriptKind {
+  return rel.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS
+}
+
+/** 1-based line of a node's first character. */
+function lineOf(sf: ts.SourceFile, node: ts.Node): number {
+  return sf.getLineAndCharacterOfPosition(node.getStart(sf)).line + 1
+}
+
+/** Declaration text including leading JSDoc, with container indentation removed. */
+function declarationText(statement: ts.Node, sf: ts.SourceFile): string {
+  return dedent(sf.text.slice(statement.getStart(sf, true), statement.getEnd()))
+}
+
+/** One member's JSDoc comment text, '' when the member has none. */
+function jsDocOf(member: ts.Node, sf: ts.SourceFile): string {
+  // getStart(includeJsDoc) brackets exactly the doc comment: with it the range
+  // opens at `/**`, without it at the member itself.
+  const withDoc = member.getStart(sf, true)
+  const withoutDoc = member.getStart(sf, false)
+  if (withDoc >= withoutDoc) return ''
+  return dedent(sf.text.slice(withDoc, withoutDoc).trimEnd())
+}
+
+/** Strip the shared leading indentation of a multi-line source slice. */
+function dedent(text: string): string {
+  const lines = text.split('\n')
+  const indents = lines.slice(1).filter(line => line.trim() !== '')
+    .map(line => (/^\s*/.exec(line) as RegExpExecArray)[0].length)
+  const shared = indents.length === 0 ? 0 : Math.min(...indents)
+  return [lines[0] ?? '', ...lines.slice(1).map(line => line.slice(shared))].join('\n').trimEnd()
+}
+
+/** Collapse a type text to one line so catalog rows stay one row. */
+function collapse(text: string): string {
+  return text.replace(/\s+/g, ' ').trim()
+}
+
+/** A type-literal member's string-literal type text, '' when absent or computed. */
+function literalMember(entry: ts.TypeLiteralNode | undefined, name: string): string {
+  const member = namedMember(entry, name)
+  if (member?.type === undefined) return ''
+  return ts.isLiteralTypeNode(member.type) && ts.isStringLiteral(member.type.literal)
+    ? member.type.literal.text
+    : ''
+}
+
+/** A type-literal member's type text on one line, absent when the member is. */
+function memberTypeText(
+  entry: ts.TypeLiteralNode | undefined,
+  name: string,
+  sf: ts.SourceFile,
+): string | undefined {
+  const member = namedMember(entry, name)
+  return member?.type === undefined ? undefined : collapse(member.type.getText(sf))
+}
+
+/** One named property signature of a type literal. */
+function namedMember(entry: ts.TypeLiteralNode | undefined, name: string): ts.PropertySignature | undefined {
+  if (entry === undefined) return undefined
+  for (const member of entry.members) {
+    if (ts.isPropertySignature(member) && memberName(member.name) === name) return member
+  }
+  return undefined
+}
+
+/** A property name's text, quotes removed. */
+function memberName(name: ts.PropertyName): string {
+  return ts.isStringLiteral(name) || ts.isIdentifier(name) ? name.text : name.getText()
+}
+
+/** One string-literal property of an options object literal. */
+function stringProperty(options: ts.ObjectLiteralExpression, name: string): string | undefined {
+  for (const property of options.properties) {
+    if (!ts.isPropertyAssignment(property)) continue
+    if (memberName(property.name) !== name) continue
+    if (ts.isStringLiteral(property.initializer)) return property.initializer.text
+  }
+  return undefined
+}
+
+/** The SlotMap keys a registration's `children` table declares. */
+function childKeys(options: ts.ObjectLiteralExpression): string[] {
+  for (const property of options.properties) {
+    if (!ts.isPropertyAssignment(property)) continue
+    if (memberName(property.name) !== 'children') continue
+    if (!ts.isObjectLiteralExpression(property.initializer)) return []
+    return property.initializer.properties
+      .flatMap(child => (child.name === undefined ? [] : [memberName(child.name)]))
+  }
+  return []
+}
+
+/** The component argument as written; a non-identifier expression is collapsed. */
+function componentText(argument: ts.Expression | undefined, sf: ts.SourceFile): string {
+  if (argument === undefined) return '(none)'
+  const text = collapse(argument.getText(sf))
+  return text.length > 60 ? `${text.slice(0, 57)}…` : text
+}

scripts/snapshot-workspace-parent.spec.ts

@@ -0,0 +1,78 @@
+import { existsSync } from 'node:fs'
+import { chmod, mkdir, mkdtemp, readFile, rm, stat, symlink } from 'node:fs/promises'
+import { homedir, tmpdir } from 'node:os'
+import { dirname, join, parse } from 'node:path'
+import { Context } from '@deepseek-ai/cordis'
+import { SandboxedFileSystem } from '@deepseek-ai/dsh-fs-sandbox'
+import { canonicalPath } from '@deepseek-ai/dsh-sandbox'
+import SandboxPolicyService from '@deepseek-ai/dsh-sandbox-policy'
+import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
+import { describe, expect, it } from 'vitest'
+import { assertWorkspaceOutsideTemp, outsideTempWorkspaceParent } from './snapshot-workspace-parent.ts'
+
+// Host disk exhaustion is not simulated: placement and the real write fence are the regression oracles.
+describe('snapshot workspace parent', () => {
+  // Windows directory permissions and root bypass do not enforce POSIX write bits.
+  it.skipIf(process.platform === 'win32' || process.getuid?.() === 0)('uses home when the temp parent is not writable', async () => {
+    const base = await mkdtemp(join(outsideTempWorkspaceParent(), '.dsh-snapshot-readonly-'))
+    try {
+      const temporary = join(base, '_temp')
+      await mkdir(temporary)
+      await chmod(base, 0o500)
+      expect(outsideTempWorkspaceParent(temporary)).toBe(homedir())
+    } finally {
+      await chmod(base, 0o700)
+      await rm(base, { recursive: true, force: true })
+    }
+  })
+
+  it('uses home when a temp sibling would require a system directory or inherit its grant', () => {
+    expect(outsideTempWorkspaceParent('/tmp')).toBe(homedir())
+    expect(outsideTempWorkspaceParent(parse(tmpdir()).root)).toBe(homedir())
+    expect(outsideTempWorkspaceParent(join(canonicalPath('/tmp'), 'runner', '_temp'))).toBe(homedir())
+  })
+
+  it('rejects automatically writable temporary workspaces, including symlink aliases', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-snapshot-parent-'))
+    try {
+      expect(() => { assertWorkspaceOutsideTemp(root) }).toThrow('must be outside temporary writable root')
+      const alias = join(root, 'alias')
+      await symlink(tmpdir(), alias, process.platform === 'win32' ? 'junction' : 'dir')
+      expect(() => { assertWorkspaceOutsideTemp(alias) }).toThrow('must be outside temporary writable root')
+    } finally {
+      await rm(root, { recursive: true, force: true })
+    }
+  })
+
+  it('allows the allocated workspace but denies sibling writes and cleans the complete tree', async () => {
+    const base = await mkdtemp(join(outsideTempWorkspaceParent(), 'dsh-snapshot-parent-'))
+    const ctx = new Context()
+    const fibers: Awaited<ReturnType<Context['plugin']>>[] = []
+    try {
+      const temporary = join(base, '_temp')
+      await mkdir(temporary)
+      expect(outsideTempWorkspaceParent(temporary)).toBe(canonicalPath(base))
+      const workspace = await mkdtemp(join(outsideTempWorkspaceParent(temporary), 'workspace-'))
+      const outside = join(base, 'outside.txt')
+      assertWorkspaceOutsideTemp(workspace)
+      expect(dirname(workspace)).toBe(canonicalPath(base))
+      expect((await stat(workspace)).dev).toBe((await stat(temporary)).dev)
+      fibers.push(await ctx.plugin(SessionProjectionRegistry))
+      fibers.push(await ctx.plugin(SandboxPolicyService, { mode: 'workspace-write', workspaceRoot: workspace }))
+      fibers.push(await ctx.plugin(SandboxedFileSystem, { cwd: workspace }))
+      const inside = join(workspace, 'inside.txt')
+      await ctx.fs.writeText(await ctx.fs.resolve(inside), 'inside')
+      expect(await readFile(inside, 'utf8')).toBe('inside')
+      await expect(ctx.fs.writeText(await ctx.fs.resolve(outside), 'outside'))
+        .rejects.toMatchObject({ code: 'FS_SANDBOX_DENIED' })
+      expect(existsSync(outside)).toBe(false)
+    } finally {
+      try {
+        for (const fiber of fibers.reverse()) await fiber.dispose()
+      } finally {
+        await rm(base, { recursive: true, force: true })
+      }
+    }
+    expect(existsSync(base)).toBe(false)
+  })
+})

scripts/test-fixture-cleanup.ts

@@ -0,0 +1,49 @@
+/**
+ * Junction-safe fixture cleanup for Windows. Test fixtures junction the REAL
+ * `scripts/`, `node_modules`, and tsx package directories so installer probes
+ * resolve through them; Windows recursive deletion — both Node's `rmSync` and
+ * Git's `worktree remove` — follows MOUNT_POINT junctions into their targets
+ * and would delete the repository's own directories. POSIX `unlink`/`rm`
+ * already remove symlinks without following them, so the walk is a no-op
+ * there.
+ */
+
+import { lstatSync, readdirSync, rmSync, unlinkSync } from 'node:fs'
+import { join } from 'node:path'
+
+/**
+ * Recursively unlink every symbolic link (junction) under `path`.
+ * @param path - the fixture tree whose reparse points are unlinked.
+ */
+export function unlinkFixtureLinks(path: string): void {
+  const visit = (entry: string): void => {
+    let stat: ReturnType<typeof lstatSync>
+    try {
+      stat = lstatSync(entry)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return
+      throw error
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+      if (stat.isSymbolicLink()) unlinkSync(entry)
+      return
+    }
+    for (const child of readdirSync(entry)) visit(join(entry, child))
+  }
+  visit(path)
+}
+
+/**
+ * Remove one fixture tree after its junctions are unlinked (see
+ * {@link unlinkFixtureLinks}). Retries the removal: Windows releases child
+ * process and antivirus file handles asynchronously, and an unretried
+ * `rmSync` fails immediately with EPERM under load. A 10-second retry window
+ * (50 attempts × 200 ms) covers the failover pool's slow handle release;
+ * release is one-shot (a terminated child's handles drain, not reacquired),
+ * so a bounded window suffices and never pins afterEach cleanup.
+ * @param path - the fixture tree to remove.
+ */
+export function removeFixtureSafely(path: string): void {
+  unlinkFixtureLinks(path)
+  rmSync(path, { recursive: true, force: true, maxRetries: 50, retryDelay: 200 })
+}

scripts/test-proxy-environment.spec.ts

@@ -0,0 +1,44 @@
+import { readFileSync } from 'node:fs'
+import { describe, expect, it } from 'vitest'
+import { PROXY_ENV_NAMES } from '../packages/util/http-proxy/src/policy.ts'
+import { clearAmbientProxyEnv, TEST_PROXY_SETUP_FILE, vitestConfigFiles } from './test-proxy-environment.ts'
+
+describe('ambient proxy environment', () => {
+  it('clears every name the policy resolver reads, in both casings', () => {
+    const env: NodeJS.ProcessEnv = {
+      HTTP_PROXY: 'http://p:1', http_proxy: 'http://p:1',
+      HTTPS_PROXY: 'http://p:1', https_proxy: 'http://p:1',
+      ALL_PROXY: 'http://p:1', all_proxy: 'http://p:1',
+      NO_PROXY: 'example.com', no_proxy: 'example.com',
+      NODE_USE_ENV_PROXY: '1',
+      PATH: '/usr/bin',
+    }
+    expect(clearAmbientProxyEnv(env)).toHaveLength(PROXY_ENV_NAMES.length + 1)
+    expect(env).toEqual({ PATH: '/usr/bin' })
+  })
+
+  it('reports only the names that were set, and touches nothing else', () => {
+    const env: NodeJS.ProcessEnv = { all_proxy: 'http://p:1', HOME: '/home/me' }
+    expect(clearAmbientProxyEnv(env)).toEqual(['all_proxy'])
+    expect(env).toEqual({ HOME: '/home/me' })
+  })
+
+  // A runtime assertion that this process is clear would pass either way: importing the module
+  // above already ran it. What can actually regress is the wiring — a new Vitest project, or a
+  // config that lists only the invariant host — so that is what this pins.
+  const declared = vitestConfigFiles()
+    .map(config => ({ config, slots: readFileSync(config, 'utf8').match(/setupFiles: \[[^\]]*\]/g) ?? [] }))
+    .filter(entry => entry.slots.length > 0)
+
+  it('finds the configurations that declare a setup at all', () => {
+    // Guards the discovery itself: a glob that stopped matching would make every case below vacuous.
+    expect(declared.map(entry => entry.config)).toEqual([
+      'vitest.bench.config.ts', 'vitest.config.ts', 'vitest.e2e.config.ts', 'vitest.expected.config.ts',
+      'vitest.snapshot.config.ts',
+    ])
+  })
+
+  it.each(declared)('$config runs the setup in every setupFiles it declares', ({ slots }) => {
+    for (const slot of slots) expect(slot).toContain(TEST_PROXY_SETUP_FILE)
+  })
+})