docs(adr): ADR-0127 - no authorization answer is cached without a declared invalidation contract and a TTL bound

[claude]

Fixes#11969

Converts the accepted cross-request caching design into docs/adr/0127-authorization-cache-invalidation-contract-and-ttl-bound.md. One new file; no code, no packages/spec, no content/docs/releases/**.

⚠️ Governed surface — this PR is not for a seat to land

docs/adr/** is governed. This PR stays a draft: not flipped ready, not enqueued, no auto-merge armed. The maintainer's merge is the review record. An open draft here is the finished state of the automated half.

Provenance — both rulings

• Design document: #11633 comment 5394942824
• Maintainer acceptance: #11633 comment 5404681591 — 2026-08-25, verbatim 「接受你的建议，继续」, accepting the design with its recommendation on all four forks
• The [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 condition, ruled met: #11663 comment 5404675670 — 2026-08-25

Premise check — the "#10348-C" token resolved

The card's surviving gate was written as "#10348-C", a token that does not resolve from outside: #10348 has no A/B/C legs, and "leg C" in this design's vocabulary is the caching leg C (#11966), which is unbuilt.

The dispatch pointed at "§10.1" of the design. ⚠️There is no §10.1 — §10 is "Proposed implementation split", a flat list of six items. The premise list lives in §6, "Dependency disclosure", restated in §9. It names exactly two premises, and the design defines the token itself in §4 (leg A/A1):

#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.

⇒ "-C" is Option C of #10348, a sub-part of that card — not leg C (#11966). §6's two premises are #10348-C and #11663; #11966 appears only as item 1 of the implementation split, i.e. something this design proposes to build, never something it depends on.

Both premises are down:

• [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 landed 2026-08-24 (completed by PR fix(auth): resolve the id-shaped platform-admin question in one place #11686). Verified against this tree, not just against the card: auth-manager.ts now carries zero platform-admin judges, and the derivation sits at packages/core/src/security/resolve-authz-context.ts with the remaining sites (admin-standing-surface.ts, last-admin-guard.ts, explain-engine.ts) consuming it rather than re-deriving it. That is the shape §6's "if it lands" branch describes.
• [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 ruled 2026-08-25.

The acceptance ruling independently spells the gate the same way: "the ADR conversion is the follow-up card, blocked on #10348 (the #11663 condition is met by today's ruling)." No "leg C" reading survives that sentence.

One place the card's summary and the design differ

Recorded because a card summarising a design is exactly where a rule quietly widens.

The card's shorthand is "no authorization answer is cached without a declared invalidation contract and a TTL bound." The design's §0 is narrower and structural:

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.

"A declared invalidation contract" can be read as a maintained list of call sites that remember to invalidate — and §2.1 explicitly rejects that reading, because a forgotten call site fails as silent over-permission, whereas a seam "cannot be forgotten, because writing through the engine is the only way to write at all."

⇒ The ADR keeps the recognisable shorthand as its title (that is the phrasing future citations will use) and adds D2 to fix what it means, so the weak reading is foreclosed on the record rather than left available. This follows ADR-0124's lesson about a rule whose citations drift from what it decides.

What the record decides

D1	Both halves required — observed write seam and TTL bound; neither alone is a design
D2	The invalidation contract is an engine seam, never a call-site list
D3	Coarse object-level invalidation is the baseline; keyed is gated behind a measurement (the seam cannot supply the mapping; org_user_ids makes the intuitive mapping wrong in the over-permitting direction)
D4	The TTL is the correctness contract; authz.invalidated on the existing at-most-once bus narrows the typical window only, with a non-optional boot-time posture statement
D5	Entries expire at min(ttl, nextBoundary) — validity windows see no write at their boundary, so write-invalidation is blind there by construction
D6	Grants cache off by default (TTL 0), supported low-seconds range, 0 a real path, knobs in deployment config never a settings row
D7	The session of record stays uncached, per #4785
D8	The explainer and runAs:'user' automation are never served from cache; sys_session is never watched
D9	Identity pins assert cached ≡ uncached, never a capability's provenance

The record states plainly that no implementation ships here and nothing is cached today — an ADR records a decision, and writing the rule before the code that must obey it is the intended order.

Changeset — deliberately none, skip-changeset

This PR ships nothing executable: one markdown file under docs/adr/, published by no package, imported by nothing, changing no runtime behaviour. There is no user-visible change for a release note to describe. ⛔ An empty changeset was not used — the skip-changeset label is this repo's mechanism for saying "publishes nothing", and it is applied.

Verification

Gate union derived on the actual changed set with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack (the --repo assertion held against this checkout's origin; the script took its own change set from the merge base — 1 path). Re-derived on the current tree rather than reused from the dispatch brief.

All gates re-run on the clean committed tree at 33f7fa07, exit codes captured before any pipe, under the shared verify lock (VERDICT command-exit 0):

gate	exit	the gate's own verdict line
check:adr-anchors	0	OK (52 anchored file(s) … 29290 citation(s) across 3670 file(s) resolve)
check-adr-links.mjs	0	564 relative link destination(s) under docs/adr/ resolve
check:doc-authoring	0	391 files clean — no bare metadata literals
check:pm-governed-merges	0	159 assertions … live: the real generator declared 9 output(s) and certified this tree
check:doc-formula-expressions	0	22 record-scoped formula example(s) across 423 files / 1450 TS blocks judged clean
check:docs-single-h1	0	180 page(s) under content/docs/ carry no body-level '# ' heading
check:doc-anchors	0	278 internal #fragment link(s) across 408 source file(s) all resolve to a real heading
check:adr-0087-registration	0	this PR adds no declared-breaking changeset
check:nul-bytes	0	scanned 6913 text file(s) … no raw ASCII control bytes

The five derived families are the first four rows plus check-adr-links.mjs; the rest were run because the docs/ADR families were expected to have an opinion rather than assumed inert.

⚠️check:doc-formula-expressions first exited 1 with PREREQUISITE NOT MET (@objectstack/formula, then @objectstack/lint, not built). That is not measured, not a red gate — recorded here because the exit code alone reads identically to a finding. Both packages were built and the gate then measured green, as above.

Anchors cited by the new record were verified to exist before citing: ADR-0091 D1/D2, ADR-0069 D4, and ADR-0049 (no D-headings, so cited bare).

Out-of-scope finding — filed for triage, no repair attempted here

#12518 remains open and is not addressed by this PR. scripts/pm/os-verify-lock.sh reads the & in a 2>&1redirection as a background operator, downgrading a correctly &&-joined command's verdict to batch-last-exit. Isolated to one variable in this container: true && true certifies, true > /dev/null 2>&1 && true does not. Filed unassigned; no fix attempted here.

---

Generated by Claude Code