docs(02-12.1): narrow two overstated claims

- the idempotency arm refuses only a wrongly-asserted context; an admin
  route behind unfenced requireAdmin still serves a headerless request
- the epoch trigger does not fire on a statement that names record_epoch
  without moving the selector; the source guard is what covers that
This commit is contained in:
Marc-André Bombeck committed 2026-08-06 20:48:50 +02:00
1 parent 731203bdf4
commit dc343f434c
7 files changed
+289 -136

No files matched your search

@@ -96,10 +96,10 @@ const CASES: AcceptanceCase[] = [
{
id: "FENCE-AC-07",
case: "IndexedDB and CacheStorage seeded with an owner snapshot, switch in, go offline",
home: "e2e/v137-record-session-fence.spec.ts",
home: "e2e/v137-record-session-fence-offline.spec.ts",
runner: "playwright",
instrument:
"Positive control first — the owner snapshot really was in CacheStorage before the switch, asserted by a non-zero entry count. Then the eviction claim of the cache-version policy, then a zero entry count after the switch, then offline with the target's own data reachable.",
"Positive control first — the owner snapshot really was in CacheStorage before the switch, asserted by a non-zero entry count. Then the eviction claim of the cache-version policy, then a zero entry count after the switch, then offline with the target record still named. It lives in its own spec and its own Playwright project because every other project sets serviceWorkers: 'block', under which the data cache is never populated and the positive control could not pass whatever the application did.",
},
{
id: "FENCE-AC-08",
@@ -89,12 +89,15 @@ const FENCED_RESOLVERS = ["requireRecordAuth", "requireGuardianAuth"] as const;
/**
* The helpers that deliberately do NOT consult the fence.
*
* This is a statement about the HELPERS and must not be read as "no admin route
* is ever fenced". `POST /api/admin/backups/[id]/restore` composes
* `withIdempotency` OUTSIDE `apiHandler`, so it is fence-visible through the
* idempotency arm even though `requireAdmin` itself is on this list — and that
* is wanted, not an oversight. An idempotent admin write under an unprovable
* context should be refused like any other.
* This is a statement about the HELPERS. It must not be read as "no admin route
* is ever fenced", and it must not be read as the reverse either.
* `POST /api/admin/backups/[id]/restore` composes `withIdempotency` OUTSIDE
* `apiHandler`, so the wrapper's fence check runs on it — but that check
* refuses only the STALE half. An `unfenced-client` verdict falls through to
* the handler, whose `requireAdmin` is on this list, so a headerless admin
* request is served exactly as it was before the fence existed. The accurate
* claim is therefore narrow: an idempotent admin write under a context the
* client asserted WRONGLY is refused; one that asserts nothing is not.
*
* Each entry's reason, once:
*
@@ -38,12 +38,17 @@
* the client's context is unknown — it is where the client LEARNS the
* context it would otherwise have to assert.
*
* That list is about the auth HELPERS, not about routes, and it is not
* absolute: `POST /api/admin/backups/[id]/restore` composes the idempotency
* wrapper OUTSIDE `apiHandler`, so it is fence-visible through the idempotency
* arm even though `requireAdmin` itself is unfenced. That is wanted. An
* idempotent admin write under an unprovable context should be refused like any
* other.
* That list is about the auth HELPERS, not about routes, and it is not quite
* absolute — but the exception is narrower than it first looks and the exact
* shape matters. `POST /api/admin/backups/[id]/restore` composes the
* idempotency wrapper OUTSIDE `apiHandler`, so the wrapper's own fence check
* does run on it. That check refuses only the STALE half: an `unfenced-client`
* verdict falls through to the handler, and the handler's `requireAdmin` is
* unfenced, so a headerless admin request is served exactly as before. So the
* accurate claim is "an idempotent admin write under a context the client
* asserted WRONGLY is refused", not "admin routes are fenced". A pre-fence
* admin tab keeps working, which is the deploy-compatibility posture
* everywhere else too.
*
* ─── Why there are two refusals and not one ───────────────────────────────
*