Four of the five declared plugin lifecycle hooks are never invoked — and the metadata-type registry docs tell plugins to use one of them

[os-zhuang]

Found while exempting onEnable from the new top-level authoring-key lint (#4167 / #4189). Checking which lifecycle hooks the runtime actually honours turned up that only one of the five does.

The finding

PluginLifecycleSchema (packages/spec/src/kernel/plugin.zod.ts:80-90) declares five hooks, each with descriptive TSDoc, and PluginLifecycleHooks (packages/spec/src/system/types/plugin.ts) mirrors them:

hook	declared	invoked anywhere
onInstall	✓	0 call sites
onEnable	✓	3 (packages/runtime/src/app-plugin.ts)
onDisable	✓	0 call sites
onUninstall	✓	0 call sites
onUpgrade	✓	0 call sites

Method: repo-wide grep over packages/, apps/, examples/ excluding dist/ and tests, for both direct (.onInstall() and indexed ([hook]() invocation, plus a check for any dynamic lifecycle dispatch table. Nothing. onEnable is the only hook with a runtime that runs it.

onUpgrade has an entire supporting type built for it — UpgradeContextSchema with previousVersion / newVersion / isMajorUpgrade (plugin.zod.ts:59-76), exported from the package root — for a callback nothing ever calls.

The part that actively misleads

packages/spec/src/kernel/metadata-type-schemas.ts documents onInstall as the place to call two registration functions:

:134  * Plugins that introduce custom metadata types — declared through
      * `additionalTypes` on `MetadataPluginConfig` — should call this from
      * their `onInstall` hook so the engine's `/meta/types/:type` endpoint
      * starts emitting a real JSON Schema for them.

:167  * Plugins call this from `onInstall` to layer actions onto any type —
      * built-in or custom — without forking the registry.

A plugin author who follows that instruction exactly registers nothing. registerMetadataTypeSchema / registerMetadataTypeActions never run, /api/v1/meta/types/:type keeps emitting no schema and no type-level buttons, and there is no error — the hook simply never fires. That is the same silent-drop shape as #3786/#4148/#4167, one layer up: the guidance is the thing that's dead, not just the property.

Why it matters

• declared ≠ enforced (Prime Directive chore: version packages #10) on the plugin system's own contract. packages/spec is the constitution; five hooks are written into it and four have no implementation.
• It is load-bearing advice, not just an unused field. The metadata-type registry is the documented extension point for custom metadata types, and its documented entry point does not exist.
• It propagates: packages/cli/src/utils/config.ts:93 and packages/cli/src/commands/serve.ts:676 both name onDisable alongside onEnable when preserving module-level named exports, so the CLI carefully carries a hook to a runtime that will not call it.

Suggested resolution — the spec-property-retirement playbook

Per ADR-0049 enforce-or-remove, each of the four needs a decision, and they may not all get the same one:

1. onInstall — highest priority, because it has documented consumers. Either implement it (the metadata-type registry needs some install-time seam) or rewrite both TSDoc blocks to name a hook that runs. Rewriting the docs to say onEnable is probably the cheap correct answer, but only if onEnable's timing is actually right for registry population — worth checking rather than assuming.
2. onDisable / onUninstall — no consumers found, no callers. Retire, or implement as part of a real enable/disable lifecycle if one is planned.
3. onUpgrade — retire together with UpgradeContextSchema, or wire it into the package-upgrade path that already exists (packages/spec/src/kernel/package-upgrade.ts), which looks like where it was meant to go.

Whichever way each goes, the lint family this came out of would like a note: onEnable is now in STACK_RUNTIME_MEMBERS precisely because the runtime honours it, and onDisable is deliberately excluded because it does not. If onDisable ever becomes real, that exclusion has to move with it — a test in packages/spec/src/kernel/metadata-authoring-lint.test.ts pins the current distinction and will fail loudly, which is the intended alarm.

I have not implemented anything here; #4189 only documents the current state where it had to.

[os-zhuang]

Correcting my own filing, and adding evidence that makes this worse rather than better.

I was wrong about onEnable

I wrote that onEnable is "invoked, 3 call sites (packages/runtime/src/app-plugin.ts)". Those three sites are a different contract that happens to share the name.

• app-plugin.ts:588-615 reads onEnable off the authored app bundle (this.bundle.default || this.bundle — the compiled objectstack.config.ts module) and calls it with a hand-built hostContext of {...ctx, ql, logger, drivers}. That is not a kernel Plugin, and that context is not PluginContext. It is the stack runtime member now named in STACK_RUNTIME_MEMBERS (packages/spec/src/data/authoring-key-lint.ts).
• The kernel never calls onEnable on anything passed to kernel.use().

So the correct statement is: all five hooks on PluginLifecycleSchema are dead, not four. The table in the issue body should read 0/5.

The surface is more thoroughly unused than I reported

• PluginSchema / PluginLifecycleSchema (packages/spec/src/kernel/plugin.zod.ts:80-143) — the only importers repo-wide are plugin.test.ts:4-5. No production code parses or executes them.
• The parallel TS interface ObjectStackPlugin (packages/spec/src/system/types/plugin.ts:114-132) is declared and referenced by no other file at all.
• What the kernel really runs (packages/core/src/kernel.ts): use() validates + stores (:180-201, no hook), then bootstrap() calls init (:544) and optionally start (:587), with destroy on shutdown (:649). The Plugin interface (packages/core/src/types.ts:91-163) declares exactly those three. There is no install phase and no first-time-only path anywhere — use → init → start runs identically on every boot.
• kernel:before-init / kernel:after-init are declared in packages/spec/src/contracts/plugin-lifecycle-events.ts:99,105 and never triggered.
• Related dead code: ObjectQLEngine.use(manifestPart, runtimePart) calls pluginDef.onEnable(context) at packages/objectql/src/engine.ts:495 — and that method has no callers. driver-memory and driver-mongodb default-export objects shaped for it; nothing loads them through it.
• The repo already recorded the mismatch once: docs/audits/2026-06-handwritten-docs-accuracy-followups.md:328.

The documented-consumer problem is also worse

Both halves of the advice in metadata-type-schemas.ts were wrong, not just the hook name:

• /api/v1/meta/types/:type is not a registered route. route-ledger.ts:216 carries GET /meta/types; the public surface is GET /api/v1/meta. The endpoint the docs promised would "start emitting a real JSON Schema" does not exist either.
• registerMetadataTypeSchema has zero callers repo-wide — not one, not even a test.
• registerMetadataTypeActions has exactly one production caller, DatasourceAdminServicePlugin (packages/services/service-datasource/src/datasource-admin-plugin.ts:199) — and it calls it from init(ctx), never onInstall. Its own comment names /api/v1/meta correctly. The only plugin doing this has always ignored the documented advice.
• A further trap: registering a schema alone cannot surface a type. getMetaTypes() (packages/metadata-protocol/src/protocol.ts:1858-1875) enumerates engine.registry.getRegisteredTypes() unioned with the metadata service's, then decorates each with its schema — a type present only in the schema registry is never reached.

What I've done, and what I deliberately have not

Sent a PR correcting the two TSDoc blocks and content/docs/plugins/adding-a-metadata-type.mdx to name init(ctx) and GET /api/v1/meta, with the example written as a real Plugin. Documentation only — it stops authors being sent at the dead hook while this issue is open.

I did not touch content/docs/protocol/kernel/{index,lifecycle,plugin-spec}.mdx, which document the whole onInstall/onEnable/onDisable lifecycle as real — index.mdx:275 states "The kernel resolves plugin dependencies, calls each plugin's onInstall / onEnable", which is simply false. Rewriting those means answering the enforce-or-remove question rather than fixing a typo, and that is this issue's decision to make, not a doc pass's. Whichever way it goes, those three pages move with it.

---

Generated by Claude Code