feat(runtime): give a declarative job's handler data reach so scheduled work can read and write records

[claude]

Closes#14094

defineJob is the platform's only metadata shape for scheduled work. Its handler resolves out of defineStack({ functions }), and AppPlugin invoked it with { jobId, data, bundle } — no engine, no service registry, no logger, no session. The job registered, appeared in the metadata registry and the admin UI, was scheduled, ran on time, and did nothing. objectstack validate passed, and the only related boot warning covers a missing handler, not a handler with no reach.

What changed

packages/runtime/src/app-plugin.ts — the context the declarative-job wrapper builds now also carries:

• ql — the live ObjectQL engine, the same handle defineStack({ onEnable }) receives as ctx.ql;
• logger — the plugin Logger, so a job's diagnostics land in the platform's log stream instead of console.

JobHandlerContext (new, packages/runtime/src/job-handler-context.ts, re-exported from @objectstack/runtime) is the type a handler can annotate against. content/docs/automation/jobs.mdx documents the context and warns against the module-scope route.

A job has no graph — this does not reopen the flow-script-node contract

FlowFunctionContext carries no engine either, and that is coherent for a flow function: the flow graph does the I/O around it — a get_record node before, a create_record node after — so the function stays a pure value-returner, and #4354's per-run write metrics depend on exactly that. Nothing here changes what a script node receives.

A job has no graph. There is no node before it and none after. So the same emptiness that is a clean contract for a script node leaves a job unable to do the one thing jobs exist for. That asymmetry is the whole argument; a reader who collapses the two cases will read this as an inconsistency rather than as a gap.

Why the module-scope escape was not documented instead

Closing over a client bound from onEnable is available to a flow function and does not survive the shipped deployment path for a job:

• objectstack build emits functions into a sibling runtime module whose only exports are { functions, meta };
• the artifact JSON carries no onEnable;
• mergeRuntimeModule (packages/runtime/src/load-artifact-bundle.ts) merges only functions.

So on an artifact-served boot the binding is never made, the module-scope slot stays empty, and the job runs against nothing — silently. Documenting that escape would make the failure harder to find, not easier. The regression suite therefore proves the write on both boot paths, and the artifact one goes through the real loadArtifactBundle, asserting on the way that the loaded bundle carries no onEnable.

Additive — IJobService is untouched

JobHandler is declared as taking { jobId: string; data?: unknown } and resolving void or a JobRunOutcome. The function AppPlugin hands to IJobService.schedule is a wrapper that satisfies it exactly; the new members are added inside that wrapper. Same shape as #6617's JobRunOutcome widening. No existing handler adapts, and no IJobService implementation grows a member. Pinned by two tests: a handler written against the pre-change context runs unchanged, and a third-party IJobService typed only at the contract schedules and drives the job to a real record write.

Measurements the dispatch asked for

Zone 2.3 — the card's probe re-run on current main. Reproduced exactly, at origin/main66ecc50a, on a real booted engine driving the real CronJobAdapter:

RUNS: 2
JOB CONTEXT KEYS: bundle, data, jobId
bundle -> object
data -> undefined
jobId -> string

Identical to the card's reading against published @objectstack/* 17.2.0.

Zone 2.1 — is the narrow route reachable without packages/spec? YES. Clause-②: no.packages/spec is not touched. Two readings carry it: the boundary type JobHandler constrains only the wrapper AppPlugin passes to IJobService.schedule, which is unchanged; and the bundle callable it invokes is typed as taking any and returning any (collectBundleFunctions), authored through functions, whose schema member is a bare z.function() — no context type constrains it. The producer of the extra members is AppPlugin, so the runtime is where the type belongs.

Zone 2.2 — ql versus the kernel's getService: settled by measurement, not by scope. The repo ships exactly onedefineJob declaration (examples/app-showcase, showcase_health_sweep → sweepProjectHealth). It needs find + update and a logger, and nothing else — it reaches them today through a module-scope let host filled by bindShowcaseJobRuntime from onEnable, which is the escape above. The card's own reporting app takes an engine as an explicit argument. Zero measured pull for automation, email or queue from any job. getService would put the whole service registry on the job context permanently — a materially larger surface to support forever, and the place an AI-authored metadata app would reach for a service it has no declared relationship with. Adding it later is additive by exactly the argument above, so choosing the narrow member now forecloses nothing.

Zone 2.5 — no change to what a job sees on error. The wrapper's throw/reject path is untouched; retry and failure semantics are exactly as before.

Zone 2.4 — no collision with #14143.packages/runtime/src/action-execution.ts is not in the diff.

The test backend

The suite boots on sqlite :memory:, the backend #5704 migrated this project's test rigs to. It needs a store; nothing in it is about any one driver. The card's own reproduction used @objectstack/driver-memory because that is what the reporter had in hand — a manual probe, never a constraint on the rig — and reaching for it here made this an unledgered arrival that pnpm check:driver-memory-census refused (#6664). Migrated rather than ledgered: the census stays at 2 ruled consumers and scripts/driver-memory-census.ledger.json is untouched by this PR.

Provisioning sweep_note and nothing else makes the engine's single-tenant probe read an absent sys_organization, so the expected refusal is withheld and asserted through expected-read-refusal-noise.ts (#10629) rather than muted. That probe is memoised behind the first data operation, so the three context-shape tests that never touch the store declare it with harness({ touchesStore: false }) — the API's own silentChannels(required) narrowing. The withholding stays unconditional; only the must-have-fired set narrows.

Does content/docs/automation/jobs.mdx still tell the truth?

For everything this PR touches, yes — and the page is now pinned rather than merely asserted: the context table (jobId / data / bundle / ql / logger) is held exactly by the suite's key-set assertion, data is checked on both the scheduled and the manual-trigger path, and the Callout's claim about the artifact boot is the artifact test.

One row on that page is not true, and this PR neither introduced nor fixes it: under What the handler returns, "resolves { outcome: 'degraded', reason? } is recorded as degraded". Measured on the declarative path — schedule through a recording IJobService, capture the wrapper, call it:

HANDLER RESOLVED: {"outcome":"degraded","reason":"STORE_UNAVAILABLE"}
WRAPPER RESOLVED: undefined

The outcome is dropped before any adapter sees it. That is filed as #14256 with the measurement; the honest repair is its one-expression code fix, not a caveat in the page, which is why the page was left alone.

Verification

Union run after the final commit, at 72c20362.

• pnpm --filter @objectstack/runtime test — 206 files, 3048 tests, all passed (the whole package, not a subset), both before and after the backend migration.
• pnpm --filter @objectstack/service-job test — 9 files, 94 tests passed (the IJobService side, untouched and confirmed so).
• pnpm --filter @objectstack/runtime typecheck — clean. ⚠️ That config excludes **/*.test.ts, so it says nothing about the new test file; measured separately with the exclusion lifted (tsc --noEmit, exit 0, --listFiles confirming the file is in the program — 1 hit there versus 0 under the package config).
• New suite packages/runtime/src/app-plugin.job-data-reach.test.ts: 8 tests, including two firing positive controls — the same shipped callable invoked with the pre-change context rejects and the store is unchanged, so neither passing write assertion can be vacuous.
• pnpm check:driver-memory-census — reproduced red on the first head, green at 72c20362, ledger untouched.
• 53 of the 57 gate families derived by scripts/pm/dispatch-gates.mjs ran green, ratchets re-run at 72c20362. Plus all 38 families in that derivation's undetermined bucket — 36 green, 2 refusing on an unbuilt sibling package. That bucket is where the census gate lives: it declares no path population, so no path derivation can name it for any card, and running only the derived list is what let this one reach CI.

Not measured locally, each refusing on a stated prerequisite rather than failing: check:type-check-debt and check:dual-build-cjs-loads (exit 3 — both need the whole workspace built), check-test-completeness (exit 3 — grades a saved turbo log CI tees), scripts/pm/check-half-states.mjs (network-bound PM patrol), and, from the undetermined bucket, check:app-nav-i18n and @objectstack/client's check:exported-any-returns (both refuse rather than compute a false green over an unbuilt package). CI runs all of them.

Filed, not fixed

• filed as AppPlugin's declarative-job wrapper discards the handler's JobRunOutcome, so defineJob cannot report a degraded run #14256 — the same wrapper discards the handler's JobRunOutcome, so a declarative job that resolves { outcome: 'degraded' } is recorded as success. Adjacent to this seam but a different defect class (outbound, not inbound), so it is not folded in here. The measurement above is on the card.
• filed as app-showcase's nightly health sweep reaches its engine through a module-scope global, so it silently does nothing on an artifact-served boot #14257 — examples/app-showcase's nightly sweep still reaches its engine through the module-scope global, so it silently does nothing on an artifact-served boot. Now migratable to the context member this PR adds.

Independent of #14095, exactly as the card says: that one is about recognising a uniqueness violation once you can reach the store; this one is about reaching it at all.

Authored by Claude Code, session session_01Q5WBDtaUnoz5XuJ6jk8pQ5 (https://claude.ai/code/session_01Q5WBDtaUnoz5XuJ6jk8pQ5).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime, touching 3 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/runtime/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/jobs.mdx(via JobHandlerContext (symbol, a top-level interface), jobId (symbol, a field of interface JobHandlerContext))
• content/docs/data-modeling/import-mappings.mdx(via jobId (symbol, a field of interface JobHandlerContext))
• content/docs/protocol/objectql/state-machine.mdx(via jobId (symbol, a field of interface JobHandlerContext))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/runtime/src/index.ts) — pages documenting those are invisible to this run
• 1 cross-cutting symbol(s) contributed no route anchor: jobId (6 routes)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 24 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 — the merge of head 72c20362c0663aa27bbfb0cf834cfa3ce144528e into base 035951faf99c42c258d470102da7346f309f7346, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 && git checkout 45e39eb79396d9b4150fc3c4f332e9dd601ecb90
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 035951faf99c42c258d470102da7346f309f7346 72c20362c0663aa27bbfb0cf834cfa3ce144528e && git checkout -B drift-repro 035951faf99c42c258d470102da7346f309f7346 && git merge --no-ff 72c20362c0663aa27bbfb0cf834cfa3ce144528e
node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 035951faf99c42c258d470102da7346f309f7346 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Closes#14094

defineJob is the platform's only metadata shape for scheduled work. Its handler resolves out of defineStack({ functions }), and AppPlugin invoked it with { jobId, data, bundle } — no engine, no service registry, no logger, no session. The job registered, appeared in the metadata registry and the admin UI, was scheduled, ran on time, and did nothing. objectstack validate passed, and the only related boot warning covers a missing handler, not a handler with no reach.

What changed

packages/runtime/src/app-plugin.ts — the context the declarative-job wrapper builds now also carries:

• ql — the live ObjectQL engine, the same handle defineStack({ onEnable }) receives as ctx.ql;
• logger — the plugin Logger, so a job's diagnostics land in the platform's log stream instead of console.

JobHandlerContext (new, packages/runtime/src/job-handler-context.ts, re-exported from @objectstack/runtime) is the type a handler can annotate against. content/docs/automation/jobs.mdx documents the context and warns against the module-scope route.

A job has no graph — this does not reopen the flow-script-node contract

FlowFunctionContext carries no engine either, and that is coherent for a flow function: the flow graph does the I/O around it — a get_record node before, a create_record node after — so the function stays a pure value-returner, and #4354's per-run write metrics depend on exactly that. Nothing here changes what a script node receives.

A job has no graph. There is no node before it and none after. So the same emptiness that is a clean contract for a script node leaves a job unable to do the one thing jobs exist for. That asymmetry is the whole argument; a reader who collapses the two cases will read this as an inconsistency rather than as a gap.

Why the module-scope escape was not documented instead

Closing over a client bound from onEnable is available to a flow function and does not survive the shipped deployment path for a job:

• objectstack build emits functions into a sibling runtime module whose only exports are { functions, meta };
• the artifact JSON carries no onEnable;
• mergeRuntimeModule (packages/runtime/src/load-artifact-bundle.ts) merges only functions.

So on an artifact-served boot the binding is never made, the module-scope slot stays empty, and the job runs against nothing — silently. Documenting that escape would make the failure harder to find, not easier. The regression suite therefore proves the write on both boot paths, and the artifact one goes through the real loadArtifactBundle, asserting on the way that the loaded bundle carries no onEnable.

Additive — IJobService is untouched

JobHandler is declared as taking { jobId: string; data?: unknown } and resolving void or a JobRunOutcome. The function AppPlugin hands to IJobService.schedule is a wrapper that satisfies it exactly; the new members are added inside that wrapper. Same shape as #6617's JobRunOutcome widening. No existing handler adapts, and no IJobService implementation grows a member. Pinned by two tests: a handler written against the pre-change context runs unchanged, and a third-party IJobService typed only at the contract schedules and drives the job to a real record write.

Measurements the dispatch asked for

Zone 2.3 — the card's probe re-run on current main. Reproduced exactly, at origin/main66ecc50a, on a real booted engine driving the real CronJobAdapter:

RUNS: 2
JOB CONTEXT KEYS: bundle, data, jobId
bundle -> object
data -> undefined
jobId -> string

Identical to the card's reading against published @objectstack/* 17.2.0.

Zone 2.1 — is the narrow route reachable without packages/spec? YES. Clause-②: no.packages/spec is not touched. Two readings carry it: the boundary type JobHandler constrains only the wrapper AppPlugin passes to IJobService.schedule, which is unchanged; and the bundle callable it invokes is typed as taking any and returning any (collectBundleFunctions), authored through functions, whose schema member is a bare z.function() — no context type constrains it. The producer of the extra members is AppPlugin, so the runtime is where the type belongs.

Zone 2.2 — ql versus the kernel's getService: settled by measurement, not by scope. The repo ships exactly onedefineJob declaration (examples/app-showcase, showcase_health_sweep → sweepProjectHealth). It needs find + update and a logger, and nothing else — it reaches them today through a module-scope let host filled by bindShowcaseJobRuntime from onEnable, which is the escape above. The card's own reporting app takes an engine as an explicit argument. Zero measured pull for automation, email or queue from any job. getService would put the whole service registry on the job context permanently — a materially larger surface to support forever, and the place an AI-authored metadata app would reach for a service it has no declared relationship with. Adding it later is additive by exactly the argument above, so choosing the narrow member now forecloses nothing.

Zone 2.5 — no change to what a job sees on error. The wrapper's throw/reject path is untouched; retry and failure semantics are exactly as before.

Zone 2.4 — no collision with #14143.packages/runtime/src/action-execution.ts is not in the diff.

The test backend

The suite boots on sqlite :memory:, the backend #5704 migrated this project's test rigs to. It needs a store; nothing in it is about any one driver. The card's own reproduction used @objectstack/driver-memory because that is what the reporter had in hand — a manual probe, never a constraint on the rig — and reaching for it here made this an unledgered arrival that pnpm check:driver-memory-census refused (#6664). Migrated rather than ledgered: the census stays at 2 ruled consumers and scripts/driver-memory-census.ledger.json is untouched by this PR.

Provisioning sweep_note and nothing else makes the engine's single-tenant probe read an absent sys_organization, so the expected refusal is withheld and asserted through expected-read-refusal-noise.ts (#10629) rather than muted. That probe is memoised behind the first data operation, so the three context-shape tests that never touch the store declare it with harness({ touchesStore: false }) — the API's own silentChannels(required) narrowing. The withholding stays unconditional; only the must-have-fired set narrows.

Does content/docs/automation/jobs.mdx still tell the truth?

For everything this PR touches, yes — and the page is now pinned rather than merely asserted: the context table (jobId / data / bundle / ql / logger) is held exactly by the suite's key-set assertion, data is checked on both the scheduled and the manual-trigger path, and the Callout's claim about the artifact boot is the artifact test.

One row on that page is not true, and this PR neither introduced nor fixes it: under What the handler returns, "resolves { outcome: 'degraded', reason? } is recorded as degraded". Measured on the declarative path — schedule through a recording IJobService, capture the wrapper, call it:

HANDLER RESOLVED: {"outcome":"degraded","reason":"STORE_UNAVAILABLE"}
WRAPPER RESOLVED: undefined

The outcome is dropped before any adapter sees it. That is filed as #14256 with the measurement; the honest repair is its one-expression code fix, not a caveat in the page, which is why the page was left alone.

Verification

Union run after the final commit, at 72c20362.

• pnpm --filter @objectstack/runtime test — 206 files, 3048 tests, all passed (the whole package, not a subset), both before and after the backend migration.
• pnpm --filter @objectstack/service-job test — 9 files, 94 tests passed (the IJobService side, untouched and confirmed so).
• pnpm --filter @objectstack/runtime typecheck — clean. ⚠️ That config excludes **/*.test.ts, so it says nothing about the new test file; measured separately with the exclusion lifted (tsc --noEmit, exit 0, --listFiles confirming the file is in the program — 1 hit there versus 0 under the package config).
• New suite packages/runtime/src/app-plugin.job-data-reach.test.ts: 8 tests, including two firing positive controls — the same shipped callable invoked with the pre-change context rejects and the store is unchanged, so neither passing write assertion can be vacuous.
• pnpm check:driver-memory-census — reproduced red on the first head, green at 72c20362, ledger untouched.
• 53 of the 57 gate families derived by scripts/pm/dispatch-gates.mjs ran green, ratchets re-run at 72c20362. Plus all 38 families in that derivation's undetermined bucket — 36 green, 2 refusing on an unbuilt sibling package. That bucket is where the census gate lives: it declares no path population, so no path derivation can name it for any card, and running only the derived list is what let this one reach CI.

Not measured locally, each refusing on a stated prerequisite rather than failing: check:type-check-debt and check:dual-build-cjs-loads (exit 3 — both need the whole workspace built), check-test-completeness (exit 3 — grades a saved turbo log CI tees), scripts/pm/check-half-states.mjs (network-bound PM patrol), and, from the undetermined bucket, check:app-nav-i18n and @objectstack/client's check:exported-any-returns (both refuse rather than compute a false green over an unbuilt package). CI runs all of them.

Filed, not fixed

• filed as AppPlugin's declarative-job wrapper discards the handler's JobRunOutcome, so defineJob cannot report a degraded run #14256 — the same wrapper discards the handler's JobRunOutcome, so a declarative job that resolves { outcome: 'degraded' } is recorded as success. Adjacent to this seam but a different defect class (outbound, not inbound), so it is not folded in here. The measurement above is on the card.
• filed as app-showcase's nightly health sweep reaches its engine through a module-scope global, so it silently does nothing on an artifact-served boot #14257 — examples/app-showcase's nightly sweep still reaches its engine through the module-scope global, so it silently does nothing on an artifact-served boot. Now migratable to the context member this PR adds.

Independent of #14095, exactly as the card says: that one is about recognising a uniqueness violation once you can reach the store; this one is about reaching it at all.

Authored by Claude Code, session session_01Q5WBDtaUnoz5XuJ6jk8pQ5 (https://claude.ai/code/session_01Q5WBDtaUnoz5XuJ6jk8pQ5).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime, touching 3 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/runtime/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/jobs.mdx(via JobHandlerContext (symbol, a top-level interface), jobId (symbol, a field of interface JobHandlerContext))
• content/docs/data-modeling/import-mappings.mdx(via jobId (symbol, a field of interface JobHandlerContext))
• content/docs/protocol/objectql/state-machine.mdx(via jobId (symbol, a field of interface JobHandlerContext))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/runtime/src/index.ts) — pages documenting those are invisible to this run
• 1 cross-cutting symbol(s) contributed no route anchor: jobId (6 routes)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 24 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 — the merge of head 72c20362c0663aa27bbfb0cf834cfa3ce144528e into base 035951faf99c42c258d470102da7346f309f7346, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 && git checkout 45e39eb79396d9b4150fc3c4f332e9dd601ecb90
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 035951faf99c42c258d470102da7346f309f7346 72c20362c0663aa27bbfb0cf834cfa3ce144528e && git checkout -B drift-repro 035951faf99c42c258d470102da7346f309f7346 && git merge --no-ff 72c20362c0663aa27bbfb0cf834cfa3ce144528e
node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 035951faf99c42c258d470102da7346f309f7346 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Closes#14094

defineJob is the platform's only metadata shape for scheduled work. Its handler resolves out of defineStack({ functions }), and AppPlugin invoked it with { jobId, data, bundle } — no engine, no service registry, no logger, no session. The job registered, appeared in the metadata registry and the admin UI, was scheduled, ran on time, and did nothing. objectstack validate passed, and the only related boot warning covers a missing handler, not a handler with no reach.

What changed

packages/runtime/src/app-plugin.ts — the context the declarative-job wrapper builds now also carries:

• ql — the live ObjectQL engine, the same handle defineStack({ onEnable }) receives as ctx.ql;
• logger — the plugin Logger, so a job's diagnostics land in the platform's log stream instead of console.

JobHandlerContext (new, packages/runtime/src/job-handler-context.ts, re-exported from @objectstack/runtime) is the type a handler can annotate against. content/docs/automation/jobs.mdx documents the context and warns against the module-scope route.

A job has no graph — this does not reopen the flow-script-node contract

FlowFunctionContext carries no engine either, and that is coherent for a flow function: the flow graph does the I/O around it — a get_record node before, a create_record node after — so the function stays a pure value-returner, and #4354's per-run write metrics depend on exactly that. Nothing here changes what a script node receives.

A job has no graph. There is no node before it and none after. So the same emptiness that is a clean contract for a script node leaves a job unable to do the one thing jobs exist for. That asymmetry is the whole argument; a reader who collapses the two cases will read this as an inconsistency rather than as a gap.

Why the module-scope escape was not documented instead

Closing over a client bound from onEnable is available to a flow function and does not survive the shipped deployment path for a job:

• objectstack build emits functions into a sibling runtime module whose only exports are { functions, meta };
• the artifact JSON carries no onEnable;
• mergeRuntimeModule (packages/runtime/src/load-artifact-bundle.ts) merges only functions.

So on an artifact-served boot the binding is never made, the module-scope slot stays empty, and the job runs against nothing — silently. Documenting that escape would make the failure harder to find, not easier. The regression suite therefore proves the write on both boot paths, and the artifact one goes through the real loadArtifactBundle, asserting on the way that the loaded bundle carries no onEnable.

Additive — IJobService is untouched

JobHandler is declared as taking { jobId: string; data?: unknown } and resolving void or a JobRunOutcome. The function AppPlugin hands to IJobService.schedule is a wrapper that satisfies it exactly; the new members are added inside that wrapper. Same shape as #6617's JobRunOutcome widening. No existing handler adapts, and no IJobService implementation grows a member. Pinned by two tests: a handler written against the pre-change context runs unchanged, and a third-party IJobService typed only at the contract schedules and drives the job to a real record write.

Measurements the dispatch asked for

Zone 2.3 — the card's probe re-run on current main. Reproduced exactly, at origin/main66ecc50a, on a real booted engine driving the real CronJobAdapter:

RUNS: 2
JOB CONTEXT KEYS: bundle, data, jobId
bundle -> object
data -> undefined
jobId -> string

Identical to the card's reading against published @objectstack/* 17.2.0.

Zone 2.1 — is the narrow route reachable without packages/spec? YES. Clause-②: no.packages/spec is not touched. Two readings carry it: the boundary type JobHandler constrains only the wrapper AppPlugin passes to IJobService.schedule, which is unchanged; and the bundle callable it invokes is typed as taking any and returning any (collectBundleFunctions), authored through functions, whose schema member is a bare z.function() — no context type constrains it. The producer of the extra members is AppPlugin, so the runtime is where the type belongs.

Zone 2.2 — ql versus the kernel's getService: settled by measurement, not by scope. The repo ships exactly onedefineJob declaration (examples/app-showcase, showcase_health_sweep → sweepProjectHealth). It needs find + update and a logger, and nothing else — it reaches them today through a module-scope let host filled by bindShowcaseJobRuntime from onEnable, which is the escape above. The card's own reporting app takes an engine as an explicit argument. Zero measured pull for automation, email or queue from any job. getService would put the whole service registry on the job context permanently — a materially larger surface to support forever, and the place an AI-authored metadata app would reach for a service it has no declared relationship with. Adding it later is additive by exactly the argument above, so choosing the narrow member now forecloses nothing.

Zone 2.5 — no change to what a job sees on error. The wrapper's throw/reject path is untouched; retry and failure semantics are exactly as before.

Zone 2.4 — no collision with #14143.packages/runtime/src/action-execution.ts is not in the diff.

The test backend

The suite boots on sqlite :memory:, the backend #5704 migrated this project's test rigs to. It needs a store; nothing in it is about any one driver. The card's own reproduction used @objectstack/driver-memory because that is what the reporter had in hand — a manual probe, never a constraint on the rig — and reaching for it here made this an unledgered arrival that pnpm check:driver-memory-census refused (#6664). Migrated rather than ledgered: the census stays at 2 ruled consumers and scripts/driver-memory-census.ledger.json is untouched by this PR.

Provisioning sweep_note and nothing else makes the engine's single-tenant probe read an absent sys_organization, so the expected refusal is withheld and asserted through expected-read-refusal-noise.ts (#10629) rather than muted. That probe is memoised behind the first data operation, so the three context-shape tests that never touch the store declare it with harness({ touchesStore: false }) — the API's own silentChannels(required) narrowing. The withholding stays unconditional; only the must-have-fired set narrows.

Does content/docs/automation/jobs.mdx still tell the truth?

For everything this PR touches, yes — and the page is now pinned rather than merely asserted: the context table (jobId / data / bundle / ql / logger) is held exactly by the suite's key-set assertion, data is checked on both the scheduled and the manual-trigger path, and the Callout's claim about the artifact boot is the artifact test.

One row on that page is not true, and this PR neither introduced nor fixes it: under What the handler returns, "resolves { outcome: 'degraded', reason? } is recorded as degraded". Measured on the declarative path — schedule through a recording IJobService, capture the wrapper, call it:

HANDLER RESOLVED: {"outcome":"degraded","reason":"STORE_UNAVAILABLE"}
WRAPPER RESOLVED: undefined

The outcome is dropped before any adapter sees it. That is filed as #14256 with the measurement; the honest repair is its one-expression code fix, not a caveat in the page, which is why the page was left alone.

Verification

Union run after the final commit, at 72c20362.

• pnpm --filter @objectstack/runtime test — 206 files, 3048 tests, all passed (the whole package, not a subset), both before and after the backend migration.
• pnpm --filter @objectstack/service-job test — 9 files, 94 tests passed (the IJobService side, untouched and confirmed so).
• pnpm --filter @objectstack/runtime typecheck — clean. ⚠️ That config excludes **/*.test.ts, so it says nothing about the new test file; measured separately with the exclusion lifted (tsc --noEmit, exit 0, --listFiles confirming the file is in the program — 1 hit there versus 0 under the package config).
• New suite packages/runtime/src/app-plugin.job-data-reach.test.ts: 8 tests, including two firing positive controls — the same shipped callable invoked with the pre-change context rejects and the store is unchanged, so neither passing write assertion can be vacuous.
• pnpm check:driver-memory-census — reproduced red on the first head, green at 72c20362, ledger untouched.
• 53 of the 57 gate families derived by scripts/pm/dispatch-gates.mjs ran green, ratchets re-run at 72c20362. Plus all 38 families in that derivation's undetermined bucket — 36 green, 2 refusing on an unbuilt sibling package. That bucket is where the census gate lives: it declares no path population, so no path derivation can name it for any card, and running only the derived list is what let this one reach CI.

Not measured locally, each refusing on a stated prerequisite rather than failing: check:type-check-debt and check:dual-build-cjs-loads (exit 3 — both need the whole workspace built), check-test-completeness (exit 3 — grades a saved turbo log CI tees), scripts/pm/check-half-states.mjs (network-bound PM patrol), and, from the undetermined bucket, check:app-nav-i18n and @objectstack/client's check:exported-any-returns (both refuse rather than compute a false green over an unbuilt package). CI runs all of them.

Filed, not fixed

• filed as AppPlugin's declarative-job wrapper discards the handler's JobRunOutcome, so defineJob cannot report a degraded run #14256 — the same wrapper discards the handler's JobRunOutcome, so a declarative job that resolves { outcome: 'degraded' } is recorded as success. Adjacent to this seam but a different defect class (outbound, not inbound), so it is not folded in here. The measurement above is on the card.
• filed as app-showcase's nightly health sweep reaches its engine through a module-scope global, so it silently does nothing on an artifact-served boot #14257 — examples/app-showcase's nightly sweep still reaches its engine through the module-scope global, so it silently does nothing on an artifact-served boot. Now migratable to the context member this PR adds.

Independent of #14095, exactly as the card says: that one is about recognising a uniqueness violation once you can reach the store; this one is about reaching it at all.

Authored by Claude Code, session session_01Q5WBDtaUnoz5XuJ6jk8pQ5 (https://claude.ai/code/session_01Q5WBDtaUnoz5XuJ6jk8pQ5).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime, touching 3 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/runtime/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/jobs.mdx(via JobHandlerContext (symbol, a top-level interface), jobId (symbol, a field of interface JobHandlerContext))
• content/docs/data-modeling/import-mappings.mdx(via jobId (symbol, a field of interface JobHandlerContext))
• content/docs/protocol/objectql/state-machine.mdx(via jobId (symbol, a field of interface JobHandlerContext))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/runtime/src/index.ts) — pages documenting those are invisible to this run
• 1 cross-cutting symbol(s) contributed no route anchor: jobId (6 routes)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 24 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 — the merge of head 72c20362c0663aa27bbfb0cf834cfa3ce144528e into base 035951faf99c42c258d470102da7346f309f7346, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 && git checkout 45e39eb79396d9b4150fc3c4f332e9dd601ecb90
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 035951faf99c42c258d470102da7346f309f7346 72c20362c0663aa27bbfb0cf834cfa3ce144528e && git checkout -B drift-repro 035951faf99c42c258d470102da7346f309f7346 && git merge --no-ff 72c20362c0663aa27bbfb0cf834cfa3ce144528e
node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 035951faf99c42c258d470102da7346f309f7346 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Closes#14094

defineJob is the platform's only metadata shape for scheduled work. Its handler resolves out of defineStack({ functions }), and AppPlugin invoked it with { jobId, data, bundle } — no engine, no service registry, no logger, no session. The job registered, appeared in the metadata registry and the admin UI, was scheduled, ran on time, and did nothing. objectstack validate passed, and the only related boot warning covers a missing handler, not a handler with no reach.

What changed

packages/runtime/src/app-plugin.ts — the context the declarative-job wrapper builds now also carries:

• ql — the live ObjectQL engine, the same handle defineStack({ onEnable }) receives as ctx.ql;
• logger — the plugin Logger, so a job's diagnostics land in the platform's log stream instead of console.

JobHandlerContext (new, packages/runtime/src/job-handler-context.ts, re-exported from @objectstack/runtime) is the type a handler can annotate against. content/docs/automation/jobs.mdx documents the context and warns against the module-scope route.

A job has no graph — this does not reopen the flow-script-node contract

FlowFunctionContext carries no engine either, and that is coherent for a flow function: the flow graph does the I/O around it — a get_record node before, a create_record node after — so the function stays a pure value-returner, and #4354's per-run write metrics depend on exactly that. Nothing here changes what a script node receives.

A job has no graph. There is no node before it and none after. So the same emptiness that is a clean contract for a script node leaves a job unable to do the one thing jobs exist for. That asymmetry is the whole argument; a reader who collapses the two cases will read this as an inconsistency rather than as a gap.

Why the module-scope escape was not documented instead

Closing over a client bound from onEnable is available to a flow function and does not survive the shipped deployment path for a job:

• objectstack build emits functions into a sibling runtime module whose only exports are { functions, meta };
• the artifact JSON carries no onEnable;
• mergeRuntimeModule (packages/runtime/src/load-artifact-bundle.ts) merges only functions.

So on an artifact-served boot the binding is never made, the module-scope slot stays empty, and the job runs against nothing — silently. Documenting that escape would make the failure harder to find, not easier. The regression suite therefore proves the write on both boot paths, and the artifact one goes through the real loadArtifactBundle, asserting on the way that the loaded bundle carries no onEnable.

Additive — IJobService is untouched

JobHandler is declared as taking { jobId: string; data?: unknown } and resolving void or a JobRunOutcome. The function AppPlugin hands to IJobService.schedule is a wrapper that satisfies it exactly; the new members are added inside that wrapper. Same shape as #6617's JobRunOutcome widening. No existing handler adapts, and no IJobService implementation grows a member. Pinned by two tests: a handler written against the pre-change context runs unchanged, and a third-party IJobService typed only at the contract schedules and drives the job to a real record write.

Measurements the dispatch asked for

Zone 2.3 — the card's probe re-run on current main. Reproduced exactly, at origin/main66ecc50a, on a real booted engine driving the real CronJobAdapter:

RUNS: 2
JOB CONTEXT KEYS: bundle, data, jobId
bundle -> object
data -> undefined
jobId -> string

Identical to the card's reading against published @objectstack/* 17.2.0.

Zone 2.1 — is the narrow route reachable without packages/spec? YES. Clause-②: no.packages/spec is not touched. Two readings carry it: the boundary type JobHandler constrains only the wrapper AppPlugin passes to IJobService.schedule, which is unchanged; and the bundle callable it invokes is typed as taking any and returning any (collectBundleFunctions), authored through functions, whose schema member is a bare z.function() — no context type constrains it. The producer of the extra members is AppPlugin, so the runtime is where the type belongs.

Zone 2.2 — ql versus the kernel's getService: settled by measurement, not by scope. The repo ships exactly onedefineJob declaration (examples/app-showcase, showcase_health_sweep → sweepProjectHealth). It needs find + update and a logger, and nothing else — it reaches them today through a module-scope let host filled by bindShowcaseJobRuntime from onEnable, which is the escape above. The card's own reporting app takes an engine as an explicit argument. Zero measured pull for automation, email or queue from any job. getService would put the whole service registry on the job context permanently — a materially larger surface to support forever, and the place an AI-authored metadata app would reach for a service it has no declared relationship with. Adding it later is additive by exactly the argument above, so choosing the narrow member now forecloses nothing.

Zone 2.5 — no change to what a job sees on error. The wrapper's throw/reject path is untouched; retry and failure semantics are exactly as before.

Zone 2.4 — no collision with #14143.packages/runtime/src/action-execution.ts is not in the diff.

The test backend

The suite boots on sqlite :memory:, the backend #5704 migrated this project's test rigs to. It needs a store; nothing in it is about any one driver. The card's own reproduction used @objectstack/driver-memory because that is what the reporter had in hand — a manual probe, never a constraint on the rig — and reaching for it here made this an unledgered arrival that pnpm check:driver-memory-census refused (#6664). Migrated rather than ledgered: the census stays at 2 ruled consumers and scripts/driver-memory-census.ledger.json is untouched by this PR.

Provisioning sweep_note and nothing else makes the engine's single-tenant probe read an absent sys_organization, so the expected refusal is withheld and asserted through expected-read-refusal-noise.ts (#10629) rather than muted. That probe is memoised behind the first data operation, so the three context-shape tests that never touch the store declare it with harness({ touchesStore: false }) — the API's own silentChannels(required) narrowing. The withholding stays unconditional; only the must-have-fired set narrows.

Does content/docs/automation/jobs.mdx still tell the truth?

For everything this PR touches, yes — and the page is now pinned rather than merely asserted: the context table (jobId / data / bundle / ql / logger) is held exactly by the suite's key-set assertion, data is checked on both the scheduled and the manual-trigger path, and the Callout's claim about the artifact boot is the artifact test.

One row on that page is not true, and this PR neither introduced nor fixes it: under What the handler returns, "resolves { outcome: 'degraded', reason? } is recorded as degraded". Measured on the declarative path — schedule through a recording IJobService, capture the wrapper, call it:

HANDLER RESOLVED: {"outcome":"degraded","reason":"STORE_UNAVAILABLE"}
WRAPPER RESOLVED: undefined

The outcome is dropped before any adapter sees it. That is filed as #14256 with the measurement; the honest repair is its one-expression code fix, not a caveat in the page, which is why the page was left alone.

Verification

Union run after the final commit, at 72c20362.

• pnpm --filter @objectstack/runtime test — 206 files, 3048 tests, all passed (the whole package, not a subset), both before and after the backend migration.
• pnpm --filter @objectstack/service-job test — 9 files, 94 tests passed (the IJobService side, untouched and confirmed so).
• pnpm --filter @objectstack/runtime typecheck — clean. ⚠️ That config excludes **/*.test.ts, so it says nothing about the new test file; measured separately with the exclusion lifted (tsc --noEmit, exit 0, --listFiles confirming the file is in the program — 1 hit there versus 0 under the package config).
• New suite packages/runtime/src/app-plugin.job-data-reach.test.ts: 8 tests, including two firing positive controls — the same shipped callable invoked with the pre-change context rejects and the store is unchanged, so neither passing write assertion can be vacuous.
• pnpm check:driver-memory-census — reproduced red on the first head, green at 72c20362, ledger untouched.
• 53 of the 57 gate families derived by scripts/pm/dispatch-gates.mjs ran green, ratchets re-run at 72c20362. Plus all 38 families in that derivation's undetermined bucket — 36 green, 2 refusing on an unbuilt sibling package. That bucket is where the census gate lives: it declares no path population, so no path derivation can name it for any card, and running only the derived list is what let this one reach CI.

Not measured locally, each refusing on a stated prerequisite rather than failing: check:type-check-debt and check:dual-build-cjs-loads (exit 3 — both need the whole workspace built), check-test-completeness (exit 3 — grades a saved turbo log CI tees), scripts/pm/check-half-states.mjs (network-bound PM patrol), and, from the undetermined bucket, check:app-nav-i18n and @objectstack/client's check:exported-any-returns (both refuse rather than compute a false green over an unbuilt package). CI runs all of them.

Filed, not fixed

• filed as AppPlugin's declarative-job wrapper discards the handler's JobRunOutcome, so defineJob cannot report a degraded run #14256 — the same wrapper discards the handler's JobRunOutcome, so a declarative job that resolves { outcome: 'degraded' } is recorded as success. Adjacent to this seam but a different defect class (outbound, not inbound), so it is not folded in here. The measurement above is on the card.
• filed as app-showcase's nightly health sweep reaches its engine through a module-scope global, so it silently does nothing on an artifact-served boot #14257 — examples/app-showcase's nightly sweep still reaches its engine through the module-scope global, so it silently does nothing on an artifact-served boot. Now migratable to the context member this PR adds.

Independent of #14095, exactly as the card says: that one is about recognising a uniqueness violation once you can reach the store; this one is about reaching it at all.

Authored by Claude Code, session session_01Q5WBDtaUnoz5XuJ6jk8pQ5 (https://claude.ai/code/session_01Q5WBDtaUnoz5XuJ6jk8pQ5).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime, touching 3 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/runtime/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/jobs.mdx(via JobHandlerContext (symbol, a top-level interface), jobId (symbol, a field of interface JobHandlerContext))
• content/docs/data-modeling/import-mappings.mdx(via jobId (symbol, a field of interface JobHandlerContext))
• content/docs/protocol/objectql/state-machine.mdx(via jobId (symbol, a field of interface JobHandlerContext))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/runtime/src/index.ts) — pages documenting those are invisible to this run
• 1 cross-cutting symbol(s) contributed no route anchor: jobId (6 routes)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 24 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 — the merge of head 72c20362c0663aa27bbfb0cf834cfa3ce144528e into base 035951faf99c42c258d470102da7346f309f7346, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 && git checkout 45e39eb79396d9b4150fc3c4f332e9dd601ecb90
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 035951faf99c42c258d470102da7346f309f7346 72c20362c0663aa27bbfb0cf834cfa3ce144528e && git checkout -B drift-repro 035951faf99c42c258d470102da7346f309f7346 && git merge --no-ff 72c20362c0663aa27bbfb0cf834cfa3ce144528e
node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 035951faf99c42c258d470102da7346f309f7346 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Closes#14094

defineJob is the platform's only metadata shape for scheduled work. Its handler resolves out of defineStack({ functions }), and AppPlugin invoked it with { jobId, data, bundle } — no engine, no service registry, no logger, no session. The job registered, appeared in the metadata registry and the admin UI, was scheduled, ran on time, and did nothing. objectstack validate passed, and the only related boot warning covers a missing handler, not a handler with no reach.

What changed

packages/runtime/src/app-plugin.ts — the context the declarative-job wrapper builds now also carries:

• ql — the live ObjectQL engine, the same handle defineStack({ onEnable }) receives as ctx.ql;
• logger — the plugin Logger, so a job's diagnostics land in the platform's log stream instead of console.

JobHandlerContext (new, packages/runtime/src/job-handler-context.ts, re-exported from @objectstack/runtime) is the type a handler can annotate against. content/docs/automation/jobs.mdx documents the context and warns against the module-scope route.

A job has no graph — this does not reopen the flow-script-node contract

FlowFunctionContext carries no engine either, and that is coherent for a flow function: the flow graph does the I/O around it — a get_record node before, a create_record node after — so the function stays a pure value-returner, and #4354's per-run write metrics depend on exactly that. Nothing here changes what a script node receives.

A job has no graph. There is no node before it and none after. So the same emptiness that is a clean contract for a script node leaves a job unable to do the one thing jobs exist for. That asymmetry is the whole argument; a reader who collapses the two cases will read this as an inconsistency rather than as a gap.

Why the module-scope escape was not documented instead

Closing over a client bound from onEnable is available to a flow function and does not survive the shipped deployment path for a job:

• objectstack build emits functions into a sibling runtime module whose only exports are { functions, meta };
• the artifact JSON carries no onEnable;
• mergeRuntimeModule (packages/runtime/src/load-artifact-bundle.ts) merges only functions.

So on an artifact-served boot the binding is never made, the module-scope slot stays empty, and the job runs against nothing — silently. Documenting that escape would make the failure harder to find, not easier. The regression suite therefore proves the write on both boot paths, and the artifact one goes through the real loadArtifactBundle, asserting on the way that the loaded bundle carries no onEnable.

Additive — IJobService is untouched

JobHandler is declared as taking { jobId: string; data?: unknown } and resolving void or a JobRunOutcome. The function AppPlugin hands to IJobService.schedule is a wrapper that satisfies it exactly; the new members are added inside that wrapper. Same shape as #6617's JobRunOutcome widening. No existing handler adapts, and no IJobService implementation grows a member. Pinned by two tests: a handler written against the pre-change context runs unchanged, and a third-party IJobService typed only at the contract schedules and drives the job to a real record write.

Measurements the dispatch asked for

Zone 2.3 — the card's probe re-run on current main. Reproduced exactly, at origin/main66ecc50a, on a real booted engine driving the real CronJobAdapter:

RUNS: 2
JOB CONTEXT KEYS: bundle, data, jobId
bundle -> object
data -> undefined
jobId -> string

Identical to the card's reading against published @objectstack/* 17.2.0.

Zone 2.1 — is the narrow route reachable without packages/spec? YES. Clause-②: no.packages/spec is not touched. Two readings carry it: the boundary type JobHandler constrains only the wrapper AppPlugin passes to IJobService.schedule, which is unchanged; and the bundle callable it invokes is typed as taking any and returning any (collectBundleFunctions), authored through functions, whose schema member is a bare z.function() — no context type constrains it. The producer of the extra members is AppPlugin, so the runtime is where the type belongs.

Zone 2.2 — ql versus the kernel's getService: settled by measurement, not by scope. The repo ships exactly onedefineJob declaration (examples/app-showcase, showcase_health_sweep → sweepProjectHealth). It needs find + update and a logger, and nothing else — it reaches them today through a module-scope let host filled by bindShowcaseJobRuntime from onEnable, which is the escape above. The card's own reporting app takes an engine as an explicit argument. Zero measured pull for automation, email or queue from any job. getService would put the whole service registry on the job context permanently — a materially larger surface to support forever, and the place an AI-authored metadata app would reach for a service it has no declared relationship with. Adding it later is additive by exactly the argument above, so choosing the narrow member now forecloses nothing.

Zone 2.5 — no change to what a job sees on error. The wrapper's throw/reject path is untouched; retry and failure semantics are exactly as before.

Zone 2.4 — no collision with #14143.packages/runtime/src/action-execution.ts is not in the diff.

The test backend

The suite boots on sqlite :memory:, the backend #5704 migrated this project's test rigs to. It needs a store; nothing in it is about any one driver. The card's own reproduction used @objectstack/driver-memory because that is what the reporter had in hand — a manual probe, never a constraint on the rig — and reaching for it here made this an unledgered arrival that pnpm check:driver-memory-census refused (#6664). Migrated rather than ledgered: the census stays at 2 ruled consumers and scripts/driver-memory-census.ledger.json is untouched by this PR.

Provisioning sweep_note and nothing else makes the engine's single-tenant probe read an absent sys_organization, so the expected refusal is withheld and asserted through expected-read-refusal-noise.ts (#10629) rather than muted. That probe is memoised behind the first data operation, so the three context-shape tests that never touch the store declare it with harness({ touchesStore: false }) — the API's own silentChannels(required) narrowing. The withholding stays unconditional; only the must-have-fired set narrows.

Does content/docs/automation/jobs.mdx still tell the truth?

For everything this PR touches, yes — and the page is now pinned rather than merely asserted: the context table (jobId / data / bundle / ql / logger) is held exactly by the suite's key-set assertion, data is checked on both the scheduled and the manual-trigger path, and the Callout's claim about the artifact boot is the artifact test.

One row on that page is not true, and this PR neither introduced nor fixes it: under What the handler returns, "resolves { outcome: 'degraded', reason? } is recorded as degraded". Measured on the declarative path — schedule through a recording IJobService, capture the wrapper, call it:

HANDLER RESOLVED: {"outcome":"degraded","reason":"STORE_UNAVAILABLE"}
WRAPPER RESOLVED: undefined

The outcome is dropped before any adapter sees it. That is filed as #14256 with the measurement; the honest repair is its one-expression code fix, not a caveat in the page, which is why the page was left alone.

Verification

Union run after the final commit, at 72c20362.

• pnpm --filter @objectstack/runtime test — 206 files, 3048 tests, all passed (the whole package, not a subset), both before and after the backend migration.
• pnpm --filter @objectstack/service-job test — 9 files, 94 tests passed (the IJobService side, untouched and confirmed so).
• pnpm --filter @objectstack/runtime typecheck — clean. ⚠️ That config excludes **/*.test.ts, so it says nothing about the new test file; measured separately with the exclusion lifted (tsc --noEmit, exit 0, --listFiles confirming the file is in the program — 1 hit there versus 0 under the package config).
• New suite packages/runtime/src/app-plugin.job-data-reach.test.ts: 8 tests, including two firing positive controls — the same shipped callable invoked with the pre-change context rejects and the store is unchanged, so neither passing write assertion can be vacuous.
• pnpm check:driver-memory-census — reproduced red on the first head, green at 72c20362, ledger untouched.
• 53 of the 57 gate families derived by scripts/pm/dispatch-gates.mjs ran green, ratchets re-run at 72c20362. Plus all 38 families in that derivation's undetermined bucket — 36 green, 2 refusing on an unbuilt sibling package. That bucket is where the census gate lives: it declares no path population, so no path derivation can name it for any card, and running only the derived list is what let this one reach CI.

Not measured locally, each refusing on a stated prerequisite rather than failing: check:type-check-debt and check:dual-build-cjs-loads (exit 3 — both need the whole workspace built), check-test-completeness (exit 3 — grades a saved turbo log CI tees), scripts/pm/check-half-states.mjs (network-bound PM patrol), and, from the undetermined bucket, check:app-nav-i18n and @objectstack/client's check:exported-any-returns (both refuse rather than compute a false green over an unbuilt package). CI runs all of them.

Filed, not fixed

• filed as AppPlugin's declarative-job wrapper discards the handler's JobRunOutcome, so defineJob cannot report a degraded run #14256 — the same wrapper discards the handler's JobRunOutcome, so a declarative job that resolves { outcome: 'degraded' } is recorded as success. Adjacent to this seam but a different defect class (outbound, not inbound), so it is not folded in here. The measurement above is on the card.
• filed as app-showcase's nightly health sweep reaches its engine through a module-scope global, so it silently does nothing on an artifact-served boot #14257 — examples/app-showcase's nightly sweep still reaches its engine through the module-scope global, so it silently does nothing on an artifact-served boot. Now migratable to the context member this PR adds.

Independent of #14095, exactly as the card says: that one is about recognising a uniqueness violation once you can reach the store; this one is about reaching it at all.

Authored by Claude Code, session session_01Q5WBDtaUnoz5XuJ6jk8pQ5 (https://claude.ai/code/session_01Q5WBDtaUnoz5XuJ6jk8pQ5).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime, touching 3 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/runtime/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/jobs.mdx(via JobHandlerContext (symbol, a top-level interface), jobId (symbol, a field of interface JobHandlerContext))
• content/docs/data-modeling/import-mappings.mdx(via jobId (symbol, a field of interface JobHandlerContext))
• content/docs/protocol/objectql/state-machine.mdx(via jobId (symbol, a field of interface JobHandlerContext))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/runtime/src/index.ts) — pages documenting those are invisible to this run
• 1 cross-cutting symbol(s) contributed no route anchor: jobId (6 routes)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 24 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 — the merge of head 72c20362c0663aa27bbfb0cf834cfa3ce144528e into base 035951faf99c42c258d470102da7346f309f7346, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 && git checkout 45e39eb79396d9b4150fc3c4f332e9dd601ecb90
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 035951faf99c42c258d470102da7346f309f7346 72c20362c0663aa27bbfb0cf834cfa3ce144528e && git checkout -B drift-repro 035951faf99c42c258d470102da7346f309f7346 && git merge --no-ff 72c20362c0663aa27bbfb0cf834cfa3ce144528e
node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 035951faf99c42c258d470102da7346f309f7346 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Closes#14094

defineJob is the platform's only metadata shape for scheduled work. Its handler resolves out of defineStack({ functions }), and AppPlugin invoked it with { jobId, data, bundle } — no engine, no service registry, no logger, no session. The job registered, appeared in the metadata registry and the admin UI, was scheduled, ran on time, and did nothing. objectstack validate passed, and the only related boot warning covers a missing handler, not a handler with no reach.

What changed

packages/runtime/src/app-plugin.ts — the context the declarative-job wrapper builds now also carries:

• ql — the live ObjectQL engine, the same handle defineStack({ onEnable }) receives as ctx.ql;
• logger — the plugin Logger, so a job's diagnostics land in the platform's log stream instead of console.

JobHandlerContext (new, packages/runtime/src/job-handler-context.ts, re-exported from @objectstack/runtime) is the type a handler can annotate against. content/docs/automation/jobs.mdx documents the context and warns against the module-scope route.

A job has no graph — this does not reopen the flow-script-node contract

FlowFunctionContext carries no engine either, and that is coherent for a flow function: the flow graph does the I/O around it — a get_record node before, a create_record node after — so the function stays a pure value-returner, and #4354's per-run write metrics depend on exactly that. Nothing here changes what a script node receives.

A job has no graph. There is no node before it and none after. So the same emptiness that is a clean contract for a script node leaves a job unable to do the one thing jobs exist for. That asymmetry is the whole argument; a reader who collapses the two cases will read this as an inconsistency rather than as a gap.

Why the module-scope escape was not documented instead

Closing over a client bound from onEnable is available to a flow function and does not survive the shipped deployment path for a job:

• objectstack build emits functions into a sibling runtime module whose only exports are { functions, meta };
• the artifact JSON carries no onEnable;
• mergeRuntimeModule (packages/runtime/src/load-artifact-bundle.ts) merges only functions.

So on an artifact-served boot the binding is never made, the module-scope slot stays empty, and the job runs against nothing — silently. Documenting that escape would make the failure harder to find, not easier. The regression suite therefore proves the write on both boot paths, and the artifact one goes through the real loadArtifactBundle, asserting on the way that the loaded bundle carries no onEnable.

Additive — IJobService is untouched

JobHandler is declared as taking { jobId: string; data?: unknown } and resolving void or a JobRunOutcome. The function AppPlugin hands to IJobService.schedule is a wrapper that satisfies it exactly; the new members are added inside that wrapper. Same shape as #6617's JobRunOutcome widening. No existing handler adapts, and no IJobService implementation grows a member. Pinned by two tests: a handler written against the pre-change context runs unchanged, and a third-party IJobService typed only at the contract schedules and drives the job to a real record write.

Measurements the dispatch asked for

Zone 2.3 — the card's probe re-run on current main. Reproduced exactly, at origin/main66ecc50a, on a real booted engine driving the real CronJobAdapter:

RUNS: 2
JOB CONTEXT KEYS: bundle, data, jobId
bundle -> object
data -> undefined
jobId -> string

Identical to the card's reading against published @objectstack/* 17.2.0.

Zone 2.1 — is the narrow route reachable without packages/spec? YES. Clause-②: no.packages/spec is not touched. Two readings carry it: the boundary type JobHandler constrains only the wrapper AppPlugin passes to IJobService.schedule, which is unchanged; and the bundle callable it invokes is typed as taking any and returning any (collectBundleFunctions), authored through functions, whose schema member is a bare z.function() — no context type constrains it. The producer of the extra members is AppPlugin, so the runtime is where the type belongs.

Zone 2.2 — ql versus the kernel's getService: settled by measurement, not by scope. The repo ships exactly onedefineJob declaration (examples/app-showcase, showcase_health_sweep → sweepProjectHealth). It needs find + update and a logger, and nothing else — it reaches them today through a module-scope let host filled by bindShowcaseJobRuntime from onEnable, which is the escape above. The card's own reporting app takes an engine as an explicit argument. Zero measured pull for automation, email or queue from any job. getService would put the whole service registry on the job context permanently — a materially larger surface to support forever, and the place an AI-authored metadata app would reach for a service it has no declared relationship with. Adding it later is additive by exactly the argument above, so choosing the narrow member now forecloses nothing.

Zone 2.5 — no change to what a job sees on error. The wrapper's throw/reject path is untouched; retry and failure semantics are exactly as before.

Zone 2.4 — no collision with #14143.packages/runtime/src/action-execution.ts is not in the diff.

The test backend

The suite boots on sqlite :memory:, the backend #5704 migrated this project's test rigs to. It needs a store; nothing in it is about any one driver. The card's own reproduction used @objectstack/driver-memory because that is what the reporter had in hand — a manual probe, never a constraint on the rig — and reaching for it here made this an unledgered arrival that pnpm check:driver-memory-census refused (#6664). Migrated rather than ledgered: the census stays at 2 ruled consumers and scripts/driver-memory-census.ledger.json is untouched by this PR.

Provisioning sweep_note and nothing else makes the engine's single-tenant probe read an absent sys_organization, so the expected refusal is withheld and asserted through expected-read-refusal-noise.ts (#10629) rather than muted. That probe is memoised behind the first data operation, so the three context-shape tests that never touch the store declare it with harness({ touchesStore: false }) — the API's own silentChannels(required) narrowing. The withholding stays unconditional; only the must-have-fired set narrows.

Does content/docs/automation/jobs.mdx still tell the truth?

For everything this PR touches, yes — and the page is now pinned rather than merely asserted: the context table (jobId / data / bundle / ql / logger) is held exactly by the suite's key-set assertion, data is checked on both the scheduled and the manual-trigger path, and the Callout's claim about the artifact boot is the artifact test.

One row on that page is not true, and this PR neither introduced nor fixes it: under What the handler returns, "resolves { outcome: 'degraded', reason? } is recorded as degraded". Measured on the declarative path — schedule through a recording IJobService, capture the wrapper, call it:

HANDLER RESOLVED: {"outcome":"degraded","reason":"STORE_UNAVAILABLE"}
WRAPPER RESOLVED: undefined

The outcome is dropped before any adapter sees it. That is filed as #14256 with the measurement; the honest repair is its one-expression code fix, not a caveat in the page, which is why the page was left alone.

Verification

Union run after the final commit, at 72c20362.

• pnpm --filter @objectstack/runtime test — 206 files, 3048 tests, all passed (the whole package, not a subset), both before and after the backend migration.
• pnpm --filter @objectstack/service-job test — 9 files, 94 tests passed (the IJobService side, untouched and confirmed so).
• pnpm --filter @objectstack/runtime typecheck — clean. ⚠️ That config excludes **/*.test.ts, so it says nothing about the new test file; measured separately with the exclusion lifted (tsc --noEmit, exit 0, --listFiles confirming the file is in the program — 1 hit there versus 0 under the package config).
• New suite packages/runtime/src/app-plugin.job-data-reach.test.ts: 8 tests, including two firing positive controls — the same shipped callable invoked with the pre-change context rejects and the store is unchanged, so neither passing write assertion can be vacuous.
• pnpm check:driver-memory-census — reproduced red on the first head, green at 72c20362, ledger untouched.
• 53 of the 57 gate families derived by scripts/pm/dispatch-gates.mjs ran green, ratchets re-run at 72c20362. Plus all 38 families in that derivation's undetermined bucket — 36 green, 2 refusing on an unbuilt sibling package. That bucket is where the census gate lives: it declares no path population, so no path derivation can name it for any card, and running only the derived list is what let this one reach CI.

Not measured locally, each refusing on a stated prerequisite rather than failing: check:type-check-debt and check:dual-build-cjs-loads (exit 3 — both need the whole workspace built), check-test-completeness (exit 3 — grades a saved turbo log CI tees), scripts/pm/check-half-states.mjs (network-bound PM patrol), and, from the undetermined bucket, check:app-nav-i18n and @objectstack/client's check:exported-any-returns (both refuse rather than compute a false green over an unbuilt package). CI runs all of them.

Filed, not fixed

• filed as AppPlugin's declarative-job wrapper discards the handler's JobRunOutcome, so defineJob cannot report a degraded run #14256 — the same wrapper discards the handler's JobRunOutcome, so a declarative job that resolves { outcome: 'degraded' } is recorded as success. Adjacent to this seam but a different defect class (outbound, not inbound), so it is not folded in here. The measurement above is on the card.
• filed as app-showcase's nightly health sweep reaches its engine through a module-scope global, so it silently does nothing on an artifact-served boot #14257 — examples/app-showcase's nightly sweep still reaches its engine through the module-scope global, so it silently does nothing on an artifact-served boot. Now migratable to the context member this PR adds.

Independent of #14095, exactly as the card says: that one is about recognising a uniqueness violation once you can reach the store; this one is about reaching it at all.

Authored by Claude Code, session session_01Q5WBDtaUnoz5XuJ6jk8pQ5 (https://claude.ai/code/session_01Q5WBDtaUnoz5XuJ6jk8pQ5).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime, touching 3 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/runtime/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/jobs.mdx(via JobHandlerContext (symbol, a top-level interface), jobId (symbol, a field of interface JobHandlerContext))
• content/docs/data-modeling/import-mappings.mdx(via jobId (symbol, a field of interface JobHandlerContext))
• content/docs/protocol/objectql/state-machine.mdx(via jobId (symbol, a field of interface JobHandlerContext))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/runtime/src/index.ts) — pages documenting those are invisible to this run
• 1 cross-cutting symbol(s) contributed no route anchor: jobId (6 routes)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 24 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 — the merge of head 72c20362c0663aa27bbfb0cf834cfa3ce144528e into base 035951faf99c42c258d470102da7346f309f7346, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 && git checkout 45e39eb79396d9b4150fc3c4f332e9dd601ecb90
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 035951faf99c42c258d470102da7346f309f7346 72c20362c0663aa27bbfb0cf834cfa3ce144528e && git checkout -B drift-repro 035951faf99c42c258d470102da7346f309f7346 && git merge --no-ff 72c20362c0663aa27bbfb0cf834cfa3ce144528e
node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 035951faf99c42c258d470102da7346f309f7346 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Closes#14094

defineJob is the platform's only metadata shape for scheduled work. Its handler resolves out of defineStack({ functions }), and AppPlugin invoked it with { jobId, data, bundle } — no engine, no service registry, no logger, no session. The job registered, appeared in the metadata registry and the admin UI, was scheduled, ran on time, and did nothing. objectstack validate passed, and the only related boot warning covers a missing handler, not a handler with no reach.

What changed

packages/runtime/src/app-plugin.ts — the context the declarative-job wrapper builds now also carries:

• ql — the live ObjectQL engine, the same handle defineStack({ onEnable }) receives as ctx.ql;
• logger — the plugin Logger, so a job's diagnostics land in the platform's log stream instead of console.

JobHandlerContext (new, packages/runtime/src/job-handler-context.ts, re-exported from @objectstack/runtime) is the type a handler can annotate against. content/docs/automation/jobs.mdx documents the context and warns against the module-scope route.

A job has no graph — this does not reopen the flow-script-node contract

FlowFunctionContext carries no engine either, and that is coherent for a flow function: the flow graph does the I/O around it — a get_record node before, a create_record node after — so the function stays a pure value-returner, and #4354's per-run write metrics depend on exactly that. Nothing here changes what a script node receives.

A job has no graph. There is no node before it and none after. So the same emptiness that is a clean contract for a script node leaves a job unable to do the one thing jobs exist for. That asymmetry is the whole argument; a reader who collapses the two cases will read this as an inconsistency rather than as a gap.

Why the module-scope escape was not documented instead

Closing over a client bound from onEnable is available to a flow function and does not survive the shipped deployment path for a job:

• objectstack build emits functions into a sibling runtime module whose only exports are { functions, meta };
• the artifact JSON carries no onEnable;
• mergeRuntimeModule (packages/runtime/src/load-artifact-bundle.ts) merges only functions.

So on an artifact-served boot the binding is never made, the module-scope slot stays empty, and the job runs against nothing — silently. Documenting that escape would make the failure harder to find, not easier. The regression suite therefore proves the write on both boot paths, and the artifact one goes through the real loadArtifactBundle, asserting on the way that the loaded bundle carries no onEnable.

Additive — IJobService is untouched

JobHandler is declared as taking { jobId: string; data?: unknown } and resolving void or a JobRunOutcome. The function AppPlugin hands to IJobService.schedule is a wrapper that satisfies it exactly; the new members are added inside that wrapper. Same shape as #6617's JobRunOutcome widening. No existing handler adapts, and no IJobService implementation grows a member. Pinned by two tests: a handler written against the pre-change context runs unchanged, and a third-party IJobService typed only at the contract schedules and drives the job to a real record write.

Measurements the dispatch asked for

Zone 2.3 — the card's probe re-run on current main. Reproduced exactly, at origin/main66ecc50a, on a real booted engine driving the real CronJobAdapter:

RUNS: 2
JOB CONTEXT KEYS: bundle, data, jobId
bundle -> object
data -> undefined
jobId -> string

Identical to the card's reading against published @objectstack/* 17.2.0.

Zone 2.1 — is the narrow route reachable without packages/spec? YES. Clause-②: no.packages/spec is not touched. Two readings carry it: the boundary type JobHandler constrains only the wrapper AppPlugin passes to IJobService.schedule, which is unchanged; and the bundle callable it invokes is typed as taking any and returning any (collectBundleFunctions), authored through functions, whose schema member is a bare z.function() — no context type constrains it. The producer of the extra members is AppPlugin, so the runtime is where the type belongs.

Zone 2.2 — ql versus the kernel's getService: settled by measurement, not by scope. The repo ships exactly onedefineJob declaration (examples/app-showcase, showcase_health_sweep → sweepProjectHealth). It needs find + update and a logger, and nothing else — it reaches them today through a module-scope let host filled by bindShowcaseJobRuntime from onEnable, which is the escape above. The card's own reporting app takes an engine as an explicit argument. Zero measured pull for automation, email or queue from any job. getService would put the whole service registry on the job context permanently — a materially larger surface to support forever, and the place an AI-authored metadata app would reach for a service it has no declared relationship with. Adding it later is additive by exactly the argument above, so choosing the narrow member now forecloses nothing.

Zone 2.5 — no change to what a job sees on error. The wrapper's throw/reject path is untouched; retry and failure semantics are exactly as before.

Zone 2.4 — no collision with #14143.packages/runtime/src/action-execution.ts is not in the diff.

The test backend

The suite boots on sqlite :memory:, the backend #5704 migrated this project's test rigs to. It needs a store; nothing in it is about any one driver. The card's own reproduction used @objectstack/driver-memory because that is what the reporter had in hand — a manual probe, never a constraint on the rig — and reaching for it here made this an unledgered arrival that pnpm check:driver-memory-census refused (#6664). Migrated rather than ledgered: the census stays at 2 ruled consumers and scripts/driver-memory-census.ledger.json is untouched by this PR.

Provisioning sweep_note and nothing else makes the engine's single-tenant probe read an absent sys_organization, so the expected refusal is withheld and asserted through expected-read-refusal-noise.ts (#10629) rather than muted. That probe is memoised behind the first data operation, so the three context-shape tests that never touch the store declare it with harness({ touchesStore: false }) — the API's own silentChannels(required) narrowing. The withholding stays unconditional; only the must-have-fired set narrows.

Does content/docs/automation/jobs.mdx still tell the truth?

For everything this PR touches, yes — and the page is now pinned rather than merely asserted: the context table (jobId / data / bundle / ql / logger) is held exactly by the suite's key-set assertion, data is checked on both the scheduled and the manual-trigger path, and the Callout's claim about the artifact boot is the artifact test.

One row on that page is not true, and this PR neither introduced nor fixes it: under What the handler returns, "resolves { outcome: 'degraded', reason? } is recorded as degraded". Measured on the declarative path — schedule through a recording IJobService, capture the wrapper, call it:

HANDLER RESOLVED: {"outcome":"degraded","reason":"STORE_UNAVAILABLE"}
WRAPPER RESOLVED: undefined

The outcome is dropped before any adapter sees it. That is filed as #14256 with the measurement; the honest repair is its one-expression code fix, not a caveat in the page, which is why the page was left alone.

Verification

Union run after the final commit, at 72c20362.

• pnpm --filter @objectstack/runtime test — 206 files, 3048 tests, all passed (the whole package, not a subset), both before and after the backend migration.
• pnpm --filter @objectstack/service-job test — 9 files, 94 tests passed (the IJobService side, untouched and confirmed so).
• pnpm --filter @objectstack/runtime typecheck — clean. ⚠️ That config excludes **/*.test.ts, so it says nothing about the new test file; measured separately with the exclusion lifted (tsc --noEmit, exit 0, --listFiles confirming the file is in the program — 1 hit there versus 0 under the package config).
• New suite packages/runtime/src/app-plugin.job-data-reach.test.ts: 8 tests, including two firing positive controls — the same shipped callable invoked with the pre-change context rejects and the store is unchanged, so neither passing write assertion can be vacuous.
• pnpm check:driver-memory-census — reproduced red on the first head, green at 72c20362, ledger untouched.
• 53 of the 57 gate families derived by scripts/pm/dispatch-gates.mjs ran green, ratchets re-run at 72c20362. Plus all 38 families in that derivation's undetermined bucket — 36 green, 2 refusing on an unbuilt sibling package. That bucket is where the census gate lives: it declares no path population, so no path derivation can name it for any card, and running only the derived list is what let this one reach CI.

Not measured locally, each refusing on a stated prerequisite rather than failing: check:type-check-debt and check:dual-build-cjs-loads (exit 3 — both need the whole workspace built), check-test-completeness (exit 3 — grades a saved turbo log CI tees), scripts/pm/check-half-states.mjs (network-bound PM patrol), and, from the undetermined bucket, check:app-nav-i18n and @objectstack/client's check:exported-any-returns (both refuse rather than compute a false green over an unbuilt package). CI runs all of them.

Filed, not fixed

• filed as AppPlugin's declarative-job wrapper discards the handler's JobRunOutcome, so defineJob cannot report a degraded run #14256 — the same wrapper discards the handler's JobRunOutcome, so a declarative job that resolves { outcome: 'degraded' } is recorded as success. Adjacent to this seam but a different defect class (outbound, not inbound), so it is not folded in here. The measurement above is on the card.
• filed as app-showcase's nightly health sweep reaches its engine through a module-scope global, so it silently does nothing on an artifact-served boot #14257 — examples/app-showcase's nightly sweep still reaches its engine through the module-scope global, so it silently does nothing on an artifact-served boot. Now migratable to the context member this PR adds.

Independent of #14095, exactly as the card says: that one is about recognising a uniqueness violation once you can reach the store; this one is about reaching it at all.

Authored by Claude Code, session session_01Q5WBDtaUnoz5XuJ6jk8pQ5 (https://claude.ai/code/session_01Q5WBDtaUnoz5XuJ6jk8pQ5).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime, touching 3 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/runtime/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/jobs.mdx(via JobHandlerContext (symbol, a top-level interface), jobId (symbol, a field of interface JobHandlerContext))
• content/docs/data-modeling/import-mappings.mdx(via jobId (symbol, a field of interface JobHandlerContext))
• content/docs/protocol/objectql/state-machine.mdx(via jobId (symbol, a field of interface JobHandlerContext))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/runtime/src/index.ts) — pages documenting those are invisible to this run
• 1 cross-cutting symbol(s) contributed no route anchor: jobId (6 routes)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 24 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 — the merge of head 72c20362c0663aa27bbfb0cf834cfa3ce144528e into base 035951faf99c42c258d470102da7346f309f7346, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 && git checkout 45e39eb79396d9b4150fc3c4f332e9dd601ecb90
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 035951faf99c42c258d470102da7346f309f7346 72c20362c0663aa27bbfb0cf834cfa3ce144528e && git checkout -B drift-repro 035951faf99c42c258d470102da7346f309f7346 && git merge --no-ff 72c20362c0663aa27bbfb0cf834cfa3ce144528e
node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 035951faf99c42c258d470102da7346f309f7346 → pass the list as
args.docs, on the commit named under Which tree this was computed on.

[claude]

Closes#14094

defineJob is the platform's only metadata shape for scheduled work. Its handler resolves out of defineStack({ functions }), and AppPlugin invoked it with { jobId, data, bundle } — no engine, no service registry, no logger, no session. The job registered, appeared in the metadata registry and the admin UI, was scheduled, ran on time, and did nothing. objectstack validate passed, and the only related boot warning covers a missing handler, not a handler with no reach.

What changed

packages/runtime/src/app-plugin.ts — the context the declarative-job wrapper builds now also carries:

• ql — the live ObjectQL engine, the same handle defineStack({ onEnable }) receives as ctx.ql;
• logger — the plugin Logger, so a job's diagnostics land in the platform's log stream instead of console.

JobHandlerContext (new, packages/runtime/src/job-handler-context.ts, re-exported from @objectstack/runtime) is the type a handler can annotate against. content/docs/automation/jobs.mdx documents the context and warns against the module-scope route.

A job has no graph — this does not reopen the flow-script-node contract

FlowFunctionContext carries no engine either, and that is coherent for a flow function: the flow graph does the I/O around it — a get_record node before, a create_record node after — so the function stays a pure value-returner, and #4354's per-run write metrics depend on exactly that. Nothing here changes what a script node receives.

A job has no graph. There is no node before it and none after. So the same emptiness that is a clean contract for a script node leaves a job unable to do the one thing jobs exist for. That asymmetry is the whole argument; a reader who collapses the two cases will read this as an inconsistency rather than as a gap.

Why the module-scope escape was not documented instead

Closing over a client bound from onEnable is available to a flow function and does not survive the shipped deployment path for a job:

• objectstack build emits functions into a sibling runtime module whose only exports are { functions, meta };
• the artifact JSON carries no onEnable;
• mergeRuntimeModule (packages/runtime/src/load-artifact-bundle.ts) merges only functions.

So on an artifact-served boot the binding is never made, the module-scope slot stays empty, and the job runs against nothing — silently. Documenting that escape would make the failure harder to find, not easier. The regression suite therefore proves the write on both boot paths, and the artifact one goes through the real loadArtifactBundle, asserting on the way that the loaded bundle carries no onEnable.

Additive — IJobService is untouched

JobHandler is declared as taking { jobId: string; data?: unknown } and resolving void or a JobRunOutcome. The function AppPlugin hands to IJobService.schedule is a wrapper that satisfies it exactly; the new members are added inside that wrapper. Same shape as #6617's JobRunOutcome widening. No existing handler adapts, and no IJobService implementation grows a member. Pinned by two tests: a handler written against the pre-change context runs unchanged, and a third-party IJobService typed only at the contract schedules and drives the job to a real record write.

Measurements the dispatch asked for

Zone 2.3 — the card's probe re-run on current main. Reproduced exactly, at origin/main66ecc50a, on a real booted engine driving the real CronJobAdapter:

RUNS: 2
JOB CONTEXT KEYS: bundle, data, jobId
bundle -> object
data -> undefined
jobId -> string

Identical to the card's reading against published @objectstack/* 17.2.0.

Zone 2.1 — is the narrow route reachable without packages/spec? YES. Clause-②: no.packages/spec is not touched. Two readings carry it: the boundary type JobHandler constrains only the wrapper AppPlugin passes to IJobService.schedule, which is unchanged; and the bundle callable it invokes is typed as taking any and returning any (collectBundleFunctions), authored through functions, whose schema member is a bare z.function() — no context type constrains it. The producer of the extra members is AppPlugin, so the runtime is where the type belongs.

Zone 2.2 — ql versus the kernel's getService: settled by measurement, not by scope. The repo ships exactly onedefineJob declaration (examples/app-showcase, showcase_health_sweep → sweepProjectHealth). It needs find + update and a logger, and nothing else — it reaches them today through a module-scope let host filled by bindShowcaseJobRuntime from onEnable, which is the escape above. The card's own reporting app takes an engine as an explicit argument. Zero measured pull for automation, email or queue from any job. getService would put the whole service registry on the job context permanently — a materially larger surface to support forever, and the place an AI-authored metadata app would reach for a service it has no declared relationship with. Adding it later is additive by exactly the argument above, so choosing the narrow member now forecloses nothing.

Zone 2.5 — no change to what a job sees on error. The wrapper's throw/reject path is untouched; retry and failure semantics are exactly as before.

Zone 2.4 — no collision with #14143.packages/runtime/src/action-execution.ts is not in the diff.

The test backend

The suite boots on sqlite :memory:, the backend #5704 migrated this project's test rigs to. It needs a store; nothing in it is about any one driver. The card's own reproduction used @objectstack/driver-memory because that is what the reporter had in hand — a manual probe, never a constraint on the rig — and reaching for it here made this an unledgered arrival that pnpm check:driver-memory-census refused (#6664). Migrated rather than ledgered: the census stays at 2 ruled consumers and scripts/driver-memory-census.ledger.json is untouched by this PR.

Provisioning sweep_note and nothing else makes the engine's single-tenant probe read an absent sys_organization, so the expected refusal is withheld and asserted through expected-read-refusal-noise.ts (#10629) rather than muted. That probe is memoised behind the first data operation, so the three context-shape tests that never touch the store declare it with harness({ touchesStore: false }) — the API's own silentChannels(required) narrowing. The withholding stays unconditional; only the must-have-fired set narrows.

Does content/docs/automation/jobs.mdx still tell the truth?

For everything this PR touches, yes — and the page is now pinned rather than merely asserted: the context table (jobId / data / bundle / ql / logger) is held exactly by the suite's key-set assertion, data is checked on both the scheduled and the manual-trigger path, and the Callout's claim about the artifact boot is the artifact test.

One row on that page is not true, and this PR neither introduced nor fixes it: under What the handler returns, "resolves { outcome: 'degraded', reason? } is recorded as degraded". Measured on the declarative path — schedule through a recording IJobService, capture the wrapper, call it:

HANDLER RESOLVED: {"outcome":"degraded","reason":"STORE_UNAVAILABLE"}
WRAPPER RESOLVED: undefined

The outcome is dropped before any adapter sees it. That is filed as #14256 with the measurement; the honest repair is its one-expression code fix, not a caveat in the page, which is why the page was left alone.

Verification

Union run after the final commit, at 72c20362.

• pnpm --filter @objectstack/runtime test — 206 files, 3048 tests, all passed (the whole package, not a subset), both before and after the backend migration.
• pnpm --filter @objectstack/service-job test — 9 files, 94 tests passed (the IJobService side, untouched and confirmed so).
• pnpm --filter @objectstack/runtime typecheck — clean. ⚠️ That config excludes **/*.test.ts, so it says nothing about the new test file; measured separately with the exclusion lifted (tsc --noEmit, exit 0, --listFiles confirming the file is in the program — 1 hit there versus 0 under the package config).
• New suite packages/runtime/src/app-plugin.job-data-reach.test.ts: 8 tests, including two firing positive controls — the same shipped callable invoked with the pre-change context rejects and the store is unchanged, so neither passing write assertion can be vacuous.
• pnpm check:driver-memory-census — reproduced red on the first head, green at 72c20362, ledger untouched.
• 53 of the 57 gate families derived by scripts/pm/dispatch-gates.mjs ran green, ratchets re-run at 72c20362. Plus all 38 families in that derivation's undetermined bucket — 36 green, 2 refusing on an unbuilt sibling package. That bucket is where the census gate lives: it declares no path population, so no path derivation can name it for any card, and running only the derived list is what let this one reach CI.

Not measured locally, each refusing on a stated prerequisite rather than failing: check:type-check-debt and check:dual-build-cjs-loads (exit 3 — both need the whole workspace built), check-test-completeness (exit 3 — grades a saved turbo log CI tees), scripts/pm/check-half-states.mjs (network-bound PM patrol), and, from the undetermined bucket, check:app-nav-i18n and @objectstack/client's check:exported-any-returns (both refuse rather than compute a false green over an unbuilt package). CI runs all of them.

Filed, not fixed

• filed as AppPlugin's declarative-job wrapper discards the handler's JobRunOutcome, so defineJob cannot report a degraded run #14256 — the same wrapper discards the handler's JobRunOutcome, so a declarative job that resolves { outcome: 'degraded' } is recorded as success. Adjacent to this seam but a different defect class (outbound, not inbound), so it is not folded in here. The measurement above is on the card.
• filed as app-showcase's nightly health sweep reaches its engine through a module-scope global, so it silently does nothing on an artifact-served boot #14257 — examples/app-showcase's nightly sweep still reaches its engine through the module-scope global, so it silently does nothing on an artifact-served boot. Now migratable to the context member this PR adds.

Independent of #14095, exactly as the card says: that one is about recognising a uniqueness violation once you can reach the store; this one is about reaching it at all.

Authored by Claude Code, session session_01Q5WBDtaUnoz5XuJ6jk8pQ5 (https://claude.ai/code/session_01Q5WBDtaUnoz5XuJ6jk8pQ5).

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/runtime, touching 3 documentable anchor(s). ⚠️1 changed file(s) yielded no anchor (packages/runtime/src/index.ts), so the pages documenting them are NOT COVERED by this run — this is not a clean bill of health for those files.

3 hand-written doc(s) NAME something this change touched and may need an implementation-accuracy re-verification:

• content/docs/automation/jobs.mdx(via JobHandlerContext (symbol, a top-level interface), jobId (symbol, a field of interface JobHandlerContext))
• content/docs/data-modeling/import-mappings.mdx(via jobId (symbol, a field of interface JobHandlerContext))
• content/docs/protocol/objectql/state-machine.mdx(via jobId (symbol, a field of interface JobHandlerContext))

What this run could not see

• 1 changed file(s) yielded no anchor (packages/runtime/src/index.ts) — pages documenting those are invisible to this run
• 1 cross-cutting symbol(s) contributed no route anchor: jobId (6 routes)
• 3 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 47 of 219 client-bound route-ledger rows — the other 172 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 172: 14 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 56 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 102 are undecided (no in-repo declaration, on a ledger that has other in-repo registrars — absence and an unreadable spelling are not distinguishable here). The rows themselves: node scripts/docs-audit/affected-docs.mjs --bridge-coverage
• a page that states a rule by its inputs shares no identifier with the emitter that implements the rule, so an emitter-only diff cannot list it — not on this run and not on any run. Measured on fix(driver-sql): emit varchar(maxLength) for a text field a declared index keys on #11430: content/docs/protocol/objectql/types.mdx documents the text-family column mapping by the ObjectQL type names it maps FROM (text / textarea / html) while the diff changed createColumn; it went unlisted, and it was the page that diff falsified, in four places. No shared token exists to detect this on, so a rule your change carries has to be re-read by hand in the pages that restate it.

Coarse fallback — 24 page(s) merely mention a changed package (the pre-#9192 predicate, kept for the deliberately-wide backstop): node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 — the merge of head 72c20362c0663aa27bbfb0cf834cfa3ce144528e into base 035951faf99c42c258d470102da7346f309f7346, which is what actions/checkout gives a pull_request run. Not the PR head.

A worktree cut from an older main holds a different content/docs, so re-deriving there can legitimately return a different list — that is a different tree, not a wrong row. To answer on the same tree:

# while this PR is open — GitHub drops the merge commit once it closes
git fetch origin 45e39eb79396d9b4150fc3c4f332e9dd601ecb90 && git checkout 45e39eb79396d9b4150fc3c4f332e9dd601ecb90
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 035951faf99c42c258d470102da7346f309f7346 72c20362c0663aa27bbfb0cf834cfa3ce144528e && git checkout -B drift-repro 035951faf99c42c258d470102da7346f309f7346 && git merge --no-ff 72c20362c0663aa27bbfb0cf834cfa3ce144528e
node scripts/docs-audit/affected-docs.mjs --json 035951faf99c42c258d470102da7346f309f7346

⚠️ That checkout carried uncommitted changes, so the commit above does not fully identify what was read.

Advisory only, and a precision-first one (#9192): a page is listed because it names a
symbol, wire route or SDK method this diff touched — not because it mentions a changed
package. Each row says which anchor put it there, so a wrong row is reportable rather than
merely annoying. To re-verify, run the docs-accuracy-audit workflow scoped to these files:
node scripts/docs-audit/affected-docs.mjs 035951faf99c42c258d470102da7346f309f7346 → pass the list as
args.docs, on the commit named under Which tree this was computed on.