@astilba/cache 0.0.0-placeholder.0 → 0.1.0

package/dist/cache-YWn0VZpn.d.ts

@@ -0,0 +1,930 @@
+//#region src/knowledge.d.ts
+/** Public consistency levels. `local` was deleted from the public union (M6). */
+type Consistency = "strong" | "eventual";
+/**
+ * Dual watermark epochs for a tag — independent, monotone, max-on-write. A
+ * later soft purge can never regress a hard purge (invariant 14).
+ */
+interface Watermark {
+  readonly softEpoch: number;
+  readonly hardEpoch: number;
+}
+/**
+ * Tri-state tag knowledge. Either `known` (with epoch provenance) or
+ * absent = `unknown`. An absent record is `unknown`, never `{0,0}`. `unknown`
+ * fails closed: never fresh, never grace (invariant 11) — a gap of unknown
+ * hardness may hide a hard purge.
+ */
+type TagKnowledge = {
+  readonly known: true;
+  readonly softEpoch: number;
+  readonly hardEpoch: number;
+  readonly throughEpoch: number;
+} | {
+  readonly known: false;
+};
+/** The outcome of validating an entry against tag knowledge (table). */
+type Validity = "fresh" | "stale" | "dead" | "unknown";
+//#endregion
+//#region src/telemetry.d.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.
+ */
+declare const TELEMETRY_EVENTS: {
+  readonly writeback_throttled: "writeback_throttled";
+  readonly l2_write_error: "l2_write_error";
+  readonly singleflight_option_mismatch: "singleflight_option_mismatch";
+  readonly store_read_suppressed: "store_read_suppressed";
+  readonly neg_suppressed: "neg_suppressed";
+  readonly private_evicted: "private_evicted";
+  readonly poll_tick_failed: "poll_tick_failed";
+  readonly l3_ineligible: "l3_ineligible";
+  readonly regid_divergence: "regid_divergence";
+  readonly bus_dial_failed: "bus_dial_failed";
+  readonly strong_degraded: "strong_degraded";
+  readonly registry_degraded: "registry_degraded";
+  readonly state_stale: "state_stale";
+};
+/** The closed vocabulary of telemetry event names. `TelemetryEvent.type` is this
+ * union, and `safeEmit` accepts only members of it — an off-catalog emit is a COMPILE error. */
+type TelemetryEventName = (typeof TELEMETRY_EVENTS)[keyof typeof TELEMETRY_EVENTS];
+/**
+ * The reason CLASS a `strong_degraded` payload reports — why a strong read could not
+ * live-check and served under eventual's posture instead. A CLASS, never the error's own words: the
+ * registry's failure text is arbitrary app/platform detail (it can carry a URL, an id, a stack), and
+ * this event's whole job is to be safe to point a plain sink at. `registry_unreachable` is the only
+ * member today; it is a union rather than a bare literal so a second cause arrives as a widened
+ * payload the sink already types against, not as a new event name.
+ */
+type StrongDegradedReason = "registry_unreachable";
+/**
+ * A telemetry event. `type` is a CATALOG member; additional fields are
+ * event-specific. Hosted sinks pseudonymize all string fields (invariant 15). The `type`
+ * narrowing from a bare `string` is consumer-safe by variance: a sink is a RECEIVER, so an app
+ * typed against the older `string` still accepts every catalog member.
+ */
+interface TelemetryEvent {
+  readonly type: TelemetryEventName;
+  readonly [field: string]: unknown;
+}
+/** A telemetry sink (`telemetry`). Receives events as they are emitted. */
+type TelemetrySink = (event: TelemetryEvent) => void;
+/**
+ * The hook `safeEmit` calls when it SWALLOWS an app-supplied sink's failure. It is
+ * INJECTABLE — passed in at the emit site, never a module global — so "observed exactly once" is
+ * testable with no module-latch order-coupling: two instances each carry their own hook and never
+ * cross-talk. It receives the swallowed error, and is itself the LAST link in the swallow chain, so
+ * if it throws that too is swallowed (safeEmit's never-throws contract is total).
+ */
+type SinkErrorHook = (error: unknown) => void;
+/**
+ * Hosted telemetry configuration. When `hosted` is set, the kernel pseudonymizes every
+ * emitted string field before delivery — key/tag references become per-project HMAC-salted hashes
+ * (never raw), and `detail` becomes error codes + hashed refs. `salt` is the per-project HMAC salt
+ * that keeps short or guessable identifiers from being reversed out of the hash. `onSinkError` (see
+ * `SinkErrorHook`) is the injectable broken-sink hook `safeEmit` calls on a swallowed sink failure.
+ * Invariant 15.
+ */
+interface TelemetryConfig {
+  readonly sink: TelemetrySink;
+  readonly hosted?: boolean;
+  readonly salt?: string;
+  readonly onSinkError?: SinkErrorHook;
+}
+//#endregion
+//#region src/drivers.d.ts
+/** Injected logical clock — the ONLY source of `now` in kernel code. */
+interface Clock {
+  /** Milliseconds on the logical timeline. Never a wall clock in the correctness path. */
+  now(): number;
+}
+/** Injected deterministic RNG — the ONLY source of randomness in kernel code. */
+interface Rng {
+  /** A float in [0, 1). Seeded and reproducible. */
+  next(): number;
+}
+type StoreMetadata = Readonly<Record<string, unknown>>;
+/** A value read from / written to a KV-like store. */
+interface StoreValue {
+  readonly value: string;
+  readonly metadata?: StoreMetadata;
+}
+interface StoreWriteOptions {
+  /** Physical residency in seconds (KV floors this at 60s). */
+  readonly expirationTtl?: number;
+  readonly metadata?: StoreMetadata;
+}
+/**
+ * Which immutable mirror object a WRITE carries. The executor passes it to
+ * `putImmutable` so a host maps kind → physical residency, NEVER by parsing the (coped) key —
+ * the fourth-class "key edition" 2b-2-0 cured. The single home for the mirror-object taxonomy;
+ * `@astilba/cache/registry` re-exports it.
+ */
+type ImmutableKind = "delta" | "snap";
+/**
+ * The mirror-object intent a READ carries — the write taxonomy PLUS the mutable `pointer`
+ * (`__state`). `Store.get`'s optional hint, symmetric with `putImmutable`: intent travels as a
+ * PARAMETER so a driver maps kind → read-cache policy, never by parsing the key. One vocabulary for
+ * mirror-object intent in both directions.
+ */
+type ReadKind = "pointer" | ImmutableKind;
+/**
+ * A KV-like tier driver. `memory` (L1, isolate-local) and `cloudflareKV` /
+ * `redis` (L2, durable) implement it. The harness `FakeStore` models N replica
+ * views with per-key visibility delay, per-key write throttle (1 write/s → 429),
+ * TTL, and injectable get/set failures; a single-view `FakeStore` is the
+ * strongly-consistent Redis stand-in.
+ */
+interface Store {
+  /** `readKind` is an optional read-cache hint: a driver may map it to a
+   * per-object read-cache policy (the DO KV `cacheTtl`). Unhinted reads inherit the platform
+   * default — for L2 KV that is a 60s edge cache, NOT minimal caching (Appendix C trap), so mirror
+   * reads pass the hint and entry reads stay allowed eventual. Fakes ignore or record it. */
+  get(key: string, readKind?: ReadKind): Promise<StoreValue | undefined>;
+  set(key: string, value: string, options?: StoreWriteOptions): Promise<void>;
+  delete(key: string): Promise<void>;
+}
+/**
+ * The structural failure contract a `Store` driver raises to the kernel on a rejected
+ * write. It is a plain SHAPE, never a class: the kernel discriminates on
+ * `code` alone (`isStoreWriteError`) so a fake's throttle error and a real driver's
+ * classified rejection speak ONE contract WITHOUT sharing a class — cross-realm and
+ * cross-package `instanceof` identity is exactly the trap that makes a shared error
+ * class unshippable. The kernel absorbs a classified write failure into an outcome +
+ * telemetry; a caller never sees the raw rejection.
+ *
+ *   - `throttled` — the write hit the tier's per-key write-rate ceiling (KV's
+ *                     1 write/s/key). Transient: `retryable` is true.
+ *   - `too_large` — the value exceeds the tier's max value size (KV's 25 MiB
+ * ceiling). Typed and rejected, NEVER truncated; not retryable.
+ *   - `unavailable` — a transient tier failure (the durable store was momentarily
+ * unreachable).
+ */
+interface StoreWriteError {
+  readonly code: "throttled" | "too_large" | "unavailable";
+  readonly retryable: boolean;
+  readonly cause?: unknown;
+}
+/**
+ * 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.
+ */
+declare function isStoreWriteError(e: unknown): e is StoreWriteError;
+/**
+ * Ordering key an atomic compare-and-set must never regress: epoch first,
+ * then fence. A born-monotone write-back is arbitrated on exactly this pair (INV-17).
+ */
+interface CasOrder {
+  readonly epoch: number;
+  readonly fence: number;
+}
+/** A versioned CAS slot: `token` is the optimistic-concurrency version. */
+interface CasRecord {
+  readonly token: number;
+  readonly order: CasOrder;
+}
+/**
+ * The atomic compare-and-set a CAS-capable durable driver (Redis Lua, DO
+ * transactional storage) layers ON TOP OF the base `Store`. An OPTIONAL
+ * capability: the base `Store` — and the v0.1 fakes — expose none, so the kernel's
+ * floor stays read-compare-write (INV-17) and prefer-CAS consumption is deferred to
+ * the first real CAS driver. Declared here so the conformance layer can pin the
+ * capability and a real driver can later satisfy the same shape.
+ */
+interface CasStore {
+  seed(key: string, order: CasOrder): Promise<void>;
+  load(key: string): Promise<CasRecord | undefined>;
+  /** Apply `next` iff the stored token still equals `expectedToken`; else a lost race. */
+  swap(key: string, expectedToken: number, next: CasOrder): Promise<number | undefined>;
+}
+/** Acknowledgement of a durably-accepted registry mutation. */
+interface RegistryAck {
+  /** The Coordinator epoch after applying this mutation. */
+  readonly epoch: number;
+}
+/**
+ * The authoritative registry / Coordinator. Holds dual watermark
+ * epochs per tag (monotone, max-on-write) and a persisted monotone epoch counter.
+ * `check` is the live, un-memoized strong read used by strong reads and the
+ * write-back fence. `doRegistry` / `redisRegistry` implement it in phase 2;
+ * the harness `FakeRegistry` is the fake.
+ */
+interface Registry {
+  /** The registry id scoping this Coordinator's mirror keyspace. The per-isolate
+   * reader scopes the keys it resyncs off to this value AND asserts the pointer payload echoes
+   * it — a mismatch reads an empty keyspace and fails closed. `doRegistry`/`FakeRegistry`
+   * default it to `"default"`; the authoring channel is `configure` (env `REGISTRY_ID`). */
+  readonly regId: string;
+  /** Live watermark knowledge for these tags. */
+  check(tags: readonly string[]): Promise<readonly TagKnowledge[]>;
+  /** Soft purge: max-on-write bump of `softEpoch`. */
+  expire(tags: readonly string[]): Promise<RegistryAck>;
+  /** Hard purge: max-on-write bump of `hardEpoch`. */
+  delete(tags: readonly string[]): Promise<RegistryAck>;
+  /** Register this instance's retention lease at bind. */
+  registerRetention(retentionMs: number): Promise<void>;
+}
+/** One tag's watermark change within a replication frame. */
+interface TagChange {
+  readonly tag: string;
+  readonly softEpoch?: number;
+  readonly hardEpoch?: number;
+}
+/** A bus frame carrying a contiguous epoch range of changes. */
+interface BusFrame {
+  readonly fromEpoch: number;
+  readonly toEpoch: number;
+  readonly changes: readonly TagChange[];
+}
+/**
+ * One event delivered to a bus subscriber. The transport hands the
+ * subscriber one of these discriminated shapes; epoch contiguity is validated by the
+ * KERNEL, never asserted by the bus (bus transports, it does not vouch):
+ *
+ *   - `frame`: a replication frame carrying its own `{fromEpoch,toEpoch}` range.
+ *   - `gap`: a frame was dropped or lost in transit — the subscriber must treat its
+ * knowledge as suspect and resync before warm trust resumes. Carries `head`:
+ *a lower bound ≥ the `toEpoch` of every frame emitted before the
+ *              signal, so the loss-revealing event ITSELF declares the head the reader must
+ *              reach to account for what it missed (detection carries its own remedy).
+ *   - `reset`: the transport was (re)established — emitted BEFORE any frame on every
+ * establishment; it suspends all warm trust until a resync
+ * handshake reconciles the subscriber's applied epoch.
+ *   - `hello`: the live channel declares its current head epoch — emitted right AFTER
+ *              `reset` on every establishment, before any frame. Convergence
+ *              anchors to a head DECLARED (`hello`/`gap`/a non-contiguous frame's `toEpoch`),
+ *              never to pointer freshness; an idle channel's `hello` head equals the applied
+ *              epoch, so a caught-up subscriber reconverges at once.
+ *   - `lost`: the transport is DOWN — a dial that did not come up, or an established socket
+ * that closed. It is the counterpart of `reset`, and it exists because its
+ *              absence is unreadable: with only `reset`/`hello` on the wire, a channel that never
+ *              connected and a healthy channel with nothing to say produce the SAME stream —
+ *              none. A subscriber cannot distinguish silence-because-quiet from
+ *              silence-because-dead by waiting longer, so the transport declares it instead.
+ *              It carries no epoch: a channel that is down declares nothing ABOUT epochs, and a
+ *              `head` here would be a number invented by the thing that just failed. It does NOT
+ *              raise suspicion — the suspicion gate owns that posture and a down channel is not a gapped map
+ *              (a never-established reader is DECLARED degraded, which is a different, honest
+ *              state); it is tracked and surfaced, and what holds the reader correct in the
+ *              meantime is the polling driver plus its refusal to guess at a tag it cannot
+ *              establish.
+ */
+type BusEvent = {
+  readonly kind: "frame";
+  readonly frame: BusFrame;
+} | {
+  readonly kind: "gap";
+  readonly head: number;
+} | {
+  readonly kind: "reset";
+} | {
+  readonly kind: "hello";
+  readonly head: number;
+} | {
+  readonly kind: "lost";
+};
+interface Subscription {
+  close(): void;
+}
+/**
+ * Cross-instance invalidation bus. A subscriber consumes a `BusEvent`
+ * stream — frames plus the out-of-band `gap`/`reset` signals — and the KERNEL, not
+ * the bus, asserts frame contiguity and forces a resync on any gap or reset.
+ * `doBus` / `redisBus` implement it in phase 2; the harness `FakeBus` models drop,
+ * delay, reorder, and disconnect/reconnect over this same union.
+ */
+interface Bus {
+  subscribe(onEvent: (event: BusEvent) => void): Subscription;
+}
+/** CDN purge acceptance modes for `delete`. */
+type CdnMode = "enqueue" | "await" | "block";
+/**
+ * CDN / L3 purge driver. Its own persisted drain queue with its own
+ * alarm; acceptance surfaces via `edgePurged()`. `cloudflarePurge`
+ * implements it in phase 2.
+ */
+interface Cdn {
+  purge(tags: readonly string[], mode: CdnMode): Promise<void>;
+}
+/**
+ * A pluggable value codec. `id` is the codec name + wire version — the
+ * `Envelope.codecId` source of truth. A decode failure or an `id` mismatch
+ * (not in `acceptCodecs`) fails closed to a miss (invariants 8, 27).
+ */
+interface Codec {
+  readonly id: string;
+  encode(value: unknown): string;
+  decode(value: string): unknown;
+}
+/** A held cross-isolate lock carrying a monotonic fencing token. */
+interface LockHandle {
+  /**
+   * Monotonic fencing token — the tie-breaker used above an equal `bornEpoch`
+   * and always above `bornMs`; a locked fill carries it into `Envelope.fence`.
+   */
+  readonly fence: number;
+  release(): Promise<void>;
+}
+/**
+ * Opt-in cross-isolate lock — DO or Redis primary only. Grants mutual
+ * exclusion plus a monotonic fencing token; the born-monotone write-back rule
+ * is what bounds a stale lease-holder's late write. `doRegistry` /
+ * `redis` back it in phase 2; the harness `FakeLock` is the fake.
+ */
+interface Lock {
+  acquire(key: string): Promise<LockHandle>;
+}
+/**
+ * L1 driver options. The `clock` is OPTIONAL: a clock-less `memory({ maxEntries,
+ * maxBytes })` stays valid (the quickstart form) and compliant with the no-ambient-time rule — the kernel
+ * passes no `expirationTtl` to L1 today, so residency is production-inert there. A
+ * clock-PRESENT `memory({ clock, … })` honors `expirationTtl` (TTL residency); a set that
+ * carries `expirationTtl` with no injected clock fails loud rather than silently ignore it.
+ *
+ * `telemetry` is the OPTIONAL private-eviction disclosure channel: when a PRIVATE (`usr:`-scoped) entry is
+ * evicted from the LRU under memory pressure, a `private_evicted` event is emitted through it
+ * (payload: reason class + counts + bytes ONLY, never a key/hash/tag — payload discipline). It
+ * is guarded by `safeEmit`, so a throwing/rejecting sink is swallowed and `onSinkError` notified.
+ */
+interface MemoryOptions {
+  /** Injected logical clock — the ONLY `now` source; required to honor `expirationTtl`. */
+  readonly clock?: Clock;
+  readonly maxEntries?: number;
+  readonly maxBytes?: number;
+  /** Private-eviction disclosure sink. Optional; off by default. */
+  readonly telemetry?: TelemetrySink;
+  /** Injectable broken-sink hook `safeEmit` calls when it swallows a `telemetry` failure. */
+  readonly onSinkError?: SinkErrorHook;
+}
+/**
+ * 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.
+ */
+declare function memory(options?: MemoryOptions): Store;
+//#endregion
+//#region src/duration.d.ts
+/** Duration units. `m` = minutes (no month unit). */
+type DurationUnit = "ms" | "s" | "m" | "h" | "d";
+/** A duration literal, e.g. `'5m'`, `'1.5h'`, `'250ms'`. */
+type Duration = `${number}${DurationUnit}`;
+/**
+ * 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.
+ */
+declare function duration(value: number, unit: DurationUnit): Duration;
+//#endregion
+//#region src/envelope.d.ts
+/** `val` = a cached value; `neg` = a remembered 404 (hard-expire only). */
+type EnvelopeKind = "val" | "neg";
+/** Wire container of the stored bytes. `codecId` is the codec identity. */
+type EnvelopeEnc = "json" | "json+gz" | "bin";
+/**
+ * The stored entry (schema version 3). `bornEpoch` is the invalidation clock;
+ * `bornMs` is TTL/grace/GC/age arithmetic ONLY and is never an arbiter.
+ *`tags` are sorted, deduped, and include `__k:<h>` and `__ns:<name>`.
+ */
+interface Envelope<T = unknown> {
+  readonly v: 3;
+  /** `<ns-version>:<ns>:<scope>:<user-key>`. */
+  readonly key: string;
+  readonly val: T;
+  /** Writer's applied registry epoch at FILL START — the invalidation clock. */
+  readonly bornEpoch: number;
+  /** Wall time at fill start — TTL/grace/GC/age arithmetic only; never an arbiter. */
+  readonly bornMs: number;
+  /** Observability only. */
+  readonly storedAt: number;
+  readonly ttl: number;
+  readonly grace: number;
+  /** Sorted, deduped; includes `__k:<h>` and `__ns:<name>`. */
+  readonly tags: readonly string[];
+  /** `'pub' | 'usr:<h>' | 'ten:<h>'`. */
+  readonly scope: string;
+  readonly src: string;
+  readonly kind: EnvelopeKind;
+  readonly enc: EnvelopeEnc;
+  readonly size: number;
+  /** Codec name + wire version; decode fails closed on mismatch. */
+  readonly codecId: string;
+  /** Lock fencing token, carried by locked fills; an arbiter above `bornMs`. */
+  readonly fence?: number;
+}
+//#endregion
+//#region src/invalidation.d.ts
+/**
+ * The live channel's state, as the reader has observed it. A LOCAL FACT — three states,
+ * because two would hide the one that matters:
+ *
+ *   - `never-established` — no `hello` has ever arrived on any socket. The reader has NEVER had a
+ *     live channel, so it runs degraded and SAYS so: what keeps it correct meanwhile is the poll
+ *     carrier plus failing closed on any unknown tag, and each of those checks teaches the map
+ * something it keeps. This is NOT suspicion — the suspect flag is for a map that
+ *     knows it MISSED something; a reader that never connected has missed nothing, because it never
+ *     had a channel to miss anything on. Conflating them
+ *     would either make every cold boot look gapped or make a dead bus look healthy; it is its own
+ *     state precisely so it can be neither.
+ *   - `established` — a `hello` arrived and the socket is up.
+ *   - `lost` — a socket that HAD established is now down. Distinguished from `never-established`
+ *     because the two have different remedies and different histories: one has knowledge to resync
+ *     against a head it once heard, the other has never heard one.
+ */
+type ChannelState = "never-established" | "established" | "lost";
+//#endregion
+//#region src/tags.d.ts
+/**
+ * A validated cache tag. Produced ONLY by `t`, `compound`, or `globalTag`; a raw
+ * string is never assignable to `Tag`. This nominal brand is how the library kills
+ * stringly-typed tags (the failure class it exists to prevent).
+ */
+type Tag = string & {
+  readonly "astilba.tag": true;
+};
+/** A positional argument to `compound()` / an interpolation in `t`. */
+type TagPart = string | number;
+/**
+ * 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`.
+ */
+declare function t(strings: TemplateStringsArray, ...values: readonly TagPart[]): Tag;
+/**
+ * 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.
+ */
+declare function compound(...parts: readonly TagPart[]): Tag;
+/**
+ * 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.
+ */
+declare function globalTag(name: string): Tag;
+//#endregion
+//#region src/cache.d.ts
+/**
+ * A scope claim. `'public'` is an enforced shared-tier claim; `{tenant}` is
+ * tenant scoping. Omitting `scope` is private-by-default (principal-derived,
+ * `usr:` ⇒ L1-only).
+ */
+type Scope = "public" | {
+  readonly tenant: string;
+};
+/** The tier an entry was served from (`tier`). */
+type Tier = "l1" | "l1.5" | "l2" | "origin" | "miss";
+/** How fail-closed `unknown` resolves (adds `'error'`). */
+type UnknownPolicy = "registry-check" | "miss" | "error";
+/** Envelope provenance exposed to a factory for the graced value. */
+interface GracedInfo {
+  readonly value: unknown;
+  readonly src: string;
+  readonly v: number;
+  readonly bornMs: number;
+}
+/**
+ * An adapter-provided request object. In a public-scoped factory dev mode
+ * wraps it in a Proxy for the frame, so any property read demotes the entry off the
+ * shared tier (closures over raw request state are the boundary invariant 4 names).
+ */
+type RequestContext = Readonly<Record<string, unknown>>;
+/**
+ * The factory context for `getOrSet`. Deliberately has NO `skip()` — the
+ * plain-`T` API cannot skip (M10; invariant 24). `reuseGraced()` is the typed
+ * primitive for reusing stale bytes — never launder `graced.value` (an
+ * `unknown`) to `T`.
+ */
+interface FactoryCtx<T> {
+  readonly signal: AbortSignal;
+  readonly graced?: GracedInfo;
+  /** The adapter request object — a guarded accessor under public scope. */
+  readonly request?: RequestContext;
+  /** Throw a classified error; bare `fail()` is non-retriable. */
+  fail(err?: unknown): never;
+  /** Contribute a dependency tag; `l3:false` marks it droppable for shared caches. */
+  dependsOn(tag: Tag, options?: {
+    readonly l3?: boolean;
+  }): void;
+  setTags(tags: readonly Tag[]): void;
+  setTtl(ttl: Duration): void;
+  /** Reuse the graced value with an identity + provenance/codec check. */
+  reuseGraced(): T;
+}
+/**
+ * The factory context for `getOrSetEntry`. Adds `skip()` — reachable ONLY
+ * through the entry form, with sound `never` typing so it cannot silently resolve
+ * `undefined` typed as `T` (M10; invariant 24).
+ */
+interface EntryFactoryCtx<T> extends FactoryCtx<T> {
+  skip(): never;
+}
+/** Options common to `getOrSet` and `getOrSetEntry`. */
+interface GetOptions {
+  readonly key: string;
+  readonly tags?: readonly Tag[];
+  /**
+   * Declared time-to-live. In v0.2 this is part of the singleflight join identity — two
+   * concurrent same-key fills declaring different ttls are an options mismatch — but it is
+   * NOT stored with the entry and does not drive expiry: validity is decided by epoch comparison,
+   * never a wall clock, and the write path passes no residency hint to the stores. So an
+   * entry outlives its declared ttl until a purge or store eviction removes it. Wiring ttl to
+   * residency and to stored identity is the v0.4 ttl design slot, beside `FactoryCtx.setTtl`.
+   */
+  readonly ttl?: Duration;
+  readonly grace?: Duration;
+  readonly notFoundTtl?: Duration;
+  readonly scope?: Scope;
+  /**
+   * Read consistency. Part of the singleflight join identity: a `strong`
+   * request never joins a non-strong fill.
+   */
+  readonly consistency?: Consistency;
+  /** Opt in to a cross-isolate lock; the fill carries `Envelope.fence`. */
+  readonly lock?: boolean;
+  /** The adapter request object for this call, surfaced as a guarded accessor. */
+  readonly request?: RequestContext;
+}
+/** `getOrSet` options — plain-`T` factory, no `skip`. */
+interface GetOrSetOptions<T> extends GetOptions {
+  readonly factory: (ctx: FactoryCtx<T>) => Promise<T>;
+}
+/** `getOrSetEntry` options — entry-form factory, `skip`-capable. */
+interface GetOrSetEntryOptions<T> extends GetOptions {
+  readonly factory: (ctx: EntryFactoryCtx<T>) => Promise<T>;
+}
+/** The `getOrSetEntry` result (adds `durable`, makes it optional). */
+interface CacheEntry<T> {
+  readonly value: T | undefined;
+  readonly skipped: boolean;
+  readonly stale: boolean;
+  readonly age: number;
+  readonly tier: Tier;
+  readonly servedOnError?: boolean;
+  /**
+   * What THIS serve can prove about the value's durability:
+   *   - `true` — the value is in the shared L2 tier (a fill that wrote it there, or a read that
+   *               found it there: either way, proof).
+   *   - `false` — the value is known NOT durable: the fill was confined to L1 (a `usr:` scope, a
+   * dev-mode guarded-accessor demotion), its L2 write-back was suppressed,
+   * or the guard REFUSED the write outright — a `kind:'neg'` candidate over a
+   *               stored val the letter protects. Only the last was never issued at all; `false`
+   *               reports this turn's own write either way, because in every one of them the
+   *               kernel positively knows no durable copy of what it tried to write exists.
+   *   - ABSENT — unknowable on this serve: a `pub`/`ten:` entry found in L1 carries no
+   * write-back record, and a serve does not consult L2 on an L1 hit.
+   *
+   * An absent field is a real answer, not a `false` in disguise. A truthiness test collapses it into
+   * the conservative direction (not provably durable), which is a safe default; code that must
+   * distinguish known-not-durable from unknowable compares against `false` explicitly.
+   */
+  readonly durable?: boolean;
+}
+/** Best-effort match hint on a purge result (renamed from `matched`). */
+type MatchedHint = "yes" | "no-such-scope" | "unknown";
+/** The result of `expire` / `delete` / `clear`. */
+interface PurgeResult {
+  readonly epoch: number;
+  /** Best-effort; legal workflows must not branch on it. */
+  readonly matchedHint: MatchedHint;
+  /** Durable + bus handoff + KV batch accepted. NOT the edge. */
+  flushed(options?: {
+    readonly timeout?: Duration;
+  }): Promise<void>;
+  /** CDN purge accepted (queue drained) — a distinct promise. */
+  edgePurged(options?: {
+    readonly timeout?: Duration;
+  }): Promise<void>;
+}
+/** `expire` selector — a tag (optionally scope-qualified) or a key. */
+type ExpireSelector = {
+  readonly tag: Tag;
+  readonly scope?: Scope;
+} | {
+  readonly key: string;
+};
+/** `delete` selector — like `expire`, plus a CDN mode. */
+type DeleteSelector = {
+  readonly tag: Tag;
+  readonly scope?: Scope;
+  readonly cdn?: CdnMode;
+} | {
+  readonly key: string;
+  readonly cdn?: CdnMode;
+};
+/** The explicit acknowledgement `expireAll` / `deleteAll` require. */
+interface OriginLoadGuard {
+  readonly iUnderstandTheOriginLoad: true;
+}
+/** Header-byte budget for shared-cache emission (16 KB / ~1,000-tag). */
+interface L3Budget {
+  readonly maxBytes?: number;
+  readonly maxTags?: number;
+}
+/**
+ * Why a response is ineligible for shared HTTP caches.
+ *
+ *   - `late-tag` / `budget`: the timing + header-budget triggers.
+ *   - `scope`: the render consumed a dependency whose stored scope is readable but
+ *     NOT `pub` (a `usr:`/`ten:` entry) — per-principal content.
+ *   - `scope-unreadable`: a consumed dependency's stored scope could not be read at
+ *     all (absent / malformed). It fails CLOSED to non-public: an unverifiable scope
+ * is treated exactly like a private one.
+ */
+type L3Ineligibility = "late-tag" | "budget" | "scope" | "scope-unreadable";
+/** The shared-cache emission decision at header commit. */
+interface L3Emission {
+  /** `false` ⇒ `Cache-Control: private` / no `s-maxage`. */
+  readonly eligible: boolean;
+  /** Cache-Tag values to emit; `__k`/`__ns` are never emitted. Always empty
+   * on a scope-ineligible emission — a poisoned response emits no tag at all. */
+  readonly cacheTags: readonly string[];
+  readonly ineligibleReason?: L3Ineligibility;
+}
+/**
+ * Request-scoped render-time dependency-tag collector. Cache hits and fills during
+ * the request contribute tags AND their scope evidence automatically (that automatic
+ * contribution is what makes the gate safe-by-default: a render cannot forget to
+ * declare the private entry it just read). `commitHeaders` decides shared-HTTP-cache
+ * eligibility at header-commit time: a non-public consumed dependency poisons the response
+ * outright, and beneath that gate the timing/budget rules still apply — required
+ * tags discovered late, or exceeding the L3 budget, make the response ineligible
+ * (invariant 13).
+ */
+interface RenderCollector {
+  dependsOn(tag: Tag, options?: {
+    readonly l3?: boolean;
+  }): void;
+  commitHeaders(budget?: L3Budget): L3Emission;
+}
+/**
+ * A stored entry's scope as read from the surface, preserving the readable-vs-
+ * unreadable distinction: a `pub` / `usr:<h>` / `ten:<h>` literal read verbatim, or the fail-closed
+ * `unreadable` marker when the surface returned no readable scope (absent / non-string).
+ */
+type ExplainScope = {
+  readonly kind: "readable";
+  readonly literal: string;
+} | {
+  readonly kind: "unreadable";
+};
+/**
+ * A stored entry's ttl as read from the surface, preserving the stored-vs-not-stored
+ * distinction: the number the stored format carries, or `not-stored` where it carries none. The two
+ * arms are structurally distinct and there is no sentinel — a stored ttl of `0` and a ttl the format
+ * never wrote are different states, and only the store's own bytes decide which. The v0.2 format
+ * persists no ttl (see the v0.4 ttl slot named beside `FactoryCtx.setTtl`), so the witness reports
+ * `not-stored` today; a format that later carries one is reported through this same arm.
+ */
+type ExplainTtl = {
+  readonly kind: "stored";
+  readonly seconds: number;
+} | {
+  readonly kind: "not-stored";
+};
+/**
+ * The scope evidence one recorded render dependency carries — the public projection
+ * of the collector's per-dependency scope. Adds `none` (a bare `dependsOn` with no managed entry
+ * behind it, which carries no scope claim) to the stored two-arm form.
+ */
+type ExplainDependencyScope = {
+  readonly kind: "none";
+} | ExplainScope;
+/**
+ * One render dependency `explain` attributes to the in-flight request — its tags, its
+ * scope evidence, and whether it is droppable for shared caches (`l3:false`). Request-scoped: only
+ * surfaced while a render collector is bound.
+ */
+interface ExplainedDependency {
+  readonly tags: readonly string[];
+  readonly scope: ExplainDependencyScope;
+  readonly l3?: boolean;
+}
+/**
+ * The entry's stored identity as `explain` reads it from the store: the
+ * stored tag set, the scope as stored (readable-vs-unreadable), the born epoch, the ttl as stored
+ * (stored-vs-not-stored), and the entry kind. Every field is read off the stored bytes: a
+ * reconstruction default the reader supplies is not stored identity, and reporting one as identity
+ * would be the witness testifying to a value the store never carried.
+ */
+interface ExplainIdentity {
+  readonly tags: readonly string[];
+  readonly scope: ExplainScope;
+  readonly bornEpoch: number;
+  readonly ttl: ExplainTtl;
+  readonly kind: EnvelopeKind;
+}
+/**
+ * The classification `explain` reaches and the epochs behind it: the reader's
+ * current-knowledge verdict over the entry, plus the tag-knowledge watermarks the born epoch was
+ * weighed against (the purge epochs behind a `stale`/`dead` verdict, `0` when nothing is known).
+ * `unknown` stays `unknown` — the fail-closed narration is the point, not a gap.
+ */
+interface ExplainVerdict {
+  readonly validity: Validity;
+  readonly softEpoch: number;
+  readonly hardEpoch: number;
+}
+/**
+ * The reader's own already-tracked state at the moment of the call,
+ * surfaced via read-only accessors — `explain` adds no tracking of its own.
+ * `appliedEpoch`/`suspect`/`channel` come from the invalidation reader; `terminal` from its
+ * replication shell. A registry-absent instance has no reader, so all four rest at their neutral
+ * values.
+ *
+ * `channel` is conformant on the letter that matters: the reader tracks it for its own use (the
+ * lazy redial needs to know whether it has a channel), so surfacing it ADDS NO BOOKKEEPING — it
+ * exposes a fact already on the object. The witness may speak; it may not touch cache state, and
+ * reading this getter does not dial, subscribe, or record.
+ *
+ * It is here because `suspect` alone cannot answer the question an operator actually asks. A reader
+ * whose bus never connected is NOT suspect — it has no gap, it has no channel — so a healthy-looking
+ * `suspect: false` is exactly what a dead bus produces. `channel` is the field that tells those two
+ * apart.
+ */
+interface ExplainReaderState {
+  readonly appliedEpoch: number;
+  readonly suspect: boolean;
+  readonly terminal: boolean;
+  /** The live channel's state — `never-established` until the first `hello` ever arrives. */
+  readonly channel: ChannelState;
+}
+/** Fields common to every arm of an `Explanation` — what the witness knows regardless of
+ * what the store said. `tier` is NOT here: it is an observation over the tiers, and a probe that
+ * failed observed none, so the arm that could not read carries no tier to report. */
+interface ExplanationBase {
+  readonly key: string;
+  readonly reader: ExplainReaderState;
+  /** Request-scoped per-dependency attribution — present (possibly empty) only
+   * while a render collector is bound to the in-flight request; ABSENT otherwise. It lives and dies
+   * with the request. */
+  readonly requestDependencies?: readonly ExplainedDependency[];
+}
+/**
+ * What `explain(key)` reports — three structurally distinct arms on one `kind`
+ * discriminant, the same two-arm discipline `ExplainScope`/`ExplainTtl` already carry, extended to
+ * the state the store itself can withhold. There is no sentinel, and no arm is reachable by reading
+ * a field off another.
+ *
+ *   - `present` — the entry was read: its stored identity and the reader's verdict, found in
+ *                     `tier`.
+ *   - `absent` — every tier was read and none holds the key. A REPORTABLE state, not an error:
+ *                     `explain` never throws for a missing key.
+ *   - `read-failed` — a tier's read failed and was suppressed, and no other tier held the key,
+ *                     so whether it exists is UNKNOWN. Distinct from `absent` because the difference
+ *                     is real: one is the store answering "nothing", the other is the store not
+ *                     answering. Reporting the second as the first would be the witness laundering
+ * an error into an answer — what the closing sentence forbids. It carries NO
+ *                     `tier` and NO `identity`: a probe that could not read observed neither.
+ *
+ * The precedence is what each state can support: a found entry is FOUND however the other tiers
+ * behaved; and a failed read outranks absence, because a tier that never answered cannot be counted
+ * as one that answered "no". `explain` cannot refill, so the serving-path remedy does not transfer
+ * — the honest report is the whole remedy available here.
+ */
+type Explanation = (ExplanationBase & {
+  readonly kind: "present";
+  /** The tier the entry was found in — an OBSERVATION over the tiers, never a hydrating read.*/
+  readonly tier: Tier;
+  readonly identity: ExplainIdentity;
+  readonly verdict: ExplainVerdict;
+}) | (ExplanationBase & {
+  readonly kind: "absent";
+  readonly tier: "miss";
+}) | (ExplanationBase & {
+  readonly kind: "read-failed";
+});
+/** Instance defaults. */
+interface CacheDefaults {
+  readonly ttl?: Duration;
+  readonly grace?: Duration;
+  /** Registered with the Coordinator at bind. */
+  readonly maxEntryRetention?: Duration;
+  readonly consistency?: Consistency;
+  readonly unknownPolicy?: UnknownPolicy;
+  readonly staleIfError?: (err: unknown) => boolean;
+  readonly graceBackoff?: Duration;
+  readonly maxSyncLag?: Duration;
+  /** Decode-only codec compatibility for intentional migrations. */
+  readonly acceptCodecs?: readonly string[];
+  /** Paid idle-heartbeat interval for `__state` liveness. */
+  readonly heartbeatInterval?: Duration;
+  /** Strong opt-out: degrade to eventual instead of throwing. */
+  readonly onUnavailable?: "eventual";
+  /**
+   * `unknown` resolves to `'error'` — the read THROWS rather than refilling.
+   *
+   * SETTABLE HERE, not only at the top level, because `defaults` is the surface a composition
+   * actually threads: `createWorkersCache` forwards `defaults` wholesale, so a flag that existed
+   * only on `CacheConfig` could not be reached through any factory that wraps `createCache`. A
+   * legal-embargo control that only the raw path can set is a control most callers do not have.
+   *
+   * It is an OVERRIDE, not a default: it outranks `unknownPolicy` — see `unknownResolution`.
+   */
+  readonly takedownSensitive?: boolean;
+}
+/** `createCache` configuration. `clock`/`rng` are injected. */
+interface CacheConfig {
+  readonly namespace: string;
+  readonly clock: Clock;
+  readonly rng: Rng;
+  readonly l1?: Store;
+  readonly l2?: Store;
+  readonly registry?: Registry;
+  readonly bus?: Bus;
+  readonly cdn?: Cdn;
+  /** Opt-in cross-isolate lock backend. */
+  readonly lock?: Lock;
+  /** Pluggable value codec. Defaults to the library's safe-mode codec. */
+  readonly codec?: Codec;
+  readonly defaults?: CacheDefaults;
+  /** A plain sink, or a hosted config that pseudonymizes every string field. */
+  readonly telemetry?: TelemetrySink | TelemetryConfig;
+  /** `unknown` + registry-unreachable resolves to `'error'`, not `'miss'`. */
+  readonly takedownSensitive?: boolean;
+  /**
+   * Dev mode: a singleflight option mismatch throws + a guarded-accessor read in a
+   * public factory throws; prod (`false`) runs a separate fill and emits a
+   * `singleflight_option_mismatch` event instead.
+   */
+  readonly dev?: boolean;
+}
+/** The public cache instance. */
+interface Cache {
+  getOrSet<T>(options: GetOrSetOptions<T>): Promise<T>;
+  getOrSetEntry<T>(options: GetOrSetEntryOptions<T>): Promise<CacheEntry<T>>;
+  expire(selector: ExpireSelector): Promise<PurgeResult>;
+  delete(selector: DeleteSelector): Promise<PurgeResult>;
+  /** Namespace version bump + hard watermark on the reserved `__ns` tag. */
+  clear(): Promise<PurgeResult>;
+  expireAll(guard: OriginLoadGuard): Promise<PurgeResult>;
+  deleteAll(guard: OriginLoadGuard): Promise<PurgeResult>;
+  /** Open a request-scoped render-time tag collector. */
+  collect(): RenderCollector;
+  /** Witness a key's stored identity, the reader's verdict + evidence, its serving tier, the
+   * reader's own state, and any request-scoped dependency attribution. Absence is a
+   * reportable state — never throws for a missing key. Introspection adds no tracked state.
+   *
+   * Two consequences of witnessing rather than simulating, both deliberate:
+   * - `usr:`-scoped entries are addressable only through request-scoped attribution; `explain(key)`
+   * cannot construct a private key, so it fails closed rather than guess a scope.
+   * - The L1 probe reads through the store's own `get`, so it takes that tier's LRU touch: the
+   *   witness perturbs recency, which is why it is an introspection tool and not a hot-path read.
+   *   A non-touching `peek` on the store surface is a v0.4 slot — it waits for a second consumer. */
+  explain(key: string): Promise<Explanation>;
+}
+/**
+ * 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.
+ */
+declare function createCache(config: CacheConfig): Cache;
+//#endregion
+export { Clock as $, Tier as A, EnvelopeEnc as B, L3Ineligibility as C, TelemetrySink as Ct, RenderCollector as D, Watermark as Dt, PurgeResult as E, Validity as Et, compound as F, Bus as G, Duration as H, globalTag as I, CasOrder as J, BusEvent as K, t as L, createCache as M, Tag as N, RequestContext as O, TagPart as P, CdnMode as Q, ChannelState as R, L3Emission as S, TelemetryEventName as St, OriginLoadGuard as T, TagKnowledge as Tt, DurationUnit as U, EnvelopeKind as V, duration as W, CasStore as X, CasRecord as Y, Cdn as Z, GetOptions as _, SinkErrorHook as _t, DeleteSelector as a, Registry as at, GracedInfo as b, TelemetryConfig as bt, ExplainDependencyScope as c, Store as ct, ExplainScope as d, StoreWriteError as dt, Codec as et, ExplainTtl as f, StoreWriteOptions as ft, FactoryCtx as g, memory as gt, Explanation as h, isStoreWriteError as ht, CacheEntry as i, ReadKind as it, UnknownPolicy as j, Scope as k, ExplainIdentity as l, StoreMetadata as lt, ExplainedDependency as m, TagChange as mt, CacheConfig as n, LockHandle as nt, EntryFactoryCtx as o, RegistryAck as ot, ExplainVerdict as p, Subscription as pt, BusFrame as q, CacheDefaults as r, MemoryOptions as rt, ExpireSelector as s, Rng as st, Cache as t, Lock as tt, ExplainReaderState as u, StoreValue as ut, GetOrSetEntryOptions as v, StrongDegradedReason as vt, MatchedHint as w, Consistency as wt, L3Budget as x, TelemetryEvent as xt, GetOrSetOptions as y, TELEMETRY_EVENTS as yt, Envelope as z };