@demlik/tea 0.13.0 → 0.15.0

package/dist/index-CSyMYDAB.d.ts

@@ -0,0 +1,69 @@
+import { S as Store } from './runtime-types-CMF13BBh.js';
+
+/**
+ * internal/work-queue — substrate-agnostic work-queue lifecycle on `Store<S>`.
+ *
+ * Two public surfaces, one shape:
+ *   - `createQueue(store)` (this file) is the in-process adapter — it binds the
+ *     pure ops to an injected `Store` and runs `load → mutate → save`.
+ *   - `internal/work-queue/ops` (`./ops`) is the BLESSED, importable surface
+ *     of those same pure ops. L2 compositions that own their own Model slice
+ *     (`monitored-run`, `idempotent-intake`, …) import the ops directly and
+ *     delegate status flips to them instead of re-rolling the transitions.
+ * Both routes call the identical ops, so the lifecycle rules live in exactly
+ * one place. This mirrors `@demlik/tea/do`'s one-shape-per-package rule.
+ *
+ * The package is generic in the input payload `I` (audit-specific fields go
+ * here in the extension host). `output` is a free-form side-channel correlation
+ * token (a backend id, URL, trace id) — typed as `string` because that's its
+ * only honest type. Consumers that need structured per-item data persist it in
+ * their own store and put the foreign-key string in `output`.
+ */
+
+type QueueItemStatus = "pending" | "running" | "done" | "failed" | "cancelled";
+/**
+ * A single queue entry. Every field is `readonly`: a persisted slice is
+ * immutable, so a transition returns a NEW item (the ops always spread —
+ * `{ ...item, status: … }`) rather than mutating in place. This type-enforces
+ * the durability invariant the consumers already honor by convention, and
+ * keeps a slice round-trippable through JSON unchanged across a reload.
+ */
+interface QueueItem<I> {
+    readonly id: string;
+    readonly status: QueueItemStatus;
+    readonly input: I;
+    readonly enqueuedAt: number;
+    readonly startedAt?: number;
+    readonly finishedAt?: number;
+    readonly output?: string;
+    readonly error?: string;
+}
+/**
+ * Caller-facing enqueue payload. Just `I` today — kept named so future
+ * variants (priority, deferUntil, …) can grow without breaking callers.
+ */
+type EnqueueInput<I> = I;
+/**
+ * Adapter that binds the pure ops to an injected `Store<QueueItem<I>[]>`.
+ *
+ * `load → mutate → save` is the only durability discipline this package
+ * imposes. The store decides what "save" means (chrome.storage, KV, DO
+ * storage, in-memory) — that decision belongs at the caller.
+ *
+ * Ops that don't change the queue (e.g. `markDone` on an unknown id) skip the
+ * save call so the underlying store doesn't observe a write churn.
+ */
+declare function createQueue<I>(store: Store<QueueItem<I>[]>): {
+    enqueue: (input: EnqueueInput<I>) => Promise<QueueItem<I>>;
+    claimNext: () => Promise<QueueItem<I> | null>;
+    markDone: (id: string) => Promise<void>;
+    markFailed: (id: string, error: string) => Promise<void>;
+    markCancelled: (id: string) => Promise<void>;
+    resetRunningToPending: () => Promise<void>;
+    removeItem: (id: string) => Promise<void>;
+    retryItem: (id: string) => Promise<void>;
+    bindOutput: (id: string, value: string) => Promise<void>;
+    list: () => Promise<QueueItem<I>[]>;
+};
+
+export { type EnqueueInput as E, type QueueItem as Q, type QueueItemStatus as a, createQueue as c };

package/dist/{fan-out/index.d.ts → index-CuNO9m8i.d.ts}

@@ -1,11 +1,8 @@
-import { C as Cmd, a as Port } from '../core-Co0LWkIA.js';
-import { QueueItem } from '../work-queue/index.js';
-import 'zod';
-import '../runtime-types-CNLmhWif.js';
-import 'better-result';
+import { C as Cmd, P as Port } from './core-DnzqWy6u.js';
+import { Q as QueueItem } from './index-CSyMYDAB.js';
 
 /**
- * @demlik/tea/fan-out — scatter-gather over a bounded-concurrency work list.
+ * internal/flow/fan-out — scatter-gather over a bounded-concurrency work list.
  *
  * The Level-2 combinator that fans a batch of items out across at most
  * `concurrency` in-flight effects, gathers each item's result (or error), and
@@ -68,8 +65,9 @@ import 'better-result';
  * than through the `join` Cmd.
  *
  * NOT a substrate primitive: it depends only on `../work-queue`'s pure types +
- * blessed ops and `../index`'s `Cmd` / `Port` types. Consumers reach it via the
- * `@demlik/tea/fan-out` subpath.
+ * blessed ops and the core `Cmd` / `Port` types. Internal since #48 — not
+ * published on any subpath; reached from inside the package as
+ * `internal/flow/fan-out`.
  */
 
 /**
@@ -238,4 +236,4 @@ declare function createFanOut<I, R, C extends Cmd = Cmd, J extends Cmd = Cmd>(co
     };
 };
 
-export { type FanOutConfig, type FanOutDone, type FanOutFailed, type FanOutPorts, type FanOutState, createFanOut, initFanOut, isComplete };
+export { type FanOutState as F, type FanOutConfig as a, type FanOutDone as b, type FanOutFailed as c, type FanOutPorts as d, createFanOut as e, isComplete as f, initFanOut as i };

package/dist/{debounce/index.d.ts → index-DHSUmQTR.d.ts}

@@ -1,15 +1,15 @@
 /**
- * @demlik/tea/debounce — a timer-based call transformer that coalesces a burst
+ * internal/timing/debounce — a timer-based call transformer that coalesces a burst
  * of calls into a single fire.
  *
- * Sibling of `@demlik/tea/throttle` — the two share a SYMMETRIC surface
+ * Sibling of `../throttle` — the two share a SYMMETRIC surface
  * (`Debounced<A>` / `Throttled<A>`, both callable + `.cancel()` + `.flush()`,
  * both `{ leading?, trailing? }`) so they read as a pair. They are kept in
  * separate files with NO cross-import: each is a self-contained timer, and the
  * coalesce-vs-drop policies are different enough that sharing code would hide
  * the distinction. Read one to understand the other; do not couple them.
  *
- * Layering with `@demlik/tea/throttled-input`: `debounce` and `throttle` are
+ * Layering with `../throttled-input`: `debounce` and `throttle` are
  * the two host-boundary PRIMITIVES — two distinct algorithms (collapse-a-burst
  * vs at-most-once-per-window) behind one signature shape. `throttled-input` is
  * NOT a third primitive: it is a TEA machine composed OVER them that
@@ -39,9 +39,9 @@
  *   window.addEventListener("resize", onResized);
  *   // cleanup: onResized.cancel(); window.removeEventListener("resize", onResized);
  *
- * NOT exported from the package root — reached via the `@demlik/tea/debounce`
- * subpath, same one-shape-per-package rule as `rate-limit`, `deadline`, and
- * `work-queue`.
+ * Internal since #47 — not published on any subpath; reached from inside the
+ * package as `internal/timing/debounce`. Same one-shape-per-package rule as
+ * `rate-limit`, `deadline`, and `work-queue`.
  *
  * Uses the universal `setTimeout` / `clearTimeout` timer idiom (same discipline
  * as `subs/from-timeout.ts`): exactly one live handle at a time, every arm
@@ -117,4 +117,4 @@ declare function debounce<A extends readonly unknown[]>(fn: (...args: A) => void
     trailing?: boolean;
 }): Debounced<A>;
 
-export { type Debounced, debounce };
+export { type Debounced as D, debounce as d };

package/dist/{recorder/index.d.ts → index-DrIRb_Ch.d.ts}

@@ -1,7 +1,4 @@
-import { B as BootingRuntime } from '../runtime-types-CNLmhWif.js';
-import 'better-result';
-import '../core-Co0LWkIA.js';
-import 'zod';
+import { B as BootingRuntime } from './runtime-types-CMF13BBh.js';
 
 /**
  * A recorded run, sufficient to reproduce it via `../trace-replay`.
@@ -221,7 +218,7 @@ interface TraceAttachment {
  *
  * ```ts
  * import * as Sentry from "@sentry/browser"; // or "@sentry/node"
- * import { traceAttachment } from "@demlik/tea/recorder";
+ * import { traceAttachment } from "./internal/persistence/recorder"; // internal module
  * Sentry.getCurrentScope().addAttachment(traceAttachment(rec.dump()));
  * ```
  *
@@ -279,7 +276,7 @@ interface BreadcrumbsOptions<M> {
  *
  * ```ts
  * import * as Sentry from "@sentry/browser"; // or "@sentry/node"
- * import { breadcrumbsFromTrace } from "@demlik/tea/recorder";
+ * import { breadcrumbsFromTrace } from "./internal/persistence/recorder"; // internal module
  * for (const b of breadcrumbsFromTrace(rec.dump())) Sentry.addBreadcrumb(b);
  * ```
  *
@@ -290,4 +287,4 @@ declare function breadcrumbsFromTrace<S, M extends {
     type: string;
 }>(trace: Trace<S, M>, opts?: BreadcrumbsOptions<M>): TraceBreadcrumb[];
 
-export { type BreadcrumbsOptions, type Recorder, type RecorderOptions, type Trace, type TraceAttachment, type TraceBreadcrumb, breadcrumbsFromTrace, parseJSONL, recorder, traceAttachment };
+export { type BreadcrumbsOptions as B, type RecorderOptions as R, type Trace as T, type Recorder as a, type TraceAttachment as b, type TraceBreadcrumb as c, breadcrumbsFromTrace as d, parseJSONL as p, recorder as r, traceAttachment as t };

package/dist/index-HSYgG2Yt.d.ts

@@ -0,0 +1,380 @@
+import { S as Sub, c as SubId } from './core-DnzqWy6u.js';
+import { S as SubscribeHandler } from './types-BseNPIhr.js';
+
+/**
+ * internal/resilience/cache — a TTL cache as pure state, PLUS a periodic eviction Sub.
+ *
+ * Same pure-state-ops shape as `../../idempotency/` and
+ * `../../work-queue/ops.ts`: a state type plus pure transition functions. Host-
+ * agnostic by construction — no `Date.now()`, no timers, no I/O inside the ops.
+ * The caller injects the clock (`nowMs`) and folds the result through its own
+ * reducer, keeping the store inside TEA's invariant 2 (transitions are pure:
+ * same inputs → same outputs) so a consumer can exercise it with `replay`
+ * without a fake clock.
+ *
+ * Every op returns a NEW cache value and never mutates its input (invariant 1 —
+ * state is a value, not a place). `get` / `has` are read-shaped; `set` /
+ * `remove` / `evictExpired` return a new cache.
+ *
+ * **Distinct from `/idempotency`.** Both are TTL-bounded key maps, but they
+ * answer different questions and so carry different shapes:
+ *
+ *   - `/idempotency` is DEDUPE-focused — "have I already processed this key?"
+ *     TTL is a single store-level policy (`ttlMs`), each entry stores the
+ *     `atMs` it was remembered at, and expiry is derived (`now - atMs >=
+ *     ttlMs`). It carries an `order` ledger + `capacity` because the use case
+ *     (webhook receivers, retried messages) needs bounded LRU eviction.
+ *   - `/cache` is RETRIEVAL-focused — "what is the value for this key right
+ *     now?" TTL is set PER ENTRY at write time: `set(key, value, nowMs,
+ *     ttlMs)` bakes the absolute `expiresAtMs = nowMs + ttlMs` into the entry.
+ *     Different keys can carry different lifetimes (a hot key cached for 1s, a
+ *     cold one for 1h) — the dimension idempotency's single store-level
+ *     `ttlMs` cannot express. No `order`, no `capacity`: a cache bounds itself
+ *     by TTL + periodic eviction, not by LRU count.
+ *
+ * The eviction Sub is the "eviction is a Msg" half: a `setInterval`-shaped Sub
+ * (composed directly on `fromInterval`, from `src/subs/`) that periodically
+ * dispatches a `cache_evict` Msg the consumer's reducer handles by calling
+ * `evictExpired`. Time still never enters the reducer — the Sub fires the Msg,
+ * the reducer reads `nowMs` off the Msg (the consumer stamps it at the Sub
+ * boundary), and `evictExpired` does the pure drop.
+ *
+ * Internal to the package (`src/internal/resilience/`), not a published
+ * subpath (#46); same one-shape-per-module rule as `work-queue`, `idempotency`,
+ * and `rate-limit`.
+ */
+
+/**
+ * A cached entry: the `value` and the absolute clock reading `expiresAtMs` it
+ * expires at. Unlike `/idempotency`'s entry (which stores `atMs` and derives
+ * expiry from a store-level `ttlMs`), the expiry instant is baked in at write
+ * time — so per-entry TTLs are a first-class capability. Both fields are plain
+ * data so the whole cache is trivially JSON-serializable into a consumer's
+ * `Store<S>`.
+ */
+interface CacheEntry<V> {
+    readonly value: V;
+    readonly expiresAtMs: number;
+}
+/**
+ * The cache: a map of `key → entry`. No `order` ledger and no `capacity` (cf.
+ * `/idempotency`) — a TTL cache bounds itself by expiry + periodic eviction,
+ * not by LRU count. Each entry carries its own `expiresAtMs`, so the cache
+ * needs no store-level TTL policy field.
+ */
+interface TtlCache<V> {
+    readonly entries: Readonly<Record<string, CacheEntry<V>>>;
+}
+/** Create an empty cache. */
+declare function initCache<V>(): TtlCache<V>;
+/**
+ * The cached `value` for `key` iff present AND unexpired at `nowMs`, else
+ * `undefined`. An expired entry reads as absent even though it is physically
+ * still in `entries` until the next `evictExpired` (or an overwriting `set`)
+ * drops it. PURE — reads only, never mutates.
+ */
+declare function get<V>(cache: TtlCache<V>, key: string, nowMs: number): V | undefined;
+/**
+ * True iff `key` is present AND unexpired at `nowMs`. The boolean sibling of
+ * `get` for callers that only need presence, not the value. PURE.
+ */
+declare function has<V>(cache: TtlCache<V>, key: string, nowMs: number): boolean;
+/**
+ * Write `key → value` with an absolute expiry of `nowMs + ttlMs`. Re-`set`ting
+ * an existing key overwrites both the value and the expiry — the TTL clock
+ * restarts from the new `nowMs`. PURE — returns a new cache; the input is
+ * untouched (a fresh shallow copy of `entries`).
+ */
+declare function set<V>(cache: TtlCache<V>, key: string, value: V, nowMs: number, ttlMs: number): TtlCache<V>;
+/**
+ * Drop `key` regardless of expiry. PURE — returns a new cache; the input is
+ * untouched. Removing an absent key returns an equivalent cache (the shallow
+ * copy still happens, but no entry is dropped).
+ */
+declare function remove<V>(cache: TtlCache<V>, key: string): TtlCache<V>;
+/**
+ * Physically drop every entry expired at `nowMs` (`nowMs >= expiresAtMs`).
+ * Returns a NEW cache with the survivors. This is the pure work the eviction
+ * Sub's `cache_evict` Msg triggers — `get` / `has` already treat expired
+ * entries as absent, so eviction is purely a memory-reclaim pass, not a
+ * correctness one. PURE — the input cache is never mutated.
+ */
+declare function evictExpired<V>(cache: TtlCache<V>, nowMs: number): TtlCache<V>;
+/**
+ * The Msg the eviction Sub dispatches each tick. `id` is the Sub's own id so a
+ * consumer with multiple caches can route the tick to the matching cache. The
+ * reducer reads `Date.now()`-free time by stamping `nowMs` itself at the Sub
+ * boundary if needed; the canonical reducer cell is
+ * `cache_evict: (s) => [{ ...s, cache: evictExpired(s.cache, nowMs) }, []]`.
+ */
+interface CacheEvictMsg {
+    readonly type: "cache_evict";
+    readonly id: string;
+}
+/** Construct a `cache_evict` Msg for the cache identified by `id`. */
+declare function cacheEvictMsg(id: string): CacheEvictMsg;
+/**
+ * The Sub shape the eviction factory installs: a `setInterval`-shaped Sub
+ * carrying its tick period (`intervalMs`) per the substrate's
+ * reconcile-by-id-with-data-on-the-Sub contract. `type: "cache"` is the
+ * lowercase source-noun Sub convention (canon §2.5 / naming-style).
+ */
+type CacheEvictionSub = Sub<"cache"> & {
+    readonly intervalMs: number;
+};
+/**
+ * Declare an eviction Sub for the cache identified by `id`, ticking every
+ * `everyMs`. Drop the result into `subscriptions(state)`:
+ *
+ *   subscriptions: (s) => [cacheEvictionSub("session-cache", 30_000)]
+ *
+ * Same id ⇒ same running interval across transitions (no reconcile churn);
+ * changing `everyMs` alone will NOT re-arm the timer (the substrate leaves a
+ * same-id Sub running) — change the `id` too if the period must change. This
+ * mirrors `fromInterval`'s data-on-the-Sub tradeoff exactly.
+ */
+declare function cacheEvictionSub(id: string, everyMs: number): CacheEvictionSub;
+/**
+ * The `subscribe` cell for the eviction Sub. Assign it to
+ * `machine.subscribe.cache`:
+ *
+ *   subscribe: { cache: cacheEvictionSubscribe }
+ *
+ * Composed directly on `fromInterval` — it owns the `setInterval` /
+ * `clearInterval` lifecycle; this cell only pins the Msg the tick dispatches
+ * (`cacheEvictMsg(sub.id)`). The cleanup `fromInterval` returns stops the
+ * interval when the Sub is reconciled out (the cache's state exits the phase
+ * that declared it).
+ */
+declare const cacheEvictionSubscribe: SubscribeHandler<CacheEvictionSub, CacheEvictMsg, unknown>;
+
+/**
+ * internal/resilience/deadline — a one-shot Sub that fires when an ABSOLUTE wall-clock
+ * deadline is reached.
+ *
+ * Generalizes the recurring "auto-fail a machine at T+N" / "15-minute stale
+ * guard" pattern: a Sub whose `subscriptions(state)` returns it only while the
+ * deadline should be armed, and which dispatches a single `DeadlineExceeded`
+ * Msg when the wall clock crosses `atMs`.
+ *
+ * Difference from `fromTimeout` (relative — "fire after N ms"): a deadline is
+ * an ABSOLUTE target. The delay is computed at subscribe time as
+ * `max(0, atMs - Date.now())`. The consequence that matters: subscribing LATE —
+ * e.g. after a `Store` rehydrate that resumes a machine whose deadline was set
+ * before the page reloaded — still fires at the correct absolute moment,
+ * because the remaining delay is recomputed from the current clock, not stored
+ * in the Sub. A deadline already in the past at subscribe time yields delay `0`,
+ * so `setTimeout(fn, 0)` fires on the NEXT tick (never synchronously inside the
+ * reconcile pass — the substrate must finish wiring all subs before any Msg
+ * lands).
+ *
+ * Composition over reinvention: the timer lifecycle is `fromTimeout`'s, not
+ * redrawn here. `deadlineSub` produces the Sub literal carrying `atMs`; the
+ * `subscribe` handler (`subscribeDeadline`) translates `atMs` → a relative delay
+ * and delegates the `setTimeout` / `clearTimeout` to `fromTimeout`. The clock
+ * read (`Date.now()`) lives only in the subscribe handler — never in a reducer
+ * (invariant 2) — and is exercised in tests via vitest fake timers, matching
+ * the no-injection convention of the `fromTimeout` / `fromInterval` exemplars.
+ *
+ * WHAT BACKS THE TIMER IS THE HOST'S CHOICE. `setTimeout` is the universal
+ * default, but it is not universal: a Durable Object that hibernates has no
+ * live `setTimeout` to wake it, so its deadline must be backed by a `do_alarm`
+ * registered on the alarm registry; a test host wants a fake-timer schedule.
+ * That backing is the `ArmTimer` seam — `subscribeWith(armTimer)` builds the
+ * `subscribe.deadline` handler from a host-plugged timer, and `subscribeDeadline`
+ * IS `subscribeWith(setTimeoutArmTimer())`. One deadline surface, three hosts;
+ * there is no second Sub type and no second `atMs` anchor to keep in sync.
+ *
+ * The anchor is what makes the seam safe. `atMs` is ABSOLUTE, so whatever backs
+ * it arms to a fixed wall-clock instant: the host computes the gap itself
+ * (`atMs - Date.now()`), and on a host that just rehydrated after hibernation
+ * that gap is the SHRUNKEN remainder — the deadline honours the original target
+ * rather than resetting to a fresh full-length window.
+ *
+ * Strengthens invariant 4 (external time is a subscription — the deadline is a
+ * `Sub` the runtime reconciles, never a `setTimeout` leaked into a reducer) and
+ * invariant 7 (identity is explicit — the Sub carries a stable `SubId`, so the
+ * reconcile pass leaves it running across transitions instead of churning it).
+ */
+
+/**
+ * The Sub variant a deadline produces. `atMs` is the absolute target — epoch
+ * milliseconds (the `Date.now()` / `Date.parse(...)` scale), NOT a relative
+ * delay. It rides on the Sub so the reconcile pass keys identity by `id`
+ * alone: the same `id` across transitions means the same armed timer, even if
+ * a later `subscriptions(state)` recomputes the literal.
+ *
+ * Lowercase `"deadline"` discriminant per the Sub naming convention (a source
+ * noun that doubles as the SubId family); same shape family as the
+ * `TimeoutSubData` the `fromTimeout` factory consumes.
+ */
+type DeadlineSub<N extends string | undefined = undefined> = Sub<"deadline"> & {
+    readonly atMs: number;
+} & DeadlineOpts<N>;
+/**
+ * Additive options the `deadlineSub` factory folds onto the Sub literal. This
+ * is the extension seam (invariant 5 — composition by reduction): future fields
+ * — `repeatMs` for a re-arming deadline, `jitterMs` for spread, etc. — land HERE
+ * as optional members, and every existing call site keeps compiling because the
+ * factory's third parameter is optional and the fields are `readonly` optionals
+ * on `DeadlineSub`. Callers are insulated from the concrete `DeadlineSub` shape:
+ * they ask for what they need by name, never positionally, so a shape extension
+ * never rewrites the ~13 `deadlineSub(id, atMs)` call sites.
+ *
+ * The first field to land here is {@link DeadlineOpts.name} — the knob name the
+ * dispatched Msg tag is derived from — and it landed exactly that way: one
+ * optional member, zero rewritten call sites.
+ */
+type DeadlineOpts<N extends string | undefined = undefined> = {
+    /**
+     * The knob this deadline belongs to. Present → the dispatched Msg's tag is
+     * `` `${name}_deadline` ``; absent → the tag stays the bare
+     * `"deadline_exceeded"` every machine wired before this field is already
+     * handling. `N` is the name as a TYPE as well as a value, so a consumer's
+     * cell key and the Msg type are derived from one place and cannot drift.
+     *
+     * Name a deadline when a machine arms more than one family of them. The Sub
+     * *id* was already scoped (`` `${name}:deadline:${key}` ``); this scopes the
+     * Msg the Sub dispatches, which is what a reducer cell keys off.
+     */
+    readonly name?: N;
+};
+/**
+ * The Msg the deadline dispatches when the wall clock crosses `atMs`. Exported
+ * as a tagged shape so consumers can union it into their machine's Msg type and
+ * handle it in a reducer cell. `id` lets a reducer disambiguate WHICH deadline
+ * fired when a machine arms several at once; `atMs` echoes the target the timer
+ * was scheduled against (useful for assertions / observability).
+ *
+ * Snake-shaped `"deadline_exceeded"` matches the tagged-Msg style this module's
+ * orchestrator requested; the actor-in-name PascalCase convention
+ * (`TimerFiredDeadline`) is the consumer's to apply at their own boundary if
+ * they prefer — `deadlineExceeded(...)` only fixes the wire shape, not the
+ * consumer's local dialect.
+ */
+type DeadlineExceeded<N extends string | undefined = undefined> = {
+    readonly type: DeadlineMsgType<N>;
+    readonly id: string;
+    readonly atMs: number;
+};
+/**
+ * The dispatched Msg's tag, derived from the deadline's optional name. A named
+ * deadline speaks `` `${N}_deadline` ``; an unnamed one speaks the bare
+ * `"deadline_exceeded"` literal, which is what `DeadlineExceeded` with no type
+ * argument still means — so every machine wired before the name existed keeps
+ * the exact type it had.
+ */
+type DeadlineMsgType<N extends string | undefined> = N extends string ? `${N}_deadline` : "deadline_exceeded";
+/**
+ * Build a deadline Sub literal. Pure data — no clock read, no timer; the timer
+ * is armed later by the `subscribe` cell. `id` is branded via `subId(...)` so
+ * accidental raw-string drift fails at the type level (invariant 7).
+ *
+ * Return the result directly from `subscriptions(state)` while the deadline
+ * should be armed; drop it (return `[]`, or stop returning this id) to disarm —
+ * the reconcile pass calls the cleanup, clearing the pending timer before it
+ * fires. That is the "cancel on state exit" lifecycle, identical to
+ * `fromTimeout`'s.
+ *
+ * @param id   Stable identity for this deadline. Same `id` across transitions =
+ *             same armed timer (no churn). Use distinct ids for distinct
+ *             deadlines on the same machine.
+ * @param atMs Absolute target in epoch milliseconds (e.g. `Date.now() + 900_000`
+ *             for a 15-minute guard, or a persisted `expiresAt`).
+ * @param opts Optional additive fields folded onto the Sub literal (see
+ *             {@link DeadlineOpts}). Omit it for the common case; pass it when a
+ *             future field (e.g. `repeatMs`) needs to ride on the deadline. The
+ *             optionality is the future-proofing seam — extending the shape
+ *             never breaks an existing `deadlineSub(id, atMs)` call site.
+ */
+declare function deadlineSub<N extends string | undefined = undefined>(id: string, atMs: number, opts?: DeadlineOpts<N>): DeadlineSub<N>;
+/**
+ * The host-plugged timer backing. Given the deadline's stable `id`, its
+ * absolute `atMs`, and the Msg to fire, arm the platform-appropriate timer
+ * (DO alarm registry, `setTimeout`, fake timer) and return a cleanup that
+ * cancels the pending fire.
+ *
+ * `id` is the Sub's reconcile id — a registry-backed host (the DO alarm slot)
+ * keys its entry on `id` so the cleanup deletes the EXACT entry the substrate
+ * reconciled. A `setTimeout`-backed host ignores `id` (the closure holds the
+ * handle).
+ *
+ * The host computes the gap itself: `atMs - Date.now()` is the REMAINING time.
+ * On a host that just rehydrated after hibernation that gap is the shrunken
+ * remainder — the deadline is NOT reset to its full length. That recomputation
+ * is the reason `atMs` rides on the Sub as an absolute instant rather than a
+ * delay: the anchor is what every backing agrees on.
+ */
+type ArmTimer<M> = (id: SubId, atMs: number, msg: M, dispatch: (msg: M) => void) => () => void;
+/**
+ * Build the `subscribe["deadline"]` cell from a host-plugged `armTimer`. This
+ * module owns the Sub shape, the anchor, and the Msg; the HOST owns what backs
+ * the timer. The returned handler reads `id` + `atMs` off the Sub, builds the
+ * `deadlineExceeded(...)` Msg, and hands all three to `armTimer`.
+ *
+ * Use it when `setTimeout` is the wrong backing — most concretely a Durable
+ * Object, which hibernates and must register a `do_alarm` instead:
+ *
+ *   subscribe: {
+ *     deadline: subscribeWith((id, atMs, msg, dispatch) =>
+ *       alarms.register(id, atMs, () => dispatch(msg)),
+ *     ),
+ *   }
+ *
+ * For the `setTimeout` default, use {@link subscribeDeadline} — it is exactly
+ * `subscribeWith(setTimeoutArmTimer())`, so there is one deadline surface and
+ * one anchor, not a second one per host.
+ */
+declare function subscribeWith<N extends string | undefined = undefined>(armTimer: ArmTimer<DeadlineExceeded<N>>): SubscribeHandler<DeadlineSub<N>, DeadlineExceeded<N>, unknown>;
+/**
+ * The `setTimeout` timer backing — for node / browser / any host whose timer is
+ * a plain `setTimeout`. Arms for the REMAINING time (`max(0, atMs - Date.now())`,
+ * floored at 0 so an already-past deadline fires on the NEXT tick rather than
+ * synchronously inside the reconcile pass), so a deadline re-derived after a
+ * rehydrate fires at the original instant, not a fresh full window.
+ *
+ * Composes on `fromTimeout` rather than redrawing `setTimeout` /
+ * `clearTimeout`: this package has ONE timer lifecycle, and the arm-timer seam
+ * plugs into it instead of forking it. A hibernating host does NOT use this —
+ * it plugs its own `armTimer` (a `do_alarm` registration) into
+ * {@link subscribeWith}.
+ */
+declare function setTimeoutArmTimer<N extends string | undefined = undefined>(): ArmTimer<DeadlineExceeded<N>>;
+/**
+ * The `subscribe["deadline"]` handler for the DEFAULT `setTimeout` backing. Arms a
+ * one-shot timer for the remaining delay `max(0, atMs - Date.now())` and
+ * dispatches `deadlineExceeded(...)` when it fires; returns a cleanup that
+ * clears the pending timer.
+ *
+ * It is `subscribeWith(setTimeoutArmTimer())` — the default backing named, not
+ * a separate implementation, so the host-plugged path and the default path can
+ * never disagree about the anchor.
+ *
+ * Assign directly to a `Subscribe` handler:
+ *
+ *   subscribe: {
+ *     deadline: subscribeDeadline,
+ *   }
+ *
+ * Generic in the deadline's name so ONE handler serves every knob in a machine:
+ * the tag it dispatches is read off the Sub's own `name`, so a machine mounting
+ * a named knob beside an unnamed one wires this same cell once and each Sub
+ * still dispatches its own tag.
+ */
+declare const subscribeDeadline: <N extends string | undefined = undefined>(sub: DeadlineSub<N>, ctx: unknown, dispatch: (msg: DeadlineExceeded<N>) => void) => () => void;
+/**
+ * Construct the Msg the deadline dispatches. Exported so consumers can build /
+ * assert the same shape (and so the subscribe cell and tests share one
+ * constructor rather than two literals that can drift).
+ */
+declare function deadlineExceeded<N extends string | undefined = undefined>(id: string, atMs: number, name?: N): DeadlineExceeded<N>;
+/**
+ * The one place the named tag is spelled. `undefined` → the bare
+ * `"deadline_exceeded"` literal; a name → `` `${name}_deadline` ``. Exported so
+ * a consumer keying a reducer cell off a named deadline derives the key from
+ * the same function the Sub dispatches through, instead of re-spelling the
+ * template and drifting.
+ */
+declare function deadlineMsgType<N extends string | undefined>(name?: N): DeadlineMsgType<N>;
+
+export { type ArmTimer as A, type CacheEvictionSub as C, type DeadlineExceeded as D, type TtlCache as T, type DeadlineSub as a, deadlineSub as b, type CacheEvictMsg as c, deadlineExceeded as d, type CacheEntry as e, type DeadlineMsgType as f, type DeadlineOpts as g, cacheEvictMsg as h, cacheEvictionSub as i, cacheEvictionSubscribe as j, deadlineMsgType as k, evictExpired as l, get as m, has as n, initCache as o, set as p, setTimeoutArmTimer as q, remove as r, subscribeDeadline as s, subscribeWith as t };

package/dist/{monitored-run/index.d.ts → index-KXqTRJyb.d.ts}

@@ -1,15 +1,10 @@
-import { DeadlineExceeded, DeadlineSub } from '../deadline/index.js';
-export { deadlineSub, subscribeDeadline } from '../deadline/index.js';
-import { I as Interpret, C as Cmd } from '../core-Co0LWkIA.js';
-import { SnapshotWriteCmd, SnapshotState, SnapshotStore, SnapshotSavedMsg, SnapshotFailedMsg, SnapshotLoadedMsg, SnapshotLoadFailedMsg, SnapshotLoadCmd } from '../snapshot/index.js';
-import { QueueItem } from '../work-queue/index.js';
-import '../types-XS_miRnB.js';
-import 'zod';
-import '../runtime-types-CNLmhWif.js';
-import 'better-result';
+import { I as Interpret, C as Cmd } from './core-DnzqWy6u.js';
+import { S as SnapshotWriteCmd, a as SnapshotState, b as SnapshotStore, c as SnapshotSavedMsg, d as SnapshotFailedMsg, e as SnapshotLoadedMsg, f as SnapshotLoadFailedMsg, g as SnapshotLoadCmd } from './index-ZCMhnVKN.js';
+import { D as DeadlineExceeded, a as DeadlineSub } from './index-HSYgG2Yt.js';
+import { Q as QueueItem } from './index-CSyMYDAB.js';
 
 /**
- * @demlik/tea/monitored-run — a long-running operation that is BOTH staged and
+ * internal/flow/monitored-run — a long-running operation that is BOTH staged and
  * watched: an ordered stage pipeline whose POSITION survives eviction, wrapped
  * by a no-progress safety deadline and (optionally) a periodic durable
  * checkpoint.
@@ -46,7 +41,7 @@ import 'better-result';
  *
  * ## Why the run lifecycle is INLINE (run-tracker not extracted)
  *
- * The phase union (`idle` / `running` / `stale` / `done` / `failed`, a
+ * The phase union (`idle` / `running` / `stale` / `done` / `failed` / `cancelled`, a
  * discriminated union carrying only each phase's own data) and its bookkeeping
  * (`runId`, `startedAt`, `lastProgressAt`, `progressSeq`) live directly on this
  * slice rather than behind a `run-tracker` sub-knob.
@@ -203,10 +198,19 @@ interface RunCore<Stage> {
  *   - `failed`  — terminal failure; the typed `failure` reason rides ONLY this
  *                 arm, so it is present iff `phase === "failed"` BY CONSTRUCTION —
  *                 there is no nullable side field to keep in sync.
+ *   - `cancelled` — the consumer stopped the run from outside (`cancel`). Its own
+ *                 phase rather than a `RunFailure` reason, on the same argument
+ *                 that keeps `stale` a phase: a caller who asked for the stop did
+ *                 not suffer a failure, and every "did this fail?" reader would
+ *                 otherwise have to except one reason. Terminal, so it re-enters
+ *                 no verb and arms no watchdog.
  *
  * `runId` is the host-minted run identity, stamped at `start` (the machine never
  * mints — see the audit seed's "run identity is host-minted"). It rides every
- * started phase, but not `idle`.
+ * started phase, but not `idle`. `cancelled` is the one phase reachable from BOTH
+ * sides of that line, so its `runId` is `string | null`: `null` says the run was
+ * cancelled before it ever started and there was no identity to mint, which is a
+ * different fact from a cancelled live run and stays a different value.
  */
 type MonitoredRunState<Stage> = (RunCore<Stage> & {
     readonly phase: "idle";
@@ -223,7 +227,26 @@ type MonitoredRunState<Stage> = (RunCore<Stage> & {
     readonly phase: "failed";
     readonly runId: string;
     readonly failure: RunFailure<Stage>;
+}) | (RunCore<Stage> & {
+    readonly phase: "cancelled";
+    readonly runId: string | null;
+    readonly at: number;
 });
+/**
+ * The ENDED phases — a run that finished (`done`) or was stopped from outside
+ * (`cancelled`). Every arm here was started or explicitly stopped, so `idle` is
+ * out and `runId` is present on the whole union: a consumer holding one of these
+ * reads the run identity without a `phase` guard the value can never fail.
+ *
+ * It is the resolved half of a drive: a promise that resolves only on an ended
+ * run should say so in its type rather than resolve `MonitoredRunState` and
+ * leave every reader to re-prove the `idle` arm impossible (#155). `cancelled`
+ * keeps its `string | null` `runId` unchanged — a run cancelled before it ever
+ * started genuinely has no identity, and that stays a different value here.
+ */
+type EndedRun<Stage> = Extract<MonitoredRunState<Stage>, {
+    readonly phase: "done" | "cancelled";
+}>;
 /**
  * The outcome a consumer reports to `advance`: the current stage either
  * succeeded (retire it, claim the next) or failed (terminate the run). Plain
@@ -259,6 +282,7 @@ declare function createMonitoredRun<Stage, V = unknown>(config?: MonitoredRunCon
     start: (s: MonitoredRunState<Stage>, runId: string, at: number) => readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]];
     progress: (s: MonitoredRunState<Stage>, payload: V, at: number) => readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]];
     markStale: (s: MonitoredRunState<Stage>) => readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]];
+    cancel: (s: MonitoredRunState<Stage>, at: number) => readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]];
     advance: (s: MonitoredRunState<Stage>, payload: V, result: StageResult, at: number) => readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]];
     onDeadline: (s: MonitoredRunState<Stage>, msg: MonitoredRunTimerMsg) => readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]];
     boot: (s: MonitoredRunState<Stage>, at: number) => readonly [MonitoredRunState<Stage>, readonly MonitoredRunCmd<V>[]];
@@ -276,4 +300,4 @@ declare function liftRun<S extends {
     run: MonitoredRunState<Stage>;
 }, Stage, C extends Cmd>(state: S, [slice, cmds]: readonly [MonitoredRunState<Stage>, readonly C[]]): readonly [S, readonly C[]];
 
-export { DeadlineExceeded, DeadlineSub, type MonitoredRunCmd, type MonitoredRunConfig, type MonitoredRunPorts, type MonitoredRunState, type MonitoredRunTimerMsg, type RunFailure, SnapshotSavedMsg, SnapshotWriteCmd, type StageResult, createMonitoredRun, liftRun };
+export { type EndedRun as E, type MonitoredRunCmd as M, type RunFailure as R, type StageResult as S, type MonitoredRunState as a, type MonitoredRunConfig as b, type MonitoredRunPorts as c, type MonitoredRunTimerMsg as d, createMonitoredRun as e, liftRun as l };