spec: the kernel startup-orchestrator contract (IStartupOrchestrator, PluginStartupResultSchema) is declared, exported and documented, and implemented by nothing #16059

Filed bare by the os-dev seat working #15820, as an out-of-scope finding surfaced while re-deriving that card's anchors. No domain:* applied, no assignee — routing is triage's call. All readings taken at origin/main e1d4f9e3f99aa16818b03e831442a2758697ef3a.

The finding

packages/spec/src/contracts/startup-orchestrator.ts and packages/spec/src/kernel/startup-orchestrator.zod.ts declare a full plugin-startup orchestration contract — IStartupOrchestrator with orchestrateStartup, plus PluginStartupResultSchema, StartupOptionsSchema, StartupOrchestrationResultSchema and HealthStatusSchema. It is exported from the package (packages/spec/api-surface/contracts.json:157, export-origins/contracts.json:157) and documented for consumers at content/docs/references/kernel/startup-orchestrator.mdx.

Nothing in this repo implements it, parses with it, or consumes it.

Measurements, each with a firing control

Implementers of IStartupOrchestrator, whole repo: zero outside packages/spec. Every hit is one of: the declaration itself, packages/spec/src/contracts/startup-orchestrator.test.ts (four ad-hoc object literals annotated with the type — shape pins, not an implementation), CHANGELOG rows, generated api-surface JSON, or the docs page. Same for orchestrateStartup: no production call site anywhere.

Consumers of PluginStartupResultSchema outside packages/spec: zero. The only two hits are content/docs/references/kernel/startup-orchestrator.mdx (a docs import) and a doc comment added by the #15820 PR.

Control fires. The same search shape finds contract interfaces in packages/core that ARE implemented — packages/core/src/metadata-service-contract.ts and packages/core/src/fallbacks/memory-metadata.ts — so the probe reaches, and the zeros above are readings rather than a dead search.

What actually starts plugins. ObjectKernel.startPluginWithTimeout in packages/core/src/kernel.ts, returning packages/core/src/plugin-loader.ts's own PluginStartupResult. The two declarations share a name and nothing else: core's carries pluginName: string, a live error?: Error and timedOut?: boolean; the spec's carries a plugin object, a serializable error projection and a health member. Core neither imports nor references the spec contract.

Why this is worth a card rather than a shrug

ADR-0078 (no silently inert metadata) and ADR-0049 (enforce-or-remove) both target exactly this: a surface that is declared, exported and documented, and that no runtime reads. The cost here is not a crash, it is a false map. A consumer — an AI-maintained one especially, which is the population ADR-0087 designs for — reads the exported contract and the reference docs and concludes there is an orchestrator seam to implement against or to receive results from. There is not. Whatever it builds against that shape can never be reached by the running kernel.

The two candidate dispositions look opposite and only triage should pick:

1. Enforce it — make the kernel's startup path implement the declared contract, or produce values that PluginStartupResultSchema actually parses. This is the direction the spec's own docs already promise.
2. Retire it — remove the contract and its schemas under the enforce-or-remove route, with the ADR-0087 ledger disposition the removal of a published, documented surface requires.

⛔ Not folded into #15820, which is deliberately narrow: that card aligns one field name in packages/core and does not touch packages/spec. This is the wider question that alignment made visible, and it is a packages/spec question.

Generated by Claude Code

Generated by Claude Code