refactor(spec)!: retire the plugin lifecycle-hook family the kernel never implemented (#4212) - #4233
Merged
Merged
Conversation
…ever implemented (#4212) 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. 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
size/xl
documentation
Contributor
📓 Docs Drift CheckThis PR changes 2 package(s): 112 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 17:03
This was referenced Jul 30, 2026
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.
Closes #4212 — the enforce-or-remove half; #4216 already fixed the advice that pointed at the dead hook.
What is being removed, and the evidence standard
PluginLifecycleSchemadeclaredonInstall/onEnable/onDisable/onUninstall/onUpgrade, each with confident TSDoc ("Called when plugin is installed", …). The kernel calls none of them, and never has. Its plugin contract isinit/start/destroy(packages/core/src/types.ts:91-163):use()validates and stores (kernel.ts:180-201— no code runs),bootstrap()runsinit(:544) thenstart(:587), shutdown runsdestroyin reverse (:649). There is no install phase and no first-time-only path.Consumer check, per the retirement playbook ("a grep can only prove presence; close the call graph"):
PluginLifecycleSchema/PluginSchema— only importer repo-wide wasplugin.test.tsitself.UpgradeContextSchema/UpgradeContext— zero consumers; built to serveonUpgradeexclusively.@objectstack/spec/system./typesmodule (ObjectStackPlugin+PluginContext/PluginLogger/ObjectQLClient/IKernel/ObjectOSKernel) — referenced by no file in any repo; it was seeded verbatim by the aspirational spec in issue ✨ Set up Copilot instructions #2 (January) and survived as fiction since.objectuiandcloudtoo: the only hits are objectui's own unrelatedblocks.zodkey and React props sharing the names.Route: plain deletion, not tombstones
Per the
spec-property-retirementplaybook §2, third row: nothing parses plugin objects through these schemas —stack.zodcarriespluginsasz.array(z.unknown())— so aretiredKey()prescription could never be received. Precedent:plugin-runtime.zod.ts(#3950/#4149).The build enforced the two consequences the playbook predicts, and both are handled deliberately in this PR:
gen:schema's vanish-guard flaggedkernel/UpgradeContext:*— the four baseline lines inauthorable-surface.jsonare dropped deliberately (the guard's message allows exactly this, done in the same PR).kernel/UpgradeContextleavesjson-schema.manifest.json; and with the function members gone,PluginSchemabecame JSON-representable for the first time — the generator addedkernel/Pluginto the published manifest.No ADR-0087 conversion: function members on runtime objects are not authorable stack metadata; there is no source file for
os migrate metato rewrite. Authors who still writeonDisable:on a stack keep hearing about it from the stack-level lint (lintUnknownStackKeys), which reports it as an undeclared key — a test pins that.FROM → TO
onInstallregistry.installPackage()→sys_packages). Install-shaped setup (services, schemas, metadata types) →init(ctx)onEnable(kernel plugin)init(ctx)/start(ctx). The app-bundleonEnablemodule export is a different, real contract and is untouched —AppPlugininvokes it at boot (STACK_RUNTIME_MEMBERS)onDisable/onUninstalldestroy()for runtime teardown; package uninstall is a registry transitiononUpgrade+UpgradeContextonBoot(docs-only)init/startThe docs taught the fiction; they now teach the contract
protocol/kernel/lifecycle.mdx— the five-hook plain-object example → aninit/start/destroyclass with real phase semantics, the app-bundleonEnabledistinction, and a callout naming the retirement.protocol/kernel/index.mdx— "The kernel resolves plugin dependencies, calls each plugin'sonInstall/onEnable" (false) and a fictionalKernel.installPlugin({ onInstall })API → the realuse → init → startorder and the real package-install flow (validate → register → materialize; no package code executes at install).protocol/kernel/plugin-spec.mdx— a manifestlifecycle:file-map ManifestSchema never declared, six per-file hooks (incl.onBoot) against an inventedcontext.db/context.schedulerAPI, and a fictional execution order → the runtime contract (verified againstPluginContext:registerServiceis real), the real boot/shutdown order, and a callout.AGENTS.md— its own plugin example taught the dead hooks; now shows the real class shape.releases/v17.mdx— row added to Dead spec clusters removed.Each callout says what was fiction, so an author who wrote against the old docs finds the correction at the place the fiction lived.
Verification
gen:api-surface/gen:spec-changes/gen:upgrade-guide/gen:docs/gen:skill-refsregenerated.check:liveness/empty-state/authorable-surface/docs/api-surface/spec-changes/upgrade-guide/skill-refs/skill-docs/skill-examples— all PASS (skill-refs after regen).check:i18nPASS; spec suite 276 files / 7154 tests; CLI build + suite 89 files / 916 tests; rootpnpm lintclean; doc guards (doc-authoring, role-word, org-identifier, release-notes, nul-bytes) PASS.PluginSchemadeclares none of the five names; an authored hook is stripped by the parse; the retired exports are gone from the module.major(pre-mode is active, so it lands as an rc pre-release bump), carrying the FROM → TO table per house convention.Deliberately untouched
ObjectQLEngine.use()'s deadonEnabledispatch (packages/objectql/src/engine.ts:495, no callers) and thedriver-memory/driver-mongodbdefault exports shaped for it — same disease, different organ; recorded on Four of the five declared plugin lifecycle hooks are never invoked — and the metadata-type registry docs tell plugins to use one of them #4212 for a follow-up rather than widened into this diff.kernel:before-init/kernel:after-init(declared inplugin-lifecycle-events.ts, never triggered) — same.PluginSchemaitself (now a plain descriptor) also has no production importer and doesn't even declare thename/initthe loader requires — candidate for its own retirement pass, noted on Four of the five declared plugin lifecycle hooks are never invoked — and the metadata-type registry docs tell plugins to use one of them #4212.Generated by Claude Code