fix(plugin-auth): declare the settings ordering edge so saved auth settings apply at boot

[os-sam]

Fixes#11579

The defect

SettingsServicePlugin registers the settings service in init() but binds its data engine from a kernel:ready hook it registers in start(). Between those two moments the service is resolvable and answers reads — from an empty in-memory fallback and the manifest defaults, with source: 'default' — while the deployment's real sys_setting rows sit unread. Nothing distinguishes that from "no row exists".

AuthPlugin was reading inside that window. Its start()-registered kernel:ready hooks reach getService('settings') at depth 3 (runBackfill → ensureAuthSettingsBound → bindAuthSettings) and call getNamespace('auth') in the same tick. Handlers fire in registration order, registration order is start() order, and AuthPlugin declared dependencies: ['com.objectstack.engine.objectql'] and nothing about settings.

On the shipped composition the resulting order was wrong, not merely unconstrained: os serve does kernel.use(new AuthPlugin(...)) before the capability loop registers SettingsServicePlugin, and resolvePluginOrder preserves insertion order for plugins with no edge between them. So everything applySettings() derives was computed from DEFAULTS at boot — the ADR-0093 membership policy the D6 backfill runs under, and the google_* social-provider config — and settings.subscribe('auth', …) only re-applies on a later change. A workspace that configured auth in Setup and never touched it again kept booting with the wrong values: authored, stored, and silently not applied.

The repair

One declaration, the #10250 shape the three other shipped readers (plugin-email, service-sms, service-storage) already carry:

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

SOFT, not hard — a kernel with no settings service must still boot auth, and bindAuthSettings already returns early when the service is absent. requiresServices would not have done it: it asserts the service is REGISTERED before init(), which it always is, and carries no start() ordering.

The acceptance test: the gate's own ledger shrinks

KNOWN_PRE_BIND_READS in scripts/check-settings-bind-window.mjs is shrink-only and errors on a stale entry, so deleting the com.objectstack.auth row is part of the repair rather than follow-up. No entry was added, re-added or weakened — the com.objectstack.mcp row (#11580, a different lane) is untouched.

The green is a measurement, not a suppression, because the red was measured first — the entry deleted with the defect still standing:

✗ settings bind-window guard (#11045)
packages/plugins/plugin-auth/src/auth-plugin.ts:1207 — AuthPlugin
A 'kernel:ready' handler registered from start() resolves getService('settings')
(directly or through a helper it calls), and NOTHING declares that this plugin
must start after 'com.objectstack.service.settings'. ...
1 settings read(s) in the pre-bind window with no declaration covering them.

With the declaration in place, at 87d39a7e9e:

✓ settings bind-window: 4 declared / 0 self / 1 structurally upstream / 1 ledgered
(68 plugin unit(s) scanned, provider 'com.objectstack.service.settings').

3 declared / 2 ledgered → 4 declared / 1 ledgered: auth moved from the ledger into the declared column. --self-test also passes (its case 2b is literally this fixed shape).

ADR-0049 — declared is enforced

packages/plugins/plugin-auth/src/auth-settings-ordering.pin.test.ts, 5 cases, all green:

1. the edge is declared, and as optionalDependencies rather than dependencies;
2. it moves resolution order — a hostile registry composing auth before settings resolves settings first;
3. …and the declaration is what does it — stripped from a live instance, the order reverts (the case that keeps 2 from passing vacuously);
4. the edge is SOFT — a registry with no settings plugin still resolves;
5. no cycle — settings declares only com.objectstack.engine.objectql, so this direction is free.

The settings plugin is a name-only stub there (resolvePluginOrder reads only the OrderablePlugin surface); that com.objectstack.service.settings is the real provider id is check:settings-bind-window's job, which DERIVES the provider from providesServices: ['settings']. The header states that division of labour so neither claim is assumed to be the other's.

Verification

Union re-run after the final commit, at 87d39a7e9e:

check	verdict
check:settings-bind-window	✓ 4 declared / 0 self / 1 structurally upstream / 1 ledgered
check:settings-bind-window --self-test	✓ all cases pass
@objectstack/plugin-auth suite	Test Files 73 passed (73) · Tests 1480 passed (1480)
@objectstack/plugin-auth typecheck	VERDICT command-exit 0 (after building the package's own dist/)
check:nul-bytes	OK (scanned 6501 text file(s) ... no raw ASCII control bytes)
check:test-source-alias	OK — 72 packages with tests scanned (no registry change needed)
check:slot-lookup	✓ ratchet holds: 107 unswept site(s), none new
check:query-options-erasure	✓ ratchet holds: 67 unswept non-test site(s), none new
check:engine-double-contract	379 (file, verb) row(s) held by the RETAINED ledger
check:where-matcher	✓ 292 matcher(s) discovered, 292 conformant
check:type-check-coverage	OK — 65/78 packages type-checked, 13 in DEBT
check:cross-package-test-inputs	OK: 16 package(s) read outside themselves, all declared

Also green before the commit, on the same content: check:auth-mount-ledger, check:route-envelope, check:plugin-teardown-shape, check:published-files, check:entry-guard, check:parse-guard, check:pnpm-filter-targets, check:ci-filter-parity, check:type-source-resolution, the changeset family (check-empty-changeset, check-changeset-no-major, check-adr-0087-registration, check:objectui-changeset, check:changeset-gate-self-tests, release-rehearsal-clone --self-test) and docs-audit/check-affected-docs. Gate list derived with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack from the real change set, not from a hand-written diff.

The zero-margin ratchet this change could have moved

TEST_DEBT['@objectstack/plugin-auth'] records 97 raw tsc errors with no margin ("the next new error here goes red immediately"), and this PR adds a test file. The package's own tsconfig.json excludes **/*.test.ts, so the green package typecheck does not cover the new file — measuring it needed the test exclusion lifted, which is what measureTestDebt does. Mirrored locally with a temp in-package project (removed afterwards, verified absent on disk) against the built dependency closure:

RAW_ERROR_LINES_TOTAL=97
LINES_MENTIONING_MY_NEW_TEST_FILE=0
SETUP_ERRORS(must be 0)=0

97 is the ledger's recorded number exactly, which is what makes the instrument credible rather than merely quiet — the new file contributes zero.

Lint: a declared narrowing, not a repo-wide run

Repo-wide pnpm lint was not run locally; the shared verify lock had a holder plus a waiter and queuing it risked the foreground cap. Narrowed instead, with the three pieces of evidence a narrowing needs:

1. population read from eslint's own config — the run reports .changeset/…md as "File ignored because no matching configuration was supplied", i.e. eslint decided the population, not I;
2. count from --format json — 4 results, 3 linted, errorCount=0, warningCount=0 on all three code files;
3. invariance for untouched files — eslint.config.mjs states in its own docblock that this repo "runs one eslint.config.mjs, which never enables type-aware linting (no parserOptions.project, no typed @typescript-eslint rules) for ANY file", and this diff changes no eslint config, so no untouched file's verdict can move.

CI runs the farm exactly once regardless.

Not measured

• check:type-check-debt --re-measure was not run whole (it refuses without the entire ledgered closure built). The one entry this change could move was measured directly, above.
• Repo-wide pnpm lint, per the declared narrowing.
• No runtime/browser dogfood: the change is a declaration read by resolvePluginOrder, and the ordering claim is pinned by the new test rather than by a boot.

Scope

packages/mcp carries the same pre-bind class in a different lane and is untouched here; #11580 remains open for it. No packages/spec/**, no content/docs/releases/**, no governed surfaces. Not flipped ready, not enqueued, no auto-merge.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/plugin-auth, touching 3 documentable anchor(s).

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

• content/docs/deployment/cli.mdx(via AuthPlugin (symbol))
• content/docs/deployment/tenancy-modes.mdx(via AuthPlugin (symbol))
• content/docs/kernel/services-checklist.mdx(via AuthPlugin (symbol))
• content/docs/permissions/authentication.mdx(via AuthPlugin (symbol))
• content/docs/permissions/record-view-auditing.mdx(via AuthPlugin (symbol))
• content/docs/plugins/anatomy.mdx(via optionalDependencies (symbol))
• content/docs/plugins/index.mdx(via AuthPlugin (symbol))
• content/docs/plugins/packages.mdx(via AuthPlugin (symbol))
• content/docs/protocol/kernel/lifecycle.mdx(via optionalDependencies (symbol))
• content/docs/protocol/kernel/plugin-spec.mdx(via optionalDependencies (symbol))

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

• content/docs/releases/v17.mdx(via optionalDependencies (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

• the SDK route bridge reached 45 of 222 client-bound route-ledger rows — the other 177 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 — 11 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 d15ddba02c698ec4116b2f032bc99c235095bad4 → packageMentionDocs.

Which tree this was computed on

This run read content/docs from 8c2800ff720252a3345270e84e056348f134e340 — the merge of head 87d39a7e9ec3e57ec4877aa37627d9dc7b2c7bd2 into base d15ddba02c698ec4116b2f032bc99c235095bad4, 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 8c2800ff720252a3345270e84e056348f134e340 && git checkout 8c2800ff720252a3345270e84e056348f134e340
# afterwards, rebuild it from the two parents, which stay fetchable
git fetch origin d15ddba02c698ec4116b2f032bc99c235095bad4 87d39a7e9ec3e57ec4877aa37627d9dc7b2c7bd2 && git checkout -B drift-repro d15ddba02c698ec4116b2f032bc99c235095bad4 && git merge --no-ff 87d39a7e9ec3e57ec4877aa37627d9dc7b2c7bd2
node scripts/docs-audit/affected-docs.mjs --json d15ddba02c698ec4116b2f032bc99c235095bad4

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