@demlik/tea 0.1.0

package/dist/pbt/arbitraries/index.js.map

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

package/dist/pbt/index.d.ts

@@ -0,0 +1,28 @@
+export { MsgArbitraryTable, arbConstantMsg, arbGuidedSequence, arbMsg, arbMsgSequence, arbRecordMsg, stubCtxThrowingProxy } from './arbitraries/index.js';
+export { Step, foldEvents, propertyInvariant, propertyTerminates, propertyTrace } from './runners/index.js';
+import { Cmd, Reducer, Transitions } from '../index.js';
+import 'fast-check';
+
+/**
+ * Extract the Msg discriminant set at runtime from a Reducer record or a
+ * Transitions table. Useful for asserting that a user-supplied
+ * `MsgArbitraryTable<M>` covers every variant the reducer can handle.
+ *
+ * - **Reducer form** — keys of the top-level record ARE the Msg variants.
+ * - **Transitions form** — keys of any single state's inner record. Every
+ *   state's inner record must cover every Msg variant (mapped-type
+ *   discipline), so reading the first state's keys is equivalent to reading
+ *   the union.
+ *
+ * @example
+ *   import { auditBackgroundMachine } from "./reducer";
+ *   msgTypeKeys(auditBackgroundMachine.update);
+ *   // → ["start_audit", "stop_audit", "window_created", ...]
+ */
+declare function msgTypeKeys<S, M extends {
+    type: string;
+}, C extends Cmd>(update: Reducer<S, M, C> | ([S] extends [{
+    type: string;
+}] ? Transitions<S, M, C> : never)): readonly string[];
+
+export { msgTypeKeys };

package/dist/pbt/index.js

@@ -0,0 +1,18 @@
+export { arbConstantMsg, arbGuidedSequence, arbMsg, arbMsgSequence, arbRecordMsg, stubCtxThrowingProxy } from '../chunk-ZRUST6BK.js';
+export { foldEvents, propertyInvariant, propertyTerminates, propertyTrace } from '../chunk-PYBQREFU.js';
+import '../chunk-CMG2KMWX.js';
+
+// src/pbt/util/msg-keys.ts
+function msgTypeKeys(update) {
+  const keys = Object.keys(update);
+  if (keys.length === 0) return [];
+  const firstValue = update[keys[0]];
+  if (typeof firstValue === "function") {
+    return keys;
+  }
+  return Object.keys(firstValue);
+}
+
+export { msgTypeKeys };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/pbt/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/pbt/util/msg-keys.ts"],"names":[],"mappings":";;;;;AAiCO,SAAS,YACd,MAAA,EACmB;AACnB,EAAA,MAAM,IAAA,GAAO,MAAA,CAAO,IAAA,CAAK,MAAgB,CAAA;AACzC,EAAA,IAAI,IAAA,CAAK,MAAA,KAAW,CAAA,EAAG,OAAO,EAAC;AAI/B,EAAA,MAAM,UAAA,GAAc,MAAA,CAAmC,IAAA,CAAK,CAAC,CAAE,CAAA;AAC/D,EAAA,IAAI,OAAO,eAAe,UAAA,EAAY;AACpC,IAAA,OAAO,IAAA;AAAA,EACT;AAEA,EAAA,OAAO,MAAA,CAAO,KAAK,UAAoB,CAAA;AACzC","file":"index.js","sourcesContent":["// ---------------------------------------------------------------------------\n// msgTypeKeys — read the Msg discriminant set at runtime from a Reducer\n// record or a Transitions table.\n//\n// TS Msg unions only exist at the type level; the discriminant strings are\n// erased at runtime. The reducer record / transitions table is the load-\n// bearing artifact that DOES carry the discriminants at runtime — its keys\n// (for Reducer) or any one cell's inner keys (for Transitions) are exactly\n// the set we need to build an `arbMsg` table without hand-listing them.\n//\n// Used by `arbMsg` to assert (in dev) that the user-supplied table covers\n// every Msg variant the reducer claims to handle. Strict drift detection\n// without runtime introspection of the type system.\n// ---------------------------------------------------------------------------\n\nimport type { Cmd, Reducer, Transitions } from \"../../index\";\n\n/**\n * Extract the Msg discriminant set at runtime from a Reducer record or a\n * Transitions table. Useful for asserting that a user-supplied\n * `MsgArbitraryTable<M>` covers every variant the reducer can handle.\n *\n * - **Reducer form** — keys of the top-level record ARE the Msg variants.\n * - **Transitions form** — keys of any single state's inner record. Every\n *   state's inner record must cover every Msg variant (mapped-type\n *   discipline), so reading the first state's keys is equivalent to reading\n *   the union.\n *\n * @example\n *   import { auditBackgroundMachine } from \"./reducer\";\n *   msgTypeKeys(auditBackgroundMachine.update);\n *   // → [\"start_audit\", \"stop_audit\", \"window_created\", ...]\n */\nexport function msgTypeKeys<S, M extends { type: string }, C extends Cmd>(\n  update: Reducer<S, M, C> | ([S] extends [{ type: string }] ? Transitions<S, M, C> : never),\n): readonly string[] {\n  const keys = Object.keys(update as object);\n  if (keys.length === 0) return [];\n  // Reducer form: every top-level value is a function (the cell).\n  // Transitions form: every top-level value is an object (the inner record).\n  // `keys[0]` is present — the length guard above rules out the empty record.\n  const firstValue = (update as Record<string, unknown>)[keys[0]!];\n  if (typeof firstValue === \"function\") {\n    return keys;\n  }\n  // Transitions form — read inner record.\n  return Object.keys(firstValue as object);\n}\n"]}

package/dist/pbt/runners/index.d.ts

@@ -0,0 +1,117 @@
+import { Cmd, Sub, Machine } from '../../index.js';
+import * as fc from 'fast-check';
+
+/**
+ * One unit in a fold trace — the four pieces of data a property
+ * invariant typically asserts on. `prev` is the state before the msg
+ * applied; `next` is the state after; `cmds` is the cmds emitted by this
+ * single step (NOT the running total).
+ */
+interface Step<S, M, C> {
+    readonly prev: S;
+    readonly msg: M;
+    readonly next: S;
+    readonly cmds: readonly C[];
+}
+/**
+ * Fold a Msg sequence through a machine's pure reducer, returning the
+ * per-step trace, every state in order, and the final state. Initial
+ * state comes from `replay(machine, { msgs: [], ctx, loaded })` — i.e.
+ * `machine.init(loaded ?? null, ctx)` faithfully. Init's emitted cmds
+ * are NOT included in any `Step` (they're the boot moment, not a Msg).
+ *
+ * @param machine  The machine under test.
+ * @param ctx      The Ctx — typically `stubCtxThrowingProxy<Ctx>()` when
+ *                 init is pure. Pass a real ctx if init reads from it.
+ * @param loaded   Optional pre-init snapshot (the `loaded` arg to
+ *                 `machine.init`). Defaults to `null` (fresh boot).
+ * @param msgs     The Msg sequence to fold.
+ *
+ * @example
+ *   const { states, steps, finalState } = foldEvents(machine, ctx, null, [
+ *     { type: "start" }, { type: "tick" }, { type: "stop" },
+ *   ]);
+ *   // steps[1] = { prev: { type: "counting", n: 0 }, msg: { type: "tick" }, ... }
+ */
+declare function foldEvents<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, ctx: NoInfer<Ctx>, loaded: NoInfer<S> | null, msgs: readonly NoInfer<M>[]): {
+    readonly states: readonly S[];
+    readonly steps: readonly Step<S, M, C>[];
+    readonly finalState: S;
+};
+
+/** Common options shared by every property runner. */
+interface PropertyOpts<S> {
+    /** Pre-init snapshot — passed to `machine.init(loaded, ctx)`. Default `null`. */
+    readonly loaded?: S | null;
+    /** Number of generated sequences to test. Forwarded to `fc.assert`. */
+    readonly numRuns?: number;
+    /** Optional fast-check seed for reproducibility. */
+    readonly seed?: number;
+}
+/**
+ * Assert every generated Msg sequence ends in a terminal state. `terminal`
+ * is the predicate that names the acceptable final states (often
+ * `(s) => s.type === "done" || s.type === "idle"`).
+ *
+ * The "every sequence" property catches stuck states (machine gets to a
+ * non-terminal state and no further msg can escape) AND silent loops
+ * (every msg variant is a noop from a given state).
+ *
+ * @example
+ *   propertyTerminates(
+ *     auditBackgroundMachine,
+ *     stubCtxThrowingProxy<BackgroundCtx>(),
+ *     arbMsgSequence(msgArb, { minLength: 1, maxLength: 30 }),
+ *     (s) => s.type === "done" || s.type === "idle",
+ *     { loaded: auditingState, numRuns: 500 },
+ *   );
+ */
+declare function propertyTerminates<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, ctx: NoInfer<Ctx>, seqArb: fc.Arbitrary<readonly NoInfer<M>[]>, terminal: (state: NoInfer<S>) => boolean, opts?: NoInfer<PropertyOpts<S>>): void;
+/**
+ * Assert a predicate holds on EVERY transition step in a generated
+ * sequence. The predicate sees `{ prev, msg, next, cmds }` per step;
+ * return true to accept, false (or throw) to fail.
+ *
+ * Use to pin a "when X happens in state Y, cmd Z must be emitted" rule.
+ * The shrinker minimizes the offending sequence to the smallest Msg list
+ * that still violates the predicate.
+ *
+ * @example
+ *   // Pin the resume-handshake fix: `ws:client:hello` in auditing must
+ *   // emit `send_ws { client:ready }`.
+ *   propertyInvariant(
+ *     auditBackgroundMachine, ctx,
+ *     arbMsgSequence(msgArb, { prefix: [{ type: "ws:client:hello" }] }),
+ *     ({ prev, msg, cmds }) =>
+ *       !(prev.type === "auditing" && msg.type === "ws:client:hello") ||
+ *       cmds.some((c) => c.type === "send_ws" && c.msg.type === "client:ready"),
+ *     { loaded: auditingState, numRuns: 200 },
+ *   );
+ */
+declare function propertyInvariant<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, ctx: NoInfer<Ctx>, seqArb: fc.Arbitrary<readonly NoInfer<M>[]>, invariant: (step: Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>) => boolean, opts?: NoInfer<PropertyOpts<S>>): void;
+/**
+ * Assert a predicate over the full trace plus the final state. Use when
+ * the property is "some Msg appeared in the trace before reaching the
+ * final state" or "no two consecutive steps had the same state.type" —
+ * predicates that need the full sequence, not a single step.
+ *
+ * @example
+ *   propertyTrace(
+ *     machine, ctx, seqArb,
+ *     (steps, final) =>
+ *       final.type !== "done" ||
+ *       steps.some((step) => step.msg.type === "ws:audit:done"),
+ *     { loaded: auditingState, numRuns: 500 },
+ *   );
+ */
+declare function propertyTrace<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, ctx: NoInfer<Ctx>, seqArb: fc.Arbitrary<readonly NoInfer<M>[]>, predicate: (steps: readonly Step<NoInfer<S>, NoInfer<M>, NoInfer<C>>[], finalState: NoInfer<S>) => boolean, opts?: NoInfer<PropertyOpts<S>>): void;
+
+export { type Step, foldEvents, propertyInvariant, propertyTerminates, propertyTrace };

package/dist/pbt/runners/index.js

@@ -0,0 +1,4 @@
+export { foldEvents, propertyInvariant, propertyTerminates, propertyTrace } from '../../chunk-PYBQREFU.js';
+import '../../chunk-CMG2KMWX.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/pbt/runners/index.js.map

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

package/dist/rate-limit/index.d.ts

@@ -0,0 +1,115 @@
+/**
+ * @demlik/tea/rate-limit — two rate limiters as pure state + ops.
+ *
+ * Same shape as `@demlik/tea/work-queue`'s `ops.ts`: 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 limiters inside TEA's
+ * invariant 2 (transitions are pure: same inputs → same outputs, no `Date.now`)
+ * so a consumer can fold them through `update` and exercise them with `replay`
+ * / the pbt fold without a fake clock.
+ *
+ * Every op returns a NEW state value and never mutates its input (invariant 1 —
+ * state is a value, not a place). The `tryConsume` / `record` ops return a
+ * `[next, ok]` tuple so the caller branches on the decision while threading the
+ * advanced state forward; `refill` / `remaining` are read-shaped helpers.
+ *
+ * Two complementary algorithms, picked by the cost the caller wants to pay:
+ *
+ *   - **Token bucket** — O(1) state (four numbers), smooths bursts against a
+ *     steady refill rate. Allows a burst up to `capacity`, then throttles to
+ *     `refillPerSec`. Cheapest; the default choice.
+ *   - **Sliding window log** — O(limit) state (one timestamp per in-window
+ *     hit), exact "no more than `limit` events per `windowMs`". Pay the memory
+ *     for precise window edges when a token bucket's continuous refill would
+ *     let through too many at a boundary.
+ *
+ * NOT exported from the package root — reached via the `@demlik/tea/rate-limit`
+ * subpath, same one-shape-per-package rule as `work-queue` and `do`.
+ */
+/**
+ * A token bucket: `tokens` of `capacity` available now, replenished at
+ * `refillPerSec` tokens per second. `lastRefillMs` is the clock reading at
+ * which `tokens` was last computed — `refill` advances it. All four fields are
+ * plain numbers so the whole bucket is trivially JSON-serializable into a
+ * consumer's `Store<S>`.
+ */
+interface TokenBucket {
+    readonly tokens: number;
+    readonly capacity: number;
+    readonly refillPerSec: number;
+    readonly lastRefillMs: number;
+}
+/**
+ * Create a full bucket. Starts at `capacity` tokens (the conventional "a fresh
+ * limiter lets the first burst through" behavior) and stamps `lastRefillMs`
+ * with the caller's clock so the first `refill` measures elapsed time from
+ * boot, not from epoch 0.
+ */
+declare function initBucket(capacity: number, refillPerSec: number, nowMs: number): TokenBucket;
+/**
+ * Add the tokens accrued since `lastRefillMs`, clamped to `capacity`, and
+ * advance `lastRefillMs` to `nowMs`. PURE — returns a new bucket; the input is
+ * untouched.
+ *
+ * A `nowMs` at or before `lastRefillMs` (clock not advanced, or skewed
+ * backwards) adds a non-positive amount; `Math.max(0, …)` floors the elapsed
+ * term so a backwards clock can never *remove* tokens. `lastRefillMs` still
+ * advances to `nowMs` so the bucket tracks the latest reading the caller
+ * presented — the next forward step measures from there, not from a stale
+ * future timestamp.
+ */
+declare function refill(bucket: TokenBucket, nowMs: number): TokenBucket;
+/**
+ * Refill against `nowMs`, then attempt to take `n` tokens (default 1).
+ *
+ * On success returns `[next, true]` with `n` subtracted; on failure returns
+ * `[refilled, false]` — the refilled bucket (so the caller keeps the advanced
+ * clock + accrued tokens) with no tokens spent. Branch on the boolean, thread
+ * the bucket forward regardless:
+ *
+ *   const [b1, ok] = tryConsume(bucket, nowMs);
+ *   return ok ? [{ ...state, bucket: b1 }, [doWork]] : [{ ...state, bucket: b1 }, []];
+ *
+ * PURE — input bucket is never mutated.
+ */
+declare function tryConsume(bucket: TokenBucket, nowMs: number, n?: number): readonly [TokenBucket, boolean];
+/**
+ * A sliding-window log: the timestamps of every hit still inside the trailing
+ * `windowMs`, capped at `limit` events per window. `hits` is `readonly` and
+ * kept oldest-first (pruning slices the stale prefix off the front, recording
+ * appends to the back), so the array is its own sorted index. Exact at the
+ * window edge — unlike a token bucket's continuous refill, a hit leaves the
+ * count the instant it ages past `windowMs`.
+ */
+interface SlidingWindow {
+    readonly hits: readonly number[];
+    readonly windowMs: number;
+    readonly limit: number;
+}
+/** Create an empty window. No hits recorded yet. */
+declare function initWindow(windowMs: number, limit: number): SlidingWindow;
+/**
+ * Prune hits older than `nowMs - windowMs`, then record `nowMs` if there is
+ * room. Returns `[next, true]` with the hit appended when `hits.length < limit`
+ * after pruning, else `[pruned, false]` — the pruned window (capacity recovers
+ * as old hits age out) with nothing appended.
+ *
+ * The cutoff is half-open: a hit exactly `windowMs` old is pruned (`<= cutoff`
+ * drops it), so a hit recorded at `t` no longer counts at `t + windowMs`. That
+ * makes the window's capacity fully recover `windowMs` after the last hit, the
+ * behavior tests pin.
+ *
+ * PURE — input window is never mutated; `hits` is rebuilt by `filter` +
+ * spread.
+ */
+declare function record(window: SlidingWindow, nowMs: number): readonly [SlidingWindow, boolean];
+/**
+ * How many more hits `record` would accept at `nowMs` without blocking —
+ * `limit` minus the live (post-prune) hit count, floored at 0. Read-only: it
+ * prunes a local copy to answer but returns no new window. Use it to render a
+ * "N requests remaining" affordance without committing a hit.
+ */
+declare function remaining(window: SlidingWindow, nowMs: number): number;
+
+export { type SlidingWindow, type TokenBucket, initBucket, initWindow, record, refill, remaining, tryConsume };

package/dist/rate-limit/index.js

@@ -0,0 +1,45 @@
+// src/rate-limit/index.ts
+function initBucket(capacity, refillPerSec, nowMs) {
+  return {
+    tokens: capacity,
+    capacity,
+    refillPerSec,
+    lastRefillMs: nowMs
+  };
+}
+function refill(bucket, nowMs) {
+  const elapsedSec = Math.max(0, nowMs - bucket.lastRefillMs) / 1e3;
+  const replenished = bucket.tokens + elapsedSec * bucket.refillPerSec;
+  return {
+    ...bucket,
+    tokens: Math.min(bucket.capacity, replenished),
+    lastRefillMs: nowMs
+  };
+}
+function tryConsume(bucket, nowMs, n = 1) {
+  const refilled = refill(bucket, nowMs);
+  if (refilled.tokens >= n) {
+    return [{ ...refilled, tokens: refilled.tokens - n }, true];
+  }
+  return [refilled, false];
+}
+function initWindow(windowMs, limit) {
+  return { hits: [], windowMs, limit };
+}
+function record(window, nowMs) {
+  const cutoff = nowMs - window.windowMs;
+  const pruned = window.hits.filter((t) => t > cutoff);
+  if (pruned.length < window.limit) {
+    return [{ ...window, hits: [...pruned, nowMs] }, true];
+  }
+  return [{ ...window, hits: pruned }, false];
+}
+function remaining(window, nowMs) {
+  const cutoff = nowMs - window.windowMs;
+  const live = window.hits.filter((t) => t > cutoff).length;
+  return Math.max(0, window.limit - live);
+}
+
+export { initBucket, initWindow, record, refill, remaining, tryConsume };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/rate-limit/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/rate-limit/index.ts"],"names":[],"mappings":";AAsDO,SAAS,UAAA,CAAW,QAAA,EAAkB,YAAA,EAAsB,KAAA,EAA4B;AAC7F,EAAA,OAAO;AAAA,IACL,MAAA,EAAQ,QAAA;AAAA,IACR,QAAA;AAAA,IACA,YAAA;AAAA,IACA,YAAA,EAAc;AAAA,GAChB;AACF;AAcO,SAAS,MAAA,CAAO,QAAqB,KAAA,EAA4B;AACtE,EAAA,MAAM,aAAa,IAAA,CAAK,GAAA,CAAI,GAAG,KAAA,GAAQ,MAAA,CAAO,YAAY,CAAA,GAAI,GAAA;AAC9D,EAAA,MAAM,WAAA,GAAc,MAAA,CAAO,MAAA,GAAS,UAAA,GAAa,MAAA,CAAO,YAAA;AACxD,EAAA,OAAO;AAAA,IACL,GAAG,MAAA;AAAA,IACH,MAAA,EAAQ,IAAA,CAAK,GAAA,CAAI,MAAA,CAAO,UAAU,WAAW,CAAA;AAAA,IAC7C,YAAA,EAAc;AAAA,GAChB;AACF;AAeO,SAAS,UAAA,CACd,MAAA,EACA,KAAA,EACA,CAAA,GAAI,CAAA,EAC6B;AACjC,EAAA,MAAM,QAAA,GAAW,MAAA,CAAO,MAAA,EAAQ,KAAK,CAAA;AACrC,EAAA,IAAI,QAAA,CAAS,UAAU,CAAA,EAAG;AACxB,IAAA,OAAO,CAAC,EAAE,GAAG,QAAA,EAAU,QAAQ,QAAA,CAAS,MAAA,GAAS,CAAA,EAAE,EAAG,IAAI,CAAA;AAAA,EAC5D;AACA,EAAA,OAAO,CAAC,UAAU,KAAK,CAAA;AACzB;AAqBO,SAAS,UAAA,CAAW,UAAkB,KAAA,EAA8B;AACzE,EAAA,OAAO,EAAE,IAAA,EAAM,EAAC,EAAG,UAAU,KAAA,EAAM;AACrC;AAgBO,SAAS,MAAA,CAAO,QAAuB,KAAA,EAAkD;AAC9F,EAAA,MAAM,MAAA,GAAS,QAAQ,MAAA,CAAO,QAAA;AAC9B,EAAA,MAAM,SAAS,MAAA,CAAO,IAAA,CAAK,OAAO,CAAC,CAAA,KAAM,IAAI,MAAM,CAAA;AACnD,EAAA,IAAI,MAAA,CAAO,MAAA,GAAS,MAAA,CAAO,KAAA,EAAO;AAChC,IAAA,OAAO,CAAC,EAAE,GAAG,MAAA,EAAQ,IAAA,EAAM,CAAC,GAAG,MAAA,EAAQ,KAAK,CAAA,EAAE,EAAG,IAAI,CAAA;AAAA,EACvD;AACA,EAAA,OAAO,CAAC,EAAE,GAAG,QAAQ,IAAA,EAAM,MAAA,IAAU,KAAK,CAAA;AAC5C;AAQO,SAAS,SAAA,CAAU,QAAuB,KAAA,EAAuB;AACtE,EAAA,MAAM,MAAA,GAAS,QAAQ,MAAA,CAAO,QAAA;AAC9B,EAAA,MAAM,IAAA,GAAO,OAAO,IAAA,CAAK,MAAA,CAAO,CAAC,CAAA,KAAM,CAAA,GAAI,MAAM,CAAA,CAAE,MAAA;AACnD,EAAA,OAAO,IAAA,CAAK,GAAA,CAAI,CAAA,EAAG,MAAA,CAAO,QAAQ,IAAI,CAAA;AACxC","file":"index.js","sourcesContent":["/**\n * @demlik/tea/rate-limit — two rate limiters as pure state + ops.\n *\n * Same shape as `@demlik/tea/work-queue`'s `ops.ts`: a state type plus pure\n * transition functions. Host-agnostic by construction — no `Date.now()`, no\n * timers, no I/O. The caller injects the clock (`nowMs`) and wires the result\n * into its own reducer / interpret. This keeps the limiters inside TEA's\n * invariant 2 (transitions are pure: same inputs → same outputs, no `Date.now`)\n * so a consumer can fold them through `update` and exercise them with `replay`\n * / the pbt fold without a fake clock.\n *\n * Every op returns a NEW state value and never mutates its input (invariant 1 —\n * state is a value, not a place). The `tryConsume` / `record` ops return a\n * `[next, ok]` tuple so the caller branches on the decision while threading the\n * advanced state forward; `refill` / `remaining` are read-shaped helpers.\n *\n * Two complementary algorithms, picked by the cost the caller wants to pay:\n *\n *   - **Token bucket** — O(1) state (four numbers), smooths bursts against a\n *     steady refill rate. Allows a burst up to `capacity`, then throttles to\n *     `refillPerSec`. Cheapest; the default choice.\n *   - **Sliding window log** — O(limit) state (one timestamp per in-window\n *     hit), exact \"no more than `limit` events per `windowMs`\". Pay the memory\n *     for precise window edges when a token bucket's continuous refill would\n *     let through too many at a boundary.\n *\n * NOT exported from the package root — reached via the `@demlik/tea/rate-limit`\n * subpath, same one-shape-per-package rule as `work-queue` and `do`.\n */\n\n// ===========================================================================\n// Token bucket\n// ===========================================================================\n\n/**\n * A token bucket: `tokens` of `capacity` available now, replenished at\n * `refillPerSec` tokens per second. `lastRefillMs` is the clock reading at\n * which `tokens` was last computed — `refill` advances it. All four fields are\n * plain numbers so the whole bucket is trivially JSON-serializable into a\n * consumer's `Store<S>`.\n */\nexport interface TokenBucket {\n  readonly tokens: number;\n  readonly capacity: number;\n  readonly refillPerSec: number;\n  readonly lastRefillMs: number;\n}\n\n/**\n * Create a full bucket. Starts at `capacity` tokens (the conventional \"a fresh\n * limiter lets the first burst through\" behavior) and stamps `lastRefillMs`\n * with the caller's clock so the first `refill` measures elapsed time from\n * boot, not from epoch 0.\n */\nexport function initBucket(capacity: number, refillPerSec: number, nowMs: number): TokenBucket {\n  return {\n    tokens: capacity,\n    capacity,\n    refillPerSec,\n    lastRefillMs: nowMs,\n  };\n}\n\n/**\n * Add the tokens accrued since `lastRefillMs`, clamped to `capacity`, and\n * advance `lastRefillMs` to `nowMs`. PURE — returns a new bucket; the input is\n * untouched.\n *\n * A `nowMs` at or before `lastRefillMs` (clock not advanced, or skewed\n * backwards) adds a non-positive amount; `Math.max(0, …)` floors the elapsed\n * term so a backwards clock can never *remove* tokens. `lastRefillMs` still\n * advances to `nowMs` so the bucket tracks the latest reading the caller\n * presented — the next forward step measures from there, not from a stale\n * future timestamp.\n */\nexport function refill(bucket: TokenBucket, nowMs: number): TokenBucket {\n  const elapsedSec = Math.max(0, nowMs - bucket.lastRefillMs) / 1000;\n  const replenished = bucket.tokens + elapsedSec * bucket.refillPerSec;\n  return {\n    ...bucket,\n    tokens: Math.min(bucket.capacity, replenished),\n    lastRefillMs: nowMs,\n  };\n}\n\n/**\n * Refill against `nowMs`, then attempt to take `n` tokens (default 1).\n *\n * On success returns `[next, true]` with `n` subtracted; on failure returns\n * `[refilled, false]` — the refilled bucket (so the caller keeps the advanced\n * clock + accrued tokens) with no tokens spent. Branch on the boolean, thread\n * the bucket forward regardless:\n *\n *   const [b1, ok] = tryConsume(bucket, nowMs);\n *   return ok ? [{ ...state, bucket: b1 }, [doWork]] : [{ ...state, bucket: b1 }, []];\n *\n * PURE — input bucket is never mutated.\n */\nexport function tryConsume(\n  bucket: TokenBucket,\n  nowMs: number,\n  n = 1,\n): readonly [TokenBucket, boolean] {\n  const refilled = refill(bucket, nowMs);\n  if (refilled.tokens >= n) {\n    return [{ ...refilled, tokens: refilled.tokens - n }, true];\n  }\n  return [refilled, false];\n}\n\n// ===========================================================================\n// Sliding window log\n// ===========================================================================\n\n/**\n * A sliding-window log: the timestamps of every hit still inside the trailing\n * `windowMs`, capped at `limit` events per window. `hits` is `readonly` and\n * kept oldest-first (pruning slices the stale prefix off the front, recording\n * appends to the back), so the array is its own sorted index. Exact at the\n * window edge — unlike a token bucket's continuous refill, a hit leaves the\n * count the instant it ages past `windowMs`.\n */\nexport interface SlidingWindow {\n  readonly hits: readonly number[];\n  readonly windowMs: number;\n  readonly limit: number;\n}\n\n/** Create an empty window. No hits recorded yet. */\nexport function initWindow(windowMs: number, limit: number): SlidingWindow {\n  return { hits: [], windowMs, limit };\n}\n\n/**\n * Prune hits older than `nowMs - windowMs`, then record `nowMs` if there is\n * room. Returns `[next, true]` with the hit appended when `hits.length < limit`\n * after pruning, else `[pruned, false]` — the pruned window (capacity recovers\n * as old hits age out) with nothing appended.\n *\n * The cutoff is half-open: a hit exactly `windowMs` old is pruned (`<= cutoff`\n * drops it), so a hit recorded at `t` no longer counts at `t + windowMs`. That\n * makes the window's capacity fully recover `windowMs` after the last hit, the\n * behavior tests pin.\n *\n * PURE — input window is never mutated; `hits` is rebuilt by `filter` +\n * spread.\n */\nexport function record(window: SlidingWindow, nowMs: number): readonly [SlidingWindow, boolean] {\n  const cutoff = nowMs - window.windowMs;\n  const pruned = window.hits.filter((t) => t > cutoff);\n  if (pruned.length < window.limit) {\n    return [{ ...window, hits: [...pruned, nowMs] }, true];\n  }\n  return [{ ...window, hits: pruned }, false];\n}\n\n/**\n * How many more hits `record` would accept at `nowMs` without blocking —\n * `limit` minus the live (post-prune) hit count, floored at 0. Read-only: it\n * prunes a local copy to answer but returns no new window. Use it to render a\n * \"N requests remaining\" affordance without committing a hit.\n */\nexport function remaining(window: SlidingWindow, nowMs: number): number {\n  const cutoff = nowMs - window.windowMs;\n  const live = window.hits.filter((t) => t > cutoff).length;\n  return Math.max(0, window.limit - live);\n}\n"]}

package/dist/react/index.d.ts

@@ -0,0 +1,72 @@
+import { Store, Cmd, Sub, Machine, Runtime } from '../index.js';
+
+/**
+ * @demlik/tea/react — React host adapter for `@demlik/tea`.
+ *
+ * The thinnest possible adapter that makes a tea machine consumable from a
+ * React component. Three rules (PRD §"React adapter"):
+ *
+ *   1. The runtime is the source of truth, NOT React state. We subscribe via
+ *      `useSyncExternalStore(runtime.subscribe, runtime.getState,
+ *      runtime.getState)`. React renders are driven by runtime state changes;
+ *      React never owns the state.
+ *   2. The runtime is memoized per component-mount, not per render. The deps
+ *      array is `[machine, opts.ctx, opts.store]` — IDENTITY, not value. See
+ *      `README.md` for the ctx-identity footgun + fix.
+ *   3. Concurrent React is the design target. `useSyncExternalStore` is the
+ *      React-blessed primitive for tearing-free external state.
+ *
+ * Client-only in v1 — components that call `useMachine` MUST be `"use client"`.
+ * Server Components consume data via Relay/RSC as today; tea machines own
+ * client-side stateful flows. No RSC streaming, no server-side state
+ * hydration. Crossing this boundary is a v2 concern.
+ */
+
+/**
+ * Options passed to `useMachine`. The shape is intentionally minimal — `ctx`
+ * is required (every machine has one), `store` is optional (omit it for
+ * volatile-state machines).
+ *
+ * **Identity matters.** The runtime is memoized on `[machine, opts.ctx,
+ * opts.store]`. A new `ctx` reference rebuilds the runtime. Always `useMemo`
+ * (or otherwise stabilize) the ctx at the call site. See README.
+ */
+interface UseMachineOpts<S, Ctx> {
+    ctx: Ctx;
+    store?: Store<S>;
+}
+/**
+ * Build and own a `Runtime<S, M>` for the lifetime of the component mount.
+ *
+ * - Builds via `useMemo(() => run(machine, opts), [machine, opts.ctx,
+ *   opts.store])` — runtime is recreated when ANY of the three identities
+ *   change.
+ * - Subscribes via `useSyncExternalStore(runtime.subscribe, runtime.getState,
+ *   runtime.getState)` — tearing-free under React 18 concurrent rendering.
+ * - On unmount (or any dep change), `useEffect` cleanup calls
+ *   `runtime.stop()` — drains the queue, runs every active sub cleanup,
+ *   flushes state.
+ *
+ * Returns `[state, dispatch]` shaped like `useReducer`.
+ */
+declare function useMachine<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, opts: UseMachineOpts<S, Ctx>): [S, (msg: M) => Promise<void>];
+/**
+ * Lower-level escape hatch: consume an externally-built `Runtime<S, M>`.
+ *
+ * Use this when the runtime is owned by something OTHER than the component —
+ * a parent component, a test harness, a singleton. **The component does NOT
+ * call `runtime.stop()` on unmount** — the caller owns the lifecycle.
+ *
+ * Primary use case in this repo: component tests. Build a runtime with
+ * `@demlik/tea/mem` and pre-seed it via `replay`, then mount the component with
+ * `useRuntime(testRuntime)` to render in any phase.
+ *
+ * Returns `[state, dispatch]` — same shape as `useMachine`.
+ */
+declare function useRuntime<S, M extends {
+    type: string;
+}>(runtime: Runtime<S, M>): [S, (msg: M) => Promise<void>];
+
+export { type UseMachineOpts, useMachine, useRuntime };

package/dist/react/index.js

@@ -0,0 +1,33 @@
+import { run } from '../chunk-CMG2KMWX.js';
+import { useMemo, useSyncExternalStore, useEffect } from 'react';
+
+function useMachine(machine, opts) {
+  const ctx = opts.ctx;
+  const store = opts.store;
+  const runtime = useMemo(() => run(machine, { ctx, store }), [machine, ctx, store]);
+  const preliminaryState = useMemo(() => machine.init(null, ctx)[0], [machine, ctx]);
+  const getSnapshot = () => {
+    try {
+      return runtime.getState();
+    } catch {
+      return preliminaryState;
+    }
+  };
+  const state = useSyncExternalStore(runtime.subscribe, getSnapshot, getSnapshot);
+  useEffect(
+    () => () => {
+      runtime.stop().catch(() => {
+      });
+    },
+    [runtime]
+  );
+  return [state, runtime.dispatch];
+}
+function useRuntime(runtime) {
+  const state = useSyncExternalStore(runtime.subscribe, runtime.getState, runtime.getState);
+  return [state, runtime.dispatch];
+}
+
+export { useMachine, useRuntime };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/react/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/react/index.ts"],"names":[],"mappings":";;;AAuDO,SAAS,UAAA,CACd,SACA,IAAA,EACgC;AAMhC,EAAA,MAAM,MAAM,IAAA,CAAK,GAAA;AACjB,EAAA,MAAM,QAAQ,IAAA,CAAK,KAAA;AACnB,EAAA,MAAM,OAAA,GAAU,OAAA,CAAuB,MAAM,GAAA,CAAI,SAAS,EAAE,GAAA,EAAK,KAAA,EAAO,CAAA,EAAG,CAAC,OAAA,EAAS,GAAA,EAAK,KAAK,CAAC,CAAA;AAahG,EAAA,MAAM,gBAAA,GAAmB,OAAA,CAAW,MAAM,OAAA,CAAQ,IAAA,CAAK,IAAA,EAAM,GAAG,CAAA,CAAE,CAAC,CAAA,EAAG,CAAC,OAAA,EAAS,GAAG,CAAC,CAAA;AAMpF,EAAA,MAAM,cAAc,MAAS;AAC3B,IAAA,IAAI;AACF,MAAA,OAAO,QAAQ,QAAA,EAAS;AAAA,IAC1B,CAAA,CAAA,MAAQ;AACN,MAAA,OAAO,gBAAA;AAAA,IACT;AAAA,EACF,CAAA;AAEA,EAAA,MAAM,KAAA,GAAQ,oBAAA,CAAqB,OAAA,CAAQ,SAAA,EAAW,aAAa,WAAW,CAAA;AAC9E,EAAA,SAAA;AAAA,IACE,MAAM,MAAM;AAIV,MAAA,OAAA,CAAQ,IAAA,EAAK,CAAE,KAAA,CAAM,MAAM;AAAA,MAAC,CAAC,CAAA;AAAA,IAC/B,CAAA;AAAA,IACA,CAAC,OAAO;AAAA,GACV;AACA,EAAA,OAAO,CAAC,KAAA,EAAO,OAAA,CAAQ,QAAQ,CAAA;AACjC;AAeO,SAAS,WACd,OAAA,EACgC;AAChC,EAAA,MAAM,QAAQ,oBAAA,CAAqB,OAAA,CAAQ,WAAW,OAAA,CAAQ,QAAA,EAAU,QAAQ,QAAQ,CAAA;AACxF,EAAA,OAAO,CAAC,KAAA,EAAO,OAAA,CAAQ,QAAQ,CAAA;AACjC","file":"index.js","sourcesContent":["/**\n * @demlik/tea/react — React host adapter for `@demlik/tea`.\n *\n * The thinnest possible adapter that makes a tea machine consumable from a\n * React component. Three rules (PRD §\"React adapter\"):\n *\n *   1. The runtime is the source of truth, NOT React state. We subscribe via\n *      `useSyncExternalStore(runtime.subscribe, runtime.getState,\n *      runtime.getState)`. React renders are driven by runtime state changes;\n *      React never owns the state.\n *   2. The runtime is memoized per component-mount, not per render. The deps\n *      array is `[machine, opts.ctx, opts.store]` — IDENTITY, not value. See\n *      `README.md` for the ctx-identity footgun + fix.\n *   3. Concurrent React is the design target. `useSyncExternalStore` is the\n *      React-blessed primitive for tearing-free external state.\n *\n * Client-only in v1 — components that call `useMachine` MUST be `\"use client\"`.\n * Server Components consume data via Relay/RSC as today; tea machines own\n * client-side stateful flows. No RSC streaming, no server-side state\n * hydration. Crossing this boundary is a v2 concern.\n */\n\n\"use client\";\n\nimport { type Cmd, type Machine, type Runtime, run, type Store, type Sub } from \"../index\";\nimport { useEffect, useMemo, useSyncExternalStore } from \"react\";\n\n/**\n * Options passed to `useMachine`. The shape is intentionally minimal — `ctx`\n * is required (every machine has one), `store` is optional (omit it for\n * volatile-state machines).\n *\n * **Identity matters.** The runtime is memoized on `[machine, opts.ctx,\n * opts.store]`. A new `ctx` reference rebuilds the runtime. Always `useMemo`\n * (or otherwise stabilize) the ctx at the call site. See README.\n */\nexport interface UseMachineOpts<S, Ctx> {\n  ctx: Ctx;\n  store?: Store<S>;\n}\n\n/**\n * Build and own a `Runtime<S, M>` for the lifetime of the component mount.\n *\n * - Builds via `useMemo(() => run(machine, opts), [machine, opts.ctx,\n *   opts.store])` — runtime is recreated when ANY of the three identities\n *   change.\n * - Subscribes via `useSyncExternalStore(runtime.subscribe, runtime.getState,\n *   runtime.getState)` — tearing-free under React 18 concurrent rendering.\n * - On unmount (or any dep change), `useEffect` cleanup calls\n *   `runtime.stop()` — drains the queue, runs every active sub cleanup,\n *   flushes state.\n *\n * Returns `[state, dispatch]` shaped like `useReducer`.\n */\nexport function useMachine<S, M extends { type: string }, C extends Cmd, U extends Sub, Ctx>(\n  machine: Machine<S, M, C, U, Ctx>,\n  opts: UseMachineOpts<S, Ctx>,\n): [S, (msg: M) => Promise<void>] {\n  // Deps are literal: machine identity, ctx identity, store identity. NOT\n  // `[opts]` (would rebuild every render — callers pass fresh objects).\n  // We pass explicit fields to `run()` so the closure captures only the\n  // deps in the array — keeps biome's `useExhaustiveDependencies` happy\n  // without lying about what the memo actually depends on.\n  const ctx = opts.ctx;\n  const store = opts.store;\n  const runtime = useMemo<Runtime<S, M>>(() => run(machine, { ctx, store }), [machine, ctx, store]);\n\n  // Preliminary state computed sync from `machine.init(null, ctx)`. This is\n  // the snapshot React sees BEFORE the runtime finishes booting (matters\n  // only when `opts.store` is present — without a store, the substrate\n  // already sets state synchronously inside `run()`). Once the runtime\n  // boots, `runtime.getState()` returns the real (possibly loaded) state.\n  //\n  // We deliberately recompute on each render but cache by `[machine,\n  // opts.ctx]` — `init` is pure by convention, so cost is negligible. The\n  // cached snapshot is also identity-stable across rerenders when the deps\n  // don't change, which `useSyncExternalStore` rewards (no spurious\n  // re-renders).\n  const preliminaryState = useMemo<S>(() => machine.init(null, ctx)[0], [machine, ctx]);\n\n  // `getSnapshot` reads the runtime if it has booted, else falls back to\n  // the preliminary state. The runtime's `getState` throws pre-boot when a\n  // store is configured — we catch that and substitute the preliminary\n  // value.\n  const getSnapshot = (): S => {\n    try {\n      return runtime.getState();\n    } catch {\n      return preliminaryState;\n    }\n  };\n\n  const state = useSyncExternalStore(runtime.subscribe, getSnapshot, getSnapshot);\n  useEffect(\n    () => () => {\n      // Fire-and-forget — `stop()` is async but `useEffect` cleanup is sync.\n      // The runtime swallows in-flight rejections internally, so this never\n      // rejects in practice; we still attach `.catch` for safety.\n      runtime.stop().catch(() => {});\n    },\n    [runtime],\n  );\n  return [state, runtime.dispatch];\n}\n\n/**\n * Lower-level escape hatch: consume an externally-built `Runtime<S, M>`.\n *\n * Use this when the runtime is owned by something OTHER than the component —\n * a parent component, a test harness, a singleton. **The component does NOT\n * call `runtime.stop()` on unmount** — the caller owns the lifecycle.\n *\n * Primary use case in this repo: component tests. Build a runtime with\n * `@demlik/tea/mem` and pre-seed it via `replay`, then mount the component with\n * `useRuntime(testRuntime)` to render in any phase.\n *\n * Returns `[state, dispatch]` — same shape as `useMachine`.\n */\nexport function useRuntime<S, M extends { type: string }>(\n  runtime: Runtime<S, M>,\n): [S, (msg: M) => Promise<void>] {\n  const state = useSyncExternalStore(runtime.subscribe, runtime.getState, runtime.getState);\n  return [state, runtime.dispatch];\n}\n"]}