@astilba/cache 0.0.0-stage → 0.1.0

package/dist/cache-Z4cJzPmm.js

@@ -0,0 +1,3528 @@
+import { createHash, createHmac } from "node:crypto";
+//#region src/errors.ts
+/**
+* Thrown by every public entry point during the correctness-kernel phase. A RED
+* invariant that fails with `NotImplementedError` is red for the right reason
+* (the kernel is unimplemented), as opposed to a toolchain/config failure.
+*/
+var NotImplementedError = class extends Error {
+	constructor(symbol) {
+		super(`${symbol}: not implemented in the correctness-kernel phase`);
+		this.name = "NotImplementedError";
+	}
+};
+/**
+* The single kernel-phase stub body. Every public function/method delegates here
+* so the switch to real logic is a body replacement with zero signature churn.
+* Callers pass their arguments through so parameters are genuinely referenced;
+* inside an `async` method the thrown error becomes a rejected promise.
+*/
+function notImplemented(symbol, ..._args) {
+	throw new NotImplementedError(symbol);
+}
+/**
+* Distinguishes cache-originated timeouts (retriable — evidence about origin
+* health) from caller aborts (not evidence of origin health).
+*/
+var CacheTimeoutError = class extends Error {
+	source;
+	constructor(source, message) {
+		super(message ?? `cache operation timed out (source: ${source})`);
+		this.name = "CacheTimeoutError";
+		this.source = source;
+	}
+};
+/**
+* Thrown by a `strong` read when the registry is unreachable. Opt out with
+* `onUnavailable: 'eventual'`.
+*/
+var RegistryUnavailableError = class extends Error {
+	/**
+	* `options.cause` carries the error this one displaced, where there was one. The serve-time
+	* re-validation of a graced candidate runs INSIDE a failed fill: if the registry is unreachable
+	* there, this error is what the caller sees instead of the factory failure that started it, so
+	* the factory failure rides along rather than being dropped. Nothing is lost and callers get one
+	* uniform type. Widened additively — `new RegistryUnavailableError(msg)` is unchanged.
+	*/
+	constructor(message, options) {
+		super(message ?? "registry unreachable", options);
+		this.name = "RegistryUnavailableError";
+	}
+};
+/**
+* Thrown by a read whose tag knowledge is UNKNOWN under `unknownPolicy: 'error'`.
+*
+* WHAT MAKES THIS DISTINCT FROM A MISS, AND WHY THE DISTINCTION IS THE POINT. Every other
+* fail-closed resolution refills from origin, which is hard-safe exactly when the origin is truth.
+* `'error'` is the policy for the case where it is NOT: a namespace under a takedown or a legal
+* embargo. There, an origin that has not caught up yet can lose a race with the purge and hand back
+* exactly the content that was supposed to vanish. So this policy declines to guess: it neither
+* serves the unknown value nor replaces it
+* with a fresh one, and the caller — who knows what the content is — decides. A policy that resolved
+* to the same refill as `'miss'` would be a switch that reads as protection and does nothing, which
+* is worse than no switch at all.
+*
+* Carries the key and the tags whose knowledge was unknown, so a caller can tell an embargoed
+* dependency from a cold one. EXACTLY those: the tags this read could not establish, and no others.
+* A payload of everything the entry declared cannot answer the question the field exists for — the
+* caller would have to guess which of them was the problem, which is the guess this policy refuses
+* to make on their behalf. Reserved (`__`-prefixed) tags never appear here: they are the kernel's
+* own bookkeeping, they are unknown for exactly the same reason the user's are, and naming them
+* tells the caller nothing they can act on.
+*/
+var UnknownTagError = class extends Error {
+	key;
+	tags;
+	/**
+	* `armedBy` names what selected this resolution — an explicit `unknownPolicy: 'error'`, or the
+	* `takedownSensitive` override that outranks it. The message used to state the former
+	* unconditionally, which was wrong precisely on the takedown path: the one place where the
+	* operator most needs to know which switch fired is the one where the message named the other.
+	*/
+	constructor(key, tags, armedBy = "unknownPolicy") {
+		const cause = armedBy === "takedownSensitive" ? "takedownSensitive is set" : "unknownPolicy is 'error'";
+		super(`read for key ${JSON.stringify(key)} has unknown tag knowledge and ${cause} (§5a, E9)`);
+		this.name = "UnknownTagError";
+		this.key = key;
+		this.tags = tags;
+	}
+};
+/** A typed HTTP error carrying the offending status and response. */
+var HttpError = class extends Error {
+	status;
+	response;
+	constructor(response) {
+		super(`HTTP ${response.status}`);
+		this.name = "HttpError";
+		this.status = response.status;
+		this.response = response;
+	}
+};
+/**
+* Thrown at the `getOrSet`/`getOrSetEntry` write boundary when a caller-supplied
+* tag is malformed — in particular a user tag beginning with the reserved `__`
+* prefix. A real runtime error, never `NotImplementedError`: tag
+* validation is not deferred kernel logic.
+*/
+var InvalidTagError = class extends Error {
+	tag;
+	constructor(tag, reason) {
+		super(`invalid tag ${JSON.stringify(tag)}: ${reason}`);
+		this.name = "InvalidTagError";
+		this.tag = tag;
+	}
+};
+/**
+* Thrown by `duration()` when a computed duration is malformed — a non-positive or
+* non-finite `value`, or (critical case) a `value × unitFactor` product that
+* is not a finite, positive, safe integer once multiplied out. A real
+* runtime error, never `NotImplementedError`: duration validation is not deferred kernel
+* logic. Mirrors `InvalidTagError` — the builder rejects a bad input, it never coerces one.
+*/
+var InvalidDurationError = class extends Error {
+	value;
+	unit;
+	constructor(value, unit, reason) {
+		super(`invalid duration ${JSON.stringify(String(value) + unit)}: ${reason}`);
+		this.name = "InvalidDurationError";
+		this.value = value;
+		this.unit = unit;
+	}
+};
+/**
+* Thrown by the plain `getOrSet` form when a fill is fenced past its write-back
+* retry attempt budget: a hard delete keeps landing mid-fill/mid-
+* refresh so the accepted result never postdates every purge visible at
+* write-back, and the fill fails within its attempt budget rather than ever
+* storing or serving a fenced value. A real runtime outcome, never
+* `NotImplementedError` — the entry form (`getOrSetEntry`) surfaces the same
+* outcome as `{ value: undefined }` instead of throwing.
+*/
+var FencedError = class extends Error {
+	key;
+	constructor(key, message) {
+		super(message ?? `fill for key ${JSON.stringify(key)} fenced past its write-back attempt budget (§5.0/MI6)`);
+		this.name = "FencedError";
+		this.key = key;
+	}
+};
+/**
+* Thrown when a factory declares a dependency after it has settled: a
+* `ctx.dependsOn`/`ctx.setTags` call reaching the context AFTER the factory promise
+* resolved or rejected. The fill's tag set closes at settle, so a later declaration is
+* outside the value's lifetime and cannot join it. A real runtime error, never
+* `NotImplementedError`. Carries the offending key.
+*/
+var FactorySettledError = class extends Error {
+	key;
+	constructor(key) {
+		super(`factory for key ${JSON.stringify(key)} declared a dependency after it settled (§2.1, E24)`);
+		this.name = "FactorySettledError";
+		this.key = key;
+	}
+};
+/**
+* The `EntryFactoryCtx.skip()` sentinel (M10, invariant 24) — a private
+* throw/catch signal, analogous to how a classified factory error rides
+* `fail()`. `skip()` is typed `never` so it never falsely resolves `undefined`
+* as a caller's `T`; `fillAndStore` catches this exact class and turns it into
+* a `{ skipped: true, value: undefined }` outcome — nothing is stored, nothing
+* is served. Never part of the public surface (not exported from `index.ts`).
+*/
+var SkipSignalError = class extends Error {
+	constructor() {
+		super("ctx.skip() called — the fill is skipped (nothing stored, nothing served)");
+		this.name = "SkipSignalError";
+	}
+};
+//#endregion
+//#region src/registry/mirror-keys.ts
+/** The default `regId` — single-registry deployments stay zero-config. */
+const DEFAULT_REG_ID = "default";
+/** The `regId` charset + length bound (`[a-z0-9._-]`, ≤ 64). */
+const REG_ID_PATTERN = /^[a-z0-9._-]{1,64}$/u;
+/**
+* Does `regId` satisfy the charset/length (`[a-z0-9._-]`, 1–64 chars)? The pure predicate
+* behind `assertRegId` — the SINGLE source of the grammar, so the machine's throwing gate and the
+* adapter's name-derivation refusal (`resolveRegId`) test the same rule and can never drift.
+*/
+function isRegId(regId) {
+	return REG_ID_PATTERN.test(regId);
+}
+/**
+* Validate a `regId` against the charset/length (`[a-z0-9._-]`, 1–64 chars) — the gate
+* that makes the scoped keyspace injective without escaping (the delimiter `:` cannot occur
+* inside a `regId`). Called at `configure` time (the machine's single seeding path), so a
+* malformed id fails LOUD before it can ever mint an ambiguous key. Throws on violation.
+*/
+function assertRegId(regId) {
+	if (!isRegId(regId)) throw new Error(`invalid regId ${JSON.stringify(regId)} — must match [a-z0-9._-], length 1-64 (E19)`);
+}
+/**
+* Build the registry-scoped mirror keys for `regId`. `regId` is expected to be
+* already validated (it enters the machine only via `configure`, which calls `assertRegId`);
+* this is a pure formatter on the hot flush/resync path, so it does not re-validate. Both the
+* writer (execute.ts) and the reader (invalidation.ts) address keys ONLY through here.
+*/
+function mirrorKeys(regId) {
+	const prefix = `__reg:${regId}:`;
+	return {
+		deltaKey: (seq) => `${prefix}delta:${seq}`,
+		snapKey: (seq) => `${prefix}snap:${seq}`,
+		stateKey: `${prefix}state`
+	};
+}
+//#endregion
+//#region src/tags.ts
+/** The two reserved tag namespaces: the per-key digest and the
+* per-namespace watermark. A user tag beginning with this prefix is rejected
+* at write — only the kernel itself may stamp `__k:<h>` / `__ns:<name>`. */
+const RESERVED_TAG_PREFIX = "__";
+/** Whether `tag` falls in the reserved `__`-prefixed namespace. */
+function isReservedTag(tag) {
+	return tag.startsWith(RESERVED_TAG_PREFIX);
+}
+/**
+* Validate one caller-supplied tag at the write boundary. Throws a
+* real `InvalidTagError` — never `NotImplementedError` — the instant a
+* `__`-prefixed tag reaches `getOrSet`/`getOrSetEntry`/a purge selector, so a
+* forged reserved tag can never be smuggled in as a "user" tag.
+*
+* Division of labor: the CHARSET/length/non-empty authority is the builders — `t`
+* validates-and-rejects, `compound` escapes — so a `Tag` they produce is already
+* well-formed. This write-time check is deliberately the NARROW `__`-prefix backstop,
+* not a re-validation: it catches only the one class the type system cannot — a
+* `__`-prefixed string force-branded to `Tag` (a raw `as Tag` cast, a harness `mkTag`,
+* any hand-forged brand) that never passed through a builder. It intentionally does NOT
+* re-check charset — narrow, not weak.
+*/
+function assertUserTag(tag) {
+	if (isReservedTag(tag)) throw new InvalidTagError(tag, `user tags may not begin with the reserved "${RESERVED_TAG_PREFIX}" prefix (§2.3, MI13)`);
+}
+/** The full tag charset: the design's `[a-z0-9:_\-.|]` extended with
+* `%` (`compound()`'s escape byte). One or more of these, nothing else. `-` is placed
+* last so it is a literal, not a range. */
+const TAG_CHARSET = /^[a-z0-9:_.|%-]+$/u;
+/** Maximum tag size — a UTF-8 BYTE budget, not code units. */
+const MAX_TAG_BYTES = 256;
+/** UTF-8 byte length of `s` — the tag budget is bytes, not string length. */
+function byteLength(s) {
+	return new TextEncoder().encode(s).length;
+}
+/**
+* Template helper for a single tag, e.g. ``t`book:${id}` ``. The tag TRUST
+* BOUNDARY: the interpolations (`values`) are UNTRUSTED user data, so `t` assembles the
+* template, then VALIDATES-and-REJECTS the final string against the full grammar
+* (non-empty, charset, ≤256 UTF-8 bytes, not `__`-prefixed) — throwing `InvalidTagError`
+* on any violation. It never escapes-by-guess: escaping is `compound()`'s separate
+* contract, and silently rewriting an interpolation is exactly how tag injection slips
+* through. On success returns the branded `Tag`.
+*/
+function t(strings, ...values) {
+	let assembled = "";
+	for (const [i, literal] of strings.entries()) {
+		assembled += literal;
+		if (i < values.length) assembled += String(values[i]);
+	}
+	if (assembled.length === 0) throw new InvalidTagError(assembled, "a tag must be non-empty (§2.3)");
+	assertUserTag(assembled);
+	if (!TAG_CHARSET.test(assembled)) throw new InvalidTagError(assembled, "a tag character is outside the [a-z0-9:_-.|%] grammar (§2.3, E10)");
+	if (byteLength(assembled) > MAX_TAG_BYTES) throw new InvalidTagError(assembled, `a tag may not exceed ${MAX_TAG_BYTES} UTF-8 bytes (§2.3)`);
+	return assembled;
+}
+/**
+* Escapes one `compound()` argument: `%` first (`%25`), then `:`
+* (`%3a`) and `|` (`%7c`), lowercase hex. Escaping `%` first guarantees the
+* mapping is injective — an escape-lookalike in the input (a literal `%3a`)
+* is itself escaped to `%253a`, so it can never be produced by escaping a raw
+* `:` (which yields `%3a`, with no leading `%25`).
+*/
+function escapePart(part) {
+	return String(part).replaceAll("%", "%25").replaceAll(":", "%3a").replaceAll("|", "%7c");
+}
+/**
+* Injective compound tag over an argument vector, e.g. `compound('book', id,
+* 'locale', locale)`. Escaping; empty vector distinct from
+* `['']`.
+*
+* Every part is escaped so an escaped part can never itself
+* contain an unescaped `|`; joining escaped parts on `|` is therefore an
+* injective join. An explicit leading arity count (itself `|`-terminated)
+* makes the count unambiguous — it is always a decimal-digit run followed by
+* the first `|` — which in turn makes vectors of differing length (including
+* the empty vector vs. `['']`) distinct regardless of what the escaped parts
+* contain.
+*/
+function compound(...parts) {
+	return `${parts.length}|${parts.map(escapePart).join("|")}`;
+}
+/**
+* A globally-scoped tag — its own scope-prefix escape hatch. Deferred to v0.4:
+* its escape-FORM is a wire-compatibility decision reserved for the scope-qualification
+* design, and ships with that consumer rather than standalone here.
+*/
+function globalTag(name) {
+	return notImplemented("globalTag (deferred to v0.4)", name);
+}
+//#endregion
+//#region src/telemetry.ts
+/**
+* The telemetry event-name CATALOG — the single, kernel-hosted registry of every
+* event `type` this library emits, the same shape as the exported error classes. Each member is an
+* event NAME; the value equals the key so a producer can reference a name as `TELEMETRY_EVENTS.<name>`
+* (a literal type, refactor-safe) while `TelemetryEventName` (below) is the union of them all.
+*
+* The names are grouped by their emitting LAYER (kernel / L1 driver / react-router adapter /
+* cloudflare adapter) — the annotation the charter requires. The machine-checked layer map (which
+* fails to compile if a member is unannotated) lives in the catalog's exhaustiveness tooth in the
+* test lane.
+*
+* GROWTH: adding a name is ADDITIVE and consumer-SAFE (a sink RECEIVES events, so a producer that
+* emits a wider vocabulary hands a consumer a value from a set it already types against — narrowing,
+* not widening, at the receiver) — so a new name is a MINOR-version change. Removing or renaming one
+* is breaking.
+*/
+const TELEMETRY_EVENTS = {
+	writeback_throttled: "writeback_throttled",
+	l2_write_error: "l2_write_error",
+	singleflight_option_mismatch: "singleflight_option_mismatch",
+	store_read_suppressed: "store_read_suppressed",
+	neg_suppressed: "neg_suppressed",
+	private_evicted: "private_evicted",
+	poll_tick_failed: "poll_tick_failed",
+	l3_ineligible: "l3_ineligible",
+	regid_divergence: "regid_divergence",
+	bus_dial_failed: "bus_dial_failed",
+	strong_degraded: "strong_degraded",
+	registry_degraded: "registry_degraded",
+	state_stale: "state_stale"
+};
+/** Report a swallowed sink failure to the injected hook, itself guarded. The hook is app code at the
+* very end of the swallow chain, so its own failure has no meta-channel to report to — swallowed, so
+* `safeEmit` cannot throw or float through it. */
+function reportSinkError(hook, error) {
+	if (hook === void 0) return;
+	const called = hook;
+	try {
+		Promise.resolve(called(error)).catch(() => {});
+	} catch {}
+}
+/**
+* Emit ONE event through an app-supplied sink so that NOTHING it does can escape (
+* the swallow-wrap extracted from the poll driver and made shared). A sink is arbitrary app code;
+* both of its failure modes are neutralized here:
+*
+*   • a SYNCHRONOUS throw → the `try`/`catch` (without it the caller's own path would throw);
+*   • a REJECTING thenable → the returned value is ADOPTED (`Promise.resolve(...).catch(...)`) so a
+*     rejecting `async` sink can never float out as an unhandled rejection.
+*
+* On either failure the injected `onSinkError` hook is called exactly once for that emit. `safeEmit`
+* NEVER throws and returns nothing the caller must await (adopt-don't-await: it must not inherit
+* app-code latency on a background or response path).
+*
+* The TYPE is the structural tooth: `event` is a `TelemetryEvent`, whose `type` is the CATALOG
+* union — so an off-catalog event name is a COMPILE error at the call site, never a grep finding.
+*/
+function safeEmit(sink, event, onSinkError) {
+	if (sink === void 0) return;
+	const called = sink;
+	try {
+		Promise.resolve(called(event)).catch((error) => {
+			reportSinkError(onSinkError, error);
+		});
+	} catch (error) {
+		reportSinkError(onSinkError, error);
+	}
+}
+//#endregion
+//#region src/invalidation.ts
+/** The one reason class a `strong_degraded` emit carries today. */
+const STRONG_DEGRADED_REGISTRY_UNREACHABLE = "registry_unreachable";
+/** The channel's starting state, and the one a reader returns to saying rather than assuming: it has
+* never heard a `hello`. Named once so the three sites that compare against it cannot drift. */
+const NEVER_ESTABLISHED = "never-established";
+/** Build the `transient-miss` retry signal for `seq` (the single runtime literal source). */
+function transientMiss(seq) {
+	return {
+		kind: "transient-miss",
+		seq
+	};
+}
+/** Narrow an `unknown` to an index-readable object, or `undefined`. The
+* single narrowing assertion in this module: every field read off the result is
+* individually type-checked below before use, so the record view is sound. */
+function parseValueObject(value) {
+	if (typeof value !== "object" || value === null) return;
+	return value;
+}
+/** Parse a stored JSON string to an object, or `undefined` on a malformed body. */
+function parseJsonObject(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return;
+	}
+	return parseValueObject(parsed);
+}
+/** Read the `state` pointer shape from stored bytes. Malformed — including a
+* non-string or absent `regId` echo — ⇒ undefined (fail closed). */
+function readPointer(raw) {
+	const o = parseJsonObject(raw);
+	if (!o || typeof o.epoch !== "number" || typeof o.lastBatch !== "number" || typeof o.regId !== "string") return;
+	const snapBatch = typeof o.snapBatch === "number" ? o.snapBatch : 0;
+	const flushedAt = typeof o.flushedAt === "number" ? o.flushedAt : 0;
+	return {
+		epoch: o.epoch,
+		flushedAt,
+		lastBatch: o.lastBatch,
+		regId: o.regId,
+		snapBatch
+	};
+}
+/**
+* Read one watermark change from a parsed value. A CORRUPT change ⇒ `undefined`
+* (fail closed), DISTINGUISHED from a legitimately-absent optional axis:
+*   • a PRESENT-but-non-number `softEpoch`/`hardEpoch` (the field is on the object but is not a
+*     `number`) is corruption — dropping it and applying the rest would silently delete a purge
+* from history (a serve-dead vector under non-canonical KV writes);
+*   • an AXIS-EMPTY change (a `tag` but NEITHER a numeric `softEpoch` NOR a numeric `hardEpoch`)
+* violates the ≥1-axis rule.
+* An ABSENT optional axis stays legal — a change may legitimately touch a single axis. A corrupt
+* change holes its whole batch via `readFrame` (never a partial-apply); the caller fails closed.
+*/
+function readChange(value) {
+	const rec = parseValueObject(value);
+	if (!rec) return;
+	const { tag } = rec;
+	if (typeof tag !== "string") return;
+	const soft = rec.softEpoch;
+	const hard = rec.hardEpoch;
+	if ("softEpoch" in rec && typeof soft !== "number" || "hardEpoch" in rec && typeof hard !== "number") return;
+	if (typeof soft !== "number" && typeof hard !== "number") return;
+	return {
+		tag,
+		...typeof soft === "number" ? { softEpoch: soft } : {},
+		...typeof hard === "number" ? { hardEpoch: hard } : {}
+	};
+}
+/**
+* Read a `__delta` batch frame from stored bytes. Malformed ⇒ undefined. Exported so the
+* doBus wire codec (`src/adapters/cloudflare/wire.ts`) validates a wire-carried frame through the
+* SAME frame parser the KV-resync path uses — one parser for the durable mirror AND the live channel,
+* so a corrupt wire change fails closed exactly like a corrupt `__delta` byte (never a partial
+* apply). Additive export only: no reader branch changes, no behavior change (the corrupt-change
+* fail-closed semantics are pinned by `reader-corrupt-change-fail-closed`).
+*/
+function readFrame(raw) {
+	const o = parseJsonObject(raw);
+	if (!o || typeof o.fromEpoch !== "number" || typeof o.toEpoch !== "number" || !Array.isArray(o.changes)) return;
+	const changes = [];
+	for (const entry of o.changes) {
+		const change = readChange(entry);
+		if (!change) return;
+		changes.push(change);
+	}
+	return {
+		changes,
+		fromEpoch: o.fromEpoch,
+		toEpoch: o.toEpoch
+	};
+}
+/** Merge a frame's watermark changes into a knowledge map (max-on-write). */
+function applyChanges(known, frame) {
+	for (const change of frame.changes) {
+		const w = known.get(change.tag) ?? {
+			hardEpoch: 0,
+			softEpoch: 0
+		};
+		if (change.softEpoch !== void 0) w.softEpoch = Math.max(w.softEpoch, change.softEpoch);
+		if (change.hardEpoch !== void 0) w.hardEpoch = Math.max(w.hardEpoch, change.hardEpoch);
+		known.set(change.tag, w);
+	}
+}
+/** The validity table over an entry's `bornEpoch` and per-tag knowledge. */
+function classify(bornEpoch, knowledge) {
+	if (knowledge.some((k) => !k.known)) return "unknown";
+	if (knowledge.some((k) => k.known && k.hardEpoch > bornEpoch)) return "dead";
+	if (knowledge.some((k) => k.known && k.softEpoch > bornEpoch)) return "stale";
+	return "fresh";
+}
+/** The highest `throughEpoch` a live check verified (0 if none is `known`). */
+function throughEpochOf(knowledge) {
+	let max = 0;
+	for (const k of knowledge) if (k.known && k.throughEpoch > max) max = k.throughEpoch;
+	return max;
+}
+/** Default liveness heartbeat interval in ms — the cadence at which a live writer refreshes the
+* pointer's freshness field. The reader mirrors the coordinator's `REGISTRY_HEARTBEAT_MS`; the
+* 2b-2-b shell threads the real value at construction. Suspicion raises after `3 ×` this much
+* OBSERVED SILENCE — an elapsed-time derivative, sampling-rate-independent (not a tick count). */
+const DEFAULT_HEARTBEAT_INTERVAL_MS = 3e4;
+const SUSPICION_SILENCE_MULTIPLE = 3;
+/**
+* The per-isolate invalidation state. Tracks tri-state tag knowledge
+* fed by the bus, the highest contiguously-applied epoch, and a `suspect` flag
+* raised on any gap/reconnect that a resync must clear before warm trust resumes.
+*Tags absent from the map are `unknown` and fail closed (invariant 11).
+*/
+var Invalidation = class {
+	#registry;
+	#stateStore;
+	/** The bus, HELD as an address rather than a subscription. Construction wires; it does not
+	* dial. The first read that needs the channel subscribes (`#ensureSubscribed`), inside the request
+	* context that asked — which is the only context where a dial is permitted to happen at all. */
+	#bus;
+	/** Telemetry for the reader's own raw facts — currently `bus_dial_failed`. Optional: a cache
+	* built with no sink emits nothing, and the reader never depends on the emit for correctness. */
+	#emit;
+	/** This isolate's mirror-key scope, read from `registry.regId` at construction. It
+	* both scopes the keys this reader resyncs off (`mirrorKeys(#regId)`) AND is the value the
+	* pointer's echoed `regId` must equal — a mismatch reads a foreign keyspace and fails closed. */
+	#regId;
+	#subscription = null;
+	/** `close()` was called: no further subscribe may happen (a lazy dial must not resurrect a closed
+	* reader — the one way deferral could outlive its owner). */
+	#closed = false;
+	/** The live channel's state — see `ChannelState`. Starts at the honest answer: this reader
+	* has never heard a `hello`, and until it does it says so rather than resting on silence. */
+	#channel = NEVER_ESTABLISHED;
+	/** tag → applied watermark; absence ⇒ `unknown` (tri-state). */
+	#known = /* @__PURE__ */ new Map();
+	/** Highest contiguous epoch applied from bus frames / resync. Drives gap
+	* detection — must stay strictly contiguous. */
+	#appliedEpoch = 0;
+	/** Highest epoch this isolate has VERIFIED from any authority — the contiguous bus
+	* `#appliedEpoch` OR a live check's `throughEpoch`. This is the writer's
+	* applied registry epoch for bornEpoch minting: a fill after a verified
+	* live check must postdate what that check observed, so a legitimate refill on a
+	* behind isolate is not fenced by its own recorded watermark. */
+	#knownThroughEpoch = 0;
+	/** Raised on a bus gap or reset; forces resync before warm trust. While raised,
+	* every tag is treated as unknown at eventual reads — a possibly-gapped map is not the
+	* merely-degraded warm map Q4 lets an isolate keep serving on. */
+	#suspect = false;
+	/** The max head DECLARED over the currently-open live channel during THIS suspect episode
+	* — from a LOSS-revealing event only: `hello.head`, `gap.head`, or a NON-CONTIGUOUS
+	* frame's `toEpoch`. A contiguous frame never declares (it only reaches toward a named head).
+	* `null` until a head is declared this episode; a `reset` discards it (new episode), a `gap`
+	* RAISES it (≥ the frame it lost) — so a hidden purge behind a hole is accounted before
+	* convergence, never skipped (serve-dead — the shape). Convergence anchors
+	* to THIS, never to pointer freshness. */
+	#headThisEpisode = null;
+	/** The `flushedAt` of the pointer at the last observation that ADVANCED it. `null` until
+	* the first observation seeds the baseline. Compared DERIVATIVELY — "did it advance?" via
+	* EQUALITY/`>` — never as an absolute-freshness anchor ( : `flushedAt` may not clear
+	* suspicion nor date the map). */
+	#lastFlushedAt = null;
+	/** The `nowMs` of the previous observation — a MONOTONICITY guard so a stale/reordered tick
+	* (`nowMs ≤` this) is a true no-op, NOT an age anchor (it is never compared to `flushedAt`).
+	* `null` until the first observation. */
+	#lastObservationMs = null;
+	/** The `nowMs` at which the current unbroken SILENCE began — the last observation that seeded
+	* the baseline or saw `flushedAt` advance. `nowMs − this` is the observed silence; reaching
+	* `#suspicionAfterMs` RAISES suspicion (derivative, raise-only, never clears). `null` until the
+	* first observation. */
+	#silenceStartMs = null;
+	/** Raise suspicion once OBSERVED SILENCE reaches this — `3 × heartbeatIntervalMs`, fixed at
+	* construction. Elapsed silence is sampling-rate-INDEPENDENT: fast ticks cannot witness this much
+	* silence in less than this much time, so a false raise is structurally impossible. */
+	#suspicionAfterMs;
+	constructor(registry, stateStore, bus, heartbeatIntervalMs = DEFAULT_HEARTBEAT_INTERVAL_MS, emit) {
+		this.#registry = registry;
+		this.#emit = emit;
+		this.#suspicionAfterMs = SUSPICION_SILENCE_MULTIPLE * heartbeatIntervalMs;
+		this.#stateStore = stateStore;
+		this.#regId = registry.regId;
+		this.#bus = bus;
+	}
+	/**
+	* Subscribe to the invalidation bus if this reader has not already — THE LAZY DIAL,
+	* and the deferral the reachability rule requires of construction. Idempotent and synchronous, so any entry point
+	* may call it unconditionally; the dial itself is the transport's business and may complete long
+	* after this returns.
+	*
+	* CALL IT FROM EVERY PATH THAT IS "USE" — the read path (`validate`), the tick path (`resync` /
+	* `resyncViaSnapshot`), and the purge verbs, which are registry RPCs and therefore already inside
+	* a request context. NEVER from `explain`: a witness that dialed would be testimony rather than
+	* introspection, which is why `explainVerdict` is the one reader entry point that does not
+	* appear on that list.
+	*
+	* NOTHING IS MISSED BY SUBSCRIBING LATE. A purge published before this reader was listening is not
+	* lost: every establishment handshakes `reset` → `hello{head}`, which suspends warm trust and
+	* anchors a resync against the durable `__state`/`__delta` mirror. The live channel is an
+	* optimization over that mirror, never the sole path — so the cost of subscribing at first use is
+	* one cold resync, and the benefit is an isolate that can be built at module scope at all.
+	*
+	* The subscriber consumes a BusEvent union: a `reset` (transport (re)establishment) or a `gap`
+	* (dropped frame) marks the map suspect and forces a resync before warm trust resumes; a `frame`
+	* takes the contiguity path; a `lost` records the channel's own state.
+	*/
+	ensureSubscribed() {
+		if (this.#subscription !== null || this.#closed) return;
+		this.#subscription = this.#bus.subscribe((event) => {
+			this.#applyEvent(event);
+		});
+	}
+	get appliedEpoch() {
+		return this.#appliedEpoch;
+	}
+	/** Whether this isolate currently DISTRUSTS its warm map — read-only. A read
+	* arriving while suspect fails closed (the gate); the shell reads it to know whether
+	* the ladder still has work. Raised by a bus gap/reset OR the derivative heartbeat miss;
+	* cleared ONLY by `#tryConverge` reaching a live-channel head (never by pointer freshness). */
+	get suspect() {
+		return this.#suspect;
+	}
+	/** The live channel's state — read-only exposition of state this reader already tracks for
+	* its own use, never new bookkeeping added for the witness. */
+	get channel() {
+		return this.#channel;
+	}
+	close() {
+		this.#closed = true;
+		this.#subscription?.close();
+		this.#subscription = null;
+	}
+	/** Advance the contiguous applied epoch (and the verified high-water) to `toEpoch`. */
+	#advanceApplied(toEpoch) {
+		this.#appliedEpoch = toEpoch;
+		this.#knownThroughEpoch = Math.max(this.#knownThroughEpoch, toEpoch);
+	}
+	/**
+	* Dispatch one bus event. Convergence anchors to a head DECLARED this episode,
+	*from exactly the LOSS-REVEALING events: a `hello` (the channel head), a `gap`
+	* (its `head`, ≥ the frame it lost), or a NON-CONTIGUOUS frame (its `toEpoch`, the hole
+	* it proves). A CONTIGUOUS frame does NOT declare — it only reaches toward a head already named.
+	* A `reset` discards the anchor (a new episode; the following `hello` re-declares). The kernel,
+	* not the bus, owns contiguity validation.
+	*/
+	#applyEvent(event) {
+		switch (event.kind) {
+			case "frame":
+				this.#applyFrame(event.frame);
+				return;
+			case "hello":
+				this.#channel = "established";
+				this.#headThisEpisode = Math.max(this.#headThisEpisode ?? 0, event.head);
+				this.#tryConverge();
+				return;
+			case "lost": {
+				const healthyClose = this.#channel === "established";
+				this.#channel = this.#channel === NEVER_ESTABLISHED ? NEVER_ESTABLISHED : "lost";
+				if (!healthyClose) this.#emit?.({ type: TELEMETRY_EVENTS.bus_dial_failed });
+				return;
+			}
+			case "gap":
+				this.#suspect = true;
+				this.#headThisEpisode = Math.max(this.#headThisEpisode ?? 0, event.head);
+				return;
+			case "reset":
+				this.#suspect = true;
+				this.#headThisEpisode = null;
+				return;
+			default: return event;
+		}
+	}
+	/** Apply a bus frame if contiguous; otherwise raise suspicion. */
+	#applyFrame(frame) {
+		if (frame.fromEpoch !== this.#appliedEpoch) {
+			this.#suspect = true;
+			this.#headThisEpisode = Math.max(this.#headThisEpisode ?? 0, frame.toEpoch);
+			return;
+		}
+		applyChanges(this.#known, frame);
+		this.#advanceApplied(frame.toEpoch);
+		this.#tryConverge();
+	}
+	/**
+	* Clear suspicion iff a head was DECLARED over the live channel this episode (hello/frame)
+	* AND the applied epoch has reached it. `#appliedEpoch` advances only by contiguous
+	* application, so `applied >= head` already encodes hole-free reach (β) — no separate holes
+	* check. Pointer freshness never arbitrates clearing: a heartbeat refreshes the pointer's
+	* freshness field without minting epochs, so freshness motion is not evidence the reader has
+	* caught up; only a live-channel head declaration anchors convergence. Bus-down /
+	* poll-only declares no head ⇒ sticky suspect (posture, priced).
+	*/
+	#tryConverge() {
+		if (this.#suspect && this.#headThisEpisode !== null && this.#appliedEpoch >= this.#headThisEpisode) this.#suspect = false;
+	}
+	/**
+	* Cold/resync path — the bounded single DELTA pass. Read the `__state`
+	* pointer from L2 and replay the `(applied, lastBatch]` delta batches — durably write-once
+	* in L2 even when the bus frame was dropped — applying the contiguous prefix (β), which
+	* advances `#appliedEpoch`. A missing pointer or a hole leaves affected knowledge `unknown`
+	* (fail closed). Resync does NOT clear suspicion off pointer freshness: a heartbeat refreshes the
+	* freshness field without minting epochs, so freshness motion is not evidence of catch-up.
+	*It only APPLIES the durable prefix; clearing is `#tryConverge`'s job, and fires iff
+	* a head was DECLARED over the live channel this episode (hello/frame) AND this replay carried
+	* the applied epoch up to it.
+	*
+	* SURFACES A STATUS (2b-2-a): the walk's hole is no longer discarded — it is returned so the
+	* SHELL (2b-2-b) can schedule the retry ladder off a pure decision. `resync` NEVER sleeps; the
+	* escalation across attempts is driven by the caller's `policy.deltasExhausted`, not by time.
+	*
+	* THE RETRY LADDER NEVER BLOCKS A READ: `validate()`'s awaited resync stays THIS bounded fast
+	* pass; a read arriving during `transient-miss` classifies `unknown` and takes the posture
+	* NOW — the ladder heals the future, not the present. Fail-closed means what it says. (So
+	* `validate` calls `resync()` with the default policy and ignores the status; it does not wait
+	* on retries, and a `transient-miss`/`needs-snapshot`/`terminal-gap` read fails closed at once
+	* via the gate.)
+	*/
+	async resync(policy) {
+		this.ensureSubscribed();
+		const deltasExhausted = policy?.deltasExhausted ?? false;
+		const mirror = await this.#readMirrorPointer();
+		if (!mirror) {
+			this.#tryConverge();
+			return transientMiss(0);
+		}
+		const hole = await this.#replayBatches(mirror.store, mirror.keys, 1, mirror.pointer.lastBatch);
+		this.#tryConverge();
+		if (hole === null) return "converged";
+		return deltasExhausted ? "needs-snapshot" : transientMiss(hole);
+	}
+	/**
+	* The SNAPSHOT bridge — the escalation the shell drives after `resync` returns
+	* `needs-snapshot`. Load ONLY the pointer-blessed snapshot `__snap:<pointer.snapBatch>` (a
+	* from-0 `BusFrame`, `fromEpoch:0`, parsed by the SAME `readFrame`), apply it as an ABSOLUTE
+	* base (`#appliedEpoch` ← `snap.toEpoch` when ahead — bridging a hole in the now-GC-eligible
+	* region below `snapBatch`), then replay the tail `(snapBatch, lastBatch]`. Never fetches an
+	* UNBLESSED snap nor a delta past `lastBatch` (the over-fetch discipline the contract pins).
+	*
+	* A lagging `snapBatch` is FIRST-CLASS NORMAL (1c): `snapBatch` may trail `lastBatch`
+	* arbitrarily — the arithmetic on `(snapBatch, lastBatch]` is correct, no warning, no anomaly.
+	*
+	* BLESSED-BUT-MISSING SNAP: if `__snap:<snapBatch>` is itself absent, give it ONE brief retry
+	* (`transient-miss` — it may be lagging); once the caller's snapshot-budget is spent
+	* (`snapshotExhausted`), rule permanently — a FULL delta replay from the floor if the chain
+	* `(0, lastBatch]` is intact (⇒ `converged`), else `terminal-gap`. No spin, no serve-through.
+	*/
+	async resyncViaSnapshot(policy) {
+		this.ensureSubscribed();
+		const snapshotExhausted = policy?.snapshotExhausted ?? false;
+		const mirror = await this.#readMirrorPointer();
+		if (!mirror) {
+			this.#tryConverge();
+			return transientMiss(0);
+		}
+		const { store, keys, pointer } = mirror;
+		const snapRaw = await store.get(keys.snapKey(pointer.snapBatch), "snap");
+		const snap = snapRaw ? readFrame(snapRaw.value) : void 0;
+		if (!snap) {
+			if (!snapshotExhausted) {
+				this.#tryConverge();
+				return transientMiss(pointer.snapBatch);
+			}
+			const holeNoSnap = await this.#replayBatches(store, keys, 1, pointer.lastBatch);
+			this.#tryConverge();
+			return holeNoSnap === null ? "converged" : "terminal-gap";
+		}
+		this.#applySnapshotBase(snap);
+		const tailHole = await this.#replayBatches(store, keys, pointer.snapBatch + 1, pointer.lastBatch);
+		this.#tryConverge();
+		if (tailHole === null) return "converged";
+		return transientMiss(tailHole);
+	}
+	/**
+	* Read the `__state` pointer through the registry-scoped keys, returning the scoped
+	* `store`/`keys` alongside it, or `undefined` when the pointer is absent/malformed OR echoes a
+	* foreign `regId` (a scheme/prefix divergence or another registry's pointer — fail closed).
+	*/
+	async #readMirrorPointer() {
+		const store = this.#stateStore;
+		const keys = mirrorKeys(this.#regId);
+		const raw = await store.get(keys.stateKey, "pointer");
+		const pointer = raw ? readPointer(raw.value) : void 0;
+		if (!pointer || pointer.regId !== this.#regId) return;
+		return {
+			keys,
+			pointer,
+			store
+		};
+	}
+	/**
+	* Replay batches `fromSeq..lastBatch` (XRANGE discipline), applying each whose
+	* `fromEpoch` is contiguous with the applied epoch. Returns the seq of the FIRST hole
+	* (a missing/garbled/non-contiguous forward batch — fail closed), or `null` when the walk
+	* reached `lastBatch` hole-free. `fromSeq` is `1` for a from-floor `(0, lastBatch]` replay and
+	* `snapBatch + 1` for a snapshot-bridged tail `(snapBatch, lastBatch]` — so GC'd batches below
+	* a snapshot floor are never miscounted as holes. Reads ONLY `deltaKey(fromSeq..lastBatch)` —
+	* never a seq past the pointer — through the SAME `keys` the pointer was read with (
+	* over-fetch discipline).
+	*/
+	async #replayBatches(store, keys, fromSeq, lastBatch) {
+		let firstHole = null;
+		for (let seq = fromSeq; seq <= lastBatch; seq++) {
+			const batchRaw = await store.get(keys.deltaKey(seq), "delta");
+			const frame = batchRaw ? readFrame(batchRaw.value) : void 0;
+			const applied = frame ? this.#applyIfContiguous(frame) : false;
+			if (!(frame && applied) && firstHole === null) firstHole = seq;
+		}
+		return firstHole;
+	}
+	/** Apply a batch frame iff it advances the applied epoch contiguously. */
+	#applyIfContiguous(frame) {
+		if (frame.toEpoch <= this.#appliedEpoch) return true;
+		if (frame.fromEpoch !== this.#appliedEpoch) return false;
+		applyChanges(this.#known, frame);
+		this.#advanceApplied(frame.toEpoch);
+		return true;
+	}
+	/**
+	* Apply a from-0 snapshot frame as an ABSOLUTE base: merge its watermarks (max-on-write,
+	* never regressing a higher already-known value) and JUMP the applied epoch to `snap.toEpoch`
+	* when the snapshot is AHEAD — a complete `(0, snap.toEpoch]` checkpoint carries its own
+	* contiguity from the floor, so no `fromEpoch === applied` gate applies. A snapshot BEHIND the
+	* applied epoch (a lagging `snapBatch` — first-class normal) adds nothing and never regresses.
+	*/
+	#applySnapshotBase(snap) {
+		if (snap.toEpoch <= this.#appliedEpoch) return;
+		applyChanges(this.#known, snap);
+		this.#advanceApplied(snap.toEpoch);
+	}
+	/**
+	* derivative suspicion RAISING — a PURE state update fed one pointer
+	* observation. A heartbeat refreshes the pointer's freshness field without minting epochs, so
+	* freshness MOTION is not evidence the reader has caught up; only a live-channel head declaration
+	* anchors convergence. This monitor uses freshness the OTHER way — to RAISE: it tracks OBSERVED
+	* SILENCE (how long `flushedAt` has failed to advance) and raises `#suspect` once that silence
+	* reaches `#suspicionAfterMs`. DERIVATIVE-ONLY, RAISE-ONLY: `flushedAt` never clears suspicion nor
+	* anchors absolute freshness — only `>`/equality ACROSS observations, only to RAISE.
+	* `nowMs` is compared ONLY to our own prior watch-times (`#lastObservationMs`, `#silenceStartMs`),
+	* NEVER to `flushedAt`, so no absolute-age anchor sneaks in. Measuring ELAPSED silence (not
+	* counting non-advancing ticks) makes the raise SAMPLING-RATE-INDEPENDENT: fast ticks cannot
+	* witness `#suspicionAfterMs` of silence in less time, and a slow-but-live writer resets the
+	* window. The shell feeds it observations (2b-2-b); here explicit test ticks.
+	*/
+	notePointerObservation(pointer, nowMs) {
+		if (this.#lastObservationMs !== null && nowMs <= this.#lastObservationMs) return;
+		this.#lastObservationMs = nowMs;
+		if (this.#lastFlushedAt === null || this.#silenceStartMs === null) {
+			this.#lastFlushedAt = pointer.flushedAt;
+			this.#silenceStartMs = nowMs;
+			return;
+		}
+		if (pointer.flushedAt > this.#lastFlushedAt) {
+			this.#lastFlushedAt = pointer.flushedAt;
+			this.#silenceStartMs = nowMs;
+			return;
+		}
+		if (nowMs - this.#silenceStartMs >= this.#suspicionAfterMs) this.#suspect = true;
+	}
+	/**
+	* The poll DECISION — a PURE, deterministic predicate: has at least `thresholdMs`
+	* elapsed since the last poll? The base cadence is maxSyncLag (60s) and the ±20% jitter is the
+	* SHELL's rng job (2b-2-b) — both enter as the caller-computed `thresholdMs`, so no ambient
+	* time/rng lives here. The poll DRIVER (the timer that calls this) is 2b-2-b.
+	*/
+	pollDue(nowMs, lastPollMs, thresholdMs) {
+		return nowMs - lastPollMs >= thresholdMs;
+	}
+	/**
+	* The `bornEpoch` to stamp into a fresh envelope at fill start, read
+	* SYNCHRONOUSLY from LOCAL VERIFIED knowledge — the highest epoch this isolate has
+	* observed from any authority (contiguous bus applies OR a recorded live check),
+	* never a fresh live read. So the default read path keeps the zero-round-trip cost
+	* model, while a fill that follows a verified live check postdates what that check
+	* observed — a legitimate refill on a behind isolate is not fenced by its own
+	* recorded watermark. A lagging high-water can only UNDER-state bornEpoch ⇒
+	* over-invalidation ⇒ the safe direction. The caller snapshots
+	* this EARLY as the fence-critical floor (a concurrent bus purge landing after the
+	* snapshot cannot lift it, so INV-9/12 hold) and only raises the fill's bornEpoch by
+	* the epoch its OWN reads verified (via `validate`'s `checkedThrough`), never by a
+	* concurrent frame — see `runGetOrSet`.
+	*/
+	localBornEpoch() {
+		return this.#knownThroughEpoch;
+	}
+	/**
+	* The verdict `explain` reports — a PURE read of CURRENT local knowledge: classify
+	* the envelope against what this isolate knows NOW, with NO live check, NO resync, and NO
+	* recording. It is exposition, not testimony: it adds no tracked state and mutates nothing (the
+	* introspection-not-testimony line). A suspect map fails closed to `unknown` (the posture
+	* an eventual read would take), and `unknown` stays `unknown`. The soft/hard watermarks are the
+	* evidence the bornEpoch was weighed against — the purge epochs behind a `stale`/`dead` verdict
+	* (`0` when nothing is known / fail-closed).
+	*/
+	explainVerdict(envelope) {
+		const knowledge = this.#localKnowledge(envelope.tags);
+		let softEpoch = 0;
+		let hardEpoch = 0;
+		for (const k of knowledge) if (k.known) {
+			softEpoch = Math.max(softEpoch, k.softEpoch);
+			hardEpoch = Math.max(hardEpoch, k.hardEpoch);
+		}
+		const validity = this.#suspect ? "unknown" : classify(envelope.bornEpoch, knowledge);
+		return {
+			hardEpoch,
+			softEpoch,
+			validity
+		};
+	}
+	/**
+	* Validate an envelope against this isolate's knowledge (table). `strong`
+	* (or an unknown tag under `registry-check`) consults a live registry read; a
+	* plain `eventual` read uses only local bus-fed knowledge and fails closed on any
+	* unknown/suspect tag (invariant 11). Never serves a hard-purged value.
+	*
+	* REACHABILITY IS SPLIT BY CHANNEL. This method is the REGISTRY-RPC half: a failure here is
+	* a strong read's `RegistryUnavailableError` or, on the eventual path, a `'miss'`.
+	* The BUS half is not represented here at all — a bus that is down or never came up is never
+	* grounds for a throw, because the eventual path's whole design is to be correct without it.
+	*/
+	async validate(envelope, consistency, resolution, onUnavailable) {
+		const { tags, bornEpoch } = envelope;
+		this.ensureSubscribed();
+		if (consistency === "strong") try {
+			return await this.#strongLiveCheck(tags, bornEpoch);
+		} catch (error) {
+			if (onUnavailable !== "eventual") throw new RegistryUnavailableError(`strong read could not reach the registry — ${String(error)}`);
+			this.#emit?.({
+				reason: STRONG_DEGRADED_REGISTRY_UNREACHABLE,
+				type: TELEMETRY_EVENTS.strong_degraded
+			});
+		}
+		if (this.#suspect) await this.resync();
+		const localVerdict = this.#suspect ? "unknown" : classify(bornEpoch, this.#localKnowledge(tags));
+		if (localVerdict !== "unknown") return {
+			checkedThrough: 0,
+			validity: localVerdict
+		};
+		if (typeof resolution !== "string") throw new UnknownTagError(envelope.key, this.#unknownUserTags(tags), resolution.armedBy);
+		if (resolution !== "registry-check") return {
+			checkedThrough: 0,
+			validity: "unknown"
+		};
+		let checked;
+		try {
+			checked = await this.#registry.check(tags);
+		} catch {
+			return {
+				checkedThrough: 0,
+				validity: "unknown"
+			};
+		}
+		this.#recordChecked(tags, checked);
+		return {
+			checkedThrough: throughEpochOf(checked),
+			validity: classify(bornEpoch, checked)
+		};
+	}
+	/**
+	* The strong-read live check: ONE live, un-memoized registry read over
+	* `tags`, memoized into local knowledge (`#recordChecked`), classified against
+	* `bornEpoch` via the table. The single engine of both the strong READ arm of
+	* `validate` and the pre-fetch strong-miss check (`liveCheckForFill`) —
+	* local knowledge is never consulted here; the primary read is the authority.
+	*/
+	async #strongLiveCheck(tags, bornEpoch) {
+		const knowledge = await this.#registry.check(tags);
+		this.#recordChecked(tags, knowledge);
+		return {
+			checkedThrough: throughEpochOf(knowledge),
+			validity: classify(bornEpoch, knowledge)
+		};
+	}
+	/**
+	* Pre-fetch strong-miss live check: the SAME live un-memoized
+	* registry read `#strongLiveCheck` runs, executed BEFORE the factory on a strong fill so
+	* the fill's bornEpoch is minted from now-current knowledge — an understatement, never an
+	* overstatement, of recency (the safe direction). Records the reading into `#known` (
+	* memoization), so a later eventual read of the tag fails closed with no second round-trip.
+	* Returns the verified high-water; the caller raises the fill's bornEpoch to it.
+	*/
+	async liveCheckForFill(tags, onUnavailable) {
+		try {
+			const { checkedThrough } = await this.#strongLiveCheck(tags, 0);
+			return checkedThrough;
+		} catch (error) {
+			if (onUnavailable !== "eventual") throw new RegistryUnavailableError(`strong fill could not reach the registry to mint its bornEpoch — ${String(error)}`);
+			this.#emit?.({
+				reason: STRONG_DEGRADED_REGISTRY_UNREACHABLE,
+				type: TELEMETRY_EVENTS.strong_degraded
+			});
+			return 0;
+		}
+	}
+	/** Merge a verified live-check result into local knowledge. Max-on-write, so
+	* a concurrently-applied newer bus frame is never regressed. The check's
+	* `throughEpoch` advances the verified high-water (bornEpoch source) so a subsequent
+	* refill postdates what this check observed. */
+	#recordChecked(tags, knowledge) {
+		for (const [i, tag] of tags.entries()) {
+			const k = knowledge[i];
+			if (k === void 0 || !k.known) continue;
+			const w = this.#known.get(tag) ?? {
+				hardEpoch: 0,
+				softEpoch: 0
+			};
+			w.softEpoch = Math.max(w.softEpoch, k.softEpoch);
+			w.hardEpoch = Math.max(w.hardEpoch, k.hardEpoch);
+			this.#known.set(tag, w);
+			this.#knownThroughEpoch = Math.max(this.#knownThroughEpoch, k.throughEpoch);
+		}
+	}
+	/**
+	* The write-back fence, evaluated against LOCAL bus-applied knowledge: any tag
+	* `hardEpoch > bornEpoch` in the isolate's contiguously-applied state ⇒ the candidate
+	* is fenced (a hard purge landed DURING the fill and was delivered here). Returns
+	* `true` when the write-back may proceed. A soft purge lands already-stale but still
+	* stores; only DEAD fences.
+	*
+	* DESIGN (per the INV-12 erratum): the write-back guard is realized as a LOCAL
+	* fence here plus read-time fail-closed resolution — not a live registry read on the
+	* write path. The local fence catches a purge that landed AND delivered locally DURING the
+	* fill (tag KNOWN-dead locally ⇒ INV-9/12); it lets a cold/dropped-frame isolate STORE a value
+	* whose tag is locally unknown (origin is truth after a purge — the legitimate
+	* refill case). A born-dead value that slips past this fence is stored but INERT: its own
+	* SUBSEQUENT eventual reads fail closed on the unknown tag and live-check — that read-time
+	* check is where the GOAL (never serve a value born against a durably-accepted purge) is
+	* enforced for THAT path. A strong fill's OWN serve is anchored earlier, at INITIATION: the
+	* pre-factory check minted its `bornEpoch` at the global epoch, so it already dominates
+	* every purge accepted before initiation — no read-time check re-verifies the fill
+	* that produced it.
+	*/
+	fenceWriteBack(tags, bornEpoch) {
+		return classify(bornEpoch, this.#localKnowledge(tags)) !== "dead";
+	}
+	/** Local tri-state knowledge for these tags (absent ⇒ unknown). */
+	/**
+	* The USER tags this read could not establish — what `UnknownTagError` carries.
+	*
+	* Under suspicion EVERY tag is unknown (the gate treats a map with a hole as knowing
+	* nothing), so the whole user set is the honest answer there. Otherwise it is exactly the tags the
+	* map has no watermark for. Reserved tags are dropped either way: `__k:`/`__ns:` are the kernel's
+	* own bookkeeping, they are unknown for the same reason the user's tags are, and a caller cannot
+	* do anything with them — the same reason they never reach an L3 header.
+	*/
+	#unknownUserTags(tags) {
+		const knowledge = this.#localKnowledge(tags);
+		return tags.filter((tag, index) => !isReservedTag(tag) && (this.#suspect || knowledge[index]?.known !== true));
+	}
+	#localKnowledge(tags) {
+		return tags.map((tag) => {
+			const w = this.#known.get(tag);
+			if (!w) return { known: false };
+			return {
+				hardEpoch: w.hardEpoch,
+				known: true,
+				softEpoch: w.softEpoch,
+				throughEpoch: this.#appliedEpoch
+			};
+		});
+	}
+};
+//#endregion
+//#region src/drivers.ts
+/**
+* Structural type-guard for `StoreWriteError`. Purely shape-based — it NEVER
+* uses `instanceof`, so a harness fake and a real driver are recognized by the SAME
+* check without a shared class. Total and safe on arbitrary `unknown`: rejects
+* non-objects/null, requires `code` to be exactly one of the three literals and
+* `retryable` to be a boolean.
+*/
+function isStoreWriteError(e) {
+	if (typeof e !== "object" || e === null) return false;
+	const code = "code" in e ? e.code : void 0;
+	const retryable = "retryable" in e ? e.retryable : void 0;
+	return (code === "throttled" || code === "too_large" || code === "unavailable") && typeof retryable === "boolean";
+}
+/**
+* Structural type-guard for `StoreReadError` — shape-based, never `instanceof`,
+* exactly as `isStoreWriteError` is. Total and safe on arbitrary `unknown`. A driver error
+* that carries a read-suppressible `code` satisfies this whatever class raised it, which is
+* the point: the own `unavailable` shape is recognized without a shared identity.
+*/
+function isStoreReadError(e) {
+	if (typeof e !== "object" || e === null) return false;
+	const code = "code" in e ? e.code : void 0;
+	const retryable = "retryable" in e ? e.retryable : void 0;
+	return (code === "throttled" || code === "unavailable") && typeof retryable === "boolean";
+}
+/**
+* Rejection raised by `memory().set` when a single value's UTF-8 byte length exceeds the
+* store's total `maxBytes` budget — a value larger than the whole budget can never fit, so
+* it is REJECTED, never truncated. Satisfies the structural `StoreWriteError`
+* contract (`too_large`, non-retryable) WITHOUT sharing a class with the kernel: consumers
+* discriminate via `isStoreWriteError` (structural), never `instanceof`. The kernel-side
+* twin of the harness `OversizeValueError`; internal, so it needs no export.
+*/
+var MemoryOversizeError = class extends Error {
+	code = "too_large";
+	retryable = false;
+	constructor(key, sizeBytes, maxBytes) {
+		super(`value too large: ${key} (${sizeBytes} > ${maxBytes} bytes)`);
+		this.name = "MemoryOversizeError";
+	}
+};
+/**
+* Rejection raised by `memory().set` when a write carries `expirationTtl` but the store was built
+* with NO injected clock — the residency cannot be honored without a `now` source, so the write
+* FAILS LOUD rather than silently drop the TTL. Unlike `MemoryOversizeError` this is a
+* MISCONFIGURATION, not a `StoreWriteError`: it must NOT satisfy the structural write-failure
+* contract the kernel absorbs — a residency the store can never honor is a programmer error,
+* surfaced typed so a caller can `instanceof`-catch it, never quietly ignored. Internal, mirroring
+* `MemoryOversizeError` (neither is re-exported from `index.ts`).
+*/
+var MemoryConfigError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "MemoryConfigError";
+	}
+};
+/** is this a PRIVATE (`usr:`-scoped) L1 entry? Read off the `scope`
+* metadata LITERAL the kernel writes with every L1 set (`pub` / `usr:<h>` / `ten:<h>`) — the
+* `usr:` PREFIX only, never the hash. A `usr:` entry is per-principal, so its eviction is disclosed;
+* detection touches nothing identifying, and a non-canonical store (no `scope` metadata) never
+* matches. */
+function isPrivateEntry(entry) {
+	const scope = entry.metadata?.scope;
+	return typeof scope === "string" && scope.startsWith("usr:");
+}
+/**
+* In-process L1 store — isolate-local, bounded by `maxEntries` / `maxBytes` with LRU
+* eviction on either bound (an insertion-ordered `Map`, re-inserted on touch, so recency —
+* not mere insertion order — picks the victim). Each `memory()` owns a PER-INSTANCE byte
+* accounter (Σ value UTF-8 byte lengths).
+*
+* an optional `telemetry` sink receives a `private_evicted` event when a
+* PRIVATE (`usr:`-scoped) entry is evicted from the LRU under memory pressure — reason class +
+* counts + bytes ONLY, so an operator sees L1 pressure on private data without the event ever
+* naming WHAT was evicted (payload discipline). The `usr:`-priority-protected LRU (evict
+* private entries LAST) is a spec MAY and stays UNBUILT: this discloses whatever the current LRU
+* policy evicts, it does not change the victim. The cross-instance shared/joint reserve (warn
+* on Σ`maxBytes` overflow across isolate L1s) is a separate advisory extra, still DEFERRED.
+*/
+function memory(options) {
+	const clock = options?.clock;
+	const maxEntries = options?.maxEntries;
+	const maxBytes = options?.maxBytes;
+	const telemetry = options?.telemetry;
+	const onSinkError = options?.onSinkError;
+	const encoder = new TextEncoder();
+	const entries = /* @__PURE__ */ new Map();
+	let totalBytes = 0;
+	const drop = (key, entry) => {
+		entries.delete(key);
+		totalBytes -= entry.bytes;
+	};
+	const overBounds = () => maxEntries !== void 0 && entries.size > maxEntries || maxBytes !== void 0 && totalBytes > maxBytes;
+	return {
+		delete: async (key) => {
+			const entry = entries.get(key);
+			if (entry !== void 0) drop(key, entry);
+		},
+		get: async (key) => {
+			const entry = entries.get(key);
+			const expired = entry !== void 0 && clock !== void 0 && entry.expireAtMs !== void 0 && clock.now() >= entry.expireAtMs;
+			if (entry === void 0 || expired) {
+				if (entry !== void 0) drop(key, entry);
+				return;
+			}
+			entries.delete(key);
+			entries.set(key, entry);
+			return entry.metadata === void 0 ? { value: entry.value } : {
+				metadata: entry.metadata,
+				value: entry.value
+			};
+		},
+		set: async (key, value, writeOptions) => {
+			const bytes = encoder.encode(value).length;
+			if (maxBytes !== void 0 && bytes > maxBytes) throw new MemoryOversizeError(key, bytes, maxBytes);
+			let expireAtMs;
+			if (writeOptions?.expirationTtl !== void 0) {
+				if (clock === void 0) throw new MemoryConfigError("memory(): expirationTtl requires an injected clock — construct memory({ clock, … }) to honor residency (§8)");
+				expireAtMs = clock.now() + writeOptions.expirationTtl * 1e3;
+			}
+			const existing = entries.get(key);
+			if (existing !== void 0) drop(key, existing);
+			entries.set(key, {
+				bytes,
+				value,
+				...writeOptions?.metadata === void 0 ? {} : { metadata: writeOptions.metadata },
+				...expireAtMs === void 0 ? {} : { expireAtMs }
+			});
+			totalBytes += bytes;
+			while (overBounds()) {
+				const lruKey = entries.keys().next().value;
+				if (lruKey === void 0) break;
+				const lru = entries.get(lruKey);
+				if (lru !== void 0) {
+					drop(lruKey, lru);
+					if (telemetry !== void 0 && isPrivateEntry(lru)) safeEmit(telemetry, {
+						bytes: lru.bytes,
+						count: 1,
+						type: TELEMETRY_EVENTS.private_evicted
+					}, onSinkError);
+				}
+			}
+		}
+	};
+}
+//#endregion
+//#region src/duration.ts
+/**
+* Milliseconds per unit — the ONE `Duration`→ms grammar source. Shared with
+* `cache.ts`'s coarse `durationMs` parser (which imports this const) so the overflow
+* check here and the retention/heartbeat parse there agree on the factor table byte-for-byte.
+* `m` = minutes.
+*/
+const DURATION_UNIT_MS = {
+	d: 864e5,
+	h: 36e5,
+	m: 6e4,
+	ms: 1,
+	s: 1e3
+};
+/**
+* Build a `Duration` from computed values — the trust point for
+* programmatically-derived durations (as opposed to a `'5m'` string literal the type
+* system already constrains). Rejects a non-positive or non-finite `value`, and — and,
+* the case a naive impl passes — a `value × unitFactor` product that is not a finite,
+* positive, SAFE integer once multiplied out. So `duration(Number.MAX_SAFE_INTEGER, 'd')`
+* is REJECTED even though the input is a safe integer: the overflow lives in the product.
+* Throws `InvalidDurationError` on any violation; never coerces.
+*/
+function duration(value, unit) {
+	if (!Number.isFinite(value) || value <= 0) throw new InvalidDurationError(value, unit, "value must be a finite number greater than 0 (§2.1)");
+	const ms = value * DURATION_UNIT_MS[unit];
+	if (!Number.isSafeInteger(ms) || ms <= 0) throw new InvalidDurationError(value, unit, "computed milliseconds must be a finite, positive, safe integer (F31)");
+	return `${value}${unit}`;
+}
+//#endregion
+//#region src/http.ts
+/** The default retriable HTTP status set (Cloudflare 52x joins it). */
+const RETRIABLE_STATUSES = /* @__PURE__ */ new Set([
+	408,
+	425,
+	429,
+	500,
+	502,
+	503,
+	504,
+	520,
+	521,
+	522,
+	523,
+	524,
+	525,
+	526,
+	527,
+	530
+]);
+/** Wrap a non-ok `Response` into a typed `HttpError`. */
+function httpError(response) {
+	return new HttpError(response);
+}
+/**
+* The default `staleIfError` predicate — retriable: the default
+* retriable set, network errors, and cache-originated timeouts. `404/410/403` are
+* facts, never masked (never retriable) — a caller-abort `CacheTimeoutError` with
+* `source:'caller'` is likewise not evidence of origin health.
+*/
+function isRetriableHttp(err) {
+	if (err instanceof HttpError) return RETRIABLE_STATUSES.has(err.status);
+	if (err instanceof CacheTimeoutError) return err.source === "cache";
+	return err instanceof TypeError;
+}
+//#endregion
+//#region src/replication-poller.ts
+const DEFAULT_POLL_BASE_MS = 6e4;
+const DEFAULT_FIRST_LADDER_DELAY_MS = 1e3;
+const DEFAULT_LATER_LADDER_DELAY_MS = 5e3;
+const DEFAULT_JITTER_FRACTION = .2;
+/** Poll-failure backoff ceiling (knob): a warm baseline poll that does NOT converge doubles
+* the cadence (×2) up to this cap — 300s — and the doubled interval is jittered like any other, so a
+* fleet whose L2 is failing degrades to one attempt per ~5 minutes per isolate instead of hammering
+* a sick store every 60s. The cap is on the BASE interval; the ±jitter rides on top (a jittered
+* 300s is 240–360s), because de-synchronizing the fleet matters most exactly when the store is sick. */
+const MAX_POLL_BACKOFF_MS = 3e5;
+/** Backoff multiplier per consecutive failed baseline poll (×2). */
+const POLL_BACKOFF_FACTOR = 2;
+/** The rung at which the delta budget is spent and the pass may escalate to the snapshot bridge. */
+const ESCALATE_AT_ATTEMPT = 3;
+/** The rung at which the snapshot budget is ALSO spent — the reader makes the permanent ruling
+* (full replay if the chain is intact ⇒ converged, else terminal-gap). Below it, a lagging snap
+* gets one brief retry. */
+const SNAPSHOT_FINAL_ATTEMPT = 4;
+/** Parse the `__state` pointer bytes the reader resyncs off into the wire shape the
+* monitor consumes. Malformed / absent ⇒ `undefined` (the observation is simply skipped — a shell
+* read that cannot see the pointer never fabricates liveness). Numbers-only fields; missing
+* optionals default the same way the kernel reader does. */
+function readStatePointer(raw) {
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch {
+		return;
+	}
+	if (typeof parsed !== "object" || parsed === null) return;
+	const o = parsed;
+	if (typeof o.epoch !== "number" || typeof o.lastBatch !== "number" || typeof o.regId !== "string") return;
+	return {
+		epoch: o.epoch,
+		flushedAt: typeof o.flushedAt === "number" ? o.flushedAt : 0,
+		lastBatch: o.lastBatch,
+		regId: o.regId,
+		snapBatch: typeof o.snapBatch === "number" ? o.snapBatch : 0
+	};
+}
+/**
+* The tick-driven replication poll driver. Each `onPollTick(nowMs)`:
+*   1. reads the `__state` pointer and feeds the derivative liveness monitor
+*      (`notePointerObservation`) — raise-only, every tick, sampling-rate-independent;
+*   2. while the reader is SUSPECT, runs the retry ladder when an attempt is DUE:
+* attempt 1 → `resync()` (delta); +~1s → attempt 2 → `resync()` (delta); +~5s →
+*        attempt 3 → `resync({deltasExhausted})` and, on `needs-snapshot`, `resyncViaSnapshot()`
+*        (snapshot-permitted). `converged` clears the reader (and backs the ladder off to the
+*        baseline cadence when suspicion persists awaiting a live-channel head — never a spin);
+*        `terminal-gap` STOPS the ladder permanently (fail-closed, no spin);
+*   3. while WARM, runs the baseline liveness poll on the maxSyncLag cadence (60s ±20%), gated by
+* the kernel's pure `pollDue`, and BACKS OFF on failure: a non-converged poll doubles the
+*      interval (×2, cap 300s, still jittered); a converged one resets it to the base.
+*
+* Pure + tick-driven: no wall clock, no ambient timers, no sleeps — `nowMs` and the injected rng
+* are the only sources of time/randomness.
+*
+* RE-ENTRANCY-SAFE BY CONTRACT. `onPollTick` is NOT required to be awaited before the
+* next one is fired, and under the request-piggyback driver it routinely is not — a burst of
+* requests hands one isolate several ticks while a step's store I/O is still in flight. Two
+* properties make that safe HERE, at the root, rather than in each driver: (i) every due-decision
+* and the state writes it authorizes happen in ONE synchronous block — no `await` separates a
+* due-check from its commit, so no tick ever acts on a schedule another tick has already consumed;
+* (ii) at most ONE ladder step is in flight, and a tick arriving mid-step declines rather than
+* queues. The `__state` observation is exempt from both — the +25 vigil runs on EVERY tick.
+*/
+var ReplicationPoller = class {
+	#reader;
+	#store;
+	#keys;
+	#rng;
+	#pollBaseMs;
+	#firstLadderDelayMs;
+	#laterLadderDelayMs;
+	#jitterFraction;
+	/** Active hole-chasing ladder, or `null` when warm (no hole to chase). */
+	#ladder = null;
+	/** A terminal-gap verdict indexed to the pointer that produced it: the LADDER stays stopped
+	* (fail-closed, no spin) while this chain cannot complete. Permanence attaches to the CHAIN, not
+	* the vigil — the baseline observation never stops (below). Cleared on a fresh suspect episode OR
+	* when a durable `snapBatch` advance past `#terminalSnapBatch` bridges the hole. */
+	#terminal = false;
+	/** The pointer `snapBatch` the terminal verdict was made against — expired deltas never return, so
+	* ONLY an observed `snapBatch` beyond this can re-arm one snapshot-permitted attempt. `null` when
+	* not terminal. */
+	#terminalSnapBatch = null;
+	/** Suspect state at the previous tick — the false→true EDGE opens a fresh episode. */
+	#prevSuspect = false;
+	/** SINGLE-FLIGHT: a ladder step is between its due-decision and its awaits. Set in the
+	* SAME synchronous block as the due-decision that authorized it and cleared in that block's
+	* `finally`, so at most one step ever runs. Ticks are request-piggybacked (an isolate gets no
+	* free-running timer), which makes RE-ENTRY ROUTINE rather than exotic — a burst of requests can
+	* hand this poller several ticks while one step's store I/O is still in flight. A tick that finds
+	* a step running DECLINES; it never queues, because queueing merely defers the burst it exists to
+	* prevent. Nothing is lost: the rung it would have run is already scheduled (below). */
+	#stepInFlight = false;
+	/** Last baseline poll time (`null` until the first warm tick seeds the cursor). */
+	#lastPollMs = null;
+	/** Jittered baseline threshold, recomputed each poll (the current interval ±20%). */
+	#pollThresholdMs;
+	/** The CURRENT baseline interval the threshold is drawn from: `#pollBaseMs` while polls converge,
+	* doubled per consecutive failure up to `MAX_POLL_BACKOFF_MS`. Reset to the base by the
+	* first poll that converges again — the backoff is a property of the current failure episode, never
+	* a permanent cadence change. */
+	#pollIntervalMs;
+	constructor(reader, store, keys, rng, options = {}) {
+		this.#reader = reader;
+		this.#store = store;
+		this.#keys = keys;
+		this.#rng = rng;
+		this.#pollBaseMs = options.pollBaseMs ?? DEFAULT_POLL_BASE_MS;
+		this.#firstLadderDelayMs = options.firstLadderDelayMs ?? DEFAULT_FIRST_LADDER_DELAY_MS;
+		this.#laterLadderDelayMs = options.laterLadderDelayMs ?? DEFAULT_LATER_LADDER_DELAY_MS;
+		this.#jitterFraction = options.jitterFraction ?? DEFAULT_JITTER_FRACTION;
+		this.#pollIntervalMs = this.#pollBaseMs;
+		this.#pollThresholdMs = this.#jitter(this.#pollIntervalMs);
+	}
+	/**
+	* Whether the reader's replication has reached a permanent terminal gap — the
+	* hole-chasing ladder is stopped, fail-closed, until a durable `snapBatch` advance re-arms it.
+	* Read-only exposition of the already-tracked `#terminal` verdict for `explain`; it
+	* adds no bookkeeping — the field is written only by the tick machinery, never by this getter.
+	*/
+	get terminal() {
+		return this.#terminal;
+	}
+	/**
+	* Advance the state machine one tick. Always observes the pointer for liveness; then
+	* drives the ladder (suspect) or the baseline poll (warm). Out-of-band — never on a read path.
+	*/
+	async onPollTick(nowMs) {
+		const raw = await this.#store.get(this.#keys.stateKey);
+		const pointer = raw === void 0 ? void 0 : readStatePointer(raw.value);
+		if (pointer !== void 0) this.#reader.notePointerObservation(pointer, nowMs);
+		if (this.#stepInFlight) return;
+		const { suspect } = this.#reader;
+		if (suspect && !this.#prevSuspect) {
+			this.#terminal = false;
+			this.#terminalSnapBatch = null;
+			this.#ladder = null;
+		}
+		this.#prevSuspect = suspect;
+		if (this.#terminal) {
+			if (pointer !== void 0 && this.#terminalSnapBatch !== null && pointer.snapBatch > this.#terminalSnapBatch) {
+				this.#terminal = false;
+				this.#terminalSnapBatch = null;
+				if (await this.#reader.resyncViaSnapshot({ snapshotExhausted: true }) === "terminal-gap") {
+					this.#terminal = true;
+					this.#terminalSnapBatch = pointer.snapBatch;
+				}
+			}
+			return;
+		}
+		if (suspect) {
+			const ladder = this.#ladder ?? {
+				attempt: 0,
+				nextDueMs: nowMs
+			};
+			this.#ladder = ladder;
+			if (nowMs < ladder.nextDueMs) return;
+			ladder.attempt += 1;
+			ladder.nextDueMs = nowMs + this.#jitter(this.#ladderDelay(ladder.attempt));
+			this.#stepInFlight = true;
+			try {
+				await this.#runLadderStep(nowMs, ladder, pointer?.snapBatch ?? 0);
+			} finally {
+				this.#stepInFlight = false;
+			}
+			return;
+		}
+		this.#ladder = null;
+		if (this.#lastPollMs === null) {
+			this.#lastPollMs = nowMs;
+			this.#pollThresholdMs = this.#jitter(this.#pollIntervalMs);
+			return;
+		}
+		if (this.#reader.pollDue(nowMs, this.#lastPollMs, this.#pollThresholdMs)) {
+			this.#lastPollMs = nowMs;
+			const status = await this.#reader.resync();
+			this.#pollIntervalMs = status === "converged" ? this.#pollBaseMs : this.#backedOff(this.#pollIntervalMs);
+			this.#pollThresholdMs = this.#jitter(this.#pollIntervalMs);
+		}
+	}
+	/** One backoff step: ×2, capped at 300s (never below the configured base — a base ABOVE the cap is
+	* already slower than any backoff could make it, so the cap floors to it rather than SPEEDING the
+	* poll up on failure). */
+	#backedOff(intervalMs) {
+		const cap = Math.max(MAX_POLL_BACKOFF_MS, this.#pollBaseMs);
+		return Math.min(intervalMs * POLL_BACKOFF_FACTOR, cap);
+	}
+	/**
+	* Run one ladder rung. Rungs 1–2 retry the delta pass; rung 3 escalates
+	* (`deltasExhausted`) and bridges via the snapshot on `needs-snapshot`; rung ≥4 spends the
+	* snapshot budget so the reader makes the permanent ruling. Never sleeps.
+	*
+	* the caller has ALREADY claimed the rung (`ladder.attempt`) and committed its provisional
+	* next-due, synchronously, before this is entered — so this method only ever OVERWRITES that
+	* schedule when the outcome calls for a different one. It re-schedules NOTHING on the retry path
+	* (the provisional IS the retry), and it writes nothing that a re-entrant tick could race, because
+	* the in-flight flag the caller set means no other tick is deciding anything while this runs.
+	*/
+	async #runLadderStep(nowMs, ladder, observedSnapBatch) {
+		const { attempt } = ladder;
+		let status = await this.#reader.resync({ deltasExhausted: attempt >= ESCALATE_AT_ATTEMPT });
+		if (status === "needs-snapshot") status = await this.#reader.resyncViaSnapshot({ snapshotExhausted: attempt >= SNAPSHOT_FINAL_ATTEMPT });
+		if (status === "converged") {
+			ladder.attempt = 0;
+			ladder.nextDueMs = nowMs + this.#jitter(this.#pollBaseMs);
+			return;
+		}
+		if (status === "terminal-gap") {
+			this.#terminal = true;
+			this.#terminalSnapBatch = observedSnapBatch;
+			this.#ladder = null;
+		}
+	}
+	/** The base ladder delay for the rung just run: attempt 1 → ~1s, attempts ≥2 → ~5s. */
+	#ladderDelay(attempt) {
+		return attempt <= 1 ? this.#firstLadderDelayMs : this.#laterLadderDelayMs;
+	}
+	/** Jitter a base delay symmetrically by ±`jitterFraction`, drawn from the injected rng (no
+	* ambient randomness). rng.next() ∈ [0,1) ⇒ factor ∈ [1−f, 1+f). */
+	#jitter(baseMs) {
+		const f = this.#jitterFraction;
+		return baseMs * (1 - f + 2 * f * this.#rng.next());
+	}
+};
+/** The library's default safe-mode codec. Deterministic JSON round-trip. */
+const safeCodec = {
+	decode(value) {
+		return JSON.parse(value);
+	},
+	encode(value) {
+		return JSON.stringify(value);
+	},
+	id: "safe/1"
+};
+//#endregion
+//#region src/cache.ts
+/** The `<scope>` literal of the one shared, principal-free storage class. It is
+* the ONLY value that keeps a response shared-cacheable under. */
+const PUBLIC_SCOPE = "pub";
+/** The scope evidence a served HIT carries: its stored literal, or the fail-closed
+* `unreadable` class when the shared surface returned none. */
+function hitScopeEvidence(hit) {
+	if (hit.scopeUnreadable || hit.rawScope === void 0) return { kind: "unreadable" };
+	return {
+		kind: "readable",
+		literal: hit.rawScope
+	};
+}
+/** The scope evidence a FILL carries: the literal this kernel just resolved for it.
+*Never `unreadable` — a computed scope cannot fail to be read. */
+function fillScopeEvidence(literal) {
+	return {
+		kind: "readable",
+		literal
+	};
+}
+/** Record one consumed dependency on the ambient collector, if there is one. */
+function recordDependency(ambient, dependency) {
+	ambient?.()?.record(dependency);
+}
+/** Record a SERVED stored entry as a consumed dependency: the tags it was stored
+* with, plus the scope evidence read off the surface it came from — `unreadable` when that
+* surface returned no scope at all, which poisons the response rather than guessing. A
+* `undefined` hit is a serve that never happened, and records nothing. */
+function recordServedHit(ambient, hit) {
+	if (hit === void 0) return;
+	recordDependency(ambient, {
+		scope: hitScopeEvidence(hit),
+		tags: hit.envelope.tags
+	});
+}
+/** The verdict for a registry-absent instance: with no watermark authority every
+* stored entry reads FRESH, exactly as the codec-only read path classifies it — there is nothing
+* that could purge it, so nothing is `stale`/`dead`/`unknown`. */
+const FRESH_VERDICT = {
+	hardEpoch: 0,
+	softEpoch: 0,
+	validity: "fresh"
+};
+/**
+* The request-scoped per-dependency attribution `explain` surfaces — the bound
+* render collector's recorded dependencies, projected to the public shape. `undefined` when no
+* collector is bound (outside an adapter request frame): the attribution lives and dies with the
+* request, so its ABSENCE is itself the honest report (a witness reports what it knows; unbound ⇒
+* there is nothing to attribute).
+*/
+function explainAttribution(ambient) {
+	const state = ambient?.();
+	if (state === void 0) return;
+	return state.records.map((dependency) => ({
+		scope: dependency.scope,
+		tags: dependency.tags,
+		...dependency.l3 === void 0 ? {} : { l3: dependency.l3 }
+	}));
+}
+/** Per-instance namespace-version counter. `clear()` bumps it so
+* every canonical key minted AFTER the bump is unreachable from a pre-clear key —
+* a second, independent defense alongside the `__ns` hard watermark (INV-23). Held
+* as a small mutable cell (not a plain closure variable) so it can be threaded
+* through the free functions below exactly like `Invalidation`. */
+var NsVersion = class {
+	#version = 0;
+	get current() {
+		return this.#version;
+	}
+	bump() {
+		this.#version += 1;
+	}
+};
+/** Canonical key form `<ns-version>:<ns>:<scope>:<user-key>`. */
+function canonicalKey(nsVersion, namespace, scope, userKey) {
+	return `${nsVersion}:${namespace}:${scope}:${userKey}`;
+}
+/**
+* The adapter-visible identity fields a default-scope request can carry, in
+* precedence order ( principal-derived scoping; adapter-visible
+* identity / request-identity-header values). `userId` is the per-user
+* principal the RR/Workers adapter surfaces; a request that carries only a
+* `tenant` still bears adapter-visible identity, so it too derives a principal.
+* A request with none of these carries no derivable principal.
+*/
+const PRINCIPAL_FIELDS = ["userId", "tenant"];
+/**
+* Derive the adapter-visible principal from a request. Returns
+* the first present identity field's value keyed by its field name, or `undefined`
+* when the request carries no recognized identity (no context / null principal ⇒
+* shared `pub` class). Adapter-visible identity is a primitive
+* (a userId/tenant string, a header value) — a non-primitive field value is not a
+* clean principal and is skipped. A read here goes through the caller-supplied
+* request object directly (NOT the dev-mode guarded Proxy) — principal derivation
+* is the kernel's own inspection, not a public-factory closure, so it must never
+* itself trip the guarded-accessor demotion (INV-4 test 2).
+*/
+function derivePrincipal(request) {
+	if (request === void 0) return;
+	for (const field of PRINCIPAL_FIELDS) {
+		const value = request[field];
+		if (typeof value === "string" || typeof value === "number" || typeof value === "boolean" || typeof value === "bigint") return `${field}:${value.toString()}`;
+	}
+}
+/**
+* Hash a derived principal into the `usr:<hash>` scope suffix. A
+* synchronous SHA-256 truncated to 128 bits (32 hex) — hashing is not randomness,
+*and this keeps the fill path synchronous. The result is
+* non-empty and checkable, so the abolished hashless `usr:` literal can
+* never recur: every `usr:` scope carries a principal hash.
+*/
+function hashPrincipal(principal) {
+	return createHash("sha256").update(principal).digest("hex").slice(0, 32);
+}
+/**
+* The `<scope>` literal prefix of the per-principal storage class — the ONE
+* class `resolveScope` confines to the isolate-local L1. Shared by both directions so they
+* cannot drift: the MINT below builds a literal with it, and `storedScopeIsL1Only` reads a
+* STORED literal back through it. A serve derives confinement from the identity the entry was
+* stored under, so the two sides must agree on one prefix by construction.
+*/
+const PRINCIPAL_SCOPE_PREFIX = "usr:";
+function resolveScope(input) {
+	const { scope } = input;
+	if (scope === "public") return {
+		l1Only: false,
+		literal: "pub"
+	};
+	if (scope !== void 0 && typeof scope === "object") return {
+		l1Only: false,
+		literal: `ten:${hashPrincipal(scope.tenant)}`
+	};
+	const principal = derivePrincipal(input.request);
+	if (principal !== void 0) return {
+		l1Only: true,
+		literal: `${PRINCIPAL_SCOPE_PREFIX}${hashPrincipal(principal)}`
+	};
+	return {
+		l1Only: false,
+		literal: "pub"
+	};
+}
+/**
+* Whether a STORED `<scope>` literal names the L1-confined class — the read-back twin
+* of `resolveScope`'s `l1Only`, over a literal rather than the call inputs a serve no longer has.
+* `pub`/`ten:` are shared-tier classes; only `usr:<hash>` is confined.
+*
+* NOTE the asymmetry this CANNOT see, by construction: a `pub` fill DEMOTED at fill time by the
+* dev-mode guarded-accessor Proxy stores the `pub` literal, so its confinement leaves no trace in
+* the stored identity. Such an entry reads back as `pub` here, and a serve reports its durability
+* ABSENT — unknowable, which is the honest answer, rather than a `true` the literal cannot
+* support.
+*/
+function storedScopeIsL1Only(literal) {
+	return literal.startsWith(PRINCIPAL_SCOPE_PREFIX);
+}
+/** The `<scope>` literal alone — for the contexts (canonical key, join
+* identity, key-selector purge) that need only the string, not the tier policy. */
+function scopeLiteral(input = {}) {
+	return resolveScope(input).literal;
+}
+/** Normalize the config's `telemetry` (a bare sink function, a config object, or
+* absent) to `{ sink, hosted?, salt?, onSinkError? }`. A bare function carries no
+* hosted/salt/onSinkError; the config-object form passes them through unchanged. */
+function telemetryOf(config) {
+	const { telemetry } = config;
+	if (telemetry === void 0) return;
+	if (typeof telemetry === "function") return { sink: telemetry };
+	return telemetry;
+}
+/**
+* Pseudonymize one string field for a HOSTED sink: a per-project
+* HMAC-salted hash, so a short or low-entropy identifier (a key or a tag) is not
+* offline-invertible and never travels raw. The salt is the per-project secret
+* (`hostedTelemetry(salt)`), so holding key+tag fixed and changing ONLY the salt
+* changes the ref — and the ref tracks its own input, so a key ref moves iff the
+* key moves and a tag ref moves iff the tag moves (INV-15). HMAC (not a bare hash)
+* so the salt genuinely keys the digest per project.
+*/
+function saltedRef(salt, value) {
+	return createHmac("sha256", salt).update(value).digest("hex").slice(0, 32);
+}
+/** Redact one event field for a hosted sink: HMAC-salt every string (per-field,
+* including inside a string array — key ref, tag refs), leave non-string scalars
+* intact. `type` (the event NAME, not sensitive) is redacted by the caller's field
+* filter, never here. A field-total salted pseudonymization — not
+* anonymization. */
+function redactField(salt, value) {
+	if (typeof value === "string") return saltedRef(salt, value);
+	if (Array.isArray(value)) return value.map((element) => redactField(salt, element));
+	return value;
+}
+/**
+* Emit a telemetry event. A plain sink receives the event verbatim
+* (raw key/tag/detail — redaction is hosted-only by design, INV-15). A HOSTED sink
+* receives a field-total salted pseudonymization: every string field EXCEPT `type`
+* (the event name) is replaced by a per-project HMAC-salted hash of its own value,
+* so no raw key/tag/salt/detail ever leaves the process. A hosted config
+* missing a salt cannot pseudonymize, so it is suppressed rather than leaking raw
+* fields. The final delivery — plain or redacted — goes through `safeEmit`, so an
+* app sink that throws or rejects is swallowed (its `onSinkError` hook notified) and
+* can never surface on the kernel's own path.
+*/
+function emitTelemetry(config, event) {
+	const telemetry = telemetryOf(config);
+	if (telemetry === void 0) return;
+	if (telemetry.hosted !== true) {
+		safeEmit(telemetry.sink, event, telemetry.onSinkError);
+		return;
+	}
+	const { salt } = telemetry;
+	if (salt === void 0) return;
+	const redacted = { type: event.type };
+	for (const [field, value] of Object.entries(event)) {
+		if (field === "type") continue;
+		redacted[field] = redactField(salt, value);
+	}
+	safeEmit(telemetry.sink, redacted, telemetry.onSinkError);
+}
+/** The reserved per-key tag: `__k:<h>`, `<h>` a ≥128-bit (32 hex char) digest
+* of the canonical key (scoped, ns-versioned). SHA-256 truncated to 128 bits — a
+* synchronous digest (`node:crypto`, available on both Node and Bun) so the fill
+* path stays fully synchronous; hashing is not randomness. `expire
+* ({key})` recomputes this same digest to target the identical tag. */
+function keyTag(canonical) {
+	return `__k:${createHash("sha256").update(canonical).digest("hex").slice(0, 32)}`;
+}
+/** The reserved per-namespace tag: `__ns:<name>`. Every envelope
+* carries it so `clear()`'s hard purge rides the same epoch/bus/conservative
+* machinery as any other purge — this is what lets a lagging isolate's read
+* fail closed instead of serving pre-clear data (INV-23). */
+function nsTag(namespace) {
+	return `__ns:${namespace}`;
+}
+/** Validate the committed user-tag SET at the write boundary. Two ceilings, both
+* per typed `InvalidTagError`, never `NotImplementedError`:
+*   - the `__`-prefix backstop, per tag — a forged reserved tag never reaches storage;
+*   - the count ceiling, over the whole set — at most `MAX_USER_TAGS` user tags.
+* The caller passes whatever set is being committed — the declared tags at `getOrSet`'s
+* boundary, or the settle-union of declared + `setTags` + `dependsOn` — so the ceiling
+* is route-independent by construction: one function, one set, one boundary. The reserved
+* `__k`/`__ns` tags are stamped separately and never counted here. The set is expected already
+* deduped (the ceiling counts distinct user tags, not raw call arity). */
+function validateUserTags(tags) {
+	if (tags === void 0) return;
+	if (tags.length > 126) throw new InvalidTagError(tags[126] ?? "", `an entry may not carry more than 126 user tags (§2.3, MI13); got ${tags.length}`);
+	for (const tag of tags) assertUserTag(tag);
+}
+/** `tags` are sorted, deduped, and include `__k`/`__ns`. Dedupes FIRST, then validates the
+* distinct set — so the count ceiling measures distinct user tags, not raw call
+* arity — and returns just the caller-supplied set, sorted and deduped. The reserved
+* `__k`/`__ns` tags are appended separately by `envelopeTags` below, since they depend on the
+* canonical key / namespace, not just the call options. */
+function sortedUserTags(tags) {
+	if (tags === void 0) return [];
+	const distinct = [...new Set(tags)].toSorted();
+	validateUserTags(distinct);
+	return distinct;
+}
+/** The full stored-envelope tag set: sorted user tags plus the reserved
+* `__k:<h>` (per-key digest of the canonical key) and `__ns:<name>` (per-namespace
+* watermark) tags. This is what rides the dual-epoch invalidation core, so
+* `expire({key})` / `clear()` invalidate through the same machinery as any tag
+* purge. */
+function envelopeTags(userTags, canonical, namespace) {
+	return [
+		...userTags,
+		keyTag(canonical),
+		nsTag(namespace)
+	].toSorted();
+}
+function makeTagAccumulator(declared) {
+	const membership = [];
+	let authored;
+	let settled = false;
+	return {
+		isSettled() {
+			return settled;
+		},
+		markSettled() {
+			settled = true;
+		},
+		addMembership(tag) {
+			assertUserTag(tag);
+			membership.push(tag);
+		},
+		author(tags) {
+			for (const tag of tags) assertUserTag(tag);
+			authored = [...tags];
+		},
+		settleUserTags() {
+			return [.../* @__PURE__ */ new Set([...authored ?? declared, ...membership])].toSorted();
+		}
+	};
+}
+/** Resolve the codec, falling back to the built-in safe-mode codec when the
+* config wires none — `world()` wires no codec, so the core needs a default
+* to store/read values at all. */
+function codecOf(config) {
+	return config.codec ?? safeCodec;
+}
+/**
+* The consistency this call reads at: per-call, then the instance's declared default, then
+* the own (`eventual`).
+*
+* The middle step is what makes `CacheDefaults.consistency` a setting rather than a decoration:
+* without it, a caller who declared `defaults: { consistency: 'strong' }` got eventual reads and
+* nothing said so. The final fallback is unchanged and matches what every shipped default already
+* declares, so an instance that sets nothing reads exactly as it did before.
+*/
+function consistencyOf(config, options) {
+	return options.consistency ?? config.defaults?.consistency ?? "eventual";
+}
+/**
+* How fail-closed `unknown` resolves for this instance.
+*
+* `takedownSensitive` is an OVERRIDE, and the precedence is the whole point. It outranks an
+* explicitly-set `unknownPolicy` rather than merely filling in for an absent one — because as an
+* absent-policy default it was unreachable in practice: any composition that sets `unknownPolicy`
+* shadows it, and `createWorkersCache`'s own safe posture sets it, so the switch was dead on the
+* entire hero path. A legal-embargo control that a routine, recommended default silently disables is
+* worse than no control: it reads as protection and does nothing.
+*
+* Reading it as an override is also what the flag MEANS. `unknownPolicy` says how this namespace
+* would like unknowns resolved; `takedownSensitive` says this namespace is one where guessing is not
+* allowed. The second is a statement about the CONTENT, so it cannot be outranked by a preference.
+*/
+function unknownResolution(config) {
+	if (config.takedownSensitive === true || config.defaults?.takedownSensitive === true) return {
+		armedBy: "takedownSensitive",
+		kind: "error"
+	};
+	const policy = config.defaults?.unknownPolicy ?? "registry-check";
+	return policy === "error" ? {
+		armedBy: "unknownPolicy",
+		kind: "error"
+	} : policy;
+}
+/** The `staleIfError` predicate for this instance — the configured
+* override, or the default HTTP classifier. */
+function staleIfErrorOf(config) {
+	return config.defaults?.staleIfError ?? isRetriableHttp;
+}
+/** Whether a thrown error is the `not_found` fact (a 404) — never masked,
+* never retriable, but eligible for negative caching when `notFoundTtl` is declared. */
+function isNotFound(err) {
+	return err instanceof HttpError && err.status === 404;
+}
+/** A miss with no live check performed (absent / codecId / decode). */
+const MISS_READ = { checkedThrough: 0 };
+/** Whether a stored entry's codec identity matches (or is an accepted migration
+* source) — checked BEFORE decode so a foreign codec never runs. */
+function codecIdMatches(storedCodecId, codec, config) {
+	if (storedCodecId === codec.id) return true;
+	const acceptCodecs = config.defaults?.acceptCodecs ?? [];
+	return typeof storedCodecId === "string" && acceptCodecs.includes(storedCodecId);
+}
+/** Reconstruct the envelope shell from stored bytes + metadata. `bornEpoch`/
+* `tags` ride in metadata so validation runs without a second decode. */
+function envelopeFromStore(key, raw, metadata, decoded, codecId) {
+	const bornEpoch = typeof metadata.bornEpoch === "number" ? metadata.bornEpoch : 0;
+	const bornMs = typeof metadata.bornMs === "number" ? metadata.bornMs : 0;
+	const tags = Array.isArray(metadata.tags) ? metadata.tags.filter((t) => typeof t === "string") : [];
+	return {
+		bornEpoch,
+		bornMs,
+		codecId,
+		enc: "json",
+		grace: 0,
+		key,
+		kind: metadata.kind === "neg" ? "neg" : "val",
+		scope: typeof metadata.scope === "string" ? metadata.scope : "pub",
+		size: raw.length,
+		src: "factory",
+		storedAt: bornMs,
+		tags,
+		ttl: 0,
+		v: 3,
+		val: decoded,
+		...typeof metadata.fence === "number" ? { fence: metadata.fence } : {}
+	};
+}
+/**
+* The value a HIT on this envelope SURFACES.
+*
+* A `kind:'neg'` envelope is a remembered 404: it caches the not-found FACT, and the envelope gives it no
+* value to carry. Its stored bytes are a JSON-representable placeholder (`writeNegEnvelope`) chosen
+* only because `undefined` is not a storable body — they are never the answer. So a read of a neg
+* surfaces `undefined`, which is EXACTLY what the fill turn that wrote it surfaced (INV-7): the
+* point of caching a 404 is that the next reader gets the same answer without paying the origin,
+* and an answer that changes on the second call is not a cached fact at all. Serving the placeholder
+* instead handed the caller a `null` no origin ever produced, and reported a durable VALUE hit for
+* an entry holding only a negative.
+*
+* A `val` envelope surfaces its decoded value unchanged. This is the ONE point where the two kinds
+* diverge on the read path; every other neg rule is already a refusal to serve at all ( a
+* stale neg is never grace/SWR-served, so the only servable neg is a fresh one).
+*/
+function servedValue(envelope) {
+	if (envelope.kind === "neg") return;
+	return envelope.val;
+}
+/**
+* Classify a rejected `Store.get` — the read-side twin of `classifyWriteBackFailure`, and
+* consistent with its reasoning rather than merely its shape:
+*
+*   - CLASSIFIED (`throttled` / `unavailable`) ⇒ returned to the caller, which absorbs it. The kernel signs
+*     that a suppressed L2 GET error is a plain MISS — never routed to unknown/fail-closed — so on
+* the serving path the caller refills, and a configured L1 (checked FIRST) may already
+*     have served without this tier being read at all.
+*   - UNCLASSIFIED ⇒ RETHROWN unchanged, for the same reason the write half rethrows one: the kernel
+*     absorbs only failures a driver has named, and a rejection nobody classified is not evidence of
+*     absence. Swallowing it would turn an unknown fault into a confident "not found" — which, on a
+*     read, is the one answer that silently refills over whatever is really there.
+*
+* Suppression is the only telemetry-bearing outcome (`store_read_suppressed`, a raw fact at the
+* instant it occurs). A rethrown error needs no event: it reaches the caller intact.
+*/
+function classifyStoreReadFailure(config, key, error) {
+	if (!isStoreReadError(error)) throw error;
+	emitTelemetry(config, {
+		code: error.code,
+		key,
+		type: TELEMETRY_EVENTS.store_read_suppressed
+	});
+	return error;
+}
+/** The ONE spelling of the "the store did not answer" discriminant, shared by the probe's outcome
+* and the witness's own arm so the two can never drift apart. */
+const READ_FAILED_KIND = "read-failed";
+/** The two probe outcomes that carry no payload — one shared instance each, exactly as `MISS_READ`
+* is for the read path. */
+const PROBE_ABSENT = { kind: "absent" };
+const PROBE_READ_FAILED = { kind: READ_FAILED_KIND };
+/**
+* A NON-mutating presence probe for `explain`: read `canonical` from `store` with a
+* plain `store.get` — never a hydrating read — and reconstruct its envelope plus the RAW stored
+* scope; `absent` when the entry is missing, codec-mismatched, or undecodable; `read-failed`
+* when the store's own read was suppressed. The read fails closed exactly as the serve path
+* does (INV-8/27); it observes, it never writes.
+*/
+async function probeStoredEntry(store, codec, config, canonical) {
+	let stored;
+	try {
+		stored = await store.get(canonical);
+	} catch (error) {
+		classifyStoreReadFailure(config, canonical, error);
+		return PROBE_READ_FAILED;
+	}
+	if (!stored || !codecIdMatches(stored.metadata?.codecId, codec, config)) return PROBE_ABSENT;
+	let decoded;
+	try {
+		decoded = codec.decode(stored.value);
+	} catch {
+		return PROBE_ABSENT;
+	}
+	const envelope = envelopeFromStore(canonical, stored.value, stored.metadata ?? {}, decoded, codec.id);
+	const storedScope = stored.metadata?.scope;
+	const scope = typeof storedScope === "string" ? {
+		kind: "readable",
+		literal: storedScope
+	} : { kind: "unreadable" };
+	const storedTtl = stored.metadata?.ttl;
+	return {
+		envelope,
+		kind: "found",
+		scope,
+		ttl: typeof storedTtl === "number" ? {
+			kind: "stored",
+			seconds: storedTtl
+		} : { kind: "not-stored" }
+	};
+}
+/**
+* THE READ PATH'S CLASSIFIER for the SERVING path. Given raw stored bytes and metadata, it answers
+* what a reader on THIS instance would make of them: an envelope, or nothing at all. (The
+* introspection probe still runs its own copy of this sequence — see `probeStoredEntry`, which
+* answers a different question and must report the causes of absence rather than collapse them to
+* one. Folding the two is worth doing and is not this change.)
+*
+* Two gates precede the reconstruction and both fail CLOSED, because a reader that cannot identify
+* or decode an entry is served a miss rather than a guess — the codecId check (INV-27/ : a
+* mismatch `acceptCodecs` does not admit is a miss) and `decode` itself (INV-8: a body this codec
+* cannot read is a miss). Only past both is an envelope built.
+*
+* Both seats call THIS function, by identity, and that is the point. "Servable" is defined by the
+* read path, so the write layer's neg-write guard must ask the READER's question rather than a looser one
+* of its own: an envelope no reader can classify as a val is not a servable good value — it is a
+* miss wearing bytes, and protecting it protects a ghost. Answering that question with a partial
+* copy of these steps is exactly how two seats stop meaning one thing while each keeps passing its
+* own tests.
+*/
+function readerEnvelope(config, codec, key, stored) {
+	if (!codecIdMatches(stored.metadata?.codecId, codec, config)) return;
+	let decoded;
+	try {
+		decoded = codec.decode(stored.value);
+	} catch {
+		return;
+	}
+	return envelopeFromStore(key, stored.value, stored.metadata ?? {}, decoded, codec.id);
+}
+/**
+* Read one tier: codecId-check + decode + validate against knowledge.
+* `hit` is a `ReadHit` (fresh or stale-servable) or `undefined` (absent / dead /
+* decode failure / codecId mismatch / suppressed read failure / unknown-fail-closed ⇒ the
+* caller refills). `checkedThrough` is the epoch a live check by THIS read verified (0 if
+* none), which the refill uses so a behind isolate does not fence its own legitimate refetch.
+*/
+async function readTier(store, codec, config, inval, consistency, key) {
+	let stored;
+	try {
+		stored = await store.get(key);
+	} catch (error) {
+		classifyStoreReadFailure(config, key, error);
+		return MISS_READ;
+	}
+	if (!stored) return MISS_READ;
+	const envelope = readerEnvelope(config, codec, key, stored);
+	if (!envelope) return MISS_READ;
+	const storedScope = stored.metadata?.scope;
+	const rawScope = typeof storedScope === "string" ? storedScope : void 0;
+	const scopeEvidence = {
+		scopeUnreadable: rawScope === void 0,
+		...rawScope === void 0 ? {} : { rawScope }
+	};
+	if (!inval) return {
+		checkedThrough: 0,
+		hit: {
+			...scopeEvidence,
+			envelope,
+			stale: false,
+			value: servedValue(envelope)
+		}
+	};
+	const { validity, checkedThrough } = await inval.validate(envelope, consistency, unknownResolution(config), config.defaults?.onUnavailable);
+	if (validity === "fresh") return {
+		checkedThrough,
+		hit: {
+			...scopeEvidence,
+			envelope,
+			stale: false,
+			value: servedValue(envelope)
+		}
+	};
+	if (validity === "stale" && envelope.kind !== "neg") return {
+		checkedThrough,
+		hit: {
+			...scopeEvidence,
+			envelope,
+			stale: true,
+			value: servedValue(envelope)
+		}
+	};
+	if (envelope.kind === "neg") return { checkedThrough };
+	return {
+		checkedThrough,
+		staleCandidate: {
+			...scopeEvidence,
+			envelope,
+			stale: true,
+			value: servedValue(envelope)
+		}
+	};
+}
+/**
+* DEVELOPMENT-TIME TEACHING TOOL — NOT A PRODUCTION SAFETY NET. It is dev-gated by design
+* (`config.dev === true`), and it stays that way. Two readings to head off, in both directions:
+*
+*   - DO NOT PROMOTE IT TO PRODUCTION believing it closes a privacy hole. It does not close one:
+*     an application that hand-mixes per-principal content into a public-scoped fill without
+*     touching `ctx.request` at all is untouched by it, so it was never a boundary — it is a
+*     tripwire that catches the honest mistake early, in the one environment where the developer
+*     is watching. Making the demotion live in production would make an entry's STORAGE TIER a
+*     function of what a factory happened to read on one execution: the same key lands durable on
+*     the request whose factory took the cache-hit path and L1-only on the request whose factory
+*     read the principal, so the tier stops being a property of the call and becomes a property of
+*     the run. That is nondeterministic caching, and it is a worse bargain than the mistake it
+*     would be trying to catch.
+*
+*   - DO NOT DELETE IT believing it is dead code. INV-4 pins it, and the demotion is exactly
+*     what that invariant's enforceable half asserts — a public fill that read request state is
+*     confined to L1 and never reaches the shared tier. Blind it and the sacred suite reds.
+*
+* It deliberately does NOT feed the shared-cacheability gate. That gate answers a different
+* question — whether the scopes the library DECLARED and STORED permit a shared HTTP cache to keep
+* the response — and it answers it from evidence that survives the request. This guard sees
+* only what one factory did while it ran. Wiring a runtime observation into that gate would make
+* the emitted response posture vary run to run for the same route, which is the same nondeterminism
+* as above, on the wire instead of in the tiers.
+*/
+function buildRequestGuard(config, options) {
+	const { request } = options;
+	if (!(config.dev === true && options.scope === "public") || request === void 0) return {
+		request,
+		wasTouched: () => false
+	};
+	let touched = false;
+	return {
+		request: new Proxy(request, { get(target, prop, receiver) {
+			touched = true;
+			return Reflect.get(target, prop, receiver);
+		} }),
+		wasTouched: () => touched
+	};
+}
+/** Acquire the cross-isolate lock if requested, returning its fence handle. */
+async function maybeLock(config, options) {
+	if (options.lock !== true) return;
+	const { lock } = config;
+	if (!lock) return;
+	return await lock.acquire(options.key);
+}
+/**
+* Classify a rejected L2 write-back into the kernel's write-failure semantics.
+* WIRES CLASSIFICATION + TELEMETRY ONLY — no REFRESH_QUEUE / retry machinery is built
+* (that is deferred). A recognized transient failure is SUPPRESSED: the write did not
+* become durable, but the operation does not fail the caller and produces no
+* fail-closed/unknown state — the function returns `false` (non-durable) and emits the
+* reserved telemetry name. Everything else keeps today's behavior and PROPAGATES:
+*   - `throttled` (retryable) → `writeback_throttled`, suppressed (`durable:false`).
+*   - `unavailable` (retryable) → `l2_write_error`, suppressed (`durable:false`).
+*   - `too_large` (permanent, non-retryable) → rethrown, never silently suppressed.
+*   - unclassified → surfaced as `l2_write_error` telemetry, then rethrown unchanged.
+*/
+function classifyWriteBackFailure(config, key, error) {
+	const classified = isStoreWriteError(error) ? error : void 0;
+	if (classified?.code === "throttled") {
+		emitTelemetry(config, {
+			key,
+			type: "writeback_throttled"
+		});
+		return false;
+	}
+	if (classified?.code === "unavailable") {
+		emitTelemetry(config, {
+			key,
+			type: "l2_write_error"
+		});
+		return false;
+	}
+	if (classified === void 0) emitTelemetry(config, {
+		key,
+		type: "l2_write_error"
+	});
+	throw error;
+}
+/**
+* Is this stored envelope a `val` that protects? THE suppression-worthiness
+* test, and it lives in ONE place because two seats have to agree about it:
+*
+*   - the SERVE seat (`gracedStillServable`) asks it of the candidate THIS read holds, deciding
+*     whether an error-path serve may draw on it;
+*   - the WRITE seat (`negDisplacesProtectedVal`) asks it of the envelope the born-monotone compare
+*     already fetched, deciding whether a `kind:'neg'` candidate may land on it.
+*
+* One function, because the two answers may never disagree in the direction that destroys data: a
+* val the serve path would hand to a caller is exactly a val the write path must refuse to bury.
+* Written twice they drift, and the drift is silent — each site keeps passing its own tests while
+* the pair stops meaning one thing.
+*
+* `validity` is the verdict, produced by the same machinery on both sides. `unknown` is
+* deliberately NOT settled here: it is a GAP rather than a window, and the two seats answer a gap
+* differently on purpose — the serve seat refuses to serve THROUGH one, the write seat refuses to
+* write through one. Each states that rule, with its own derivation, at its own site.
+*/
+function e7ProtectsStoredVal(envelope, validity) {
+	return envelope.kind !== "neg" && (validity === "fresh" || validity === "stale");
+}
+/** The `UnknownResolution` a RE-VALIDATION of an already-stored envelope asks for: settle
+* an unknown tag with one live registry read. Named once because the two seats that re-validate the
+* same envelope — the serve seat's grace check and the write seat's neg-write guard — must ask the SAME
+* question of it; drifting onto different resolutions would let them reach different verdicts about
+* one entry and call it agreement. Distinct from `unknownResolution`, which reports the instance's
+* configured READ-time policy. */
+const REVALIDATION_RESOLUTION = "registry-check";
+/**
+* the kind-aware guard: would landing a `kind:'neg'` candidate here bury a
+* `val` the letter protects? Asked of the envelope the born-monotone compare ALREADY fetched, which
+* is why it lives at the write layer — one boundary, so every neg-write source passes it identically
+* and the outcome cannot vary by the route that reached it.
+*
+* The question is ONTOLOGICAL: what does the STORE hold? That is a different question from the one
+* the filling caller's own read can answer, and the gap between them is the whole defect this closes
+* — a caller blind to a servable val (a tier that was unreadable for a moment, or a join whose
+* leader read nothing) would otherwise write straight over it, and every later reader would be
+* served the negative. Note also which KIND is which: `FilledAttempt.storedKind` describes what THIS
+* fill produced, while the kind read here is the STORED envelope's — different objects, and only the
+* second one can answer this.
+*
+* The within-grace term is not re-invented: it is the verdict `validate` gives, asked on the
+* same terms the serve seat asks for it (`gracedStillServable`), and settled by the shared predicate
+* both seats share.
+*/
+async function negDisplacesProtectedVal(config, key, existing, inval, consistency) {
+	const stored = readerEnvelope(config, codecOf(config), key, existing);
+	if (!stored) return false;
+	if (!inval) return e7ProtectsStoredVal(stored, "fresh");
+	let validity;
+	try {
+		({validity} = await inval.validate(stored, consistency, REVALIDATION_RESOLUTION, config.defaults?.onUnavailable));
+	} catch {
+		validity = "unknown";
+	}
+	return e7ProtectsStoredVal(stored, validity === "unknown" ? "stale" : validity);
+}
+/**
+* Born-monotone write-back (invariant 17): never replace a stored
+* envelope with a strictly-higher `(bornEpoch, fence)`. Read-compare-write against
+* L2 — the KV CAS-less residual race is documented and bounded to one refresh cycle.
+*`bornMs` is never an arbiter. `durable` is `true` when the candidate landed (or a
+* strictly-newer envelope already sits durably), `false` when a classified `throttled`/`unavailable`
+* failure suppressed it.
+*
+* It is ALSO where the kind-aware guard sits, for the reason the guard needs and this function
+* already has: the stored envelope is in hand here. A `kind:'neg'` candidate may only land on a true
+* miss, so every neg-write source — a solo caller's own disposition, a blind leader's in-window
+* recording — meets the same test on the same evidence, and route-independence holds by construction
+* rather than by matching two call sites. `val`-over-`neg` is untouched: recovery is the direction
+* The neg-write guard leaves open, and the guard is asked only of a neg candidate.
+*/
+async function bornMonotoneWrite(config, l2, key, encoded, candidate, inval, consistency) {
+	let existing;
+	try {
+		existing = await l2.get(key);
+	} catch (error) {
+		return {
+			durable: classifyWriteBackFailure(config, key, error),
+			writeSuppressed: false
+		};
+	}
+	if (existing) {
+		if (candidate.kind === "neg" && await negDisplacesProtectedVal(config, key, existing, inval, consistency)) {
+			emitTelemetry(config, {
+				key,
+				type: TELEMETRY_EVENTS.neg_suppressed
+			});
+			return {
+				durable: false,
+				writeSuppressed: true
+			};
+		}
+		const meta = existing.metadata ?? {};
+		const storedBornEpoch = typeof meta.bornEpoch === "number" ? meta.bornEpoch : 0;
+		const storedFence = typeof meta.fence === "number" ? meta.fence : -1;
+		const candidateFence = candidate.fence ?? -1;
+		if (storedBornEpoch > candidate.bornEpoch || storedBornEpoch === candidate.bornEpoch && storedFence > candidateFence) return {
+			durable: true,
+			writeSuppressed: false
+		};
+	}
+	try {
+		await l2.set(key, encoded, { metadata: {
+			bornEpoch: candidate.bornEpoch,
+			bornMs: candidate.bornMs,
+			codecId: candidate.codecId,
+			enc: candidate.enc,
+			kind: candidate.kind,
+			scope: candidate.scope,
+			tags: candidate.tags,
+			v: candidate.v,
+			...candidate.fence === void 0 ? {} : { fence: candidate.fence }
+		} });
+		return {
+			durable: true,
+			writeSuppressed: false
+		};
+	} catch (error) {
+		return {
+			durable: classifyWriteBackFailure(config, key, error),
+			writeSuppressed: false
+		};
+	}
+}
+/**
+* Re-validate a graced candidate's tags AT SERVE TIME: a hard delete
+* that landed after the candidate was read (e.g. during the failed refresh) must
+* fence it here — a graced value is never served once its purge is visible. No
+* `Invalidation` (registry-absent) ⇒ nothing to invalidate it ⇒ always servable.
+*
+* AT `strong` THIS IS A LIVE REGISTRY CHECK LIKE ANY OTHER, so it honors `onUnavailable`
+* exactly as its sibling sites do. Leaving it unguarded did not avoid a throw — it MANUFACTURED
+* one: the guard inside `validate` fires for a caller who explicitly opted out, which is the one
+* caller who asked not to see it.
+*
+* `factoryError` is what this re-validation runs on behalf of, and it rides out as the thrown
+* error's `cause`. That answers the reason the guard was omitted here — the fear that a throw would
+* REPLACE the caller's factory error — without leaving the site unguarded: nothing is dropped, and
+* callers still get the one type the API names.
+*
+* WHEN THE OPT-OUT IS TAKEN this call drops to what an eventual read would do, and the candidate is
+* settled against local knowledge alone. A tag whose hardness cannot be established stays UNKNOWN,
+* and an unknown tag is never graced (ladder sends unknown to 5a and never to grace) —
+* when hardness is exactly what we failed to learn, a hard purge is one of the things the gap could
+* be concealing. So an unknown candidate is not servable, and the factory's own error is what the
+* caller ends up with.
+*/
+async function gracedStillServable(inval, consistency, envelope, onUnavailable, factoryError) {
+	if (!inval) return e7ProtectsStoredVal(envelope, "fresh");
+	let validity;
+	try {
+		({validity} = await inval.validate(envelope, consistency, REVALIDATION_RESOLUTION, onUnavailable));
+	} catch (error) {
+		if (error instanceof RegistryUnavailableError) throw new RegistryUnavailableError(error.message, { cause: factoryError });
+		throw error;
+	}
+	return e7ProtectsStoredVal(envelope, validity);
+}
+/**
+* Write a `kind:'neg'` envelope for a `not_found` fact.
+* `notFoundTtl` is the per-call opt-in; the write shares the same born-monotone
+* fence as any write-back.
+*
+* Returns the write's OUTCOME (durability, and whether the guard refused it) AND
+* the `bornMs` it stamped — the neg's birth instant, read off the clock exactly once here and
+* carried out for every later consumer, the same way a value fill's is.
+*
+* `inval`/`consistency` ride down for the guard alone: it decides against the STORE, and deciding
+* against the store means asking the same validity question a reader asks of what it finds there.
+*/
+async function writeNegEnvelope(config, key, tags, scope, bornEpoch, inval, consistency) {
+	const { l2 } = config;
+	const bornMs = config.clock.now();
+	if (!l2) return {
+		bornMs,
+		durable: true,
+		writeSuppressed: false
+	};
+	const codec = codecOf(config);
+	const encoded = codec.encode(null);
+	return {
+		bornMs,
+		...await bornMonotoneWrite(config, l2, key, encoded, {
+			bornEpoch,
+			bornMs,
+			enc: "json",
+			grace: 0,
+			key,
+			kind: "neg",
+			scope,
+			size: encoded.length,
+			src: "factory",
+			storedAt: bornMs,
+			tags,
+			ttl: 0,
+			v: 3,
+			val: null,
+			codecId: codec.id
+		}, inval, consistency)
+	};
+}
+/** Build the INV-26 neg-suppression serve of a still-servable candidate (a 404 that a servable
+* `val` displaces). ONE constructor for both call sites — the leader-sighted classification and a
+* blind leader's per-waiter tail — so `value` is always the served candidate's own value.
+*
+* It also EMITS, and the emit belongs here rather than at either caller. The design lists `neg_suppressed`
+* among a suppression's consequences, and the design attaches those consequences to whichever seat renders
+* the suppression, one event per suppression. This is the serve seat's renderer; the write layer's
+* guard emits its own at its own site. Emitting from the shared constructor is what makes one
+* event per suppression structural instead of a convention two call sites have to remember —
+* before it, the epistemic suppression that the own rationale describes fired no telemetry at all,
+* so the commonest case was the silent one. */
+function negSuppressed(config, key, served) {
+	emitTelemetry(config, {
+		key,
+		type: TELEMETRY_EVENTS.neg_suppressed
+	});
+	return {
+		kind: "neg-suppressed",
+		served,
+		value: served.hit.value
+	};
+}
+/**
+* Write the `not_found` neg and package it as the `filled` attempt every
+* SERVED-fill path already understands: `value:undefined`, the neg's stored tag set, and the write's
+* own `durable`/`bornMs`. A neg carries no `bornEpoch` on the outcome — its presence is the marker
+* of a successful VALUE fill, which this is not — so L1 hydration falls back to the caller's
+* outer floor exactly as the value path intends.
+*
+* ONE writer of the neg for two call sites: the leader that read a candidate of its own that
+* re-validated DEAD (its own disposition, in `classifyFillError`), and any blind waiter's own tail
+* (`runOwnNotFoundTail`). Both stamp the fill's tags/scope/bornEpoch, so a neg written on either path
+* is byte-identical to the one a solo caller writes — and both meet the write-layer guard, which is
+* why a SUPPRESSED write is one of the outcomes this can carry (`writeSuppressed`): the fill still
+* produced the not-found FACT and still serves it, but nothing was stored and nothing is evicted.
+*/
+async function negWriteFilled(config, key, tags, scope, bornEpoch, inval, consistency) {
+	const neg = await writeNegEnvelope(config, key, tags, scope, bornEpoch, inval, consistency);
+	return {
+		bornMs: neg.bornMs,
+		durable: neg.durable,
+		kind: "filled",
+		storedKind: "neg",
+		tags,
+		value: void 0,
+		writeSuppressed: neg.writeSuppressed
+	};
+}
+/**
+* The factory error-path classification, extracted out of
+* `fillAndStore` to keep its cognitive complexity down:
+*   - `ctx.skip()` (M10/invariant 24): `{kind:'skipped'}` — nothing stored,
+*     nothing served; no write-back of any kind, not even a neg.
+*   - `not_found` (404, a fact — never masked): with `notFoundTtl` declared and THIS fill's own read
+*     holding a still-servable `val`, suppress the neg-write and serve that val — a neg must never
+* displace a servable value — with no `servedOnError` (a suppressed neg is not an
+*     error-path serve). This fill's own copy re-validated DEAD ⇒ write the neg and serve it (its own
+*     disposition). This fill read NO copy at all (a blind leader) ⇒ ride the 404 out as a shareable
+*     `not-found` FACT so each waiter runs its own tail against its own read ( `NotFoundFact
+*     Attempt`), the mirror of the retriable branch's fenced-vs-fact split just below. Without
+*     `notFoundTtl`, rethrow.
+*   - retriable (`staleIfError`, default `isRetriableHttp`) with a graced `val`
+* still servable at serve time: serve it, `servedOnError: true`. A
+*     `kind:'neg'` graced candidate is NEVER offered here — it is never grace/SIE-
+* served — so a neg-only history rethrows.
+*   - otherwise (non-retriable, or no servable graced copy): rethrow — a failed or
+* timed-out factory never modifies the stored good value.
+*/
+async function classifyFillError(error, config, key, tags, scope, bornEpoch, inval, consistency, options, graced) {
+	if (error instanceof SkipSignalError) return { kind: "skipped" };
+	if (isNotFound(error)) {
+		if (options.notFoundTtl === void 0) throw error;
+		if (graced) {
+			if (await gracedStillServable(inval, consistency, graced.hit.envelope, config.defaults?.onUnavailable, error)) return negSuppressed(config, key, graced);
+			return await negWriteFilled(config, key, tags, scope, bornEpoch, inval, consistency);
+		}
+		return {
+			error,
+			kind: "not-found",
+			neg: await negWriteFilled(config, key, tags, scope, bornEpoch, inval, consistency),
+			scope
+		};
+	}
+	if (options.grace !== void 0 && staleIfErrorOf(config)(error)) {
+		if (graced) {
+			if (await gracedStillServable(inval, consistency, graced.hit.envelope, config.defaults?.onUnavailable, error)) return {
+				kind: "graced",
+				served: graced,
+				value: graced.hit.value
+			};
+			return {
+				error,
+				kind: "fenced"
+			};
+		}
+		return {
+			error,
+			kind: "retriable-failed"
+		};
+	}
+	throw error;
+}
+/**
+* Fill: run the factory, fence the write-back, then born-monotone
+* write-through to L2. Returns `{kind:'filled', value}` on success,
+* `{kind:'fenced'}` when the fill was fenced by a hard purge visible at write-back
+* (never store or serve a fenced value), `{kind:'skipped'}` on
+* `ctx.skip()` (M10/invariant 24), or `{kind:'graced', value}` when the
+* factory threw a retriable error and `graced` — the currently-known
+* stale-but-servable `val` — is STILL servable once re-validated at serve time.
+*`bornEpoch` is captured by the caller at FILL START so a
+* purge that bumps the epoch after the fill began cannot retroactively make the
+* born value look fresh. Error-path handling is `classifyFillError` above.
+*/
+async function fillAndStore(config, options, key, inval, consistency, bornEpoch, graced, ambient) {
+	const codec = codecOf(config);
+	const { l2 } = config;
+	if (!l2) return notImplemented("cache.getOrSet (no l2 configured)", config, options);
+	const declaredUserTags = sortedUserTags(options.tags);
+	const declaredTags = envelopeTags(declaredUserTags, key, config.namespace);
+	const accum = makeTagAccumulator(declaredUserTags);
+	const resolvedScope = resolveScope(options);
+	const scope = resolvedScope.literal;
+	const guard = buildRequestGuard(config, options);
+	const lockHandle = await maybeLock(config, options);
+	const ctx = {
+		dependsOn(tag, dependsOptions) {
+			if (dependsOptions?.l3 === false) notImplemented("FactoryCtx.dependsOn({ l3: false }) — deferred to v0.5", config, options);
+			if (accum.isSettled()) throw new FactorySettledError(key);
+			accum.addMembership(tag);
+			recordDependency(ambient, {
+				scope: fillScopeEvidence(scope),
+				tags: [tag],
+				...dependsOptions?.l3 === void 0 ? {} : { l3: dependsOptions.l3 }
+			});
+		},
+		fail(err) {
+			if (err === void 0) throw new Error("factory failed (non-retriable)");
+			if (err instanceof Error) throw err;
+			throw new Error("factory failed (non-retriable)", { cause: err });
+		},
+		/** Deferred to v0.4 — explicit grace-reuse from within a fill is not part of this phase. */
+		reuseGraced() {
+			return notImplemented("FactoryCtx.reuseGraced (deferred to v0.4)", config, options);
+		},
+		...guard.request === void 0 ? {} : { request: guard.request },
+		setTags(tags) {
+			if (accum.isSettled()) throw new FactorySettledError(key);
+			accum.author(tags);
+		},
+		/** Deferred to v0.4 — the TTL-override (what it overrides, how it meets grace and
+		* the duration grammar) is a v0.4 design slot, not a silent no-op (spec-surface sweep). */
+		setTtl() {
+			notImplemented("FactoryCtx.setTtl (deferred to v0.4)", config, options);
+		},
+		signal: new AbortController().signal,
+		skip() {
+			throw new SkipSignalError();
+		}
+	};
+	try {
+		let value;
+		try {
+			value = await options.factory(ctx);
+		} catch (error) {
+			accum.markSettled();
+			return await classifyFillError(error, config, key, declaredTags, scope, bornEpoch, inval, consistency, options, graced);
+		}
+		accum.markSettled();
+		const userTags = accum.settleUserTags();
+		validateUserTags(userTags);
+		const tags = envelopeTags(userTags, key, config.namespace);
+		if (inval && tags.length > 0 && !inval.fenceWriteBack(tags, bornEpoch)) return { kind: "fenced" };
+		const bornMs = config.clock.now();
+		const encoded = codec.encode(value);
+		const fence = lockHandle?.fence;
+		const envelope = {
+			bornEpoch,
+			bornMs,
+			enc: "json",
+			grace: 0,
+			key,
+			kind: "val",
+			scope,
+			size: encoded.length,
+			src: "factory",
+			storedAt: bornMs,
+			tags,
+			ttl: 0,
+			v: 3,
+			val: value,
+			codecId: codec.id,
+			...fence === void 0 ? {} : { fence }
+		};
+		const written = resolvedScope.l1Only || guard.wasTouched() ? {
+			durable: false,
+			writeSuppressed: false
+		} : await bornMonotoneWrite(config, l2, key, encoded, envelope, inval, consistency);
+		return {
+			bornEpoch,
+			bornMs,
+			durable: written.durable,
+			kind: "filled",
+			storedKind: "val",
+			tags,
+			value,
+			writeSuppressed: written.writeSuppressed
+		};
+	} finally {
+		await lockHandle?.release();
+	}
+}
+/** Write-back attempt budget: fence-taught retries. A fill fenced by a
+* hard purge that landed mid-fill re-mints its `bornEpoch` from the now-advanced verified
+* high-water and refetches, up to this many attempts before failing typed. */
+const WRITE_BACK_ATTEMPT_BUDGET = 3;
+/**
+* `fillAndStore` fronted by the CHECK-THEN-FETCH strong-miss reorder
+* and the fence-taught retry. On a
+* `strong`, registry-backed fill the live un-memoized registry check
+* (`inval.liveCheckForFill`) runs over the fill's tags BEFORE the factory; the fill's
+* `bornEpoch` is raised to the now-current verified high-water, so the born value
+* postdates every purge that check observed — hard OR soft. A strong read
+* therefore never serves a stale-born or hard-dead value, and two strong reads of an
+* unmutated key agree.
+*
+* If the LOCAL write-back fence (`fenceWriteBack`) fences the fill — a hard purge
+* landed DURING the factory and was delivered/verified into local knowledge — the fill
+* RE-MINTS `bornEpoch` from the now-advanced verified high-water (`localBornEpoch`,
+* which a resync or this call's own live check has caught up between attempts, per
+* `#recordChecked`) and REFETCHES: the honest post-acceptance fetch the purge demanded,
+* which borns past it and passes the fence ( observations commission later
+* fetches, they never bless the earlier one). Bounded by the attempt budget; an
+* attempt whose re-mint cannot advance the floor gives up (the fence is not from an
+* observable purge). Exhaustion returns `fenced` — `getOrSet` throws `FencedError`,
+* `getOrSetEntry` misses. `eventual`/registry-absent/tags-empty fills skip
+* the pre-fetch check but share the retry.
+*/
+async function fillAndStoreChecked(config, options, key, inval, consistency, bornEpoch, graced, ambient) {
+	const tags = inval ? envelopeTags(sortedUserTags(options.tags), key, config.namespace) : [];
+	let bornEpochForFill = bornEpoch;
+	if (consistency === "strong" && inval && tags.length > 0) {
+		const checkedThrough = await inval.liveCheckForFill(tags, config.defaults?.onUnavailable);
+		bornEpochForFill = Math.max(bornEpochForFill, checkedThrough);
+	}
+	for (let attempt = 0; attempt < WRITE_BACK_ATTEMPT_BUDGET; attempt++) {
+		const result = await fillAndStore(config, options, key, inval, consistency, bornEpochForFill, graced, ambient);
+		if (result.kind !== "fenced" || !inval || tags.length === 0) return result;
+		const reMinted = Math.max(bornEpochForFill, inval.localBornEpoch());
+		if (reMinted === bornEpochForFill) return result;
+		bornEpochForFill = reMinted;
+	}
+	return { kind: "fenced" };
+}
+/** A fresh, empty singleflight registry for one isolate. */
+function newSingleflight() {
+	return {
+		byIdentity: /* @__PURE__ */ new Map(),
+		byKey: /* @__PURE__ */ new Map()
+	};
+}
+/**
+* The singleflight JOIN IDENTITY ( strict option-compatibility, step
+* the canonical key plus every structurally-relevant option a
+* waiter would otherwise silently miss. Two concurrent calls coalesce onto ONE
+* factory invocation iff their join identities are byte-identical strings.
+*
+*   - `key`: the already-canonicalized (ns-versioned, scoped) key — two calls
+*     for different keys must never coalesce.
+*   - `consistency`: a `strong` request never joins a non-strong (`eventual`)
+*     fill — an eventual waiter MAY join a strong fill (strictly safer), so the
+*     identity is keyed on the REQUESTING call's own consistency, not some
+*     merged value; a `strong` caller's identity differs from an `eventual`
+*     caller's, so they never hash equal and each strong call always runs its
+*     own fill, while two `eventual` calls (or two `strong` calls) still share.
+*   - `apiForm`: `getOrSet` vs `getOrSetEntry` — a plain-`T` waiter must
+*     never join an entry-form fill's ctx (skip-capability differs, M10).
+*   - structural options (GPT note): tags (sorted+deduped, so order never
+*     matters), ttl, grace, scope, notFoundTtl, codec id — a mismatch here means
+*     a waiter could receive an envelope missing its own declared dependency
+*     tags, the exact stringly-typed no-op class this library exists to kill.
+*
+* `dev` mismatch handling (throw vs a separate fill + telemetry event) belongs
+* to a later cluster; this cluster only builds the identity and coalesces
+* exact matches — a mismatch here simply produces a different map key, so it
+* already runs its own separate fill (the safe default) without yet emitting
+* `singleflight_option_mismatch` or dev-throwing.
+*/
+function joinIdentity(key, consistency, apiForm, codec, options) {
+	const userTags = sortedUserTags(options.tags);
+	return JSON.stringify({
+		apiForm,
+		codecId: codec.id,
+		consistency,
+		grace: options.grace ?? null,
+		key,
+		notFoundTtl: options.notFoundTtl ?? null,
+		scope: scopeLiteral(options),
+		tags: userTags,
+		ttl: options.ttl ?? null
+	});
+}
+/** A structural options mismatch between concurrent same-key fills.
+* The message points at the fix (declare compatible options); dev throws it. */
+var SingleflightOptionMismatchError = class extends Error {
+	constructor(userKey) {
+		super(`singleflight option mismatch for key ${JSON.stringify(userKey)}: concurrent calls declared incompatible options (tags/ttl/grace/scope/notFoundTtl/codec). Make the options identical, or serialize the calls.`);
+		this.name = "SingleflightOptionMismatchError";
+	}
+};
+/**
+* Detect + handle a singleflight OPTION MISMATCH: another fill for
+* the SAME canonical key is already in flight under a DIFFERENT join identity.
+* `dev:true` throws (a caller bug surfaced loudly); prod runs a SEPARATE fill and
+* emits `singleflight_option_mismatch` — carrying the colliding key + the
+* declared tags (hosted sinks salt every field, INV-15). A matching-identity
+* joiner never reaches here (it joined in `singleflight` before this ran).
+*/
+function handleOptionMismatch(map, key, identity, config, options) {
+	const identities = map.byKey.get(key);
+	if (identities === void 0) return;
+	let incumbent;
+	for (const [inFlight, record] of identities) if (inFlight !== identity) {
+		incumbent = record;
+		break;
+	}
+	if (incumbent === void 0) return;
+	if (config.dev === true) throw new SingleflightOptionMismatchError(options.key);
+	emitTelemetry(config, {
+		key,
+		tags: incumbent.envelopeTags,
+		type: "singleflight_option_mismatch"
+	});
+}
+/** Track this identity as in flight for its canonical key (mismatch detection),
+* remembering its full stored tag set for a later mismatch event's tag ref. */
+function trackKeyIdentity(map, key, identity, fillEnvelopeTags) {
+	const identities = map.byKey.get(key) ?? /* @__PURE__ */ new Map();
+	const existing = identities.get(identity);
+	if (existing) existing.count += 1;
+	else identities.set(identity, {
+		count: 1,
+		envelopeTags: fillEnvelopeTags
+	});
+	map.byKey.set(key, identities);
+}
+/** Untrack this identity once its fill settles (mismatch detection cleanup). */
+function untrackKeyIdentity(map, key, identity) {
+	const identities = map.byKey.get(key);
+	if (identities === void 0) return;
+	const record = identities.get(identity);
+	if (record !== void 0) {
+		record.count -= 1;
+		if (record.count <= 0) identities.delete(identity);
+	}
+	if (identities.size === 0) map.byKey.delete(key);
+}
+/**
+* Run `fill` under in-isolate singleflight (invariant 5): if a fill with
+* the SAME join identity is already in flight, join it instead of starting a
+* second factory invocation — both callers resolve to the one result. Otherwise,
+* a concurrent fill for the same KEY under a DIFFERENT identity is an OPTION
+* MISMATCH: dev throws, prod runs a separate fill + emits the event
+* (`handleOptionMismatch`). Then register this call's fill and run it.
+*
+* CRITICAL — coalescing under `Promise.all` / same-tick concurrent callers
+* (not just `fc.scheduler` interleavings): the in-flight promise is registered
+* into the map SYNCHRONOUSLY, in the same microtask turn as the identity
+* lookup, with NO `await` between the `byIdentity.get` check and the
+* registration. `fill()` itself is only invoked (and starts doing real async
+* work) after registration. Two callers racing through `Promise.all` each
+* invoke `singleflight` synchronously up to this point; the first to run
+* (JS's single-threaded execution order gives the two `Promise.all` callbacks
+* a well-defined sequential dispatch — there is no `await` before either call
+* reaches here) wins the identity check and registers, so a same-identity
+* second call synchronously observes the first's entry and joins it, while a
+* different-identity second call synchronously observes the mismatch. The entry
+* is removed in a `finally` once the fill settles (success or failure) — a
+* subsequent, non-concurrent call always runs its own fresh fill.
+*/
+async function singleflight(map, key, identity, config, options, fill) {
+	const existing = map.byIdentity.get(identity);
+	if (existing) return await existing;
+	handleOptionMismatch(map, key, identity, config, options);
+	trackKeyIdentity(map, key, identity, envelopeTags(sortedUserTags(options.tags), key, config.namespace));
+	const registration = (async () => {
+		try {
+			return await fill();
+		} finally {
+			map.byIdentity.delete(identity);
+			untrackKeyIdentity(map, key, identity);
+		}
+	})();
+	map.byIdentity.set(identity, registration);
+	return await registration;
+}
+/**
+* Open the mint for one read, snapshotting the `bornEpoch` floor SYNCHRONOUSLY — the writer's
+* applied registry epoch at fill start. Taking it at OPEN is the fence-critical part:
+* a purge that lands via a concurrent bus frame after this call cannot lift the floor, so a fill
+* that BEGAN before a concurrent purge still fences correctly at write-back (INV-9/INV-12).
+* Registry-absent ⇒ 0.
+*/
+function openBornMint(inval) {
+	const floor = inval ? inval.localBornEpoch() : 0;
+	return { stamp: (checkedThrough) => Math.max(floor, checkedThrough) };
+}
+/**
+* What a SERVE can prove about the served value's durability. A serve
+* reports only what ITS OWN evidence supports:
+*
+*   - found in L2 ⇒ `true`. The read itself observed the value in the shared tier, so the claim is
+*     backed by something this turn actually did.
+*   - the STORED scope resolves L1-only (a `usr:` principal) ⇒ `false`. Derived from the identity
+*     the entry was stored under, not from this turn: such an entry is never published to L2, so
+*     the kernel KNOWS it is not durable.
+*   - otherwise ⇒ ABSENT. A `pub`/`ten:` entry found in L1, or a scope the surface did not return
+* readably: the L1 envelope carries no write-back record, and the serve algorithm does
+*     not consult L2 on an L1 hit, and adding a read to populate this field would make an L1 hit
+*     cost what the driver contract forbids. The write-through outcome simply cannot be settled here, and
+*     an unsettled question is reported as such rather than guessed in either direction.
+*
+* Returned as a spread FRAGMENT so absence is STRUCTURAL — the property simply not present, never
+* a sentinel and never an explicit `undefined` (`exactOptionalPropertyTypes` keeps the difference
+* observable to a consumer that compares against `false`).
+*/
+function serveDurability(tier, hit) {
+	if (tier === "l2") return { durable: true };
+	const evidence = hitScopeEvidence(hit);
+	if (evidence.kind === "readable" && storedScopeIsL1Only(evidence.literal)) return { durable: false };
+	return {};
+}
+/**
+* The error-path grace serve: a stored candidate that re-validated as
+* still-servable is served `stale:true` after the fill failed. `graced` (a retriable failure)
+* carries `servedOnError`; `neg-suppressed` (a 404, which is not `staleIfError`) does not.
+*
+* Every field here reports the CANDIDATE — the entry actually being served — rather than the fill
+* that failed: its tier is the tier it was read from, its durability what that tier can prove,
+*its age its own stamp. The earlier shape named `tier:'l2'` and `durable:true` as
+* constants, for a value that may have been found in L1 and never written to a shared tier at all.
+*/
+function gracedServe(attempt, ambient) {
+	const { served } = attempt;
+	recordServedHit(ambient, served.hit);
+	return {
+		...serveDurability(served.tier, served.hit),
+		bornMs: served.hit.envelope.bornMs,
+		skipped: false,
+		stale: true,
+		tier: served.tier,
+		value: attempt.value,
+		...attempt.kind === "graced" ? { servedOnError: true } : {}
+	};
+}
+/**
+* One caller's error-path tail over a SHARED retriable failure: the fill that
+* failed produced no serve of its own (a blind leader), so it handed out the classified error as a
+* FACT. This runs on behalf of a caller against ITS OWN read — a singleflight joiner that read a
+* copy of its own, or the blind leader itself. Each state resolves to exactly what a SOLO caller in
+* that same state resolves to, because a caller's outcome must not depend on which caller happened
+* to win singleflight:
+*
+*   - this caller read a `val` candidate that STILL re-validates as servable now ( a
+*     hard delete during the fill must not resurrect it): serve it `{stale:true, servedOnError}`
+* with THIS candidate's own evidence (tier/durable/age), exactly as a leader's own
+*     graced serve would. `staleCandidate` is already a `ServedCandidate`, so the evidence-riding
+*     machinery is reused unchanged.
+*   - this caller read a candidate that re-validates DEAD: it REFUSES the serve and takes the
+*     classified failure — returned as the FENCED OUTCOME, not thrown, so the wrapper applies the
+*     same per-form mapping the solo path gets for this state (the plain form rethrows the typed
+*     error, the entry form resolves a miss). Throwing here would make an entry-form joiner reject
+*     where an identical solo call resolves a miss.
+*   - this caller read no candidate at all: the classified error is rethrown, exactly as a solo
+* caller with nothing to fall back on rethrows it.
+*
+* A joiner's recourse is thus judged against its OWN read, never the leader's disposition — the
+* leader's blindness is a fact it shares, not a verdict it imposes.
+*/
+async function runOwnErrorTail(config, options, inval, consistency, staleCandidate, error, ambient) {
+	if (options.grace !== void 0 && staleCandidate !== void 0) {
+		if (await gracedStillServable(inval, consistency, staleCandidate.hit.envelope, config.defaults?.onUnavailable, error)) return gracedServe({
+			kind: "graced",
+			served: staleCandidate,
+			value: staleCandidate.hit.value
+		}, ambient);
+		return {
+			durable: false,
+			error,
+			skipped: false,
+			stale: false,
+			tier: "miss"
+		};
+	}
+	throw error;
+}
+/** The read tiers in order: L1 then L2. Absent tiers are skipped. */
+function tiersOf(config) {
+	const tiers = [];
+	if (config.l1) tiers.push([config.l1, "l1"]);
+	if (config.l2) tiers.push([config.l2, "l2"]);
+	return tiers;
+}
+/** Write the freshly-filled value into L1 (write-through) — best-effort. The whole fill
+* outcome rides in, because every field written here belongs to that ONE fill: its `bornEpoch` so
+* both tiers validate identically ( `fallbackBornEpoch` covers the neg-write outcome, which
+* stamps none), its `bornMs` so both tiers report the same age ( birth is an event, and a value
+* has ONE: the stamp is minted at fill and carried here, never re-read off the clock, which would
+* date the L1 copy to the moment the L2 write finished and make one value two ages), and its STORED
+* tag set (settle-union) so the two tiers are tag-coherent: a later L1 hit replays the
+* same purge handles L2 carries.
+*
+* A `kind:'neg'` fill whose write LANDED stores nothing here and EVICTS whatever L1 still holds for
+* the key — two halves of one rule, and neither is sufficient alone. A neg whose write the guard
+* SUPPRESSED does neither: eviction follows the write's fate (see below).
+*
+* It stores nothing because the neg's storage is `writeNegEnvelope`'s single L2 write
+*  — that function is the neg's whole write path, and it deliberately writes one tier. What
+* this write-through would put in L1 is a `kind:'val'`-stamped copy of the neg's placeholder body:
+* an envelope claiming to be a VALUE, holding a value no origin produced. Read back, it would
+* surface that placeholder (the read path's neg rule keys on the stored `kind`, which this write
+* misstates) and, worse, stand as a grace/stale-if-error candidate — precisely what invariant 7 forbids a
+* neg from ever being. Today the default codec cannot encode `undefined` to a decodable body, so
+* such a write lands as an unreadable entry that always misses; that is an accident of one codec,
+* not a guarantee any other owes us.
+*
+* It evicts because L1 may ALREADY hold an OLDER value for this key. A fill runs when the read
+* found nothing servable — and a tier read that a classified transient failure suppressed is
+* a plain MISS over an entry that is still sitting there. Refusing the write alone leaves that
+* entry standing, and it outlives the 404: once the tier reads cleanly again L1 is consulted first
+* (steps 2/4) and answers with the superseded value, in preference to the neg L2 now holds —
+* the origin's not-found reverted by a tier that was merely unreadable for a moment. Deleting ends
+* the turn with L1 holding nothing for the key, so reads fall through to the tier that remembers
+* the 404 and a served neg still reports the tier and durability its one write proves.
+*
+* Whether a neg SHOULD also LIVE in L1 is a storage-policy question the design does not settle — it would
+* change that reported tier and durability — so this evicts rather than storing a neg envelope,
+* closing the mislabel and the resurrection without deciding it.
+*
+* EVICTION FOLLOWS THE WRITE'S FATE. Both halves above are premised on a neg that
+* LANDED: the eviction exists to stop a superseded L1 copy outliving a 404 the durable tier now
+* remembers. A neg the guard suppressed leaves the durable tier remembering no 404 at all — the
+* verdict the suppression rendered is that the val stands — so deleting that val's L1 copy would
+* contradict the verdict on the way out, and cost a refill of a value that is still good. A
+* suppressed write mutates nothing, in either tier. */
+async function hydrateL1(config, codec, key, options, attempt, fallbackBornEpoch) {
+	const { l1 } = config;
+	if (!l1) return;
+	if (attempt.storedKind === "neg") {
+		if (attempt.writeSuppressed) return;
+		try {
+			await l1.delete(key);
+		} catch {}
+		return;
+	}
+	const { bornMs, tags, value } = attempt;
+	const bornEpoch = attempt.bornEpoch ?? fallbackBornEpoch;
+	try {
+		await l1.set(key, codec.encode(value), { metadata: {
+			bornEpoch,
+			bornMs,
+			codecId: codec.id,
+			enc: "json",
+			kind: "val",
+			scope: scopeLiteral(options),
+			tags,
+			v: 3
+		} });
+	} catch {}
+}
+/**
+* The successful foreground fill's serve: record the dependency, hydrate L1, and
+* report the fill's own outcome.
+*
+* This is the one serve that can always answer `durable` (leaves it untouched): it performed
+* the write-back itself and awaited the result, so it reports a real boolean rather than the absent
+* arm the read-path serves need.
+*/
+async function filledServe(config, codec, key, options, scope, attempt, bornEpoch, ambient) {
+	const storedTags = attempt.tags;
+	recordDependency(ambient, {
+		scope: fillScopeEvidence(scope),
+		tags: storedTags
+	});
+	const filled = attempt.value;
+	await hydrateL1(config, codec, key, options, attempt, bornEpoch);
+	return {
+		durable: attempt.durable,
+		bornMs: attempt.bornMs,
+		skipped: false,
+		stale: false,
+		tier: "origin",
+		value: filled
+	};
+}
+/**
+* One caller's error-path neg tail over a SHARED `not_found` fact. The fill
+* read no candidate of its own (a blind leader), so it recorded the fact and handed it out rather
+* than deciding, from a read that saw nothing, what every waiter should be served. This decides
+* DISPOSITION ONLY — it records nothing, because the recording already happened once,
+* inside the fill's window. It runs on behalf of one caller against ITS OWN read (a joiner that read
+* a copy of its own, or the blind leader itself), so that each caller resolves EXACTLY as a SOLO
+* caller in that same state resolves — an outcome must not depend on which caller won singleflight:
+*
+*   - this caller read a `val` candidate that STILL re-validates as servable now: the guard serves
+* that val `{stale:true}` with THIS candidate's own evidence (tier/durable/age), and — a
+*     404 not being `staleIfError` — WITHOUT `servedOnError`, exactly as a solo sighted caller does.
+*     The gate matches the solo path's: this arm is offered only when `grace` was declared (the solo
+*     fill receives its `staleCandidate` only then).
+*   - otherwise (this caller read no candidate, or its own copy re-validated dead): it takes the
+*     RECORDED neg as its outcome, served `{tier:'origin'}` with that write's own evidence — the same
+*     `filled` serve a solo blind caller performs over its own neg-write.
+*
+* A joiner's disposition is thus judged against its OWN read — its read is the existence proof the
+* blind leader lacked — while the fact itself was recorded exactly once, by the fill that found it.
+*/
+async function runOwnNotFoundTail(config, options, inval, consistency, key, staleCandidate, fact, outerBornEpoch, ambient) {
+	if (options.grace !== void 0 && staleCandidate !== void 0 && await gracedStillServable(inval, consistency, staleCandidate.hit.envelope, config.defaults?.onUnavailable, fact.error)) return gracedServe(negSuppressed(config, key, staleCandidate), ambient);
+	return await filledServe(config, codecOf(config), key, options, fact.scope, fact.neg, outerBornEpoch, ambient);
+}
+/**
+* A STALE hit → the SWR path (SWR). The OBSERVABLE contract, independent of `grace`:
+* **this response always serves the stale value with `stale:true`** — never the
+* refreshed/fresh result. A refresh runs synchronously (the full background /
+* `waitUntil` / REFRESH_QUEUE machinery of step 6 stays deferred; a synchronous
+* refresh is a placeholder that produces the same observable serve), and its result
+* is written through for the NEXT read only. It never changes the value THIS call
+* returns, and its failure never propagates to the caller — SWR's promise is a fast
+* stale response.
+*
+* `servedOnError:true` iff the refresh failed RETRIABLY (per `staleIfError`)
+* within a grace window (`grace` declared on the call) AND the stale copy is still
+* servable after serve-time re-validation — the `graced` outcome. A
+* successful refresh, a fenced/non-servable refresh, a suppressed 404 ( a neg
+* never displaces a servable val, and a 404 is not `staleIfError`), and a
+* non-retriable refresh failure all serve the stale value WITHOUT `servedOnError`.
+* `grace` only affects whether the error path yields `servedOnError`, never whether
+* the stale value is served (it always is).
+*/
+async function refreshOrGrace(config, options, key, inval, consistency, tier, hit, bornEpoch) {
+	const codec = codecOf(config);
+	let graced = false;
+	try {
+		const attempt = await fillAndStore(config, options, key, inval, consistency, bornEpoch, {
+			hit,
+			tier
+		});
+		if (attempt.kind === "filled") await hydrateL1(config, codec, key, options, attempt, bornEpoch);
+		graced = attempt.kind === "graced" && options.grace !== void 0;
+	} catch {}
+	return {
+		...serveDurability(tier, hit),
+		bornMs: hit.envelope.bornMs,
+		skipped: false,
+		stale: true,
+		tier,
+		value: hit.value,
+		...graced ? { servedOnError: true } : {}
+	};
+}
+/**
+* The core getOrSet path: L1 → L2 → foreground fill with the fence and
+* Born-monotone write-back. Serves fresh directly; serves a soft-stale value
+* with `stale:true`; refills on miss/dead/unknown. Shared by `getOrSet` (plain) and
+* `getOrSetEntry`.
+*/
+async function runGetOrSet(config, options, inval, nsVersion, apiForm, inFlight, ambient) {
+	const codec = codecOf(config);
+	const scope = scopeLiteral(options);
+	const key = canonicalKey(nsVersion.current, config.namespace, scope, options.key);
+	const consistency = consistencyOf(config, options);
+	const mint = openBornMint(inval);
+	let checkedThrough = 0;
+	let staleCandidate;
+	for (const [store, tier] of tiersOf(config)) {
+		const read = await readTier(store, codec, config, inval, consistency, key);
+		checkedThrough = Math.max(checkedThrough, read.checkedThrough);
+		if (read.hit) {
+			if (read.hit.stale && consistency !== "strong") {
+				recordServedHit(ambient, read.hit);
+				return await refreshOrGrace(config, options, key, inval, consistency, tier, read.hit, mint.stamp(checkedThrough));
+			}
+			if (!read.hit.stale) {
+				recordServedHit(ambient, read.hit);
+				return {
+					...serveDurability(tier, read.hit),
+					bornMs: read.hit.envelope.bornMs,
+					skipped: false,
+					stale: false,
+					tier,
+					value: read.hit.value
+				};
+			}
+		}
+		const candidate = read.hit?.stale === true ? read.hit : read.staleCandidate;
+		if (candidate !== void 0) staleCandidate = {
+			hit: candidate,
+			tier
+		};
+	}
+	const bornEpoch = mint.stamp(checkedThrough);
+	const attempt = await singleflight(inFlight, key, joinIdentity(key, consistency, apiForm, codec, options), config, options, async () => await fillAndStoreChecked(config, options, key, inval, consistency, bornEpoch, options.grace === void 0 ? void 0 : staleCandidate, ambient));
+	if (attempt.kind === "filled") return await filledServe(config, codec, key, options, scope, attempt, bornEpoch, ambient);
+	if (attempt.kind === "graced" || attempt.kind === "neg-suppressed") return gracedServe(attempt, ambient);
+	if (attempt.kind === "retriable-failed") return await runOwnErrorTail(config, options, inval, consistency, staleCandidate, attempt.error, ambient);
+	if (attempt.kind === "not-found") return await runOwnNotFoundTail(config, options, inval, consistency, key, staleCandidate, attempt, bornEpoch, ambient);
+	if (attempt.kind === "skipped") return {
+		durable: false,
+		skipped: true,
+		stale: false,
+		tier: "miss"
+	};
+	return {
+		durable: false,
+		skipped: false,
+		stale: false,
+		tier: "miss",
+		...attempt.error === void 0 ? {} : { error: attempt.error }
+	};
+}
+/** Whether a raw regex-captured unit is a known `DurationUnit`. */
+function isDurationUnit(unit) {
+	return unit !== void 0 && Object.hasOwn(DURATION_UNIT_MS, unit);
+}
+/** Convert a `Duration` to milliseconds. The full `Duration` grammar is
+* deferred; the retention lease and the reader's liveness heartbeat cadence need
+* only a coarse ms value, so this parses the `<number><unit>` shape. */
+function durationMs(duration) {
+	const match = /^(?<value>[0-9]+(?:\.[0-9]+)?|\.[0-9]+)(?<unit>ms|s|m|h|d)$/u.exec(duration);
+	const value = Number(match?.groups?.value ?? "0");
+	const rawUnit = match?.groups?.unit;
+	return value * (isDurationUnit(rawUnit) ? DURATION_UNIT_MS[rawUnit] : 1);
+}
+/** Build the per-instance invalidation core when a registry + bus are wired.
+*Registry-absent instances (codec.test.ts) get `undefined` and keep the
+* always-fresh codec path.
+*
+* A registry+bus instance REQUIRES an L2 replication mirror: the reader's only safe way to
+* clear a bus gap is to resync off the `state`/`delta` mirror there. Constructing
+* it without one is rejected LOUDLY here (dead-branch ruling) — the reader has no
+* honest job with no store. This throw is dead today (a registry+bus config is only ever wired
+* with L2), and it is guarded precisely because that reachability would change silently if L2
+* became optional: the old handling — clearing suspicion without resyncing — was a fail-OPEN
+* hole. Fail loud instead of silently reopening it. */
+function buildInvalidation(config) {
+	const { registry, bus, l2 } = config;
+	if (!registry || !bus) return;
+	if (!l2) throw new Error("createCache: a registry+bus instance requires an l2 store (the §4.2 replication mirror the reader resyncs off — E20)");
+	const emit = (event) => {
+		emitTelemetry(config, event);
+	};
+	const heartbeat = config.defaults?.heartbeatInterval;
+	return new Invalidation(registry, l2, bus, heartbeat === void 0 ? void 0 : durationMs(heartbeat), emit);
+}
+/**
+* A facade → the instance it fronts. THE ONE PLACE an alternate identity for one cache is recorded.
+*
+* WHY THIS EXISTS, AND WHY IT IS ONE MECHANISM RATHER THAN A HABIT. Several internal seams hang
+* per-instance state off a `Cache` through a module-private WeakMap, keyed by the object itself. A
+* composition that returns a WRAPPER around a `createCache` instance — `createWorkersCache` does, to
+* hang its freshness carrier on the read path — hands callers an object those maps have never heard
+* of. The address a seam is keyed by is therefore the identity CALLERS HOLD, and a facade that
+* re-registers one seam and forgets another does not fail loudly: it produces a seam that silently
+* answers `undefined` forever. Registering per-seam is the fix that does not generalize — the next
+* seam, or the next facade, reopens it.
+*
+* So identity is aliased ONCE, here, and every seam lookup resolves through `resolveCacheIdentity`
+* BEFORE keying. A new seam is covered because it resolves like the others; a new facade is covered
+* because it aliases like the others. Neither has to remember the list.
+*/
+const identityAliases = /* @__PURE__ */ new WeakMap();
+/**
+* The instance `cache` stands for — itself, unless it is a facade over another.
+*
+* SAME-PACKAGE internal seam, NOT public API (not re-exported from `index.ts`). Every WeakMap keyed
+* by a `Cache` resolves through this before keying, so a facade and the instance it fronts address
+* ONE slot. A cache that is nobody's facade resolves to itself, which is every raw `createCache`
+* instance and therefore the overwhelmingly common path.
+*
+* ONE STEP IS ENOUGH because `aliasCacheIdentity` flattens the chain at registration.
+*/
+function resolveCacheIdentity(cache) {
+	return identityAliases.get(cache) ?? cache;
+}
+/**
+* Record that `facade` is an alternate identity for `inner` — called ONCE, by whatever
+* composition returns a wrapper, at construction. SAME-PACKAGE internal seam, NOT public API.
+*
+* THE TARGET IS RESOLVED AS IT IS STORED, so a facade over a facade lands on the instance at the
+* bottom rather than on the middle link. That keeps `resolveCacheIdentity` a single lookup on the
+* hot path while making a stack of facades correct BY CONSTRUCTION rather than by anyone noticing
+* that it is a stack — the chain is flattened once, here, where it is built.
+*/
+function aliasCacheIdentity(facade, inner) {
+	identityAliases.set(facade, resolveCacheIdentity(inner));
+}
+/** Cache instance → its replication poller. Module-private internal state: the
+* poller is attached WITHOUT touching the public `Cache` surface. the request-piggyback driver
+* (the RR adapter) is the READER of this map — the seam arrived with its consumer, so the map is no
+* longer write-only and the `sonarjs/no-unused-collection` suppression that carried the named "C4"
+* expiry is DELETED (its premise is gone; a suppression outliving its premise is a lie). */
+const replicationPollers = /* @__PURE__ */ new WeakMap();
+/**
+* The replication poller attached to `cache`, or `undefined` for a registry-absent instance (which
+* has no reader to drive). SAME-PACKAGE internal seam, NOT public API: it is deliberately not
+* re-exported from `index.ts`, and its ONE consumer is the request-piggyback tick driver in the
+* RR adapter (`src/adapters/react-router/poll-driver.ts`), which owns the staleness gate + the
+* failure swallow. Kept as narrow as that consumer needs: a `Cache` in, its poller out — no other
+* kernel internal crosses the boundary.
+*
+* Resolves identity first, so a facade over an instance finds that instance's poller. Without that
+* an RR app on a wrapping factory would lose its replication poll SILENTLY — `tickIfStale` reads a
+* missing poller as "registry-absent, nothing to drive" and returns.
+*/
+function replicationPollerOf(cache) {
+	return replicationPollers.get(resolveCacheIdentity(cache));
+}
+/** A `RenderCollector` → its internal scope-bearing writer. Module-private: the
+* public collector interface cannot carry the scope half (a public `dependsOn` has no entry
+* behind it), so the kernel's automatic hit/fill recording reaches it through this map
+* instead of through a widened public type or a cast. */
+const collectorStates = /* @__PURE__ */ new WeakMap();
+/**
+* An `L3Emission` → how many dependencies the render had consumed when that emission was
+* committed — hits, fills, and explicit `dependsOn` declarations. Same
+* module-private-WeakMap seam as `collectorStates` above, and for a kindred reason: the count is
+* a fact the ADAPTER's header decision needs and no caller of the public type does, and
+* `L3Emission` is a spec-verbatim shape — so the count rides the private channel rather
+* than widening a published surface with a field only this package reads.
+*/
+const emissionCounts = /* @__PURE__ */ new WeakMap();
+/** Bank an emission's consumed-dependency count on the seam and return the emission (the ONE
+* writer of `emissionCounts` — the count is banked with the emission it belongs to, so the two
+* can never drift apart). */
+function withManagedDependencies(emission, count) {
+	emissionCounts.set(emission, count);
+	return emission;
+}
+/**
+* How many dependencies the render had consumed when `emission` was committed.
+* SAME-PACKAGE internal seam, NOT public API: deliberately not re-exported from `index.ts`, and
+* its ONE consumer is the React-Router middleware's header decision, where ZERO is the adapter's
+* JURISDICTION FLOOR — a render that consumed no managed dependency gets a safe DEFAULT and
+* nothing more (`private` filled in only where the app wrote no `Cache-Control`, an app-set
+* `Cache-Tag` left where it is, nothing overridden). It is what separates that floor from an
+* eligible render whose dependencies simply emit no tag.
+*
+* An emission this kernel never minted reads as 0, i.e. as the floor — the direction in which the
+* adapter asserts least, which is the safe one for an unrecognized input.
+*/
+function managedDependenciesOf(emission) {
+	return emissionCounts.get(emission) ?? 0;
+}
+/**
+* A `Cache` → the accessor that yields the AMBIENT render collector for the request in
+* flight. Same module-private-WeakMap seam as `replicationPollers` above, and the
+* same reason: the collector must reach the kernel WITHOUT widening the public `Cache`
+* surface and WITHOUT the kernel importing `node:async_hooks` (the request frame is the
+* adapter's — a Workers deployment without the ALS compat flag must still be able to import
+* this module).
+*
+* Keyed by RESOLVED identity, like every other instance-keyed seam here: an adapter binds against
+* the cache the app holds, and the kernel looks up against the instance running the read. Those are
+* different objects whenever a facade is in play, and this map is where they have to meet — a
+* privacy gate that reads an empty collector concludes the render consumed nothing and asserts
+* nothing, which is the loudest possible silence.
+*/
+const renderCollectors = /* @__PURE__ */ new WeakMap();
+/**
+* Bind the adapter's ambient-collector accessor to `cache`. SAME-PACKAGE internal
+* seam, NOT public API: deliberately not re-exported from `index.ts`, and its ONE consumer is
+* the React-Router middleware (`src/adapters/react-router/middleware.ts`), which owns the
+* `AsyncLocalStorage` request frame the accessor reads.
+*
+* The consequence is the safety property, not a limitation: a cache used WITHOUT the adapter
+* has no bound accessor, so the kernel records nothing, no `commitHeaders` ever runs, and no
+* header is ever emitted. Nothing to leak, by construction — it fails closed.
+*/
+function bindRenderCollector(cache, accessor) {
+	renderCollectors.set(resolveCacheIdentity(cache), accessor);
+}
+/** The ambient collector's internal writer for `cache`, or `undefined` when the adapter bound
+* none / no request frame is open. */
+function ambientCollectorOf(cache) {
+	const collector = renderCollectors.get(resolveCacheIdentity(cache))?.();
+	return collector === void 0 ? void 0 : collectorStates.get(collector);
+}
+/** Build the tick-driven replication poll driver alongside the reader, under the
+* SAME condition (registry+bus+L2, already validated by `buildInvalidation`). It is CONSTRUCTED
+* here — never a knip entry: the construction makes `replication-poller.ts` reachable, so deleting
+* this wiring reds knip, which is the point (the dead-code gate becomes the wiring's tooth). The
+* poller runs no timer of its own; C4 drives it (deterministic ticks drive it in tests). The
+* `maxSyncLag` base cadence defaults to the Workers profile (60s) unless config overrides. */
+function buildReplicationPoller(config, reader) {
+	const { l2, registry } = config;
+	if (!l2 || !registry) throw new Error("createCache: the replication poller requires the same registry+l2 as the reader (§4.2)");
+	const maxSyncLag = config.defaults?.maxSyncLag;
+	const options = maxSyncLag === void 0 ? {} : { pollBaseMs: durationMs(maxSyncLag) };
+	return new ReplicationPoller(reader, l2, mirrorKeys(registry.regId), config.rng, options);
+}
+/**
+* Register this instance's retention lease — DEFERRED TO FIRST USE, best-effort
+* and fire-and-forget; a registration failure never blocks anything (the GC horizon extends under
+* uncertainty).
+*
+* IT USED TO FIRE FROM `createCache`, AND THAT IS AN RPC AT CONSTRUCTION. Construction performs no
+* I/O: at module scope the platform refuses the call outright, and the bare `try{}catch{}` around it
+* — swallowing by design, which is right for a best-effort lease — meant the refusal was invisible.
+* A lease that never registered and never said so is the worst of both: the Coordinator's GC horizon
+* is not extended by an instance it never heard from, and nothing anywhere reports it.
+*
+* Returns a function the first read calls. It runs AT MOST ONCE per instance and never blocks: the
+* lease is a hint to the GC horizon, not a precondition for reading, so making a read wait on it
+* would trade a correctness-neutral registration for real latency on the request that happened to be
+* first.
+*/
+function retentionRegistrar(config) {
+	const { registry } = config;
+	const retention = config.defaults?.maxEntryRetention;
+	if (!registry || retention === void 0) return () => {};
+	let registered = false;
+	return () => {
+		if (registered) return;
+		registered = true;
+		(async () => {
+			try {
+				await registry.registerRetention(durationMs(retention));
+			} catch {}
+		})();
+	};
+}
+/** Resolve a purge selector to its registry tag(s). A key selector maps to
+* the reserved `__k` tag digest of that key's canonical form — the
+* IDENTICAL digest `expire`/`delete` by tag would never see, since the literal
+* `__k` form is internal and only `expire({key})`/`delete({key})` may target
+* it. No `scope` and no request on the key selector ⇒ the same `pub` default
+* a scope-less, contextless `getOrSet` call stamps, so
+* `expire({key: options.key})` targets exactly the tag a matching contextless
+* `getOrSet({key: options.key})` carries. */
+function selectorTags(selector, config, nsVersion) {
+	if ("tag" in selector) return [selector.tag];
+	return [keyTag(canonicalKey(nsVersion.current, config.namespace, scopeLiteral(), selector.key))];
+}
+/** Wrap a registry ack into a `PurgeResult`. `flushed`/`edgePurged`
+* resolve minimally here — the registry mutation already durably accepted + emitted
+* the __delta/__state batch (steps 1–3); the KV-acceptance handoff and CDN
+* drain (step 4) are deferred to a later cluster. */
+function purgeResult(ack) {
+	return {
+		edgePurged: async () => {
+			await Promise.resolve();
+		},
+		epoch: ack.epoch,
+		flushed: async () => {
+			await Promise.resolve();
+		},
+		matchedHint: "unknown"
+	};
+}
+/**
+* Build a cache instance. Wires the dual-epoch invalidation core when a
+* registry + bus are present; otherwise runs the registry-absent codec path.
+* Not-yet-implemented verbs still throw `NotImplementedError`.
+*
+* CONSTRUCTION PERFORMS NO I/O. What happens here is bookkeeping over the arguments —
+* addresses are recorded, components are pointed at each other, and no door is opened. Every
+* deferred piece (the bus subscription via `Invalidation`'s lazy dial; the retention lease via
+* `registerRetention` below) waits for the first read that needs it and runs inside that read's
+* request context. This is what makes one cache per isolate, built at module scope, a legal and
+* expected shape rather than an isolate that refuses to start.
+*/
+function createCache(config) {
+	const inval = buildInvalidation(config);
+	const poller = inval === void 0 ? void 0 : buildReplicationPoller(config, inval);
+	/** The lease, armed but NOT fired — the first read pays it, and only the first. */
+	const registerRetention = retentionRegistrar(config);
+	const nsVersion = new NsVersion();
+	const inFlight = newSingleflight();
+	const ambientCell = { lookup() {} };
+	const ambient = () => ambientCell.lookup();
+	const instance = {
+		async clear() {
+			const { registry } = config;
+			if (!registry) return notImplemented("cache.clear (no registry configured)", config);
+			inval?.ensureSubscribed();
+			nsVersion.bump();
+			return purgeResult(await registry.delete([nsTag(config.namespace)]));
+		},
+		collect() {
+			const required = [];
+			let committed = false;
+			let lateTag = false;
+			let managedDependencies = 0;
+			let poisoned = false;
+			let scopeUnreadable = false;
+			const records = [];
+			const state = {
+				get records() {
+					return records;
+				},
+				record(dependency) {
+					records.push(dependency);
+					const { l3, scope, tags } = dependency;
+					managedDependencies += 1;
+					if (scope.kind === "unreadable") {
+						scopeUnreadable = true;
+						poisoned = true;
+					} else if (scope.kind === "readable" && scope.literal !== PUBLIC_SCOPE) poisoned = true;
+					if (l3 === false) return;
+					if (committed) {
+						lateTag = true;
+						return;
+					}
+					required.push(...tags);
+				}
+			};
+			const collector = {
+				commitHeaders(budget) {
+					const cacheTags = required.filter((tag) => !isReservedTag(tag));
+					committed = true;
+					if (poisoned) return withManagedDependencies({
+						cacheTags: [],
+						eligible: false,
+						ineligibleReason: scopeUnreadable ? "scope-unreadable" : "scope"
+					}, managedDependencies);
+					if (lateTag) return withManagedDependencies({
+						cacheTags,
+						eligible: false,
+						ineligibleReason: "late-tag"
+					}, managedDependencies);
+					const maxTags = budget?.maxTags;
+					if (maxTags !== void 0 && cacheTags.length > maxTags) return withManagedDependencies({
+						cacheTags,
+						eligible: false,
+						ineligibleReason: "budget"
+					}, managedDependencies);
+					const maxBytes = budget?.maxBytes;
+					if (maxBytes !== void 0) {
+						if (new TextEncoder().encode(cacheTags.join(",")).length > maxBytes) return withManagedDependencies({
+							cacheTags,
+							eligible: false,
+							ineligibleReason: "budget"
+						}, managedDependencies);
+					}
+					return withManagedDependencies({
+						cacheTags,
+						eligible: true
+					}, managedDependencies);
+				},
+				dependsOn(tag, dependsOptions) {
+					state.record({
+						scope: { kind: "none" },
+						tags: [tag],
+						...dependsOptions?.l3 === void 0 ? {} : { l3: dependsOptions.l3 }
+					});
+				}
+			};
+			collectorStates.set(collector, state);
+			return collector;
+		},
+		async delete(selector) {
+			const { registry } = config;
+			if (!registry) return notImplemented("cache.delete (no registry configured)", selector);
+			inval?.ensureSubscribed();
+			return purgeResult(await registry.delete(selectorTags(selector, config, nsVersion)));
+		},
+		/** Deferred to v0.4 — namespace-wide hard purge behind the origin-load guard. */
+		async deleteAll(guard) {
+			return notImplemented("cache.deleteAll (deferred to v0.4)", config, guard);
+		},
+		async expire(selector) {
+			const { registry } = config;
+			if (!registry) return notImplemented("cache.expire (no registry configured)", selector);
+			inval?.ensureSubscribed();
+			return purgeResult(await registry.expire(selectorTags(selector, config, nsVersion)));
+		},
+		/** Deferred to v0.4 — namespace-wide soft purge behind the origin-load guard. */
+		async expireAll(guard) {
+			return notImplemented("cache.expireAll (deferred to v0.4)", config, guard);
+		},
+		/**
+		* Witness a key's state — introspection, not testimony: every field is drawn from
+		* an ALREADY-KNOWN source, and nothing here mutates state. The tier is a NON-mutating presence
+		* probe (`store.get`, never `hydrateL1` ); the verdict is a pure classify over the
+		* reader's CURRENT knowledge (no live check, no resync ); the reader state is exposed
+		* via read-only accessors; the request attribution is the bound render collector's
+		* request-scoped records. The key is canonicalized at the DEFAULT (`pub`) scope — the
+		* signature carries no scope, so `explain` introspects the default-scoped entry for that key.
+		*/
+		async explain(key) {
+			const codec = codecOf(config);
+			const canonical = canonicalKey(nsVersion.current, config.namespace, scopeLiteral(), key);
+			const reader = {
+				appliedEpoch: inval?.appliedEpoch ?? 0,
+				channel: inval?.channel ?? "never-established",
+				suspect: inval?.suspect ?? false,
+				terminal: poller?.terminal ?? false
+			};
+			const requestDependencies = explainAttribution(ambient);
+			const attribution = requestDependencies === void 0 ? {} : { requestDependencies };
+			let readFailed = false;
+			for (const [store, tier] of tiersOf(config)) {
+				const probed = await probeStoredEntry(store, codec, config, canonical);
+				if (probed.kind !== "found") {
+					readFailed ||= probed.kind === READ_FAILED_KIND;
+					continue;
+				}
+				return {
+					identity: {
+						bornEpoch: probed.envelope.bornEpoch,
+						kind: probed.envelope.kind,
+						scope: probed.scope,
+						tags: probed.envelope.tags,
+						ttl: probed.ttl
+					},
+					key,
+					kind: "present",
+					reader,
+					tier,
+					verdict: inval ? inval.explainVerdict(probed.envelope) : FRESH_VERDICT,
+					...attribution
+				};
+			}
+			if (readFailed) return {
+				key,
+				kind: READ_FAILED_KIND,
+				reader,
+				...attribution
+			};
+			return {
+				key,
+				kind: "absent",
+				reader,
+				tier: "miss",
+				...attribution
+			};
+		},
+		async getOrSet(options) {
+			registerRetention();
+			inval?.ensureSubscribed();
+			const outcome = await runGetOrSet(config, options, inval, nsVersion, "getOrSet", inFlight, ambient);
+			if (outcome.value === void 0 && outcome.tier === "miss") {
+				if (outcome.error !== void 0) throw outcome.error;
+				throw new FencedError(options.key);
+			}
+			return outcome.value;
+		},
+		async getOrSetEntry(options) {
+			registerRetention();
+			inval?.ensureSubscribed();
+			const outcome = await runGetOrSet(config, options, inval, nsVersion, "getOrSetEntry", inFlight, ambient);
+			return {
+				age: outcome.bornMs === void 0 ? 0 : Math.max(0, config.clock.now() - outcome.bornMs),
+				...outcome.durable === void 0 ? {} : { durable: outcome.durable },
+				skipped: outcome.skipped,
+				stale: outcome.stale,
+				tier: outcome.tier,
+				value: outcome.value,
+				...outcome.servedOnError === void 0 ? {} : { servedOnError: outcome.servedOnError }
+			};
+		}
+	};
+	ambientCell.lookup = () => ambientCollectorOf(instance);
+	if (poller !== void 0) replicationPollers.set(instance, poller);
+	return instance;
+}
+//#endregion
+export { UnknownTagError as A, FactorySettledError as C, InvalidTagError as D, InvalidDurationError as E, NotImplementedError as O, CacheTimeoutError as S, HttpError as T, t as _, replicationPollerOf as a, isRegId as b, isRetriableHttp as c, memory as d, readFrame as f, globalTag as g, compound as h, managedDependenciesOf as i, RegistryUnavailableError as k, duration as l, safeEmit as m, bindRenderCollector as n, resolveCacheIdentity as o, TELEMETRY_EVENTS as p, createCache as r, httpError as s, aliasCacheIdentity as t, isStoreWriteError as u, DEFAULT_REG_ID as v, FencedError as w, mirrorKeys as x, assertRegId as y };