foottrace 1.0.3 → 1.1.0

package/README.md

@@ -10,8 +10,8 @@ Foottrace owns the record layer used by footprintjs 10. Older stored records rem
 
 | Import | Responsibility |
 | --- | --- |
-| `foottrace` | Record types, runtime IDs, replay, time-travel cursors, causal and variable slices, honesty codes |
-| `foottrace/write` | `SharedMemory`, `EventLog`, `RecordFrame`, encoding and write types, writer-owned freezing |
+| `foottrace` | Record types, runtime and attempt IDs, replay, time-travel cursors, causal and variable slices, honesty codes, the stored-record reader |
+| `foottrace/write` | `SharedMemory`, `EventLog`, `RecordFrame`, encoding and write types, writer-owned freezing, the record sink port and `memorySink` |
 | `foottrace/paths` | Record-path encoding/decoding, nested access and safe diagnostic writes |
 
 Every declaration has one public entry point. There are no public deep imports or `/testing` entry point. FootPrint's engine, observer channels, recorders and stores remain in `footprintjs`.
@@ -42,6 +42,45 @@ Writers record during execution. Readers query what was recorded; they do not re
 
 See the [record contract](docs/guides/record-contract.md), [time-travel contract](src/lib/time-travel/README.md), and [slice contract](src/lib/slice/README.md).
 
+## A record that survives the run
+
+A log can also hand every entry to a sink **as it lands**, so a run that is killed still leaves its record behind. The sink sees four entries — `opened` (the base), `commit` (each bundle, after it is frozen), `note` (anything the writer wants kept beside the log, as it happens) and `closed` (how the log ended) — and `memorySink` is the reference adapter. Write your own for a file, a bucket or a table by implementing those four methods.
+
+```ts
+import { readStoredRecord, timeTravel } from 'foottrace';
+import { EventLog, RecordFrame, SharedMemory, memorySink } from 'foottrace/write';
+
+const sink = memorySink();
+const state = new SharedMemory(undefined, { count: 0 });
+const log = new EventLog(state.getState(), { sink, address: { logRunId: 'run-1', drillPath: [] } });
+const frame = new RecordFrame(state, log);
+frame.write(frame.at([], 'count'), 1, 'set');
+frame.commit(() => ({ stage: 'Increment', stageId: 'increment', runtimeStageId: 'increment#0' }));
+log.note('attempt', { attempt: 1, outcome: 'timeout' });
+// … the process dies here: no log.close('ok') …
+
+const run = readStoredRecord(sink.entries).root('run-1')!;
+run.complete; // false — the log never closed
+run.notes; // [{ kind: 'attempt', at, data: { attempt: 1, outcome: 'timeout' } }]
+timeTravel(run.source()).last(); // the cursor over what landed
+```
+
+A failing sink never stops the writer: a throw or a rejected promise is counted (`log.sinkFailures`) and reported to `sink.onFailure`. The reader treats what storage gives back as untrusted (`Iterable<unknown>`) and checks each entry: one it does not read into a log is listed in `unread` by name, and a commit sits at its own index, so a commit the store lost is a gap the fold reports by index — never a shifted log. `complete` means the writer closed the log and the reader read it all. Its work is bounded by four documented limits (`StoredRecordLimits`, raised per call). A sink adds nothing to the log's bytes; `meta` and a note's data are opaque, stored and handed back, never read. See [time travel](src/lib/time-travel/README.md#6-a-stored-record-reads-back--even-a-run-that-never-ended-110) and the [record contract](docs/guides/record-contract.md#a-stored-record).
+
+## Attempt IDs
+
+An attempt under a stage execution has its own ID: `charge#4@2` is attempt 2 of `charge#4`, and `charge#4@2.1@3` is attempt 3 of the first call that stage attempt made. Counts start at 1.
+
+```ts
+import { buildAttemptId, parseAttemptId } from 'foottrace';
+
+buildAttemptId('charge#4', 2, { ordinal: 1, attempt: 3 }); // 'charge#4@2.1@3'
+parseAttemptId('charge#4@2'); // { runtimeStageId: 'charge#4', attempt: 2 }
+parseAttemptId('charge#4'); // undefined — a stage execution, not an attempt
+```
+
+The parser reads from the right, so a stage ID may contain `@` or `.` and no character is newly reserved. See [ids/](src/lib/ids/README.md#attempt-ids-110).
+
 ## Paths are not interchangeable
 
 - `idPathSegments` (root entry) splits runtime IDs on `/` and drops empty segments. `isExecutionKey` detects `#`; it is not a complete validator.

package/dist/esm/index.d.ts

@@ -1,6 +1,8 @@
 /** Read a recorded execution: replay, time travel, slicing and attribution. */
 export type { CommitIdx, ExecutionCounter, ExecutionIndex, RuntimeStageId } from './lib/ids/runtimeStageId.js';
 export { buildRuntimeStageId, createExecutionCounter, parseRuntimeStageId, splitStageId, } from './lib/ids/runtimeStageId.js';
+export type { AttemptId } from './lib/ids/attemptId.js';
+export { buildAttemptId, parseAttemptId } from './lib/ids/attemptId.js';
 export { UnknownVerbError } from './lib/memory/verbs.js';
 export type { CommitBundle, MemoryPatch, TraceEntry } from './lib/memory/types.js';
 export type { ExecutionTree } from './lib/memory/types.js';
@@ -8,8 +10,9 @@ export { applySmartMerge } from './lib/memory/verbs.js';
 export type { ValueBasis, ValueBasisOptions, ValueWithBasis, WriterBasis, WriterWithBasis, } from './lib/memory/commitLogUtils.js';
 export { buildCommitIndex, commitIndexOf, commitValueAt, commitValueAtWithBasis, findCommit, findCommits, findLastWriter, findLastWriterWithBasis, inferLegacyPhases, recordsPhases, } from './lib/memory/commitLogUtils.js';
 export type { CommitPhase } from './lib/memory/types.js';
-export type { AxisRefusal, AxisSplit, BookendedAxis, FoldBasis, FoldedState, FoldSource, LogGap, Mark, Move, MoveRefusal, Stop, StopFilter, StopKind, TimeTravel, TimeTravelOptions, TimeTravelSource, TimeTravelStrategy, } from './lib/time-travel/index.js';
-export { commitStops, commitStopsStrategy, filterStops, isCommitBundle, splitAxis, stateAt, tagStops, timeTravel, } from './lib/time-travel/index.js';
+export type { AxisRefusal, AxisSplit, BookendedAxis, FoldBasis, FoldedState, FoldSource, LogGap, Mark, Move, MoveRefusal, Stop, StopFilter, StopKind, StoredLog, StoredNote, StoredRecord, StoredRecordLimits, TimeTravel, TimeTravelOptions, TimeTravelSource, TimeTravelStrategy, } from './lib/time-travel/index.js';
+export { commitStops, commitStopsStrategy, filterStops, isCommitBundle, readStoredRecord, splitAxis, stateAt, tagStops, timeTravel, } from './lib/time-travel/index.js';
+export type { LogOutcome, Meta } from './lib/memory/sink.js';
 export type { CausalChainOptions, CausalEdge, CausalNode, ControlDependency, ControlDepLookup, EdgeWeigher, KeysReadLookup, } from './lib/memory/backtrack.js';
 export { causalChain, flattenCausalDAG, formatCausalChain } from './lib/memory/backtrack.js';
 export type { UntrackedSource } from './lib/memory/types.js';

package/dist/esm/index.js

@@ -1,8 +1,9 @@
 export { buildRuntimeStageId, createExecutionCounter, parseRuntimeStageId, splitStageId, } from './lib/ids/runtimeStageId.js';
+export { buildAttemptId, parseAttemptId } from './lib/ids/attemptId.js';
 export { UnknownVerbError } from './lib/memory/verbs.js';
 export { applySmartMerge } from './lib/memory/verbs.js';
 export { buildCommitIndex, commitIndexOf, commitValueAt, commitValueAtWithBasis, findCommit, findCommits, findLastWriter, findLastWriterWithBasis, inferLegacyPhases, recordsPhases, } from './lib/memory/commitLogUtils.js';
-export { commitStops, commitStopsStrategy, filterStops, isCommitBundle, splitAxis, stateAt, tagStops, timeTravel, } from './lib/time-travel/index.js';
+export { commitStops, commitStopsStrategy, filterStops, isCommitBundle, readStoredRecord, splitAxis, stateAt, tagStops, timeTravel, } from './lib/time-travel/index.js';
 export { causalChain, flattenCausalDAG, formatCausalChain } from './lib/memory/backtrack.js';
 export { arrayProvenance, elementProvenance, formatForwardSlice, formatSlice, formatTimeline, forwardSliceForKey, forwardSliceToJSON, keysReadFromExecutionTree, keysReadFromMap, keyTimeline, resolveKeysReadSource, sliceForKey, sliceToJSON, } from './lib/slice/index.js';
 export { HONESTY_CODES } from './lib/memory/honesty.js';

package/dist/esm/lib/ids/attemptId.d.ts

@@ -0,0 +1,63 @@
+/**
+ * attemptId — the address of one attempt under a stage execution.
+ *
+ * Format:
+ *   <runtimeStageId>@<n>              attempt n of the stage execution      'charge#4@2'
+ *   <runtimeStageId>@<n>.<k>@<m>      attempt m of the k-th call made        'charge#4@2.1@3'
+ *                                     during stage attempt n
+ *
+ * Every number after the runtimeStageId is a positive integer, counted from 1: attempt 1 is the first
+ * try, call 1 the first call the stage attempt made. Written without leading zeros, so one attempt has
+ * one spelling and an id is a safe join key.
+ *
+ * PARSED FROM THE RIGHT. A runtimeStageId always ends in `#<execution index>`, and the suffix grammar
+ * holds no `#`, so the LAST `#` of an attempt id is its execution delimiter whatever the stage id
+ * contains — `@`, `.` and `~` stay legal in stage ids, and no byte is newly reserved (the id doors'
+ * refusal, FootPrint's `refuseReservedId`, is untouched). The delimiter is read from the grammar's one
+ * owner, `runtimeStageId.ts`.
+ *
+ * Imports nothing but the runtime-ID grammar: a leaf of the record, checked by the package fence.
+ *
+ * @example
+ * ```typescript
+ * buildAttemptId('charge#4', 2);                              // 'charge#4@2'
+ * buildAttemptId('charge#4', 2, { ordinal: 1, attempt: 3 });  // 'charge#4@2.1@3'
+ * parseAttemptId('sf/v1.2@x#7@3'); // { runtimeStageId: 'sf/v1.2@x#7', attempt: 3 }
+ * parseAttemptId('charge#4');      // undefined — a stage execution, not an attempt
+ * ```
+ */
+import { type RuntimeStageId } from './runtimeStageId.js';
+declare const ATTEMPT_ID: unique symbol;
+/** A `<runtimeStageId>@<n>[.<k>@<m>]` string the grammar produced. Assignable to `string`. */
+export type AttemptId = string & {
+    readonly [ATTEMPT_ID]: true;
+};
+/**
+ * Build the id of one attempt.
+ *
+ * @param runtimeStageId The stage execution the attempt belongs to (`[subflowPath/]stageId#index`).
+ * @param attempt The stage attempt, from 1.
+ * @param call For an attempt of a call made inside the stage attempt: the call's `ordinal` (1 for the
+ *   first call that stage attempt made) and its own `attempt` (from 1).
+ * @throws TypeError when `runtimeStageId` does not end in `#<execution index>`, and RangeError when a
+ *   count is not a positive integer — what `parseAttemptId` could not give back is never written.
+ */
+export declare function buildAttemptId(runtimeStageId: string, attempt: number, call?: {
+    readonly ordinal: number;
+    readonly attempt: number;
+}): AttemptId;
+/**
+ * Parse an attempt id into its parts, or `undefined` when `id` is not one (a bare runtimeStageId, a
+ * count of 0, a leading zero, a missing part). Never throws.
+ *
+ * `parseAttemptId(buildAttemptId(...parts))` gives the parts back, whatever the stage id contains.
+ */
+export declare function parseAttemptId(id: string): {
+    runtimeStageId: RuntimeStageId;
+    attempt: number;
+    call?: {
+        ordinal: number;
+        attempt: number;
+    };
+} | undefined;
+export {};

package/dist/esm/lib/ids/attemptId.js

@@ -0,0 +1,91 @@
+/**
+ * attemptId — the address of one attempt under a stage execution.
+ *
+ * Format:
+ *   <runtimeStageId>@<n>              attempt n of the stage execution      'charge#4@2'
+ *   <runtimeStageId>@<n>.<k>@<m>      attempt m of the k-th call made        'charge#4@2.1@3'
+ *                                     during stage attempt n
+ *
+ * Every number after the runtimeStageId is a positive integer, counted from 1: attempt 1 is the first
+ * try, call 1 the first call the stage attempt made. Written without leading zeros, so one attempt has
+ * one spelling and an id is a safe join key.
+ *
+ * PARSED FROM THE RIGHT. A runtimeStageId always ends in `#<execution index>`, and the suffix grammar
+ * holds no `#`, so the LAST `#` of an attempt id is its execution delimiter whatever the stage id
+ * contains — `@`, `.` and `~` stay legal in stage ids, and no byte is newly reserved (the id doors'
+ * refusal, FootPrint's `refuseReservedId`, is untouched). The delimiter is read from the grammar's one
+ * owner, `runtimeStageId.ts`.
+ *
+ * Imports nothing but the runtime-ID grammar: a leaf of the record, checked by the package fence.
+ *
+ * @example
+ * ```typescript
+ * buildAttemptId('charge#4', 2);                              // 'charge#4@2'
+ * buildAttemptId('charge#4', 2, { ordinal: 1, attempt: 3 });  // 'charge#4@2.1@3'
+ * parseAttemptId('sf/v1.2@x#7@3'); // { runtimeStageId: 'sf/v1.2@x#7', attempt: 3 }
+ * parseAttemptId('charge#4');      // undefined — a stage execution, not an attempt
+ * ```
+ */
+import { EXECUTION_DELIMITER } from './runtimeStageId.js';
+/**
+ * What follows the last `#`: the execution index, `@` and the attempt, then — for a call — `.`, the
+ * call's ordinal, `@` and the call's attempt. Counts are canonical positive integers.
+ */
+const AFTER_EXECUTION_DELIMITER = /^(\d+)@([1-9]\d*)(?:\.([1-9]\d*)@([1-9]\d*))?$/;
+const EXECUTION_INDEX = /^\d+$/;
+/** True when `id` ends in `#<digits>` — the one shape every runtimeStageId has. */
+function endsInExecutionIndex(id) {
+    const at = id.lastIndexOf(EXECUTION_DELIMITER);
+    return at !== -1 && EXECUTION_INDEX.test(id.slice(at + 1));
+}
+/** Refuse a count the parser could not give back: a positive safe integer, or a `RangeError`. */
+function requireCount(name, value) {
+    if (!Number.isSafeInteger(value) || value < 1) {
+        throw new RangeError(`buildAttemptId: ${name} must be a positive integer (counted from 1), got ${String(value)}`);
+    }
+}
+/**
+ * Build the id of one attempt.
+ *
+ * @param runtimeStageId The stage execution the attempt belongs to (`[subflowPath/]stageId#index`).
+ * @param attempt The stage attempt, from 1.
+ * @param call For an attempt of a call made inside the stage attempt: the call's `ordinal` (1 for the
+ *   first call that stage attempt made) and its own `attempt` (from 1).
+ * @throws TypeError when `runtimeStageId` does not end in `#<execution index>`, and RangeError when a
+ *   count is not a positive integer — what `parseAttemptId` could not give back is never written.
+ */
+export function buildAttemptId(runtimeStageId, attempt, call) {
+    if (typeof runtimeStageId !== 'string' || !endsInExecutionIndex(runtimeStageId)) {
+        throw new TypeError(`buildAttemptId: ${JSON.stringify(runtimeStageId)} is not a runtimeStageId (it must end in #<execution index>)`);
+    }
+    requireCount('attempt', attempt);
+    if (call === undefined)
+        return `${runtimeStageId}@${attempt}`;
+    requireCount('call ordinal', call.ordinal);
+    requireCount('call attempt', call.attempt);
+    return `${runtimeStageId}@${attempt}.${call.ordinal}@${call.attempt}`;
+}
+/**
+ * Parse an attempt id into its parts, or `undefined` when `id` is not one (a bare runtimeStageId, a
+ * count of 0, a leading zero, a missing part). Never throws.
+ *
+ * `parseAttemptId(buildAttemptId(...parts))` gives the parts back, whatever the stage id contains.
+ */
+export function parseAttemptId(id) {
+    if (typeof id !== 'string')
+        return undefined;
+    const at = id.lastIndexOf(EXECUTION_DELIMITER);
+    if (at === -1)
+        return undefined;
+    const parts = AFTER_EXECUTION_DELIMITER.exec(id.slice(at + 1));
+    if (!parts)
+        return undefined;
+    const [, index, attempt, ordinal, callAttempt] = parts;
+    const counts = [attempt, ordinal, callAttempt].filter((n) => n !== undefined).map(Number);
+    if (!counts.every(Number.isSafeInteger))
+        return undefined;
+    const runtimeStageId = id.slice(0, at + 1 + index.length);
+    if (ordinal === undefined)
+        return { runtimeStageId, attempt: counts[0] };
+    return { runtimeStageId, attempt: counts[0], call: { ordinal: counts[1], attempt: counts[2] } };
+}

package/dist/esm/lib/memory/EventLog.d.ts

@@ -24,8 +24,20 @@
  * contract for state) and a `SharedArrayBuffer` (every copy shares its memory). A frozen RegExp's
  * `lastIndex` is read-only, so a `/g` or `/y` regex read from a bundle throws when `exec` or
  * `replace` advance it.
+ *
+ * A SINK (1.1.0, optional). `new EventLog(base, { sink, address, meta? })` also hands every entry to a
+ * `RecordSink` AS IT LANDS (`sink.ts`): `opened` from the constructor (the base, as the sink's own
+ * copy), `commit` from `record` after the bundle is frozen and appended (the bundle as served),
+ * `note` from `note`, `closed` from `close`. The log's own record never depends on the sink: the
+ * bundle is in `steps` before the sink sees it, and nothing the sink does reaches the writer — a
+ * throw, a rejected promise or an entry the log refuses to send (a `note` whose data is not a plain
+ * object that survives `structuredClone`) is counted (`sinkFailures`) and reported to
+ * `sink.onFailure`, and the writer goes on; a `meta` that will not copy is lost on its own and its
+ * entry still goes. Without a sink, nothing here runs: the one-argument log writes the same bytes,
+ * and has the same own fields, it always did.
  */
 import type { EmitSourcePosition, LogAddress } from './eventPosition.js';
+import { type LogOutcome, type Meta, type RecordSink } from './sink.js';
 import type { CommitBundle } from './types.js';
 export declare class EventLog {
     /** Base snapshot BEFORE the first stage mutates anything. */
@@ -34,7 +46,26 @@ export declare class EventLog {
     private steps;
     private sourceAddress?;
     private sourceAddressRetired;
-    constructor(initialMemory: any);
+    /** Where entries go as they land; absent for the one-argument log. */
+    private readonly sink?;
+    /** Entries the sink did not take; set with the sink. */
+    private lostEntries?;
+    /** True while `onFailure` runs (until its promise settles): a loss it causes is counted, not reported again. */
+    private reporting?;
+    /**
+     * @param initialMemory The fold base — the state before the first commit (copied).
+     * @param options With a `sink`: every entry goes to it as it lands, under `address` — which also
+     *   becomes this log's {@link address} — and `meta` rides the `opened` entry. The sink is told
+     *   `opened` before the constructor returns.
+     * @throws TypeError when `options` names no sink, a malformed address, or a base that is not a plain
+     *   object (the `opened` entry carries it) — a writer's mistake, refused at the door. Nothing the sink
+     *   itself does is ever thrown.
+     */
+    constructor(initialMemory: any, options?: {
+        readonly sink: RecordSink;
+        readonly address: LogAddress;
+        readonly meta?: Meta;
+    });
     /**
      * The fold BASE — the state as it stood before the first commit.
      *
@@ -78,6 +109,53 @@ export declare class EventLog {
      * will no longer edit — its own object is the one frozen.
      */
     record(bundle: CommitBundle): void;
+    /**
+     * Note something beside the log, in the sink, as it happens — for evidence that must survive a run
+     * that never closes (an attempt that ended, before the next one starts). `kind` and `data` are the
+     * writer's: opaque to the record. Notes never enter the log's bundles, so the log's bytes are the
+     * same with or without them. Without a sink, nothing happens.
+     *
+     * Never throws: a `kind` that is not a string, `data` that is not a plain object surviving
+     * `structuredClone`, or a sink that fails is counted in {@link sinkFailures} and reported to
+     * `sink.onFailure`. The sink keeps its own copy of `data`.
+     */
+    note(kind: string, data: Meta): void;
+    /**
+     * Tell the sink this log ended — `outcome` and, for the reader's check that the stored log is
+     * whole, how many commits it holds now. `meta` rides the entry, copied. Without a sink, nothing
+     * happens. The log itself stays as it is: a later `record` still lands, and still reaches the sink
+     * (a reader then reads the log as not complete until it is closed again).
+     *
+     * Never throws: an unknown outcome, a `meta` that is not a plain object surviving `structuredClone`,
+     * or a sink that fails is counted in {@link sinkFailures} and reported to `sink.onFailure`.
+     */
+    close(outcome: LogOutcome, meta?: Meta): void;
+    /**
+     * How many entries the sink did not take: a sink method that threw or whose promise rejected, and an
+     * entry the log refused to send — plus each `meta` the log could not copy (that entry went without
+     * it). Counted as each happens (a rejection, when it settles); 0 without a sink. The stored record
+     * says the same from its side: a missing commit is a gap.
+     */
+    get sinkFailures(): number;
+    /**
+     * One entry to the sink. Nothing here reaches the writer: a refusal, a throw or a rejection is a lost
+     * entry; a `meta` that cannot be copied is lost on its own — counted and reported — and the entry goes
+     * without it.
+     */
+    private send;
+    /**
+     * Count the rejection of an adapter's promise once. A native promise is watched through the real
+     * `Promise.prototype.then` (an own `then` on it is not trusted); any other thenable is adopted into a
+     * fresh promise first, whose settling functions run once. Either way the rejection is handled.
+     */
+    private watch;
+    /**
+     * Count a lost entry and tell the sink's `onFailure`, if it listens; a report that fails is ignored.
+     * A loss caused while `onFailure` runs — until the promise it returns settles, when it returns one —
+     * (it wrote to this log again, through the same failing sink) is counted and not reported again: one
+     * report deep, never a runaway.
+     */
+    private lost;
     /**
      * Every recorded commit bundle, AS SERVED (9.44.2): a new array each call; a bundle freezing sealed
      * whole is the log's own (frozen) object, one holding a Date, Map, buffer … is a copy of its open
@@ -94,12 +172,20 @@ export declare class EventLog {
     recorded(): CommitBundle[];
     /** Number of recorded commits. */
     get length(): number;
-    /** Immutable identity of this log, absent until the engine binds it. */
+    /**
+     * Immutable identity of this log: the sink's address when the log was built with one, otherwise
+     * absent until the engine binds it.
+     */
     get address(): LogAddress | undefined;
     /** @internal Bind once; resuming the same log must not rename its earlier positions. */
     bindAddress(logRunId: string, drillPath: readonly string[]): void;
     /** O(1) source-time capture. No counter, observer bookkeeping, or future commit prediction. */
     capturePosition(runId: string): EmitSourcePosition | undefined;
-    /** Wipes history (useful for test resets). */
+    /**
+     * Wipes history (useful for test resets).
+     *
+     * @throws Error on a log built with a sink: what the sink stored cannot be wiped, and a second
+     *   history under the same address would read back as one corrupted log. Start a fresh EventLog.
+     */
     clear(): void;
 }

package/dist/esm/lib/memory/EventLog.js

@@ -24,9 +24,92 @@
  * contract for state) and a `SharedArrayBuffer` (every copy shares its memory). A frozen RegExp's
  * `lastIndex` is read-only, so a `/g` or `/y` regex read from a bundle throws when `exec` or
  * `replace` advance it.
+ *
+ * A SINK (1.1.0, optional). `new EventLog(base, { sink, address, meta? })` also hands every entry to a
+ * `RecordSink` AS IT LANDS (`sink.ts`): `opened` from the constructor (the base, as the sink's own
+ * copy), `commit` from `record` after the bundle is frozen and appended (the bundle as served),
+ * `note` from `note`, `closed` from `close`. The log's own record never depends on the sink: the
+ * bundle is in `steps` before the sink sees it, and nothing the sink does reaches the writer — a
+ * throw, a rejected promise or an entry the log refuses to send (a `note` whose data is not a plain
+ * object that survives `structuredClone`) is counted (`sinkFailures`) and reported to
+ * `sink.onFailure`, and the writer goes on; a `meta` that will not copy is lost on its own and its
+ * entry still goes. Without a sink, nothing here runs: the one-argument log writes the same bytes,
+ * and has the same own fields, it always did.
  */
 import { freezeRecord, serveRecord } from '../capture/freeze.js';
+import { isEntryObject, LOG_OUTCOMES, sendEntry, } from './sink.js';
 import { applySmartMergeInto } from './utils.js';
+/** True when `value` has a callable `then` — an adapter that answered with a promise. */
+function isThenable(value) {
+    return ((typeof value === 'object' || typeof value === 'function') &&
+        value !== null &&
+        typeof value.then === 'function');
+}
+/**
+ * The address, copied segment by segment and frozen — the log's identity cannot be edited through the
+ * caller's object, and a path with a hole or a non-string segment is refused rather than copied as one.
+ */
+function frozenAddress(address) {
+    const { logRunId, drillPath } = (address ?? {});
+    const refused = () => new TypeError('EventLog: a sink needs an address — { logRunId: string, drillPath: string[] }');
+    if (typeof logRunId !== 'string' || !Array.isArray(drillPath))
+        throw refused();
+    const segments = [];
+    for (let i = 0; i < drillPath.length; i++) {
+        const segment = drillPath[i];
+        if (typeof segment !== 'string')
+            throw refused();
+        segments.push(segment);
+    }
+    return Object.freeze({ logRunId, drillPath: Object.freeze(segments) });
+}
+/** A writer's payload as the sink keeps it: a plain object, copied — or a `TypeError` naming `field`. */
+function copiedPayload(value, field) {
+    if (!isEntryObject(value))
+        throw new TypeError(`EventLog: ${field} must be a plain object`);
+    return structuredClone(value);
+}
+/**
+ * The entry with its `meta` copied — or, when `meta` cannot be copied, the entry WITHOUT it and the
+ * error: the structural facts (the base, how the log ended, its length) still go; only `meta` is lost.
+ */
+function withCopiedMeta(entry) {
+    if (entry.meta === undefined)
+        return { ready: entry };
+    try {
+        return { ready: { ...entry, meta: copiedPayload(entry.meta, 'meta') } };
+    }
+    catch (error) {
+        const { meta: _dropped, ...rest } = entry;
+        return { ready: rest, dropped: error };
+    }
+}
+/**
+ * The entry as the sink may keep it: a payload checked and copied (the writer keeps its own object),
+ * the bundle served. `dropped` is a `meta` that could not be copied (the entry goes without it). Throws
+ * when the entry itself cannot be sent; the caller counts it as a lost entry.
+ */
+function detached(entry) {
+    switch (entry.kind) {
+        case 'opened':
+            return withCopiedMeta(entry);
+        case 'commit':
+            return { ready: { ...entry, bundle: serveRecord(entry.bundle) } };
+        case 'note':
+            if (typeof entry.note !== 'string')
+                throw new TypeError('EventLog.note: kind must be a string');
+            return { ready: { ...entry, data: copiedPayload(entry.data, 'note data') } };
+        case 'closed':
+            if (!LOG_OUTCOMES.includes(entry.outcome)) {
+                throw new TypeError(`EventLog.close: outcome must be ${LOG_OUTCOMES.join(', ')}`);
+            }
+            return withCopiedMeta(entry);
+    }
+}
+/** Swallows a rejection nobody waits for. */
+function ignore() {
+    // A failure report that fails changes nothing: the loss is already counted.
+}
 export class EventLog {
     /** Base snapshot BEFORE the first stage mutates anything. */
     base;
@@ -34,12 +117,39 @@ export class EventLog {
     steps = [];
     sourceAddress;
     sourceAddressRetired = false;
-    constructor(initialMemory) {
+    /**
+     * @param initialMemory The fold base — the state before the first commit (copied).
+     * @param options With a `sink`: every entry goes to it as it lands, under `address` — which also
+     *   becomes this log's {@link address} — and `meta` rides the `opened` entry. The sink is told
+     *   `opened` before the constructor returns.
+     * @throws TypeError when `options` names no sink, a malformed address, or a base that is not a plain
+     *   object (the `opened` entry carries it) — a writer's mistake, refused at the door. Nothing the sink
+     *   itself does is ever thrown.
+     */
+    constructor(initialMemory, options) {
         // Normalised to an object: the base is a STATE, and every fold over it
         // (`materialise`, `stateAt`) applies path writes to it. `undefined` —
         // what a run with no `initialContext` used to store here — made every
         // one of those folds throw on the first `set`.
         this.base = initialMemory === undefined ? {} : structuredClone(initialMemory);
+        if (options === undefined)
+            return;
+        if (!isEntryObject(options.sink))
+            throw new TypeError('EventLog: options.sink must be a RecordSink');
+        if (!isEntryObject(this.base)) {
+            throw new TypeError('EventLog: a log that writes to a sink needs a plain-object base — its opened entry carries it');
+        }
+        const address = frozenAddress(options.address);
+        this.sourceAddress = address;
+        this.sink = options.sink;
+        this.lostEntries = 0;
+        this.send({
+            kind: 'opened',
+            address,
+            at: Date.now(),
+            initialState: this.getInitialState(),
+            ...(options.meta === undefined ? {} : { meta: options.meta }),
+        });
     }
     /**
      * The fold BASE — the state as it stood before the first commit.
@@ -96,6 +206,124 @@ export class EventLog {
         bundle.idx = this.steps.length;
         freezeRecord(bundle, 'indices');
         this.steps.push(bundle);
+        if (this.sink !== undefined)
+            this.send({ kind: 'commit', address: this.sourceAddress, at: Date.now(), bundle });
+    }
+    /**
+     * Note something beside the log, in the sink, as it happens — for evidence that must survive a run
+     * that never closes (an attempt that ended, before the next one starts). `kind` and `data` are the
+     * writer's: opaque to the record. Notes never enter the log's bundles, so the log's bytes are the
+     * same with or without them. Without a sink, nothing happens.
+     *
+     * Never throws: a `kind` that is not a string, `data` that is not a plain object surviving
+     * `structuredClone`, or a sink that fails is counted in {@link sinkFailures} and reported to
+     * `sink.onFailure`. The sink keeps its own copy of `data`.
+     */
+    note(kind, data) {
+        if (this.sink === undefined)
+            return;
+        this.send({ kind: 'note', address: this.sourceAddress, at: Date.now(), note: kind, data });
+    }
+    /**
+     * Tell the sink this log ended — `outcome` and, for the reader's check that the stored log is
+     * whole, how many commits it holds now. `meta` rides the entry, copied. Without a sink, nothing
+     * happens. The log itself stays as it is: a later `record` still lands, and still reaches the sink
+     * (a reader then reads the log as not complete until it is closed again).
+     *
+     * Never throws: an unknown outcome, a `meta` that is not a plain object surviving `structuredClone`,
+     * or a sink that fails is counted in {@link sinkFailures} and reported to `sink.onFailure`.
+     */
+    close(outcome, meta) {
+        if (this.sink === undefined)
+            return;
+        this.send({
+            kind: 'closed',
+            address: this.sourceAddress,
+            at: Date.now(),
+            outcome,
+            commits: this.steps.length,
+            ...(meta === undefined ? {} : { meta }),
+        });
+    }
+    /**
+     * How many entries the sink did not take: a sink method that threw or whose promise rejected, and an
+     * entry the log refused to send — plus each `meta` the log could not copy (that entry went without
+     * it). Counted as each happens (a rejection, when it settles); 0 without a sink. The stored record
+     * says the same from its side: a missing commit is a gap.
+     */
+    get sinkFailures() {
+        return this.lostEntries ?? 0;
+    }
+    /**
+     * One entry to the sink. Nothing here reaches the writer: a refusal, a throw or a rejection is a lost
+     * entry; a `meta` that cannot be copied is lost on its own — counted and reported — and the entry goes
+     * without it.
+     */
+    send(entry) {
+        const sink = this.sink;
+        if (sink === undefined)
+            return;
+        let sent = entry;
+        try {
+            const { ready, dropped } = detached(entry);
+            sent = Object.freeze(ready);
+            if (dropped !== undefined)
+                this.lost(sink, entry, dropped);
+            const returned = sendEntry(sink, sent);
+            if (isThenable(returned))
+                this.watch(sink, sent, returned);
+        }
+        catch (error) {
+            this.lost(sink, sent, error);
+        }
+    }
+    /**
+     * Count the rejection of an adapter's promise once. A native promise is watched through the real
+     * `Promise.prototype.then` (an own `then` on it is not trusted); any other thenable is adopted into a
+     * fresh promise first, whose settling functions run once. Either way the rejection is handled.
+     */
+    watch(sink, entry, returned) {
+        let counted = false;
+        const onRejected = (error) => {
+            if (counted)
+                return;
+            counted = true;
+            this.lost(sink, entry, error);
+        };
+        if (returned instanceof Promise)
+            Promise.prototype.then.call(returned, undefined, onRejected);
+        else
+            new Promise((resolve) => resolve(returned)).then(undefined, onRejected);
+    }
+    /**
+     * Count a lost entry and tell the sink's `onFailure`, if it listens; a report that fails is ignored.
+     * A loss caused while `onFailure` runs — until the promise it returns settles, when it returns one —
+     * (it wrote to this log again, through the same failing sink) is counted and not reported again: one
+     * report deep, never a runaway.
+     */
+    lost(sink, entry, error) {
+        this.lostEntries = (this.lostEntries ?? 0) + 1;
+        if (this.reporting === true)
+            return;
+        this.reporting = true;
+        let pending = false;
+        try {
+            const reported = sink.onFailure?.({ entry, error });
+            if (isThenable(reported)) {
+                pending = true;
+                const done = () => {
+                    this.reporting = false;
+                };
+                new Promise((resolve) => resolve(reported)).then(done, done);
+            }
+        }
+        catch {
+            ignore();
+        }
+        finally {
+            if (!pending)
+                this.reporting = false;
+        }
     }
     /**
      * Every recorded commit bundle, AS SERVED (9.44.2): a new array each call; a bundle freezing sealed
@@ -119,7 +347,10 @@ export class EventLog {
     get length() {
         return this.steps.length;
     }
-    /** Immutable identity of this log, absent until the engine binds it. */
+    /**
+     * Immutable identity of this log: the sink's address when the log was built with one, otherwise
+     * absent until the engine binds it.
+     */
     get address() {
         return this.sourceAddress;
     }
@@ -135,8 +366,16 @@ export class EventLog {
             return undefined;
         return Object.freeze({ runId, ...this.sourceAddress, committedThroughIdx: this.steps.length - 1 });
     }
-    /** Wipes history (useful for test resets). */
+    /**
+     * Wipes history (useful for test resets).
+     *
+     * @throws Error on a log built with a sink: what the sink stored cannot be wiped, and a second
+     *   history under the same address would read back as one corrupted log. Start a fresh EventLog.
+     */
     clear() {
+        if (this.sink !== undefined) {
+            throw new Error('EventLog.clear: this log writes to a sink, and a stored record cannot be wiped — use a new EventLog');
+        }
         this.steps = [];
         // A reset prefix cannot reuse old coordinates, even if another stage of
         // the SAME leg binds it again. Keep clear's data behavior, but retire