Design: cross-request caching for the authenticated request path (tranche 2 of #10757) — write-invalidation-first, short-TTL fallback, configurable staleness window

[os-zhuang]

Chartered by maintainer ruling, 2026-08-24, live PM chat on #10757 (「10757 接受你的建议」— accepting the design-first recommendation). This is the design card whose output unblocks #10757's tranche 2; #10757 carries Blocked-by: pointing here.

Why design-first (recorded so it is not re-litigated)

Caching session and authorization state is a security change wearing a performance costume — a stale grants cache is a privilege-escalation window (a permission revoked at T honoured until TTL expiry). The invalidation design is agreed BEFORE implementation code, per the tranche split's own words on #10757.

Ruled direction (the design works within this, deviations come back as a fork)

• Write-invalidation is primary: permission/session mutations (grant/revoke/role change/session revoke/settings write) invalidate the affected cache entries in the same operation — correctness does not rest on a timer.
• Short TTL is the fallback bound, not the mechanism: a configurable staleness ceiling (order of seconds, default conservative) catching invalidation paths the design missed, out-of-process writers, and multi-node skew.
• Configurable: deployments can tighten to zero (cache off) — the security-sensitive default must be defensible in the ADR-class writeup.
• Low-sensitivity caches first: localization (sys_setting success reads — note 新环境日志被 sys_setting 'no such table' ERROR 刷屏：本地化读取先于建表，真错误被噪音淹没 #10221 deliberately caches failures only; the dogfood read-after-write pin is satisfied by invalidation-on-write) and getMetaItems' sys_metadata read (registry-epoch keyed) may be designed to ship ahead of grants/session caching.
• Multi-node: state the story explicitly (per-process cache + TTL bound, or the invalidation bus), since cloud runs more than one instance.

Deliverable

A design document (issue comment or ADR draft — if ADR-class, governed rules apply: draft PR, human merge) covering: cache keys and scopes per leg (A session / B grants / C localization / D metadata, from #10757's trace), invalidation triggers per mutation path, TTL defaults and config surface, multi-node semantics, and the test/pin plan (the existing batch-equivalence golden discipline extends to "cached answer ≡ uncached answer" identity pins). Implementation is dispatched as follow-up cards against the approved design, not as riders on this one.

Refs: #10757 (trace + tranche history; tranches 1/1b landed via #10824/#11197/#11200/#11208) · cloud#1521 (the ≤200ms gate this ultimately serves) · cloud#1518 (placement half, separate).

[os-sam]

Claim + dispatch — design only, no implementation, no follow-up cards filed

• Session: session_01APWX2AwT3a4xDcjPCe8bk4 (os-sam, domain:services execution seat)
• Branch: claude/issue-11633-cross-request-cache-design (claim marker; ⛔ no PR expected unless the design turns out ADR-class)
• Worktree: ../objectstack-11633-design (per-repo; ⛔ never the shared checkout; ⛔ never git stash)
• Container & model: claude-opus-5 — no path-derived tier mandate (a design deliverable touches no mandated surface), and the measured quota exemption applies this round regardless: a dev on this lane terminated at ~11:50Z with You've reached your Fable 5 limit, so fable-tier execution is not reliably available (fable unavailable ⇒ opus, never lower).
• pm:queue → pm:dispatched

Honouring this card's own discipline: the deliverable is the design document, and 「Implementation is dispatched as follow-up cards against the approved design, not as riders on this one.」 ⛔ No product code. ⛔ No implementation. ⛔ No follow-up cards filed — the dev proposes the split; filing waits on your acceptance.

⚠️ If the design is ADR-class: docs/adr/** is a governed surface — draft PR, human merge. ⛔ This seat never flips ready, never arms auto-merge and never merges a governed surface, whatever the review says.

The framing the dev is held to, verbatim from the card

Caching session and authorization state is a security change wearing a performance costume — a stale grants cache is a privilege-escalation window (a permission revoked at T honoured until TTL expiry).

The ruled direction is a fence, not a starting point: write-invalidation primary, short TTL as a fallback bound rather than the mechanism, configurable down to zero, low-sensitivity legs first, multi-node story stated explicitly. ⛔ A deviation comes back as a fork for you to rule on, never as a quiet design choice.

⭐ Two authorization surfaces this design sits on top of are MOVING right now

The dev could not know this from the card, so it has been told:

• [finding] Three spellings of the ADR-0068 platform-admin read now live in plugin-auth, and one of them skips the system read context #10348 (ruled option C, dispatched this round, Clause-② / needs:contract-review): the two stray plugin-auth platform-admin judges are deleted and both call sites ask core/security/resolve-authz-context.ts. ⇒ The thing a grants cache would cache is being consolidated to one site as we speak. Design for the post-C single derivation point.
• [Design] Re-anchor platform-admin: admin_full_access becomes a kernel metadata declaration; WHO holds it comes from env-configured verified emails — retiring the org-less row anchor #11663 (priority:p0, design delivered, now needs-user-decision): platform-admin re-anchors onto env-configured verified emails, retiring the org-less row anchor. ⇒ Part of "grants" may stop being a row read at all. A cache keyed on grant rows would be caching something the re-anchor removes.

The dev is instructed to state explicitly which parts of its cache design depend on either landing, rather than silently assuming today's shape — the same coupling disclosure #11663's designer was held to.

Fences

⛔ Zero packages/spec ownership — a spec change is named as a spec-seat leg, never taken. ⛔ cloud#1521 / cloud#1518 are NOT reachable from this session (repo scope is objectstack-ai/objectstack): reason only from what this card records, and mark that leg NOT MEASURED rather than inferring it. ⛔ Never edit content/docs/releases/, .claude/**, skills/**, AGENTS.md, CLAUDE.md.

⛔ Disclosure discipline: the design describes an escalation window class. Public text carries the design and its reasoning — no reproduction recipe for exploiting a stale cache.

---

Generated by Claude Code

[claude]

Design — cross-request caching for the authenticated request path (tranche 2)

Form chosen: this issue comment, not an ADR — deliberately, and with a proposal attached.
See §9. Measurement base: every code claim below was read on a full (non-shallow) worktree
cut from origin/main at 992161b728; origin/main has since moved one commit
(88b9d749a1, plugin-audit sys_activity vocabulary) which touches none of the files cited.
Claims carried from the card's 2026-08-21 trace rather than re-measured are marked
NOT MEASURED inline.

---

0. The frame, and what it changes about the shape of the answer

The card's framing is that this is a security change wearing a performance costume. Taken
seriously, it changes the unit of design. The unit is not "a cache". The unit is:

A cached answer together with the declared contract that says when it stops being an answer.

So the design rule this document proposes, and which every leg below is written against:

No authorization answer may be cached unless (a) every write that can change it passes a
seam this process observes, and (b) a TTL bounds the case where (a) fails. Both. Always.
Neither alone is a design.

(a) alone fails on the writer this process cannot see — another node, a migration, a DBA.
(b) alone is the timer the card's ruling already refuses. The interesting content of this
document is mostly in the places where (a) turns out to be cheaper and stronger than expected,
and in three places where (a) is not derivable and the design has to say so out loud.

---

1. What a request actually pays today — re-measured on 992161b728

Tranches 1 and 1b have landed since the card's trace, so the numbers moved. Measured by reading
the code, not by reasoning from the card:

leg	site	reads today	legs
A session	better-auth findSession	sys_session + sys_user — NOT MEASURED this round (carried from the card's 2026-08-21 rig trace); the mechanism was re-verified (§5)	1–2
A session	customSession callback, auth-manager.ts:3061	sys_user_permission_set {user_id} limit 50, sys_permission_set {} limit 50 (no where — full page), sys_member {user_id, organization_id} limit 5; plus findOne sys_session when idle/absolute controls are on	3+
B grants	resolveUserAuthzGrants, resolve-authz-context.ts:319	8 reads in 4 waves post-#10825: wave 1 = Promise.all over sys_user(conditional) + sys_member{user_id} + sys_user_position + sys_member{organization_id} limit 1000 + sys_user_permission_set; then sys_position → sys_position_permission_set → sys_permission_set sequentially	4
C localization	resolveLocalizationContext, :726	1 settings.getMany('localization', [timezone, locale, currency]) → 1 loadRows (all three keys are tenant/global scope, so the two-group split collapses to one)	1
D metadata	getMetaItems, protocol.ts:5992, per enforceApiAccess	queryByOrg(null) then queryByOrg(orgId), each with an alt-type retry when the first returns empty ⇒ 2–4 reads, and the two queryByOrg calls are awaited in sequence	≥2

Two things worth pulling out of that table before the design starts:

• Leg D's cost is concentrated in the empty case. The alt-type retry fires because the
  first read returned nothing, so an app whose objects are all code-authored (no overlay rows)
  pays the doubled read on every request. Most of leg D's win is negative caching.
• Leg C is already one query. resolveLocalizationContext reads the same sys_setting namespace three times per request #10826 did that. Leg C is now worth caching for the round
  trip, not for the query count — which matters, because it lowers the value at risk and
  makes C the right leg to ship first for reasons beyond "it is least sensitive".

---

2. The invalidation substrate — measured, and stronger than the card assumes

2.1 The engine seam sees every write, and it is not a call-site list

IObjectQL.registerMiddleware hands each middleware an OperationContext
(objectql/src/engine.ts:1842):

export interface OperationContext {
 object: string;
 operation: 'find' | 'findOne' | 'insert' | 'update' | 'delete' | 'count' | 'aggregate';
 ast?: QueryAST; data?: any; options?: any; context?: ExecutionContext; result?: any;
}

Measured: plugin-security already uses exactly this as an invalidation trigger, and its
docblock already argues the case this design needs (security-plugin.ts:820-844, :986-993):

• the epoch bump is the first statement in the middleware, ahead of the isSystem bypass, so
  a seeder, a package publish and the auto-org-admin grant all invalidate;
• metadata.changed also bumps it, because a permission set can be declared in metadata, so a
  Studio edit is a permission change with no row written.

Measured, and this is the part that makes the seam decisive: better-auth does not bypass it.
plugin-auth/src/objectql-adapter.ts:689-691 routes better-auth's own adapter straight through
the engine:

insert: async (m, d, o) => e.insert(m, d, await asAttributedSystem(o)),
update: async (m, d, o) => e.update(m, d, await asAttributedSystem(o)),
delete: async (m, q) => e.delete(m, await asAttributedSystem(q)),

So membership changes, bans, session revocation and org-role changes — everything better-auth
writes — are visible at one seam this process already owns.

Why this matters on the AI-safety axis specifically: a call-site list of "places that must
remember to invalidate" is a permanent maintenance obligation, and the failure mode when a new
grant path forgets is silent over-permission. A seam cannot be forgotten, because writing
through the engine is the only way to write at all. This is the "declared = enforced" shape:
a new capability-granting path physically cannot skip the invalidation.

2.2 Where the seam is not precise enough — stated, not designed past

For insert, opCtx.data carries the row. For update/delete expressed as a where, the
affected user_id / organization_id is frequently not derivable without reading the row
back. A design that assumes it can compute "whose cache entry does this write touch" from the
OperationContext is assuming something the seam does not provide.

⇒ Ruled into this design: object-level (coarse) invalidation is the baseline. Any write to a
watched object retires the whole cache for that leg. That is what plugin-security already does
(writeEpoch++, any write retires every entry), it is un-missable, and its only cost is
cache-effectiveness under write load. Fine-grained keyed invalidation is a later optimization
and must not be the starting point — see Fork 1 (§8).

2.3 The settings change bus already exists and is unused by the localization cache

Measured: SettingsService already has a synchronous in-process change bus —
subscribe(namespace, handler) (settings-service.ts:1435), emitChange(...) (:767), fired
from the write path (:1708) and from bindEngine (:621). Leg C's primary invalidation
trigger therefore requires no new mechanism at all; it requires a subscription.

⚠️ One measured constraint that decides its shape: the event is
{ namespace, key, scope, action, at } — no tenant discriminator. A handler cannot know
which tenant's entry to drop. ⇒ drop the whole localization bucket on any localization
event. Over-invalidation is the safe direction here and the cheap one; a surgical handler
would be inventing a tenant id the event does not carry.

---

3. Multi-node — the measurement that forces the design

The card asks for the multi-node story to be stated explicitly and for a pick-and-argue between
"per-process cache + TTL bound" and "an invalidation bus". The measurement removes the fork
for grants and grants it for the others. Three measured facts:

1. The only shipped cross-node channel is IPubSub, and it is at-most-once.
   service-cluster-redis/src/pubsub.ts:78-92, in its own words: "Redis pub/sub is
   at-most-once — there is no delivery guarantee to subscribers and no replay for a node that
   was down or slow at publish time. This is acceptable only for events that are pure
   cache-invalidation hints, never the source of truth." content/docs/kernel/cluster.mdx §4.2
   confirms at the contract level: "No shipped driver provides at-least-once yet."

2. The one channel in production use is metadata.changed, bridged by
   MetadataClusterBridgePlugin (service-cluster/src/metadata-cluster-bridge-plugin.ts), which
   silently returns when no cluster service is registered — the default composition.

3. Row-level authorization writes have no cross-node channel today at all. writeEpoch++
   fires on writes this process's middleware sees. Another node's grant revocation is invisible.
   That is harmless today only because the thing it guards dies with the request.

The consequences, which are the load-bearing multi-node claims of this design:

• A bus cannot be the correctness mechanism for grants. A dropped message on an at-most-once
  transport is an escalation window with no upper bound. ⇒ The TTL is not a convenience and
  not a backstop for "paths we missed" — it is the only bound that survives the transport's own
  stated guarantee. This is the strongest available argument for the card's ruled direction, and
  it is a measurement rather than a preference.
• A bus is still worth adding, as a latency improvement to the typical case: it moves the
  usual convergence from "one TTL" to "one network hop". It should be a new channel on the
  existing bus (authz.invalidated), following the MetadataClusterBridgePlugin shape exactly
  — never a new transport, never a new dependency.
• The shipped default has no cluster service, so the default configuration must be correct
  with no bus present. ⇒ per-process cache + TTL bound is the baseline; the bus is an optional
  tightening that lowers the typical window, never the worst-case one.
• ⚠️ A silently-absent bridge is security-relevant here in a way it is not for metadata. For
  metadata a missed event costs a stale schema until reload and loses no data — its own doc says
  so. For grants it costs a permission honoured past its revocation. A mechanism whose absence is
  logged at debug is precisely the shape of decision(plugin-auth): 会话的「记录之处」到底在哪 —— better-auth secondaryStorage 一旦接上 cache，ADR-0069 D4 的会话管控就静默失效 #4785 (a config that silently disabled a control).
  ⇒ Required: a loud boot-time posture statement when a grants cache is enabled with a
  non-zero TTL and no invalidation bus is registered. Not a refusal — a deployment may accept the
  TTL as its whole bound — but it must be stated, not discovered.

---

4. Per-leg design

Ordering below is the card's ruled order (low-sensitivity first), which is also the order in
which the invalidation contracts get progressively harder to write.

Leg C — localization (ship first)

• What is cached: the successful outcome of resolveLocalizationContext. The failure-only
  cache (新环境日志被 sys_setting 'no such table' ERROR 刷屏：本地化读取先于建表，真错误被噪音淹没 #10221) stays exactly as it is; this widens it to success, which is the thing 新环境日志被 sys_setting 'no such table' ERROR 刷屏：本地化读取先于建表，真错误被噪音淹没 #10221
  deliberately refused.
• Key: extend the existing table rather than adding a second one —
  WeakMap(ql instance) → Map("tenantId|userId"), the shape already at
  resolve-authz-context.ts:709. Keying on the ql instance is what keeps two environments in
  one process from seeing each other's answer; that property is already argued in the existing
  docblock and must be preserved.
• Invalidation, primary: settings.subscribe('localization', ...) → clear the whole bucket
  (§2.3).
• Invalidation, backstop: engine-seam write to sys_setting. Needed because the resolver's
  own fallback path reads sys_setting directly (:806-816), so a write that bypasses
  SettingsService — a seeder, a direct engine write — would emit no service event.
• TTL: short, configurable to zero. 30s is defensible and has two shipped precedents in this
  repo (hostnameCacheTtlMs = 30_000 in rest-server.ts:812, and 新环境日志被 sys_setting 'no such table' ERROR 刷屏：本地化读取先于建表，真错误被噪音淹没 #10221's own
  LOCALIZATION_FAILURE_CACHE_TTL_MS). The value at risk is a timezone/locale/currency.
• ⭐ Re-measured, as the card instructed: the card says the dogfood read-after-write pin is
  satisfied by invalidation-on-write. It is — and it is sharper than the card states. Measured
  in packages/qa/dogfood/test/analytics-timezone.dogfood.test.ts: the write is a real
  PUT /api/settings/localization, the read is a separate HTTP request, and both run in one
  process, sequentially awaited. Therefore:
  • a synchronous, in-process invalidation on the settings event satisfies it;
  • a TTL alone does not — 30s far exceeds the inter-request gap;
  • an asynchronous or deferred invalidation does not reliably satisfy it either.
    ⇒ That test already is the acceptance test for "write-invalidation primary" on leg C. It goes
    red exactly when the primary mechanism is missing and the timer is doing the work. Keep it
    unchanged and unweakened; it is free coverage of the property that matters most.

Leg D — metadata (ship second)

• What is cached: the sys_metadata overlay read inside getMetaItems — the 2–4 reads and
  ≥2 sequential legs measured in §1.
• Key: (environmentId, canonical type, packageId, organizationId, previewDrafts) plus an
  epoch. The epoch is the card's "registry-epoch keyed": bump on (i) any engine-seam write to
  sys_metadata, and (ii) any metadata.changed watch event.
• Multi-node: already solved for this leg. metadata.changed is bridged cross-node today, and
  leg D is the one leg where an at-most-once hint is genuinely adequate — by the transport's own
  documented criterion (a missed event costs a stale schema until reload; no data loss, self-heals).
• ⚠️ Trap that a naive implementation will hit. getMetaItems is not a pure read: its
  overlay-hydration branch registers overlay rows back into the SchemaRegistry (see the
  #4432 comment at protocol.ts:5993-6001, and :159). A cache that skips the read also skips
  that registration, and the symptom is not a stale answer — it is a registry that stops being
  populated. ⇒ Cache the merged post-hydration result, or keep hydration outside the cached
  path and prove it idempotent. Naming this is most of why leg D deserved a design pass.
• ⚠️ Negative caching is where the win is, and it is the entry most in need of the epoch. The
  empty result is what triggers the alt-type retry, so caching "empty" is the bulk of the saving —
  and a newly published overlay must appear promptly. The epoch, not the TTL, is what makes that
  correct; a TTL-only leg D would make publish-visibility a timer.
• TTL: short, configurable to zero, as a bound on the same at-most-once transport.

Leg B — grants (ship third; the one the card is really about)

• What is cached: the UserAuthzGrants envelope from resolveUserAuthzGrants.

• Watched objects (derived by reading §3–§7 of the resolver): sys_member,
  sys_user_position, sys_user_permission_set, sys_position, sys_position_permission_set,
  sys_permission_set, sys_user. Plus metadata.changed for declared permission sets.
  ⚠️ sys_session is deliberately NOT in this set — see the measured reason under leg A.

• Invalidation triggers, per mutation path:

  mutation	reaches the seam as	retires
  grant / revoke a permission set to a user	write to sys_user_permission_set	leg B, all entries
  role change (better-auth org role)	write to sys_member (via the ObjectQL adapter)	leg B, all entries
  auto-org-admin reconcile	write to sys_user_permission_set (system write — caught because the bump precedes the isSystem bypass)	leg B, all entries
  position assign / deactivate	sys_user_position / sys_position	leg B, all entries
  permission-set edit, deactivate, or system_permissions/tab_permissions change	sys_permission_set	leg B, all entries
  permission set declared in metadata	metadata.changed	leg B, all entries
  ai_access toggle	sys_user	leg B, all entries
  settings write	not a leg-B trigger	—

• ⭐ Three correctness constraints that a naive keying gets wrong. These are the substance of
  this leg.

  B.1 — The answer is a function of the clock, and caching freezes it.
  Validity windows (ADR-0091) are evaluated at resolution time: isGrantActive(row, nowMs) is
  applied to sys_member, sys_user_position and sys_user_permission_set rows, and nowMs is
  taken once per resolution (:383). A cached envelope therefore freezes a validity decision:
  a grant whose valid_until passes during the TTL keeps resolving until the entry expires.
  No write occurs at that boundary, so no write-invalidation can ever catch it — the entire
  primary mechanism is blind to this class by construction.
  ⇒ Required: an entry must carry the earliest upcoming validity boundary among the rows
  it consulted, and expire at min(ttl, nextBoundary). Without it, "expires at T" silently
  becomes "expires at T rounded up by the TTL", and ADR-0091's fail-closed promise quietly
  acquires a tolerance. I have not found this stated anywhere in the Authenticated data requests issue ~20 DB queries in ~17 sequential legs — per-request auth/session/localization/metadata resolution has no cross-request caching, costing ~1.5s/request on remote Postgres #10757 lineage.

  B.2 — Seeds are part of the answer, and their order is contractual.
  seedPermissions (API-key scopes) and seedEmail enter the envelope
  (grants.permissions = [...opts.seedPermissions], then set names appended), and the existing
  golden asserts array order deliberately. Two options: put the seeds in the key, or cache the
  seedless envelope and apply seeds outside it. The second is better (one entry per
  (userId, tenantId) instead of one per key-scope combination) but it is only sound because
  seeding is a pure prepend, which must be pinned, not assumed. Note also that a seeded
  API-key principal suppresses the sys_user read entirely (needsUserRow at :365) — so the
  seedless entry issues a read the seeded path would not have. That is a query-multiset
  difference the existing golden will notice.

  B.3 — org_user_ids depends on OTHER users' rows.
  The fellow-org peer list is sys_member {organization_id} limit 1000 (:370). It changes when
  any user's membership in that organization changes. ⇒ invalidation on a sys_member write
  must retire every entry for that organization, not the written user's entry. This is the
  single most likely place for a "fine-grained invalidation" optimization to introduce a silent
  bug, and it is a second reason coarse invalidation is the right baseline.

• ⭐ Two call sites that must bypass the cache. resolveUserAuthzGrants has 17 call sites
  across 12 packages (measured); two of them are wrong to serve from cache:

  • plugin-security/src/explain-engine.ts:473 — the permission explainer. This is the tool
    an administrator uses to verify that a revocation took effect. An explainer answering from
    cache would explain a state that no longer exists, and would do it at exactly the moment
    someone is checking. ⇒ explain takes a force-fresh path.
  • service-automation/src/plugin.ts:812 — runAs:'user' automation runs. These are not
    request-shaped and can be long-lived; they must not pin an envelope.

• TTL: the security-sensitive number. The card rules "order of seconds, default conservative".
  Recommendation and the one number to confirm: default 0 (off) for leg B specifically, with
  a supported non-zero range in the low seconds. Rationale: legs C and D deliver real latency with
  a defensible story; leg B is where the escalation window lives, and shipping it on by default
  makes every existing deployment absorb a posture change it did not ask for. A deployment that
  wants it turns it on knowingly — which is also what makes the boot-time posture statement (§3)
  meaningful rather than noise.

• Depends on [finding] Three spellings of the ADR-0068 platform-admin read now live in plugin-auth, and one of them skips the system read context #10348-C landing. See §6.

Leg A — session (ship last, and not in the form the card sketches)

⭐ Measured blocker: the two mechanisms #10757's direction 1 names are already ruled out, one of
them by a closed decision with landed pins.

• secondaryStorage — closed decision. decision(plugin-auth): 会话的「记录之处」到底在哪 —— better-auth secondaryStorage 一旦接上 cache，ADR-0069 D4 的会话管控就静默失效 #4785 ("where is the session of record?") is
  closed as completed via merged PR test(plugin-auth): 证明 ADR-0069 D4 真能撤销活动会话，并把「会话的记录之处」定为 sys_session (#4785) #5101, fixing the answer: it is always sys_session, the
  database. The reasoning is recorded in plugin-auth/src/secondary-storage.ts:22-38: handing
  better-auth a secondaryStorage moves the session of record into it —
  internalAdapter.createSession skips the sys_session row and findSession answers from the
  cached snapshot without consulting the database — while ObjectStack revokes sessions by
  writing that row (enforceSessionControls / enforceConcurrentCap stamp revoked_at plus a
  past expires_at, ADR-0069 D4). The result is that idle-timeout, absolute-max and
  concurrent-cap revocation silently stop taking effect.
  It is pinned. plugin-auth/src/session-of-record.test.ts carries, by name:
  'opting into cacheSecondaryStorage empties sys_session and makes idle timeout inert',
  'option C (dual-write) is not reachable through config — asking for it changes nothing', and
  'the DEFAULT composition refuses to boot with a secondaryStorage rather than degrading quietly'. Its header states the discipline this whole design should borrow: "every test here
  asserts the END of the chain, not the middle: a request that carries a real session cookie stops
  being authenticated. Asserting only that the row was stamped would re-create the exact blind
  spot."
• cookieCache — same ground, no guard. Measured with a positive control: cookieCache
  has zero hits repo-wide (git grep exit 1, 0 lines; the control on the same instrument
  returns 10 hits), so it is genuinely unconfigured. But it is a different better-auth key
  reaching the same architecture: it answers getSession from a signed cookie snapshot without
  reading sys_session, so a session revoked by writing the row keeps authenticating for the
  cookie's TTL. ⇒ Authenticated data requests issue ~20 DB queries in ~17 sequential legs — per-request auth/session/localization/metadata resolution has no cross-request caching, costing ~1.5s/request on remote Postgres #10757's direction 1, as written, is not available without re-opening a closed
  ruling. ⚠️ And worth recording on its own: the secondaryStorage door is boot-refused while
  the cookieCache door is unguarded — the same rejected architecture reachable through a config
  key nothing pins. That is a gap in the guard, not a gap in the ruling.

⇒ What leg A becomes:

• A1 — the customSession enrichment (3 of leg A's ~5 reads). ⭐ Do not design a cache for
  this. [finding] Three spellings of the ADR-0068 platform-admin read now live in plugin-auth, and one of them skips the system read context #10348-C deletes it. Option C (ruled 2026-08-24) removes the id-shaped judges from
  auth-manager.ts and sends both call sites to resolve-authz-context.ts. Post-C the enrichment
  is the same derivation as leg B, so leg B's cache serves it, with leg B's single invalidation
  contract. Designing A1 separately would create a second cached derivation of the same fact —
  the exact drift shape [finding] Three spellings of the ADR-0068 platform-admin read now live in plugin-auth, and one of them skips the system read context #10348 exists to end.
• A2 — better-auth's own sys_session + sys_user read. This is the half decision(plugin-auth): 会话的「记录之处」到底在哪 —— better-auth secondaryStorage 一旦接上 cache，ADR-0069 D4 的会话管控就静默失效 #4785 fenced.
  Out of scope for this design. It is not a cache-design surface; it is a
  ruled-decision surface, and reaching it means re-opening decision(plugin-auth): 会话的「记录之处」到底在哪 —— better-auth secondaryStorage 一旦接上 cache，ADR-0069 D4 的会话管控就静默失效 #4785 Option B with the revocation
  rewrite that option always required. Proposed as a decision card, not an implementation card (§7).
• ⭐ Measured reason sys_session must stay out of leg B's watched set.
  enforceSessionControls writes last_activity_at on a throttled cadence — once a minute
  per active session (auth-manager.ts:5771-5776). Under coarse object-level invalidation, that
  write would retire the entire grants cache roughly every minute on any deployment with idle
  timeout configured. sys_session does not feed the grants envelope, so excluding it is free —
  but only if someone notices, and the natural instinct ("sessions are authz, watch them") gets it
  wrong. This is also a general warning for Fork 1: a watched object with a background write
  cadence silently converts a cache into a non-cache.

---

5. Config surface

• ⭐ Deployment config (OS_* env), never a settings row. Two reasons, one of them measured:
  1. Settings live in sys_setting, which leg C caches. A staleness bound read through a
     cached path is a bootstrap hazard — the knob that governs the cache would be served by the
     cache.
  2. It matches the direction [Design] Re-anchor platform-admin: admin_full_access becomes a kernel metadata declaration; WHO holds it comes from env-configured verified emails — retiring the org-less row anchor #11663 is being ruled on for operator-level configuration
     ("operator-level admin comes from deployment config, never from business data"), and the
     existing settings service already models env as outranking every persisted scope
     (effectiveEnvOverride), so the two channels do not fight.
• One variable per leg, so the low-sensitivity legs can ship enabled while leg B stays off.
  Each accepts 0 = off, and 0 must be a real path, not a degenerate TTL (see pin 7).
• Registered in content/docs/deployment/environment-variables.mdx, the canonical table.
• ⛔ Spec-seat leg, not taken here: if the invalidation event or a cache-posture value needs a
  declared shape in packages/spec (a contract type for the authz.invalidated payload, or a
  posture enum surfaced in diagnostics), that is a packages/spec card for the spec seat. This
  design does not take it and does not pre-commit its shape.

---

6. Dependency disclosure — what this design assumes, and what happens if it does not land

#10348-C (dispatched, not merged). Load-bearing.

• If it lands: the platform-admin derivation exists at exactly one site, leg A1 disappears into
  leg B, and there is one cached derivation with one invalidation contract.
• If it does not: A1 becomes a real leg needing its own cache and its own triggers, and the
  design has two cached copies of the same authorization fact — strictly worse than today, because
  today's copies at least re-read every time. ⇒ Recommendation: leg B's implementation card is
  Blocked-by: [finding] Three spellings of the ADR-0068 platform-admin read now live in plugin-auth, and one of them skips the system read context #10348. This design should not be implemented for leg B against the pre-C shape.

#11663 (design delivered, awaiting ruling). Load-bearing for the pins, not for the mechanism.

• If platform-admin re-anchors onto env-configured verified emails, hasPlatformAdminGrant stops
  being derived from the sys_user_permission_set → admin_full_access row read (resolver §6,
  §6b, §6c). That half of the answer becomes deployment config, invalidated by reload, not by a
  row write.
• The cache design survives this unchanged: sys_permission_set / sys_user_permission_set
  stay in the watched set for ordinary grants; the platform-admin half simply stops being one of
  the things a row write can change.
• ⭐ But the pins do not survive it unless they are written correctly now. A pin that asserts
  "the cached answer contains platform_admin because row X exists" becomes an obstacle to
  [Design] Re-anchor platform-admin: admin_full_access becomes a kernel metadata declaration; WHO holds it comes from env-configured verified emails — retiring the org-less row anchor #11663 and will be "fixed" by someone editing it. A pin that asserts "the cached answer equals
  the uncached answer" survives, because it keeps testing the property this card is about rather
  than the derivation [Design] Re-anchor platform-admin: admin_full_access becomes a kernel metadata declaration; WHO holds it comes from env-configured verified emails — retiring the org-less row anchor #11663 is replacing. ⇒ Design instruction: identity pins assert
  cached ≡ uncached, never the provenance of a particular capability. This is the same coupling
  disclosure [Design] Re-anchor platform-admin: admin_full_access becomes a kernel metadata declaration; WHO holds it comes from env-configured verified emails — retiring the org-less row anchor #11663's designer was asked for, pointed the other way.

cloud#1521 / cloud#1518 — NOT MEASURED. Out of this session's repo scope. The ≤200 ms gate and
the placement half are reasoned about only as this card records them. Nothing in this design should
be read as a claim about whether it clears that gate; §1's numbers are query and leg counts, not
milliseconds.

---

7. Test and pin plan

The existing batch-equivalence golden discipline extends naturally, and the harness is reusable:
makeRecordingQl is exported from resolve-authz-context.batch-equivalence.test.ts and
already records the query multiset and counts real legs. ⚠️ Cross-package test imports are gated
(check:cross-package-test-inputs), so a pin outside packages/core needs the repo's .testkit.ts
convention (8 such files exist today) rather than importing the test file.

1. Identity — cached ≡ uncached. For each fixture in the existing 11-fixture matrix: resolve
   twice; deep-equal including array order; and assert the second resolution issued zero
   reads. Both halves are needed — equality alone passes on a cache that never caches.
2. ⭐ Revocation — the pin that catches the failure that matters. Populate the cache, revoke a
   capability through the engine (the same seam a real revoke uses), resolve again, and assert
   the capability is absent, with no clock advance.
   ⚠️ It must assert the absence of the capability, not "the cache was cleared" — a
   clear-then-repopulate-from-a-stale-read implementation passes the second and fails the first.
   This is session-of-record.test.ts's own discipline ("assert the END of the chain, not the
   middle"), which is the right precedent because it was written after exactly this blind spot.
   The implementation card must ablate write-invalidation and report the observed direction.
3. Validity boundary (pins B.1). A grant whose valid_until falls inside the TTL stops
   resolving at the boundary, not at TTL expiry. No write occurs, so this pin is the only thing
   that can catch it.
4. Peer membership (pins B.3). User X's envelope must change when user Y's sys_member row
   in the same organization is written.
5. Seed isolation (pins B.2). Two callers with different seedPermissions never see each
   other's envelope; ordering matches the existing golden; and the seeded-API-key path's suppressed
   sys_user read is preserved in the query multiset.
6. Explain path. explain-engine observes a revocation immediately.
7. ⭐ Zero means off. With the cache configured to 0, the query multiset is byte-identical
   to today's golden. This is what makes "configurable to zero" an escape hatch a deployment can
   rely on rather than a claim in a docblock.
8. Leg C. analytics-timezone.dogfood.test.ts unchanged and unweakened — it is already the
   leg-C acceptance test (§4, leg C).
9. Multi-node. Two cache instances plus a bus double: a write on node 1 retires node 2's entry;
   and with the bus absent, node 2 still converges by TTL — the pin that proves the bound
   exists independently of the transport.

---

8. Forks — where a real choice remains

Fork 1 — invalidation granularity for leg B: coarse vs keyed

• A. Coarse (recommended). Any write to a watched object retires the whole leg-B cache.
• B. Keyed. Retire only entries for the affected user / organization.

Real business need: the pull is cloud#1521's fixed per-request cost. Coarse delivers it on
read-heavy traffic, which is the measured shape (a Console cold load fires 27 API calls). Keyed
only wins on write-heavy tenants, and nobody has measured one. Long-term soundness: coarse has
one rule; keyed needs a correct write→entry mapping that §2.2 shows the seam does not supply, and
§B.3 shows is counter-intuitive for org_user_ids. AI-safety: decisive for coarse — keyed
invalidation is the shape where a wrong mapping over-permits silently, and it is exactly the kind
of mapping an AI-authored change extends without noticing org_user_ids. Startup scope: coarse
is less code and no new concepts. ⇒ A, and keyed is not a follow-up to schedule — it is a
follow-up to justify with a measurement first.

Fork 2 — multi-node: TTL-only vs adding an authz.invalidated channel

• A. TTL-only (per-process caches, no cross-node signal).
• B. TTL + a new channel on the existing at-most-once bus (recommended).

Real business need: cloud runs more than one instance, so under A every grant change costs a
full TTL on every node that did not serve the write. Long-term soundness: B reuses a shipped
transport and a shipped bridge pattern; it adds no dependency and no new failure mode, because
the TTL still bounds the worst case — B is strictly a narrowing of the typical window. AI-safety:
B is safe only if nobody is allowed to read it as the correctness mechanism; the design must say
in the code, at the channel, that a missed message is expected and the TTL is the contract.
Startup scope: B is small precisely because MetadataClusterBridgePlugin already shows the
shape. ⇒ B, with the §3 boot-time posture statement as a non-optional part of it.

Fork 3 — leg A's remaining half (better-auth's own session read)

• A. Leave it (recommended for this card). Session reads stay uncached; decision(plugin-auth): 会话的「记录之处」到底在哪 —— better-auth secondaryStorage 一旦接上 cache，ADR-0069 D4 的会话管控就静默失效 #4785's ruling stands.
• B. Re-open decision(plugin-auth): 会话的「记录之处」到底在哪 —— better-auth secondaryStorage 一旦接上 cache，ADR-0069 D4 的会话管控就静默失效 #4785 Option B — session of record moves to the cache, ADR-0069 D4's revocation is
  rewritten to invalidate the cache as well as write the row.

Real business need: it is ~2 of a request's reads after legs B/C/D land — the smallest remaining
share. Long-term soundness: B requires an ADR revision and makes revocation a two-place
consistency problem; #4785 already analysed it and the maintainer already chose A. AI-safety:
#4785's own words — "撤销从一次写变成两处一致性，AI 生成的新管控极易只写一半". Startup scope:
reopening a settled architectural decision for the smallest remaining win is the definition of
scope diffusion. ⇒ A. If B is ever wanted, it is a decision card that re-opens #4785, never a
performance card.

Fork 4 — the one number to confirm

Leg B's default TTL. This design recommends 0 (off by default) with a supported low-seconds
range, for the reason in §4 (leg B). The card rules "short, default conservative"; 0 is the most
conservative reading, and it makes the deployment's acceptance of a staleness window explicit.
If the maintainer wants leg B on by default, that is a posture change this design does not
assume — it is named here rather than chosen quietly.

---

9. Deliverable form — why this is a comment and not an ADR

Judgement: ADR-class in substance, not yet ripe to write as an ADR.

In substance it is exactly what this repo's ADRs record: a durable, cross-package rule ("no
authorization answer is cached without a declared invalidation contract and a TTL bound"), a
staleness posture, and a set of obligations future authors inherit. The repo has 129 ADRs,
including narrower ones.

But two of its load-bearing premises are unlanded rulings — #10348-C is dispatched and not
merged, and #11663 is awaiting a maintainer decision that changes what "grants" even means (§6). An
ADR written now would record a decision the maintainer has not made, on a surface that is moving,
and docs/adr/** is a governed surface where the cost of getting that wrong is a human merge to
undo.

⇒ Proposal: accept or amend this design here; on acceptance, the first follow-up card converts it
to an ADR — by then #10348-C has landed and #11663 is ruled, and the ADR can state the rule
against a stable shape rather than against two pending ones. pr: null for this card accordingly.

---

10. Proposed implementation split — proposed, not filed

Per the dispatch, no cards were filed. Ordering is by rising invalidation difficulty, and each
step's substrate is used by the next.

1. Leg C — cache successful localization reads. Subscribe to the existing settings change bus;
   engine-seam backstop on sys_setting; TTL bound. Acceptance test already exists.
2. Leg D — getMetaItems overlay cache, epoch-keyed. Reuses metadata.changed cross-node.
   Must resolve the SchemaRegistry-hydration trap (§4, leg D) explicitly in the PR body.
3. The invalidation substrate. Extract the engine-seam epoch (generalising plugin-security's
   writeEpoch) plus the optional authz.invalidated channel and the boot-time posture statement.
   Done once, before leg B, so leg B does not carry it.
4. Leg B — grants cache. Blocked-by: [finding] Three spellings of the ADR-0068 platform-admin read now live in plugin-auth, and one of them skips the system read context #10348. Carries pins 1–7 and 9, and the required
   ablation of write-invalidation.
5. Leg A remainder — a decision card, not an implementation card: re-open decision(plugin-auth): 会话的「记录之处」到底在哪 —— better-auth secondaryStorage 一旦接上 cache，ADR-0069 D4 的会话管控就静默失效 #4785 Option B, or
   record that A2 stays uncached. Ordered last because legs B/C/D shrink what is left of it.
6. (Spec seat, if needed) a declared shape for the invalidation event / posture value. Not
   taken by this design.

Honest scoping note, carried forward from every card in this lineage: tranches 1 + 1b did not
clear cloud#1521's gate, and this design should not be read as clearing it either. §1 counts
queries and legs, not milliseconds, and placement (cloud#1518) is the other half — NOT MEASURED
from this session.

---

Generated by Claude Code

---

Generated by Claude Code

[claude]

os-dev-report

{
 "issue": 11633,
 "status": "done",
 "branch": "claude/issue-11633-cross-request-cache-design",
 "pr": null,
 "premise_still_valid": true,
 "summary": "Design delivered as the issue comment (5394942824), no product code, no cards filed. The card's premise holds: none of the four legs is cross-request cached on main today, and the invalidation design was genuinely undecided. But ONE named sub-direction it inherited from #10757 is FORECLOSED and I did not design around it: direction 1 (leg A, 'enable better-auth cookieCache or secondaryStorage') collides with #4785, which is CLOSED as completed via merged PR #5101 fixing the session of record as sys_session, and is pinned by plugin-auth/src/session-of-record.test.ts whose tests are named 'opting into cacheSecondaryStorage empties sys_session and makes idle timeout inert', 'option C (dual-write) is not reachable through config', and 'the DEFAULT composition refuses to boot with a secondaryStorage rather than degrading quietly'. So leg A splits: its customSession half is DELETED by #10348-C and should be served by leg B's cache rather than designed separately, and its better-auth half is a decision surface (re-open #4785), not a cache-design surface. Design core: the unit is 'a cached answer plus the contract that says when it stops being an answer' -- write-invalidation at the ObjectQL engine middleware seam as primary (measured: better-auth's own adapter routes insert/update/delete through the engine, so one seam catches membership/ban/session/org-role writes; plugin-security already does exactly this with writeEpoch ahead of the isSystem bypass), plus a TTL as the bound. Multi-node is not a fork for grants: the ONLY shipped cross-node channel is IPubSub and it is at-most-once with no replay by its own doc, so a bus can never be the correctness mechanism -- it narrows the typical window, the TTL bounds the worst case. Recommend adding an authz.invalidated channel on the existing bus following MetadataClusterBridgePlugin's shape, plus a LOUD boot posture statement when a grants cache is on with no bus (a silently-absent bridge is exactly #4785's failure shape). Three constraints a naive keying gets wrong are called out with evidence: (B.1) ADR-0091 validity windows are evaluated at resolution time, so a cached envelope FREEZES an expiry -- no write happens at that boundary, so write-invalidation is blind to it by construction and an entry must expire at min(ttl, nextBoundary); I found this stated nowhere in the #10757 lineage. (B.2) seedPermissions/seedEmail are part of the answer and their order is contractual. (B.3) org_user_ids depends on OTHER users' sys_member rows, so a sys_member write must retire every entry for that ORG, not the written user's. Also: sys_session must stay OUT of leg B's watched set because enforceSessionControls writes last_activity_at once a minute per session, which under coarse invalidation would destroy the cache every minute. And explain-engine plus runAs automation must bypass the cache -- an explainer answering from cache explains a state that no longer exists, at exactly the moment an admin is verifying a revocation. Form: judged ADR-class in SUBSTANCE but not yet ripe, because two load-bearing premises are unlanded rulings (#10348-C dispatched-not-merged; #11663 awaiting ruling) and docs/adr/** is governed; proposed that the first follow-up converts it to an ADR once both settle. Hence pr: null, no draft PR, no governed surface touched.",
 "tests": "NO CODE WAS WRITTEN, so no gates are owed; this is a measurement record for a design. MEASUREMENT BASE: full (non-shallow, verified `git rev-parse --is-shallow-repository` = false) worktree cut from origin/main at 992161b728. origin/main moved one commit during the round (88b9d749a1, plugin-audit sys_activity vocabulary); `git diff --name-only` shows it touches ONLY plugin-audit objects/tests/translations, none of the files cited, so every measurement stands at both shas. `git merge-base --is-ancestor HEAD origin/main` exit 0. ZERO-HIT CLAIMS CARRY POSITIVE CONTROLS, exit codes captured BEFORE any pipe: (1) cookieCache repo-wide -- `git grep -n cookieCache > /tmp/cc.txt; E1=$?` gave exit=1 lines=0, and the control on the SAME instrument (`git grep -n customSession -- .../auth-manager.ts`) gave exit=0 lines=10, so the zero is a real absence and not a broken channel. (2) module-level caches on the authz path -- `git grep '^const .*= new WeakMap' -- packages/core/src/security/*.ts` exit=0 hits=1 (only #10221's localizationFailureCache), control over packages/*/src/** exit=0 hits=6. That control is what surfaced plugin-security/src/auto-org-admin-grant.ts:209 permissionSetIdCache -- an existing UN-invalidated, un-TTL'd process-lifetime cache on the authorization path; searched before treating it as new and found it ALREADY FILED as #11670 (open, bug, priority:p2), so nothing was filed. STATIC MEASUREMENTS, each read at a named line rather than recalled: resolve-authz-context.ts:319-630 (leg B's 4 waves, the isGrantActive/nowMs clock dependency, the limit-1000 fellow-org read, the seed handling and the needsUserRow condition); :648-828 (leg C, #10221's failure-ONLY cache and the getMany path); auth-manager.ts:3029-3140 (customSession's isPlatformAdmin doing an unfiltered `sys_permission_set limit 50` full page, plus activeOrgRoles) and :5734-5812 (enforceSessionControls' once-a-minute last_activity_at write and the revoke-by-writing-the-row mechanism); protocol.ts:5992-6120 (getMetaItems' queryByOrg(null) THEN queryByOrg(orgId), each with an alt-type retry on empty, plus the overlay-hydration branch that registers rows back into the SchemaRegistry -- the trap a naive leg-D cache hits); security-plugin.ts:815-845/:986-993/:1385-1400/:4320-4360 (the writeEpoch prior art and its own argument for why an epoch and not object identity); settings-service.ts:621/:767/:1180-1270/:1435/:1708/:2146 (the pre-existing subscribe/emitChange bus, the getMany two-load grouping, loadRows, and the fact that the event carries no tenant discriminator); objectql/src/engine.ts:1842 (OperationContext carries `object` + `operation`); plugin-auth/src/objectql-adapter.ts:689-691 (better-auth routes its writes through the engine -- the fact that makes the seam decisive); service-cluster-redis/src/pubsub.ts:78-92 and content/docs/kernel/cluster.mdx section 4.2 (at-most-once, no replay, 'no shipped driver provides at-least-once yet'); service-cluster/src/metadata-cluster-bridge-plugin.ts (the bridge silently returns when no cluster service is registered). CALL-SITE CENSUS: `git grep` for the three resolvers returns 17 non-test call sites across 12 packages, which is what identified explain-engine.ts:473 and service-automation/src/plugin.ts:812 as the two that must bypass the cache. RE-MEASURED RATHER THAN TRANSCRIBED, as the brief required: the card asserts the #10221 dogfood pin is satisfied by invalidation-on-write. Read analytics-timezone.dogfood.test.ts in full -- the write is a real PUT /api/settings/localization, the read is a SEPARATE HTTP request, and both run in ONE process, sequentially awaited. So the claim holds and is sharper than stated: a synchronous in-process invalidation satisfies it, a TTL alone does NOT (30s far exceeds the inter-request gap), and a deferred invalidation does not reliably either. That test already IS the leg-C acceptance test for 'write-invalidation primary'. PIN HARNESS REUSE VERIFIED: makeRecordingQl is `export`ed from resolve-authz-context.batch-equivalence.test.ts and counts real legs, so the identity pins can reuse it inside packages/core; noted in the design that check:cross-package-test-inputs means a pin outside core needs the repo's .testkit.ts convention (8 such files exist) rather than importing the test file. NOT MEASURED, DECLARED RATHER THAN FOLDED INTO A PASS: (a) NO DYNAMIC RUN. The worktree had no node_modules (`test -d node_modules` exit 1) and a dynamic capture would have needed a full monorepo install plus a dep-closure build; at first check the verify lock showed a holder at 465s with two heavy jobs already queued (it later freed). I narrowed the dynamic leg away and DECLARE it: no rig capture, no DEBUG=knex:query trace, no positive control of my own for the X-OS-Debug-Timing instrument this round. Every design claim above is a statement about code at a named sha, which is why the narrowing is a measurement decision and not a hole -- but leg A's better-auth query COUNT (sys_session + sys_user) is carried from the card's 2026-08-21 trace and is marked NOT MEASURED inline in the document; only its MECHANISM was re-verified. (b) cloud#1521 / cloud#1518 are out of this session's repo scope and are marked NOT MEASURED in the document; the design counts queries and legs, never milliseconds, and explicitly refuses to be read as clearing the 200ms gate. (c) No ablation was run because there is no code to ablate; the design instead REQUIRES the leg-B implementation card to ablate write-invalidation and report the observed direction. DELIVERY VERIFIED, not assumed: posted comment 5394942824 was fetched back and compared byte-for-byte against the local source. Content is fully intact (probes for session-of-record.test.ts, at-most-once, min(ttl, nextBoundary), org_user_ids, cookieCache, #4785, #10348-C, Fork 4 and the session-URL footer all present). The only delta is +58 bytes: the platform APPENDED a second, bare-form `_Generated by [Claude Code](https://claude.ai/code)_` footer after mine. Nothing was stripped or rewritten; I left the duplicate alone rather than editing a landed comment. CLEANUP: worktree removed with `git worktree remove` and NO --force on a clean tree (`git status --porcelain` 0 lines); directory confirmed gone; no dev servers or background processes were started, so none needed killing. The remote claim-marker branch remains at 992161b728 (the empty write-route probe push, which returned exit 0 in the first minute).",
 "open_questions": [
 {
 "question": "Fork 4 -- what is leg B's DEFAULT grants-cache TTL? This is the one number the design deliberately does not choose, because it is a security-posture default rather than a tuning value.",
 "options": [
 "A -- default 0 (cache OFF for leg B), supported non-zero range in the low seconds. Legs C and D ship enabled and deliver real latency; a deployment that wants the grants cache turns it on knowingly.",
 "B -- default a small non-zero value (order of seconds) for leg B, matching the card's 'short TTL, default conservative' wording read as 'on but short'."
 ],
 "recommendation": "A. Real business need: cloud#1521 pulls on fixed per-request cost, but legs C+D plus tranches 1/1b address it without any deployment absorbing a new staleness window it did not ask for. Long-term soundness: an explicit opt-in is what makes the boot-time posture statement meaningful rather than background noise. AI-safety: a default-off cache cannot silently widen an existing deployment's escalation window during an upgrade -- the direction that matters, because the failure is invisible. Startup scope: A ships the same code and defers only the posture change. If you want B, say so -- it is a posture change this design refuses to assume."
 },
 {
 "question": "Fork 3 -- leg A's remaining half (better-auth's own sys_session + sys_user read) is fenced by #4785, which is closed as completed with landed pins. Does it stay fenced?",
 "options": [
 "A -- leave it. Session reads stay uncached; #4785's ruling stands; leg A contributes nothing further to this design.",
 "B -- re-open #4785 Option B: move the session of record into the cache and rewrite ADR-0069 D4's revocation to invalidate the cache as well as write the row."
 ],
 "recommendation": "A. Real business need: it is ~2 of a request's reads once B/C/D land -- the smallest remaining share. Long-term soundness: B needs an ADR revision and turns revocation into a two-place consistency problem. AI-safety: #4785's own words, kept verbatim -- 'AI generated new controls very easily write only half'. Startup scope: reopening a settled architectural decision for the smallest remaining win is scope diffusion by definition. If B is ever wanted it is a DECISION card that re-opens #4785, never a performance card."
 },
 {
 "question": "Deliverable form -- the design is ADR-class in substance but two of its load-bearing premises are unlanded rulings (#10348-C dispatched not merged; #11663 awaiting your ruling). Convert to an ADR now, or on acceptance?",
 "options": [
 "A -- accept/amend the design as this comment now; the FIRST follow-up card converts it to an ADR once #10348-C has landed and #11663 is ruled, so the ADR states the rule against a stable shape.",
 "B -- require an ADR draft PR now (governed surface: draft PR, human merge), recording the rule against today's shape and amending it later."
 ],
 "recommendation": "A, which is why this card returns pr: null. An ADR written now would record a decision you have not made, on a derivation #11663 may remove, on a governed surface where undoing it costs a human merge. The design already states which parts depend on each ruling, so nothing is lost by sequencing the ADR after them."
 }
 ],
 "out_of_scope_findings": [
 "NOTHING FILED -- this dispatch fenced card-filing, and neither candidate needed it. (1) plugin-security/src/auto-org-admin-grant.ts:209 permissionSetIdCache is a process-lifetime, un-TTL'd, un-invalidated name->id cache on the authorization path; searched before acting and it is ALREADY FILED as #11670 (open, bug, priority:p2), which names the same cache and a wider defect. Flagged here only because #11663/#11532 plan to reap org-less permission-set rows, and a reap while a process holds that cache is exactly when it bites. (2) The `cookieCache` door is unguarded while the `secondaryStorage` door is boot-refused -- the same #4785-rejected architecture reachable through a config key nothing pins. I did NOT file this as a separate finding because it is not an unrelated defect: it is a direct input to leg A's mechanism choice, so it belongs in the design document, where it is recorded in section 4 (leg A). Noting the reasoning explicitly so the judgement is reviewable rather than silent."
 ]
}

---

Generated by Claude Code

[os-sam]

Design delivered — pm:dispatched → needs-user-decision, assignee cleared

Design-only dispatch closed as specified: no product code, no PR (pr: null), no ADR, no follow-up cards filed. The document is comment 5394942824. Three forks need your ruling.

⛔ This seat does not rank the three forks and does not restate the design's recommendations as its own. They are the designer's, with four-axis passes, in its own words. Read 5394942824.

Three things flagged so they cannot be lost in a long document

① ⭐ One direction this card INHERITED from #10757 is already foreclosed — and the designer did not quietly design around it.

Direction 1 for leg A ("enable better-auth cookieCache or secondaryStorage") collides with #4785, which is closed as completed via merged PR #5101 fixing the session of record as sys_session, and is pinned by plugin-auth/src/session-of-record.test.ts — whose test names say it outright: "opting into cacheSecondaryStorage empties sys_session and makes idle timeout inert", "option C (dual-write) is not reachable through config", and "the DEFAULT composition refuses to boot with a secondaryStorage rather than degrading quietly."

⇒ Leg A splits: its customSession half is deleted by #10348-C and should be served by leg B's cache rather than designed separately; its better-auth half is a decision surface (re-open #4785), not a cache-design surface. That is Fork 3.

② ⭐ A gap in the ruled direction itself, surfaced by measurement — and stated nowhere in the #10757 lineage.

The ruling says write-invalidation is primary and TTL is only the fallback bound. The designer measured that this cannot hold for one class:

ADR-0091 validity windows are evaluated at resolution time, so a cached envelope FREEZES an expiry — no write happens at that boundary, so write-invalidation is blind to it by construction.

⇒ An entry must expire at min(ttl, nextBoundary). For grant expiry there is no write to hang invalidation on, so the timer is not a fallback there — it is the only mechanism. Worth your eye because it qualifies the ruled direction rather than implementing it.

Two more keying traps recorded with evidence: org_user_ids depends on other users' sys_member rows, so a sys_member write must retire every entry for that org, not the written user's; and sys_session must stay out of leg B's watched set, because enforceSessionControls writes last_activity_at once a minute per session — coarse invalidation would destroy the cache every minute.

③ ⭐ Two call sites must bypass the cache, found by a 17-call-site census across 12 packages: explain-engine.ts:473 and service-automation/src/plugin.ts:812. The designer's reason is the sharpest line in the document — an explainer answering from cache explains a state that no longer exists, at exactly the moment an admin is verifying a revocation.

Multi-node: answered from the shipped contract, not assumed

The only shipped cross-node channel is IPubSub, and it is at-most-once with no replay by its own documentation (cluster.mdx §4.2: "no shipped driver provides at-least-once yet"). ⇒ A bus can never be the correctness mechanism — it narrows the typical window; the TTL bounds the worst case. Recommendation is an authz.invalidated channel plus a loud boot posture statement when a grants cache is on with no bus, because a silently-absent bridge is exactly #4785's failure shape.

Form: ADR-class in substance, deliberately not written yet

The designer judged this ADR-class but not ripe, because two load-bearing premises are unlanded rulings — #10348-C is dispatched-not-merged and #11663 awaits your ruling — and docs/adr/** is a governed surface. Hence pr: null and no governed surface touched. That is Fork 5 in the document and this seat agrees with the sequencing on process grounds: ⛔ an ADR written now would record a decision you have not made, on a derivation #11663 may remove, on a surface where undoing it costs a human merge.

Re-measured rather than transcribed — and it changed the claim

This card asserts the #10221 dogfood pin is satisfied by invalidation-on-write. The designer read analytics-timezone.dogfood.test.ts in full instead of transcribing: the claim holds, and is sharper than stated — a synchronous in-process invalidation satisfies it, a TTL alone does not (30s far exceeds the inter-request gap), and a deferred invalidation does not reliably either. That test already is leg C's acceptance test for "write-invalidation primary".

Declared narrowing, recorded as NOT MEASURED rather than folded into a pass

No dynamic run this round — the worktree had no node_modules and the verify lock showed a holder at 465s with two heavy jobs queued. So: no rig capture, no query trace. Leg A's better-auth query count is carried from the card's 2026-08-21 trace and is marked NOT MEASURED inline; only its mechanism was re-verified. cloud#1521 / cloud#1518 are out of this session's repo scope and are likewise marked NOT MEASURED — ⛔ the design counts queries and legs, never milliseconds, and explicitly refuses to be read as clearing the 200ms gate.

Nothing filed, and the reasoning is on the record

plugin-security/src/auto-org-admin-grant.ts:209's permissionSetIdCache — a process-lifetime, un-TTL'd, un-invalidated cache on the authorization path — was searched for before acting and is already #11670 (open, bug, priority:p2), so nothing was double-filed. Flagged only because #11663/#11532 plan to reap org-less permission-set rows, and a reap while a process holds that cache is exactly when it bites.

---

Generated by Claude Code