`SettingsService.getMany`'s all-or-nothing key validation is undocumented on the contract that owns it

[huangyiirene]

Filed unassigned from the domain:engine seat while implementing #11222 (PR #11677). Routed here rather than fixed there: #11222's own body flagged this as possibly belonging on getMany's contract rather than at its first call site, and triage designated #11222 a core + rest card. Fixing it in packages/services/service-settings would have been a silent widening into a third package, so it is a card of its own — domain:services.

The behaviour

SettingsService.getMany (packages/services/service-settings/src/settings-service.ts) validates every requested key before loading a single row:

const reg = this.registry.get(namespace);
if (!reg) throw new UnknownNamespaceError(namespace);
for (const key of keys) {
 if (!reg.scopes.has(key)) throw new UnknownKeyError(namespace, key);
}

So one unknown key rejects the whole call — the caller gets nothing, not the subset that was declared. get has no such property: one key failing leaves the others answerable.

This is a legitimate design (a batched read either has a coherent manifest or it does not), and it is pinned — settings-getmany.test.ts asserts await expect(svc.getMany('localization', ['timezone', 'nope'])).rejects.toThrow(/nope/). What is missing is that getMany's doc comment never says it, even though the comment is otherwise detailed: it explains the row-load grouping, the env-override ordering, and claims row-for-row equivalence with per-key get "BY CONSTRUCTION". That equivalence claim is true for every key that resolves and false for the failure mode, and the doc does not draw the line.

Why it matters to a caller

Every batched consumer inherits the all-or-nothing rule, and the first one already had to write the consequence down locally. resolveLocalizationContext degrades correctly — PR #11677 records that a host registering a partial localization manifest loses all three keys at once and drops to a shorter cascade (no global scope layer, no OS_LOCALIZATION_* env override) where the per-key path would still have resolved the declared keys. That note is the caller's own degradation and belongs where it is. The rule it is a consequence of belongs on the producer, so consumer number two does not have to rediscover it from a test.

Unreachable against the in-repo localizationSettingsManifest, which declares all three keys — this is reachable only for a host with a partial manifest. Documentation, not a behaviour change.

Suggested shape

A paragraph on getMany's doc comment stating that key validation is up-front and total, that this is the one respect in which it is not equivalent to N get calls, and what a caller should expect on a partial manifest. No code change; the behaviour is correct and already pinned.

---

Generated by Claude Code

[os-zhuang]

Triage: lands on the contract text face (the SettingsService.getMany declaration in packages/spec) → domain:spec, type Task, pm:queue. Rationale: documenting enforced behaviour (all-or-nothing key validation) on the contract that owns it is declared=enforced convergence on the prose axis — spec text face, Clause-②: no expected (describe/JSDoc only, no accept-set change). If the implementing dev finds the honest fix is changing the behaviour instead of the text, that flips to a contract question — stop and report, don't pick silently.

---

Generated by Claude Code

[os-litant]

Claim: PM loop round R6 (wave 2)
Session: session_01NDGG54XF5gbTLdQzCtnaVV
Branch: claude/issue-11680-getmany-all-or-nothing-doc
Worktree: objectstack-issue-11680
Domain: domain:spec
File surface: the SettingsService.getMany declaration's JSDoc in packages/spec/src/contracts (located from the card) + a pin test for the documented behaviour if the contract test file carries siblings + changeset (patch) (stop on breach; explain in the report)
Container & model: S text-surface, mode:subagent, model: opus — dispatch-gates 2026-08-25 @8619f95: "no path-derived mandate … floor sonnet · default opus · ceiling fable"; contract-prose accuracy is editorial judgment no gate checks ⇒ default opus
Clause-②: no — with the triage fork clause carried: if the honest fix is changing BEHAVIOUR rather than text, stop and report (needs_decision), never pick silently
Serial constraints cleared: sole writer of the settings contract this batch; disjoint from all wave-2 siblings. No pin assertions on sibling behavior.

---

Generated by Claude Code

[os-litant]

os-dev-report

{
 "issue": 11680,
 "status": "done",
 "branch": "claude/issue-11680-getmany-all-or-nothing-doc",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/12169",
 "premise_still_valid": true,
 "summary": "The ISSUE's premise is intact and was verified line by line: SettingsService.getMany validates every requested key against the manifest before reading any env override and before loading any row, so one undeclared key rejects the whole call with UnknownKeyError (code SETTINGS_UNKNOWN_KEY) and the caller gets nothing, while the doc comment claimed row-for-row equivalence with per-key get 'BY CONSTRUCTION' without drawing that line. The TRIAGE premise is falsified, and this is the report's main deviation: getMany does not exist anywhere in packages/spec (git grep getMany -- packages/spec = zero hits; packages/spec/src/contracts holds 49 non-test contract modules and none is a settings service; the only SettingsService interfaces in the repo are SettingsServicePluginOptions and SettingsServiceOptions, both in packages/services/service-settings, and neither declares getMany). The contract that owns getMany is the concrete method's own JSDoc in packages/services/service-settings/src/settings-service.ts, exactly where the issue body pointed, so the fix landed there: a doc paragraph stating the all-or-nothing rule, its blast radius, why up-front validation makes the refusal independent of key order and scope grouping, and what a caller on a partial manifest should expect, plus a sibling pin and a patch changeset. Two consequences for the PM: the domain label is wrong (this is domain:services, as the issue body itself said) and the diff touches no packages/spec/** path, so the Clause-2 spec-surface review limb does not fire. The triage fork clause did NOT trigger: the honest fix was text, not behaviour, and the implementation file's diff is 34 added lines and 0 removed. Separately worth PM triage but NOT acted on here: triage assumed a spec-side settings service contract exists; none does, and whether one should is an architecture question with no pull behind it today.",
 "tests": "All at final commit 5067b79, after the last commit. (1) pnpm --filter @objectstack/service-settings typecheck (tsc --noEmit, script name echoed in output so not a zero-match silent pass) && pnpm --filter @objectstack/service-settings test -> 'Test Files 29 passed (29) / Tests 515 passed (515)'; run through scripts/pm/os-verify-lock.sh, which printed 'VERDICT command-exit 0 - held the lock 27s - waited 323s'. (2) Targeted: vitest run --maxWorkers=2 src/settings-getmany.test.ts -> 'Test Files 1 passed (1) / Tests 7 passed (7)', VERDICT command-exit 0. (3) ABLATION - deferred getMany's key validation until after the grouped row load, then restored. REBUILD: none required and none done, because the test imports './settings-service.js' RELATIVELY and vitest resolves that to src/ - there is no package exports -> dist hop on this path, so the mutation takes effect without a build; stated explicitly because rebuild-free is the exception. MUTATION CONFIRMED ON DISK (never from an editor exit code): the count of the literal 'if (!reg.scopes.has(key)) throw new UnknownKeyError(namespace, key);' in the file went 3 -> 2 (the getMany occurrence gone, get and setMany untouched) and the mutated getMany head was dumped and read back; the anchor-replacement step also asserted exactly 1 occurrence per anchor and would have aborted otherwise. RESTORE CONFIRMED ON DISK: injected marker count back to 0 and throw count back to 3; the script carried trap '<restore>' EXIT INT TERM and the trap fired. DIRECTION PREDICTED THEN OBSERVED: the new pin turned RED on expect(engine.find).toHaveBeenCalledTimes(0) - 'expected vi.fn() to be called +0 times, but got 2 times' - while the PRE-EXISTING rejects.toThrow(/nope/) pin stayed GREEN through the same ablation (6 passed / 1 failed), which is the measurement the new pin exists for; the restored tree re-ran 7/7 green. Honesty note: the mutation script annotated its marker count as 'expect 4' where 3 injection sites can only produce 3 - the stated expectation was wrong, not the observation, and the load-bearing proofs (3 -> 2 throw count, head dump) both held. (4) GATE UNION, families derived from the real change set by 'node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack' with no hand-built path list (it reported 3 paths vs merge base 577fabf27, three-dot semantics) - materially wider than the dispatch's guessed list. All exit 0, each read from a captured exit code and not through a pipe: check:nul-bytes, check:error-code-casing, check:changeset-gate-self-tests, check:objectui-changeset, check:published-files, check:slot-lookup, check:test-source-alias, check:type-source-resolution, check-adr-0087-registration, check-changeset-no-major, check-empty-changeset, check-plugin-teardown-shape, release-rehearsal-clone --self-test, docs-audit/check-affected-docs, plus the convention-triggered set for a test edit: check:query-options-erasure, check:engine-double-contract, check:where-matcher, check:cross-package-test-inputs, check:type-check-coverage. Dispatch-named gates with no derived population and no path of mine in scope (doc-formula-expressions, empty-state, liveness, merge-driver) were not run; the derivation did not name them for these paths. (5) LINT, NOT a narrowing: npx eslint . --no-inline-config --format json ran repo-wide and finished - 5220 files resolved by eslint's own config, 0 errors, 0 warnings. (6) NOT RUN LOCALLY, declared: check:type-check-debt --re-measure (refuses on an unbuilt worktree and needs the whole workspace closure built - a repo-scale run CI owns) and docs-audit/check-drift-comment (needs PR context). CI status at report time: in_progress - reported at draft-PR time per the standing contract, not waited on.",
 "open_questions": [],
 "out_of_scope_findings": [
 "NOT FILED (dedup channel unavailable, see below): packages/services/service-settings/src/settings-getmany.test.ts's ROWS fixture stores JSON TEXT in `value` ('\"America/New_York\"'), but sys_setting.value is a Field.json column and the service is verbatim in both directions - setMany writes `storedValue = rawValue` and materialiseRow's non-encrypted branch is `return row.value ?? null`, with the driver owning the JSON codec. The fake engine skips that codec and returns rows as written, so every value in this fixture resolves one JSON encoding deep. Invisible today because every assertion in the file compares getMany against get and both are equally affected - the same 'a fake that lies consistently' shape this file's own header warns about for $or matchers. Cost one test iteration here (an assertion on a literal value) and would mislead the next author who asserts a concrete value. Severity: observational, would carry the `finding` label and no pm:queue.",
 "SEAT/CHANNEL FINDING for the PM, not a repo defect: the dedup search this seat is required to do before filing ('search first, then file', via the REST list endpoint and explicitly NOT MCP list_issues/search_issues) is not reachable from this session. curl against api.github.com returns {\"message\":\"GitHub access is not enabled for this session. An org admin must connect the Claude GitHub App for this organization.\"}, GITHUB_TOKEN is a 14-character placeholder, and `gh` is not installed. Only the MCP github tools and the git proxy (push worked) are live. So the finding above was reported rather than filed without a duplicate check. This also means the curl-based `skip-changeset` label step in the dev contract is unreachable from this seat - it did not apply here (this PR ships a changeset), but it will silently fail for the next docs/tests-only card dispatched to this container."
 ]
}

---

Generated by Claude Code