authz caching substrate: engine-seam write epoch (generalise plugin-security's `writeEpoch`) + `authz.invalidated` channel + boot-time posture statement

[os-support-ai]

Substrate step (§10.3) of the accepted #11633 cross-request caching design. Provenance: design document = #11633 comment 5394942824 (§2, §3, §10.3); maintainer acceptance = #11633 comment 5404681591 (2026-08-25, verbatim 「接受你的建议，继续」, Fork 2 → B). Filed by PM session session_01KWRU3s15AJz7PGW7a7wdCh.

Content: extract the engine-seam write epoch (generalising plugin-security's writeEpoch) + add the authz.invalidated channel on the existing at-most-once IPubSub + the boot-time posture statement. Done once, before leg B, so leg B does not carry it.

Hard requirements from the ruling:

• The TTL is the correctness contract; the bus only narrows the typical staleness window. The code at the channel must say a missed message is expected — nobody may read the channel as the correctness mechanism (cluster.mdx §4.2: no shipped driver provides at-least-once).
• The boot-time posture statement is non-optional: a loud line whenever a grants cache is enabled with no bus bridge (a silently-absent bridge is decision(plugin-auth): 会话的「记录之处」到底在哪 —— better-auth secondaryStorage 一旦接上 cache，ADR-0069 D4 的会话管控就静默失效 #4785's failure shape).

Acceptance criterion: with the substrate landed and no cache consumers yet, runtime behaviour is unchanged; the posture line appears exactly when a cache flag is on without a bus, and not otherwise.

Downstream: leg B (grants cache) declares Blocked-by: on this card. Premise-first: design measured at 992161b728; re-verify seams on current origin/main.

[os-trump]

Triage (half-label repair, daily full round): the engine-seam write epoch + authz.invalidated channel land in the query-engine seam (generalising plugin-security's writeEpoch up into the engine) — domain:engine. Substrate leg of the #11633 ruled caching design; sibling legs carry their own domains. Type Task.

---

Generated by Claude Code

[os-warren]

Claimed and dispatched — substrate first, as the ruling sequences it

• Session: session_01W6HFzyH98W1YaQXhJUJt6o (seat post [PM seat] domain:engine — 🟢 session_01LZbWd2jNV1FErXTPSS4Dry · R1 派发轮 #6367)
• Branch: claude/issue-11968-authz-cache-substrate
• Comments re-read in the same action as the claim: one, triage's grading. No prior claim by any other session.

Dispatched before its siblings deliberately: triage records this as the substrate leg and leg B (#11967, the grants cache) declares Blocked-by: on it. Doing it once here is the point — "done once, before leg B, so leg B does not carry it." #11966 and #11967 stay in pm:queue behind it.

The two hard requirements go to the dev verbatim, because both are the kind that get softened into a comment and then quietly dropped:

1. ⭐ The TTL is the correctness contract; the bus only narrows the typical staleness window. The code at the channel must say that a missed message is expected — no shipped driver provides at-least-once (cluster.mdx §4.2). Anyone reading the channel as the correctness mechanism has misread it, and the place to prevent that is the channel itself, not the design doc.
2. ⭐ The boot-time posture statement is non-optional: a loud line whenever a grants cache is enabled with no bus bridge. A silently-absent bridge is decision(plugin-auth): 会话的「记录之处」到底在哪 —— better-auth secondaryStorage 一旦接上 cache，ADR-0069 D4 的会话管控就静默失效 #4785's failure shape, and this card exists partly to stop it recurring.

The acceptance criterion is an honest one and I have told the dev to treat it as the pin: with the substrate landed and no cache consumers yet, runtime behaviour is unchanged — the posture line appears exactly when a cache flag is on without a bus, and not otherwise. Both arms.

One thing in flight the card could not name

PR #12519 is an open draft from another lane: ADR-0127 — no authorization answer is cached without a declared invalidation contract and a TTL bound. It is a governed surface (docs/adr/**), so ⛔ the dev must not touch it, and must not treat a draft ADR as a ruling. But it constrains exactly this substrate, so the brief says: read it, and if its shape conflicts with what #11633 ruled, stop and report the conflict rather than improvising a reconciliation. A ruled design and a draft ADR disagreeing is a maintainer question, not a dev one.

Premise-first, as the card itself instructs: the design was measured at 992161b728 and the seams must be re-verified on current origin/main. That instruction has earned its keep four times today — a premise I supplied has been corrected by measurement on four separate cards, most recently an hour ago.

Serial check: lands in the query-engine seam, generalising plugin-security's writeEpoch. The two cards in flight are #12559 (i18n extract configs) and #9276 (driver-memory / driver-mongodb). No overlap.

---

Generated by Claude Code

[os-warren]

Dispatch killed by a container restart — work recovered and pushed, not verified

The dev seat was killed mid-task when the container restarted. Its worktree survived; its work did not reach origin. Recovered at 17:5xZ:

• 0 commits, but 14 uncommitted modified/added files on container-local disk only, including three new files: packages/objectql/src/write-epoch.ts, packages/plugins/plugin-security/src/write-epoch-source.ts, packages/services/service-cluster/src/authz-cluster-bridge-plugin.ts.
• Committed as 4ea453ae55 and pushed. The commit message says plainly what it is: NOT REVIEWED, NOT VERIFIED — no gate was run, no test was run, no ablation exists, and neither of the ruling's two hard requirements has been checked for presence (the TTL-is-the-correctness-contract note at the channel, and the non-optional boot-time posture statement).

I am not vouching for any of it. A resuming dev should inspect it, and git reset + re-derive is a legitimate and backed choice.

State is now honest: the card stays pm:dispatched with work on the branch that nobody has verified. Whoever resumes should re-read the dispatch conditions on this card and the parent #11633 rather than assuming the recovered code implements them — the shape of the files suggests the substrate was being built, but "suggests" is not a measurement.

Second stall-and-recover on this seat today; the first (#12068 / #11671 / #12393 at 09:00Z) is recorded on those cards and in §7 of the seat post #6367.

---

Generated by Claude Code

[os-warren]

{
 "issue": 11968,
 "status": "done",
 "branch": "claude/issue-11968-authz-cache-substrate",
 "pr": "https://github.com/objectstack-ai/objectstack/pull/12652",
 "premise_still_valid": true,
 "recovered": {
 "kept": "All 14 files of 4ea453ae55, unchanged except for five repairs the verification found. Read each against the ruling and re-verified its seams by symbol on current origin/main before keeping it. git reset + re-derive was on the table and was NOT taken: the recovered code satisfies both hard requirements (measured), builds (30/30 then 70/70 turbo tasks), and its shape is the one 11633 s2.1/s3 argue for. The five repairs: limit-blind stub driver (check:objectql-double-limit), missing vitest source alias for service-cluster (check:test-source-alias), three `as any` query bags (check:query-options-erasure), and two shrink-only ledger drifts repaired at source, never by raising a ratchet.",
 "rederived": "The entire verification layer, which did not exist. Full workspace build; five package suites (objectql 241f/4227t, runtime 196f/2879t, plugin-security 85f/1554t, core 40f/1009t, service-cluster 4f/66t, all exit 0); three NEW test files carrying 56 cases (write-epoch.test.ts, authz-invalidation-bridge.test.ts, authz-cluster-bridge-plugin.test.ts); two ablations with written predictions; the 54-gate union at the final head; repo-wide eslint. Plus the changeset, the OS_AUTHZ_GRANTS_CACHE_TTL_MS row in the canonical env table, and one deliberate direction change in runtime.test.ts.",
 "discarded": "Nothing. No file and no part of any file was reverted."
 },
 "clause2": "accept/reject: NO. public surface: YES, additively, and packages/spec is untouched.",
 "clause2_evidence": "No schema, no parse, no refusal changed - nothing that parsed before is rejected now and nothing rejected before is accepted; the posture statement is a log line, not a gate. Surface widening, named precisely: @objectstack/core gains 1 const (AUTHZ_INVALIDATED_CHANNEL) + 3 functions (resolveAuthzCachePosture, readAuthzGrantsCacheTtlMs, reportAuthzCachePosture) + 1 const (AUTHZ_GRANTS_CACHE_TTL_ENV) + 8 types; @objectstack/objectql gains WriteEpoch, isWriteEpochLike, isWriteEpochOperation, WRITE_EPOCH_OPERATIONS, bridgeAuthzInvalidation + 4 types, plus three public members on ObjectQL (writeEpoch, attachAuthzInvalidationPubSub, detachAuthzInvalidationPubSub); @objectstack/service-cluster gains AuthzClusterBridgePlugin and isInProcessClusterDriver. No existing signature changed, nothing removed or renamed. The authz.invalidated payload is deliberately NOT a packages/spec contract type - 11633 s5 reserves that shape for the spec seat and does not pre-commit it.",
 "ttlContractStatedAtChannel": "PRESENT, measured. packages/core/src/security/authz-invalidation-channel.ts is the module that declares AUTHZ_INVALIDATED_CHANNEL, so a consumer cannot import the constant without the rule being in the file they opened. It states that a missed message is EXPECTED, cites the three measured sources (cluster.mdx s4.2 'No shipped driver provides this yet', service-cluster-redis's own publish docblock, the memory driver's no-cross-process note), and states the consequence in the form a misuse would violate. Restated at both other arrival points: ObjectQL.attachAuthzInvalidationPubSub's docblock and authz-invalidation-bridge.ts. Also STRUCTURAL, not only prose, and that half is pinned: publish failure (rejecting or synchronously throwing) is logged at debug and swallowed, never awaited by the writer, epoch already advanced.",
 "postureLineBothArmsPinned": "PRESENT, both arms, at both levels. Decision level: authz-cache-posture.test.ts with an enumerated 3x3 ttl-by-bus matrix, so 'exactly when' is measured rather than described. Boot level: authz-cluster-bridge-plugin.test.ts - loud arm (no cluster service / in-process driver / remote driver with no engine seam / failed attach / malformed TTL) and silent arm (shipped default attaches nothing and says nothing above debug). Unchanged-behaviour half: write-epoch.test.ts 'with no consumers, the substrate is inert' - a fresh engine has ZERO epoch subscribers, so a write advances a counter nobody reads. The in-process case is a distinct bus state on purpose: Runtime registers the memory driver by default, so 'is a cluster service registered?' answers yes on the shipped default while fanning out to nobody.",
 "adr0127Conflict": "NO CONFLICT. PR 12519 (draft, docs/adr/**) not touched and not treated as a ruling. Its D4 is the same rule this PR implements in the ruling's own words; D2 (engine seam, never a call-site list) and D3 (coarse baseline) match s2.1/s2.2 and Fork 1 -> A; D6 (off by default, 0 a real path, deployment config never a settings row) is what readAuthzGrantsCacheTtlMs implements. Nothing to escalate.",
 "gates": {
 "green": "54 families, all at final head 756786cc2e, each exit captured BEFORE any pipe. Matched-by-path: check:cross-package-test-inputs, check:durability-log-level, check:kernel-hook-pairs, check:objectql-double-limit, check:page-declaration-shape, check:published-files, check:slot-lookup, check:stack-collection-maps, check:test-source-alias, check:type-source-resolution, check:role-word, check:react-page-adapter-contract, check:published-readme-links, check:doc-anchors, check:doc-authoring, check:docs-audit-scope, check:docs-redirects, check:docs-single-h1, check-adr-0087-registration, check-changeset-no-major, check-empty-changeset, check-ci-filter-parity, check-comment-mask-adoption, check-cross-package-test-inputs, check-doc-frontmatter, check-doc-route-spelling, check-docs-section-name, check-engine-split-ratio, check-plugin-teardown-shape, check-section-landing-index, docs-audit/check-affected-docs, docs-audit/check-drift-comment, pm/release-rehearsal-clone --self-test, check:changeset-gate-self-tests, check:objectui-changeset, spec check:docs/empty-state/liveness/skill-examples/strictness-ledger/variant-docs, lint check:doc-formula-expressions/doc-security-posture. Convention-triggered: check:engine-double-contract, check:where-matcher, check:query-options-erasure, check:i18n, check:i18n-stale-fill, check:type-check-coverage, check:type-check-debt (--re-measure: '31 ledger entries re-measured, 1687 raw tsc errors total, none above its recorded number'). Run BY HAND because the derivation cannot name them and this diff adds exported names: spec check:api-surface, spec check:export-origins, root check:published-readme-exports, check:nul-bytes. Plus repo-wide `eslint . --no-inline-config` exit 0 in 62s - NOT narrowed, so no narrowing claim is being made.",
 "red": "None at the final head. FOUR were red mid-task and were repaired at the source, listed because the repair is the finding: check:objectql-double-limit (new stub driver's find was limit-blind), check:test-source-alias (service-cluster test reached @objectstack/core through the workspace link i.e. dist/), check:query-options-erasure (240->243, three `as any` query bags on calls the engine already types), check:type-check-debt (service-cluster DEBT +1, objectql TEST_DEBT +3 - repaired by giving registerObject its required package id and typing the attach mock's parameters; NEITHER ledger was raised). Also two existing runtime.test.ts pins went red - resolved in the direction the ruling requires, not by moving the registration.",
 "notMeasured": "check:type-check-debt refused once with 'cannot run: @objectstack/core has a type entry point OLDER than its own sources' - that is NOT MEASURED, not a red gate. Rebuilt core directly as the gate instructed, then it measured. Recorded because the exit code alone reads identically to a finding."
 },
 "ablations": [
 "A1 - the engine seam. Mutation: disable the epoch bump at the head of executeWithMiddleware. Predicted IN WRITING FIRST: RED, exactly 4 failed / 20 passed of 24, naming all four, and naming the deliberate non-movers ('no read verb advances it' passes VACUOUSLY at 0-before-0-after and is therefore not the seam's evidence; the 6 counter-contract cases and all 11 bridge cases drive WriteEpoch directly). On disk BEFORE any result was read: removed anchor 1->0, injected marker 0->1, `this.writeEpoch.bump('write');` 1->0. OBSERVED: 4 failed / 20 passed, exactly the four named. Restored under trap ... EXIT INT TERM; restoration verified more strongly than an empty diff - `git diff --exit-code` on the single mutated path AND both anchors measured back to their original counts.",
 "A2 - the 'and not otherwise' arm. Mutation: make ttl 0 fall through the disabled branch, i.e. an implementation that states a posture always. Predicted IN WRITING FIRST: RED, exactly 6 failed / 16 passed of 22, naming all six, and naming why 'ttl=0 bus=bridged -> quiet' must NOT move (the bridged posture speaks at info and that matrix row asserts on warn), so the count is 3+2+1 and not 3+3+1. On disk BEFORE any result: removed anchor 1->0, injected marker 0->1. OBSERVED: 6 failed / 16 passed, exactly those six, with the bridged row green. Restored under trap, same two-part verification.",
 "Neither ablation needed a rebuild, and that is a measurement rather than an assumption: both subjects are imported by RELATIVE path within their own package, which vitest resolves to src/. Evidence: an earlier failing run in this task printed the frame `ObjectQL.requireFindOnePredicate src/engine.ts:8595:11` - a src frame with src line numbers."
 ],
 "openQuestions": [
 "None blocking. One thing the maintainer may want to look at, stated rather than decided: Runtime now registers AuthzClusterBridgePlugin UNCONDITIONALLY, including under `cluster: false`, which changed an existing pin from 'kernel.use is not called at all' to 'exactly one plugin, the authz posture bridge'. The ruling's logic requires it - a missing bus is the loudest case the posture check has, and skipping it there puts the statement's absence exactly where the missing bus is (#4785's shape) - and the plugin is inert on the shipped default. But it does mean `cluster: false` no longer means 'this package contributes nothing', and if the maintainer prefers the posture statement to live outside the service-cluster package, that is a shape change rather than a bug."
 ],
 "out_of_scope_findings": [
 "filed as #12651: IPubSub's interface docblock in @objectstack/spec/contracts states 'At-least-once delivery', which contradicts cluster.mdx s4.2 ('No shipped driver provides this yet') and every shipped driver. Unassigned, no label, no repair attempted. Dedup search channel DECLARED: this session's REST endpoints answer HTTP 403 ('sessions are bound to their configured repositories' for /search/issues; 'GitHub access is not enabled for this session' for the repo-scoped issue list), so the pre-file search ran through MCP search - one call, zero results - plus a local grep of the two contradicting sources.",
 "NOT filed, already tracked upstream by #6376: check:type-check-debt reports @objectstack/runtime TEST_DEBT recorded at 227 while tsc measures 226 - one unit of slack in a shrink-only ratchet. Attributed by measurement rather than left as a guess: with only runtime.test.ts swapped between two test-inclusive tsc runs, the count is 226 before and 226 after this branch's edit, so the surplus is pre-existing and not this PR's to close."
 ]
}

---

Generated by Claude Code