/**
 * checkpointSanitize — clone-resilience helpers for `buildPauseCheckpoint`.
 *
 * The pause checkpoint is detached via one `structuredClone` of the assembled
 * checkpoint. 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. These helpers restore the grain:
 *
 *   - `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.
 *
 * Both run ONLY on the clone-failure path of a pause — never on the hot path.
 */
import type { StageSnapshot } from '../memory/types.js';
/**
 * Walk a `StageSnapshot` tree (via `next` + `children`) and sanitize the four
 * diagnostic bags on every node IN PLACE.
 *
 * In-place is safe and intentional: `StageContext.getSnapshot()` builds fresh
 * node objects on every call, but the bag fields on those fresh nodes ALIAS
 * the live `DiagnosticCollector` bags. We replace the node's bag REFERENCE
 * with a sanitized copy — the live engine bags are never mutated, so a
 * same-executor resume keeps the original diagnostic values.
 */
export declare function sanitizeDiagnosticBags(tree: StageSnapshot): StageSnapshot;
/**
 * Build the DESCRIPTIVE error for a checkpoint that still cannot be cloned
 * after diagnostic-bag sanitization — i.e. the non-cloneable value lives in
 * consumer-owned data (a genuine JSON-safe contract violation). Probes each
 * top-level checkpoint field individually so the message names the offending
 * field family. Never lets a naked `DataCloneError` escape.
 */
export declare function describeCheckpointCloneFailure(checkpoint: Record<string, unknown>, cause: unknown): Error;