docs(spec): the metadata-type registry named a hook that does not exist (#4212) - #4216
Merged
Merged
Conversation
`registerMetadataTypeSchema` and `registerMetadataTypeActions` both told plugins to call them "from their `onInstall` hook", and named `/api/v1/meta/types/:type` as the endpoint that would serve the result. Neither is real. The kernel's plugin contract is `init` / `start` / `destroy` (`packages/core/src/types.ts`): `kernel.use()` validates and stores, `bootstrap()` calls `init` then `start`. The `onInstall` / `onEnable` / `onDisable` / `onUninstall` / `onUpgrade` family declared on `PluginLifecycleSchema` has no invocation site anywhere in the runtime — its only importer repo-wide is its own test. So a plugin following the documented advice registered nothing and got no error saying so, and its custom metadata type silently served no JSON Schema. `/api/v1/meta/types/:type` is likewise not a registered route; the route ledger carries `GET /meta/types` and the public surface is `GET /api/v1/meta`. Both TSDoc blocks and `content/docs/plugins/adding-a-metadata-type.mdx` now name the hook that runs and the endpoint that exists, with the example written as a real `Plugin` with an `init(ctx)`. That matches `DatasourceAdminServicePlugin` — the single production caller of `registerMetadataTypeActions` — which has always used `init` rather than the `onInstall` the docs prescribed. Two facts the old text obscured, now stated because both change how an author writes the code: - `getMetaTypes()` reads these registries at REQUEST time, not from a boot snapshot, so a type registered during `init` is served from the first call. - Registering a schema does not by itself put a type in the listing. `getMetaTypes()` 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. Documentation only; no behaviour change. Whether the five uninvoked lifecycle hooks get implemented or retired (ADR-0049) is #4212 — this stops the registry's own docs from sending authors at the dead one meanwhile. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh
|
The latest updates on your projects. Learn more about Vercel for GitHub. 1 Skipped Deployment
|
github-actions
Bot
added
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 106 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
os-zhuang
marked this pull request as ready for review
July 30, 2026 16:31
os-zhuang
added a commit
that referenced
this pull request
Jul 30, 2026
…ever implemented (#4212) (#4233) PluginLifecycleSchema declared onInstall / onEnable / onDisable / onUninstall / onUpgrade, each with confident TSDoc. The kernel calls none of them, and never has. Its plugin contract is init / start / destroy (packages/core/src/types.ts): use() validates and stores, bootstrap() runs init then start, shutdown runs destroy in reverse order. There is no install phase and no first-time-only path. Repo-wide, the schema's only importer was its own test — and the docs built on it sent authors at a dead seam (#4216 fixed the metadata-type registry's advice; this removes what the advice pointed at). Removed, with zero consumers verified across objectstack, objectui and cloud: - PluginLifecycleSchema + PluginLifecycleHooks, and the five hook members on PluginSchema (now a plain descriptor object — and, with the function members gone, JSON-representable: it publishes a kernel/Plugin JSON schema for the first time). - UpgradeContextSchema + UpgradeContext, which existed solely to serve onUpgrade. - The @objectstack/spec/system ./types module: the ObjectStackPlugin interface and its PluginContext / PluginLogger / ObjectQLClient / IKernel / ObjectOSKernel companions — seeded by the aspirational spec in issue #2, referenced by no file in any repo since. Route: plain deletion, not retiredKey() tombstones — nothing parses plugin objects through these schemas (stack.zod carries plugins as z.array(z.unknown())), so a prescription nobody can receive is noise; the plugin-runtime.zod.ts precedent. Per that precedent the key-vanish guard's baseline entries (kernel/UpgradeContext:* in authorable-surface.json) are dropped deliberately, and kernel/UpgradeContext leaves json-schema.manifest.json in the same PR. No ADR-0087 conversion: function members on runtime objects are not authorable stack metadata; there is no source for os migrate meta to rewrite. The kernel docs that taught the fiction now teach the real contract: protocol/kernel/lifecycle.mdx (five-hook example → init/start/destroy class, plus the app-bundle onEnable distinction), protocol/kernel/index.mdx (the "kernel calls onInstall/onEnable" claim and a fictional Kernel.installPlugin API → the real package-install flow), protocol/kernel/plugin-spec.mdx (a manifest `lifecycle:` file-map ManifestSchema never declared + a six-hook section with an invented context API → the runtime contract and real execution order), and AGENTS.md's own plugin example. Each page carries a callout naming what was fiction, so an author who wrote against the old docs finds the correction where the fiction was. Pin tests: PluginSchema declares none of the five names; an authored hook is stripped by the parse; the retired exports are gone from the module. The stack-level lint keeps reporting onDisable and friends as undeclared keys, so authors who still write them hear about it at load. Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh Co-authored-by: Claude <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Part of #4212 — the half that is a factual correction rather than a design decision.
What was wrong
registerMetadataTypeSchemaandregisterMetadataTypeActionsboth told plugins to call them "from theironInstallhook", and named/api/v1/meta/types/:typeas the endpoint that would then serve the result. Neither exists.The hook. The kernel's plugin contract is
init/start/destroy(packages/core/src/types.ts:91-163).kernel.use()validates and stores (packages/core/src/kernel.ts:180-201) — it invokes nothing;bootstrap()callsinit(:544) then optionallystart(:587). TheonInstall/onEnable/onDisable/onUninstall/onUpgradefamily onPluginLifecycleSchemahas no invocation site anywhere in the runtime — its only importer repo-wide is its own test. A plugin that followed the documented advice registered nothing and got no error, and its custom metadata type silently served no JSON Schema.The endpoint.
/api/v1/meta/types/:typeis not a registered route.route-ledger.ts:216carriesGET /meta/types(server-only), and the public surface isGET /api/v1/meta.The one plugin doing this in production already ignores the docs:
DatasourceAdminServicePlugincallsregisterMetadataTypeActionsas the first statement ofinit(ctx)(packages/services/service-datasource/src/datasource-admin-plugin.ts:189-199), and its own comment names/api/v1/metacorrectly.registerMetadataTypeSchemahas zero callers repo-wide — not even a test — which is roughly what you'd expect of an API whose only documented entry point cannot fire.What this changes
Both TSDoc blocks and
content/docs/plugins/adding-a-metadata-type.mdxnow nameinit(ctx)andGET /api/v1/meta. The doc example is rewritten as a realPluginwith aninit, matching the production caller instead of a shape that does not load.Two facts the old text obscured, now stated because each changes how an author writes the code:
getMetaTypes()reads these registries at request time, not from a boot snapshot (packages/metadata-protocol/src/protocol.ts:1889,1898,1913), so a type registered duringinitis served from the first call onward. The only cache is aWeakMapkeyed on Zod object identity for the JSON-Schema conversion — it does not memoise the lookup.getMetaTypes()enumeratesengine.registry.getRegisteredTypes()unioned with the metadata service's (protocol.ts:1858-1873), then decorates each with its schema. A type present only in the schema registry is never reached, soadditionalTypesis not optional.Documentation only. No behaviour change, no API surface change.
Scope — what I deliberately left alone
content/docs/protocol/kernel/{index,lifecycle,plugin-spec}.mdxdocument the wholeonInstall/onEnable/onDisablelifecycle as real;index.mdx:275states "The kernel resolves plugin dependencies, calls each plugin'sonInstall/onEnable", which is false. I did not touch them: rewriting those pages means answering #4212's enforce-or-remove question (implement the hooks, or retire them from the protocol), and that is a maintainer decision rather than something a doc pass should settle by fiat. Whichever way it goes, those three pages move with it.I also corrected my own filing on #4212 in a comment: I had counted
onEnableas invoked, citingapp-plugin.ts. Those call sites are the app-bundle runtime member (STACK_RUNTIME_MEMBERS), a different contract that shares the name. The kernel never callsonEnableon akernel.use()plugin, so the real count is 0 of 5 dead, not 4 of 5.Verification
check:doc-authoringclean (214 files);metadata-type-actionssuite passes; rootpnpm lintclean.Generated by Claude Code