@demlik/tea 0.1.0

package/dist/idempotency/index.d.ts

@@ -0,0 +1,131 @@
+/**
+ * @demlik/tea/idempotency — dedupe-by-key + last-result cache as pure state + ops.
+ *
+ * Same shape as `@demlik/tea/work-queue`'s `ops.ts` and `@demlik/tea/rate-limit`:
+ * a state type plus pure transition functions. Host-agnostic by construction —
+ * no `Date.now()`, no timers, no I/O. The caller injects the clock (`nowMs`)
+ * and wires the result into its own reducer / interpret. This keeps the store
+ * inside TEA's invariant 2 (transitions are pure: same inputs → same outputs,
+ * no `Date.now`) so a consumer can fold it through `update` and exercise it
+ * with `replay` / the pbt fold without a fake clock.
+ *
+ * Every op returns a NEW store value and never mutates its input (invariant 1 —
+ * state is a value, not a place). `seen` / `recall` are read-shaped predicates;
+ * `remember` / `evictExpired` return a new store.
+ *
+ * The use case: a webhook receiver, a retried queue message, or a repeated user
+ * action arrives carrying an idempotency key. `seen(store, key, now)` answers
+ * "did I already process this?"; `recall(store, key, now)` returns the cached
+ * result so the duplicate request gets the SAME response the original produced
+ * rather than re-running the side effect. `remember(store, key, value, now)`
+ * records the key + its result after the first run.
+ *
+ * Two eviction policies keep the store bounded, both injected at `initStore`:
+ *
+ *   - **`ttlMs`** — an entry expires `ttlMs` after the `atMs` it was remembered
+ *     at. `seen` / `recall` treat an expired entry as absent; `evictExpired`
+ *     (and every `remember`) physically drops it. Without a TTL, entries live
+ *     until evicted by capacity. The cutoff is half-open: an entry exactly
+ *     `ttlMs` old is expired (`age >= ttlMs` drops it), matching `rate-limit`'s
+ *     window edge — a key remembered at `t` no longer counts at `t + ttlMs`.
+ *   - **`capacity`** — at most `capacity` entries are retained. When a
+ *     `remember` would push the count past `capacity` (after expiry eviction),
+ *     the OLDEST entries by insertion `order` are dropped until the count fits.
+ *     Without a capacity, the store grows unbounded (TTL alone bounds it).
+ *
+ * `order` is the insertion-order index that capacity eviction reads — the keys
+ * oldest-first. It is the store's own LRU-by-insertion ledger, kept in lockstep
+ * with `entries` so `entries` never needs to be sorted to find the oldest.
+ *
+ * **Overwrite semantics** (decided + pinned by tests): re-`remember`ing an
+ * existing key is an UPDATE, not a no-op. It (1) overwrites `value`, (2)
+ * refreshes `atMs` to the new `nowMs` — so the TTL clock restarts and a
+ * frequently-seen key never expires — and (3) moves the key to the NEWEST
+ * position in `order` — so capacity eviction treats a re-remembered key as
+ * fresh, not as a stale candidate for eviction. This makes `remember` behave
+ * like "touch": a key actively being re-seen is kept alive on both the TTL and
+ * capacity axes.
+ *
+ * NOT exported from the package root — reached via the `@demlik/tea/idempotency`
+ * subpath, same one-shape-per-package rule as `work-queue`, `rate-limit`, and
+ * `do`.
+ */
+/**
+ * A cached entry: the result `value` the original request produced and the
+ * clock reading `atMs` it was remembered at. `atMs` is the TTL anchor — expiry
+ * is measured from here, and a re-`remember` refreshes it. Both fields are
+ * plain data so the whole store is trivially JSON-serializable into a
+ * consumer's `Store<S>`.
+ */
+interface IdempotencyEntry<V> {
+    readonly value: V;
+    readonly atMs: number;
+}
+/**
+ * The dedupe store: a map of `key → entry`, an insertion-`order` ledger
+ * (oldest-first) that capacity eviction reads, and the two optional bounds.
+ *
+ * `entries` and `order` are kept in lockstep — every key in `order` has an
+ * entry and vice versa. `capacity` / `ttlMs` are carried on the store (not
+ * passed per-op) so a single value fully describes the policy; a consumer
+ * persists the store and rehydrates the same bounds without re-deriving them.
+ */
+interface IdempotencyStore<V> {
+    readonly entries: Readonly<Record<string, IdempotencyEntry<V>>>;
+    readonly order: readonly string[];
+    readonly capacity?: number;
+    readonly ttlMs?: number;
+}
+/**
+ * Create an empty store. `capacity` and `ttlMs` are both optional — omit both
+ * for an unbounded cache, supply either or both to bound by count, age, or
+ * both. Stored on the returned value so every later op reads the policy off
+ * the store rather than from a re-passed argument.
+ */
+declare function initStore<V>(opts?: {
+    capacity?: number;
+    ttlMs?: number;
+}): IdempotencyStore<V>;
+/**
+ * True iff `key` is present AND not expired at `nowMs`. This is the dedupe
+ * predicate: a webhook / retried message / repeated action whose key returns
+ * `true` has already been processed and should be short-circuited (paired with
+ * `recall` to return the original result). PURE — reads only, never mutates.
+ */
+declare function seen<V>(store: IdempotencyStore<V>, key: string, nowMs: number): boolean;
+/**
+ * The cached `value` for `key` if present and unexpired at `nowMs`, else
+ * `undefined`. Use after `seen` returns `true` to replay the original result to
+ * a duplicate request. An expired entry reads as absent (returns `undefined`)
+ * even though it is physically still in `entries` until the next `remember` /
+ * `evictExpired` drops it. PURE — reads only, never mutates.
+ */
+declare function recall<V>(store: IdempotencyStore<V>, key: string, nowMs: number): V | undefined;
+/**
+ * Drop every entry expired at `nowMs` (older than `ttlMs`). Returns a NEW store
+ * with the survivors; `order` is rebuilt to drop the same keys, preserving the
+ * relative insertion order of the survivors. A no-TTL store returns an
+ * equivalent store (nothing ages out). PURE — the input store is never mutated.
+ */
+declare function evictExpired<V>(store: IdempotencyStore<V>, nowMs: number): IdempotencyStore<V>;
+/**
+ * Record `key → value` at `nowMs`, then enforce both bounds. PURE — returns a
+ * new store; the input is untouched.
+ *
+ * Order of operations (each step matters):
+ *   1. **Expiry eviction** — drop everything older than `ttlMs` first, so an
+ *      expired key never occupies a capacity slot the new entry could take, and
+ *      a stale entry under the same `key` is cleared before the overwrite.
+ *   2. **Insert / overwrite** — write the new entry. If `key` already exists,
+ *      this is an UPDATE: `value` is overwritten, `atMs` is refreshed to
+ *      `nowMs` (restarting the TTL clock), and the key is moved to the NEWEST
+ *      position in `order` (removed from wherever it sat, appended at the end).
+ *      See the module-level "Overwrite semantics" note.
+ *   3. **Capacity eviction** — if the entry count now exceeds `capacity`, drop
+ *      the OLDEST keys by `order` until the count fits. Because step 2 moves a
+ *      re-remembered key to the newest position, an actively re-seen key is
+ *      never the eviction victim.
+ */
+declare function remember<V>(store: IdempotencyStore<V>, key: string, value: V, nowMs: number): IdempotencyStore<V>;
+
+export { type IdempotencyEntry, type IdempotencyStore, evictExpired, initStore, recall, remember, seen };

package/dist/idempotency/index.js

@@ -0,0 +1,58 @@
+// src/idempotency/index.ts
+function initStore(opts) {
+  return {
+    entries: {},
+    order: [],
+    capacity: opts?.capacity,
+    ttlMs: opts?.ttlMs
+  };
+}
+function isExpired(entry, nowMs, ttlMs) {
+  if (ttlMs === void 0) return false;
+  return nowMs - entry.atMs >= ttlMs;
+}
+function seen(store, key, nowMs) {
+  const entry = store.entries[key];
+  if (entry === void 0) return false;
+  return !isExpired(entry, nowMs, store.ttlMs);
+}
+function recall(store, key, nowMs) {
+  const entry = store.entries[key];
+  if (entry === void 0 || isExpired(entry, nowMs, store.ttlMs))
+    return void 0;
+  return entry.value;
+}
+function evictExpired(store, nowMs) {
+  if (store.ttlMs === void 0) return store;
+  const nextEntries = {};
+  const nextOrder = [];
+  for (const key of store.order) {
+    const entry = store.entries[key];
+    if (entry === void 0) continue;
+    if (isExpired(entry, nowMs, store.ttlMs)) continue;
+    nextEntries[key] = entry;
+    nextOrder.push(key);
+  }
+  return { ...store, entries: nextEntries, order: nextOrder };
+}
+function remember(store, key, value, nowMs) {
+  const pruned = evictExpired(store, nowMs);
+  const nextEntries = {
+    ...pruned.entries
+  };
+  nextEntries[key] = { value, atMs: nowMs };
+  const nextOrder = pruned.order.filter((k) => k !== key);
+  nextOrder.push(key);
+  if (store.capacity !== void 0) {
+    while (nextOrder.length > store.capacity) {
+      const oldest = nextOrder.shift();
+      if (oldest === void 0) break;
+      delete nextEntries[oldest];
+    }
+  }
+  return { ...store, entries: nextEntries, order: nextOrder };
+}
+
+export { evictExpired, initStore, recall, remember, seen };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/idempotency/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/idempotency/index.ts"],"names":[],"mappings":";AAuFO,SAAS,UAAa,IAAA,EAGL;AACtB,EAAA,OAAO;AAAA,IACL,SAAS,EAAC;AAAA,IACV,OAAO,EAAC;AAAA,IACR,UAAU,IAAA,EAAM,QAAA;AAAA,IAChB,OAAO,IAAA,EAAM;AAAA,GACf;AACF;AAUA,SAAS,SAAA,CACP,KAAA,EACA,KAAA,EACA,KAAA,EACS;AACT,EAAA,IAAI,KAAA,KAAU,QAAW,OAAO,KAAA;AAChC,EAAA,OAAO,KAAA,GAAQ,MAAM,IAAA,IAAQ,KAAA;AAC/B;AAQO,SAAS,IAAA,CACd,KAAA,EACA,GAAA,EACA,KAAA,EACS;AACT,EAAA,MAAM,KAAA,GAAQ,KAAA,CAAM,OAAA,CAAQ,GAAG,CAAA;AAC/B,EAAA,IAAI,KAAA,KAAU,QAAW,OAAO,KAAA;AAChC,EAAA,OAAO,CAAC,SAAA,CAAU,KAAA,EAAO,KAAA,EAAO,MAAM,KAAK,CAAA;AAC7C;AASO,SAAS,MAAA,CACd,KAAA,EACA,GAAA,EACA,KAAA,EACe;AACf,EAAA,MAAM,KAAA,GAAQ,KAAA,CAAM,OAAA,CAAQ,GAAG,CAAA;AAC/B,EAAA,IAAI,UAAU,MAAA,IAAa,SAAA,CAAU,KAAA,EAAO,KAAA,EAAO,MAAM,KAAK,CAAA;AAC5D,IAAA,OAAO,MAAA;AACT,EAAA,OAAO,KAAA,CAAM,KAAA;AACf;AAQO,SAAS,YAAA,CACd,OACA,KAAA,EACqB;AACrB,EAAA,IAAI,KAAA,CAAM,KAAA,KAAU,MAAA,EAAW,OAAO,KAAA;AACtC,EAAA,MAAM,cAAmD,EAAC;AAC1D,EAAA,MAAM,YAAsB,EAAC;AAG7B,EAAA,KAAA,MAAW,GAAA,IAAO,MAAM,KAAA,EAAO;AAC7B,IAAA,MAAM,KAAA,GAAQ,KAAA,CAAM,OAAA,CAAQ,GAAG,CAAA;AAC/B,IAAA,IAAI,UAAU,MAAA,EAAW;AACzB,IAAA,IAAI,SAAA,CAAU,KAAA,EAAO,KAAA,EAAO,KAAA,CAAM,KAAK,CAAA,EAAG;AAC1C,IAAA,WAAA,CAAY,GAAG,CAAA,GAAI,KAAA;AACnB,IAAA,SAAA,CAAU,KAAK,GAAG,CAAA;AAAA,EACpB;AACA,EAAA,OAAO,EAAE,GAAG,KAAA,EAAO,OAAA,EAAS,WAAA,EAAa,OAAO,SAAA,EAAU;AAC5D;AAoBO,SAAS,QAAA,CACd,KAAA,EACA,GAAA,EACA,KAAA,EACA,KAAA,EACqB;AAErB,EAAA,MAAM,MAAA,GAAS,YAAA,CAAa,KAAA,EAAO,KAAK,CAAA;AAKxC,EAAA,MAAM,WAAA,GAAmD;AAAA,IACvD,GAAG,MAAA,CAAO;AAAA,GACZ;AACA,EAAA,WAAA,CAAY,GAAG,CAAA,GAAI,EAAE,KAAA,EAAO,MAAM,KAAA,EAAM;AACxC,EAAA,MAAM,YAAY,MAAA,CAAO,KAAA,CAAM,OAAO,CAAC,CAAA,KAAM,MAAM,GAAG,CAAA;AACtD,EAAA,SAAA,CAAU,KAAK,GAAG,CAAA;AAKlB,EAAA,IAAI,KAAA,CAAM,aAAa,MAAA,EAAW;AAChC,IAAA,OAAO,SAAA,CAAU,MAAA,GAAS,KAAA,CAAM,QAAA,EAAU;AACxC,MAAA,MAAM,MAAA,GAAS,UAAU,KAAA,EAAM;AAC/B,MAAA,IAAI,WAAW,MAAA,EAAW;AAC1B,MAAA,OAAO,YAAY,MAAM,CAAA;AAAA,IAC3B;AAAA,EACF;AAEA,EAAA,OAAO,EAAE,GAAG,KAAA,EAAO,OAAA,EAAS,WAAA,EAAa,OAAO,SAAA,EAAU;AAC5D","file":"index.js","sourcesContent":["/**\n * @demlik/tea/idempotency — dedupe-by-key + last-result cache as pure state + ops.\n *\n * Same shape as `@demlik/tea/work-queue`'s `ops.ts` and `@demlik/tea/rate-limit`:\n * a state type plus pure transition functions. Host-agnostic by construction —\n * no `Date.now()`, no timers, no I/O. The caller injects the clock (`nowMs`)\n * and wires the result into its own reducer / interpret. This keeps the store\n * inside TEA's invariant 2 (transitions are pure: same inputs → same outputs,\n * no `Date.now`) so a consumer can fold it through `update` and exercise it\n * with `replay` / the pbt fold without a fake clock.\n *\n * Every op returns a NEW store value and never mutates its input (invariant 1 —\n * state is a value, not a place). `seen` / `recall` are read-shaped predicates;\n * `remember` / `evictExpired` return a new store.\n *\n * The use case: a webhook receiver, a retried queue message, or a repeated user\n * action arrives carrying an idempotency key. `seen(store, key, now)` answers\n * \"did I already process this?\"; `recall(store, key, now)` returns the cached\n * result so the duplicate request gets the SAME response the original produced\n * rather than re-running the side effect. `remember(store, key, value, now)`\n * records the key + its result after the first run.\n *\n * Two eviction policies keep the store bounded, both injected at `initStore`:\n *\n *   - **`ttlMs`** — an entry expires `ttlMs` after the `atMs` it was remembered\n *     at. `seen` / `recall` treat an expired entry as absent; `evictExpired`\n *     (and every `remember`) physically drops it. Without a TTL, entries live\n *     until evicted by capacity. The cutoff is half-open: an entry exactly\n *     `ttlMs` old is expired (`age >= ttlMs` drops it), matching `rate-limit`'s\n *     window edge — a key remembered at `t` no longer counts at `t + ttlMs`.\n *   - **`capacity`** — at most `capacity` entries are retained. When a\n *     `remember` would push the count past `capacity` (after expiry eviction),\n *     the OLDEST entries by insertion `order` are dropped until the count fits.\n *     Without a capacity, the store grows unbounded (TTL alone bounds it).\n *\n * `order` is the insertion-order index that capacity eviction reads — the keys\n * oldest-first. It is the store's own LRU-by-insertion ledger, kept in lockstep\n * with `entries` so `entries` never needs to be sorted to find the oldest.\n *\n * **Overwrite semantics** (decided + pinned by tests): re-`remember`ing an\n * existing key is an UPDATE, not a no-op. It (1) overwrites `value`, (2)\n * refreshes `atMs` to the new `nowMs` — so the TTL clock restarts and a\n * frequently-seen key never expires — and (3) moves the key to the NEWEST\n * position in `order` — so capacity eviction treats a re-remembered key as\n * fresh, not as a stale candidate for eviction. This makes `remember` behave\n * like \"touch\": a key actively being re-seen is kept alive on both the TTL and\n * capacity axes.\n *\n * NOT exported from the package root — reached via the `@demlik/tea/idempotency`\n * subpath, same one-shape-per-package rule as `work-queue`, `rate-limit`, and\n * `do`.\n */\n\n/**\n * A cached entry: the result `value` the original request produced and the\n * clock reading `atMs` it was remembered at. `atMs` is the TTL anchor — expiry\n * is measured from here, and a re-`remember` refreshes it. Both fields are\n * plain data so the whole store is trivially JSON-serializable into a\n * consumer's `Store<S>`.\n */\nexport interface IdempotencyEntry<V> {\n  readonly value: V;\n  readonly atMs: number;\n}\n\n/**\n * The dedupe store: a map of `key → entry`, an insertion-`order` ledger\n * (oldest-first) that capacity eviction reads, and the two optional bounds.\n *\n * `entries` and `order` are kept in lockstep — every key in `order` has an\n * entry and vice versa. `capacity` / `ttlMs` are carried on the store (not\n * passed per-op) so a single value fully describes the policy; a consumer\n * persists the store and rehydrates the same bounds without re-deriving them.\n */\nexport interface IdempotencyStore<V> {\n  readonly entries: Readonly<Record<string, IdempotencyEntry<V>>>;\n  readonly order: readonly string[];\n  readonly capacity?: number;\n  readonly ttlMs?: number;\n}\n\n/**\n * Create an empty store. `capacity` and `ttlMs` are both optional — omit both\n * for an unbounded cache, supply either or both to bound by count, age, or\n * both. Stored on the returned value so every later op reads the policy off\n * the store rather than from a re-passed argument.\n */\nexport function initStore<V>(opts?: {\n  capacity?: number;\n  ttlMs?: number;\n}): IdempotencyStore<V> {\n  return {\n    entries: {},\n    order: [],\n    capacity: opts?.capacity,\n    ttlMs: opts?.ttlMs,\n  };\n}\n\n/**\n * Whether `entry` (remembered at `entry.atMs`) is expired at `nowMs` under\n * `ttlMs`. Half-open: an entry exactly `ttlMs` old is expired (`age >= ttlMs`),\n * matching `rate-limit`'s window-edge cutoff. A `nowMs` before `atMs` (clock\n * skewed backwards) yields a negative age — never expired, the safe direction\n * (a duplicate is still deduped rather than re-run). When `ttlMs` is undefined\n * the entry never expires by age.\n */\nfunction isExpired<V>(\n  entry: IdempotencyEntry<V>,\n  nowMs: number,\n  ttlMs: number | undefined,\n): boolean {\n  if (ttlMs === undefined) return false;\n  return nowMs - entry.atMs >= ttlMs;\n}\n\n/**\n * True iff `key` is present AND not expired at `nowMs`. This is the dedupe\n * predicate: a webhook / retried message / repeated action whose key returns\n * `true` has already been processed and should be short-circuited (paired with\n * `recall` to return the original result). PURE — reads only, never mutates.\n */\nexport function seen<V>(\n  store: IdempotencyStore<V>,\n  key: string,\n  nowMs: number,\n): boolean {\n  const entry = store.entries[key];\n  if (entry === undefined) return false;\n  return !isExpired(entry, nowMs, store.ttlMs);\n}\n\n/**\n * The cached `value` for `key` if present and unexpired at `nowMs`, else\n * `undefined`. Use after `seen` returns `true` to replay the original result to\n * a duplicate request. An expired entry reads as absent (returns `undefined`)\n * even though it is physically still in `entries` until the next `remember` /\n * `evictExpired` drops it. PURE — reads only, never mutates.\n */\nexport function recall<V>(\n  store: IdempotencyStore<V>,\n  key: string,\n  nowMs: number,\n): V | undefined {\n  const entry = store.entries[key];\n  if (entry === undefined || isExpired(entry, nowMs, store.ttlMs))\n    return undefined;\n  return entry.value;\n}\n\n/**\n * Drop every entry expired at `nowMs` (older than `ttlMs`). Returns a NEW store\n * with the survivors; `order` is rebuilt to drop the same keys, preserving the\n * relative insertion order of the survivors. A no-TTL store returns an\n * equivalent store (nothing ages out). PURE — the input store is never mutated.\n */\nexport function evictExpired<V>(\n  store: IdempotencyStore<V>,\n  nowMs: number,\n): IdempotencyStore<V> {\n  if (store.ttlMs === undefined) return store;\n  const nextEntries: Record<string, IdempotencyEntry<V>> = {};\n  const nextOrder: string[] = [];\n  // Walk `order` (not `Object.keys`) so the surviving order ledger keeps the\n  // exact relative insertion order capacity eviction depends on.\n  for (const key of store.order) {\n    const entry = store.entries[key];\n    if (entry === undefined) continue; // defensive: order/entries kept in lockstep\n    if (isExpired(entry, nowMs, store.ttlMs)) continue;\n    nextEntries[key] = entry;\n    nextOrder.push(key);\n  }\n  return { ...store, entries: nextEntries, order: nextOrder };\n}\n\n/**\n * Record `key → value` at `nowMs`, then enforce both bounds. PURE — returns a\n * new store; the input is untouched.\n *\n * Order of operations (each step matters):\n *   1. **Expiry eviction** — drop everything older than `ttlMs` first, so an\n *      expired key never occupies a capacity slot the new entry could take, and\n *      a stale entry under the same `key` is cleared before the overwrite.\n *   2. **Insert / overwrite** — write the new entry. If `key` already exists,\n *      this is an UPDATE: `value` is overwritten, `atMs` is refreshed to\n *      `nowMs` (restarting the TTL clock), and the key is moved to the NEWEST\n *      position in `order` (removed from wherever it sat, appended at the end).\n *      See the module-level \"Overwrite semantics\" note.\n *   3. **Capacity eviction** — if the entry count now exceeds `capacity`, drop\n *      the OLDEST keys by `order` until the count fits. Because step 2 moves a\n *      re-remembered key to the newest position, an actively re-seen key is\n *      never the eviction victim.\n */\nexport function remember<V>(\n  store: IdempotencyStore<V>,\n  key: string,\n  value: V,\n  nowMs: number,\n): IdempotencyStore<V> {\n  // Step 1 — expire first so stale entries free capacity slots before insert.\n  const pruned = evictExpired(store, nowMs);\n\n  // Step 2 — insert/overwrite. Drop any prior position of `key` from order,\n  // then append it as newest. `delete` on a fresh shallow copy keeps the input\n  // store untouched (invariant 1).\n  const nextEntries: Record<string, IdempotencyEntry<V>> = {\n    ...pruned.entries,\n  };\n  nextEntries[key] = { value, atMs: nowMs };\n  const nextOrder = pruned.order.filter((k) => k !== key);\n  nextOrder.push(key);\n\n  // Step 3 — capacity eviction. Drop oldest (front of `order`) until the count\n  // fits. `capacity <= 0` evicts everything just inserted down to the bound;\n  // `undefined` capacity skips eviction entirely.\n  if (store.capacity !== undefined) {\n    while (nextOrder.length > store.capacity) {\n      const oldest = nextOrder.shift();\n      if (oldest === undefined) break; // order emptied — nothing left to evict\n      delete nextEntries[oldest];\n    }\n  }\n\n  return { ...store, entries: nextEntries, order: nextOrder };\n}\n"]}

package/dist/index.d.ts

@@ -0,0 +1,364 @@
+type Reducer<S, M extends {
+    type: string;
+}, C extends Cmd> = {
+    [K in M["type"]]: (state: S, msg: Extract<M, {
+        type: K;
+    }>) => readonly [S, readonly C[]];
+};
+type Transitions<S extends {
+    type: string;
+}, M extends {
+    type: string;
+}, C extends Cmd> = {
+    [P in S["type"]]: {
+        [K in M["type"]]: (state: Extract<S, {
+            type: P;
+        }>, msg: Extract<M, {
+            type: K;
+        }>) => readonly [S, readonly C[]];
+    };
+};
+/**
+ * Compile-time exhaustiveness assertion. Use in default branches of
+ * switches over discriminated unions where every case should be handled
+ * explicitly — TS narrows the type to `never` only if every variant has
+ * been covered. Strengthens invariant 7 (identity is explicit).
+ *
+ * @example
+ *   switch (msg.type) {
+ *     case "a": return ...;
+ *     case "b": return ...;
+ *     default: return absurd(msg);  // compile error if a "c" is added
+ *   }
+ */
+declare function absurd(x: never): never;
+declare const noop: <S, M, C extends Cmd>(state: S, _msg: M) => readonly [S, readonly C[]];
+/**
+ * @demlik/tea — TEA-faithful state machine substrate.
+ *
+ * This module exposes the full Locked API Surface from the PRD as types and
+ * implements `defineMachine` (identity, task 1), `run` (task 2), and
+ * `replay` + `tryInterpret` (task 3).
+ *
+ * `replay` is the pure unit-test tool: it composes `init` + `update` only,
+ * never touches `Store`, never calls `interpret`, never starts subscriptions.
+ *
+ * `tryInterpret` is Railway sugar — wraps a fallible async function and routes
+ * Ok/Err to two Msg constructors via better-result.
+ */
+type Cmd<T extends string = string> = {
+    type: T;
+};
+declare const Cmd: {
+    /**
+     * The empty Cmd array. Typed `readonly never[]` so it's assignable to any
+     * `readonly C[]` for any `C extends Cmd`. Use in `init` returns and
+     * Transitions cells that emit zero effects:
+     *
+     *   init: (loaded) => [loaded ?? initial, Cmd.none],
+     *   tick: (state) => [state, Cmd.none],
+     *
+     * Elm's `Cmd.none` analogue. Cultural signal alongside the runtime help:
+     * `[state, Cmd.none]` reads as intent ("this transition emits nothing"),
+     * `[state, []]` reads as "empty array of what".
+     *
+     * Frozen at runtime so a downstream consumer can't `.push()` into the
+     * shared reference.
+     */
+    readonly none: readonly never[];
+    /**
+     * Flat concat of cmd arrays. Use when a cell composes effects from
+     * multiple conditional sources:
+     *
+     *   return [next, Cmd.batch(
+     *     Cmd.whenDefined(state.queueItemId, (id) => ({ type: "complete", id })),
+     *     Cmd.when(state.windowId !== undefined, { type: "close_window", windowId }),
+     *     [{ type: "detach_debugger", tabId: state.tabId }],
+     *   )];
+     *
+     * `<const C>` keeps inline cmd literals' discriminants narrow (same
+     * rationale as `when` / `whenDefined` above).
+     */
+    readonly batch: <const C extends Cmd>(...arrs: readonly (readonly C[])[]) => readonly C[];
+    /**
+     * Emit `cmd` wrapped in a single-element array iff `cond` is true.
+     * Otherwise return the empty array. Spreads cleanly into the cmds array
+     * returned by a Transitions cell.
+     *
+     * `const C` (TypeScript 5.0+) keeps the inferred `type:` discriminator
+     * literal narrow when called with an object literal — so `Cmd.when(b,
+     * { type: "x", ... })` infers as `{ type: "x", ... }`, not `{ type:
+     * string, ... }`, and stays assignable to a discriminated-union arm
+     * without `as const` at the call site.
+     */
+    readonly when: <const C extends Cmd>(cond: boolean, cmd: C) => readonly C[];
+    /**
+     * If `value` is defined, call `build(value)` and emit the resulting cmd
+     * wrapped in a single-element array. If `value` is `undefined`, return
+     * the empty array. `value` is narrowed to `T` inside `build`.
+     *
+     * `const C` on the return type keeps the callback's object-literal
+     * `type:` field narrow (see `when` above for the full rationale).
+     */
+    readonly whenDefined: <T, const C extends Cmd>(value: T | undefined, build: (value: T) => C) => readonly C[];
+};
+type SubId = string & {
+    readonly __brand: "SubId";
+};
+/**
+ * Construct a `SubId` from a string. Use this everywhere a Sub literal is
+ * built — including ids derived from runtime data (`subId(\`ws:${auditId}\`)`).
+ * The brand is structural, not nominal, so dynamic ids are permitted; the
+ * constructor's job is to make the identity decision explicit at every call
+ * site so the type system can catch accidental raw-string drift.
+ *
+ * Strengthens invariant 7 (identity is explicit).
+ */
+declare function subId(s: string): SubId;
+type Sub<T extends string = string> = {
+    id: SubId;
+    type: T;
+};
+interface Port<T> {
+    readonly __brand: "port";
+    readonly name: string;
+    readonly __t?: T;
+}
+/**
+ * Thrown by `definePort` when a name has already been registered in the
+ * current process. Symmetric with the `Sub.id` collision assert in
+ * `reconcileSubs` — both mechanize invariant 7 (identity is explicit) at the
+ * runtime layer the type system cannot reach (string names compared at
+ * runtime, not at compile time).
+ */
+declare class PortNameCollisionError extends Error {
+    readonly name = "PortNameCollisionError";
+    constructor(portName: string);
+}
+/**
+ * Test-only escape hatch — clears the module-level port-name registry so the
+ * collision assert in `definePort` doesn't false-positive across vitest's
+ * non-isolated runs. Production code MUST NOT call this; the registry is the
+ * invariant-7 witness for the process lifetime.
+ *
+ * @internal test-only
+ */
+declare function __resetPortRegistry(): void;
+/**
+ * Define a typed port. `name` is metadata (shown in devtools / debug logs);
+ * port identity is by reference. Each definePort call must use a unique
+ * `name` — a second call with the same name throws
+ * `PortNameCollisionError`. If two modules need the same port, export it
+ * from one module and import it from the other.
+ *
+ * Use ports for "data leaving the runtime selectively" — e.g. cursor
+ * announcements, DOM-mutation broadcasts, telemetry events that should NOT be
+ * folded into State and should NOT be observed by every transition listener.
+ *
+ * Strengthens invariant 7 (identity is explicit) — the runtime assert is the
+ * Port-side counterpart of `SubId`'s id collision check in `reconcileSubs`.
+ */
+declare function definePort<T>(name: string): Port<T>;
+/**
+ * Augmentation injected onto `ctx` inside Cmd handlers. Handlers receive
+ * `ctx & PortEmitter` so they can call `ctx.emit(port, value)` synchronously.
+ * Subscribers registered via `runtime.subscribePort(port, listener)` receive
+ * the value immediately.
+ *
+ * Emitting to a port with no subscribers is a no-op (does not throw).
+ */
+interface PortEmitter {
+    emit<T>(port: Port<T>, value: T): void;
+}
+type Interpret<M extends {
+    type: string;
+}, C extends Cmd, Ctx> = {
+    [K in C["type"]]: (cmd: Extract<C, {
+        type: K;
+    }>, ctx: Ctx & PortEmitter) => Promise<M | void>;
+};
+type Subscribe<M extends {
+    type: string;
+}, U extends Sub, Ctx> = {
+    [K in U["type"]]: (sub: Extract<U, {
+        type: K;
+    }>, ctx: Ctx, dispatch: (msg: M) => void) => () => void;
+};
+type Machine<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx> = {
+    /**
+     * Boot the runtime. Called once by `run(...)` with whatever `Store.load()`
+     * returned: `null` on fresh boot, the persisted state on rehydrate.
+     *
+     * **Contract:** when `loaded !== null`, init MUST return `[loaded, []]` —
+     * no Cmds. Init's rehydrate branch is the migration / parse boundary, not
+     * the boot-effect hook. See Invariant 2 in `.patterns/tea/tea-invariants.md`.
+     *
+     * Boot effects routes:
+     *   - Stateless infrastructure → host module top, outside TEA.
+     *   - State-conditional resume → a `boot` Msg the host dispatches once
+     *     after `run(...)` returns.
+     *
+     * Violations are caught at runtime by `replay` (which throws with a
+     * pointer to the alternatives).
+     */
+    init: (loaded: S | null, ctx: Ctx) => readonly [S, readonly C[]];
+    update: Reducer<S, M, C> | ([S] extends [{
+        type: string;
+    }] ? Transitions<S, M, C> : never);
+    subscriptions?: (state: S) => readonly U[];
+    subscribe?: Subscribe<M, U, Ctx>;
+} & ([C] extends [Cmd<never>] ? {
+    interpret?: Interpret<M, C, Ctx>;
+} : {
+    interpret: Interpret<M, C, Ctx>;
+});
+interface Store<S> {
+    load(): Promise<unknown>;
+    save(state: S): Promise<void>;
+    migrate(raw: unknown): S | null;
+}
+interface RuntimeRef<M extends {
+    type: string;
+}> {
+    dispatch(msg: M): Promise<void>;
+}
+interface Runtime<S, M extends {
+    type: string;
+}> extends RuntimeRef<M> {
+    dispatch(msg: M): Promise<void>;
+    getState(): S;
+    subscribe(listener: () => void): () => void;
+    observe(observer: (msg: M | null, state: S) => void): () => void;
+    /**
+     * Subscribe to a typed Port. Returns a cleanup function that removes the
+     * listener. Multiple listeners per port are supported; fanout is synchronous
+     * (same shape as `observe`) and isolated — one listener throw does not strand
+     * the others.
+     *
+     * Ports are for "data leaving the runtime selectively" — see `definePort`.
+     * Distinct from `observe` (every transition) and from State (the world).
+     */
+    subscribePort<T>(port: Port<T>, listener: (value: T) => void): () => void;
+    /**
+     * Emit a value on a Port from OUTSIDE an interpret handler. Same synchronous
+     * fanout discipline as `ctx.emit` inside interpret — every subscriber
+     * receives the value immediately; emitting to a port with no subscribers is
+     * a no-op; listener throws are isolated.
+     *
+     * Use this for `observe`-driven Port emission: the canonical case is one
+     * runtime publishing a state-derived signal (e.g. "am I idle?") that
+     * another runtime subscribes to via `subscribePort`. Without
+     * `runtime.emitPort`, the only way to emit a Port is from inside an
+     * `interpret` handler — which forces the reducer to spawn a "tell the
+     * outside world" Cmd on every transition that should signal. With it,
+     * `runtime.observe((msg, state) => runtime.emitPort(port, derive(state)))`
+     * keeps the reducer free of Port-plumbing Cmds and matches the "every
+     * transition is observable" contract this invariant set already commits to.
+     *
+     * Strengthens invariant 6 (runtime is small and inspectable — Port emission
+     * is no longer privileged to interpret handlers; `observe`-driven emission
+     * is structurally supported).
+     */
+    emitPort<T>(port: Port<T>, value: T): void;
+    /**
+     * Resolves after boot completes — i.e. after `store.load()` (if any), `init`,
+     * `store.save()` of the initial state, `reconcileSubs`, `interpret` of any
+     * init-emitted cmds, and the initial listener / observer fanout. Rejects with
+     * the boot error if boot fails (the same error every subsequent `dispatch`
+     * call rejects with).
+     *
+     * Idempotent — subsequent reads return the same settled promise. The runtime
+     * holds exactly one `ready` promise per `run()` call.
+     *
+     * Closes the v1 boot-await gap previously documented in `stepBootEffects`:
+     * components that need synchronous initial state under a store (e.g.,
+     * `useSyncExternalStore` consumers) can `await runtime.ready` instead of
+     * `runtime.dispatch(noopMsg)`.
+     *
+     * Expresses canon §2.3 (the `init` contract — boot is a named, awaitable
+     * moment). Strengthens invariant 6 (runtime is small and inspectable).
+     */
+    ready: Promise<void>;
+    stop(): Promise<void>;
+}
+declare function defineMachine<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(m: Omit<Machine<S, M, C, U, Ctx>, "update"> & {
+    update: [S] extends [{
+        type: string;
+    }] ? Transitions<S, M, C> : never;
+}): Machine<S, M, C, U, Ctx>;
+declare function defineMachine<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(m: Omit<Machine<S, M, C, U, Ctx>, "update"> & {
+    update: Reducer<S, M, C>;
+}): Machine<S, M, C, U, Ctx>;
+declare function run<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, opts: {
+    ctx: Ctx;
+    store?: Store<S>;
+}): Runtime<S, M>;
+interface HistoryTracker<S, M extends {
+    type: string;
+}> {
+    /**
+     * Snapshot of recorded transitions, oldest first. Each entry is
+     * `{ msg, state }` exactly as the underlying `observe` callback received
+     * it — `msg` is `null` for the boot transition, a Msg for every other.
+     *
+     * Returns a shallow copy: the array is fresh on every call (callers may
+     * iterate, slice, or replay without affecting the tracker's buffer).
+     * Entry values are references to the originals (TEA states/msgs are
+     * conventionally immutable; do not mutate them if your S/M is not).
+     */
+    snapshot(): readonly {
+        readonly msg: M | null;
+        readonly state: S;
+    }[];
+    /**
+     * Detach the underlying observer. After `stop()`:
+     *   - No new transitions are recorded.
+     *   - `snapshot()` continues to work and returns the buffer's contents
+     *     at the moment of stop (useful for post-hoc inspection in tests).
+     *   - The tracker holds no references that would prevent GC of the
+     *     `runtime` argument other than the entries already buffered.
+     *
+     * Idempotent — subsequent calls are no-ops.
+     */
+    stop(): void;
+}
+/**
+ * Create a bounded history tracker over a Runtime. The tracker subscribes
+ * to the runtime via `observe(...)` and retains the last `size` `(msg,
+ * state)` transitions in a FIFO ring buffer.
+ *
+ * @param runtime  Any `Runtime<S, M>`. The tracker uses only `observe`.
+ * @param size     Buffer cap. `size <= 0` produces a tracker whose
+ *                 snapshot is always `[]` (the observer is still attached
+ *                 but pushes a no-op; cheaper to skip the tracker entirely
+ *                 in that case).
+ *
+ * Memory cost: O(size × avg(msg + state size)). For audit-extension's
+ * inspector use case (size 100, audit state ~5KB), ~500KB max — held
+ * in-memory only, no persistence.
+ */
+declare function historyTracker<S, M extends {
+    type: string;
+}>(runtime: Runtime<S, M>, size: number): HistoryTracker<S, M>;
+declare function replay<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, opts: {
+    msgs: readonly M[];
+    ctx: Ctx;
+    loaded?: S | null;
+}): {
+    state: S;
+    cmds: C[];
+    subs: U[];
+};
+declare function tryInterpret<C extends Cmd, Ok, M, Ctx>(work: (cmd: C, ctx: Ctx) => Promise<Ok>, onOk: (value: Ok, cmd: C) => M, onErr: (error: unknown, cmd: C) => M): (cmd: C, ctx: Ctx) => Promise<M>;
+
+export { Cmd, type HistoryTracker, type Interpret, type Machine, type Port, type PortEmitter, PortNameCollisionError, type Reducer, type Runtime, type RuntimeRef, type Store, type Sub, type SubId, type Subscribe, type Transitions, __resetPortRegistry, absurd, defineMachine, definePort, historyTracker, noop, replay, run, subId, tryInterpret };

package/dist/index.js

@@ -0,0 +1,3 @@
+export { Cmd, PortNameCollisionError, __resetPortRegistry, absurd, defineMachine, definePort, historyTracker, noop, replay, run, subId, tryInterpret } from './chunk-CMG2KMWX.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/machine-viz/index.d.ts

@@ -0,0 +1,78 @@
+import { Cmd, Sub, Machine } from '../index.js';
+
+/**
+ * @demlik/tea/machine-viz — turn a `Machine` into a Mermaid diagram string.
+ *
+ * PURE. No deps, no AST parsing, no file I/O. The function reads only the
+ * `Machine` value it is handed plus optional sample states/msgs/ctx.
+ *
+ * The trick: TEA update cells are PURE (invariant 2 — they return
+ * `[nextState, cmds]` as data, no effects). So we can SAFELY EXECUTE a cell to
+ * discover its target state — exactly what `replay` does. That gives us REAL
+ * edges (`red --> green : go`) without parsing source. When no sample is
+ * provided for a `(state, msg)` pair we cannot resolve the target, so we fall
+ * back to a STRUCTURAL self-edge annotated with `?` — visually distinct from a
+ * resolved edge and documented in the diagram's legend.
+ *
+ * Form detection mirrors `run`/`replay` (the `updateMode` logic): inspect the
+ * first own key of `update`; a value that is a function ⇒ Reducer form, a value
+ * that is a record ⇒ Transitions form. We do NOT add a runtime tag to Machine.
+ *
+ * What we MUST NOT do (these are the effectful paths, off-limits here):
+ *   - call `interpret[*]` handlers (perform I/O)
+ *   - call `subscribe[*]` handlers (install listeners)
+ *   - call `run` / the runtime
+ * We MAY call `init`, `update[*]` cells, and `subscriptions(state)` — all pure
+ * by the invariants (same set `replay` is allowed to touch).
+ */
+
+/**
+ * Options controlling diagram emission.
+ *
+ * `samples` is the lever that turns STRUCTURAL edges into RESOLVED edges. For a
+ * Transitions machine, providing a sample state for `stateType` AND a sample
+ * msg for `msgType` lets us execute `update[stateType][msgType](state, msg)` and
+ * read the real target `next.type`. Sample maps are keyed by the discriminant
+ * string (`state.type` / `msg.type`).
+ *
+ * `samples.ctx` is the argument to `init(null, ctx)` — provide it to draw the
+ * `[*] -->` initial-state edge. Omitted ⇒ no init edge (annotated as such),
+ * because `init`'s signature requires a ctx and we will not invent one.
+ */
+interface MachineVizOptions<S, M> {
+    samples?: {
+        /** Sample state per `state.type` — unlocks RESOLVED edges + sub annotations. */
+        states?: Partial<Record<string, S>>;
+        /** Sample msg per `msg.type` — unlocks RESOLVED edges. */
+        msgs?: Partial<Record<string, M>>;
+        /** Ctx for `init(null, ctx)` — unlocks the `[*] -->` initial-state edge. */
+        ctx?: unknown;
+    };
+    /** Mermaid layout direction. Default `"TB"` (top-to-bottom). */
+    direction?: "TB" | "LR";
+    /** Optional diagram title, emitted as a Mermaid front-matter `title:` block. */
+    title?: string;
+}
+/**
+ * Render a `Machine` as a Mermaid `stateDiagram-v2` string.
+ *
+ * - **Transitions form** (`update` is a record-of-records): nodes are the
+ *   `state.type` keys; each `(stateType × msgType)` cell becomes an edge. With
+ *   samples for both, the edge is RESOLVED by executing the (pure) cell. Without
+ *   samples it is STRUCTURAL — a `from --> from : msg?` self-loop (the `?`
+ *   suffix marks "target unresolved"). A legend note documents the distinction.
+ *   The `[*] -->` init edge is drawn only when `samples.ctx` is provided.
+ *
+ * - **Reducer form** (`update` values are functions): there is no static phase
+ *   graph (state is not a discriminated union over phases). We emit a single
+ *   node listing the handled `msg.type`s and an honest note saying so. No edges
+ *   are invented.
+ *
+ * Output is deterministic for the same input (keys iterated in insertion order,
+ * no clocks, no randomness).
+ */
+declare function toMermaid<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, opts?: MachineVizOptions<NoInfer<S>, NoInfer<M>>): string;
+
+export { type MachineVizOptions, toMermaid };