@demlik/tea 0.12.0 → 0.14.0

package/dist/reconciler/index.js

@@ -1,164 +0,0 @@
-import { createPaginatedWalk, PAGE_KEY } from '../chunk-I5OV65MS.js';
-import '../chunk-SINXE47Y.js';
-import '../chunk-EUF7XOEE.js';
-import '../chunk-JELSZN25.js';
-export { deadlineSub, subscribeDeadline } from '../chunk-JGVL3WPL.js';
-import '../chunk-Q2UM7BXU.js';
-import '../chunk-S2EGRPCM.js';
-import '../chunk-UF4MZSLT.js';
-import { initCache, get, set } from '../chunk-7SVIRMC6.js';
-import '../chunk-3JU6657S.js';
-import '../chunk-2YFLOCWX.js';
-import '../chunk-ZJ5AOYBH.js';
-import '../chunk-5EHLEUTL.js';
-import '../chunk-B5VXOFMZ.js';
-
-// src/reconciler/index.ts
-function createReconciler(config, rng = Math.random) {
-  const walk = createPaginatedWalk(
-    {
-      firstPage: config.firstPage,
-      nextCursor: config.nextCursor,
-      // The walk's per-page hook emits no Cmds — the reconciler accumulates the
-      // page's items itself in `pageOk` (where it holds its own slice), so the
-      // walk's onPage stays empty.
-      onPage: () => [],
-      retry: config.retry,
-      circuit: config.circuit,
-      rateLimit: config.rateLimit,
-      deadline: config.deadline
-    },
-    rng
-  );
-  function changeId(change) {
-    return config.idOf ? config.idOf(change) : JSON.stringify(change);
-  }
-  function withWalk(s, w) {
-    return { ...s, walk: w };
-  }
-  function init() {
-    return {
-      phase: "idle",
-      walk: walk.init(),
-      actual: [],
-      plan: [],
-      appliedCursor: 0,
-      applied: initCache()
-    };
-  }
-  function scan(s, at) {
-    if (s.phase !== "idle") return [s, []];
-    const [w, cmds] = walk.start(s.walk, at);
-    const next = { ...s, phase: "scanning", walk: w };
-    return [next, cmds];
-  }
-  function pageOk(s, page, at) {
-    if (s.phase !== "scanning") {
-      const [w2] = walk.pageOk(s.walk, page, at);
-      return [withWalk(s, w2), []];
-    }
-    const [w, walkCmds] = walk.pageOk(s.walk, page, at);
-    const actual = [...s.actual, ...config.itemsOf(page)];
-    const scanned = { ...s, walk: w, actual };
-    const cmds = walkCmds;
-    if (walk.isComplete(scanned.walk)) {
-      const [plannedState, applyCmds] = planned(scanned, at);
-      return [plannedState, [...cmds, ...applyCmds]];
-    }
-    return [scanned, cmds];
-  }
-  function pageErr(s, error, at) {
-    const [w, cmds] = walk.pageErr(s.walk, error, at);
-    let next = withWalk(s, w);
-    if (s.phase === "scanning" && w.resilience.calls[PAGE_KEY]?.phase === "failed") {
-      next = { ...next, phase: "failed" };
-    }
-    return [next, cmds];
-  }
-  function planned(s, at, changes) {
-    const plan = changes ?? config.diff(config.desired, s.actual);
-    const planning = {
-      ...s,
-      phase: "applying",
-      plan,
-      appliedCursor: 0
-    };
-    return applyNext(planning, at);
-  }
-  function applyNext(s, at) {
-    if (s.phase !== "applying") return [s, []];
-    let cursor = s.appliedCursor;
-    while (cursor < s.plan.length) {
-      const change = s.plan[cursor];
-      if (change === void 0) {
-        cursor++;
-        continue;
-      }
-      const id = changeId(change);
-      if (get(s.applied, id, at) === void 0) {
-        const advanced = { ...s, appliedCursor: cursor };
-        return [advanced, [config.apply(change)]];
-      }
-      cursor++;
-    }
-    const done = { ...s, phase: "done", appliedCursor: cursor };
-    return [done, []];
-  }
-  function applied(s, change, at) {
-    if (s.phase !== "applying") return [s, []];
-    const id = changeId(change);
-    const applied2 = set(
-      s.applied,
-      id,
-      change,
-      at,
-      Number.MAX_SAFE_INTEGER
-    );
-    const advanced = {
-      ...s,
-      applied: applied2,
-      appliedCursor: s.appliedCursor + 1
-    };
-    return applyNext(advanced, at);
-  }
-  function onTimer(s, msg) {
-    const [w, cmds] = walk.onTimer(s.walk, msg);
-    if (w === s.walk) {
-      return [s, []];
-    }
-    let next = withWalk(s, w);
-    if (s.phase === "scanning" && w.resilience.calls[PAGE_KEY]?.phase === "failed") {
-      next = { ...next, phase: "failed" };
-    }
-    return [next, cmds];
-  }
-  function isComplete(s) {
-    return s.phase === "done";
-  }
-  function subs(s) {
-    return walk.subs(s.walk);
-  }
-  function handlers(ports) {
-    return walk.handlers(ports);
-  }
-  return {
-    init,
-    scan,
-    pageOk,
-    pageErr,
-    planned,
-    applyNext,
-    applied,
-    onTimer,
-    isComplete,
-    subs,
-    handlers
-  };
-}
-function liftReconciler(state, [slice, cmds]) {
-  return [{ ...state, rec: slice }, cmds];
-}
-
-export { createReconciler, liftReconciler };
-//# sourceMappingURL=index.js.map
-//# sourceMappingURL=index.js.map

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"}