fix(service-settings): refuse a settings write issued before the engine is bound

[os-warren]

Fixes #10159

SettingsService.upsertRow picks its store on if (this.engine), and the engine is bound in exactly one place: SettingsServicePlugin registers a kernel:ready hook from its start() and calls bindEngine inside it. Hooks fire in registration order (hooks.get(name).push(...) in packages/core/src/kernel-base.ts, dispatched in array order) and every plugin's init() runs before any plugin's start() — so every kernel:ready hook registered from an init() runs inside that window. A set() from there landed in the in-process memory fallback, re-resolved off that same array, and handed the caller a fully resolved value while sys_setting received nothing and both audit ledgers stayed silent. Nothing was logged at any level, because the write did not fail: it succeeded against the wrong store.

Premise re-established on this branch before anything changed

A real LiteKernel, a real ObjectQL over the real SysSetting/SysSecret schemas, the real SettingsServicePlugin, and a probe plugin registering its kernel:ready hook from init():

                            BEFORE (origin/main)                    AFTER
serviceResolvableAtReady  : true                                  true
engineBoundAtReady        : false                                 false
writeAtReady              : resolved:"written-at-kernel-ready"    threw:SETTINGS_ENGINE_NOT_BOUND:503
readAtReady               : resolved:"written-at-kernel-ready"    resolved:"never"   (manifest default)
rowsInDbAfterBoot         : []                                    []
engineBoundAfterBoot      : true                                  true
rowsInDbAfterControlWrite : [ { receipt_probe, last_run, … } ]    [ { receipt_probe, last_run, … } ]
auditRowsAfterControlWrite: 1                                     1

One column is sourced differently and is flagged rather than blended in: readAtReady was not a field on the original pre-fix probe (it was added when the probe became the shipped test), so its BEFORE value is the ablation reading — the guard neutered on the fixed tree, which restores this code path to origin/main's behaviour. Every other BEFORE cell was measured directly on origin/main before anything changed.

The control write moments later lands a real sys_setting row and a real sys_setting_audit row on the same connection, so the store existed throughout — the timing is the whole cause. The named population is real and static: assembleMetadataProtocol registers the three platform migrations' kernel:ready hook from ObjectQLPlugin.init() (packages/objectql/src/plugin.ts, init = async at 303, well before start at 385 → packages/metadata-protocol/src/plugin.ts:306).

Loud refusal, not buffered replay — argued from measured consequences

Who is in the window today. Swept the repo for settings writers: zero .set( / .setMany( call sites against the settings service outside packages/services/service-settings itself, and the two inside it are the HTTP PUT handler (settings-routes.ts:137, which cannot run before kernel:listening) and setMany's own internal delegate. Counter-check on the same corpus with the same regex family: .get( / .getNamespace( returns ten shipped call sites, so the sweep works and the zero is a measurement rather than a broken pattern. No shipped startup sequence becomes an error.

Why a buffer cannot keep the promise the resolved value makes:

• Pre-flight is evaluated against the wrong store. setMany's env-lock and upper-scope-lock checks read through loadRows, which in the window reads memory — an in-window write is validated against a store that does not contain the persisted locks. Replaying it would commit a write a real pre-flight would have refused with SETTINGS_LOCKED. That is a correctness failure, not a bookkeeping one.
• Encrypted specifiers cannot be buffered safely. cryptoProvider and secretStore arrive on the same bindEngine call, so a buffer would have to hold plaintext in process memory until bind. In-window encrypted writes already refuse today (the plugin's default crypto is NoopCryptoAdapter, providesConfidentiality returns false, assertEncryptionAvailable throws) — buffering would make the write door less uniform, in the direction SETTINGS_CRYPTO_UNAVAILABLE exists to prevent.
• A replay has nobody left to report to. The caller was told "resolved" during boot; a replay failing at bind time re-creates the silent loss this card is about, one phase later.

What the refused caller does instead is a shipped, documented phase, named in the error message: kernel:bootstrapped, which plugin-lifecycle-events.ts already describes as the "all synchronous bootstrap has settled" anchor for exactly this class of work.

Clause-② determination: no — non-window callers observe nothing new

Decided before the fix was written, and pinned by tests rather than asserted. The refusal is armed only by the new opt-in SettingsServiceOptions.engineBindPending, which only SettingsServicePlugin sets (in init()) and which both branches of its kernel:ready hook clear — bindEngine when objectql resolves, the new SettingsService.settleWithoutEngine() when it does not. So the guard covers a declared, pending bind and nothing else:

population	before	after
write inside the window	resolves, nothing persists	SETTINGS_ENGINE_NOT_BOUND / 503
write after bind	persists to sys_setting + audit	unchanged
directly constructed SettingsService (unit test / bootstrap / control-plane mock)	resolves into memory	unchanged — declares no pending bind, guard never arms
lean kernel with no objectql	resolves into memory	unchanged after its kernel:ready hook settles the question (now with a warn that those values are lost on restart)
reads, in every state	resolve	unchanged

One surface addition is unavoidable for any refusal-shaped fix and is called out rather than buried: SETTINGS_ENGINE_NOT_BOUND is registered in ERROR_CODE_LEDGER (packages/spec/src/api/error-code-ledger.zod.ts) per ADR-0112. That widens the ErrorCode union by one member; it changes no existing envelope and no existing caller's accept/reject behaviour. The status (503, not SETTINGS_CRYPTO_UNAVAILABLE's 500 — this one is temporal, the identical write succeeds one phase later) is declared on the error class rather than at a sendError site because no HTTP door can reach it: the window closes at kernel:ready and sockets open at kernel:listening, strictly after.

Tests

packages/services/service-settings/src/settings-engine-bind-window.test.ts, six cases, driving a real kernel boot. Cases 4–6 are the Clause-② pins above.

The silent-loss direction is pinned explicitly. On the behaviour this replaces, sys_setting was also empty after the in-window write — so a case asserting only "no row landed" would have passed against the defect and tested nothing. The load-bearing assertion is the refusal: the probe records the write's outcome as a string, resolved:… on the old behaviour and threw:SETTINGS_ENGINE_NOT_BOUND:503 on the new one.

Ablation. Predicted signature stated first: neutering assertEngineBound to an unconditional return restores the silent accept, so the two in-window write cases and the standalone bindEngine case go red. Observed 4 red, not the predicted 3 — the extra one is real and is reported rather than smoothed over: case 2 (reads in the window are NOT gated) also reddened, with expected 'resolved:"written-at-kernel-ready"' to be 'resolved:"never"', because under the ablation the in-window write lands in memory and the in-window read then reads the phantom value straight back out. That is a second silent-loss witness, and case 2 now documents the coupling deliberately instead of carrying it by accident.

git hash-object packages/services/service-settings/src/settings-service.ts: ff35b55c7d25959350d185ea4db5ccffb8c953b2 before → 52ce662edcda238953c83bb543a5e6139a1bfc4e neutered → ff35b55c7d25959350d185ea4db5ccffb8c953b2 restored, byte-identical, with the ablation marker absent from the tree and git status clean.

Rebuild statement, argued from the files rather than recited. No rebuild was required for this ablation, and the reason is that dist is nowhere in the resolution path of the mutated file. The tests import the subject through relative specifiers (./settings-service.js), which vitest resolves to src/*.ts in the same directory — no package exports involved. Every cross-package specifier they do use is aliased to source by this package's own vitest.config.ts (@objectstack/core, @objectstack/objectql, @objectstack/platform-objects[/system], @objectstack/spec[/*], @objectstack/types), which is why this package carries no KNOWN_UNALIASED_TEST_IMPORTS entry. The decisive check rather than the argument: packages/services/service-settings/dist/ does not exist in this worktree, and the new cases pass asserting new behaviour — there is no build artifact they could have been reading.

Gates

node scripts/pm/dispatch-gates.mjs (no paths passed — the script derives the change set from the merge base itself) run after the final commit, on a clean worktree. Exit codes captured by redirecting each gate to a file first and reading $? before any pipe, never through tail.

All at cd161cb2d (git rev-parse --short HEAD), which is also the sha the package suite and the ablation above were measured on.

gate	exit	verdict line (the gate's own)
check:nul-bytes	0	—
check:changeset-gate-self-tests	0	—
check:cross-package-test-inputs (both spellings)	0	—
check:dispatcher-error-vocabulary	0	—
lint check:doc-formula-expressions	0	—
spec check:empty-state	0	—
check:error-code-casing	0	—
spec check:liveness	0	—
check:merge-driver	0	—
check:objectui-changeset	0	—
check:slot-lookup	0	—
check:spec-parsed-alias	0	—
spec check:strictness-ledger	0	—
check:test-source-alias	0	—
check:type-source-resolution	0	—
spec check:variant-docs	0	—
check-adr-0087-registration	0	—
check-changeset-no-major	0	—
check-empty-changeset	0	—
docs-audit/check-affected-docs	0	—
check:query-options-erasure	0	—
check:type-check-coverage	0	check-type-check-coverage: OK — 64/77 workspace packages type-checked (plus the root), 13 in the DEBT ledger
check:type-check-debt (--re-measure)	0	check-type-check-coverage --re-measure: OK — 33 ledger entr(ies) re-measured in 238.5s, 1924 raw tsc error(s) total, none above its recorded number.
check:engine-double-contract	0	—
check:where-matcher	0	—
check-dev-prereqs	1 → 0	first run: ✗ The workspace is not built — 1 unmet precondition, not a list of problems. An unbuilt-worktree precondition, not this diff — after turbo run build (exit 0) it re-ran green: ✓ 67 package build artifacts present.

Package suite, at the same sha: pnpm --filter @objectstack/service-settings test → Test Files 24 passed (24) · Tests 462 passed (462) (456 before, +6 new); pnpm --filter @objectstack/service-settings typecheck → exit 0.

check:type-check-coverage ledger entries were not raised — the --re-measure verdict above says none is above its recorded number.

Deliberately not done

• Reads in the window are not addressed here and remain a separate question: an in-window get() resolves from manifest defaults / the memory fallback rather than from persisted sys_setting rows, so a boot-time reader can legitimately see a stale value. That is a different defect from this card's silent write loss, and closing it would change what a real population observes. Filed as [finding] A settings READ in the pre-bind window silently resolves to manifest defaults instead of the persisted sys_setting row #10250 (unassigned, finding — the population is not yet measured).
• No content/docs/releases/ edit, no check-type-check-coverage ledger movement, and no attempt to make the window smaller — a narrower silent-loss window would still be a silent-loss window.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 2 package(s): @objectstack/service-settings, @objectstack/spec, touching 10 documentable anchor(s).

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

• content/docs/api/error-catalog.mdx (via ERROR_CODE_LEDGER (symbol))
• content/docs/api/error-handling-server.mdx (via ERROR_CODE_LEDGER (symbol))
• content/docs/data-modeling/drivers.mdx (via SettingsService (symbol))
• content/docs/kernel/contracts/data-engine.mdx (via ERROR_CODE_LEDGER (symbol))
• content/docs/kernel/runtime-services/settings-service.mdx (via setMany (symbol))
• content/docs/protocol/kernel/config-resolution.mdx (via SettingsService (symbol), SettingsServiceOptions (symbol), setMany (symbol))
• content/docs/protocol/kernel/index.mdx (via SettingsService (symbol), SettingsServicePlugin (symbol))

⛔ 2 release-owned page(s) also name something this change touched. These are read-only:

• content/docs/releases/v14.mdx (via setMany (symbol))
• content/docs/releases/v17.mdx (via ERROR_CODE_LEDGER (symbol))

content/docs/releases/ is RELEASE-OWNED (AGENTS.md "Documentation Guardrails"): release
notes are written centrally at release time, and a code PR that edits them is the exact PR
that guardrail exists to stop. They are still audited — read-only. If one of them is actually
wrong, file an issue or open a dedicated docs-only PR; do not edit it here.

What this run could not see

• 1 changed file(s) yielded no anchor (packages/services/service-settings/src/index.ts) — pages documenting those are invisible to this run
• 2 name(s) were too generic to anchor anything (single lowercase words)
• the SDK route bridge reached 45 of 221 client-bound route-ledger rows — the other 176 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run: node scripts/docs-audit/affected-docs.mjs --bridge-coverage

Coarse fallback — 124 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 359f5956d7910aed7ae9f8fccc9fbb988b3e4882 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from bffafa173c08a0603eecb300b6ac11a0dcd9310b — the merge of head 8b2c585286a2402f5cf25f618e5c2681dfe70e06 into base 359f5956d7910aed7ae9f8fccc9fbb988b3e4882, 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 bffafa173c08a0603eecb300b6ac11a0dcd9310b && git checkout bffafa173c08a0603eecb300b6ac11a0dcd9310b
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin 359f5956d7910aed7ae9f8fccc9fbb988b3e4882 8b2c585286a2402f5cf25f618e5c2681dfe70e06 && git checkout -B drift-repro 359f5956d7910aed7ae9f8fccc9fbb988b3e4882 && git merge --no-ff 8b2c585286a2402f5cf25f618e5c2681dfe70e06

node scripts/docs-audit/affected-docs.mjs --json 359f5956d7910aed7ae9f8fccc9fbb988b3e4882

⚠️ 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 359f5956d7910aed7ae9f8fccc9fbb988b3e4882 → pass the list as
args.docs, on the commit named under Which tree this was computed on.