[finding] The localization getMany switch leaves two stale declarations, an unpinned leg count, and a resolution context no pin can see

[os-zhuang]

Filed unassigned as a finding — recording only, not graded. Found while reviewing PR #11208 (the caller half of #10826) from the domain:engine seat. ⛔ None of this blocked that PR and none of it should: #11208 is correct, feature-detected, preserves #10221's failure-cache semantics, and carries the card's calibration in both its code comments and its changeset. Everything below is follow-up material.

Four items, related only by all being consequences of the same one-line switch from three settings.get() calls to one settings.getMany().

1. Two declaration sites now under-state what the consumer calls

resolveLocalizationContext now calls getMany. Two declarations still say it calls only get:

• packages/core/src/security/resolve-authz-context.ts:650 — the param JSDoc sitting on the very parameter whose consumption changed:

  /** Settings service exposing `get(namespace, key, { tenantId, userId })`. */
  settings?: any;

• packages/rest/src/rest-api-plugin.ts:60 — interface SettingsReadSurface, whose own prose reads "The one method the platform consumes is get, through resolveLocalizationContext's 4-tier timezone/locale/currency cascade." Note SettingsReadSurface is declared per-consumer: plugin-auth/src/auth-plugin.ts:77 and a reference in plugin-email/src/email-plugin.ts:159 name their own. getMany appears in none of them.

Nothing breaks, and the reason is itself the finding. The type is erased three times before reaching the call site: ctx.getService<SettingsReadSurface>('settings') is a cast, not a structural check (nothing in the repo implements it); rest-server.ts:840 widens it to Promise<any | undefined>; and resolve-authz-context.ts:651 receives settings?: any. So settings.getMany is never type-checked anywhere — which is exactly why CI is green without the declaration — and TS erasure means a narrow declaration cannot strip the method off the real object, so the feature-detect sees it regardless.

No gate covers this. check:slot-lookup (the #4251 ratchet) is the only gate on this slot, and it bans erasing a service lookup to any — rest-api-plugin.ts is not in scripts/slot-lookup-baseline.json, i.e. already swept. The gate enforces that the lookup is typed, never that the type is complete. This declared≠actual shape is mechanically invisible.

Cost, honestly bounded: a host author reading SettingsReadSurface to decide what their settings occupant must implement is told getMany is not consumed. Believing it is safe — their occupant takes the three-read path, because the feature-detect degrades correctly. So the blast radius is a false declaration plus an unrealized optimization, not a wrong answer. That is what keeps it a finding rather than a defect.

Fix is ~2 lines across the two sites. Runtime's own lookup (resolve-execution-context.ts:204) is untyped, so there is no fourth site.

2. The card's own metric — legs — is pinned by nothing

#10826's calibration is explicitly "this is a query-count fix, not a latency fix", because cloud#1539 measured the three reads running in parallel: 3 queries but 1 leg, and legs are the latency multiplier.

Queries are now pinned — correcting an initial misreading of mine: #11208's pins do assert numbers, not just behaviour (expect(getMany.calls).toBe(1), expect(ql.counts.sys_setting ?? 0).toBe(0), and expect(gets).toBe(3) on the legacy path). Composed with #11200's engine-level pin, the 3→1 query claim is covered across both packages.

Legs are not. #11208's getMany double is a stub modelling no row load and no concurrency. So a future edit turning the fallback into a sequential for loop takes legs 1→3 while every existing assertion stays green (gets === 3 counts calls, not waves). The one number distinguishing "not a latency fix" from "a latency regression" is unmeasured.

A working rig exists: counting a leg as a row load starting while none is in flight reverse-verified as expected { queries: 3, legs: 1 } to deeply equal { queries: 1, legs: 1 }. See the comment below.

3. No pin can see the resolution context

Pin 1 asserts the namespace and [...keys].sort(), but its getMany double is declared (ns: string, keys: readonly string[]) — two parameters. It structurally cannot observe the third argument. Drop sctx from the production call and all three pins stay green.

Harmless today: all three localization keys are tenant-scoped, so getMany routes them to loadRows(namespace, null) and ignores ctx.userId. It becomes a live scoping hole the moment any localization key becomes user-scoped.

4. One genuinely non-equivalent case, undocumented: partial-manifest key failure

Not a difference between implementations — every batched approach inherits it — but nobody has written it down.

• Before: one key's get throws (e.g. UnknownKeyError); the other two still resolve through the manifest cascade and answer.
• After: getMany validates every key up front and throws for the whole call, so all three go unresolved and the request drops to the direct tenant-scoped $in read — which loses the global scope layer and the OS_LOCALIZATION_* env overrides.

Unreachable against the in-repo localizationSettingsManifest (it declares all three keys); reachable only for a host registering a partial localization manifest. Degradation, not a wrong answer.

⚠️ Worth checking whether it should be documented on getMany itself rather than at this call site — the all-or-nothing validation is the service's contract, and this caller is just its first consumer.

Suggested disposition

One card fixing items 1–3 (two declaration lines, a leg assertion, an sctx assertion) and adding a sentence for item 4. Item 1 belongs to whoever owns the declarations; items 2–3 are test-only. ⛔ Not graded, no domain:* set, no pm:queue — triage's to route.

[os-zhuang]

Salvaged artifact — from a duplicate dispatch that will NOT ship as its own PR

⛔ Not a competing implementation. This seat was dispatched on #10826 in parallel with the work that became PR #11208, which is the implementation that lands. The local commit this rig came from is being discarded and its worktree torn down; nothing here will be pushed, and no PR will be opened from it. Posting only the measurement harness, because it is the hard part of item 2 above and whoever picks that card up should not have to rebuild it.

⚠️ Written against pre-#11208 source — it needs rebasing onto the landed getMany path. It was authored on a branch cut from 21756b325, before #11208 existed. Nothing in it is exotic, but expect at least these adjustments: the EXPECTED/VALUES constants and makeCountingQl helper already exist in resolve-authz-context.test.ts; and the BEFORE case below only runs at all because the landed implementation keeps a per-key fallback for occupants without getMany — verify that is still true before trusting it as a before-state.

How the leg count works

The one idea worth keeping. loadRows stands in for the real service's namespace row load, so one call is one sys_setting query. A leg is a row load that starts while nothing else is in flight — i.e. the number of sequential round-trip waves. Three loads issued inside one Promise.all all increment inFlight synchronously before any of them resumes past its first await, so they count as one leg; three awaited in sequence count as three. That is the leg definition cloud#1539 used, and it is what makes "3 queries, 1 leg" measurable rather than asserted.

 /**
 * A settings-service double that MEASURES what the resolver asks for.
 *
 * - `queries` — every row load.
 * - `legs` — every row load that STARTS while nothing else is in
 * flight, i.e. the number of sequential round-trip waves.
 *
 * `batched: false` reproduces the pre-#10826 occupant (only `get`), which is
 * also the shape the resolver still falls back to for a host-provided
 * settings service that predates `getMany`.
 */
 function makeSettingsRig(
 values: Record[string, unknown],
 { batched }: { batched: boolean },
 ) {
 const stats = { queries: 0, legs: 0 };
 const calls: Array[{ method: string; args: any[] }] = [];
 let inFlight = 0;
 const loadRows = async () => {
 stats.queries += 1;
 if (inFlight === 0) stats.legs += 1; // nothing else in flight -> a new wave
 inFlight += 1;
 try {
 await Promise.resolve();
 return values;
 } finally {
 inFlight -= 1;
 }
 };
 const pick = (loaded: Record[string, unknown], key: string) =>
 key in loaded ? { value: loaded[key], source: 'tenant' } : { value: undefined, source: 'default' };
 const rig: any = {
 stats,
 calls,
 async get(namespace: string, key: string, ctx: any) {
 calls.push({ method: 'get', args: [namespace, key, ctx] });
 return pick(await loadRows(), key);
 },
 };
 if (batched) {
 // NOTE the THIRD parameter — this is also the fix for item 3 above:
 // the double must accept `ctx` to be able to assert it was forwarded.
 rig.getMany = async (namespace: string, keys: readonly string[], ctx: any) => {
 calls.push({ method: 'getMany', args: [namespace, [...keys], ctx] });
 const loaded = await loadRows();
 const out: Record[string, unknown] = {};
 for (const key of keys) out[key] = pick(loaded, key);
 return out;
 };
 }
 return rig;
 }

 const VALUES = { timezone: 'Asia/Tokyo', locale: 'ja-JP', currency: 'JPY' };
 const EXPECTED = { timezone: 'Asia/Tokyo', locale: 'ja-JP', currency: 'JPY' };

 it('BEFORE — a per-key occupant issues three namespace reads in one leg', async () => {
 const settings = makeSettingsRig(VALUES, { batched: false });
 const ql = makeCountingQl({ sys_setting: [] });
 const loc = await resolveLocalizationContext({ ql, settings, tenantId: 'o1', userId: 'u1' });
 expect(loc).toEqual(EXPECTED);
 expect(settings.stats).toEqual({ queries: 3, legs: 1 });
 // The settings path answered, so the direct `sys_setting` fallback is not
 // reached — the three reads above are the whole cost.
 expect(ql.counts.sys_setting ?? 0).toBe(0);
 });

 it('AFTER — the batched occupant issues ONE namespace read, in the same one leg', async () => {
 const settings = makeSettingsRig(VALUES, { batched: true });
 const ql = makeCountingQl({ sys_setting: [] });
 const loc = await resolveLocalizationContext({ ql, settings, tenantId: 'o1', userId: 'u1' });
 expect(loc).toEqual(EXPECTED);
 expect(settings.stats).toEqual({ queries: 1, legs: 1 });
 expect(ql.counts.sys_setting ?? 0).toBe(0);
 });

 // Item 3: the context assertion the current pins structurally cannot make.
 it('asks for all three keys of the one namespace in a single call, with the same context', async () => {
 const settings = makeSettingsRig(VALUES, { batched: true });
 await resolveLocalizationContext({
 ql: makeCountingQl({ sys_setting: [] }), settings, tenantId: 'o1', userId: 'u1',
 });
 expect(settings.calls).toEqual([
 { method: 'getMany', args: ['localization', ['timezone', 'locale', 'currency'], { tenantId: 'o1', userId: 'u1' }] },
 ]);
 });

⚠️ Typing note: the generic type arguments above are written with square brackets (Record[string, unknown], Array[{ … }]) instead of angle brackets, because this repo has measured GitHub's body sanitizer eating short angle-bracket fragments even inside fenced code. Restore them to angle brackets when pasting into the test file.

Reverse-verified, not merely written

Run against the pre-fix source with the tests kept in place, the AFTER case failed with exactly the before-state numbers:

AssertionError: expected { queries: 3, legs: 1 } to deeply equal { queries: 1, legs: 1 }

That single line is the card's whole calibration as a measurement: queries 3 → 1, legs 1 → 1. It confirms cloud#1539's finding independently — the three reads really did already run in one leg — which is why #10826 was correctly scheduled as a query-count fix and not a latency fix. A future regression to a sequential loop would move the legs half of that assertion while leaving every call-count pin green, which is the gap item 2 exists to close.

---

Generated by Claude Code

---

Generated by Claude Code

[claude]

Finding concentration round (triage seat, session session_01Kktexqp6uVuFMztvvTMf3V, 2026-08-24, maintainer-invoked): promoted → pm:queue + domain:engine, Task (S). All four items are consequences of one getMany switch; single PR, declared file surface: packages/core/src/security/resolve-authz-context.ts (param JSDoc) + packages/rest/src/rest-api-plugin.ts (SettingsReadSurface prose) + the leg-count pin + resolution-context note. Cross-domain designation by triage (core+rest in one S card): engine seat carries it; file surface above is the claim-comment surface.

---

Generated by Claude Code

[huangyiirene]

Claim: PM loop round 1
Session: session_01VK8rFDtg8eREaxBGX99Csn
Branch: claude/issue-11222-localization-getmany-declarations
Worktree: objectstack-issue-11222
Domain: domain:engine
File surface: packages/core/src/security/resolve-authz-context.ts + packages/core/src/security/resolve-authz-context.test.ts + packages/rest/src/rest-api-plugin.ts (stop on breach; explain in the report)
Container & model: S, mode:subagent, model: opus (tier: dispatch-gates.mjs --tier on this surface returns no path-derived mandate, quoted not recalled. Two declaration lines are mechanical, but the leg-count rig is a measurement device that has to reverse-verify, and a rig that cannot fail is worse than no rig.)
Clause-②: no — two declarations are corrected to match what the consumer already calls, plus test-only assertions. No accept/reject behaviour moves and no public surface widens; the runtime path is untouched.
Serial constraints cleared: no open PR touches either production file. All 21 open PRs enumerated and their diffs read; the matcher's positive control is #11659 at 9 changed files. Sibling read-coupling, named because file-disjointness does not cover it: #11580 / PR #11623 (domain:cli) moves when the MCP stdio transport reads localization settings — it does not touch this resolver and asserts nothing about its call shape, so this card's pins cannot be flipped by it landing. #11588 (domain:cli, rest sandbox error wrapper) is in packages/rest but not in rest-api-plugin.ts.

Directed in-flight check — required, because this is a triage-designated cross-domain card

Triage designated this a single S card spanning core + rest and assigned it to this seat by name (2026-08-24 promotion comment). Per the cross-domain exception path, the directed in-flight check runs over the lanes this surface touches — domain:engine (core) and domain:cli (rest):

• domain:engine in flight: driver-sql: the platform-objects schema does not sync onto MySQL — unbounded string fields become TEXT, which MySQL refuses to index #11374, Remove the (p as any) cast at the REST publishMetaItem call site once MetadataProtocol declares the member (#11006 follow-up) #11145 (this seat, same round). driver-sql: the platform-objects schema does not sync onto MySQL — unbounded string fields become TEXT, which MySQL refuses to index #11374's surface is packages/platform-objects/src/identity/**; Remove the (p as any) cast at the REST publishMetaItem call site once MetadataProtocol declares the member (#11006 follow-up) #11145's is packages/rest/src/rest-server.ts. Neither intersects this card's three files.
• domain:cli in flight: burn down the cli-test-child-env baseline: 18 spawned children in 17 packages/cli/test files still built from the whole of process.env #11596, rest: the sandbox debug wrapper hook '<name>' threw: Error: … reaches the client on every write route that exits above mapDataError's unwrap (batch, createMany, updateMany, deleteMany, clone, analytics) #11588, MCP stdio transport pins its localization to the manifest defaults — the settings read happens in start(), inside the pre-bind window under every composition order #11580, @objectstack/rest openapi.json sets info.version to config.api.version ('v1') under a comment promising "the runtime version" — the comment is falsified by the line it introduces #11546, packages/cli e2e tests that spawn bin/run.js as "the SHIPPED entrypoint" never reach dist/ — oclif's ts-path reroutes them to src/ under NODE_ENV=test|development #11317, [finding] ADR-0120 D4 says the duplicate pre-flight lives in os migrate plan, but the runtime-managed index class now reports through os migrate duplicates #11032, Decide whether POST /api/v1/automation/:name/toggle belongs in the manage_metadata write set — it mutates flow enablement with no authoring capability #10243. Of these, the ones with open PRs were checked by diff and none touches rest-api-plugin.ts or resolve-authz-context.ts. ⚠️ Honest bound on this reading: cards without a pushed PR expose no diff, so for those the check is "no declared overlap", not "measured disjoint".

Premises re-verified on the merged ref

origin/main @ cad8b42. Both declaration sites are live and both still under-state the consumer:

• packages/core/src/security/resolve-authz-context.ts:650 — the param JSDoc still says the service exposes get(namespace, key, ...).
• packages/rest/src/rest-api-plugin.ts:60 — interface SettingsReadSurface is still declared, and still consumed at 327/329 via ctx.getService.
• getMany occurs 5x in the resolver, so the switch this card follows did land and the declarations really are the stale half.

The measurement rig is already written, and it has a trap in it

The card's own thread carries a salvaged, reverse-verified leg-count rig (comment 5384105106) from a discarded duplicate dispatch. It is the hard part of item 2 and should not be rebuilt from scratch. ⚠️ Two documented hazards, both from the author:

1. It was written against pre-perf(core): resolveLocalizationContext reads its three keys through settings.getMany (#10826) #11208 source and needs rebasing onto the landed getMany path; EXPECTED / VALUES / makeCountingQl already exist in the target test file.
2. ⛔ Its generic type arguments are written with square brackets (Record[string, unknown], Array[{ … }]) because this repo has measured GitHub's sanitizer eating short angle-bracket fragments even inside fenced code. They must be restored to angle brackets when pasted. Pasting it verbatim will not compile.

The rig's whole value is that it reverse-verified: against pre-fix source the AFTER case failed with expected { queries: 3, legs: 1 } to deeply equal { queries: 1, legs: 1 }. A leg pin that has never been seen red is not a pin.

Scope note carried from the card

Item 1 (the two declarations) and items 2-3 (test-only) are in scope. Item 4 — the partial-manifest getMany all-or-nothing failure — the card itself flags that it may belong on getMany's own contract rather than at this call site, since the validation is the service's behaviour and this caller is merely its first consumer. That judgement is the dev's to make and report; if it lands in the settings service it is a domain:services card, ⛔ not a silent widening of this PR.

H17 on-hold trigger index — zero intersection

Intersected against all 17 indexed holds on the patrol anchor (#9857). No hit. ⚠️ Note the near-miss deliberately checked: hold #7898 indexes packages/core/src/security/auth-gate.ts — a different file in the same directory as this card's resolver. Same folder is not the trigger; the indexed path is.

---

Generated by Claude Code