@demlik/tea 0.1.0 → 0.1.2

package/dist/poller/index.d.ts

@@ -0,0 +1,288 @@
+import { DeadlineSub } from '../deadline/index.js';
+import { IdempotencyStore } from '../idempotency/index.js';
+import { C as Cmd, S as Sub } from '../core-BoB6t7dB.js';
+import { RetryPolicy, RetryState } from '../retry-backoff/index.js';
+import '../types-B-8bcAp8.js';
+
+/**
+ * @demlik/tea/poller — "poll a source every N ms until a predicate holds, with
+ * backoff on failure" as a TEA knob: one config object + a few pre-wired hooks
+ * you spread into your machine.
+ *
+ * The recipe (which bricks it composes):
+ *
+ *   - `../deadline`        — the recurring tick is an ABSOLUTE-deadline Sub.
+ *                            Each successful tick computes the NEXT absolute
+ *                            fire time (`at + everyMs`) and the knob re-arms a
+ *                            deadline against it. Absolute (not relative) so a
+ *                            poller resumed after a DO eviction / page reload
+ *                            fires at the correct wall-clock moment, not
+ *                            `everyMs` after the reload (`../deadline`'s late-
+ *                            subscribe property).
+ *   - `../retry-backoff`   — a failed tick does NOT reschedule on the steady
+ *                            cadence; it backs off. The next attempt is armed
+ *                            `nextDelayMs(retry, policy)` from now, the retry
+ *                            counter advances, and `shouldRetry` decides whether
+ *                            the poller keeps trying or gives up.
+ *   - `../idempotency`     — successive ticks against a flaky source can deliver
+ *                            the SAME observation twice (a retried fetch, a
+ *                            duplicate webhook the poll re-reads). `dedupeKey`
+ *                            lets the consumer key each tick result; a duplicate
+ *                            key is recorded but emits no fresh `onTick` follow-
+ *                            up Cmd, so the side effect runs once per distinct
+ *                            observation.
+ *
+ * Typical wiring (spread the knob's hooks into your machine):
+ *
+ *   const poll = createPoller<MyState, MyResult>({
+ *     everyMs: 5_000,
+ *     until: (s) => s.poll.lastResult?.status === "ready",
+ *     onTick: () => ({ type: "fetch_status" }),
+ *     retry: { ...defaultRetryPolicy, maxAttempts: 4 },
+ *   });
+ *
+ *   // Model slice:
+ *   init: (loaded) => [loaded ?? { poll: poll.init(), ... }, []],
+ *
+ *   // The deadline Sub fires `deadline_exceeded` on the cadence/backoff target;
+ *   // route it to `tick`, the ONLY place the `onTick` fetch is emitted:
+ *   deadline_exceeded: (s) => {
+ *     const [slice, cmds] = poll.tick(s.poll);
+ *     return [{ ...s, poll: slice }, cmds];
+ *   },
+ *
+ *   // update cells (thread `at` in from the firing Msg / the runtime clock):
+ *   poll_result: (s, m) => {
+ *     const untilHeld = config.until({ ...s, ...folded });
+ *     const [slice, cmds] = poll.tickResult(s.poll, m.result, m.at, untilHeld);
+ *     return [{ ...s, poll: slice }, cmds];
+ *   },
+ *   poll_error: (s, m) => {
+ *     const [slice, cmds] = poll.tickErr(s.poll, m.error, m.at);
+ *     return [{ ...s, poll: slice }, cmds];
+ *   },
+ *
+ *   // Subs — the knob owns the interval/backoff deadline:
+ *   subscriptions: (s) => poll.subs(s.poll),
+ *
+ * The cadence has exactly ONE source: the `everyMs` deadline Sub. `start`,
+ * `tickResult`, and `tickErr` only RE-ARM the deadline (they emit no cadence
+ * Cmd); the fetch fires solely from `tick`, which the consumer routes the
+ * deadline's `deadline_exceeded` Msg to. No verb performs an immediate
+ * "fire now" observation, so the poller never polls faster than `everyMs`.
+ *
+ * The two non-negotiables every knob preserves hold here:
+ *   - **Durable** — `tick`, `lastResult`, `retry`, and the next-fire target all
+ *     live in the Model slice, so a poller survives eviction and resumes its
+ *     cadence from the persisted target.
+ *   - **Replayable** — every transition is a pure verb returning new state; the
+ *     clock is never read inside a verb (the firing Msg carries `at`), and the
+ *     retry RNG is injected ONCE at `createPoller` and threaded internally (no
+ *     verb body names the global RNG). `replay` reconstructs a poll run exactly.
+ *
+ * NOT a substrate primitive: it depends only on sibling subpaths
+ * (`../deadline`, `../retry-backoff`, `../idempotency`) and the core `Cmd` /
+ * `Sub` types. Consumers reach it via the `@demlik/tea/poller` subpath; the L1
+ * escape hatch is those three sibling subpaths threaded by hand.
+ */
+
+/**
+ * The poller knob's config — the single object you hand `createPoller`.
+ *
+ * `State` is the consumer's WHOLE Model (so `until` can read any field), `R` is
+ * the shape of one tick observation (`lastResult` carries it forward).
+ */
+interface PollerConfig<State, R> {
+    /**
+     * The steady cadence, in milliseconds, between successful ticks. The next
+     * tick is armed at the absolute target `at + everyMs` (computed from the
+     * `at` the prior tick's Msg carried), NOT `everyMs` from when the Sub
+     * happens to be reconciled — so the cadence does not drift across resumes.
+     */
+    readonly everyMs: number;
+    /**
+     * The stop predicate, read against the consumer's whole Model. When it
+     * returns `true`, the poller is DONE: `subs` returns `[]` (the timer
+     * disarms) and no further tick is scheduled. Pure — it must not read the
+     * clock or mutate; the substrate calls it inside `subscriptions(state)`.
+     */
+    readonly until: (state: State) => boolean;
+    /**
+     * The effect to run on each tick — the actual "go observe the source" Cmd
+     * (a fetch, a status read, a list call). The knob returns it from
+     * `tickResult` when the run continues; the consumer's `interpret` performs
+     * it and routes the observation back as the next tick-result Msg.
+     *
+     * Nullary by contract: a tick carries no per-call argument (the poller
+     * re-reads the same source every cadence). Capture any target in the Cmd
+     * literal the consumer's `onTick` returns.
+     */
+    readonly onTick: () => Cmd;
+    /**
+     * Backoff policy for FAILED ticks. Omit to use `defaultRetryPolicy`
+     * (full-jitter, 5 attempts). A success resets the retry counter, so the
+     * policy only governs consecutive failures.
+     */
+    readonly retry?: RetryPolicy;
+    /**
+     * Optional dedupe key derived from a tick result. When provided, a result
+     * whose key was already `seen` records the observation but emits NO fresh
+     * `onTick` follow-up — the side effect runs once per distinct observation.
+     * Omit to treat every tick result as fresh (no dedupe). The dedupe store is
+     * bounded by `dedupeTtlMs` if set; otherwise it grows with distinct keys.
+     */
+    readonly dedupeKey?: (result: R) => string;
+    /**
+     * TTL for the dedupe store, in milliseconds. Only meaningful when
+     * `dedupeKey` is set. An observation older than `dedupeTtlMs` is forgotten,
+     * so a key seen long ago is treated as fresh again. Omit for an unbounded
+     * dedupe window (every distinct key remembered for the poller's lifetime).
+     */
+    readonly dedupeTtlMs?: number;
+}
+/**
+ * The Model field the poller knob owns — its visible slice (the knob principle:
+ * managed state lives in the Model, never a closure, so it is durable and
+ * replayable).
+ *
+ * - `tick`       — count of ticks recorded so far (success or failure). Doubles
+ *                  as an observability cursor and a stable per-tick discriminant.
+ * - `lastResult` — the most recent successful observation, or `undefined`
+ *                  before the first success. `until` typically reads it (via the
+ *                  consumer's Model), but the knob never interprets it.
+ * - `retry`      — the `../retry-backoff` counter for consecutive failures.
+ *                  Reset to `initRetry()` on every success.
+ * - `nextAtMs`   — the ABSOLUTE target the interval/backoff timer is armed
+ *                  against, or `null` when the poller is done / not yet started.
+ *                  Persisted so a resumed poller re-arms the same moment.
+ * - `phase`      — `"polling"` while ticks are scheduled, `"done"` once `until`
+ *                  held, `"gave_up"` once backoff exhausted `maxAttempts`.
+ * - `dedupe`     — the `../idempotency` store backing `dedupeKey`. An empty,
+ *                  unbounded store when `dedupeKey` is unset (never written).
+ */
+interface PollerState<R> {
+    readonly tick: number;
+    readonly lastResult?: R;
+    readonly retry: RetryState;
+    readonly nextAtMs: number | null;
+    readonly phase: "polling" | "done" | "gave_up";
+    readonly dedupe: IdempotencyStore<true>;
+}
+/**
+ * The poller Sub type — a `../deadline` Sub under a fixed id family. One id per
+ * knob instance keeps the reconcile pass from churning the timer: the same id
+ * across transitions means "same armed deadline", even as `nextAtMs` advances.
+ */
+type PollerSub = DeadlineSub;
+/**
+ * The knob handle returned by `createPoller`. Spread its hooks into your
+ * machine: `init()` seeds the slice, `start(...)` arms the first tick,
+ * `tickResult` / `tickErr` are the two update verbs, and `subs(...)` returns the
+ * timer Sub while the poller is live.
+ *
+ * Pure-ops + subs module: there is no `handlers(ports)` cell. The poller's I/O
+ * is the consumer's own `onTick` Cmd run by the consumer's `interpret` — the
+ * knob never owns a port. (Compare `../deadline`, which ships a `subscribe`
+ * cell; the poller reuses `../deadline`'s, so it has nothing of its own to
+ * splice into `interpret`.)
+ */
+interface Poller<State, R> {
+    /** Seed the Model slice. Idle until `start(...)` arms the first tick. */
+    init(): PollerState<R>;
+    /**
+     * Arm the first tick. `at` is the current clock (carried in from the Msg /
+     * runtime that kicks the poller off — never read inside the verb). Returns
+     * the slice with the first deadline target set to `at + everyMs` and emits NO
+     * Cmd. The cadence has ONE source — the deadline Sub — so `start` does not
+     * perform the first observation itself (an immediate `onTick` here would race
+     * the timer and poll as fast as the source responds). The first observation
+     * fires when the deadline crosses `at + everyMs` and the consumer routes
+     * `deadline_exceeded` → `tick`.
+     */
+    start(state: PollerState<R>, at: number): readonly [PollerState<R>, readonly Cmd[]];
+    /**
+     * Perform one observation — the cadence verb. The consumer routes the
+     * deadline Sub's `deadline_exceeded` Msg here; `tick` emits the single
+     * `config.onTick()` Cmd that goes and reads the source. This is the ONLY
+     * next-tick mechanism: the timer fires, the consumer calls `tick`, the fetch
+     * runs, and the observation comes back through `tickResult` / `tickErr`
+     * (which re-arm the next deadline). A no-op on a finished poller — a stale
+     * deadline fire racing a terminal transition the reconcile pass has not yet
+     * retired emits nothing.
+     *
+     * Takes no `at`: `tick` does not touch the schedule (the just-fired deadline
+     * is exhausted; the next target is set when the result lands), so it needs no
+     * clock — keeping it trivially pure.
+     */
+    tick(state: PollerState<R>): readonly [PollerState<R>, readonly Cmd[]];
+    /**
+     * Record a successful tick observation at clock `at`.
+     *
+     * - Resets the retry counter (a success clears consecutive-failure state).
+     * - Stores `result` as `lastResult` and bumps `tick`.
+     * - Re-arms the next tick at the absolute target `at + everyMs` (the steady
+     *   cadence). It emits NO cadence `onTick` — the next observation fires from
+     *   the deadline Sub via `tick`, never immediately from a result.
+     * - Dedupe (opt-in, orthogonal to cadence): when `dedupeKey` is set, a FRESH
+     *   observation emits one `onTick` FOLLOW-UP (the consumer's "run the
+     *   downstream side effect once per distinct observation" hook) and a
+     *   DUPLICATE key records the sighting but suppresses the follow-up. With no
+     *   `dedupeKey`, `tickResult` emits nothing — the cadence `tick` is the only
+     *   `onTick`, so an unconfigured poller never double-fetches.
+     * - UNLESS `untilHeld` is `true` (the consumer evaluated `config.until`
+     *   against the post-result Model) — then the poller enters `"done"`,
+     *   disarms (`nextAtMs: null`), and emits no Cmd, dedupe or otherwise.
+     *
+     * `untilHeld` is passed in rather than computed here because `until` reads
+     * the consumer's WHOLE Model, which this verb does not hold — the consumer
+     * evaluates it at the call site after folding `result` into its Model and
+     * passes the boolean. (`subs` re-checks `phase` to decide arming, so a
+     * mis-passed `untilHeld` cannot leave a "done" poller arming timers.)
+     */
+    tickResult(state: PollerState<R>, result: R, at: number, untilHeld: boolean): readonly [PollerState<R>, readonly Cmd[]];
+    /**
+     * Record a FAILED tick at clock `at`. Backs off instead of holding the
+     * steady cadence:
+     *
+     * - Advances the retry counter (`recordFailure`).
+     * - If `shouldRetry` still permits another attempt, arms the next tick at
+     *   `at + nextDelayMs(retry, policy)` (the backoff curve) and emits NO Cmd —
+     *   the retry observation fires when that backoff deadline crosses and the
+     *   consumer routes `deadline_exceeded` → `tick`. The timer is the single
+     *   next-tick mechanism, on the backoff curve here instead of `everyMs`.
+     * - If backoff is exhausted (`!shouldRetry`), enters `"gave_up"`, disarms
+     *   (`nextAtMs: null`), and emits no Cmd.
+     *
+     * The backoff jitter uses the `rng` injected ONCE at `createPoller` (default
+     * `Math.random` at the effect boundary, a fixed value in tests); the verb
+     * body never names the global RNG, so a poller built with a fixed `rng`
+     * replays a failure-and-backoff run bit-for-bit.
+     */
+    tickErr(state: PollerState<R>, error: unknown, at: number): readonly [PollerState<R>, readonly Cmd[]];
+    /**
+     * The pre-wired subscriptions cell. Returns the single tick-deadline Sub
+     * while the poller is `"polling"` with an armed `nextAtMs`; returns `[]`
+     * once `"done"` / `"gave_up"` (the timer disarms) or before `start`. Assign
+     * directly: `subscriptions: (s) => poll.subs(s.poll)`.
+     *
+     * The `DeadlineSub` it returns is consumed by `../deadline`'s
+     * `subscribeDeadline` cell, which the consumer wires into `subscribe` —
+     * the poller does not redraw the timer lifecycle.
+     */
+    subs(state: PollerState<R>): readonly Sub[];
+}
+/**
+ * Build a poller knob from `config`. Returns the hook bag to spread into a
+ * machine (see the module doc-comment for the wiring). Pure factory — no clock
+ * read, no timer; everything happens when the consumer calls the returned
+ * verbs / `subs` with an injected `at`.
+ *
+ * `rng` is injected ONCE here (default `Math.random` at the effect boundary, a
+ * fixed value in tests) and threaded internally into the backoff jitter. No
+ * verb body ever names the global RNG, so a poller built with a fixed `rng`
+ * replays a failure-and-backoff run bit-for-bit (invariant 2: the verbs are
+ * pure given the injected `rng`).
+ */
+declare function createPoller<State, R>(config: PollerConfig<State, R>, rng?: () => number): Poller<State, R>;
+
+export { type Poller, type PollerConfig, type PollerState, type PollerSub, createPoller };

package/dist/poller/index.js

@@ -0,0 +1,79 @@
+import { deadlineSub } from '../chunk-K7Q23EQ4.js';
+import { asRng, defaultRetryPolicy, initRetry, recordFailure, shouldRetry, nextDelayMs } from '../chunk-5VNWZADP.js';
+import { idempotencyMemory } from '../chunk-BYQUGDD3.js';
+import '../chunk-K575PT4S.js';
+import '../chunk-2YFLOCWX.js';
+import '../chunk-MMH7CW5K.js';
+import '../chunk-QLA76GIT.js';
+
+// src/poller/index.ts
+function pollerSubId(atMs) {
+  return `poller:tick:${atMs}`;
+}
+function createPoller(config, rng = Math.random) {
+  const rngBranded = asRng(rng);
+  const policy = config.retry ?? defaultRetryPolicy;
+  const memory = idempotencyMemory();
+  function init() {
+    return {
+      tick: 0,
+      retry: initRetry(),
+      nextAtMs: null,
+      phase: "polling",
+      // The dedupe store is created regardless; it is only WRITTEN when
+      // `dedupeKey` is set, so an unconfigured poller carries an inert empty
+      // store (no per-op cost, JSON-serializable, durable like the rest of
+      // the slice).
+      dedupe: memory.init({ ttlMs: config.dedupeTtlMs })
+    };
+  }
+  function start(state, at) {
+    return [{ ...state, phase: "polling", nextAtMs: at + config.everyMs }, []];
+  }
+  function tick(state) {
+    if (state.phase !== "polling") return [state, []];
+    return [state, [config.onTick()]];
+  }
+  function tickResult(state, result, at, untilHeld) {
+    const base = {
+      ...state,
+      tick: state.tick + 1,
+      lastResult: result,
+      retry: initRetry()
+    };
+    if (untilHeld) {
+      return [{ ...base, phase: "done", nextAtMs: null }, []];
+    }
+    const next = {
+      ...base,
+      phase: "polling",
+      nextAtMs: at + config.everyMs
+    };
+    if (!config.dedupeKey) return [next, []];
+    const key = config.dedupeKey(result);
+    const suppress = memory.isSeen(next.dedupe, key, at);
+    const deduped = {
+      ...next,
+      dedupe: memory.remember(next.dedupe, key, true, at)
+    };
+    return [deduped, suppress ? [] : [config.onTick()]];
+  }
+  function tickErr(state, error, at) {
+    const retry = recordFailure(state.retry, error);
+    const failed = { ...state, tick: state.tick + 1, retry };
+    if (!shouldRetry(retry, policy)) {
+      return [{ ...failed, phase: "gave_up", nextAtMs: null }, []];
+    }
+    const delayMs = nextDelayMs(retry, policy, rngBranded);
+    return [{ ...failed, phase: "polling", nextAtMs: at + delayMs }, []];
+  }
+  function subs(state) {
+    if (state.phase !== "polling" || state.nextAtMs === null) return [];
+    return [deadlineSub(pollerSubId(state.nextAtMs), state.nextAtMs)];
+  }
+  return { init, start, tick, tickResult, tickErr, subs };
+}
+
+export { createPoller };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/poller/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/poller/index.ts"],"names":[],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @demlik/tea/poller — \"poll a source every N ms until a predicate holds, with\n * backoff on failure\" as a TEA knob: one config object + a few pre-wired hooks\n * you spread into your machine.\n *\n * The recipe (which bricks it composes):\n *\n *   - `../deadline`        — the recurring tick is an ABSOLUTE-deadline Sub.\n *                            Each successful tick computes the NEXT absolute\n *                            fire time (`at + everyMs`) and the knob re-arms a\n *                            deadline against it. Absolute (not relative) so a\n *                            poller resumed after a DO eviction / page reload\n *                            fires at the correct wall-clock moment, not\n *                            `everyMs` after the reload (`../deadline`'s late-\n *                            subscribe property).\n *   - `../retry-backoff`   — a failed tick does NOT reschedule on the steady\n *                            cadence; it backs off. The next attempt is armed\n *                            `nextDelayMs(retry, policy)` from now, the retry\n *                            counter advances, and `shouldRetry` decides whether\n *                            the poller keeps trying or gives up.\n *   - `../idempotency`     — successive ticks against a flaky source can deliver\n *                            the SAME observation twice (a retried fetch, a\n *                            duplicate webhook the poll re-reads). `dedupeKey`\n *                            lets the consumer key each tick result; a duplicate\n *                            key is recorded but emits no fresh `onTick` follow-\n *                            up Cmd, so the side effect runs once per distinct\n *                            observation.\n *\n * Typical wiring (spread the knob's hooks into your machine):\n *\n *   const poll = createPoller<MyState, MyResult>({\n *     everyMs: 5_000,\n *     until: (s) => s.poll.lastResult?.status === \"ready\",\n *     onTick: () => ({ type: \"fetch_status\" }),\n *     retry: { ...defaultRetryPolicy, maxAttempts: 4 },\n *   });\n *\n *   // Model slice:\n *   init: (loaded) => [loaded ?? { poll: poll.init(), ... }, []],\n *\n *   // The deadline Sub fires `deadline_exceeded` on the cadence/backoff target;\n *   // route it to `tick`, the ONLY place the `onTick` fetch is emitted:\n *   deadline_exceeded: (s) => {\n *     const [slice, cmds] = poll.tick(s.poll);\n *     return [{ ...s, poll: slice }, cmds];\n *   },\n *\n *   // update cells (thread `at` in from the firing Msg / the runtime clock):\n *   poll_result: (s, m) => {\n *     const untilHeld = config.until({ ...s, ...folded });\n *     const [slice, cmds] = poll.tickResult(s.poll, m.result, m.at, untilHeld);\n *     return [{ ...s, poll: slice }, cmds];\n *   },\n *   poll_error: (s, m) => {\n *     const [slice, cmds] = poll.tickErr(s.poll, m.error, m.at);\n *     return [{ ...s, poll: slice }, cmds];\n *   },\n *\n *   // Subs — the knob owns the interval/backoff deadline:\n *   subscriptions: (s) => poll.subs(s.poll),\n *\n * The cadence has exactly ONE source: the `everyMs` deadline Sub. `start`,\n * `tickResult`, and `tickErr` only RE-ARM the deadline (they emit no cadence\n * Cmd); the fetch fires solely from `tick`, which the consumer routes the\n * deadline's `deadline_exceeded` Msg to. No verb performs an immediate\n * \"fire now\" observation, so the poller never polls faster than `everyMs`.\n *\n * The two non-negotiables every knob preserves hold here:\n *   - **Durable** — `tick`, `lastResult`, `retry`, and the next-fire target all\n *     live in the Model slice, so a poller survives eviction and resumes its\n *     cadence from the persisted target.\n *   - **Replayable** — every transition is a pure verb returning new state; the\n *     clock is never read inside a verb (the firing Msg carries `at`), and the\n *     retry RNG is injected ONCE at `createPoller` and threaded internally (no\n *     verb body names the global RNG). `replay` reconstructs a poll run exactly.\n *\n * NOT a substrate primitive: it depends only on sibling subpaths\n * (`../deadline`, `../retry-backoff`, `../idempotency`) and the core `Cmd` /\n * `Sub` types. Consumers reach it via the `@demlik/tea/poller` subpath; the L1\n * escape hatch is those three sibling subpaths threaded by hand.\n */\n\nimport { type DeadlineSub, deadlineSub } from \"../deadline\";\nimport type { IdempotencyStore } from \"../idempotency\";\nimport { idempotencyMemory } from \"../idempotency/adapter\";\nimport type { Cmd, Sub } from \"../index\";\nimport {\n  asRng,\n  defaultRetryPolicy,\n  initRetry,\n  nextDelayMs,\n  type RetryPolicy,\n  type RetryState,\n  recordFailure,\n  shouldRetry,\n} from \"../retry-backoff\";\n\n/**\n * The poller knob's config — the single object you hand `createPoller`.\n *\n * `State` is the consumer's WHOLE Model (so `until` can read any field), `R` is\n * the shape of one tick observation (`lastResult` carries it forward).\n */\nexport interface PollerConfig<State, R> {\n  /**\n   * The steady cadence, in milliseconds, between successful ticks. The next\n   * tick is armed at the absolute target `at + everyMs` (computed from the\n   * `at` the prior tick's Msg carried), NOT `everyMs` from when the Sub\n   * happens to be reconciled — so the cadence does not drift across resumes.\n   */\n  readonly everyMs: number;\n  /**\n   * The stop predicate, read against the consumer's whole Model. When it\n   * returns `true`, the poller is DONE: `subs` returns `[]` (the timer\n   * disarms) and no further tick is scheduled. Pure — it must not read the\n   * clock or mutate; the substrate calls it inside `subscriptions(state)`.\n   */\n  readonly until: (state: State) => boolean;\n  /**\n   * The effect to run on each tick — the actual \"go observe the source\" Cmd\n   * (a fetch, a status read, a list call). The knob returns it from\n   * `tickResult` when the run continues; the consumer's `interpret` performs\n   * it and routes the observation back as the next tick-result Msg.\n   *\n   * Nullary by contract: a tick carries no per-call argument (the poller\n   * re-reads the same source every cadence). Capture any target in the Cmd\n   * literal the consumer's `onTick` returns.\n   */\n  readonly onTick: () => Cmd;\n  /**\n   * Backoff policy for FAILED ticks. Omit to use `defaultRetryPolicy`\n   * (full-jitter, 5 attempts). A success resets the retry counter, so the\n   * policy only governs consecutive failures.\n   */\n  readonly retry?: RetryPolicy;\n  /**\n   * Optional dedupe key derived from a tick result. When provided, a result\n   * whose key was already `seen` records the observation but emits NO fresh\n   * `onTick` follow-up — the side effect runs once per distinct observation.\n   * Omit to treat every tick result as fresh (no dedupe). The dedupe store is\n   * bounded by `dedupeTtlMs` if set; otherwise it grows with distinct keys.\n   */\n  readonly dedupeKey?: (result: R) => string;\n  /**\n   * TTL for the dedupe store, in milliseconds. Only meaningful when\n   * `dedupeKey` is set. An observation older than `dedupeTtlMs` is forgotten,\n   * so a key seen long ago is treated as fresh again. Omit for an unbounded\n   * dedupe window (every distinct key remembered for the poller's lifetime).\n   */\n  readonly dedupeTtlMs?: number;\n}\n\n/**\n * The Model field the poller knob owns — its visible slice (the knob principle:\n * managed state lives in the Model, never a closure, so it is durable and\n * replayable).\n *\n * - `tick`       — count of ticks recorded so far (success or failure). Doubles\n *                  as an observability cursor and a stable per-tick discriminant.\n * - `lastResult` — the most recent successful observation, or `undefined`\n *                  before the first success. `until` typically reads it (via the\n *                  consumer's Model), but the knob never interprets it.\n * - `retry`      — the `../retry-backoff` counter for consecutive failures.\n *                  Reset to `initRetry()` on every success.\n * - `nextAtMs`   — the ABSOLUTE target the interval/backoff timer is armed\n *                  against, or `null` when the poller is done / not yet started.\n *                  Persisted so a resumed poller re-arms the same moment.\n * - `phase`      — `\"polling\"` while ticks are scheduled, `\"done\"` once `until`\n *                  held, `\"gave_up\"` once backoff exhausted `maxAttempts`.\n * - `dedupe`     — the `../idempotency` store backing `dedupeKey`. An empty,\n *                  unbounded store when `dedupeKey` is unset (never written).\n */\nexport interface PollerState<R> {\n  readonly tick: number;\n  readonly lastResult?: R;\n  readonly retry: RetryState;\n  readonly nextAtMs: number | null;\n  readonly phase: \"polling\" | \"done\" | \"gave_up\";\n  readonly dedupe: IdempotencyStore<true>;\n}\n\n/**\n * The poller Sub type — a `../deadline` Sub under a fixed id family. One id per\n * knob instance keeps the reconcile pass from churning the timer: the same id\n * across transitions means \"same armed deadline\", even as `nextAtMs` advances.\n */\nexport type PollerSub = DeadlineSub;\n\n/**\n * The Sub id the poller arms its tick deadline under, keyed on the absolute\n * target. The id ROTATES per target because a one-shot deadline timer is\n * exhausted once it fires and the substrate reconciles subs by `id` alone: a\n * fixed id would leave the fired timer registered and never re-arm, so the\n * cadence would die after exactly one tick. Encoding `atMs` in the id makes each\n * cadence/backoff target a distinct identity — the reconcile pass retires the\n * spent timer and arms the next — while a resumed poller re-arms the SAME id\n * from its persisted `nextAtMs` (eviction is idempotent).\n *\n * A single poller machine arms exactly one tick timer at a time; a consumer\n * running several pollers on one machine namespaces them by composing the knob\n * under distinct slices (a future multi-poller config would thread a prefix).\n */\nfunction pollerSubId(atMs: number): string {\n  return `poller:tick:${atMs}`;\n}\n\n/**\n * The knob handle returned by `createPoller`. Spread its hooks into your\n * machine: `init()` seeds the slice, `start(...)` arms the first tick,\n * `tickResult` / `tickErr` are the two update verbs, and `subs(...)` returns the\n * timer Sub while the poller is live.\n *\n * Pure-ops + subs module: there is no `handlers(ports)` cell. The poller's I/O\n * is the consumer's own `onTick` Cmd run by the consumer's `interpret` — the\n * knob never owns a port. (Compare `../deadline`, which ships a `subscribe`\n * cell; the poller reuses `../deadline`'s, so it has nothing of its own to\n * splice into `interpret`.)\n */\nexport interface Poller<\n  // State is a phantom-style parameter — present so consumers can spell\n  // `Poller<MyState, MyResult>` matching `createPoller<State, R>`. It is\n  // consumed by the config's `until` predicate, not by any handle method, so\n  // it does not appear in the interface body. Same discipline as\n  // `BoundMachine`'s `Ctx`.\n  // biome-ignore lint/correctness/noUnusedVariables: phantom type parameter (see above)\n  State,\n  R,\n> {\n  /** Seed the Model slice. Idle until `start(...)` arms the first tick. */\n  init(): PollerState<R>;\n  /**\n   * Arm the first tick. `at` is the current clock (carried in from the Msg /\n   * runtime that kicks the poller off — never read inside the verb). Returns\n   * the slice with the first deadline target set to `at + everyMs` and emits NO\n   * Cmd. The cadence has ONE source — the deadline Sub — so `start` does not\n   * perform the first observation itself (an immediate `onTick` here would race\n   * the timer and poll as fast as the source responds). The first observation\n   * fires when the deadline crosses `at + everyMs` and the consumer routes\n   * `deadline_exceeded` → `tick`.\n   */\n  start(\n    state: PollerState<R>,\n    at: number,\n  ): readonly [PollerState<R>, readonly Cmd[]];\n  /**\n   * Perform one observation — the cadence verb. The consumer routes the\n   * deadline Sub's `deadline_exceeded` Msg here; `tick` emits the single\n   * `config.onTick()` Cmd that goes and reads the source. This is the ONLY\n   * next-tick mechanism: the timer fires, the consumer calls `tick`, the fetch\n   * runs, and the observation comes back through `tickResult` / `tickErr`\n   * (which re-arm the next deadline). A no-op on a finished poller — a stale\n   * deadline fire racing a terminal transition the reconcile pass has not yet\n   * retired emits nothing.\n   *\n   * Takes no `at`: `tick` does not touch the schedule (the just-fired deadline\n   * is exhausted; the next target is set when the result lands), so it needs no\n   * clock — keeping it trivially pure.\n   */\n  tick(state: PollerState<R>): readonly [PollerState<R>, readonly Cmd[]];\n  /**\n   * Record a successful tick observation at clock `at`.\n   *\n   * - Resets the retry counter (a success clears consecutive-failure state).\n   * - Stores `result` as `lastResult` and bumps `tick`.\n   * - Re-arms the next tick at the absolute target `at + everyMs` (the steady\n   *   cadence). It emits NO cadence `onTick` — the next observation fires from\n   *   the deadline Sub via `tick`, never immediately from a result.\n   * - Dedupe (opt-in, orthogonal to cadence): when `dedupeKey` is set, a FRESH\n   *   observation emits one `onTick` FOLLOW-UP (the consumer's \"run the\n   *   downstream side effect once per distinct observation\" hook) and a\n   *   DUPLICATE key records the sighting but suppresses the follow-up. With no\n   *   `dedupeKey`, `tickResult` emits nothing — the cadence `tick` is the only\n   *   `onTick`, so an unconfigured poller never double-fetches.\n   * - UNLESS `untilHeld` is `true` (the consumer evaluated `config.until`\n   *   against the post-result Model) — then the poller enters `\"done\"`,\n   *   disarms (`nextAtMs: null`), and emits no Cmd, dedupe or otherwise.\n   *\n   * `untilHeld` is passed in rather than computed here because `until` reads\n   * the consumer's WHOLE Model, which this verb does not hold — the consumer\n   * evaluates it at the call site after folding `result` into its Model and\n   * passes the boolean. (`subs` re-checks `phase` to decide arming, so a\n   * mis-passed `untilHeld` cannot leave a \"done\" poller arming timers.)\n   */\n  tickResult(\n    state: PollerState<R>,\n    result: R,\n    at: number,\n    untilHeld: boolean,\n  ): readonly [PollerState<R>, readonly Cmd[]];\n  /**\n   * Record a FAILED tick at clock `at`. Backs off instead of holding the\n   * steady cadence:\n   *\n   * - Advances the retry counter (`recordFailure`).\n   * - If `shouldRetry` still permits another attempt, arms the next tick at\n   *   `at + nextDelayMs(retry, policy)` (the backoff curve) and emits NO Cmd —\n   *   the retry observation fires when that backoff deadline crosses and the\n   *   consumer routes `deadline_exceeded` → `tick`. The timer is the single\n   *   next-tick mechanism, on the backoff curve here instead of `everyMs`.\n   * - If backoff is exhausted (`!shouldRetry`), enters `\"gave_up\"`, disarms\n   *   (`nextAtMs: null`), and emits no Cmd.\n   *\n   * The backoff jitter uses the `rng` injected ONCE at `createPoller` (default\n   * `Math.random` at the effect boundary, a fixed value in tests); the verb\n   * body never names the global RNG, so a poller built with a fixed `rng`\n   * replays a failure-and-backoff run bit-for-bit.\n   */\n  tickErr(\n    state: PollerState<R>,\n    error: unknown,\n    at: number,\n  ): readonly [PollerState<R>, readonly Cmd[]];\n  /**\n   * The pre-wired subscriptions cell. Returns the single tick-deadline Sub\n   * while the poller is `\"polling\"` with an armed `nextAtMs`; returns `[]`\n   * once `\"done\"` / `\"gave_up\"` (the timer disarms) or before `start`. Assign\n   * directly: `subscriptions: (s) => poll.subs(s.poll)`.\n   *\n   * The `DeadlineSub` it returns is consumed by `../deadline`'s\n   * `subscribeDeadline` cell, which the consumer wires into `subscribe` —\n   * the poller does not redraw the timer lifecycle.\n   */\n  subs(state: PollerState<R>): readonly Sub[];\n}\n\n/**\n * Build a poller knob from `config`. Returns the hook bag to spread into a\n * machine (see the module doc-comment for the wiring). Pure factory — no clock\n * read, no timer; everything happens when the consumer calls the returned\n * verbs / `subs` with an injected `at`.\n *\n * `rng` is injected ONCE here (default `Math.random` at the effect boundary, a\n * fixed value in tests) and threaded internally into the backoff jitter. No\n * verb body ever names the global RNG, so a poller built with a fixed `rng`\n * replays a failure-and-backoff run bit-for-bit (invariant 2: the verbs are\n * pure given the injected `rng`).\n */\nexport function createPoller<State, R>(\n  config: PollerConfig<State, R>,\n  rng: () => number = Math.random,\n): Poller<State, R> {\n  // Re-affirm the `[0, 1)` contract at the seam where the injected generator\n  // enters the backoff math (brand from `../retry-backoff`). The factory's\n  // public param stays a plain `() => number` so transitive callers are\n  // unchanged; `asRng` is the single point where it's branded for `nextDelayMs`.\n  const rngBranded = asRng(rng);\n  const policy: RetryPolicy = config.retry ?? defaultRetryPolicy;\n\n  // The dedupe store seam, bound once. The poller delegates its dedupe-window\n  // reads (`memory.isSeen`) and the per-sighting touch (`memory.remember`) to\n  // the verbs, so the `IdempotencyStore` shape stays insulated.\n  const memory = idempotencyMemory<true>();\n\n  function init(): PollerState<R> {\n    return {\n      tick: 0,\n      retry: initRetry(),\n      nextAtMs: null,\n      phase: \"polling\",\n      // The dedupe store is created regardless; it is only WRITTEN when\n      // `dedupeKey` is set, so an unconfigured poller carries an inert empty\n      // store (no per-op cost, JSON-serializable, durable like the rest of\n      // the slice).\n      dedupe: memory.init({ ttlMs: config.dedupeTtlMs }),\n    };\n  }\n\n  function start(\n    state: PollerState<R>,\n    at: number,\n  ): readonly [PollerState<R>, readonly Cmd[]] {\n    // Arm the first deadline at `at + everyMs` and emit NOTHING. The cadence has\n    // ONE source — the `everyMs` deadline Sub. `start` does not perform the\n    // first observation itself: that would be a second, immediate next-tick\n    // mechanism racing the timer (it would fire as fast as the source responds,\n    // never honoring `everyMs`). The first observation fires when the deadline\n    // crosses `at + everyMs` and the consumer routes `deadline_exceeded` → the\n    // `tick` verb (which emits `onTick`). No drift, no double-fire.\n    return [{ ...state, phase: \"polling\", nextAtMs: at + config.everyMs }, []];\n  }\n\n  function tick(\n    state: PollerState<R>,\n  ): readonly [PollerState<R>, readonly Cmd[]] {\n    // The deadline fired. Perform the observation — this is the ONLY place the\n    // `onTick` Cmd is emitted, so the timer is the single next-tick mechanism.\n    // No schedule change here: the just-fired deadline is exhausted, and the\n    // NEXT target is re-armed when the observation lands (`tickResult` /\n    // `tickErr`). A no-op on a finished poller (a stale fire racing a terminal\n    // transition the reconcile pass has not yet retired).\n    if (state.phase !== \"polling\") return [state, []];\n    return [state, [config.onTick()]];\n  }\n\n  function tickResult(\n    state: PollerState<R>,\n    result: R,\n    at: number,\n    untilHeld: boolean,\n  ): readonly [PollerState<R>, readonly Cmd[]] {\n    // A success always clears consecutive-failure state and records the datum.\n    const base: PollerState<R> = {\n      ...state,\n      tick: state.tick + 1,\n      lastResult: result,\n      retry: initRetry(),\n    };\n\n    // Stop condition first: if the consumer's `until` held against the\n    // post-result Model, we are DONE — disarm and emit nothing, regardless of\n    // dedupe (the final observation is still recorded as `lastResult`).\n    if (untilHeld) {\n      return [{ ...base, phase: \"done\", nextAtMs: null }, []];\n    }\n\n    // Re-arm the steady cadence: the next observation fires when THIS deadline\n    // (`at + everyMs`) crosses and the consumer routes `deadline_exceeded` →\n    // `tick`. `tickResult` itself never emits the cadence `onTick` — the timer\n    // is the single next-tick mechanism (recording a result is not a reason to\n    // immediately re-fetch; that would poll as fast as the source responds).\n    const next: PollerState<R> = {\n      ...base,\n      phase: \"polling\",\n      nextAtMs: at + config.everyMs,\n    };\n\n    // Dedupe is an OPT-IN follow-up, orthogonal to the cadence above. When\n    // `dedupeKey` is set, a FRESH observation emits one `onTick` follow-up (the\n    // consumer's \"run the downstream side effect once per distinct observation\"\n    // hook); a DUPLICATE key records the sighting but suppresses that follow-up.\n    // With no `dedupeKey` there is no follow-up at all — the cadence `tick` is\n    // the only `onTick`, so an unconfigured poller never double-fetches.\n    if (!config.dedupeKey) return [next, []];\n\n    const key = config.dedupeKey(result);\n    const suppress = memory.isSeen(next.dedupe, key, at);\n    // `remember` refreshes the key's TTL clock on every sighting (the\n    // idempotency \"touch\" semantics), so a steadily-repeating observation never\n    // ages out mid-poll. The stored value is the unit `true` — the poller only\n    // needs presence, not a payload.\n    const deduped: PollerState<R> = {\n      ...next,\n      dedupe: memory.remember(next.dedupe, key, true, at),\n    };\n    return [deduped, suppress ? [] : [config.onTick()]];\n  }\n\n  function tickErr(\n    state: PollerState<R>,\n    error: unknown,\n    at: number,\n  ): readonly [PollerState<R>, readonly Cmd[]] {\n    const retry = recordFailure(state.retry, error);\n    const failed: PollerState<R> = { ...state, tick: state.tick + 1, retry };\n\n    // Backoff exhausted → give up: disarm and emit nothing. `shouldRetry`\n    // reads the just-advanced `retry`, so the (maxAttempts)-th failure is the\n    // one that stops the poller.\n    if (!shouldRetry(retry, policy)) {\n      return [{ ...failed, phase: \"gave_up\", nextAtMs: null }, []];\n    }\n\n    // Back off: arm the next attempt at `at + backoff(retry)` rather than the\n    // steady cadence, and emit NOTHING. The retry observation fires when this\n    // backoff deadline crosses and the consumer routes `deadline_exceeded` →\n    // `tick` — the timer is the single next-tick mechanism, on the backoff\n    // curve here instead of `everyMs`. `rng` is the value injected once at\n    // `createPoller`; the verb body never names the global RNG, so a fixed\n    // `rng` makes the backoff target replay bit-for-bit.\n    const delayMs = nextDelayMs(retry, policy, rngBranded);\n    return [{ ...failed, phase: \"polling\", nextAtMs: at + delayMs }, []];\n  }\n\n  function subs(state: PollerState<R>): readonly Sub[] {\n    // Arm the tick deadline only while live. `phase` is the authority (so a\n    // mis-passed `untilHeld` into `tickResult` cannot resurrect a finished\n    // poller); `nextAtMs` is the absolute target `../deadline` translates to a\n    // remaining delay at subscribe time — a resumed poller re-arms the exact\n    // persisted moment.\n    if (state.phase !== \"polling\" || state.nextAtMs === null) return [];\n    // The Sub id ROTATES with the target. A one-shot deadline timer is\n    // exhausted once it fires, and the substrate's reconcile pass keys identity\n    // by `id` alone — a fixed id would leave the fired timer in the registry and\n    // NEVER re-arm for the next cadence (cadence dies after one tick). Folding\n    // `nextAtMs` into the id makes each successive target a distinct identity:\n    // the reconcile pass retires the spent timer (old id absent from the desired\n    // set) and arms the next one (new id). A resumed poller re-arms the SAME id\n    // from its persisted `nextAtMs`, so eviction is idempotent.\n    return [deadlineSub(pollerSubId(state.nextAtMs), state.nextAtMs)];\n  }\n\n  return { init, start, tick, tickResult, tickErr, subs };\n}\n"]}

package/dist/prediction/index.d.ts

@@ -0,0 +1,130 @@
+import { C as Cmd, S as Sub, M as Machine } from '../core-BoB6t7dB.js';
+
+/**
+ * @demlik/tea/prediction — the client-prediction ack primitive (epic #186, facet 2).
+ *
+ * The contract the Gambetta/Valve authoritative-server netcode loop needs:
+ * **command-seq-in → last-applied-seq-out.** A client tags each predicted
+ * command/`Msg` with a monotonic `seq`; the authoritative side replies with the
+ * `lastAppliedSeq` it has processed. `partitionByAck` then splits the client's
+ * pending buffer into the inputs the server has ACKED (`seq <= lastAppliedSeq`)
+ * and those still PENDING (`seq > lastAppliedSeq`) — the un-acked tail the
+ * reconciliation pass (#214) replays over the authoritative snapshot via
+ * `foldMsgs` (#211, `@demlik/tea/pure`).
+ *
+ * Deliberately **Model-shape-agnostic** (ADR 0006): the ack is a standalone
+ * value, NOT a field this module requires on the consumer's `State`. It
+ * generalizes the `lastAckedSeq`-on-the-Model + `seq`-threaded-through-the-Msg
+ * pattern vortex hand-rolled (epic #186). It is a LEAF module — pure and
+ * runtime-free, importing nothing from the tea core or host, so it can never
+ * drag `run`/the host into a client bundle.
+ *
+ * This is the read/ack side of the primitive; `tagSeq`/`nextSeq` are the write
+ * side, letting a client mint monotonic seqs from its pending buffer alone —
+ * again with no counter field on the Model.
+ *
+ * `reconcile` (the read side's payoff, #214) composes this ack partition with
+ * the pure fold seam `foldMsgs` (#211) to perform the whole Gambetta/Valve
+ * reconciliation step in one call. The `foldMsgs` import is the ONLY dependency
+ * this leaf takes, and it reaches into the pure-core leaf (`../pure/core`) — NOT
+ * the runtime root — so the module stays runtime-free and the `@demlik/tea/pure`
+ * import-graph guard (ADR 0006, #213) still holds.
+ */
+
+/**
+ * A monotonic, non-negative sequence number tagging one client-predicted
+ * command. Monotonicity is the client's contract (mint successive seqs with
+ * `nextSeq`); this module only ever *compares* seqs.
+ */
+type Seq = number;
+/** A command (or `Msg`) tagged with the `seq` the client assigned it. */
+interface SeqTagged<T> {
+    readonly seq: Seq;
+    readonly value: T;
+}
+/** Tag a command/`Msg` with its sequence number. */
+declare const tagSeq: <T>(seq: Seq, value: T) => SeqTagged<T>;
+/**
+ * The authoritative side's acknowledgement: the highest `seq` it has applied.
+ * Everything with `seq <= lastAppliedSeq` is settled; everything above is still
+ * in flight. This *is* the whole "ack from the authoritative side" — a value
+ * the consumer carries however it likes (a wire field, a message payload),
+ * never a shape this module imposes on the Model.
+ */
+interface Ack {
+    readonly lastAppliedSeq: Seq;
+}
+/** Construct an `Ack` for a last-applied sequence number. */
+declare const ack: (lastAppliedSeq: Seq) => Ack;
+/**
+ * The "nothing applied yet" cursor — the ack value for a server that has applied
+ * no client input at all. Because `nextSeq` mints **0-based** seqs and
+ * `partitionByAck` acks **inclusively** (`seq <= lastAppliedSeq`), the pre-first
+ * cursor must sit strictly *below* seq 0: `lastAppliedSeq = 0` would falsely ack
+ * the seq-0 input before the server ever saw it. `-1` is "before any seq", and
+ * `partitionByAck(buffer, NO_ACK)` therefore leaves the whole buffer PENDING.
+ *
+ * This names the boundary value on the seam so no consumer has to re-discover it
+ * as a magic number: it is the primitive's own design (0-based mint + inclusive
+ * partition) that creates the trap, so it is the primitive's job to name the
+ * escape. Pair with {@link initAck} when an {@link Ack} is wanted instead of the
+ * bare `Seq`.
+ */
+declare const NO_ACK: Seq;
+/**
+ * The `Ack` for a server that has applied nothing yet — `ack(NO_ACK)`. The `Ack`
+ * counterpart to the {@link NO_ACK} `Seq` sentinel, for a consumer that carries
+ * an `Ack` rather than a bare `lastAppliedSeq`.
+ */
+declare const initAck: () => Ack;
+/** The result of splitting a seq-tagged buffer against an ack. */
+interface AckPartition<T> {
+    /** Inputs the authoritative side has applied (`seq <= lastAppliedSeq`). */
+    readonly acked: readonly SeqTagged<T>[];
+    /** Inputs still in flight / un-acked (`seq > lastAppliedSeq`) — the replay tail. */
+    readonly pending: readonly SeqTagged<T>[];
+}
+/**
+ * Partition a buffer of seq-tagged commands into ACKED and PENDING against the
+ * authoritative `lastAppliedSeq`. Pure and total: every item lands in exactly
+ * one bucket, input order is preserved within each bucket, and the boundary
+ * `seq == lastAppliedSeq` is ACKED (inclusive `<=`). Routing is by `seq` value,
+ * not buffer position, so an out-of-order or duplicate-seq buffer partitions
+ * correctly. Accepts either an {@link Ack} or a bare `lastAppliedSeq` number, so
+ * a caller passes whichever it holds.
+ */
+declare const partitionByAck: <T>(buffer: readonly SeqTagged<T>[], ackOrSeq: Ack | Seq) => AckPartition<T>;
+/**
+ * The next sequence number to assign: one past the highest `seq` in the buffer,
+ * or `0` for an empty buffer. Lets a client mint monotonic seqs from its pending
+ * buffer alone — no counter field on the Model — and is tolerant of an unordered
+ * buffer (it takes the max, not the last element).
+ */
+declare const nextSeq: <T>(buffer: readonly SeqTagged<T>[]) => Seq;
+/**
+ * The client prediction/reconciliation helper — the Gambetta/Valve
+ * authoritative-server loop's reconcile step, generalized (#214, epic #186).
+ *
+ * Given the latest `authoritativeState` from the server, the server's
+ * `lastAppliedSeq` ack, and the client's `pending` buffer of seq-tagged inputs,
+ * it returns the corrected predicted state: drop the inputs the server has
+ * already applied (`seq <= lastAppliedSeq`) and replay ONLY the un-acked tail
+ * (`seq > lastAppliedSeq`) over the authoritative snapshot.
+ *
+ * It is **composed, not re-derived** (ADR 0006): the drop is {@link partitionByAck}
+ * (the ack primitive, #212) and the replay is `foldMsgs` (the pure fold seam,
+ * #211) — there is no second copy of the partition logic and no second copy of
+ * the fold. `lastAppliedSeq` accepts either an {@link Ack} or a bare `Seq`, so a
+ * caller passes whichever it holds, matching `partitionByAck`.
+ *
+ * Pure and host-agnostic: it takes the `machine` (which `foldMsgs` needs to
+ * dispatch `update`) but touches no `Store`, `interpret`, or subscription, and
+ * imports nothing from the runtime — so it ships on `@demlik/tea/prediction`
+ * and the client-safe `@demlik/tea/pure` umbrella without dragging `run` into a
+ * client bundle.
+ */
+declare function reconcile<S, M extends {
+    type: string;
+}, C extends Cmd, U extends Sub, Ctx>(machine: Machine<S, M, C, U, Ctx>, authoritativeState: S, lastAppliedSeq: Ack | Seq, pending: readonly SeqTagged<M>[]): S;
+
+export { type Ack, type AckPartition, NO_ACK, type Seq, type SeqTagged, ack, initAck, nextSeq, partitionByAck, reconcile, tagSeq };

package/dist/prediction/index.js

@@ -0,0 +1,4 @@
+export { NO_ACK, ack, initAck, nextSeq, partitionByAck, reconcile, tagSeq } from '../chunk-SQTCS44W.js';
+import '../chunk-QLA76GIT.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/prediction/index.js.map

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

package/dist/protocol-B5YmJr0d.d.ts

@@ -0,0 +1,45 @@
+/**
+ * The closed set of cross-module Msg/Cmd discriminant strings. Declared `as
+ * const` so each entry is usable as both a value (construction / reducer keys /
+ * switch labels) and, via `typeof MsgType.X`, a literal type (`readonly type:`
+ * fields). The single source of truth for issue #60.
+ */
+declare const MsgType: {
+    /** The "run the port for `key`" effect Cmd resilient-call emits. */
+    readonly ResilientRun: "resilient_run";
+    /** PRIVATE success settle Msg (read only by `agentEvents`, #47). */
+    readonly ResilientOk: "resilient_ok";
+    /** Failure settle Msg — routed to the `fail` verb (back off via retry). */
+    readonly ResilientErr: "resilient_err";
+    /** Begin a run. */
+    readonly AgentStart: "agent_start";
+    /** PRIVATE tool-fan-out success settle Msg (read only by `agentEvents`, #47). */
+    readonly AgentToolOk: "agent_tool_ok";
+    /** Tool-fan-out failure settle Msg. */
+    readonly AgentToolErr: "agent_tool_err";
+    /**
+     * Re-fire the one outstanding effect on rehydrate (the do↔agent seam). Fired
+     * by `do/host`'s `autoBoot` via the typed `agentBootMsg` constructor, matched
+     * by the agent reducer — see `AgentBootPort` in `../agent`.
+     */
+    readonly AgentBoot: "agent_boot";
+    /**
+     * The "summarize the oldest N turns" effect Cmd the agent emits when its
+     * `CompactionPolicy` asks to compact before a brain call. A DEDICATED
+     * round-trip (design B1), distinct from the brain call's `resilient_run`, so
+     * compaction is its own honest `Awaiting` state — see `../agent`.
+     */
+    readonly CompactRun: "compact_run";
+    /** Compaction round-trip resolved — carries the summary text the fold-back folds. */
+    readonly CompactOk: "compact_ok";
+    /** Compaction round-trip failed (exhausted retry) — surfaced as data, not a stall. */
+    readonly CompactErr: "compact_err";
+    /** Refresh port resolved — carries the fresh `Token`. */
+    readonly TokenRefreshed: "token_refreshed";
+    /** Refresh port rejected — carries the rejection (errors are data). */
+    readonly TokenRefreshFailed: "token_refresh_failed";
+    /** The 401 the consumer dispatches when a guarded call comes back unauthorized. */
+    readonly Unauthorized: "unauthorized";
+};
+
+export { MsgType as M };

package/dist/pure/index.d.ts

@@ -0,0 +1,2 @@
+export { Ack, AckPartition, NO_ACK, Seq, SeqTagged, ack, initAck, nextSeq, partitionByAck, reconcile, tagSeq } from '../prediction/index.js';
+export { C as Cmd, b as ContextFree, I as Interpret, M as Machine, N as NoCtx, P as Port, c as PortEmitter, R as Reducer, S as Sub, a as SubId, d as Subscribe, e as SyncReturn, T as Transitions, U as UpdateForm, g as detectUpdateForm, h as foldMsgs, i as formOf, s as subId } from '../core-BoB6t7dB.js';

package/dist/pure/index.js

@@ -0,0 +1,4 @@
+export { NO_ACK, ack, initAck, nextSeq, partitionByAck, reconcile, tagSeq } from '../chunk-SQTCS44W.js';
+export { Cmd, detectUpdateForm, foldMsgs, formOf, subId } from '../chunk-QLA76GIT.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/pure/index.js.map

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