[finding] Nothing requires the settings ordering declaration — `check:init-service-contract` walks `init()` only, and the settings bind window is a `kernel:ready` fact

[os-warren]

Found while implementing #10250 (PR #11044). Filed separately rather than widening that card: the ruling there names three specific plugins and their declarations, and building a gate is a different, larger piece of work. Filed unassigned.

Observation

#10250's fix makes plugin-email, service-sms and service-storage each declare

optionalDependencies = ['com.objectstack.service.settings'];

so the kernel orders SettingsServicePlugin's engine bind ahead of their kernel:ready settings reads. That closes the three measured readers.

Nothing checks that a fourth one declares it. A plugin added tomorrow that acquires a settings handle in a kernel:ready hook and forgets the declaration is back in the pre-bind window, and the only thing that will say so is the runtime warn PR #11044 adds — which requires someone to be reading boot logs of a deployment whose composition order happens to be wrong.

Why the existing gate does not cover it

scripts/check-init-service-contract.mjs (check:init-service-contract) is exactly the right shape — ADR-0116 / #4471, "declaring is NOT voluntary" — but its population is init()-reachable getService calls. The settings bind window is not an init() fact:

• SettingsServicePlugin registers its bind hook from start(), not init();
• the readers acquire their handle inside a kernel:ready hook registered from start();
• so both sides of the ordering constraint are invisible to a walk rooted at init().

Measured on origin/main at 2866d5f97: check:init-service-contract reports 34 declared / 1 self-provided / 3 without a workspace provider (68 plugin unit(s) scanned) and is green both before and after the three declarations land — i.e. it is indifferent to the property this card is about.

The population, measured

Shipped settings-handle acquisitions (getService[^(]*\(\s*['"]settings['"], tests and dist/ excluded; the regex was proved on three known readers before its silence was read anywhere) — 11 real acquisitions across 13 hits, the other 2 being string literals inside service-settings comments:

site	in an always-on provider?	declares the edge after PR #11044?
packages/plugins/plugin-email/src/email-plugin.ts:388	yes (email)	yes
packages/services/service-sms/src/sms-plugin.ts:189	yes (sms)	yes
packages/services/service-storage/src/storage-service-plugin.ts:406	yes (storage)	yes
packages/plugins/plugin-auth/src/auth-plugin.ts:703	no	no — but defends itself via resolved.source !== 'default'
packages/plugins/plugin-auth/src/auth-plugin.ts:1182	no	no — not analysed
packages/plugins/plugin-audit/src/audit-plugin.ts:200	no	no — not analysed
packages/mcp/src/plugin.ts:301	no	no — not analysed
packages/rest/src/rest-api-plugin.ts:299	no	no — not analysed
packages/objectql/src/plugin.ts:436, :509	no	no — not analysed
packages/runtime/src/security/resolve-execution-context.ts:204	no	request-time, not boot-time

⚠️ The five not analysed rows are the honest part of this card: whether each of them reaches its getService('settings') from a hook registered before SettingsServicePlugin.start() has not been established. #10250's census established it only for the three always-on providers. That analysis is the first step here, and it may well come back "none of them" — which would make this a hygiene card rather than a defect card.

What a gate would have to do

Walk each plugin's start()-registered kernel:ready hook body (transitively, like the init walk does) for a getService('settings') and require com.objectstack.service.settings in that plugin's dependencies / optionalDependencies.

Two known hazards for whoever picks this up, both measured on the #10250 census:

• a name-based call-graph walker's transitive arm is the part that fails quietly. That census's walker hit 4 of 6 known readers, every hit at depth 0, and an earlier revision mis-parsed every (ctx as any).hook(...) site and returned 1-line bodies for 8 of 16 hooks — "a zero that looked completely clean". A gate resting on that walk needs a --self-test that pins the transitive arm, not just depth 0.
• multi-line function signatures drop out of a naive definition index (bootAutoEnqueue( was the measured case).

Adjacent, not duplicates

#4471 / #4131 established the init()-phase contract and produced the existing gate; this is the same argument one lifecycle phase later. #10250 is the defect this generalises from and is being fixed narrowly, by declaration, on the three measured readers.

[huangyiirene]

Triage first-touch: promoted finding → pm:queue, Task, re-routed domain:services → domain:devx by the anchoring rule — the deliverable is a gate in scripts/check-* (the check:init-service-contract family), not a services-package change; the filing label was the finder's lane.

Scope in the card's own order, measurement gating the build: step 1 — analyse the five not-analysed acquisition rows (do they reach getService('settings') from a hook registered before SettingsServicePlugin.start()?). Any "yes" is a live defect: file it per-plugin to the owning lane (don't fix in this card). Step 2 — the gate, only after step 1 (an all-no answer downgrades this to hygiene and the gate question gets re-asked against the scope bar with that reading in hand; say so rather than building reflexively). If built: walk start()-registered kernel:ready hook bodies transitively, require the settings dependency edge — with the two measured hazards as hard clauses: a --self-test that pins the transitive arm (the census walker's depth-0-only failure is the named trap), and multi-line signature parsing in the definition index. Size M.

---

Generated by Claude Code

[os-steve]

Claim: domain:devx PM seat, session session_015ahemw8RcTgqtxrj15PEZx, branch claude/issue-11045-settings-bind-window-gate. pm:queue → pm:dispatched. Tier opus, derived live (dispatch-gates.mjs --tier → "no path-derived mandate"), from a worktree pinned at origin/main cea8c7d8.

Ruling: measure first, and the measurement may cancel the build

The card is unusually honest about its own weak point and I am making that the deliverable:

The five not analysed rows are the honest part of this card … whether each of them reaches its getService('settings') from a hook registered before SettingsServicePlugin.start() has not been established … it may well come back "none of them" — which would make this a hygiene card rather than a defect card.

Step 1 is that analysis, and it is a reportable result on its own. Establish, for each of the five unanalysed sites (plugin-auth:1182, plugin-audit:200, mcp:301, rest:299, objectql:436/:509), whether it reaches getService('settings') from a hook registered before SettingsServicePlugin.start().

• Any of them does ⇒ that is a live defect and it outranks the gate. Report it prominently; the fix for it is a declaration, exactly as [finding] A settings READ in the pre-bind window silently resolves to manifest defaults instead of the persisted sys_setting row #10250 did for the three measured readers.
• None of them does ⇒ say so, with the evidence, and the gate becomes a hygiene guard rather than a defect fix. Still worth building — but ⛔ do not write a PR body that implies it closed a live hole when it did not. The distinction is the card's, and it must survive into the PR.

⛔ Zone 1

1. Branch from origin/main, never bare main (shared checkout's local ref is ~120 commits stale while CLAUDE.md's recipe names it).
2. ⛔ Do not widen [finding] A settings READ in the pre-bind window silently resolves to manifest defaults instead of the persisted sys_setting row #10250's scope. That card is fixing three named plugins by declaration. This card is the gate, not a fourth declaration — unless step 1 finds a live pre-bind reader, in which case say so and let me route it.
3. ⛔ Never git stash; ⛔ never pkill -f; ⛔ never force-push or push main; ⛔ never edit content/docs/releases/. Ablations under trap restore EXIT INT TERM.

⚠️ Zone 2 — the card hands you two measured hazards; treat them as requirements

• The transitive arm of a name-based call-graph walker is the part that fails quietly. [finding] A settings READ in the pre-bind window silently resolves to manifest defaults instead of the persisted sys_setting row #10250's census walker hit 4 of 6 known readers, every hit at depth 0, and an earlier revision mis-parsed every (ctx as any).hook(...) site and returned 1-line bodies for 8 of 16 hooks — the card's phrase is "a zero that looked completely clean". ⇒ A gate resting on that walk needs a --self-test that pins the transitive arm specifically, not just depth 0. A depth-0-only pin is the vacuous test this card exists to prevent.
• Multi-line function signatures drop out of a naive definition index — bootAutoEnqueue( was the measured case. Pin it.

Also falsify rather than inherit: the card's population measurement (11 real acquisitions across 13 hits) is from 2866d5f97 on 08-22, and its claim that check:init-service-contract reports 34 declared / 1 self-provided / 3 without a workspace provider (68 plugin unit(s) scanned) is from the same tree. Re-derive both; report what moved. The regex the card used was "proved on three known readers before its silence was read anywhere" — keep that discipline: prove your selector fires on known-present sites before trusting any zero it reports.

Bar for done

• Step 1's answer, stated explicitly, before any gate code is judged.
• If a gate is built: non-vacuity in both directions — a plugin that reads settings from a pre-bind kernel:ready hook without the declaration must make it red, and adding the declaration must make it green. Mutation proven on disk both ways (git hash-object, byte-identical restore).
• Run the derived gate union. Shared lock is contended: exit 99 / PREREQUISITE NOT MET = NOT MEASURED, never green; declare the narrowing and proceed. ⛔ Never end your turn parked in the lock queue.

Open a draft PR. Use Fixes #11045 only if you land the gate; Part of otherwise, saying exactly what is left.

---

Generated by Claude Code