fix(service-settings)!: the user rung answers only its owner; a user-scoped write must name its user

[objectstack-fleet]

Fixes #22168

Clause-②: no (narrowing)

SettingsService now treats the user rung as belonging to one user, on both its read side and its write side. This is the defensive fix the seat review on the card ruled, in two halves. One file changes (packages/services/service-settings/src/settings-service.ts), with a pin file and a minor changeset that declares the narrowing.

What changes

Read half: resolveKeyFromRows. The cascade walk now takes the caller's user id. The user rung answers only a row whose user_id equals that id. A resolve whose context names no user (no userId, or an empty one) has no user rung: it answers from the tenant rung, then global, then the manifest default, exactly as if no user row existed. get and getMany pass the id through, with one helper (callerUserIdOf) as the single definition of "present". getNamespace, createClient, runAction, resetNamespace and setMany's own re-resolve all reach the cascade through get or getMany, so every read path gets the same answer. The engine-bound store and the no-engine in-memory fallback share the pick, so both are covered.

Write half: setMany, ruled A. A key declared scope: 'user' in a batch whose context names no user is refused with SettingsValidationError (SETTINGS_VALIDATION). Each such key gets one fields entry: field names the key, code: 'invalid_value' and constraint: { scope: 'user' }. The check runs in the pre-flight, before validation, before any row load for that key and before any write, and it refuses the whole batch. A null reset of such a key is refused too: the only row it could touch has no owner, and no reader returns that row any more.

Unchanged:

• A caller with a user id reads and writes only their own rows.
• Tenant and global keys resolve and write the same with or without a user id.
• The settings HTTP routes are unaffected. Their context comes from the verified authz resolution, which either names a user or carries no permissions, and the manifest permission gate runs before any row load.
• The tenant rung's organization comparison is untouched. feat(objectql,cli): inventory + migration — four fates per object, mirrors deleted only after the id→name rewrite is verified, per-table boot report (ADR-0131 D10) #15211 is not addressed here.

Why SETTINGS_VALIDATION and not a new code

I checked the service's existing error vocabulary first, as the dispatch asked. SettingsValidationError already refuses a whole batch before any write, with one FieldError per key. It also already carries a refusal that is not about the submitted value: the manifest-side visible predicate, under invalid_value, ADR-0114's slot for "rejected for a reason no other member names". SETTINGS_FORBIDDEN is defined as the HTTP-boundary capability refusal, and its message names a capability. SETTINGS_LOCKED drives the lock affordances. A new code would also need a ledger row in packages/spec, which is outside this card's fence.

Reach (the round-1 census, re-read on this base)

The shipped settings manifests declare no scope: 'user' key at manifest or specifier level. That was true at the claim's base and still is at 0e9371f0c6. So no in-repo caller meets either half today. The in-process writers are the HTTP routes and the service's own set and resetNamespace, and the HTTP door always carries a user. The change is latent and defensive. It takes effect the first time a manifest declares a user-scoped key.

Tests

Measured at fd24546953. Every run went through scripts/pm/os-verify-lock.sh.

• New pin file settings-user-rung-owner.pin.test.ts, 65 cases, run on both stores:
  • a resolve with no user id never answers a user-scoped row, on each read path (get, getMany, getNamespace, createClient, runAction), for an empty context, a tenant-only context and an empty-string user id;
  • the fall-through order (tenant, then global, then the default) for a resolve with no user id;
  • a reset with no user id counts no user row and writes nothing;
  • the user-rung pick compares the owner itself, even when the store returns more rows than the query asked for;
  • a write of a user-scoped key with no user id is refused, with the envelope (code plus fields), stores nothing and emits no change event, and a mixed batch is refused whole;
  • controls: per-user reads and writes, the owner's row above the tenant rung, and tenant and global keys with and without a user id.
• Before the fix, on the base source: 34 failed and 26 passed. Every negative pin was red and every control was green. One control was split before commit because it also asserted a read with no user. The two load-bearing pins were added in the second commit; ablations M1 and M2 below make them red.
• With the fix: pnpm --filter @objectstack/service-settings exec vitest run --maxWorkers=2 gave 39 files and 702 tests passed. pnpm --filter @objectstack/service-settings typecheck gave exit 0, and --listFiles shows the pin file is part of that program.
• Ablation, run from the committed state through scripts/ablation-replace.mjs (anchor hit once, blob changed, restore proven equal to HEAD, git diff HEAD empty), with a bash trap restore as well. Every leg turned red, and no control failed:
  • M1, the presence check removed from the user-rung pick: 39 of 65 failed. These were the no-user read pins on both stores, the fall-through, the reset and the over-answer pin. An ownerless legacy row is what makes this check load-bearing.
  • M2, the owner comparison removed: 5 of 65 failed. These were the over-answer pin on each read path. With the current loaders a present user id only loads its own rows, so this is the pin that holds the comparison.
  • M12, both removed: 39 of 65 failed.
  • M3, the refusal disarmed: 8 of 65 failed. These were the no-user write pins on both stores and the batch pin.

Acceptance notes

• The load with no user id still reads every user's user rows (loadScopedRows and the in-memory filter). With the pick narrowed, those rows are inert for the cascade. Narrowing the load itself is defence in depth and is outside this card's fence. Carrier: none.
• Ownerless user rows written before this change, by a write with no user id, stay in the store. No reader returns them now. The service cannot clear one either, because a null write with no user id is refused. No in-repo writer could have produced one, since no shipped manifest declares a user-scoped key.
• resetNamespace on a user-scoped key whose effective value comes from the tenant or global rung writes null at the key's declared (user) rung, so the upper value stays in force even though it is counted as cleared. This was there before this change and is a reading, not measured. With no user id, that path now meets the write refusal instead of storing an ownerless row. Carrier: none.
• Docs: the "Writes fail loudly" table in content/docs/protocol/kernel/config-resolution.mdx has no row for this refusal. That file is outside this card's fence. Carrier: none.

---

Generated by Claude Code

[github-actions]

📓 Docs Drift Check

This PR changes 1 package(s): @objectstack/service-settings, touching 8 documentable anchor(s).

26 hand-written doc(s) name something this change touched — list omitted above 15 rows. Re-derive on the tree named below: node scripts/docs-audit/affected-docs.mjs --json f4bed58341c16062b63bd95864aea53839293745.

⛔ 5 release-owned page(s) also affected — read-only, see AGENTS.md Documentation Guardrails.

What this run could not see

• the SDK route bridge reached 54 of 206 client-bound route-ledger rows — the other 152 have no registrar path: tail to select them, so pages documenting THEIR client methods cannot appear above, on this or any run. Of those 152: 0 are remediable by widening that discovery convention (an in-repo file declares the path; the convention did not scan it); 55 are structural — on a ledger where NOT ONE row is declared in-repo, so no discovery change reaches them at any price; 97 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.
• a key NAME is not a key, so the hand re-read the line above prescribes can land on the wrong schema. The same spelling is authorable on one governed type and a [REMOVED] tombstone on another for each of active, aria, joins, objects, template, tools and version (censused on [finding] tools is a key on BOTH AgentSchema (tombstoned, dead) and SkillSchema (live, cloud-attested), so a name-based search attributes skill examples to the agent key — it produced a false stop-the-line alarm on PR #19059 #19093 over the liveness ledger's governed types, top-level keys); nothing in a search result distinguishes the two, so a grep hit on a LIVE example reads as evidence about the DEAD key. Measured on fix(spec): the agent.tools liveness row says dead — it claimed live on a key the schema tombstoned #19059: content/docs/ai/agents.mdx was reported as contradicting the agent.tools tombstone over its tools: example at :161, which is inside the defineSkill({ block opened at :155 — the page was already correct. Settle ownership by PARSING the value against both schemas, never by the name: that literal PASSES SkillSchema, and as an AgentSchema it FAILS at tools with the tombstone prescription. ⛔ These names are not the whole class — a key retired through a .strict() guidance map leaves no tombstone in the walked shape and none of them here (tool.category, live as AIToolDefinition.category).

Coarse fallback — 8 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 f4bed58341c16062b63bd95864aea53839293745 → packageMentionDocs.

Which tree this was computed on

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

node scripts/docs-audit/affected-docs.mjs --json f4bed58341c16062b63bd95864aea53839293745

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