footprintjs 10.0.1 → 10.2.0

package/dist/types/lib/scope/ScopeFacade.d.ts

@@ -13,6 +13,9 @@
  * }
  * ```
  */
+import type { AttemptContext, AttemptError, CallOptions, RetryPolicy, RunCorrelation } from '../attempt/types.js';
+import type { FlowChart } from '../builder/types.js';
+import type { DetachDriver, DetachHandle } from '../detach/types.js';
 import type { ExecutionEnv } from '../engine/types.js';
 import { StageContext } from '../memory/StageContext.js';
 import type { CommitEvent, RedactionPolicy, RedactionReport, ScopeRecorder } from './types.js';
@@ -63,6 +66,28 @@ export declare class ScopeFacade {
      * tree and this stays unset; see {@link rule}.
      */
     private _localRule?;
+    /**
+     * The run's correlation (10.1), installed by the executor's composed scope factory
+     * (`RunObservers · composeScopeFactory`) — stamped LAST on every scope and emit event this facade fires,
+     * only when present, so a run without one fires byte-identical events.
+     */
+    private _correlation?;
+    /**
+     * The attempt this facade was built for (P1b) — the runner's, read off the
+     * context at construction. A facade is ONE attempt's handle: once that
+     * attempt ends without an answer (its cap, the deadline, a cancellation, a
+     * throw), the function behind it may still be running, and anything it
+     * touches through this facade is refused ({@link refuseIfAttemptEnded}) —
+     * a write or an emit is also recorded on the stage. Absent for a stage the
+     * runner does not run: nothing is fenced, as before.
+     */
+    private readonly _attempt?;
+    /** The run's signal, for `$attempt()` of a stage the runner does not run. */
+    private readonly _runSignal?;
+    /** `$call`s with `of > 1` in flight through this facade — a keyless touching call inside one is refused (P3). */
+    private _retryingCalls;
+    /** This attempt's observed reports, grouped into series (P2) — made on the first report. */
+    private _observedBook?;
     constructor(context: StageContext, stageName: string, readOnlyValues?: unknown, executionEnv?: ExecutionEnv);
     /**
      * The redaction rule this facade decides with — the SAME object its
@@ -93,6 +118,12 @@ export declare class ScopeFacade {
      * @internal
      */
     useRedactionPolicy(policy: RedactionPolicy): void;
+    /**
+     * Install the run's correlation — every scope and emit event this facade fires carries it; `undefined` clears
+     * it. Engine-only (the composed scope factory calls it once per stage), like `useRedactionPolicy`.
+     * @internal
+     */
+    useCorrelation(correlation: RunCorrelation | undefined): void;
     /** @internal */
     getRedactionPolicy(): RedactionPolicy | undefined;
     /**
@@ -119,6 +150,85 @@ export declare class ScopeFacade {
      * to the stage that made the write.
      */
     private assertLive;
+    /**
+     * The attempt fence (P1b): this facade's attempt has ended, so whatever the
+     * abandoned function does now must not reach the stage — not its buffer, its
+     * reads, its untracked sources or a recorder. Refused; a write or an emit is
+     * recorded on the stage first (`StageSnapshot.lateWrites`, the name only),
+     * a read (`channel` undefined) is not.
+     */
+    private refuseIfAttemptEnded;
+    /**
+     * The attempt this stage function runs in — `scope.$attempt()` (design
+     * §3.1). Its `signal` aborts when the attempt must stop (its cap, the run's
+     * deadline, a cancellation): pass it to `fetch` and SDK calls. Its
+     * `timeLeftMs()` reads the run's deadline — time is an input the record
+     * cannot replay, so with a deadline the read marks the stage's commit
+     * `untrackedSources: ['env']`, as `getEnv()` does.
+     *
+     * A stage the attempt runner does not run (no retry policy, no `timeoutMs`,
+     * no deadline) is attempt 1 of 1, with the run's signal and `Infinity` left.
+     *
+     * ```typescript
+     * const t = scope.$attempt();
+     * const res = await fetch(url, { signal: t.signal });
+     * if (t.timeLeftMs() < 1_000) scope.summary = 'partial';
+     * ```
+     */
+    getAttempt(): AttemptContext;
+    /**
+     * A call to an outside system, made inside this stage — `scope.$call(target, fn, policy?)` (design §3.6, P2).
+     * `fn` runs on the attempt runner under `policy` (none = ONE attempt, still recorded: a single call is evidence
+     * too), and every attempt is an `AttemptRecord` of kind `'call'` on this stage's execution-tree node and on
+     * `onAttempt` — its timing, outcome, failure category and the retry-or-stop decision, its error served under the
+     * run's redaction rule.
+     *
+     * The call lives within this stage attempt: it is capped by the time the attempt has left (its cap, the run's
+     * deadline) and `fn`'s `signal` aborts when the attempt does; once the attempt is over nothing of the call lands
+     * and no further attempt of it starts (`attempt/call.ts`). `target` is a NAME from code — never a value.
+     *
+     * ```typescript
+     * const quote = await scope.$call('stripe.quotes.create', (t) => stripe.quotes.create(body, { signal: t.signal }),
+     *   { attempts: 3, timeoutMs: 10_000, backoffMs: (n) => 500 * n });
+     * ```
+     *
+     * A call that CHANGES an outside system declares it (P3): `options.touches` names the system and
+     * `options.idempotencyKey` the key every attempt is made under (`t.idempotencyKey`) — a value from the stage's
+     * input or state, never from model output. A touching call that may retry without a key is refused here,
+     * before anything is sent; each record says what its attempt did (`effect`), and a call that ends without an answer after any attempt left the
+     * effect unknown rejects with `UnknownEffectError` — reconcile by the key, do not retry blindly.
+     */
+    call<T>(target: string, fn: (attempt: AttemptContext) => Promise<T> | T, policy?: RetryPolicy, options?: CallOptions): Promise<T>;
+    /** `runCall` with this stage attempt as its host (`call`). */
+    private startCall;
+    /** @internal The explicit retry helper owns this state; the normal write path still owns retention/commit. */
+    writeRetryLoopState(key: string, state: {
+        readonly idempotencyKey: string;
+    }): void;
+    /** @internal Exactly the existing P3 key-retention law; operational state keeps the real key. */
+    serveRetryLoopKey(key: string): string;
+    /** @internal Loop state is durable data: never persist the thrown value, stack, cause or payload. */
+    serveRetryLoopError(error: unknown): AttemptError;
+    /** A touching call's target, its key served for the records (`RedactionRule · retainIdempotencyKey`: by name and by its sources). */
+    private callEffect;
+    /**
+     * A `$call` from an ended attempt, or from a frame that has committed: recorded by name (`lateWrites`, channel
+     * `'attempt'`) and refused — before anything reaches outside. The P1b fence first, so its message and record are
+     * the same.
+     */
+    private refuseLateCall;
+    /**
+     * An outside attempt an adapter reported — `AttemptContext.observed` on this stage's attempt or on one of its
+     * calls' (P2). Read and validated first (a malformed report is the adapter's bug: a `TypeError`, and it never
+     * reaches the record). A report that comes after its attempt ended — the call attempt it was made through, this
+     * stage attempt, or the frame's commit — is recorded by name (`lateWrites`, channel `'attempt'`) and DROPPED,
+     * never thrown: adapters report from an SDK's own callbacks, which may fire after the stage moved on, and an
+     * observed attempt never changes control flow — in either direction. Its series opens at this stage attempt's call
+     * level: an SDK's call is a call the stage attempt made, so a report made through a `$call` is that call's sibling.
+     */
+    private recordObserved;
+    /** This facade's attempt has ended — the P1b fence is closed. */
+    private attemptHasEnded;
     /** Called by StageContext.commit() observer. Converts tracked writes to CommitEvent format.
      *  Errors are caught to prevent recorder issues from aborting the traversal. */
     private _onCommitFired;
@@ -147,9 +257,9 @@ export declare class ScopeFacade {
      */
     emitEvent(name: string, payload: unknown): void;
     /** See `ScopeMethods.$detachAndJoinLater`. */
-    detachAndJoinLater(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): import('../detach/types.js').DetachHandle;
+    detachAndJoinLater(driver: DetachDriver, child: FlowChart, input?: unknown): DetachHandle;
     /** See `ScopeMethods.$detachAndForget`. */
-    detachAndForget(driver: import('../detach/types.js').DetachDriver, child: import('../builder/types.js').FlowChart, input?: unknown): void;
+    detachAndForget(driver: DetachDriver, child: FlowChart, input?: unknown): void;
     /**
      * Build the subflowPath (outer → inner) for event enrichment.
      *
@@ -251,8 +361,10 @@ export declare class ScopeFacade {
      * Returns the execution environment — read-only infrastructure values
      * that propagate through nested executors (like `process.env` for flowcharts).
      *
-     * Contains: signal (abort), timeoutMs, traceId.
-     * Frozen at construction time. Inherited by subflows automatically.
+     * Contains: signal (abort — the run's one effective signal), timeoutMs, traceId, operationId, traceparent,
+     * deadline (epoch ms) — the run's env as admitted (`attempt/correlation.ts · admitRunEnv`: one own-field
+     * snapshot; `traceparent` is the canonical header the run's correlation carries, never the received bytes), then
+     * armed (`runner/deadline.ts · armRun`). Frozen at construction time. Inherited by subflows automatically.
      *
      * ```typescript
      * const { signal, traceId } = scope.getEnv();
@@ -266,6 +378,8 @@ export declare class ScopeFacade {
     /** @internal */
     getPipelineId(): string;
     private _invokeHook;
+    /** The event as fired: unchanged without a correlation, else with the run's correlation as its last key. */
+    private _correlated;
     /**
      * The scope channel's isolation: a recorder's throw becomes an `onError` on every recorder
      * (stamped with this stage), and a throw from `onError` itself is dropped.

package/dist/types/lib/scope/recorders/DebugRecorder.d.ts

@@ -1,14 +1,27 @@
 /**
  * DebugRecorder — Development-focused recorder for detailed debugging
  *
- * Captures errors (always), mutations and reads (in verbose mode),
- * and stage lifecycle events for troubleshooting.
+ * Captures errors (always — a scope recorder's own failure, the scope
+ * channel's `onError`; a stage's failure is not one), mutations and reads
+ * (in verbose mode), and stage lifecycle events for troubleshooting.
+ *
+ * Attempts (10.1): one `attempt` row per attempt of a series that retried,
+ * gave up or timed out (`recorder/attemptSeries.ts · isRetryEvidence`) — its
+ * outcome, category, duration, decision, the cap and time left it ran under
+ * (present with a cap or a deadline) and served error — and one `attemptStop`
+ * row when the series gave up (exhausted, declined, no time left). Both verbosities: like a
+ * pause, an attempt is significant — and for a retried stage these rows are
+ * the failure evidence (a stage's error is never an `error` row). They arrive on the FLOW channel
+ * (`onAttempt`), so attach with `attachCombinedRecorder` to see them; the
+ * flow channel's own `onError` / `onPause` / `onResume` are ignored, so a
+ * combined attach never doubles a scope row.
  */
+import type { FlowAttemptEvent } from '../../engine/narrative/types.js';
 import type { RecorderOperation } from '../../recorder/RecorderOperation.js';
 import type { ErrorEvent, PauseEvent, ReadEvent, ResumeEvent, ScopeRecorder, StageEvent, WriteEvent } from '../types.js';
 export type DebugVerbosity = 'minimal' | 'verbose';
 export interface DebugEntry {
-    type: 'read' | 'write' | 'error' | 'stageStart' | 'stageEnd' | 'pause' | 'resume';
+    type: 'read' | 'write' | 'error' | 'stageStart' | 'stageEnd' | 'pause' | 'resume' | 'attempt' | 'attemptStop';
     stageName: string;
     timestamp: number;
     data: unknown;
@@ -48,6 +61,7 @@ export declare class DebugRecorder implements ScopeRecorder {
     onStageEnd(event: StageEvent): void;
     onPause(event: PauseEvent): void;
     onResume(event: ResumeEvent): void;
+    onAttempt(event: FlowAttemptEvent): void;
     getEntries(): DebugEntry[];
     getErrors(): DebugEntry[];
     getEntriesForStage(stageName: string): DebugEntry[];

package/dist/types/lib/scope/recorders/MetricRecorder.d.ts

@@ -6,6 +6,14 @@
  * (Convention 1 — one purpose per recorder: this is the ScopeRecorder; the store
  * is the storage).
  *
+ * Attempts (10.1): a stage with a retry policy runs each attempt in a fresh
+ * scope, so this recorder sees one `onStageStart` per attempt. `attempts` is
+ * that count, present when it is 2 or more; `duration` spans the whole
+ * execution — from the FIRST attempt's start, waits included — never just the
+ * attempt that succeeded. An execution that never returned (it gave up) has
+ * no `onStageEnd`, so its duration stays `0`, as for any failed stage. A stage
+ * that ran once reads exactly as before.
+ *
  * @example
  * ```typescript
  * const metric = new MetricRecorder();
@@ -38,6 +46,8 @@ export interface StepMetrics {
     pauseCount: number;
     /** Duration in ms for this invocation. */
     duration: number;
+    /** How many attempts the execution made (its `onStageStart` count) — present only when it retried (≥ 2). */
+    attempts?: number;
 }
 /** Aggregated metrics across all invocations (backward compatible). */
 export interface AggregatedMetrics {

package/dist/types/lib/scope/runtime.d.ts

@@ -7,6 +7,7 @@
  * ScopeFacade owns recording, redaction and state access; custom scopes may
  * explicitly supply a smaller port (including `{}` for data-only scopes).
  */
+import type { RunCorrelation } from '../attempt/types.js';
 import type { RedactionPolicy, ScopeRecorder } from './types.js';
 /** Engine-facing capabilities. Never use a strict user-field proxy as this port. */
 export interface ScopeRuntimeTarget {
@@ -15,6 +16,8 @@ export interface ScopeRuntimeTarget {
     getScopeRecorders?(): ScopeRecorder[];
     useSharedRedactedKeys?(keys: Set<string>): void;
     useRedactionPolicy?(policy: RedactionPolicy): void;
+    /** The run's correlation, stamped on every scope and emit event this scope fires (10.1). */
+    useCorrelation?(correlation: RunCorrelation | undefined): void;
     getRedactedKeys?(): Set<string>;
     notifyStageStart?(): void;
     notifyStageEnd?(duration?: number): void;

package/dist/types/lib/scope/types.d.ts

@@ -5,6 +5,7 @@
  * Architecture follows composition-over-inheritance: Recorders are
  * attached to Scope instances to observe read/write/commit operations.
  */
+import type { RunCorrelation } from '../attempt/types.js';
 import type { StructuredErrorInfo } from '../errors/errorInfo.js';
 export interface RecorderContext {
     stageName: string;
@@ -14,6 +15,11 @@ export interface RecorderContext {
     runtimeStageId: string;
     pipelineId: string;
     timestamp: number;
+    /**
+     * The run's correlation (10.1) — the same frozen object as `TraversalContext.correlation` on the flow events
+     * and `getSnapshot().correlation`. Absent — no key — when the run's env gave none.
+     */
+    readonly correlation?: RunCorrelation;
 }
 export interface ReadEvent extends RecorderContext {
     key?: string;

package/dist/types/lib/sinks/fileSink.d.ts

@@ -0,0 +1,135 @@
+/**
+ * sinks/fileSink.ts — the record, one JSON line per entry, in a file (design §3.5, §4, packet P6). NODE ONLY: the
+ * one file in `src/` that imports a Node built-in, reachable only through the `footprintjs/sinks` door.
+ *
+ * WHY A FILE, WHY THIS SHAPE. A run's record must outlive the process that made it — a killed process, a crashed
+ * host, a serverless freeze. Each entry the log hands over is encoded, checked and given its own offset in the file,
+ * and its write is handed to the I/O pool AT ONCE (a positional write — no entry waits for the event loop to turn);
+ * the pool's threads perform them while the main thread runs on. A process killed after a pool thread wrote an entry
+ * keeps it. Until then it is not on disk: microseconds on a free pool, but the pool (4 threads by default) is shared
+ * with DNS lookups, zlib, crypto and other fs work, so while it is busy the window is as long as that work — and since
+ * writes complete out of order, a kill can lose an entry in the middle (the reader reports the hole). `flush()` waits for every write and
+ * `fsync`s — the step that also survives the machine losing power, and the one the executor awaits after each run's
+ * closing entry.
+ *
+ * THE THREAT MODEL, as code — every resource bounded, nothing that can stall the run:
+ *   - ONLY THE PATH THE APP GIVES. Resolved once and opened once, at `fileSink(path)`; every entry goes to that open
+ *     file. A symbolic link at the path is refused (`O_NOFOLLOW`, where the platform has it), and so is anything
+ *     that is not a regular file, a file with another hard link, another owner, or group/world write. A file the
+ *     sink creates is `0o600`.
+ *   - ATOMIC PER ENTRY. A line is encoded in full first — an entry JSON cannot write (a `BigInt`, a cycle) is
+ *     refused whole — then written at its own offset. A write that fails part-way leaves a hole up to the next
+ *     entry's offset; the reader splits at it (NUL), so a torn line never swallows the one after it (an existing
+ *     file with a torn tail gets a newline first).
+ *   - BOUNDED: `maxEntryBytes` (one line, 8 MiB — refused by name, before it is encoded when its length already
+ *     says so), `maxQueuedBytes` (accepted, not yet written, 16 MiB — past it an entry is DROPPED and counted, never
+ *     buffered without limit), `maxBytes` (the file, 64 MiB — once full, every further entry is refused and counted;
+ *     a closing entry may use a 64 KiB reserve so a full file can still say how the run ended), `flushTimeoutMs`
+ *     (10 s — then `flush()` rejects). Every refusal throws from the sink method, which the log counts
+ *     (`getSnapshot().sink`); a write that fails later rejects that entry's promise, counted the same way.
+ *   - ASYNCHRONOUS WRITES ONLY. No method blocks on the disk; the file is released asynchronously, after every
+ *     write and every started fsync.
+ *   - NO SECRET ON DISK is the EXECUTOR's law, applied before any entry reaches an adapter (`runner/recordSink.ts`):
+ *     this file writes what it is handed and reads nothing else.
+ *   - ONE WRITER PER FILE. A second sink on a file this process has open is refused (by device and inode, across the
+ *     CommonJS and ESM builds). ANOTHER PROCESS writing the same path is not seen at open: each writes at its own
+ *     offsets and would overwrite the other. `flush()` checks the file's size against what this sink placed and rejects
+ *     (a loss the run counts) when another writer's bytes reach past it — best effort: an overwrite this sink's own
+ *     later writes cover is not seen. Give each process its own file.
+ *
+ * WHAT JSON KEEPS. A line holds what `JSON.stringify` keeps: a `Date` becomes its ISO string, a `Map` / `Set` an
+ * empty object, `undefined` disappears. A record of plain JSON values reads back exactly (`readRecordFile` →
+ * `readStoredRecord`); for richer values, bring an adapter with a richer encoding.
+ */
+import type { RecordSink } from 'foottrace/write';
+/** The default cap on a record file: 64 MiB. */
+export declare const DEFAULT_FILE_SINK_MAX_BYTES: number;
+/** The default cap on ONE entry's line: 8 MiB. */
+export declare const DEFAULT_FILE_SINK_MAX_ENTRY_BYTES: number;
+/** The default cap on bytes accepted but not yet written: 16 MiB. */
+export declare const DEFAULT_FILE_SINK_MAX_QUEUED_BYTES: number;
+/** The default bound on `flush()`: 10 s. */
+export declare const DEFAULT_FILE_SINK_FLUSH_TIMEOUT_MS = 10000;
+/** `fileSink`'s options — every resource the sink can spend, bounded. */
+export interface FileSinkOptions {
+    /**
+     * The most bytes the file may hold (the bytes already in it count). Once an entry would pass it, the file is FULL:
+     * that entry and every later one is refused and counted by the run, never written — except a closing entry, which
+     * may use 64 KiB more so a full file can still say how the run ended. Default 64 MiB.
+     */
+    readonly maxBytes?: number;
+    /** The largest ONE entry's line may be; a larger entry is refused whole (`maxEntryBytes` named). Default 8 MiB. */
+    readonly maxEntryBytes?: number;
+    /**
+     * The most bytes accepted and not yet on disk. Writes are asynchronous, so a sink slower than the run queues; past
+     * this bound an entry is DROPPED and counted (never buffered without limit, never a stall). Default 16 MiB.
+     */
+    readonly maxQueuedBytes?: number;
+    /** How long `flush()` (drain the queue, then `fsync`) may take before it rejects. Default 10 s. */
+    readonly flushTimeoutMs?: number;
+}
+/** A record sink that appends to one file — `RecordSink` plus what the app needs to manage the file. */
+export interface FileSink extends RecordSink {
+    /** The absolute path the sink writes to — resolved once, when it was made. */
+    readonly path: string;
+    /**
+     * Bytes this sink knows are on disk: the file's size when it opened plus every byte its writes completed — a
+     * running sum, not the file's end (writes complete out of order; a failed one leaves a hole).
+     */
+    readonly bytes: number;
+    /** Bytes accepted and not yet written. */
+    readonly queuedBytes: number;
+    /** `true` once an entry was refused for `maxBytes`: the file is full, and only a closing entry may still go. */
+    readonly full: boolean;
+    /**
+     * Release the file. Idempotent. Every entry after it is refused (the run counts it), and `flush()` rejects;
+     * entries already accepted are still written (and a flush already started finishes), then the file is closed —
+     * the promise settles then.
+     */
+    close(): Promise<void>;
+}
+/**
+ * A record sink that appends each entry to `path` as one JSON line — the crash-safe record on a Node host.
+ *
+ * Every method returns at once: the line is encoded, checked against every bound, given its offset and handed to
+ * the I/O pool. The method's promise settles when that line is written; a write that fails rejects it, and the run
+ * counts the loss.
+ *
+ * @throws TypeError when `path` is not a non-empty string or does not name a regular file the writer owns alone;
+ *   RangeError for a bound that is not a whole number ≥ 1; the operating system's error when
+ *   the file cannot be opened (a symbolic link at `path` included). Made once, at setup — never during a run.
+ *
+ * @example
+ * ```typescript
+ * import { fileSink, readRecordFile } from 'footprintjs/sinks';
+ * import { readStoredRecord } from 'foottrace';
+ *
+ * const sink = fileSink('/var/footprint/orders.jsonl');
+ * const executor = new FlowChartExecutor(chart, { sink });
+ * await executor.run({ input });
+ * // …later, or after a crash:
+ * const record = readStoredRecord(readRecordFile('/var/footprint/orders.jsonl').entries);
+ * record.root(runId)?.complete; // false for a run that never ended
+ * ```
+ */
+export declare function fileSink(path: string, options?: FileSinkOptions): FileSink;
+/** A record file read back: every parsed line, and every line that could not be. */
+export interface RecordFile {
+    /** The parsed entries, in file order — untrusted input for `readStoredRecord` (`foottrace`). */
+    readonly entries: readonly unknown[];
+    /** Each line that is not JSON (a torn last line, a corrupt one), by its 1-based number. Blank lines are skipped. */
+    readonly unreadable: readonly {
+        readonly line: number;
+        readonly reason: string;
+    }[];
+}
+/**
+ * Read a record file back, line by line — the entries for `readStoredRecord`, and every line that could not be
+ * read, by number, never a failed read. A stored key named `__proto__` stays data (`JSON.parse` makes it an own
+ * property). The file is untrusted: a file larger than `maxBytes` (default 256 MiB) is refused before it is read.
+ *
+ * @throws RangeError when the file is larger than `maxBytes`; the operating system's error when it cannot be read.
+ */
+export declare function readRecordFile(path: string, options?: {
+    readonly maxBytes?: number;
+}): RecordFile;

package/dist/types/recorders.d.ts

@@ -25,7 +25,7 @@
  */
 import type { CombinedNarrativeRecorderOptions } from './lib/engine/narrative/CombinedNarrativeRecorder.js';
 import { CombinedNarrativeRecorder } from './lib/engine/narrative/CombinedNarrativeRecorder.js';
-import type { BreakRenderContext, DecisionRenderContext, EmitRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, NarrativeFormatter, OpRenderContext, SelectedRenderContext, StageRenderContext, SubflowRenderContext } from './lib/engine/narrative/narrativeTypes.js';
+import type { AttemptRenderContext, BreakRenderContext, DecisionRenderContext, EmitRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, NarrativeFormatter, OpRenderContext, SelectedRenderContext, StageRenderContext, SubflowRenderContext } from './lib/engine/narrative/narrativeTypes.js';
 import { AdaptiveNarrativeFlowRecorder } from './lib/engine/narrative/recorders/AdaptiveNarrativeFlowRecorder.js';
 import type { ManifestEntry } from './lib/engine/narrative/recorders/ManifestFlowRecorder.js';
 import { ManifestFlowRecorder } from './lib/engine/narrative/recorders/ManifestFlowRecorder.js';
@@ -66,7 +66,13 @@ export declare function manifest(): ManifestInstance;
 export declare function adaptive(): AdaptiveNarrativeFlowRecorder;
 export declare function milestone(): MilestoneNarrativeFlowRecorder;
 export declare function windowed(maxEntries?: number): WindowedNarrativeFlowRecorder;
-export type { BreakRenderContext, CombinedNarrativeRecorderOptions, DecisionRenderContext, EmitEvent, EmitRecorder, EmitRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, NarrativeFormatter, OpRenderContext, SelectedRenderContext, StageRenderContext, SubflowRenderContext, };
+export type { AttemptRenderContext, BreakRenderContext, CombinedNarrativeRecorderOptions, DecisionRenderContext, EmitEvent, EmitRecorder, EmitRenderContext, ErrorRenderContext, ForkRenderContext, LoopRenderContext, NarrativeFormatter, OpRenderContext, SelectedRenderContext, StageRenderContext, SubflowRenderContext, };
 export type { AggregatedMetrics, MetricRecorderOptions, StageMetrics };
+export type { AttemptAggregate, AttemptDecisionRow, AttemptMetricRef, AttemptQuery, AttemptRecorderOptions, AttemptRow, AttemptRunRow, AttemptRunStats, AttemptStats, AttemptStorageStats, AttemptStore, PhysicalAttemptRow, } from './lib/recorder/attemptMetricsTypes.js';
+export { memoryStore } from './lib/recorder/AttemptRecorder.js';
 export type { CompositeSnapshot } from './lib/recorder/index.js';
 export { CompositeRecorder } from './lib/recorder/index.js';
+import type { AttemptRecorderOptions } from './lib/recorder/attemptMetricsTypes.js';
+import { AttemptRecorder } from './lib/recorder/AttemptRecorder.js';
+/** Collect payload-free attempts during traversal; storage adapters are optional and provider-neutral. */
+export declare function attempts(options?: AttemptRecorderOptions): AttemptRecorder;

package/dist/types/sinks.d.ts

@@ -0,0 +1,23 @@
+/**
+ * footprintjs/sinks — where a run's crash-safe record goes on a Node host (10.1, design §3.5).
+ *
+ * NODE ONLY. This door imports `node:fs`; it is the one door that does (`test/architecture/layering.test.ts`), so
+ * every other door stays loadable in a browser. The port itself — `RecordSink`, and the reference `memorySink()` —
+ * is foottrace's (`foottrace/write`); the reader is `readStoredRecord` (`foottrace`).
+ *
+ * @example
+ * ```typescript
+ * import { flowChart, FlowChartExecutor } from 'footprintjs';
+ * import { fileSink, readRecordFile } from 'footprintjs/sinks';
+ * import { readStoredRecord } from 'foottrace';
+ *
+ * const executor = new FlowChartExecutor(chart, { sink: fileSink('/var/footprint/orders.jsonl') });
+ * await executor.run({ input });
+ *
+ * // After a crash — in another process:
+ * const record = readStoredRecord(readRecordFile('/var/footprint/orders.jsonl').entries);
+ * for (const log of record.logs.values()) if (!log.complete) console.log('never finished:', log.address);
+ * ```
+ */
+export type { FileSink, FileSinkOptions, RecordFile } from './lib/sinks/fileSink.js';
+export { DEFAULT_FILE_SINK_FLUSH_TIMEOUT_MS, DEFAULT_FILE_SINK_MAX_BYTES, DEFAULT_FILE_SINK_MAX_ENTRY_BYTES, DEFAULT_FILE_SINK_MAX_QUEUED_BYTES, fileSink, readRecordFile, } from './lib/sinks/fileSink.js';

package/dist/types/trace.d.ts

@@ -11,7 +11,7 @@ export { BRANCH_SEGMENT_MARKER, buildBranchSegment, hasBranchSegmentMarker, isBr
 export { BoundaryStateStore } from './lib/recorder/BoundaryStateStore.js';
 export type { ControlDecisionRecord, ControlDepRecorderOptions } from './lib/recorder/ControlDepRecorder.js';
 export { ControlDepRecorder, controlDepRecorder } from './lib/recorder/ControlDepRecorder.js';
-export type { InOutEntry, InOutPhase, InOutRecorderOptions } from './lib/recorder/InOutRecorder.js';
+export type { InOutAttempts, InOutEntry, InOutPhase, InOutRecorderOptions } from './lib/recorder/InOutRecorder.js';
 export { InOutRecorder, inOutRecorder, ROOT_RUNTIME_STAGE_ID, ROOT_SUBFLOW_ID } from './lib/recorder/InOutRecorder.js';
 export { KeyedStore } from './lib/recorder/KeyedStore.js';
 export type { QualityEntry, QualityRecorderOptions, QualityScoringFn } from './lib/recorder/QualityRecorder.js';
@@ -19,5 +19,5 @@ export { QualityRecorder } from './lib/recorder/QualityRecorder.js';
 export type { QualityFrame, QualityStackTrace } from './lib/recorder/qualityTrace.js';
 export { formatQualityTrace, qualityTrace } from './lib/recorder/qualityTrace.js';
 export { SequenceStore } from './lib/recorder/SequenceStore.js';
-export type { Topology, TopologyEdge, TopologyIncomingKind, TopologyNode, TopologyRecorderOptions, } from './lib/recorder/TopologyRecorder.js';
+export type { Topology, TopologyEdge, TopologyIncomingKind, TopologyNode, TopologyNodeKind, TopologyRecorderOptions, } from './lib/recorder/TopologyRecorder.js';
 export { TopologyRecorder, topologyRecorder } from './lib/recorder/TopologyRecorder.js';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "footprintjs",
-  "version": "10.0.1",
+  "version": "10.2.0",
   "description": "Explainable backend flows — automatic causal traces, decision evidence, and MCP tool generation for AI agents",
   "license": "MIT",
   "author": "Sanjay Krishna Anbalagan",
@@ -38,7 +38,7 @@
     "node": ">=22"
   },
   "scripts": {
-    "clean": "rm -rf build/* coverage dist node_modules package-lock.json",
+    "clean": "rm -rf build/* coverage dist node_modules",
     "build": "rm -rf dist && tsc && tsc -p tsconfig.esm.json && node scripts/postbuild-esm.mjs",
     "prepare": "husky",
     "watch": "tsc -w",
@@ -137,6 +137,16 @@
         "default": "./dist/detach.js"
       }
     },
+    "./sinks": {
+      "import": {
+        "types": "./dist/esm/sinks.d.ts",
+        "default": "./dist/esm/sinks.js"
+      },
+      "require": {
+        "types": "./dist/types/sinks.d.ts",
+        "default": "./dist/sinks.js"
+      }
+    },
     "./zod": {
       "import": {
         "types": "./dist/esm/zod.d.ts",
@@ -163,6 +173,9 @@
       "detach": [
         "./dist/types/detach.d.ts"
       ],
+      "sinks": [
+        "./dist/types/sinks.d.ts"
+      ],
       "zod": [
         "./dist/types/zod.d.ts"
       ]
@@ -176,7 +189,7 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "foottrace": "^1.0.0"
+    "foottrace": "^1.3.0"
   },
   "peerDependencies": {
     "zod": "^3.0.0 || ^4.0.0"
@@ -188,12 +201,12 @@
   },
   "devDependencies": {
     "@arethetypeswrong/cli": "^0.18.1",
-    "@typescript-eslint/eslint-plugin": "^5.61.0",
-    "@typescript-eslint/parser": "^5.61.0",
+    "@typescript-eslint/eslint-plugin": "^8.71.2",
+    "@typescript-eslint/parser": "^8.71.2",
     "@vitest/coverage-v8": "^4.1.8",
     "concurrently": "^8.0.1",
     "esbuild": "^0.28.0",
-    "eslint": "^8.44.0",
+    "eslint": "^8.57.1",
     "eslint-config-prettier": "^6.15.0",
     "eslint-config-standard": "^17.0.0",
     "eslint-import-resolver-typescript": "^3.5.2",
@@ -210,6 +223,7 @@
     "prettier": "^2.8.1",
     "publint": "^0.3.0",
     "semver": "^7.8.5",
+    "tsx": "^4.23.15",
     "typedoc": "^0.28.17",
     "typescript": "~5.4.5",
     "vitest": "^4.0.18",