footprintjs 9.43.0 → 9.44.0

package/dist/types/lib/runner/checkpoint.d.ts

@@ -6,24 +6,35 @@
  * (`pause/record.ts` · `CHECKPOINT_VERSION` / `decodeCheckpoint`), and
  * detaches it with one `structuredClone`.
  *
- * Clone resilience lives beside it. The JSON-safe contract governs what
- * CONSUMERS put into a checkpoint (pauseData, shared state) — but the
- * execution tree's diagnostic bags (`logs`/`errors`/`metrics`/`evals`) accept
- * ANY value at write time without cloning (`$debug`/`$error`/`$metric`/`$eval`
- * route through `DiagnosticCollector`, which stores raw references). A
- * `$debug`'d function in any stage of a pausing run would make the
- * whole-checkpoint clone throw `DataCloneError` — swallowing the pause. That
- * violates the library's error-isolation grain (observability side-bags never
- * abort traversal anywhere else), so:
+ * LEAN (format 2). The checkpoint holds what `resume()` reads and the pause's
+ * own record, nothing else:
  *
- *   - `sanitizeDiagnosticBags` — replace non-cloneable diagnostic values with
- *     marker strings (`'[non-serializable: function]'`) so the pause survives.
- *   - `describeCheckpointCloneFailure` — when the clone STILL fails after
- *     sanitization (the non-cloneable lives in consumer-owned data, e.g.
- *     `pauseData`), name the offending checkpoint field(s) and point at the
- *     JSON-safe contract instead of letting a naked `DataCloneError` escape.
+ *   read by resume  the cursor (`pausedStageId`, `subflowPath`, `pausedBy`),
+ *                   the state (`sharedState`, and `subflowStates` — one capture
+ *                   per subflow ON the pause path), the counters
+ *                   (`executionCount`, `visitCounts` — one entry per stage id),
+ *                   the waiting siblings (`pendingPauses`), the redaction names
+ *                   (`redactionMarks`), the link (`pausedExecution`);
+ *   the record      `pauseData` (the question), `invokerStageId`, `pausedAt`.
  *
- * Both run ONLY on the clone-failure path of a pause — never on the hot path.
+ * So its size is the state's and the chart's, never the run's length. Format 1
+ * also carried the whole execution tree and the finished subflows' results —
+ * the run's served record, which no resume read and which grew with every
+ * finished iteration (`bench/checkpoint-size.ts`: 19.3 MB after 60 agent
+ * turns whose resumable state — root plus captures — is 0.13 MB; the tree
+ * alone was 97%). That record is `getSnapshot()`'s. Pinned:
+ * test/lib/pause/checkpoint-size.test.ts.
+ *
+ * THE LAW holds: the checkpoint keeps REAL values — no redaction policy ever
+ * touches it (it is what the resumed run computes on); the marks travel as
+ * NAMES only.
+ *
+ * The JSON-safe contract governs what CONSUMERS put into a checkpoint
+ * (`pauseData`, shared state). A value `structuredClone` refuses can only come
+ * from them — shared state is cloned at every commit, so a function never
+ * reaches it, and no diagnostic bag is carried — so a failed clone becomes a
+ * DESCRIPTIVE contract error naming the field (`describeCheckpointCloneFailure`)
+ * instead of a naked `DataCloneError`.
  */
 import type { FlowchartTraverser } from '../engine/traversal/FlowchartTraverser.js';
 import type { FlowchartCheckpoint, PauseSignal, RedactionMarks } from '../pause/types.js';
@@ -36,7 +47,7 @@ export interface PausedRun {
     readonly redactionMarks?: RedactionMarks;
 }
 /**
- * Build a fully DETACHED checkpoint from a caught PauseSignal.
+ * Build a fully DETACHED, lean checkpoint from a caught PauseSignal.
  *
  * Every field is deep-copied via one `structuredClone` of the assembled
  * checkpoint, because the raw pieces alias live engine state:
@@ -45,27 +56,21 @@ export interface PausedRun {
  *     but (copy-on-write, 9.29.0) every later generation shares its
  *     unchanged subtrees, so a checkpoint that aliased it would alias the
  *     resumed run's state too.
- *   - `executionTree` nodes are fresh, but their `logs`/`errors`/`metrics`/
- *     `evals`/`stageReads`/`flowMessages` fields reference live
- *     `DiagnosticCollector` bags that keep accumulating on same-executor
- *     resume.
  *   - `subflowStates` values are shallow copies whose NESTED objects alias
  *     subflow memory, and they get seeded back into live runtimes on resume.
- *   - `subflowResults` values stay referenced by the traverser's results map.
  *
  * The checkpoint is persisted by contract ("store in Redis/Postgres") — it
- * must never share structure with the engine. Pause is not a hot path; the
- * clone cost is irrelevant.
+ * must never share structure with the engine.
  *
- * On clone failure the diagnostic bags are sanitized (the live engine bags
- * are never touched) and the clone retried; if the retry STILL fails, the
- * violation is in consumer-owned data (realistically `pauseData` — a function
- * can never reach shared state: the record's clone at commit refuses it) and a
- * DESCRIPTIVE contract error names the offending checkpoint field(s).
+ * The state is read straight off the root runtime's store — no snapshot is
+ * built (a snapshot would build the execution tree and copy the commit log,
+ * work proportional to the run's length, only to throw both away).
  *
  * Subflow scope capture (`subflowStates`) survives ONLY on the signal — the
  * nested runtimes are GC'd as the stack unwinds. Promoting it onto the
  * checkpoint here lets cross-executor resume restore pre-pause subflow
- * scope (e.g. an Agent's `scope.history`). Empty `{}` for root-level pauses.
+ * scope (e.g. an Agent's `scope.history`). The signal captures a subflow only
+ * as it bubbles through that subflow's boundary, so the keys are exactly the
+ * pause path's. Empty `{}` for root-level pauses.
  */
 export declare function buildPauseCheckpoint(signal: PauseSignal, traverser: FlowchartTraverser<any, any>, run: PausedRun): FlowchartCheckpoint;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "9.43.0",
+  "version": "9.44.0",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",