@demlik/tea 0.13.0 → 0.15.0

package/dist/reconciler/index.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../../src/reconciler/index.ts"],"names":["w","applied"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @demlik/tea/reconciler — the desired-vs-actual sync loop (the \"fleet-sync /\n * coverage-gap\" shape): walk the ACTUAL world end to end, diff it against the\n * DESIRED spec, then apply each resulting `Change` one at a time until the two\n * agree. The control-plane reconcile pattern (Kubernetes controllers, fleet\n * config rollout, accessibility coverage-gap remediation) lifted to the uniform\n * L2 knob contract.\n *\n * ## The recipe (which bricks it composes)\n *\n *   - **`../paginated-walk`** owns the SCAN. The actual world is rarely a single\n *     fetch — it is a paginated list (every node in a fleet, every page of an\n *     audit, every row of a table). `reconciler` does not re-implement that walk:\n *     it embeds a `paginated-walk` slice and lets it sequence the actual-state\n *     fetch (gated, retried, rate-limited, resumable across eviction). The walk's\n *     own `onPage` hook stays empty (`() => []`) — `reconciler` accumulates each\n *     fetched page's items into the running `actual` snapshot inside its OWN\n *     `pageOk` verb, where it holds its slice and so can extend the accumulator\n *     the walk cannot see; when the walk reports `isComplete`, the full actual\n *     snapshot is in hand.\n *   - **`../cache`** owns the APPLIED ledger. Every `Change` that settles is\n *     written into a TTL cache keyed by the change's id, so a re-`applyNext`\n *     after an eviction skips changes already applied (idempotent re-apply — the\n *     reconcile is safe to resume from any point). The cache is the durable\n *     \"what have I already done?\" memory the apply loop reads before re-issuing.\n *\n * Because the scan IS a `paginated-walk` slice (which itself IS a\n * `resilient-call` slice), this knob **inherits that contract verbatim**: the\n * slice is flat plain data, every verb returns `readonly [State, Cmd[]]`, time\n * is always an `at` parameter, and the jitter RNG is injected once at\n * `createReconciler(config, rng)` — never read inside a verb (the spec:\n * `reconciler` *extends* `paginated-walk`).\n *\n * ## Why the run lifecycle is INLINE (run-tracker not extracted)\n *\n * The reconcile phase union (`idle` / `scanning` / `applying` / `done` /\n * `failed`) and its bookkeeping (`plan`, `appliedCursor`, the `actual`\n * accumulator) live directly on this slice rather than behind a `run-tracker`\n * sub-knob — exactly as `monitored-run` keeps its lifecycle inline. Extraction\n * earns its keep when two independent axes vary; here the lifecycle has one\n * anchoring axis (this reconcile pass). The genuinely independent axes — the\n * paginated SCAN and the applied LEDGER — ARE extracted (`../paginated-walk`,\n * `../cache`). The lifecycle is the glue that sequences scan → plan → apply.\n *\n * ## The two non-negotiables (canon)\n *\n *   - **Durable** — the slice is plain data: the paginated-walk slice, the\n *     accumulated `actual` items, the planned `Change[]`, the applied cursor, and\n *     the applied-ledger cache (all JSON-serializable). A reconcile survives DO\n *     eviction mid-scan or mid-apply and resumes from the exact position.\n *   - **Replayable** — every transition is a verb returning new state + Cmds.\n *     `diff` / `apply` are pure config functions applied at the verb boundary;\n *     the Cmds they yield are plain data. `replay` reconstructs the whole pass\n *     exactly. Nothing here closes over time or RNG.\n *\n * ## Where the clock / RNG live\n *\n * Inside the verbs: nowhere. `at` arrives on `scan` / `pageOk` / `pageErr` /\n * `applied` / `onTimer` and threads into the underlying paginated-walk gate (so a\n * retried / rate-limited page measures backoff from that `at`) and into the\n * applied-ledger cache writes. The jitter RNG is injected at construction. The\n * only clock read is `Date.now()` inside the inherited paginated-walk `handlers`\n * port (the effect boundary).\n *\n * ## Typical wiring\n *\n *   const rec = createReconciler<FleetNode, NodeSpec, Page, SyncChange, ApplyCmd>({\n *     desired: targetSpecs,                          // the spec to converge on\n *     firstPage: null,                               // actual-list page-one sentinel\n *     nextCursor: (page) => page.next ?? null,\n *     itemsOf: (page) => page.nodes,                 // page → actual items\n *     diff: (desired, actual) => planChanges(desired, actual),\n *     apply: (change) => ({ type: \"apply_change\", change }),\n *     idOf: (change) => change.nodeId,               // applied-ledger key\n *     rateLimit: { capacity: 10, refillPerSec: 5 },\n *     retry: defaultRetryPolicy,\n *   });\n *\n *   // in the machine:\n *   init: () => [{ rec: rec.init() }, []],\n *   update: {\n *     reconcile:   (s, m) => lift(s, rec.scan(s.rec, m.at)),\n *     page_ok:     (s, m) => lift(s, rec.pageOk(s.rec, m.result, m.at)),\n *     page_err:    (s, m) => lift(s, rec.pageErr(s.rec, m.error, m.at)),\n *     change_done: (s, m) => lift(s, rec.applied(s.rec, m.change, m.at)),\n *     retry_due:   (s, m) => lift(s, rec.onTimer(s.rec, m)),\n *   },\n *   subscriptions: (s) => rec.subs(s.rec),\n *   subscribe: { deadline: subscribeDeadline },\n *   interpret: rec.handlers({ run: (cursor) => api.listActual(cursor) }),\n */\n\nimport {\n  get as cacheGet,\n  set as cacheSet,\n  initCache,\n  type TtlCache,\n} from \"../cache\";\nimport type { Cmd } from \"../index\";\nimport {\n  createPaginatedWalk,\n  type DeadlineSub,\n  deadlineSub,\n  type FetchPageCmd,\n  PAGE_KEY,\n  type PageErrMsg,\n  type PageOkMsg,\n  type PaginatedWalkState,\n  type PaginatedWalkTimerMsg,\n  subscribeDeadline,\n} from \"../paginated-walk\";\nimport type {\n  CircuitConfig,\n  DeadlineConfig,\n  RateLimitConfig,\n  ResilientPorts,\n} from \"../resilient-call\";\nimport type { RetryPolicy } from \"../retry-backoff\";\n\n// ===========================================================================\n// Config — the knob. `desired` / `diff` / `apply` / `idOf` describe the\n// reconcile; the SCAN knobs (firstPage / nextCursor / itemsOf) describe how the\n// actual world is walked; the resilience bricks are inherited from\n// paginated-walk (every one optional — omit a brick, omit its gate).\n// ===========================================================================\n\n/**\n * The reconciler knob. Generic in:\n *   - `Actual`  — one item of the ACTUAL world (a fleet node, an audited page, a\n *                 table row). The scan accumulates these.\n *   - `Desired` — the DESIRED spec value the diff converges toward. Opaque to\n *                 this module; only `diff` reads it.\n *   - `Page`    — the shape one actual-list page fetch resolves with.\n *   - `Change`  — one unit of remediation the diff produces and `apply` realizes.\n *   - `ApplyCmd`— the Cmd `apply(change)` yields (the effect that mutates the\n *                 actual world toward desired).\n *\n * `diff` / `apply` / `idOf` / `nextCursor` / `itemsOf` are PURE config functions\n * applied at the verb boundary, never stored in the slice or in a Cmd (Cmds are\n * plain data, not closures). The resilience bricks (`retry` / `circuit` /\n * `rateLimit` / `deadline`) are the SAME optional knobs `paginated-walk` /\n * `resilient-call` expose — reconciler extends them; `rateLimit` keeps the scan\n * from 429-ing the upstream listing API.\n */\nexport interface ReconcilerConfig<\n  Actual,\n  Desired,\n  Page,\n  Change,\n  ApplyCmd extends Cmd,\n  Cursor = number,\n> {\n  /**\n   * The DESIRED spec to converge on. Held verbatim and handed to `diff` once the\n   * scan completes. Any JSON-serializable value — a list of specs, a target map,\n   * a single target object — `diff` alone interprets it.\n   */\n  readonly desired: Desired;\n  /**\n   * Compute the remediation plan: the ordered `Change[]` that moves `actual` to\n   * `desired`. Called once when the scan finishes (the full actual snapshot is in\n   * hand). An empty plan means \"already in sync — nothing to apply\". PURE +\n   * consumer-specific (only the consumer knows the domain's reconcile rules).\n   */\n  readonly diff: (\n    desired: Desired,\n    actual: readonly Actual[],\n  ) => readonly Change[];\n  /**\n   * Realize one `Change` as the Cmd that mutates the actual world. Returns plain\n   * data (a `{ type, ... }` Cmd the consumer's interpret handler performs).\n   * PURE — the side effect happens when the runtime performs the emitted Cmd,\n   * never here.\n   */\n  readonly apply: (change: Change) => ApplyCmd;\n  /**\n   * Stable identity for a `Change` — the applied-ledger cache key. A re-`applyNext`\n   * after eviction (or after a re-plan) skips a change whose id is already in the\n   * ledger (idempotent re-apply). MUST be a property of the change itself, NOT its\n   * position in the plan: the ledger has to survive re-planning. When omitted the\n   * default keys by the change's serialized CONTENT (`JSON.stringify(change)`) —\n   * a stable per-change identity that is unchanged by where the change sits in the\n   * plan. Supply a domain id (the target node id, the resource key) when one\n   * exists; it is cheaper than serializing and dedupes two changes that differ\n   * only in fields irrelevant to identity. PURE.\n   *\n   * Why NOT positional: keying by index silently drops changes on the documented\n   * re-plan path. After applying the index-0 change, its `\"0\"` ledger entry would\n   * match WHATEVER different, never-applied change lands at index 0 in the next\n   * plan — the apply loop skips it as \"already done\". Identity must be intrinsic\n   * to the change so the ledger means \"this change settled\", not \"slot N settled\".\n   */\n  readonly idOf?: (change: Change) => string;\n\n  // --- scan knobs (the actual-world walk), inherited from paginated-walk ---\n  /**\n   * The cursor the actual-list scan fetches first. For an offset API typically\n   * `0`; for a token API whatever sentinel the API treats as page one.\n   */\n  readonly firstPage: Cursor;\n  /**\n   * Extract the next scan cursor from a fetched page — a `Cursor` to keep\n   * scanning, or `null` when the actual listing is exhausted (scan finishes,\n   * plan computed). PURE + consumer-specific.\n   */\n  readonly nextCursor: (page: Page) => Cursor | null;\n  /**\n   * Extract the actual items from one fetched page. Each page's items are\n   * appended to the running `actual` accumulator. PURE.\n   */\n  readonly itemsOf: (page: Page) => readonly Actual[];\n\n  // --- resilience bricks, inherited from paginated-walk (all optional) ---\n  /** Exponential-backoff retry policy for a transient scan-page failure. */\n  readonly retry?: RetryPolicy;\n  /** Circuit breaker around the scan fetch (one upstream → one breaker). */\n  readonly circuit?: CircuitConfig;\n  /** Token-bucket rate limit on the scan — the \"don't 429 the listing API\" knob. */\n  readonly rateLimit?: RateLimitConfig;\n  /** Overall wall-clock deadline per individual scan-page fetch. */\n  readonly deadline?: DeadlineConfig;\n}\n\n// ===========================================================================\n// Slice — the Model field this knob owns. The paginated-walk scan slice + the\n// accumulated actual snapshot + the inline reconcile lifecycle (plan, applied\n// cursor, ledger). All flat plain data.\n// ===========================================================================\n\n/**\n * Reconcile lifecycle phase. Discriminated on `phase`:\n *\n *   - `idle`     — created, never scanned. `scan` starts the actual-world walk.\n *   - `scanning` — the paginated-walk is traversing the actual listing; pages\n *                  fold into `actual` as they arrive. The scan owns the `walk`\n *                  sub-slice; this phase ends when the walk finishes.\n *   - `applying` — the scan finished, `diff` produced the `plan`, and changes are\n *                  being applied one at a time. `appliedCursor` is the index of\n *                  the next change to apply.\n *   - `done`     — every planned change applied (or an empty plan: already in\n *                  sync). Terminal.\n *   - `failed`   — the scan failed terminally (the page-fetch retries were\n *                  exhausted / a deadline fired). `error` carries why. Terminal.\n */\nexport type ReconcilePhase =\n  | \"idle\"\n  | \"scanning\"\n  | \"applying\"\n  | \"done\"\n  | \"failed\";\n\n/**\n * The slice. Plain data end to end:\n *   - `phase`         — the lifecycle discriminant.\n *   - `walk`          — the `../paginated-walk` scan slice (cursor + resilience).\n *                       Drives the actual-world traversal; POSITION survives\n *                       eviction.\n *   - `actual`        — the accumulated actual items, appended page by page during\n *                       the scan. The full snapshot `diff` is computed against.\n *   - `plan`          — the `Change[]` `diff` produced. Empty until the scan\n *                       finishes; the apply loop walks it by `appliedCursor`.\n *   - `appliedCursor` — index of the NEXT change to apply (0 ≤ cursor ≤ plan.length).\n *                       `cursor === plan.length` means every change applied.\n *   - `applied`       — the applied-ledger cache: `idOf(change) → change`, written\n *                       as each change settles. The idempotency memory the apply\n *                       loop reads to skip already-applied changes after eviction.\n */\nexport interface ReconcilerState<Actual, Change, Page, Cursor = number> {\n  readonly phase: ReconcilePhase;\n  readonly walk: PaginatedWalkState<Cursor, Page>;\n  readonly actual: readonly Actual[];\n  readonly plan: readonly Change[];\n  readonly appliedCursor: number;\n  readonly applied: TtlCache<Change>;\n}\n\n// ===========================================================================\n// Cmds + Msgs the knob speaks. The scan emits the inherited page-fetch effect;\n// the apply loop emits the consumer's `apply(change)` Cmds.\n// ===========================================================================\n\n/**\n * The actual-list page-fetch effect: the inherited `resilient_run` Cmd from\n * paginated-walk, whose `input` is the `Cursor` to fetch and whose `key` is the\n * fixed `PAGE_KEY`. The consumer's `handlers(ports)` interprets it.\n */\nexport type ScanPageCmd<Cursor> = FetchPageCmd<Cursor>;\n\n/** Page-settled Msgs the scan `handlers` port dispatches back (inherited verbatim). */\nexport type ScanPageOkMsg<Page> = PageOkMsg<Page>;\nexport type ScanPageErrMsg = PageErrMsg;\n\n/** The scan retry / deadline timer Msg — inherited from paginated-walk. */\nexport type ReconcilerTimerMsg = PaginatedWalkTimerMsg;\n\n/**\n * Ports the consumer supplies to `handlers`. `run(cursor)` fetches ONE page of\n * the ACTUAL listing for the given cursor; throwing routes to `pageErr` (and\n * thus the scan backoff). Same shape as paginated-walk's port.\n */\nexport interface ReconcilerPorts<Cursor, Page>\n  extends ResilientPorts<Cursor, Page> {}\n\n// ===========================================================================\n// The knob factory.\n// ===========================================================================\n\n/**\n * Build a reconciler knob from `config`. `rng` is injected for the underlying\n * scan-retry jitter — pass a fixed `() => 0` in tests to pin backoff; defaults\n * to `Math.random` (read at the verb boundary inside resilient-call, never in a\n * reconciler verb). Inherited straight from paginated-walk.\n *\n * Returns the uniform L2 knob contract: `init()`, the verbs `scan` / `pageOk` /\n * `pageErr` / `planned` / `applyNext` / `applied` / `onTimer`, the derived\n * `isComplete`, `subs(state)`, and `handlers(ports)`.\n */\nexport function createReconciler<\n  Actual,\n  Desired,\n  Page,\n  Change,\n  ApplyCmd extends Cmd = Cmd,\n  Cursor = number,\n>(\n  config: ReconcilerConfig<Actual, Desired, Page, Change, ApplyCmd, Cursor>,\n  rng: () => number = Math.random,\n) {\n  type State = ReconcilerState<Actual, Change, Page, Cursor>;\n  // The combined Cmd type the verbs can emit: the inherited scan page-fetch\n  // effect plus whatever `apply(change)` yields.\n  type OutCmd = ScanPageCmd<Cursor> | ApplyCmd;\n\n  // The scan is a paginated-walk over the actual listing. We feed it the scan\n  // cursor knobs + the resilience bricks; `onPage` is OURS — it is a pure marker\n  // (we accumulate items in `pageOk` instead, where we hold the reconciler\n  // slice). The walk's `Page` payload is the consumer's `Page`; the reconciler\n  // slice stores the walk as `PaginatedWalkState<Cursor, unknown>` so its own\n  // type does not have to thread `Page` (the page never lands in the slice — only\n  // the extracted `actual` items do).\n  const walk = createPaginatedWalk<Cursor, Page, never>(\n    {\n      firstPage: config.firstPage,\n      nextCursor: config.nextCursor,\n      // The walk's per-page hook emits no Cmds — the reconciler accumulates the\n      // page's items itself in `pageOk` (where it holds its own slice), so the\n      // walk's onPage stays empty.\n      onPage: () => [],\n      retry: config.retry,\n      circuit: config.circuit,\n      rateLimit: config.rateLimit,\n      deadline: config.deadline,\n    },\n    rng,\n  );\n\n  /**\n   * The applied-ledger key for a change. Custom `idOf` when supplied; otherwise\n   * the change's serialized CONTENT — a stable per-change identity. NEVER the\n   * positional index: an index-keyed ledger drops a never-applied change that\n   * happens to land at a slot a different, already-applied change once occupied\n   * (the re-plan defect). Identity is intrinsic to the change, so the ledger\n   * means \"this change settled\", surviving a re-plan that reorders the slots.\n   */\n  function changeId(change: Change): string {\n    return config.idOf ? config.idOf(change) : JSON.stringify(change);\n  }\n\n  /** Replace the walk sub-slice, leaving the rest of the reconciler untouched. */\n  function withWalk(s: State, w: State[\"walk\"]): State {\n    return { ...s, walk: w };\n  }\n\n  /** The starting slice: idle, fresh walk + empty accumulator / plan / ledger. */\n  function init(): State {\n    return {\n      phase: \"idle\",\n      walk: walk.init(),\n      actual: [],\n      plan: [],\n      appliedCursor: 0,\n      applied: initCache<Change>(),\n    };\n  }\n\n  // === Verb: scan ==========================================================\n\n  /**\n   * Begin the reconcile: start the paginated walk over the ACTUAL world and\n   * enter `scanning`. Issues the first scan-page fetch (gated through the\n   * inherited resilience). A no-op on any non-`idle` phase — re-scanning a\n   * reconcile already in flight would restart the actual walk and double-count,\n   * so a stray `scan` is absorbed. PURE — `at` threads into the fetch gate.\n   */\n  function scan(s: State, at: number): readonly [State, readonly OutCmd[]] {\n    if (s.phase !== \"idle\") return [s, []];\n    const [w, cmds] = walk.start(s.walk, at);\n    const next: State = { ...s, phase: \"scanning\", walk: w };\n    return [next, cmds];\n  }\n\n  // === Verb: pageOk ========================================================\n\n  /**\n   * Record a successfully fetched actual-list `page`: append its items to the\n   * `actual` accumulator and advance the walk. When the walk finishes (the\n   * listing is exhausted), the full actual snapshot is in hand → compute the\n   * plan (`planned`) and start applying. PURE — `at` is the scan clock.\n   *\n   * A stray `pageOk` while not `scanning` (a late duplicate after the scan\n   * completed) is absorbed by the walk (no cursor advance) and contributes no\n   * items — the reconcile never re-accumulates after the plan is computed.\n   */\n  function pageOk(\n    s: State,\n    page: Page,\n    at: number,\n  ): readonly [State, readonly OutCmd[]] {\n    // Once we are past scanning, the actual snapshot is frozen — absorb stray pages.\n    if (s.phase !== \"scanning\") {\n      const [w] = walk.pageOk(s.walk, page, at);\n      return [withWalk(s, w), []];\n    }\n\n    const [w, walkCmds] = walk.pageOk(s.walk, page, at);\n    const actual = [...s.actual, ...config.itemsOf(page)];\n    const scanned: State = { ...s, walk: w, actual };\n\n    // The walk emits the next scan-page fetch while it stays fetching. When it\n    // finishes (done / paused with no fetch), `walkCmds` is empty.\n    const cmds: readonly OutCmd[] = walkCmds;\n\n    // Scan exhausted → plan + begin applying. `walk.isComplete` is the honest\n    // \"the API returned a null next cursor\" signal.\n    if (walk.isComplete(scanned.walk)) {\n      const [plannedState, applyCmds] = planned(scanned, at);\n      return [plannedState, [...cmds, ...applyCmds]];\n    }\n\n    return [scanned, cmds];\n  }\n\n  // === Verb: pageErr =======================================================\n\n  /**\n   * Record a failed scan-page fetch and back off via the inherited resilience:\n   * schedule a retry (the scan cursor stays parked — no advance) or, once the\n   * page-fetch retries are exhausted, the underlying call settles `failed`. When\n   * the scan call is terminally failed, the whole reconcile enters `failed`.\n   * PURE — `at` stamps the breaker trip + the retry-delay base.\n   */\n  function pageErr(\n    s: State,\n    error: unknown,\n    at: number,\n  ): readonly [State, readonly OutCmd[]] {\n    const [w, cmds] = walk.pageErr(s.walk, error, at);\n    let next = withWalk(s, w);\n    // The page-fetch call settling `failed` (retries exhausted) is a terminal\n    // scan failure → the reconcile cannot trust an incomplete actual snapshot.\n    if (\n      s.phase === \"scanning\" &&\n      w.resilience.calls[PAGE_KEY]?.phase === \"failed\"\n    ) {\n      next = { ...next, phase: \"failed\" };\n    }\n    return [next, cmds];\n  }\n\n  // === Verb: planned =======================================================\n\n  /**\n   * Compute the remediation plan from the accumulated `actual` snapshot and the\n   * configured `desired`, store it, and enter `applying`. Normally driven\n   * internally by `pageOk` when the scan finishes, but exposed as a\n   * verb so a consumer can force planning from an externally-supplied actual\n   * snapshot (e.g. a single-shot actual fetch outside the paginated scan), or\n   * re-plan after a desired change. An empty plan settles straight to `done`\n   * (already in sync). PURE — `at` only stamps the (empty) apply-loop clock.\n   *\n   * `changes` is optional: omit it to diff the slice's own accumulated `actual`\n   * against `config.desired`; pass an explicit plan to install it directly\n   * (skipping the diff — the consumer computed it elsewhere).\n   */\n  function planned(\n    s: State,\n    at: number,\n    changes?: readonly Change[],\n  ): readonly [State, readonly OutCmd[]] {\n    const plan = changes ?? config.diff(config.desired, s.actual);\n    const planning: State = {\n      ...s,\n      phase: \"applying\",\n      plan,\n      appliedCursor: 0,\n    };\n    return applyNext(planning, at);\n  }\n\n  // === Verb: applyNext =====================================================\n\n  /**\n   * Emit the apply Cmd for the next not-yet-applied change in the plan, skipping\n   * any whose id is already in the applied ledger (idempotent re-apply after\n   * eviction). Advances `appliedCursor` past skipped + the emitted change. When\n   * the cursor reaches the end of the plan, settles `done`. A no-op unless\n   * `applying`. PURE — `at` is read only for the ledger lookup clock; `idOf`\n   * keys the skip check.\n   *\n   * Emits at most ONE apply Cmd per call (the loop is sequential: each `applied`\n   * drives the next `applyNext`). This keeps the actual-world mutation\n   * one-at-a-time, matching a controller's serial reconcile.\n   */\n  function applyNext(\n    s: State,\n    at: number,\n  ): readonly [State, readonly OutCmd[]] {\n    if (s.phase !== \"applying\") return [s, []];\n\n    let cursor = s.appliedCursor;\n    // Skip changes already in the ledger (a resumed reconcile re-issues from the\n    // cursor but must not re-apply what already settled).\n    while (cursor < s.plan.length) {\n      const change = s.plan[cursor];\n      // `cursor < plan.length` guarantees an element under normal indexing; the\n      // explicit `undefined` narrow (vs a non-null assertion) keeps the access\n      // typed without a suppression and tolerates a sparse hole by skipping it.\n      if (change === undefined) {\n        cursor++;\n        continue;\n      }\n      const id = changeId(change);\n      if (cacheGet(s.applied, id, at) === undefined) {\n        // This change is not yet applied — emit its Cmd and park the cursor here\n        // (it advances to cursor+1 only once `applied` confirms the change).\n        const advanced: State = { ...s, appliedCursor: cursor };\n        return [advanced, [config.apply(change)]];\n      }\n      cursor++;\n    }\n\n    // Every change applied → reconcile complete.\n    const done: State = { ...s, phase: \"done\", appliedCursor: cursor };\n    return [done, []];\n  }\n\n  // === Verb: applied =======================================================\n\n  /**\n   * Record that `change` finished applying: write it into the applied ledger,\n   * advance the cursor past it, and drive the next `applyNext`. PURE — `at` is\n   * the ledger-write clock (the entry never expires in practice; a large TTL\n   * keeps the idempotency window open for the reconcile's lifetime).\n   *\n   * `change` is the SAME change the consumer's apply handler settled (echoed back\n   * on the settle Msg) — its id is computed from the change's own identity (NOT a\n   * cursor position), so the ledger key matches the skip check in `applyNext`\n   * regardless of where the change sits in the plan. A no-op unless `applying` (a\n   * late settle after `done` is ignored). PURE.\n   */\n  function applied(\n    s: State,\n    change: Change,\n    at: number,\n  ): readonly [State, readonly OutCmd[]] {\n    if (s.phase !== \"applying\") return [s, []];\n    const id = changeId(change);\n    // A very large TTL: the ledger entry must outlive the whole reconcile pass.\n    // `get(..., at)` treats it as fresh for `at < expiresAtMs`, which holds for\n    // any realistic reconcile (the cache exists to dedupe within one pass).\n    const applied = cacheSet(\n      s.applied,\n      id,\n      change,\n      at,\n      Number.MAX_SAFE_INTEGER,\n    );\n    const advanced: State = {\n      ...s,\n      applied,\n      appliedCursor: s.appliedCursor + 1,\n    };\n    return applyNext(advanced, at);\n  }\n\n  // === Verb: onTimer =======================================================\n\n  /**\n   * A scan retry / deadline timer fired. Defers to paginated-walk's `onTimer`: a\n   * retry timer re-issues the SAME scan-page fetch (re-fetching the parked\n   * cursor); a deadline timer settles the scan call failed. A deadline-driven\n   * terminal scan failure escalates the whole reconcile to `failed`. A stale fire\n   * is a pure no-op (inherited identity). PURE.\n   */\n  function onTimer(\n    s: State,\n    msg: ReconcilerTimerMsg,\n  ): readonly [State, readonly OutCmd[]] {\n    const [w, cmds] = walk.onTimer(s.walk, msg);\n    if (w === s.walk) {\n      // Inherited no-op identity → keep our slice identity too.\n      return [s, []];\n    }\n    let next = withWalk(s, w);\n    if (\n      s.phase === \"scanning\" &&\n      w.resilience.calls[PAGE_KEY]?.phase === \"failed\"\n    ) {\n      next = { ...next, phase: \"failed\" };\n    }\n    return [next, cmds];\n  }\n\n  // === Derived predicate ===================================================\n\n  /**\n   * Whether the reconcile has fully settled — every planned change applied (or an\n   * empty plan: already in sync). PURE, read-only. Lets a consumer's reducer fire\n   * a \"reconcile complete\" Cmd without re-checking the phase by hand.\n   */\n  function isComplete(s: State): boolean {\n    return s.phase === \"done\";\n  }\n\n  // === Subs ================================================================\n\n  /**\n   * Pre-wired subscriptions: exactly the scan's paginated-walk subs — a retry\n   * timer while a scan page is `waiting_retry`, and (with the `deadline` brick) a\n   * per-page deadline timer while a scan fetch is active. The apply loop emits no\n   * timers (each apply settles via the consumer's own Msg), so once the scan\n   * finishes the desired sub set empties. Reconciled by id; wire `subscribe: {\n   * deadline: subscribeDeadline }` (re-exported below).\n   */\n  function subs(s: State): readonly DeadlineSub[] {\n    return walk.subs(s.walk);\n  }\n\n  // === Handlers ============================================================\n\n  /**\n   * Pre-wired interpret handler for the scan page-fetch effect. Inherited from\n   * paginated-walk (`resilient_run`): wraps the consumer's `run(cursor)` actual-\n   * list port via `tryInterpret` (Railway) — success → `resilient_ok` (handled by\n   * `pageOk`), failure → `resilient_err` (handled by `pageErr`), each stamped\n   * with `Date.now()` at the effect boundary (the ONE permitted clock read).\n   *\n   *   interpret: rec.handlers({ run: (cursor) => api.listActual(cursor) })\n   *\n   * The apply-Cmd side is the CONSUMER's interpret handler (it knows how to\n   * realize `apply(change)`); the consumer routes its settle Msg back through\n   * `applied`. This knob only owns the scan's interpret cell.\n   */\n  function handlers(ports: ReconcilerPorts<Cursor, Page>) {\n    return walk.handlers(ports);\n  }\n\n  return {\n    init,\n    scan,\n    pageOk,\n    pageErr,\n    planned,\n    applyNext,\n    applied,\n    onTimer,\n    isComplete,\n    subs,\n    handlers,\n  };\n}\n\n/**\n * Lift a knob result `[slice, cmds]` into a host `[State, cmds]` where the slice\n * lives at `state.rec`. Convenience for the common single-slice host; hosts with\n * a differently-named field spread by hand. PURE — a thin record rebuild, no\n * clock / RNG.\n */\nexport function liftReconciler<\n  S extends { rec: ReconcilerState<Actual, Change, Page, Cursor> },\n  Actual,\n  Change,\n  Page,\n  Cursor,\n  C extends Cmd,\n>(\n  state: S,\n  [slice, cmds]: readonly [\n    ReconcilerState<Actual, Change, Page, Cursor>,\n    readonly C[],\n  ],\n): readonly [S, readonly C[]] {\n  return [{ ...state, rec: slice }, cmds];\n}\n\n/**\n * Re-export the deadline Sub primitives (inherited from paginated-walk) so\n * consumers wire one import: `subscribeDeadline` is the `subscribe` cell,\n * `deadlineSub` builds the Sub literal this knob's `subs` emits.\n */\nexport { subscribeDeadline, deadlineSub };\nexport type { DeadlineSub };\n"]}

package/dist/recorder/index.js

@@ -1,3 +0,0 @@
-export { breadcrumbsFromTrace, parseJSONL, recorder, traceAttachment } from '../chunk-MUUROGIH.js';
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

package/dist/recorder/index.js.map

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

package/dist/reducer-4GNR6b8B.d.ts

@@ -1,447 +0,0 @@
-import { k as EventOrigin, C as Chart, R as ReducerChart } from './graph-B3L5e0N1.js';
-import { R as RtSamples } from './samples-B3My5oh2.js';
-
-/**
- * WHY a (state, event) pair is refused. The chart's three refusal mechanisms,
- * each carrying the evidence that produced it, so a UI can say *"`WIP` is not
- * addressed to `blocked` — its scope is `edges`"* rather than "disabled".
- *
- * `undeclared` is the fourth case the type layer forbids: a pair that is live,
- * unhandled and unrefused. It cannot occur on a chart that compiled through
- * `defineChart`, and it is reported rather than swallowed because reaching it
- * means the types were bypassed with a cast — which is precisely when a
- * debugger should say so instead of drawing a well-behaved button.
- */
-type RefusalReason = {
-    readonly kind: "end";
-    /** Terminal state: it accepts nothing, by declaration. */
-    readonly state: string;
-} | {
-    readonly kind: "out-of-scope";
-    /** The event's declared `scope`, flattened to its members. */
-    readonly scope: readonly string[];
-    /** The phase this state lives in — the one that is not in `scope`. */
-    readonly phase: string;
-} | {
-    /**
-     * `scope: "edges"` — the event is live exactly where an edge declares it,
-     * and this state declares none.
-     *
-     * SPLIT OUT OF `out-of-scope` because the phase has nothing to do with it.
-     * `"edges"` is not a phase name, so the phase test could never pass and
-     * the refusal came back naming a phase the reader then went looking for:
-     * *"`DONE` is not addressed to phase `working` (scope: edges)"* — three
-     * pieces of vocabulary for one fact, and the fact is not in there. The
-     * default scope is `edges`, so this was most refusals on most charts.
-     */
-    readonly kind: "no-edge";
-    readonly state: string;
-} | {
-    readonly kind: "ignored";
-    /** The event is live here and this state refuses it BY NAME. */
-    readonly state: string;
-} | {
-    readonly kind: "undeclared";
-};
-/** A one-line, human-readable rendering of a {@link RefusalReason}. */
-declare function explainRefusal(event: string, reason: RefusalReason): string;
-/** What kind of transition an edge declares. */
-type EdgeKind = "plain" | "guarded" | "cell" | "resume";
-/** One declared edge — a `(state, event)` pair the chart routes. */
-interface ChartEdge {
-    readonly from: string;
-    readonly event: string;
-    /** `"${from}.${event}"` — the site key guards/cmds/cells are indexed by. */
-    readonly at: string;
-    readonly kind: EdgeKind;
-    /**
-     * Every state this edge can land on, in declaration order. A guarded edge
-     * contributes both arms; a cell edge contributes its whole declared `to`.
-     * For a resume edge this is the fallback alone — the real target is
-     * `state.was`, which is a property of the LIVE state, not of the chart.
-     */
-    readonly targets: readonly string[];
-    /** The guard's name, on a guarded edge. */
-    readonly guard?: string;
-    /** The target taken when the guard HOLDS. */
-    readonly then?: string;
-    /** The target taken when the guard FAILS. */
-    readonly otherwise?: string;
-    /** The cell's name, on a `{ to, cell }` edge. */
-    readonly cell?: string;
-    /** The declared fallback, on a `resume` edge. */
-    readonly fallback?: string;
-    /** Cmds fired when the edge fires (the guard's `then` arm, if guarded). */
-    readonly cmds: readonly string[];
-    /** Cmds fired when the guard FAILS. Empty unless the edge is guarded. */
-    readonly otherwiseCmds: readonly string[];
-}
-/** A (state, event) pair the chart explicitly refuses, and why. */
-interface ChartRefusal {
-    readonly from: string;
-    readonly event: string;
-    readonly reason: RefusalReason;
-}
-/** One state, with the facts the chart declares about it. */
-interface ChartStateInfo {
-    readonly name: string;
-    /** The phase it was declared under. */
-    readonly phase: string;
-    /** `initial: true` — the entry state. Exactly one per machine-bearing chart. */
-    readonly initial: boolean;
-    /**
-     * Terminal by DECLARATION, not by "has no outgoing edges" — `true` for both
-     * polarities, because both accept nothing and both owe nothing.
-     */
-    readonly end: boolean;
-    /**
-     * WHICH ending. `true` a success final, `"error"` the failure terminal,
-     * `false` not a final at all.
-     *
-     * `end` answers "does this accept anything"; this answers "did the machine
-     * win or lose". A lane needs both and they are not the same question —
-     * `shipped` and `frozen` are equally terminal and are not the same outcome.
-     */
-    readonly endPolarity: false | true | "error";
-    /** Carries a `resume` edge out of it, so the compiler injects `was` here. */
-    readonly parking: boolean;
-}
-/** One event of the alphabet. */
-interface ChartEventInfo {
-    readonly name: string;
-    /** The declared `scope`, flattened: `"edges"`, `"all"`, or phase names. */
-    readonly scope: readonly string[];
-    /** `foreign: true` — the name belongs to someone else and stays bare. */
-    readonly foreign: boolean;
-    /**
-     * WHERE THIS EVENT COMES FROM — `from`, read back off the chart.
-     *
-     * `undefined` means the chart does not say, which is a fact of its own and
-     * never a default: a UI that groups its button row by sender must render the
-     * undeclared ones as undeclared rather than filing them under a guess.
-     */
-    readonly from?: EventOrigin;
-    /**
-     * Whether the event DECLARED a payload (`data: ty<…>()`).
-     *
-     * `ty<T>()` is `{}` at runtime, so `T` is unreadable — but the `data` KEY is
-     * right there in the literal, so "does this event carry a payload at all" IS
-     * a runtime fact. It is what decides whether a sample is required.
-     */
-    readonly hasPayload: boolean;
-}
-/**
- * A whole chart, as data a UI can build itself from. Nothing here is supplied
- * by the caller; every field is read off the one chart value.
- */
-interface ChartDescription {
-    /** The phases, in declaration order, each with its member states. */
-    readonly phases: readonly {
-        readonly name: string;
-        readonly states: readonly string[];
-    }[];
-    readonly states: readonly ChartStateInfo[];
-    /** The state marked `initial: true`, or `undefined` on a chart with none. */
-    readonly initial: string | undefined;
-    readonly events: readonly ChartEventInfo[];
-    /** Every cmd DECLARED in the `cmds` section — the effect alphabet. */
-    readonly cmds: readonly string[];
-    /** Every guard name any edge references. */
-    readonly guards: readonly string[];
-    /** Every cell name any `{ to, cell }` edge references. */
-    readonly cells: readonly string[];
-    readonly edges: readonly ChartEdge[];
-    readonly refusals: readonly ChartRefusal[];
-}
-/**
- * A read edge MINUS the state it leaves — everything about an edge that is a
- * fact of the edge itself rather than of the grid it sits in.
- *
- * The reducer form has no state dimension (`src/chart/inspect/reducer.ts`), so
- * its edges are exactly this: same kinds, same targets, same guard/cell/cmd
- * fields, with `from` unrepresentable rather than blank.
- */
-type EdgeCore = Omit<ChartEdge, "from">;
-/**
- * Read a chart into its {@link ChartDescription}.
- *
- * Pure, total, and allocation-only — it never executes a guard, a cell or a
- * payload builder, so it is safe on a chart whose parts do not exist yet.
- */
-declare function describeChart<const C extends Chart<C>>(chart: C): ChartDescription;
-/** The declared edge out of `state` on `event`, or `undefined`. */
-declare function edgeAt(desc: ChartDescription, state: string, event: string): ChartEdge | undefined;
-/** Why `state` refuses `event`, or `undefined` when it does not. */
-declare function refusalAtState(desc: ChartDescription, state: string, event: string): RefusalReason | undefined;
-/** The record for `state`, or `undefined` when the chart has no such state. */
-declare function stateInfo(desc: ChartDescription, state: string): ChartStateInfo | undefined;
-
-/** Any guard, however narrowly its use sites typed it. */
-type AnyGuard = (...args: never[]) => boolean;
-/** Any cell, in either the single-body or the per-site form. */
-type AnyCell = ((...args: never[]) => readonly [{
-    readonly type: string;
-}, unknown]) | Readonly<Record<string, unknown>>;
-/**
- * The code parts a preview may consult — the SAME bag `compile` receives, so
- * an author passes the one they already built rather than a second copy.
- * Every field is optional: the preview degrades where a part is absent.
- */
-interface InspectParts {
-    readonly guards?: Readonly<Record<string, AnyGuard | undefined>>;
-    readonly cells?: Readonly<Record<string, AnyCell | undefined>>;
-}
-/** Everything a live preview may consult, beyond the state itself. */
-interface InspectOptions {
-    /** The parts bag `compile` was given. Guards/cells are read from it. */
-    readonly parts?: InspectParts;
-    /** Sample payload per event — see `./samples`. */
-    readonly samples?: RtSamples;
-}
-/** Why a guard could not be evaluated. Each is a fact, not a guess. */
-type GuardUnknown = "no-guard-bag" | "no-implementation" | "no-sample" | "threw";
-/**
- * Which branch a guarded edge would take right now.
- *
- * `then` / `else` are ANSWERS — the guard ran, on this state, with this msg.
- * `unknown` is the honest non-answer, carrying the reason and (for a throwing
- * guard) the message, so a UI shows "cannot evaluate: no sample for FAIL"
- * rather than a confidently wrong arrow.
- */
-type GuardPreview = {
-    readonly guard: string;
-    readonly branch: "then" | "else";
-    /** The state that branch lands on. */
-    readonly target: string;
-    /** The cmds that branch fires. */
-    readonly cmds: readonly string[];
-} | {
-    readonly guard: string;
-    readonly branch: "unknown";
-    readonly why: GuardUnknown;
-    /** The thrown error's message, when `why` is `"threw"`. */
-    readonly error?: string;
-};
-/** How a single target was determined, when one could be. */
-type ResolvedBy = "declared" | "guard" | "resume" | "cell";
-/**
- * What would happen if `event` were dispatched at the current state.
- *
- * A refusal is FIRST-CLASS: it carries the reason and a rendered explanation,
- * so a UI draws it as visibly refused rather than omitting the control. That
- * is the totality property paying rent — the chart knows the difference
- * between "not routed here", "deliberately dropped here" and "this state is
- * over", and a debugger that hides all three behind a missing button throws
- * away the one thing this substrate knows and others do not.
- */
-interface EventPreview {
-    readonly event: string;
-    readonly status: "legal" | "refused";
-    /**
-     * Who would send this — the event's declared `from`, carried through rather
-     * than recomputed, so a button row can be grouped by sender with the same
-     * answer the report's "waiting on" line gives. `undefined` when the chart
-     * does not say.
-     */
-    readonly from?: EventOrigin;
-    /** Present iff `status` is `"refused"`. */
-    readonly reason?: RefusalReason;
-    /** A one-line rendering of `reason`. Present iff refused. */
-    readonly why?: string;
-    /** The declared edge. Present iff legal. */
-    readonly edge?: ChartEdge;
-    /** Present iff the edge is guarded. */
-    readonly guard?: GuardPreview;
-    /**
-     * The cmds that WOULD fire — read off the edge's declaration. For a guarded
-     * edge whose branch resolved, the cmds of THAT arm; for one that did not, the
-     * `then` arm's (the declared happy path) — `guard.branch === "unknown"` is
-     * what says so.
-     *
-     * This is the BEFORE question, and a `{ to, cell }` edge answers it with an
-     * empty list BY DECLARATION: the cell builds its cmds inside its body, so the
-     * chart has none to declare. For what actually fired, ask the after question
-     * — `captureCmds` in `./captured`, which reads the emitted cmds off the
-     * machine's own output.
-     */
-    readonly cmds: readonly string[];
-    /** Every state the edge declares it can reach. */
-    readonly targets: readonly string[];
-    /** The single target, when one is determined. */
-    readonly resolved?: string;
-    /** How {@link EventPreview.resolved} was determined. */
-    readonly resolvedBy?: ResolvedBy;
-    /**
-     * The msg this preview used — the sample plus the chart's `type`. `undefined`
-     * when the event declares a payload and no sample was supplied, which is
-     * also why a guard or cell may have come back `unknown`.
-     */
-    readonly msg?: {
-        readonly type: string;
-    };
-}
-/**
- * Preview one event against a live state.
- *
- * @param desc  the chart's {@link ChartDescription}.
- * @param state the live state — anything with a `type` (and `was`, on a
- *              parking state, which is what makes a resume target resolvable).
- */
-declare function previewEvent<S extends {
-    readonly type: string;
-}>(desc: ChartDescription, state: S, event: string, opts?: InspectOptions): EventPreview;
-/**
- * Preview EVERY event of the alphabet against a live state, in the chart's
- * declaration order.
- *
- * This is the button row: one entry per declared event, each either legal
- * (with its branch, targets and cmds) or refused (with its reason). Nothing is
- * filtered out — a refused event is a control the UI draws, not one it lacks.
- */
-declare function inspectState<S extends {
-    readonly type: string;
-}>(desc: ChartDescription, state: S, opts?: InspectOptions): readonly EventPreview[];
-/**
- * {@link inspectState}, plus the two roll-ups a caller almost always wants
- * next: the legal event names and the refused ones.
- *
- * The whole verdict list is still there — the split is a convenience, not a
- * filter, and `events` remains the surface a UI renders so a refusal keeps its
- * reason.
- */
-declare function inspectStateSummary<S extends {
-    readonly type: string;
-}>(desc: ChartDescription, state: S, opts?: InspectOptions): {
-    readonly state: S;
-    readonly events: readonly EventPreview[];
-    readonly legal: readonly string[];
-    readonly refused: readonly string[];
-};
-
-/**
- * A QUESTION THIS FORM CANNOT ANSWER, carried in the slot where the grid form
- * carries the answer.
- *
- * `answerable: false` is the whole type: there is no `true` member, because a
- * question this form CAN answer is answered with the answer. So `desc.refusals`
- * on a reducer description is not an empty list a UI silently renders — it is a
- * value whose only shape says why the list is not there, and code written
- * against the grid form's array fails to compile against it.
- */
-interface Unanswerable<Q extends string> {
-    readonly answerable: false;
-    /** Which question — the grid-form field this stands in for. */
-    readonly question: Q;
-    /** One line, ready to render. */
-    readonly why: string;
-}
-/** One edge of a reducer chart — an edge with no state to leave from. */
-type ReducerEdge = EdgeCore;
-/** One event of a reducer chart's alphabet. `scope` has no counterpart here. */
-interface ReducerEventInfo {
-    readonly name: string;
-    /** `foreign: true` — the name belongs to someone else and stays bare. */
-    readonly foreign: boolean;
-    /** WHO SENDS THIS. `undefined` means the chart does not say — never a guess. */
-    readonly from?: EventOrigin;
-    /** Whether the event declared a payload (`data: ty<…>()`). */
-    readonly hasPayload: boolean;
-    /** `false` iff the chart declares this event and routes it nowhere. */
-    readonly routed: boolean;
-}
-/**
- * A reducer-form chart, as data a UI can build itself from — the same contract
- * as {@link import("./describe").ChartDescription}, over the facts this form
- * actually has.
- */
-interface ReducerChartDescription {
-    /** The declared state names, in declaration order. Flat: there are no groups. */
-    readonly states: readonly string[];
-    /** The entry state — the chart's `initial` field, not a marked node. */
-    readonly initial: string;
-    readonly events: readonly ReducerEventInfo[];
-    /** Every cmd DECLARED in the `cmds` section — the effect alphabet. */
-    readonly cmds: readonly string[];
-    readonly guards: readonly string[];
-    readonly cells: readonly string[];
-    /** One edge per routed event, in the alphabet's declaration order. */
-    readonly edges: readonly ReducerEdge[];
-    /**
-     * TOTALITY, read back off the value: `true` iff every declared event owes and
-     * has an edge. Through the typed door this is always `true` — `on` is a
-     * required mapped type — so a `false` here means the types were bypassed with
-     * a cast, exactly as `refusals`' `undeclared` kind does in the grid form.
-     */
-    readonly total: boolean;
-    /** The declared events with no edge. Empty through the typed door. */
-    readonly missing: readonly string[];
-    /** NOT AVAILABLE — see {@link Unanswerable}. */
-    readonly phases: Unanswerable<"phases">;
-    /** NOT AVAILABLE — see {@link Unanswerable}. */
-    readonly refusals: Unanswerable<"refusals">;
-    /** NOT AVAILABLE — see {@link Unanswerable}. */
-    readonly scope: Unanswerable<"scope">;
-}
-/**
- * Read a reducer-form chart into its {@link ReducerChartDescription}.
- *
- * Pure, total and allocation-only, exactly as `describeChart` is: it never runs
- * a guard, a cell or a payload builder, so it is safe on a chart whose parts do
- * not exist yet.
- */
-declare function describeReducerChart<const C extends ReducerChart<C>>(chart: C): ReducerChartDescription;
-/** The edge that routes `event`, or `undefined` when the chart routes it nowhere. */
-declare function reducerEdgeAt(desc: ReducerChartDescription, event: string): ReducerEdge | undefined;
-/**
- * What would happen if `event` were dispatched at the current state.
- *
- * There is NO `status` field, and its absence is the honest part: this form
- * cannot refuse an event — `on` is total over the alphabet and there is no
- * state dimension to refuse from — so a "legal" tag would be a distinction
- * without a second case. Everything a grid preview can still say here it says:
- * the edge, the guard's branch, the declared fan-out, the target a cell picks.
- *
- * The cmds are the DECLARED ones — the before question. For what actually
- * fired, see `captureCmds` in `./captured`.
- */
-interface ReducerEventPreview {
-    readonly event: string;
-    /** The event's declared `from`, carried through rather than recomputed. */
-    readonly from?: EventOrigin;
-    /** The declared edge. `undefined` only when the chart routes the event nowhere. */
-    readonly edge?: ReducerEdge;
-    /** Present iff the edge is guarded. */
-    readonly guard?: GuardPreview;
-    /** The cmds the edge DECLARES for the arm that resolved. */
-    readonly cmds: readonly string[];
-    /** Every state the edge declares it can reach. */
-    readonly targets: readonly string[];
-    /** The single target, when one is determined. */
-    readonly resolved?: string;
-    /** How {@link ReducerEventPreview.resolved} was determined. */
-    readonly resolvedBy?: ResolvedBy;
-    /** The msg this preview used, or `undefined` when no sample was supplied. */
-    readonly msg?: {
-        readonly type: string;
-    };
-}
-/**
- * Preview one event of a reducer chart against a live state.
- *
- * The guard and cell previews are the SAME functions the grid form uses — a
- * guard is pure and a cell is pure in both forms, and the only difference is
- * that `at` is the bare event name.
- */
-declare function previewReducerEvent<S extends {
-    readonly type: string;
-}>(desc: ReducerChartDescription, state: S, event: string, opts?: InspectOptions): ReducerEventPreview;
-/**
- * Preview EVERY event of a reducer chart's alphabet against a live state, in
- * declaration order. The button row — and here every control is live, because
- * this form has nothing with which to refuse one.
- */
-declare function inspectReducerState<S extends {
-    readonly type: string;
-}>(desc: ReducerChartDescription, state: S, opts?: InspectOptions): readonly ReducerEventPreview[];
-
-export { type AnyCell as A, type ChartDescription as C, type EdgeCore as E, type GuardPreview as G, type InspectOptions as I, type ReducerChartDescription as R, type Unanswerable as U, type AnyGuard as a, type ChartEdge as b, type ChartEventInfo as c, type ChartRefusal as d, type ChartStateInfo as e, type EdgeKind as f, type EventPreview as g, type GuardUnknown as h, type InspectParts as i, type ReducerEdge as j, type ReducerEventInfo as k, type ReducerEventPreview as l, type RefusalReason as m, type ResolvedBy as n, describeChart as o, describeReducerChart as p, edgeAt as q, explainRefusal as r, inspectReducerState as s, inspectState as t, inspectStateSummary as u, previewEvent as v, previewReducerEvent as w, reducerEdgeAt as x, refusalAtState as y, stateInfo as z };