fix(objectql)!: retire the dead ObjectQLEngine.use() plugin path - #4242
Merged
Conversation
The engine's own plugin loader — registerApp + an onEnable dispatch over an ObjectQLHostContext — has zero callers repo-wide: kernel plugins go through kernel.use() → init/start, and the manifest path routes through registerApp() directly. The onEnable dispatch is the engine-level twin of the #4212 disease (a lifecycle entry point that reads as a contract and never runs); the app-bundle onEnable module export is a different, real contract and is unchanged. Removed use(), the ObjectQLHostContext type (constructed only inside the dead method; un-exported from both barrels), and the write-only hostContext field — the constructor keeps its signature and its logger extraction, so new ObjectQL({ logger }) and ObjectQLPlugin's hostContext option are unaffected. Verified: objectql 1271 tests green (82 files) after a full turbo build (71 packages) with the change in place; the 42 pre-existing local failures reproduced identically on pristine main with the change stashed and disappeared after rebuilding stale sibling dists — unrelated to this diff. 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
|
github-actions
Bot
added
size/s
documentation
Contributor
📓 Docs Drift CheckThis PR changes 1 package(s): 14 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 19:44
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 was referenced Jul 31, 2026
os-zhuang
pushed a commit
that referenced
this pull request
Jul 31, 2026
Ran the repo's docs-accuracy-audit workflow scoped to the drift-check advisory from #4242 (14 docs) plus 4 the retired-surface grep implicated. 158 evidence-backed fixes across 18 docs, each cited to file:line. The largest classes: - kernel/cluster.mdx (22): a documented `eventBus.emit(...)` that exists nowhere in packages/, a `ctx.cluster` PluginContext property that does not exist, `defineStack({ cluster })` that stack.zod.ts silently strips, `postgres`/`nats` listed as shipped drivers when neither package exists, `REDIS_URL` for the real `OS_CLUSTER_DRIVER`, and an at-least-once delivery promise no shipped driver provides. - protocol/kernel/plugin-spec.mdx (20): `plugin.manifest.ts` as the manifest filename — grep-empty across packages/, apps/ and examples/; the real one is `objectstack.plugin.json`. Plus `context.plugins.isInstalled()` (no such member), compound semver ranges (`'>=1.0.0 <2.0.0'`) that make the resolver throw, and init ordering described as registration order when bootstrap() runs a dependency topological sort. - data-modeling/external-datasources.mdx: `credentialsRef: 'secret:…'` — the shipped binder only resolves `sys_secret:<id>`, so the sample as written fails closed at connect. - deployment/migration-from-objectql.mdx: a `^3.1.0` pin that can never resolve to the current 16.1.0 line. VERIFICATION STATUS — 7 of 18 docs carry an adversarial-verifier pass; the other 11 do not (the run hit the session limit mid-phase). The verifier earned its keep on the 7 it reached: 8 repairs, including a fabricated `enforceNetworkAccess` (real: `enforceNetworkRequest`, plugin-permission-enforcer.ts:212) and an over-broad retirement claim that would have contradicted the live app-bundle `onEnable`. The remaining 11 are committed unverified and MUST NOT ship until their verifier pass runs — the PR stays draft until then. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh
os-zhuang
pushed a commit
that referenced
this pull request
Jul 31, 2026
Ran the repo's docs-accuracy-audit workflow scoped to the drift-check advisory from #4242 (14 docs) plus 4 the retired-surface grep implicated. 158 evidence-backed fixes across 18 docs, each cited to file:line. The largest classes: - kernel/cluster.mdx (22): a documented `eventBus.emit(...)` that exists nowhere in packages/, a `ctx.cluster` PluginContext property that does not exist, `defineStack({ cluster })` that stack.zod.ts silently strips, `postgres`/`nats` listed as shipped drivers when neither package exists, `REDIS_URL` for the real `OS_CLUSTER_DRIVER`, and an at-least-once delivery promise no shipped driver provides. - protocol/kernel/plugin-spec.mdx (20): `plugin.manifest.ts` as the manifest filename — grep-empty across packages/, apps/ and examples/; the real one is `objectstack.plugin.json`. Plus `context.plugins.isInstalled()` (no such member), compound semver ranges (`'>=1.0.0 <2.0.0'`) that make the resolver throw, and init ordering described as registration order when bootstrap() runs a dependency topological sort. - data-modeling/external-datasources.mdx: `credentialsRef: 'secret:…'` — the shipped binder only resolves `sys_secret:<id>`, so the sample as written fails closed at connect. - deployment/migration-from-objectql.mdx: a `^3.1.0` pin that can never resolve to the current 16.1.0 line. VERIFICATION STATUS — 7 of 18 docs carry an adversarial-verifier pass; the other 11 do not (the run hit the session limit mid-phase). The verifier earned its keep on the 7 it reached: 8 repairs, including a fabricated `enforceNetworkAccess` (real: `enforceNetworkRequest`, plugin-permission-enforcer.ts:212) and an over-broad retirement claim that would have contradicted the live app-bundle `onEnable`. The remaining 11 are committed unverified and MUST NOT ship until their verifier pass runs — the PR stays draft until then. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh
os-zhuang
added a commit
that referenced
this pull request
Jul 31, 2026
…#4312) * docs: checkpoint the docs-accuracy audit pass over 18 hand-written docs WIP checkpoint — the adversarial verification pass is still running and will add repairs on top of this commit. Recorded now so the work survives. An audit agent read each doc, located the backing implementation under packages/, and applied evidence-backed fixes in place (158 across 18 docs). Every fix carries file:line evidence in the run's fix log. The heaviest: - kernel/cluster.mdx (22): documented an `eventBus.emit(...)` API that exists nowhere in the codebase, a `ctx.cluster` PluginContext property that does not exist, `defineStack({ cluster })` that stack.zod.ts silently strips, fabricated `postgres`/`nats` drivers, the wrong env var (real one is OS_CLUSTER_DRIVER), and an at-least-once delivery promise neither shipped driver provides. - protocol/kernel/plugin-spec.mdx (20): `plugin.manifest.ts` as the manifest filename — grep-empty across the implementation, the real one is objectstack.plugin.json; `context.plugins.isInstalled()` which does not exist; compound semver ranges ('>=1.0.0 <2.0.0') that make the resolver's anchored parse throw; init described as registration order when bootstrap() runs the dependency-topological order. - data-modeling/external-datasources.mdx (3): credentialsRef samples used a `secret:` prefix the shipped SecretBinder cannot dereference (`sys_secret:`), so copying the sample fails closed at connect. - deployment/migration-from-objectql.mdx (2): a `^3.1.0` pin that can never resolve to the current 16.1.0 line. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh * docs: implementation-accuracy audit of the #4212-family affected docs Ran the repo's docs-accuracy-audit workflow scoped to the drift-check advisory from #4242 (14 docs) plus 4 the retired-surface grep implicated. 158 evidence-backed fixes across 18 docs, each cited to file:line. The largest classes: - kernel/cluster.mdx (22): a documented `eventBus.emit(...)` that exists nowhere in packages/, a `ctx.cluster` PluginContext property that does not exist, `defineStack({ cluster })` that stack.zod.ts silently strips, `postgres`/`nats` listed as shipped drivers when neither package exists, `REDIS_URL` for the real `OS_CLUSTER_DRIVER`, and an at-least-once delivery promise no shipped driver provides. - protocol/kernel/plugin-spec.mdx (20): `plugin.manifest.ts` as the manifest filename — grep-empty across packages/, apps/ and examples/; the real one is `objectstack.plugin.json`. Plus `context.plugins.isInstalled()` (no such member), compound semver ranges (`'>=1.0.0 <2.0.0'`) that make the resolver throw, and init ordering described as registration order when bootstrap() runs a dependency topological sort. - data-modeling/external-datasources.mdx: `credentialsRef: 'secret:…'` — the shipped binder only resolves `sys_secret:<id>`, so the sample as written fails closed at connect. - deployment/migration-from-objectql.mdx: a `^3.1.0` pin that can never resolve to the current 16.1.0 line. VERIFICATION STATUS — 7 of 18 docs carry an adversarial-verifier pass; the other 11 do not (the run hit the session limit mid-phase). The verifier earned its keep on the 7 it reached: 8 repairs, including a fabricated `enforceNetworkAccess` (real: `enforceNetworkRequest`, plugin-permission-enforcer.ts:212) and an over-broad retirement claim that would have contradicted the live app-bundle `onEnable`. The remaining 11 are committed unverified and MUST NOT ship until their verifier pass runs — the PR stays draft until then. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh * chore(lint): ratchet the role-word baseline down after the docs audit The audit pass removed a "role" occurrence from kernel/events.mdx (now clean) and one from kernel/services-checklist.mdx (4 → 3). check-role-word is a ratchet, so an improvement fails the gate until the baseline records it. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh * docs: apply adversarial-verifier repairs (metadata-lifecycle, protocol/kernel/index) Verifier pass for two more of the 18 audited docs completed: 27 of the audit's fixes confirmed against code, 5 repaired. Checkpoint commit — the remaining verifier passes are still running and will land separately. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01HrRNgrWaRtggzmrHpbomyh * docs: apply the remaining adversarial-verifier repairs Completes the verifier phase for all 18 audited docs (36/36 agents, 0 errors). Across the run: 158 audit fixes, 29 verifier repairs, 91 residual items recorded rather than guessed at. The repairs are why this phase exists — the audit agents were confident and sometimes wrong. Representative catches: - `enforceNetworkAccess` invented for the real `enforceNetworkRequest` (plugin-permission-enforcer.ts:212). - A retirement callout widened to "None of it existed" over a list containing `onEnable`, which would have contradicted the live app-bundle contract AppPlugin.start() dispatches (app-plugin.ts:574). - `cluster.lock.withLock(key, fn)` attributed to service-job's cron scheduler, which actually does `lock.acquire(...)` + manual release (cron-job-adapter.ts:139-147). - A "(planned)" marker dropped from the webhook dispatcher, which filed an already-shipping partitioned dispatcher under "Not started". Gates: check-doc-authoring 215 files clean; check-role-word OK (44 baselined); docs build compiles all pages. 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 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.
What
The last #4212 leftover with a clear verdict:
ObjectQLEngine.use(manifestPart, runtimePart)— the engine's own plugin loader — has zero callers repo-wide (src, apps, examples, tests; not in the specdata-enginecontract; no dynamic dispatch). Kernel plugins go throughkernel.use()→init/start; the manifest path routes throughregisterApp()directly (ObjectQLPlugin and the manifest service already do).Its
onEnabledispatch was the engine-level twin of the #4212 disease — a lifecycle entry point that reads as a contract and never runs. The app-bundleonEnablemodule export is a different, real contract (dispatched by AppPlugin at boot, pinned inSTACK_RUNTIME_MEMBERS) and is unchanged.Removed:
ObjectQLEngine.use()ObjectQLHostContext(un-exported from both barrels; it was constructed only inside the dead method)hostContextfield — the constructor signature and itsloggerextraction stay, sonew ObjectQL({ logger })andObjectQLPlugin'shostContextoption are unaffectedChangeset:
@objectstack/objectql: major(public method + type export removed), FROM → TO included.Deliberately not done
PluginSchemastays. refactor(spec)!: retire the plugin lifecycle-hook family the kernel never implemented (#4212) #4233 (merged this week) explicitly kept it as the protocol's plain plugin descriptor and started publishing thekernel/PluginJSON schema. The kernel's loader validates structurally rather than parsing through it — if that gap should close (parse inloadPlugin()) or the schema should go, that's a fresh maintainer call, not something to re-litigate as a leftover. This closes out the 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 follow-up list either way.Verification
objectuigrepped forObjectQLHostContext: zero hitsdist/s — environmental, unrelated to this diffGenerated by Claude Code