Merge master into feat/xdg-single-root-home

2026-08-15 21:04:50 +00:00 · 2026-07-21 21:20:43 +08:00
parent e97290ba9e 717fa47535
commit af1e40e7c6
635 changed files with 21507 additions and 3326 deletions
--- a/scripts/check-workspace-constraints.ts
+++ b/scripts/check-workspace-constraints.ts
@@ -93,29 +93,6 @@ function workspaceManifests(): WorkspaceManifest[] {
  return manifests
 }

-const dshPackageFiles = [
-  'lib/index.js',
-  'lib/types/**/*.d.ts',
-  'lib/types/**/*.d.ts.map',
-  'src',
-] as const
-
-const dshBinPackageFiles = [
-  'lib/index.js',
-  'lib/bin.js',
-  'lib/types/**/*.d.ts',
-  'lib/types/**/*.d.ts.map',
-  'src',
-] as const
-
-const dshWorkerPackageFiles = [
-  'lib/index.js',
-  'lib/worker.cjs',
-  'lib/types/**/*.d.ts',
-  'lib/types/**/*.d.ts.map',
-  'src',
-] as const
-
 const packageFileExtras: Readonly<Record<string, readonly string[]>> = {
  '@deepseek-ai/dsh-helper': ['lib/assets'],
  '@deepseek-ai/dsh-scripts': [
@@ -131,22 +108,18 @@ function sameStringList(actual: readonly string[] | undefined, expected: readonl

 function expectedDshPackageFiles(manifest: PackageManifest): readonly string[] {
  const extras = manifest.name ? packageFileExtras[manifest.name] ?? [] : []
-  if (extras.length > 0) {
-    return [
-      'lib/index.js',
-      ...manifest.bin ? ['lib/bin.js'] : [],
-      ...extras,
-      'lib/types/**/*.d.ts',
-      'lib/types/**/*.d.ts.map',
-      'src',
-    ]
-  }
-  if (manifest.bin) return dshBinPackageFiles
-  // A declared "./worker" subpath export sanctions the one extra runtime
-  // bundle a worker-thread entry needs (and NodeNext/publint then validate
-  // that subpath's targets like any other export).
-  if (manifest.exports?.['./worker']) return dshWorkerPackageFiles
-  return dshPackageFiles
+  return [
+    'lib/index.js',
+    // Every package publishes its invariant ownership companion as a separate
+    // bundle; the package-invariant gate validates the companion itself.
+    'lib/invariant.js',
+    ...manifest.bin ? ['lib/bin.js'] : [],
+    ...manifest.exports?.['./worker'] ? ['lib/worker.cjs'] : [],
+    ...extras,
+    'lib/types/**/*.d.ts',
+    'lib/types/**/*.d.ts.map',
+    'src',
+  ]
 }

 function checkWorkspace({ dir, manifest }: WorkspaceManifest): string[] {
@@ -188,6 +161,16 @@ function checkWorkspace({ dir, manifest }: WorkspaceManifest): string[] {
    if (manifest.exports?.['.']?.default !== './lib/index.js') {
      errors.push(`${label}: package.json exports["."].default must be "./lib/index.js"`)
    }
+    const invariantExport = manifest.exports?.['./invariant']
+    if (invariantExport?.types !== undefined && invariantExport.types !== './lib/types/invariant.d.ts') {
+      errors.push(`${label}: package.json exports["./invariant"].types must be "./lib/types/invariant.d.ts"`)
+    }
+    if (invariantExport?.default !== undefined && invariantExport.default !== './lib/invariant.js') {
+      errors.push(`${label}: package.json exports["./invariant"].default must be "./lib/invariant.js"`)
+    }
+    if (invariantExport && (invariantExport.types === undefined || invariantExport.default === undefined)) {
+      errors.push(`${label}: package.json exports["./invariant"] must declare both types and default targets`)
+    }
    const expectedFiles = expectedDshPackageFiles(manifest)
    if (!sameStringList(manifest.files, expectedFiles)) {
      errors.push(`${label}: package.json files must be ${JSON.stringify(expectedFiles)}`)
--- a/scripts/doc-typecheck-paths.spec.ts
+++ b/scripts/doc-typecheck-paths.spec.ts
@@ -0,0 +1,17 @@
+import { describe, expect, it } from 'vitest'
+import { builtDeclarationPath } from './doc-typecheck-paths.ts'
+
+describe('builtDeclarationPath', () => {
+  it('maps package source directories and exact entry files to built declarations', () => {
+    expect(builtDeclarationPath('./packages/*/*/src')).toBe('./packages/*/*/lib/types')
+    expect(builtDeclarationPath('./packages/support/invariants/src/index.ts'))
+      .toBe('./packages/support/invariants/lib/types/index.d.ts')
+    expect(builtDeclarationPath('./packages/core/session/src/invariant.ts'))
+      .toBe('./packages/core/session/lib/types/invariant.d.ts')
+  })
+
+  it('rejects aliases without a supported source target', () => {
+    expect(() => builtDeclarationPath('./packages/support/invariants/source/index.ts'))
+      .toThrow('cannot map workspace source path')
+  })
+})
--- a/scripts/doc-typecheck-paths.ts
+++ b/scripts/doc-typecheck-paths.ts
@@ -0,0 +1,11 @@
+/** Map one workspace source alias target to its declaration-build target. */
+export function builtDeclarationPath(candidate: string): string {
+  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`
+  }
+  throw new Error(`doc-typecheck: cannot map workspace source path to built declarations: ${candidate}`)
+}
--- a/scripts/doc-typecheck.ts
+++ b/scripts/doc-typecheck.ts
@@ -8,6 +8,7 @@ import { execFileSync } from 'node:child_process'
 import { globSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
 import { join, relative, resolve } from 'node:path'
 import ts from 'typescript'
+import { builtDeclarationPath } from './doc-typecheck-paths.ts'
 import { extractFences } from './md-fences.ts'

 const root = resolve(import.meta.dirname, '..')
@@ -65,12 +66,7 @@ function builtTypeCompilerOptions(): ts.CompilerOptions {
  if (parsed.options.paths === undefined) throw new Error('doc-typecheck: root tsconfig has no workspace paths')
  const paths = Object.fromEntries(Object.entries(parsed.options.paths).map(([specifier, candidates]) => [
    specifier,
-    candidates.map((candidate) => {
-      if (!candidate.endsWith('/src')) {
-        throw new Error(`doc-typecheck: cannot map workspace source path to built declarations: ${candidate}`)
-      }
-      return `${candidate.slice(0, -'/src'.length)}/lib/types`
-    }),
+    candidates.map(builtDeclarationPath),
  ]))
  const options: ts.CompilerOptions = {
    ...parsed.options,
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -35,6 +35,7 @@ export const LINK_MAP: Record<string, string> = {
  ContinuationStop: 'core.md',
  GenerateOptions: 'core.md',
  LlmCallConfig: 'core.md',
+  LlmModelContext: 'core.md',
  LlmFailure: 'llm-streaming.md',
  LlmModelInfo: 'core.md',
  LlmProviderInfo: 'core.md',
@@ -168,6 +169,8 @@ const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
  BashEnvVariableInfo: 'service-local metadata type is owned by packages/bash/tool-bash/src/index.ts',
  CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
  CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
+  InvariantInstaller: 'service-local contribution contract is owned by packages/support/invariants/README.md',
+  InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/README.md',
  PresetOption: 'deployment menu metadata is owned by packages/ui/permission/README.md',
  PresetSpec: 'deployment preset composition is owned by packages/ui/permission/README.md',
  PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -109,9 +109,17 @@ const SERVICE_ROLES: ServiceRole[] = [
    pkg: 'session',
    title: 'In-memory session store',
    mode: 'core',
-    consumers: ['agent-loop', 'agent', 'cli-demo', 'session-persistence', 'session-query', 'subagent-inprocess', 'invariants'],
+    consumers: ['agent-loop', 'agent', 'cli-demo', 'session-persistence', 'session-query', 'subagent-inprocess'],
    note: 'Owns append-only Session instances and emits the durable session event feed.',
  },
+  {
+    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: 'sessionPersistence',
    pkg: 'session-persistence',
@@ -175,7 +183,7 @@ const SERVICE_ROLES: ServiceRole[] = [
    pkg: 'agent',
    title: 'Agent service',
    mode: 'core',
-    consumers: ['agent-loop', 'acp', 'cli-demo', 'subagent-inprocess', 'tui-demo', 'invariants'],
+    consumers: ['agent-loop', 'acp', 'cli-demo', 'subagent-inprocess', 'tui-demo'],
    note: 'Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation.',
  },
  {
--- a/scripts/gen-scoped-events.ts
+++ b/scripts/gen-scoped-events.ts
@@ -1,6 +1,6 @@
 /**
- * Generate the dev-invariants scoped-event resolver map from the
- * repository TypeScript Program.
+ * 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
@@ -20,7 +20,7 @@ import { pointer, rawJsDoc } from './jsdoc.ts'
 import { TypeScriptProject } from './ts-project.ts'

 const root = resolve(import.meta.dirname, '..')
-const OUT = 'packages/support/invariants/src/scoped-events.generated.ts'
+const OUT = 'packages/core/scope/src/scoped-events.generated.ts'
 const SCOPE_DOC_MARKER = 'Scope-filtered dispatch'

 interface ScopeTargetContract {
@@ -39,7 +39,6 @@ interface SubjectCandidate {
 interface ScopedEventResolver {
  event: string
  candidate: SubjectCandidate | null
-  ownerPackage: string
 }

 interface ScopeTag {
@@ -54,7 +53,6 @@ class ScopedEventGenerator {
  private readonly scopeTargetDeclaration: ts.FunctionDeclaration
  private readonly scopedSymbol: ts.Symbol
  private readonly violations: string[] = []
-  private readonly packageNames = new Map<string, string>()

  constructor(private readonly project: TypeScriptProject) {
    this.checker = project.checker
@@ -81,44 +79,25 @@ class ScopedEventGenerator {
        + this.violations.map(violation => `  - ${violation}`).join('\n'),
      )
    }
-    const ownerImports = [...new Set(resolvers.map(resolver => resolver.ownerPackage))]
-      .sort()
-      .map(packageName => `import type {} from ${quote(packageName)}`)
    return [
      '/**',
-      ' * Generated scoped-event routing-subject resolvers for dsh-invariants.',
+      ' * 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-invariants/scoped-events.generated',
+      ' * @module @deepseek-ai/dsh-scope/scoped-events.generated',
      ' */',
      '',
-      "import type { Events } from 'cordis'",
-      "import type { Scoped } from '@deepseek-ai/dsh-scope'",
-      ...ownerImports,
-      '',
-      'type ScopedEventName = {',
-      '  [K in keyof Events]: ThisParameterType<Events[K]> extends Scoped<object> ? K : never',
-      '}[keyof Events]',
-      '',
      'type ScopedSubjectResolver = (args: readonly unknown[]) => unknown',
      '',
-      'function adapt<K extends ScopedEventName>(',
-      '  resolver: (args: Parameters<Events[K]>) => unknown,',
-      '): ScopedSubjectResolver {',
-      '  return args => resolver(args as Parameters<Events[K]>)',
-      '}',
-      '',
-      'const scopedSubjectResolvers = Object.freeze({',
+      '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}].${candidate.property}`
-        return `  '${event}': adapt<'${event}'>(args => ${subject}),`
+          : `(args[${candidate.parameter}] as Record<string, unknown>)[${quote(candidate.property)}]`
+        return `  '${event}': args => ${subject},`
      }),
-      '} as const satisfies Readonly<Record<ScopedEventName, ScopedSubjectResolver | null>>)',
-      '',
-      'const scopedSubjectResolverIndex: Readonly<Record<string, ScopedSubjectResolver | null>> = scopedSubjectResolvers',
+      '})',
      '',
      '/**',
      ' * Resolve the routing key named by one scoped event payload. A null',
@@ -129,7 +108,7 @@ class ScopedEventGenerator {
      ' *   or undefined when the event is not scope-filtered.',
      ' */',
      'export function scopedSubjectResolverFor(event: string): ScopedSubjectResolver | null | undefined {',
-      '  return scopedSubjectResolverIndex[event]',
+      '  return scopedSubjectResolvers[event]',
      '}',
      '',
    ].join('\n')
@@ -186,7 +165,6 @@ class ScopedEventGenerator {
    const resolvers: ScopedEventResolver[] = []
    for (const sourceFile of this.packageSources) {
      const rel = this.project.relativePath(sourceFile)
-      const ownerPackage = this.packageName(packageRootFor(rel))
      const visit = (node: ts.Node): void => {
        if (ts.isInterfaceDeclaration(node) && node.name.text === 'Events' && isCordisModuleInterface(node)) {
          for (const member of node.members) {
@@ -232,7 +210,7 @@ class ScopedEventGenerator {
                  + 'add @dshScopeScan unsupported only when the key is intentionally absent from the payload',
                )
              }
-              resolvers.push({ event, candidate: null, ownerPackage })
+              resolvers.push({ event, candidate: null })
              continue
            }
            if (tag.unsupported) {
@@ -241,7 +219,7 @@ class ScopedEventGenerator {
              )
              continue
            }
-            resolvers.push({ event, candidate: candidates[0] ?? null, ownerPackage })
+            resolvers.push({ event, candidate: candidates[0] ?? null })
          }
        }
        ts.forEachChild(node, visit)
@@ -311,19 +289,6 @@ class ScopedEventGenerator {
    return dedupeCandidates(candidates)
  }

-  /** Read and cache one workspace package name. */
-  private packageName(packageRoot: string): string {
-    const cached = this.packageNames.get(packageRoot)
-    if (cached) return cached
-    const manifest: unknown = JSON.parse(readFileSync(resolve(root, packageRoot, 'package.json'), 'utf8'))
-    const name: unknown = typeof manifest === 'object' && manifest !== null
-      ? Reflect.get(manifest, 'name')
-      : undefined
-    if (typeof name !== 'string') throw new Error(`gen-scoped-events: ${packageRoot}/package.json has no name`)
-    this.packageNames.set(packageRoot, name)
-    return name
-  }
-
  /** Compare exact Program type identities after removing null and undefined. */
  private typesEquivalent(left: ts.Type, right: ts.Type): boolean {
    const normalizedLeft = this.normalizedType(left)
@@ -398,13 +363,6 @@ function dedupeCandidates(candidates: readonly SubjectCandidate[]): SubjectCandi
  })
 }

-/** Return the workspace package root owning one package source file. */
-function packageRootFor(relativePath: string): string {
-  const match = /^(packages\/[^/]+\/[^/]+)\/src\//.exec(relativePath)
-  if (!match?.[1]) throw new Error(`gen-scoped-events: cannot derive package root from ${relativePath}`)
-  return match[1]
-}
-
 /** Quote a generated property key as a single-quoted TypeScript string. */
 function quote(value: string): string {
  return `'${value.replaceAll('\\', '\\\\').replaceAll("'", "\\'")}'`
@@ -419,7 +377,7 @@ export function renderScopedEvents(projectRoot: string = root): string {
  return new ScopedEventGenerator(new TypeScriptProject(projectRoot)).render()
 }

-/** Generate or freshness-check the fixed invariants source file. */
+/** Generate or freshness-check the fixed dsh-scope source file. */
 function main(): void {
  const content = renderScopedEvents()
  const output = resolve(root, OUT)
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -33,6 +33,8 @@ import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
 import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
 import * as ToolFsSearch from '@deepseek-ai/dsh-tool-fs-search'
 import * as ToolGoal from '@deepseek-ai/dsh-tool-goal'
+import Lsp from '@deepseek-ai/dsh-lsp'
+import * as ToolLsp from '@deepseek-ai/dsh-tool-lsp'
 import * as ToolSkill from '@deepseek-ai/dsh-tool-skill'
 import * as ToolTasks from '@deepseek-ai/dsh-tool-tasks'
 import * as ToolTodo from '@deepseek-ai/dsh-tool-todo'
@@ -242,6 +244,20 @@ const TOOL_PACKAGES: ToolPackage[] = [
    note:
      'create, edit, pause, and resume require direct-human root authority; complete and blocked also accept the exact current goal round. The default blocked lower bound is three admitted rounds.',
  },
+  {
+    pkg: '@deepseek-ai/dsh-tool-lsp',
+    dir: 'tool-lsp',
+    source: 'packages/lsp/tool-lsp/src/index.ts',
+    requires: ['ctx.tools', 'ctx.lsp', 'ctx.systemPrompt'],
+    writes: ['tool/call', 'tool/result'],
+    async mount(ctx) {
+      // The tool registers from the seam alone; the schema does not depend on any provider.
+      await ctx.plugin(Lsp)
+      await ctx.plugin(ToolLsp)
+    },
+    note:
+      'The lsp tool keeps provider selection and language-server subprocesses behind ctx.lsp, so its model-visible schema stays stable across providers. Requires a registered provider (e.g. `@deepseek-ai/dsh-lsp-local`) at runtime; without one, a query returns the structured `LSP_UNAVAILABLE` error rather than changing the schema.',
+  },
  {
    pkg: '@deepseek-ai/dsh-tool-ralph',
    dir: 'tool-ralph',
--- a/scripts/package-invariants.spec.ts
+++ b/scripts/package-invariants.spec.ts
@@ -0,0 +1,187 @@
+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 {
+  collectPackageInvariantViolations,
+} from './package-invariants.ts'
+
+const roots: string[] = []
+
+afterEach(() => {
+  for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+function handwrittenInvariant(packageName: string): string {
+  return `
+export const name = 'probe-invariant'
+export const inject = ['invariants']
+const install = (ctx: { on(name: string, listener: (value: number) => void): void }, fail: (message: string) => never) => {
+  ctx.on('probe/value', (value) => {
+    if (value < 0) fail('observed values must be non-negative')
+  })
+}
+export const apply = (ctx: { invariants: { register(name: string, install: typeof install): () => void } }) =>
+  Promise.resolve(ctx.invariants.register(${JSON.stringify(packageName)}, install))
+`
+}
+
+function fixture(options: {
+  packageName?: string
+  source?: string
+  invariantExport?: boolean
+  invariantDependency?: boolean
+  invariantReference?: boolean
+  buildEntry?: boolean
+} = {}): string {
+  const root = mkdtempSync(join(tmpdir(), 'dsh-package-invariants-'))
+  roots.push(root)
+  const dir = join(root, 'packages/core/probe')
+  mkdirSync(join(dir, 'src'), { recursive: true })
+  const packageName = options.packageName ?? '@deepseek-ai/dsh-probe'
+  const manifest = {
+    name: packageName,
+    exports: options.invariantExport === false ? {} : {
+      './invariant': {
+        types: './lib/types/invariant.d.ts',
+        default: './lib/invariant.js',
+      },
+    },
+    files: ['lib/index.js', 'lib/invariant.js', 'src'],
+    peerDependencies: options.invariantDependency === false ? {} : {
+      '@deepseek-ai/dsh-invariants': '^0.0.1',
+    },
+    devDependencies: options.invariantDependency === false ? {} : {
+      '@deepseek-ai/dsh-invariants': 'workspace:^',
+    },
+  }
+  writeFileSync(join(dir, 'package.json'), `${JSON.stringify(manifest, null, 2)}\n`)
+  writeFileSync(join(dir, 'tsconfig.json'), `${JSON.stringify({
+    references: options.invariantReference === false ? [] : [{ path: '../../support/invariants' }],
+  }, null, 2)}\n`)
+  writeFileSync(join(dir, 'src/invariant.ts'), options.source ?? handwrittenInvariant(packageName))
+  writeFileSync(
+    join(dir, 'tsdown.config.ts'),
+    options.buildEntry === false ? "export default { entry: ['lib/types/index.js'] }\n" : "export default { entry: ['lib/types/index.js', 'lib/types/invariant.js'] }\n",
+  )
+  return root
+}
+
+describe('package invariant gate', () => {
+  it('accepts a hand-owned checking companion with publication metadata', () => {
+    expect(collectPackageInvariantViolations(fixture())).toEqual([])
+  })
+
+  it('rejects missing publication metadata and build output', () => {
+    const violations = collectPackageInvariantViolations(fixture({
+      invariantExport: false,
+      invariantDependency: false,
+      invariantReference: false,
+      buildEntry: false,
+    }))
+    expect(violations.map(violation => violation.message)).toEqual(expect.arrayContaining([
+      expect.stringContaining('exports["./invariant"]'),
+      expect.stringContaining('peerDependency'),
+      expect.stringContaining('devDependency'),
+      expect.stringContaining('TypeScript project references'),
+      expect.stringContaining('must bundle lib/types/invariant.js'),
+    ]))
+  })
+
+  it('rejects foreign, duplicate, and unresolved registrations', () => {
+    const source = `
+export const name = 'probe-invariant'
+export const inject = ['invariants']
+const selected = process.env.PACKAGE_NAME
+const install = (_ctx: unknown, fail: (message: string) => never) => { fail('probe') }
+export const apply = (ctx: { invariants: { register(name: string, install: typeof install): () => void } }) => {
+  ctx.invariants.register('@deepseek-ai/dsh-foreign', install)
+  return ctx.invariants.register(selected!, install)
+}
+`
+    const violations = collectPackageInvariantViolations(fixture({ source }))
+    expect(violations.map(violation => violation.message)).toEqual(expect.arrayContaining([
+      expect.stringContaining('must resolve to a local string constant'),
+      expect.stringContaining('must register exactly its own package name'),
+    ]))
+  })
+
+  it('rejects generated markers and reporter-free executable installers', () => {
+    const generated = fixture({
+      source: `/** @generated */\n${handwrittenInvariant('@deepseek-ai/dsh-probe')}`,
+    })
+    expect(collectPackageInvariantViolations(generated).map(violation => violation.message))
+      .toContain('invariant companions must be hand-owned and may not carry @generated markers')
+
+    const reporterFree = fixture({
+      source: `
+export const name = 'probe-invariant'
+export const inject = ['invariants']
+const install = () => { void 0 }
+export const apply = (ctx: { invariants: { register(name: string, install: typeof install): () => void } }) =>
+  Promise.resolve(ctx.invariants.register('@deepseek-ai/dsh-probe', install))
+`,
+    })
+    expect(collectPackageInvariantViolations(reporterFree).map(violation => violation.message))
+      .toContain('install function must accept the bound failure reporter as its second parameter')
+
+    const unused = fixture({
+      source: `
+export const name = 'probe-invariant'
+export const inject = ['invariants']
+const install = (_ctx: unknown, _fail: (message: string) => never) => { void 0 }
+export const apply = (ctx: { invariants: { register(name: string, install: typeof install): () => void } }) =>
+  Promise.resolve(ctx.invariants.register('@deepseek-ai/dsh-probe', install))
+`,
+    })
+    expect(collectPackageInvariantViolations(unused).map(violation => violation.message))
+      .toContain('install function must use its bound failure reporter')
+  })
+
+  it('rejects registering a different installer than the checked local function', () => {
+    const decoy = fixture({
+      source: `
+export const name = 'probe-invariant'
+export const inject = ['invariants']
+const install = (_ctx: unknown, fail: (message: string) => never) => { fail('checked decoy') }
+export const apply = (ctx: { invariants: { register(name: string, install: () => void): () => void } }) =>
+  ctx.invariants.register('@deepseek-ai/dsh-probe', () => {})
+`,
+    })
+    expect(collectPackageInvariantViolations(decoy).map(violation => violation.message))
+      .toContain('line 6: ctx.invariants.register must use the checked local install function')
+  })
+
+  it.each([
+    'export default { name, inject, apply }',
+    "export * as default from './probe.ts'",
+  ])('rejects a default export that would collapse the Loader namespace', (defaultExport) => {
+    const source = `${handwrittenInvariant('@deepseek-ai/dsh-probe')}\n${defaultExport}\n`
+    expect(collectPackageInvariantViolations(fixture({ source })).map(violation => violation.message))
+      .toContain('must not default-export; Loader must retain the companion namespace')
+  })
+
+  it('accepts explained empty installers and rejects unexplained ones', () => {
+    const explained = `
+export const name = 'probe-invariant'
+export const inject = ['invariants']
+const PACKAGE_NAME = '@deepseek-ai/dsh-probe'
+/** No runtime invariant: this pure package owns no events or mutable data. */
+const install = () => {}
+export const apply = (ctx: { invariants: { register(name: string, install: () => void): () => void } }) =>
+  ctx.invariants.register(PACKAGE_NAME, install)
+`
+    expect(collectPackageInvariantViolations(fixture({ source: explained }))).toEqual([])
+
+    const unexplained = `
+export const name = 'probe-invariant'
+export const inject = ['invariants']
+const PACKAGE_NAME = '@deepseek-ai/dsh-probe'
+const install = () => {}
+export const apply = (ctx: { invariants: { register(name: string, install: () => void): () => void } }) =>
+  ctx.invariants.register(PACKAGE_NAME, install)
+`
+    expect(collectPackageInvariantViolations(fixture({ source: unexplained })).map(violation => violation.message))
+      .toContain('empty install function must explain why with a "No runtime invariant:" comment')
+  })
+})
--- a/scripts/package-invariants.ts
+++ b/scripts/package-invariants.ts
@@ -0,0 +1,340 @@
+/**
+ * Package-invariant companion discovery and structural checks.
+ * The runtime registry stays product-independent; this gate makes ownership
+ * exhaustive across packages without centralizing package checks.
+ */
+
+import { existsSync, globSync, readFileSync } from 'node:fs'
+import { dirname, relative, resolve, sep } from 'node:path'
+import ts from 'typescript'
+
+/** Required explanation marker for an intentionally empty installer. */
+const NO_RUNTIME_INVARIANT_MARKER = 'No runtime invariant:'
+
+interface PackageManifest {
+  name?: string
+  exports?: Record<string, { types?: string; default?: string } | string | undefined>
+  files?: string[]
+  peerDependencies?: Record<string, string>
+  devDependencies?: Record<string, string>
+}
+
+/** One package and the files participating in its invariant publication contract. */
+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 every package under the repository package tree. */
+export function packageInvariantOwners(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 contract. */
+export function collectPackageInvariantViolations(root: string): PackageInvariantViolation[] {
+  const violations: PackageInvariantViolation[] = []
+  for (const owner of packageInvariantOwners(root)) {
+    const manifest = readManifest(resolve(root, owner.manifestPath))
+    checkManifest(owner, manifest, violations)
+    checkBuild(owner, root, violations)
+    checkSource(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,
+  violations: PackageInvariantViolation[],
+): void {
+  const invariantExport = manifest.exports?.['./invariant']
+  if (typeof invariantExport !== 'object'
+    || 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
+  if (manifest.peerDependencies?.['@deepseek-ai/dsh-invariants'] !== '^0.0.1') {
+    addViolation(
+      violations,
+      owner.manifestPath,
+      '@deepseek-ai/dsh-invariants must be a ^0.0.1 peerDependency',
+    )
+  }
+  if (manifest.devDependencies?.['@deepseek-ai/dsh-invariants'] !== 'workspace:^') {
+    addViolation(
+      violations,
+      owner.manifestPath,
+      '@deepseek-ai/dsh-invariants must also be a workspace:^ devDependency',
+    )
+  }
+}
+
+function checkBuild(
+  owner: PackageInvariantOwner,
+  root: string,
+  violations: PackageInvariantViolation[],
+): void {
+  const tsconfigPath = `${owner.dir}/tsconfig.json`
+  const tsconfig = JSON.parse(readFileSync(resolve(root, tsconfigPath), 'utf8')) as {
+    references?: Array<{ path?: string }>
+  }
+  if (owner.packageName !== '@deepseek-ai/dsh-invariants'
+    && !tsconfig.references?.some(reference => reference.path === '../../support/invariants')) {
+    addViolation(
+      violations,
+      tsconfigPath,
+      'TypeScript project references must include ../../support/invariants',
+    )
+  }
+
+  const configPath = `${owner.dir}/tsdown.config.ts`
+  if (!existsSync(resolve(root, configPath))) return
+  const source = readFileSync(resolve(root, configPath), 'utf8')
+  if (!source.includes('lib/types/invariant.js')) {
+    addViolation(violations, configPath, 'package build override must bundle lib/types/invariant.js')
+  }
+}
+
+function checkSource(
+  owner: PackageInvariantOwner,
+  root: string,
+  violations: PackageInvariantViolation[],
+): void {
+  const absolutePath = resolve(root, owner.sourcePath)
+  if (!existsSync(absolutePath)) {
+    addViolation(violations, owner.sourcePath, 'missing package-owned invariant companion')
+    return
+  }
+  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, sourceText, violations)
+}
+
+function checkInstaller(
+  owner: PackageInvariantOwner,
+  sourceFile: ts.SourceFile,
+  sourceText: string,
+  violations: PackageInvariantViolation[],
+): void {
+  let initializer: ts.Expression | undefined
+  let declarationStatement: ts.VariableStatement | 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
+        declarationStatement = statement
+      }
+    }
+  }
+  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) {
+    const declarationText = declarationStatement === undefined
+      ? ''
+      : sourceText.slice(declarationStatement.getFullStart(), declarationStatement.getEnd())
+    if (!declarationText.includes(NO_RUNTIME_INVARIANT_MARKER)) {
+      addViolation(
+        violations,
+        owner.sourcePath,
+        `empty install function must explain why with a "${NO_RUNTIME_INVARIANT_MARKER}" comment`,
+      )
+    }
+    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}`
+}
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -18,6 +18,7 @@ type Mode =
  | 'ci-artifacts'
  | 'node-compat'
  | 'pre-push'
+  | 'doc-sync'
 type GateStatus = 'pending' | 'running' | 'passed' | 'failed' | 'skipped'

 interface Gate {
@@ -87,21 +88,25 @@ function parseMode(raw: string | undefined): Mode {
    case 'ci-artifacts':
    case 'node-compat':
    case 'pre-push':
+    case 'doc-sync':
      return raw
    default:
      throw new Error(
-        `run-gates: expected mode ci-primary | ci-static | ci-lint | ci-coverage | ci-snapshot | ci-artifacts | node-compat | pre-push, got ${JSON.stringify(raw)}.`,
+        `run-gates: expected mode ci-primary | ci-static | ci-lint | ci-coverage | ci-snapshot | ci-artifacts | node-compat | pre-push | doc-sync, got ${JSON.stringify(raw)}.`,
      )
  }
 }

 function defaultConcurrency(selectedMode: Mode, total: number): ConcurrencyDefault {
  const available = availableParallelism()
-  const modeLimit = selectedMode === 'pre-push' ? Math.min(4, available) : available
+  // Local modes cap workers: several doc gates each build a full ts.Program,
+  // so an uncapped default on a large host trades wall clock for memory blowups.
+  const localCap = selectedMode === 'pre-push' || selectedMode === 'doc-sync'
+  const modeLimit = localCap ? Math.min(4, available) : available
  return {
    workers: Math.min(total, modeLimit),
-    source: selectedMode === 'pre-push'
-      ? `${available} available CPU(s), pre-push cap 4`
+    source: localCap
+      ? `${available} available CPU(s), ${selectedMode} cap 4`
      : `${available} available CPU(s)`,
  }
 }
@@ -201,6 +206,8 @@ function gatesForMode(selected: Mode): Gate[] {
        }),
        pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }),
      ]
+    case 'doc-sync':
+      return docSyncLeafGates()
  }
 }

@@ -208,6 +215,7 @@ function ciPrimaryGates(): Gate[] {
  return [
    pnpmScript('runtime-closure', 'verify-runtime-closure', { label: 'runtime closure' }),
    pnpmScript('constraints', 'constraints'),
+    pnpmScript('package-invariants', 'verify-package-invariants', { label: 'package invariants' }),
    pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }),
    pnpmScript('typecheck', 'typecheck'),
    lintGate(),
@@ -223,6 +231,7 @@ function ciPrimaryGates(): Gate[] {
      label: 'node-next types',
      needs: ['build'],
    }),
+    builtPackageInvariantsGate(['build']),
    builtBinSmokeGate(),
  ]
 }
@@ -231,6 +240,7 @@ function ciStaticGates(): Gate[] {
  return [
    pnpmScript('runtime-closure', 'verify-runtime-closure', { label: 'runtime closure' }),
    pnpmScript('constraints', 'constraints'),
+    pnpmScript('package-invariants', 'verify-package-invariants', { label: 'package invariants' }),
    pnpmScript('cordis-config', 'verify-cordis-config', { label: 'Cordis config' }),
    ...docSyncLeafGates(),
    pnpmScript('module-graph', 'verify-module-graph', { label: 'module graph' }),
@@ -246,6 +256,7 @@ function ciArtifactGates(): Gate[] {
      label: 'node-next types',
      needs: ['build'],
    }),
+    builtPackageInvariantsGate(['build']),
    builtBinSmokeGate(),
  ]
 }
@@ -293,6 +304,13 @@ function snapshotGate(): Gate {
  })
 }

+function builtPackageInvariantsGate(needs?: string[]): Gate {
+  return pnpmScript('built-package-invariants', 'verify-built-package-invariants', {
+    label: 'built package invariants',
+    ...needs === undefined ? {} : { needs },
+  })
+}
+
 function positiveIntArg(envName: string, flag: string): string[] {
  const raw = process.env[envName]
  if (raw === undefined || raw === '') return []
@@ -309,6 +327,8 @@ function hygieneLeafGates(options: { artifactNeeds?: string[] } = {}): Gate[] {
    pnpmScript('knip', 'knip'),
    pnpmScript('publint', 'publint', artifactOptions),
    pnpmScript('constraints', 'constraints'),
+    pnpmScript('package-invariants', 'verify-package-invariants', { label: 'package invariants' }),
+    builtPackageInvariantsGate(options.artifactNeeds),
    pnpmScript('node-next-types', 'verify-node-next-types', {
      label: 'node-next types',
      ...artifactOptions,
@@ -326,6 +346,7 @@ function docSyncLeafGates(options: {
  return [
    pnpmScript('doc-typecheck', 'doc-typecheck', docTypecheckOptions),
    pnpmScript('cordis-catalog', 'verify-cordis-catalog', { label: 'cordis catalog' }),
+    pnpmScript('cordis-api', 'verify-cordis-api', { label: 'cordis api' }),
    pnpmScript('export-jsdoc', 'verify-export-jsdoc', { label: 'export jsdoc' }),
    pnpmScript('tool-catalog', 'verify-tool-catalog', { label: 'tool catalog' }),
    pnpmScript('config-catalog', 'verify-config-catalog', { label: 'config catalog' }),
--- a/scripts/test-invariants.spec.ts
+++ b/scripts/test-invariants.spec.ts
@@ -0,0 +1,87 @@
+import { describe, expect, it, vi } from 'vitest'
+import { Context, Service } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+import { packageInvariantOwners } from './package-invariants.ts'
+import {
+  testInvariantCompanionPaths,
+  testInvariantCompanions,
+  usesManualInvariantTree,
+} from './test-invariants.ts'
+
+declare module 'cordis' {
+  interface Context {
+    testInvariantProbe: TestInvariantProbe
+  }
+}
+
+class TestInvariantProbe extends Service {
+  constructor(ctx: Context) {
+    super(ctx, 'testInvariantProbe')
+  }
+}
+
+describe('global test invariant host', () => {
+  it('uses one exhaustive topology to reserve every package name with enabled checks', async () => {
+    const ctx = new Context()
+    await ctx.plugin(TestInvariantProbe)
+
+    const owners = packageInvariantOwners(process.cwd())
+    expect(Object.keys(testInvariantCompanions)).toHaveLength(owners.length)
+    const unreserved: string[] = []
+    for (const owner of owners) {
+      try {
+        const dispose = ctx.invariants.register(owner.packageName, () => {})
+        unreserved.push(owner.packageName)
+        dispose()
+      } catch (error) {
+        expect(error).toHaveProperty(
+          'message',
+          `invariants: package "${owner.packageName}" is already registered`,
+        )
+      }
+    }
+    expect(unreserved).toEqual([])
+  })
+
+  it('mounts the owning package companion while leaving non-package roots service-only', () => {
+    expect(testInvariantCompanionPaths('/repo/packages/core/tools/tests/tools.spec.ts'))
+      .toEqual(['../packages/core/tools/src/invariant.ts'])
+    expect(testInvariantCompanionPaths('/repo/examples/echo-agent/tests/echo.spec.ts')).toEqual([])
+    expect(testInvariantCompanionPaths('/repo/scripts/test-invariants.spec.ts'))
+      .toEqual(Object.keys(testInvariantCompanions).sort())
+  })
+
+  it('loads and executes every source companion through the real Loader shape', async () => {
+    const owners = new Map(packageInvariantOwners(process.cwd()).map(owner => [owner.sourcePath, owner.packageName]))
+    const registrations = new Map<string, string>()
+    const loader = Object.create(Loader.prototype) as Loader
+    const register = vi.fn((_packageName: string, installer: InvariantInstaller) => {
+      expect(typeof installer).toBe('function')
+      return () => {}
+    })
+    const fakeContext = { invariants: { register } } as unknown as Context
+    for (const [rawPath, companion] of Object.entries(testInvariantCompanions)) {
+      const path = rawPath.replace(/^\.\.\//, '')
+      expect(companion.default, path).toBeUndefined()
+      const unwrapped = loader.unwrapExports(companion) as typeof companion
+      expect(unwrapped, path).toBe(companion)
+      expect(typeof unwrapped.name, path).toBe('string')
+      expect(unwrapped.inject, path).toContain('invariants')
+      expect(typeof unwrapped.apply, path).toBe('function')
+      await unwrapped.apply(fakeContext)
+      const call = register.mock.calls.at(-1)
+      if (call === undefined) throw new Error(`${path}: companion did not register`)
+      registrations.set(path, call[0])
+    }
+    expect(registrations).toEqual(owners)
+  })
+
+  it('recognizes focused invariant suites without a package inventory', () => {
+    expect(usesManualInvariantTree('/repo/packages/core/session/tests/invariant.spec.ts')).toBe(true)
+    expect(usesManualInvariantTree('/repo/packages/core/session/tests/request-invariant-hmr.spec.ts')).toBe(true)
+    expect(usesManualInvariantTree('C:\\repo\\packages\\support\\invariants\\tests\\service.spec.ts')).toBe(true)
+    expect(usesManualInvariantTree('/repo/packages/examples/agent-spine-demo/tests/agent-core.spec.ts')).toBe(true)
+    expect(usesManualInvariantTree('/repo/packages/core/session/tests/session.spec.ts')).toBe(false)
+  })
+})
--- a/scripts/test-invariants.ts
+++ b/scripts/test-invariants.ts
@@ -0,0 +1,150 @@
+/**
+ * Vitest-wide invariant host. Ordinary Cordis roots receive the invariant
+ * service with global enablement plus the current test package's companion.
+ * One topology test mounts every companion; focused invariant tests own their
+ * service topology explicitly.
+ */
+
+import { expect } from 'vitest'
+import { RegistryService } from 'cordis'
+import type { Context, Plugin } from 'cordis'
+import InvariantService from '@deepseek-ai/dsh-invariants'
+
+declare global {
+  interface ImportMeta {
+    /** Eager Vite module-glob expansion used by the Vitest setup file. */
+    glob<TModule>(pattern: string, options: { eager: true }): Record<string, TModule>
+  }
+}
+
+/** Loader-safe shape shared by every package invariant companion. */
+export interface TestInvariantCompanion {
+  readonly name: string
+  readonly inject: readonly string[]
+  readonly default?: unknown
+  apply(ctx: Context): Promise<() => void>
+}
+
+/** Every package companion, discovered eagerly so coverage observes each registration. */
+export const testInvariantCompanions: Readonly<Record<string, TestInvariantCompanion>> =
+  import.meta.glob<TestInvariantCompanion>('../packages/*/*/src/invariant.ts', { eager: true })
+
+/** Manual-topology suites whose names cannot follow the focused invariant convention. */
+const MANUAL_INVARIANT_TEST_EXCEPTIONS = [
+  '/packages/support/invariants/tests/service.spec.ts',
+  '/packages/examples/agent-spine-demo/tests/agent-core.spec.ts',
+] as const
+
+interface InvariantHost {
+  readonly fibers: readonly PluginFiber[]
+  readonly byCallback: ReadonlyMap<unknown, PluginFiber>
+  readonly ready: Promise<void>
+}
+
+type PluginFiber = ReturnType<RegistryService['plugin']>
+
+const hosts = new WeakMap<Context, InvariantHost>()
+// eslint-disable-next-line @typescript-eslint/unbound-method -- every call below supplies its RegistryService receiver explicitly.
+const originalPlugin = RegistryService.prototype.plugin
+
+RegistryService.prototype.plugin = function(plugin: Plugin, config?: unknown, getOuterStack?: () => string[]) {
+  const testPath = expect.getState().testPath ?? ''
+  if (usesManualInvariantTree(testPath)) return originalPlugin.call(this, plugin, config, getOuterStack)
+
+  const root = this.ctx.root
+  const host = hosts.get(root) ?? startInvariantHost(root)
+  const callback = this.resolve(plugin)
+  const existing = callback === undefined ? undefined : host.byCallback.get(callback)
+  if (existing !== undefined) {
+    return this.ctx === root ? joinInvariantStartup(existing, host.ready) : existing
+  }
+
+  const fiber = originalPlugin.call(this, plugin, config, getOuterStack)
+  // A root-level await is the test's composition boundary. Nested plugin
+  // fibers must not await their own companion parent through the global host.
+  if (this.ctx !== root) return fiber
+  return joinInvariantStartup(fiber, host.ready)
+}
+
+/**
+ * Detect focused suites that construct service selection or companion lifecycle explicitly.
+ * @param testPath - absolute or repo-relative Vitest file path.
+ * @returns whether the global invariant host must leave the root untouched.
+ */
+export function usesManualInvariantTree(testPath: string): boolean {
+  const normalized = testPath.replaceAll('\\', '/')
+  if (/\/packages\/[^/]+\/[^/]+\/tests\/[^/]*invariant[^/]*\.spec\.ts$/.test(normalized)) return true
+  return MANUAL_INVARIANT_TEST_EXCEPTIONS.some(path => normalized.endsWith(path))
+}
+
+const ALL_COMPANION_TESTS = ['/scripts/test-invariants.spec.ts'] as const
+
+/**
+ * Select the package companions that an ordinary test root must register.
+ * Package tests receive their owner's checks; the dedicated topology test
+ * receives every owner so coverage and exhaustive runtime registration remain
+ * independently enforced.
+ * @param testPath - absolute or repo-relative normalized Vitest file path.
+ * @returns sorted `import.meta.glob` keys for companions to mount.
+ */
+export function testInvariantCompanionPaths(testPath: string): string[] {
+  const normalized = testPath.replaceAll('\\', '/')
+  const allPaths = Object.keys(testInvariantCompanions).sort()
+  if (ALL_COMPANION_TESTS.some(path => normalized.endsWith(path))) return allPaths
+
+  const owner = normalized.match(/\/packages\/([^/]+)\/([^/]+)\/tests\//)
+  if (owner === null) return []
+  const companionPath = `../packages/${owner[1]}/${owner[2]}/src/invariant.ts`
+  if (testInvariantCompanions[companionPath] === undefined) {
+    throw new Error(`test invariants: package test has no companion at ${companionPath}`)
+  }
+  return [companionPath]
+}
+
+function startInvariantHost(root: Context): InvariantHost {
+  const fibers: PluginFiber[] = []
+  const byCallback = new Map<unknown, PluginFiber>()
+  const mount = (plugin: Plugin, config?: unknown): void => {
+    const fiber = originalPlugin.call(root.registry, plugin, config)
+    const callback = root.registry.resolve(plugin)
+    if (callback === undefined) throw new Error('test invariants: companion is not a valid Cordis plugin')
+    fibers.push(fiber)
+    byCallback.set(callback, fiber)
+  }
+
+  mount(InvariantService, { enabled: true })
+  const testPath = expect.getState().testPath ?? ''
+  const companionPaths = testInvariantCompanionPaths(testPath)
+  for (const path of companionPaths) {
+    const companion = testInvariantCompanions[path]
+    if (companion === undefined) {
+      throw new Error(`test invariants: selected companion vanished at ${path}`)
+    }
+    if (!companion.inject.includes('invariants')) {
+      throw new Error(`test invariants: ${path} must inject the invariant service`)
+    }
+    mount(companion)
+  }
+
+  const [serviceFiber, ...companionFibers] = fibers
+  if (serviceFiber === undefined) throw new Error('test invariants: service fiber was not mounted')
+  // A companion is initially PENDING on the invariant service, and Cordis
+  // Fiber.await() only joins work already in flight. Wait for the service to
+  // activate its dependants before joining their startup and failures.
+  const ready = serviceFiber.await()
+    .then(() => Promise.all(companionFibers.map(fiber => fiber.await())))
+    .then(() => undefined)
+  const host = { fibers, byCallback, ready }
+  hosts.set(root, host)
+  return host
+}
+
+function joinInvariantStartup(fiber: PluginFiber, invariantReady: Promise<void>): PluginFiber {
+  const readiness = fiber.await().then(async (loaded) => {
+    await invariantReady
+    return loaded
+  })
+  const joined = Object.create(fiber) as PluginFiber
+  joined.then = readiness.then.bind(readiness)
+  return joined
+}
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -9,6 +9,7 @@
    { "doc": "docs/core-data-structures/core.md", "symbol": "FinishReasonMap", "source": "packages/llm/llm/src/types.ts" },
    { "doc": "docs/core-data-structures/core.md", "symbol": "LlmProviderInfo", "source": "packages/llm/llm/src/types.ts" },
    { "doc": "docs/core-data-structures/core.md", "symbol": "LlmModelInfo", "source": "packages/llm/llm/src/types.ts" },
+    { "doc": "docs/core-data-structures/core.md", "symbol": "LlmModelContext", "source": "packages/llm/llm/src/types.ts" },
    { "doc": "docs/core-data-structures/core.md", "symbol": "GenerateOptions", "source": "packages/llm/llm/src/types.ts" },
    { "doc": "docs/core-data-structures/core.md", "symbol": "ToolSchema", "source": "packages/llm/llm/src/types.ts" },
    { "doc": "docs/core-data-structures/core.md", "symbol": "LlmCallConfig", "source": "packages/llm/llm/src/call-config.ts" },
@@ -203,6 +204,17 @@
    { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowStartRequest", "source": "packages/workflow/workflow/src/types.ts" },
    { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowMeta", "source": "packages/workflow/workflow/src/types.ts" },
    { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowResult", "source": "packages/workflow/workflow/src/types.ts" },
-    { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowRun", "source": "packages/workflow/workflow/src/types.ts" }
+    { "doc": "docs/core-data-structures/workflow.md", "symbol": "WorkflowRun", "source": "packages/workflow/workflow/src/types.ts" },
+
+    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspOperation", "source": "packages/lsp/lsp/src/types.ts" },
+    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspPosition", "source": "packages/lsp/lsp/src/types.ts" },
+    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspRange", "source": "packages/lsp/lsp/src/types.ts" },
+    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspQueryRequest", "source": "packages/lsp/lsp/src/types.ts" },
+    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspProviderQuery", "source": "packages/lsp/lsp/src/types.ts" },
+    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspLocation", "source": "packages/lsp/lsp/src/types.ts" },
+    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspHover", "source": "packages/lsp/lsp/src/types.ts" },
+    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspQueryResult", "source": "packages/lsp/lsp/src/types.ts" },
+    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspProvider", "source": "packages/lsp/lsp/src/types.ts" },
+    { "doc": "docs/core-data-structures/lsp.md", "symbol": "LspService", "source": "packages/lsp/lsp/src/types.ts" }
  ]
 }
--- a/scripts/verify-built-package-invariants.mjs
+++ b/scripts/verify-built-package-invariants.mjs
@@ -0,0 +1,102 @@
+/** Verify every packed companion through its package self-reference under plain Node. */
+
+import { spawnSync } from 'node:child_process'
+import {
+  copyFileSync,
+  globSync,
+  mkdirSync,
+  mkdtempSync,
+  readFileSync,
+  rmSync,
+} from 'node:fs'
+import { dirname, resolve } from 'node:path'
+import { pathToFileURL } from 'node:url'
+
+const root = resolve(import.meta.dirname, '..')
+const loaderUrl = pathToFileURL(resolve(root, 'vendor/loader/lib/index.js')).href
+const failures = []
+const manifests = globSync('packages/*/*/package.json', { cwd: root }).sort()
+const packArgs = ['pack', '--dry-run', '--json', '--ignore-scripts']
+// Windows cannot spawn npm's .cmd shim directly; setup-node installs this JS
+// entrypoint beside node.exe, so the probe stays shell-free on every runner.
+const npmInvocation = process.platform === 'win32'
+  ? [process.execPath, [resolve(dirname(process.execPath), 'node_modules/npm/bin/npm-cli.js'), ...packArgs]]
+  : ['npm', packArgs]
+
+for (const manifestPath of manifests) {
+  const packageDir = dirname(resolve(root, manifestPath))
+  const manifest = JSON.parse(readFileSync(resolve(root, manifestPath), 'utf8'))
+  const packageName = manifest.name
+  if (typeof packageName !== 'string' || packageName.length === 0) {
+    failures.push(`${manifestPath}: missing package name`)
+    continue
+  }
+
+  const pack = spawnSync(npmInvocation[0], npmInvocation[1], {
+    cwd: packageDir,
+    encoding: 'utf8',
+  })
+  if (pack.status !== 0) {
+    const detail = pack.error?.message
+      ?? (pack.stderr.trim() || pack.stdout.trim() || `npm pack exited ${pack.status}`)
+    failures.push(`${packageName}: ${detail}`)
+    continue
+  }
+
+  let files
+  try {
+    const result = JSON.parse(pack.stdout)
+    files = result[0]?.files
+    if (!Array.isArray(files)) throw new Error('npm pack returned no file inventory')
+  } catch (error) {
+    failures.push(`${packageName}: cannot parse npm pack inventory: ${String(error)}`)
+    continue
+  }
+
+  // Keep the packed view below its owning package so Node reaches the real
+  // pnpm dependency links. Junctioning node_modules elsewhere breaks pnpm's
+  // relative workspace links on Windows.
+  const stagedPackageDir = mkdtempSync(resolve(packageDir, '.dsh-packed-invariant-'))
+  try {
+    for (const file of files) {
+      if (typeof file.path !== 'string'
+        || (file.path !== 'package.json' && !file.path.startsWith('lib/'))) continue
+      const target = resolve(stagedPackageDir, file.path)
+      mkdirSync(dirname(target), { recursive: true })
+      copyFileSync(resolve(packageDir, file.path), target)
+    }
+
+    const probe = `
+      const companion = await import(${JSON.stringify(`${packageName}/invariant`)});
+      const { default: Loader } = await import(${JSON.stringify(loaderUrl)});
+      if ('default' in companion) throw new Error('companion has a default export');
+      const loader = Object.create(Loader.prototype);
+      const unwrapped = loader.unwrapExports(companion);
+      if (unwrapped !== companion) throw new Error('Loader collapsed the companion namespace');
+      if (typeof unwrapped.name !== 'string') throw new Error('companion name is missing');
+      if (!Array.isArray(unwrapped.inject) || !unwrapped.inject.includes('invariants')) {
+        throw new Error('companion does not inject invariants');
+      }
+      if (typeof unwrapped.apply !== 'function') throw new Error('companion apply is missing');
+    `
+    const result = spawnSync(process.execPath, ['--input-type=module', '--eval', probe], {
+      cwd: stagedPackageDir,
+      encoding: 'utf8',
+    })
+    if (result.status !== 0) {
+      const detail = result.error?.message
+        ?? (result.stderr.trim() || result.stdout.trim() || `node exited ${result.status}`)
+      failures.push(`${packageName}: ${detail}`)
+    }
+  } finally {
+    rmSync(stagedPackageDir, { recursive: true, force: true })
+  }
+}
+
+if (failures.length > 0) {
+  console.error('verify-built-package-invariants: packed companion failures:')
+  for (const failure of failures) console.error(`  ${failure}`)
+  process.exit(1)
+}
+
+console.log(`verify-built-package-invariants: ${manifests.length} packed companion(s) passed plain-Node Loader checks.`)
--- a/scripts/verify-package-invariants.ts
+++ b/scripts/verify-package-invariants.ts
@@ -0,0 +1,21 @@
+/** Verify package-owned invariant source and publication contracts. */
+
+import { resolve } from 'node:path'
+import {
+  collectPackageInvariantViolations,
+  formatPackageInvariantViolation,
+  packageInvariantOwners,
+} from './package-invariants.ts'
+
+const root = resolve(import.meta.dirname, '..')
+const violations = collectPackageInvariantViolations(root)
+
+if (violations.length > 0) {
+  console.error('verify-package-invariants: violations found:')
+  for (const violation of violations) {
+    console.error(`  ${formatPackageInvariantViolation(root, violation)}`)
+  }
+  process.exit(1)
+}
+
+console.log(`verify-package-invariants: ${packageInvariantOwners(root).length} hand-owned package companion(s) conform.`)
--- a/scripts/verify-package-readme-model-experience.ts
+++ b/scripts/verify-package-readme-model-experience.ts
@@ -52,6 +52,8 @@ const SENTENCE_MODEL_EXPERIENCE: Readonly<Record<string, SentenceContract>> = {
  'packages/hooks/hook-protocol': { kind: 'indirect', reason: 'Only the hook bridge plugins render decoded hook output to a model.' },
  'packages/llm/llm': { kind: 'none', reason: 'The adapter registry forwards already-assembled requests unchanged.' },
  'packages/llm/token-meter': { kind: 'indirect', reason: 'The measurement service leaves model-visible changes to its consumers.' },
+  'packages/lsp/lsp': { kind: 'indirect', reason: 'The provider registry delegates model rendering to dsh-tool-lsp.' },
+  'packages/lsp/lsp-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-tool-lsp.' },
  'packages/sandbox/sandbox-local': { kind: 'indirect', reason: 'The provider backend delegates model rendering to dsh-bash-sandbox and dsh-tool-bash.' },
  'packages/sandbox/sandbox-policy': { kind: 'indirect', reason: 'The policy service holds the mode dsh-tool-bash and dsh-tool-fs render in their denial markers.' },
  'packages/sdk/create-sdk': { kind: 'indirect', reason: 'The initializer only writes project files; selected runtime plugins provide the generated project model surface.' },