Uh oh!
There was an error while loading. Please reload this page.
fix(spec): retire the never-built typed-event system; the lifecycle registry now lists the events that actually fire - #4241
Merged
Conversation
…sts the events that actually fire The lifecycle-event surface promised a typed-event system that was never built, in three layers (#4212 leftovers, ADR-0049 enforce-or-remove): - kernel/plugin-lifecycle-events.zod.ts: 346 lines of payload schemas + a 21-name event enum — zero consumers for every export, and the enum both listed 17 names nothing fires and missed 10 events that DO fire. Deleted, with its test and barrel line; the 13 schemas leave json-schema.manifest.json and authorable-surface.json in the same PR (sanctioned deliberate-removal path; the keys were never authorable — they described runtime event payloads no config author can write, so the silent-strip class the ratchet guards against is vacuous here). - contracts/plugin-lifecycle-events.ts: IPluginLifecycleEvents kept the same 17 dead names alongside 5 real ones, plus an ITypedEventEmitter nothing implements. Rewritten as the registry of the 14 events with a real emitter — kernel:{ready,bootstrapped,listening,shutdown}, app:seeded, metadata:reloaded (metadata now optional, matching the documented contract), external.schema.drift, ai:routes (out-of-repo emitter, in-repo listener), auth:configure, and the {service}:ready convention family (mcp, automation, analytics, external-datasource, datasource-admin) — each with its payload as observed at the fire site. - Enforcement so the registry cannot rot again: LifecycleEventName now types IPluginContext.hook/trigger in @objectstack/core as LifecycleEventName | (string & {}) — known names autocomplete, custom cross-plugin names stay legal — and a pinning test asserts two-way equality between the interface keys and the fire-site inventory. Docs follow the code: the generated reference page for the deleted zod file is gone (nav + index links updated via gen:docs), PROTOCOL_MAP row repointed at the contracts registry, skill reference index regenerated. Verified: spec 7142 tests green (275 files), core 437 green, spec tsc --noEmit clean, and the full generated-artifact gate family in sync (docs 251, skill refs/docs/examples, api-surface, authorable-surface, spec-changes, upgrade-guide, exported-any). Co-Authored-By: Claude Fable 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
|
Contributor
📓 Docs Drift CheckThis PR changes 2 package(s): 114 hand-written doc(s) reference the affected code and may need an implementation-accuracy re-verification:
|
Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh
os-zhuang
marked this pull request as ready for review
July 30, 2026 19:15
Uh oh!
There was an error while loading. Please reload this page.
os-zhuang added a commit
that referenced
this pull request
Jul 31, 2026
… v17 notes and status matrix (#4279) * docs(releases): record the #4212-family plugin-API retirements in the v17 notes and status matrix The v17 release notes already carried the #4212 row (lifecycle-hook family) but not its two follow-ups that also ship in the 17.0.0 train: - "Dead spec clusters removed" gains the #4241 row: the never-built typed-event cluster (ten payload schemas, the 21-name enum wrong in both directions, ITypedEventEmitter), and what replaced it — the enforced IPluginLifecycleEvents registry of the 14 events with a real emitter plus the LifecycleEventName soft union on hook/trigger. - "Smaller breaking changes" gains the #4242 entry: ObjectQLEngine.use() / ObjectQLHostContext removal, with the FROM → TO migration (registerApp / kernel plugin) and the explicit note that the app-bundle onEnable module export is a different, live contract. implementation-status.mdx stops claiming "lifecycle hooks" as a plugin-system capability (that family never ran and is now retired) and states the real init/start/destroy contract and the #4241 event registry instead. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh * chore: empty changeset for the docs-only release-notes update Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> 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 freeto 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.
What
Follows up the #4212 leftovers (ADR-0049 enforce-or-remove): the lifecycle-event surface promised a typed-event system that was never built, in three layers.
-1164/+235.Deleted
kernel/plugin-lifecycle-events.zod.ts— 346 lines of event payload schemas + a 21-name enum. Zero consumers for every export (verified per-name repo-wide, including apps/examples). The enum was wrong in both directions: 17 names nothing fires, and 10 real events missing.Rewrote
contracts/plugin-lifecycle-events.ts—IPluginLifecycleEventskept the same 17 dead names next to 5 real ones, plus anITypedEventEmitternothing implements. It is now the registry of the 14 events with a real emitter, each payload as observed at its fire site:kernel:ready/kernel:bootstrapped/kernel:listening/kernel:shutdownapp:seededmetadata:reloadedmetadatanow optional, matching the documented contractexternal.schema.driftai:routesauth:configuremcp:ready,automation:ready,analytics:ready,external-datasource:ready,datasource-admin:ready{service}:readyconvention familyThe load-bearing
kernel:bootstrapped/app:seededdoc blocks (#2996 ordering caveats) are preserved verbatim.Enforcement so it cannot rot again
LifecycleEventNamenow typesPluginContext.hook/triggerin@objectstack/coreasLifecycleEventName | (string & {})— known names autocomplete; custom cross-plugin names stay legal (the bus is open by design; zero breakage).Exclude-to-neverboth directions + runtime list) between the interface keys and the fire-site inventory, each name annotated with its emitter.Guard-rail edits made deliberately in this PR
json-schema.manifest.json−13 keys andauthorable-surface.json−33 lines: both guards' sanctioned same-PR deliberate-removal path. Note for reviewers: these keys were never authorable — they described runtime event payload records no config author can write, so the silent-strip class the authorable-surface ratchet guards against is vacuous for them. If you'd rather see the fullretiredKey()+ D2 conversion treatment anyway, say so and I'll add it.SKILL_MAPentry dropped (the concept's skill coverage is the hand-writtenreferences/plugin-hooks.md, which already documents exactly this inventory and corroborated two events my first grep pass missed).gen:docs/gen:skill-refs;PROTOCOL_MAP.mdrow repointed at the contracts registry.Verification
tsc --noEmitcleanDeliberately not done
onEnabledispatch inObjectQLEngine.use()and the unusedPluginSchemaremain the other 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 leftovers — separate surfaces, separate PRs.Generated by Claude Code