@astilba/cache 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Rees Morris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,15 @@
-# Temporary Holding Version
+# @astilba/cache
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+A portable TypeScript caching library — tag invalidation (soft/hard), classified stale-if-error resilience, and private-by-default scopes. Targets Node, Bun, and Cloudflare Workers.
+
+> **Public alpha (0.1).** The correctness kernel and the Cloudflare Workers and React Router paths ship and run under the test suite, but elapsed TTL and grace periods are not enforced yet, a few methods still throw, and there is no production support commitment. Expect breaking changes before 1.0. Check [implementation status](https://astilba.com/docs/cache/api-status/) before relying on a feature.
+
+```sh
+pnpm add @astilba/cache
+```
+
+Documentation lives at [astilba.com/docs/cache](https://astilba.com/docs/cache/).
+
+## License
+
+MIT © Rees Morris

package/dist/adapters/cloudflare/index.d.ts

@@ -0,0 +1,299 @@
+import { Ct as TelemetrySink, G as Bus, Tt as TagKnowledge, at as Registry, bt as TelemetryConfig, ct as Store, ot as RegistryAck, r as CacheDefaults, st as Rng, t as Cache } from "../../cache-YWn0VZpn.js";
+import { DurableObject } from "cloudflare:workers";
+//#region src/adapters/cloudflare/bus-client.d.ts
+/** A message event as delivered to a WS `message` listener — `data` is the payload string. */
+interface WireMessageEvent {
+  readonly data: unknown;
+}
+/** A close event as delivered to a WS `close` listener. */
+interface WireCloseEvent {
+  readonly code: number;
+  readonly reason: string;
+}
+/**
+ * The minimal client-side socket surface the doBus client needs. workerd's client WebSocket
+ * (`response.webSocket`, after `accept()`) satisfies it structurally; the conformance in-memory
+ * pair implements the same shape.
+ */
+interface ClientSocket {
+  close(code?: number, reason?: string): void;
+  addEventListener(type: "message", listener: (event: WireMessageEvent) => void): void;
+  addEventListener(type: "close", listener: (event: WireCloseEvent) => void): void;
+}
+/** How the client obtains an OPEN socket. Returns synchronously (the conformance pair) or a promise
+ * (a real `stub.fetch` → `accept()`); the client handles both. */
+type Dial = () => ClientSocket | Promise<ClientSocket>;
+/** Why the doBus socket closed (status report). `local` distinguishes a close the client
+ * ITSELF initiated (a protocol/scope violation) from one the transport/server delivered. EXPORTED at
+ * its first consumer, the redial driver (`redial.ts`), has arrived, and an app that supplies
+ * its own `onClose` reads the same shape. */
+interface DoBusCloseInfo {
+  readonly code: number;
+  readonly reason: string;
+  readonly local: boolean;
+}
+interface DoBusOptions {
+  /** The mirror-key scope this subscriber expects the DO to echo in its `hello`. */
+  readonly regId: string;
+  /** Status report: the socket closed. Fired at most once per subscription. The
+   * driver redials off this; integration tests redial explicitly. */
+  readonly onClose?: (info: DoBusCloseInfo) => void;
+}
+/**
+ * Build a `doBus` client `Bus`. `dial` obtains an OPEN socket (synchronously in the
+ * conformance pair; a `stub.fetch` → `accept()` promise in workerd). `options.regId` is the scope
+ * the DO's `hello` must echo; `options.onClose` receives the socket's close (
+ * NO self-reconnect). The reader subscribes to the returned `Bus`; the client decodes each message
+ * and dispatches the `BusEvent`, closing loud on any protocol/scope violation.
+ */
+declare function doBus(dial: Dial, options: DoBusOptions): Bus;
+//#endregion
+//#region src/adapters/cloudflare/coordinator.d.ts
+/** The bindings the Coordinator reads. `REGISTRY_KV` is the replication mirror. */
+interface CoordinatorEnv {
+  /** The KV namespace the `__delta`/`__snap`/`__state` replication mirror is written to. */
+  readonly REGISTRY_KV: KVNamespace;
+  /**
+   * liveness heartbeat interval in ms, as a config var (`env` decides WHEN the shell
+   * issues a heartbeat command — it never parameterizes the machine). When set (Paid deployments),
+   * an idle alarm refreshes `__state`'s freshness even with no purges, via the machine's
+   * state-neutral heartbeat routed through the shared executor; earliest-wins arbitration keeps it
+   * from starving the flush deadline, and a flush never also heartbeats in the same alarm.
+   * UNSET by default (off — the default in every test lane; the heartbeat suite sets it per-test),
+   * so the heartbeat path stays fully dormant.
+   *
+   * THE COORDINATOR END OF THE ONE HEARTBEAT NUMBER, and the end NO WORKER CAN REACH.
+   * This var and the reader's `defaults.heartbeatInterval` are the two ends of the liveness
+   * contract, but a Worker cannot write a Durable Object's `env`: deploy-time wrangler config is
+   * this end's ONLY seed. So the two ends are NOT matched by construction — they are ONE DOCUMENTED
+   * NUMBER over TWO DEPLOYMENT SURFACES, and matching them is a deployment step. Recommended
+   * production posture: `"vars": { "REGISTRY_HEARTBEAT_MS": "30000" }` — the same 30s the
+   * `createWorkersCache` reader defaults to (see `DEFAULT_HEARTBEAT_INTERVAL` in `workers-cache.ts`
+   * for the full price of leaving it unset). A change here lands at the DO's next boot (one boot's
+   * lag). A drift between the ends is safe-direction (a shorter reader interval raises suspicion
+   * SPURIOUSLY: live registry checks, telemetry-visible, never a stale serve), which is why nothing
+   * enforces equality; the asymmetry is documented at that constant rather than engineered away.
+   */
+  readonly REGISTRY_HEARTBEAT_MS?: string;
+  /**
+   * Snapshot cadence knobs, as config vars. `env` may only AUTHOR a journaled `configure`
+   * command (Ruling B) — it never parameterizes the machine directly. On boot the shell diffs
+   * `env` against the journal's effective config and, if changed, journals a fresh `configure`
+   * (see `#reconcileConfig`), applied PROSPECTIVELY at a definite journal position — replay-exact
+   * forever. So a later var change can never retroactively fork `snapBatch` or bless a `__snap`
+   * that was never written; the journal is the single durable truth. UNSET ⇒ the machine's
+   * 500-batch / 6h defaults.
+   */
+  readonly REGISTRY_SNAPSHOT_EVERY_BATCHES?: string;
+  readonly REGISTRY_SNAPSHOT_INTERVAL_MS?: string;
+  /**
+   * Snapshot SIZE ceiling in bytes, as a config var. Seeds the machine's
+   * `maxSnapshotBytes` through the SAME journaled `configure` channel as the cadence (Ruling B):
+   * `env` authors it, the journal is the single durable truth, replay reproduces the skip decision.
+   * A due snapshot whose canonical shipped bytes exceed this is SKIPPED (never truncated, never a
+   * phantom bless). UNSET ⇒ the machine's 25 MiB default (the KV per-value profile).
+   */
+  readonly REGISTRY_MAX_SNAPSHOT_BYTES?: string;
+  /**
+   * The registry id scoping the mirror keyspace — the DEMOTED FALLBACK, as a config var.
+   * Identity = address: a Coordinator's `regId` derives from its OWN Durable Object name
+   * (`ctx.id.name`), the string clients address it by. `REGISTRY_ID` is consulted ONLY for an
+   * un-named object (`newUniqueId` ⇒ `ctx.id.name === undefined`), never as an override (an override
+   * would resurrect the one-registry-per-deployment defect kills). UNSET ⇒ `"default"`
+   * (single-registry deployments stay zero-config). Validated `[a-z0-9._-]`, ≤ 64 — a malformed
+   * value fails the boot loud (see `resolveRegId`) rather than minting a bad key.
+   */
+  readonly REGISTRY_ID?: string;
+}
+/**
+ * A name/journal regId DIVERGENCE detected at boot. regId is journaled at first
+ * `configure` and NEVER re-journaled; on a later boot where the DO's name derives a DIFFERENT id
+ * than the journaled one, the Coordinator KEEPS the journaled identity and records this — it can
+ * never serve dead, because both replication channels already fail closed on identity mismatch (the
+ * pointer's regId echo, `hello`'s regId echo). Migration to a new identity =
+ * addressing a NEW name (fresh journal, fresh keyspace), never a rekey of the live one.
+ */
+interface RegIdDivergence {
+  /** The regId journaled at first boot — the identity that WINS (mirror keys stay `__reg:<this>:*`). */
+  readonly journaled: string;
+  /** The regId the current Durable Object name derives — observed, priced (misses/checks), never served. */
+  readonly name: string;
+}
+declare class Coordinator extends DurableObject<CoordinatorEnv> {
+  #private;
+  /**
+   * The name/journal regId divergence detected at this instance's boot, or null when the
+   * name still derives the journaled identity. A read-only boot diagnostic (surfaced to the
+   * integration divergence scene via `runInDurableObject`); never consulted on a hot path.
+   */
+  get regIdDivergence(): RegIdDivergence | null;
+  /** Strong read: live, un-memoized, primary-only — the DO IS the primary. */
+  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 a retention lease; the GC horizon rises to the high-water. */
+  registerRetention(retentionMs: number): Promise<void>;
+  /**
+   * The doBus live-channel endpoint. A subscriber opens a WebSocket here; the DO
+   * accepts it HIBERNATABLY (no per-subscriber attachment, ZERO replay state) and runs
+   * the establishment handshake: `reset` → `hello{head, regId}`, BEFORE any frame. `head`
+   * is the DO's OWN last-flushed epoch (`#flushedEpoch`) and the `hello` echoes `regId`,
+   *so a mismatched subscriber closes loud. Serialized under `blockConcurrencyWhile` so the
+   * handshake snapshots a consistent (cursor, regId) against any in-flight mutation.
+   */
+  fetch(request: Request): Promise<Response>;
+  /**
+   * Hibernatable WebSocket message handler. The doBus client is RECEIVE-ONLY —
+   * it dials, decodes, and dispatches; it never sends. Any inbound message is unexpected and there
+   * is no per-subscriber state to update, so it is ignored. Defined so the hibernation runtime has a
+   * message handler for woken sockets.
+   */
+  webSocketMessage(_ws: WebSocket, _message: ArrayBuffer | string): void;
+  /**
+   * Hibernatable WebSocket close handler. Stateless fan-out holds ZERO
+   * per-subscriber state, so a closed socket needs no reclamation — a later `getWebSockets()` simply
+   * will not include it. Defined so the hibernation runtime has a close handler for woken sockets.
+   */
+  webSocketClose(_ws: WebSocket, _code: number, _reason: string, _wasClean: boolean): void;
+  /** Hibernatable WebSocket error handler — best-effort close; no state to reclaim. */
+  webSocketError(ws: WebSocket, _error: unknown): void;
+  /**
+   * The DO alarm handler, serving BOTH the flush window and the heartbeat cadence off the one
+   * alarm slot. A PURE function of durable state, idempotent under at-least-once
+   * delivery + redeploy: it rehydrates the machine from the journal and either FLUSHES the
+   * coalescing window `(kvFlushedEpoch, epoch]` into one content-addressed batch (advancing the
+   * durable cursor ONLY after KV accepts), or — on an EMPTY window — refreshes the `__state`
+   * freshness via a state-neutral heartbeat. A redelivery before the cursor advances re-writes the
+   * identical (content-addressed, write-once) bytes; a redelivery after finds an empty window and
+   * heartbeats (or no-ops when the cadence is unset).
+   */
+  alarm(): Promise<void>;
+}
+//#endregion
+//#region src/adapters/cloudflare/do-registry.d.ts
+/**
+ * Where a Coordinator stub comes from (widened by ADDITIVELY, in the warrant).
+ *
+ * A STUB is a client-held I/O handle: it belongs to the request context that minted it, and the
+ * platform refuses it anywhere else. A long-lived cache therefore cannot hold one — but the API defines
+ * `doRegistry(stub, regId)`, and a caller who mints and uses inside ONE request (the explicit
+ * composition, as written) is doing nothing wrong. So the parameter widens instead of changing: a
+ * bare stub stays exactly as valid as it was, and a THUNK lets a caller that outlives a request hand
+ * over the ADDRESS — the recipe for a stub — rather than a stub. The thunk is invoked per use, so
+ * whichever request is running gets a handle of its own.
+ */
+type StubSource = DurableObjectStub<Coordinator> | (() => DurableObjectStub<Coordinator>);
+/** Build a `Registry` from a Coordinator DO stub OR a thunk that mints one (`StubSource` —
+ * the widening is additive, so `doRegistry(stub, regId)` remains exactly as signed). `regId`
+ * must match the Coordinator's regId — which is its Durable Object NAME
+ * (identity = address) — so the client-side reader resyncs the same scoped keyspace the DO writes;
+ * defaults to `"default"` for single-registry (zero-config) deployments.
+ *
+ * Pass a THUNK from anything that outlives a request (`createWorkersCache` does); pass a bare stub
+ * when the caller mints and uses within one. */
+declare function doRegistry(source: StubSource, regId?: string): Registry;
+//#endregion
+//#region src/adapters/cloudflare/kv.d.ts
+/** Build a `Store` over a Cloudflare `KVNamespace` binding. */
+declare function cloudflareKV(ns: KVNamespace): Store;
+//#endregion
+//#region src/adapters/cloudflare/redial.d.ts
+/** `redialingDoBus` configuration. `regId` + `onClose` mirror `DoBusOptions` (the close report is
+ * PASSED THROUGH to the app after the redial is scheduled — the driver consumes it, it does not
+ * swallow it); `rng` is the jitter source (injected — the platform boundary owns ambient randomness,
+ * and `createWorkersCache` hands its one `Rng` to both the kernel and this driver). */
+interface RedialOptions {
+  readonly regId: string;
+  readonly rng: Rng;
+  /** Status report, after this driver has scheduled the redial. Observability only. */
+  readonly onClose?: (info: DoBusCloseInfo) => void;
+  /** First-attempt delay before the ×2 ladder (default 1s). */
+  readonly baseDelayMs?: number;
+  /** Symmetric jitter fraction (default 0.2 → ±20%). */
+  readonly jitterFraction?: number;
+}
+/** A `Bus` whose redial ladder is driven by ticks rather than timers. `tick(nowMs)` performs a
+ * DUE redial and is a no-op otherwise; the composition calls it from a request context. */
+interface RedialingBusHandle extends Bus {
+  tick(nowMs: number): void;
+}
+/**
+ * Build a self-redialing doBus `Bus`. This is the bus `createWorkersCache` wires: the
+ * transport reports its close, and this driver owns the reconnect + the ×2/300s jittered
+ * backoff — LAZILY, performed by `tick` inside a request context rather than by a timer that would
+ * be refused at global scope and would race a dead isolate everywhere else. Use the bare `doBus`
+ * instead when the caller drives redials itself (the integration lane does — tests own time).
+ */
+declare function redialingDoBus(dial: Dial, options: RedialOptions): RedialingBusHandle;
+//#endregion
+//#region src/adapters/cloudflare/reg-id.d.ts
+/**
+ * Refused: a Coordinator addressed by a Durable Object name that violates the regId
+ * grammar (`[a-z0-9._-]`, 1–64). Typed so the boot failure is unambiguous and machine-checkable —
+ * the fix is a conforming name or an explicit `REGISTRY_ID`. Thrown at first boot only (before any
+ * data), so it strands nothing: validate-and-refuse, not journal-wins. `Error.name` stays the class
+ * name; `registryName` carries the offending Durable Object name.
+ */
+declare class InvalidRegistryNameError extends Error {
+  readonly registryName: string;
+  constructor(registryName: string);
+}
+//#endregion
+//#region src/adapters/cloudflare/workers-cache.d.ts
+/**
+ * `createWorkersCache` configuration (SIGNED shape). The required key set is EXACTLY
+ * `{ name, kv, coordinator }`; `defaults` is optional. `name` is the ONE identity string: it becomes
+ * the Coordinator DO address (`idFromName(name)`), the registry id (`regId`), and the cache key
+ * namespace — identity = address. `coordinator` is parameterized by `Coordinator` so
+ * `.get(idFromName(name))` yields the typed stub `doRegistry` needs.
+ */
+interface WorkersCacheConfig {
+  readonly name: string;
+  readonly kv: KVNamespace;
+  readonly coordinator: DurableObjectNamespace<Coordinator>;
+  readonly defaults?: CacheDefaults;
+  /** A plain sink, or a hosted config that pseudonymizes every string field. Passed
+   * straight through to `createCache`. OPTIONAL, so the signed required key set is untouched — but
+   * PRESENT, because without it the events this composition emits (`bus_dial_failed`,
+   * `strong_degraded`, …) are unreachable for every hero-path user, which is a health surface that
+   * exists only on paper. */
+  readonly telemetry?: TelemetrySink | TelemetryConfig;
+  /** `unknown` resolves to `'error'` — the read THROWS rather than refilling. An OVERRIDE:
+   * it outranks `defaults.unknownPolicy`, including this factory's own safe-posture default. For
+   * namespaces under a takedown or legal embargo, where refilling from origin could resurrect the
+   * content that had to disappear. Optional; the key set is untouched. */
+  readonly takedownSensitive?: boolean;
+}
+/**
+ * Build a Workers-native `Cache` from one registry `name` + a KV namespace + a Coordinator DO
+ * namespace. Sugar over `createCache`: the wall clock and RNG enter here at the platform
+ * boundary and reach the kernel only as the injected `clock`/`rng`; the drivers are composed against
+ * the single `name` (DO stub, registry id, key namespace). A caller's `defaults` override the safe
+ * posture per-field; everything else is fixed.
+ *
+ * WHY THE L1 IS NOT OPTIONAL HERE, AND WHAT IT COSTS TO SKIP IT. This factory always composes an L1,
+ * and under an L2 outage that L1 is the absorber. A failing L2 read is suppressed to a plain miss,
+ *so the reader refills from origin — and with an L1 the refill lands there, is checked first
+ * on every subsequent read, and the failing tier is never consulted again: one origin call,
+ * however long the outage runs. Take the L1 away and nothing catches the refill. The read suppresses
+ * to a miss, the write-back's read-compare cannot read, so nothing lands durably (`durable: false`),
+ * and the next call repeats the whole trip — every call, forever, for as long as L2 is down. So a
+ * raw `createCache` composed WITHOUT an `l1` converts an L2 outage into an unbounded origin
+ * stampede, exactly when the origin is least able to absorb one. That is a priced consequence of
+ * the miss-class posture, not a defect — a suppressed read must refill, and a refill it cannot
+ * cache must happen again. Compose an L1, or accept the bill.
+ *
+ * ONE DEPLOYMENT STEP THIS FACTORY CANNOT DO FOR YOU (R6). A Worker cannot write a Durable Object's
+ * `env`, so the Coordinator's idle liveness heartbeat is seeded ONLY by its own wrangler config, and it
+ * ships DORMANT. Recommended production posture — set it to the same 30s this reader defaults to
+ * (see `DEFAULT_HEARTBEAT_INTERVAL` for the full price of leaving it unset, and for why a mismatch
+ * is safe-direction rather than a bug):
+ *
+ *     // wrangler.jsonc (the Worker that hosts the Coordinator Durable Object)
+ *     "vars": { "REGISTRY_HEARTBEAT_MS": "30000" }
+ */
+declare function createWorkersCache(config: WorkersCacheConfig): Cache;
+//#endregion
+export { Coordinator, type Dial, type DoBusCloseInfo, type DoBusOptions, InvalidRegistryNameError, type RedialOptions, type RedialingBusHandle, type StubSource, type WorkersCacheConfig, cloudflareKV, createWorkersCache, doBus, doRegistry, redialingDoBus };