foottrace 1.0.3 → 1.2.0

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

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

@@ -23,10 +23,11 @@
  *     alias of `foottrace` that is a union of string literals: each one is inside the
  *     registry or is named, with its reason, as not an honesty vocabulary.
  *
- * NO OBJECT GAINS A FIELD from being registered. Three signals carry no code of their own — a
- * `LogGap` (`'log-gap'`), `CausalNode.incompleteSources` (`'incomplete-sources'`) and
- * `FoldedState.redacted` / `redactedPaths` (`'redacted'`) — and a `truncated: { byDepth, byNodes }`
- * field means `'truncated'`; they are registered so a reader explains them from the same place.
+ * NO OBJECT GAINS A FIELD from being registered. Four signals carry no code of their own — a
+ * `LogGap` (`'log-gap'`), `CausalNode.incompleteSources` (`'incomplete-sources'`),
+ * `FoldedState.redacted` / `redactedPaths` (`'redacted'`) and an entry of `StoredRecord.unread`
+ * (`'unread-entry'`, 1.1.0) — and a `truncated: { byDepth, byNodes }` field means `'truncated'`; they
+ * are registered so a reader explains them from the same place.
  *
  * NOT HERE: the two strings a redaction leaves where a value was. The engine writes those on every
  * redacted run; the log's lives in its own leaf, `memory/placeholders.ts` (the scope channel's with
@@ -75,6 +76,7 @@ export declare const HONESTY_CODES: Readonly<{
     'initial+log': string;
     'log-only': string;
     'log-gap': string;
+    'unread-entry': string;
     'incomplete-sources': string;
     redacted: string;
     deleted: string;

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

@@ -23,10 +23,11 @@
  *     alias of `foottrace` that is a union of string literals: each one is inside the
  *     registry or is named, with its reason, as not an honesty vocabulary.
  *
- * NO OBJECT GAINS A FIELD from being registered. Three signals carry no code of their own — a
- * `LogGap` (`'log-gap'`), `CausalNode.incompleteSources` (`'incomplete-sources'`) and
- * `FoldedState.redacted` / `redactedPaths` (`'redacted'`) — and a `truncated: { byDepth, byNodes }`
- * field means `'truncated'`; they are registered so a reader explains them from the same place.
+ * NO OBJECT GAINS A FIELD from being registered. Four signals carry no code of their own — a
+ * `LogGap` (`'log-gap'`), `CausalNode.incompleteSources` (`'incomplete-sources'`),
+ * `FoldedState.redacted` / `redactedPaths` (`'redacted'`) and an entry of `StoredRecord.unread`
+ * (`'unread-entry'`, 1.1.0) — and a `truncated: { byDepth, byNodes }` field means `'truncated'`; they
+ * are registered so a reader explains them from the same place.
  *
  * NOT HERE: the two strings a redaction leaves where a value was. The engine writes those on every
  * redacted run; the log's lives in its own leaf, `memory/placeholders.ts` (the scope channel's with
@@ -81,6 +82,8 @@ export const HONESTY_CODES = /* @__PURE__ */ Object.freeze({
     'log-only': 'No initialState travelled with this log (a snapshot stored before 9.17, a redacted snapshot or a hand-built log), so the fold started from an empty object: a key seeded before the run is whole only once a commit since wrote its whole value, and until then it holds just what its merges, appends and nested writes added, or nothing.',
     // ── a row of a stored log that is not a commit bundle — `LogGap` ──────────
     'log-gap': 'A row of the stored log could not be read as a commit bundle, so it keeps its index but contributes no state, and any fold that crosses it is missing whatever that row wrote.',
+    // ── an entry a sink stored that no log could hold — `StoredRecord.unread` (1.1.0) ─
+    'unread-entry': "An entry a sink stored was not read into any log (it could not be read as an opened, commit, note or closed entry, it lay past one of the reader's limits, or another entry holds its place), so whatever it said (a base, a commit, a note or how the log ended) is not in the record read back.",
     // ── untracked reads a stage also consumed — `CausalNode.incompleteSources` ─
     'incomplete-sources': 'The stage also consumed read paths that bypass read tracking (args, env or an unshadowed silent read), so a slice through it may be incomplete: those reads produce no read-to-write edge to follow.',
     // ── values scrubbed at write time — `FoldedState.redacted` / `redactedPaths`, a value basis ─

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

@@ -0,0 +1,148 @@
+/**
+ * sink.ts — the record's sink port: where a log's entries go AS THEY LAND, so a run that never ends
+ * still leaves its record behind.
+ *
+ * A log that is given a sink (`new EventLog(base, { sink, address })`) hands it four kinds of entry,
+ * each stamped with the log's address and the time it was written (`at`, epoch ms):
+ *
+ *   - `opened` — once, from the constructor: the fold base (`initialState`, the sink's own copy);
+ *   - `commit` — per `record()`, AFTER the bundle is frozen: the log's own bundle, as served;
+ *   - `note`   — per `note(kind, data)`: something the writer wants kept beside the log, as it happens;
+ *   - `closed` — per `close(outcome)`: how the log ended, and how many commits it held then (`commits`).
+ *
+ * These are RECORD facts. What the writer means by them rides `meta` (on `opened` / `closed`) and a
+ * note's `kind` and `data`: opaque here — stored and handed back, never read or interpreted. Nothing in
+ * this file names an engine.
+ *
+ * THE STORED FORM. A sink stores each entry as a {@link RecordEntry}: the method's entry plus the
+ * method's name as `kind`. A note's own kind cannot also be called `kind`, so it is stored as `note`.
+ * `memorySink` is the reference adapter; `readStoredRecord` (`foottrace`) reads the entries back.
+ *
+ * @example
+ * ```typescript
+ * import { EventLog, memorySink } from 'foottrace/write';
+ * import { readStoredRecord } from 'foottrace';
+ *
+ * const sink = memorySink();
+ * const log = new EventLog({ count: 0 }, { sink, address: { logRunId: 'run-1', drillPath: [] } });
+ * log.note('attempt', { attempt: 1, outcome: 'failed' });
+ * // … the process dies here: no `closed` entry …
+ * readStoredRecord(sink.entries).root('run-1')?.complete; // false — and its note is still there
+ * ```
+ */
+import type { LogAddress } from './eventPosition.js';
+import type { CommitBundle } from './types.js';
+/**
+ * What a writer puts beside the record — on a log's `opened` / `closed` entry, or as a note's data.
+ * A plain object that survives `structuredClone`; opaque to foottrace: stored and returned, never read.
+ */
+export type Meta = Readonly<Record<string, unknown>>;
+/** How a log's writer said it ended. A pause ends this log; it is not a failure. */
+export type LogOutcome = 'ok' | 'failed' | 'paused';
+/** The outcomes a `closed` entry may carry, in one place for the writer's and the reader's checks. */
+export declare const LOG_OUTCOMES: readonly LogOutcome[];
+/**
+ * One stored entry: what a sink keeps per call, discriminated by `kind` (the method that received it).
+ * A note's own kind is stored as `note`.
+ */
+export type RecordEntry = {
+    readonly kind: 'opened';
+    readonly address: LogAddress;
+    readonly at: number;
+    /** The fold base — the state before the log's first commit. */
+    readonly initialState: Record<string, unknown>;
+    readonly meta?: Meta;
+} | {
+    readonly kind: 'commit';
+    readonly address: LogAddress;
+    readonly at: number;
+    /** The log's own bundle, frozen, its position stamped as `idx`. */
+    readonly bundle: CommitBundle;
+} | {
+    readonly kind: 'note';
+    readonly address: LogAddress;
+    readonly at: number;
+    /** The note's own kind, as the writer named it (`note('attempt', …)` → `'attempt'`). */
+    readonly note: string;
+    readonly data: Meta;
+} | {
+    readonly kind: 'closed';
+    readonly address: LogAddress;
+    readonly at: number;
+    readonly outcome: LogOutcome;
+    /** The log's length when it closed — how many commits the stored log must hold to be whole. */
+    readonly commits: number;
+    readonly meta?: Meta;
+};
+/**
+ * Where a log's entries go as they land — the port an adapter implements (memory, a file, S3, a table).
+ *
+ * Every method is called synchronously from the writer; an adapter that writes somewhere slow queues
+ * the entry and drains in `flush`. A method may throw, or return a promise that rejects: the log
+ * counts it (`EventLog · sinkFailures`), reports it to `onFailure`, and goes on — a failing sink never
+ * stops the writer. The entries an adapter is handed are its to keep: the bundle is frozen and shared
+ * with the log, everything else is the adapter's own copy.
+ */
+export interface RecordSink {
+    /** A log opened at `address` with its fold base. Called once, from the log's constructor. */
+    opened(entry: {
+        readonly address: LogAddress;
+        readonly at: number;
+        readonly initialState: Record<string, unknown>;
+        readonly meta?: Meta;
+    }): void;
+    /** A bundle landed in the log at `address` (its position is `bundle.idx`). */
+    commit(entry: {
+        readonly address: LogAddress;
+        readonly at: number;
+        readonly bundle: CommitBundle;
+    }): void;
+    /** The writer noted something beside the log — `kind` and `data` are opaque. */
+    note(entry: {
+        readonly address: LogAddress;
+        readonly at: number;
+        readonly kind: string;
+        readonly data: Meta;
+    }): void;
+    /** The log at `address` closed with `outcome`, holding `commits` bundles. */
+    closed(entry: {
+        readonly address: LogAddress;
+        readonly at: number;
+        readonly outcome: LogOutcome;
+        readonly commits: number;
+        readonly meta?: Meta;
+    }): void;
+    /** Drain whatever the adapter queued. The log never calls it; whoever owns the sink does. */
+    flush?(): Promise<void>;
+    /** Told of every entry this sink did not take — the entry and what went wrong. A throw here is ignored. */
+    onFailure?(failure: {
+        readonly entry: RecordEntry;
+        readonly error: unknown;
+    }): void;
+}
+/** A plain object — not null, not an array, not a primitive. */
+export declare function isEntryObject(value: unknown): value is Record<string, unknown>;
+/**
+ * Hand `entry` to the sink's method for its kind, as that method's entry; returns what the method
+ * returned (a promise from an async adapter). Throws whatever the method throws — the log catches.
+ */
+export declare function sendEntry(sink: RecordSink, entry: RecordEntry): unknown;
+/**
+ * A sink that keeps every entry in memory, in arrival order — the reference adapter: what any adapter
+ * must give back for `readStoredRecord` to read the same record. `entries` is a new array on each read.
+ * What it keeps is frozen as far as freezing reaches — the base, `meta` and a note's `data` are the
+ * copies a log hands it, and the bundle is already frozen — so no reader can rewrite its containers. A
+ * Date's time, a Map's or Set's entries and a buffer's bytes are not sealed by freezing (`deepFreeze`'s
+ * stated limit). A caller that hands it objects directly hands them over: they are frozen in place.
+ *
+ * @example
+ * ```typescript
+ * const sink = memorySink();
+ * const log = new EventLog({}, { sink, address: { logRunId: 'run-1', drillPath: [] } });
+ * log.close('ok');
+ * sink.entries.map((e) => e.kind); // ['opened', 'closed']
+ * ```
+ */
+export declare function memorySink(): RecordSink & {
+    readonly entries: readonly RecordEntry[];
+};

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

@@ -0,0 +1,92 @@
+/**
+ * sink.ts — the record's sink port: where a log's entries go AS THEY LAND, so a run that never ends
+ * still leaves its record behind.
+ *
+ * A log that is given a sink (`new EventLog(base, { sink, address })`) hands it four kinds of entry,
+ * each stamped with the log's address and the time it was written (`at`, epoch ms):
+ *
+ *   - `opened` — once, from the constructor: the fold base (`initialState`, the sink's own copy);
+ *   - `commit` — per `record()`, AFTER the bundle is frozen: the log's own bundle, as served;
+ *   - `note`   — per `note(kind, data)`: something the writer wants kept beside the log, as it happens;
+ *   - `closed` — per `close(outcome)`: how the log ended, and how many commits it held then (`commits`).
+ *
+ * These are RECORD facts. What the writer means by them rides `meta` (on `opened` / `closed`) and a
+ * note's `kind` and `data`: opaque here — stored and handed back, never read or interpreted. Nothing in
+ * this file names an engine.
+ *
+ * THE STORED FORM. A sink stores each entry as a {@link RecordEntry}: the method's entry plus the
+ * method's name as `kind`. A note's own kind cannot also be called `kind`, so it is stored as `note`.
+ * `memorySink` is the reference adapter; `readStoredRecord` (`foottrace`) reads the entries back.
+ *
+ * @example
+ * ```typescript
+ * import { EventLog, memorySink } from 'foottrace/write';
+ * import { readStoredRecord } from 'foottrace';
+ *
+ * const sink = memorySink();
+ * const log = new EventLog({ count: 0 }, { sink, address: { logRunId: 'run-1', drillPath: [] } });
+ * log.note('attempt', { attempt: 1, outcome: 'failed' });
+ * // … the process dies here: no `closed` entry …
+ * readStoredRecord(sink.entries).root('run-1')?.complete; // false — and its note is still there
+ * ```
+ */
+import { deepFreeze } from '../capture/freeze.js';
+/** The outcomes a `closed` entry may carry, in one place for the writer's and the reader's checks. */
+export const LOG_OUTCOMES = /* @__PURE__ */ Object.freeze(['ok', 'failed', 'paused']);
+/** A plain object — not null, not an array, not a primitive. */
+export function isEntryObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** `{ meta }` when there is one, `{}` otherwise — an absent field stays absent. */
+function withMeta(meta) {
+    return meta === undefined ? {} : { meta };
+}
+/**
+ * Hand `entry` to the sink's method for its kind, as that method's entry; returns what the method
+ * returned (a promise from an async adapter). Throws whatever the method throws — the log catches.
+ */
+export function sendEntry(sink, entry) {
+    const { address, at } = entry;
+    switch (entry.kind) {
+        case 'opened':
+            return sink.opened({ address, at, initialState: entry.initialState, ...withMeta(entry.meta) });
+        case 'commit':
+            return sink.commit({ address, at, bundle: entry.bundle });
+        case 'note':
+            return sink.note({ address, at, kind: entry.note, data: entry.data });
+        case 'closed':
+            return sink.closed({ address, at, outcome: entry.outcome, commits: entry.commits, ...withMeta(entry.meta) });
+    }
+}
+/**
+ * A sink that keeps every entry in memory, in arrival order — the reference adapter: what any adapter
+ * must give back for `readStoredRecord` to read the same record. `entries` is a new array on each read.
+ * What it keeps is frozen as far as freezing reaches — the base, `meta` and a note's `data` are the
+ * copies a log hands it, and the bundle is already frozen — so no reader can rewrite its containers. A
+ * Date's time, a Map's or Set's entries and a buffer's bytes are not sealed by freezing (`deepFreeze`'s
+ * stated limit). A caller that hands it objects directly hands them over: they are frozen in place.
+ *
+ * @example
+ * ```typescript
+ * const sink = memorySink();
+ * const log = new EventLog({}, { sink, address: { logRunId: 'run-1', drillPath: [] } });
+ * log.close('ok');
+ * sink.entries.map((e) => e.kind); // ['opened', 'closed']
+ * ```
+ */
+export function memorySink() {
+    const stored = [];
+    const keep = (entry) => {
+        stored.push(deepFreeze(entry));
+    };
+    return {
+        get entries() {
+            return stored.slice();
+        },
+        opened: ({ address, at, initialState, meta }) => keep({ kind: 'opened', address, at, initialState, ...withMeta(meta) }),
+        commit: ({ address, at, bundle }) => keep({ kind: 'commit', address, at, bundle }),
+        note: ({ address, at, kind, data }) => keep({ kind: 'note', address, at, note: kind, data }),
+        closed: ({ address, at, outcome, commits, meta }) => keep({ kind: 'closed', address, at, outcome, commits, ...withMeta(meta) }),
+        flush: () => Promise.resolve(),
+    };
+}

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

@@ -2,10 +2,11 @@
  * types.ts — the record's types: a bundle, its rows, its patches, its encoding, and the
  * execution tree as the record's readers read it.
  *
- * Imports nothing. The standalone record names nothing outside itself: the engine's frame
+ * Imports only the record's leaf attention type. The record names nothing outside itself: the engine's frame
  * types — the stage snapshot, flow messages and retention dials — remain in FootPrint's
  * `frameTypes.ts`. The closed record graph is enforced by scripts/check-layering.mjs.
  */
+import type { Attention } from '../cause/types.js';
 /** A flat key-value bag representing a state patch (overwrite or merge). */
 export interface MemoryPatch {
     [key: string]: any;
@@ -194,6 +195,8 @@ export type CommitValuesMode = 'full' | 'delta';
  * ```
  */
 export interface ExecutionTree {
+    /** Optional recorded business attention; absence does not assert health. */
+    readonly attention?: readonly Attention[];
     /** The stage's id (prefixed inside a subflow). `commitStops` reads the root's to place a subflow's seed. */
     readonly id?: string;
     /** `[subflowPath/]stageId#executionIndex` — what a reader keys on. A node without one is not a stage. */

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

@@ -2,7 +2,7 @@
  * types.ts — the record's types: a bundle, its rows, its patches, its encoding, and the
  * execution tree as the record's readers read it.
  *
- * Imports nothing. The standalone record names nothing outside itself: the engine's frame
+ * Imports only the record's leaf attention type. The record names nothing outside itself: the engine's frame
  * types — the stage snapshot, flow messages and retention dials — remain in FootPrint's
  * `frameTypes.ts`. The closed record graph is enforced by scripts/check-layering.mjs.
  */

package/dist/esm/lib/time-travel/bundles.d.ts

@@ -19,6 +19,8 @@ import type { CommitBundle, ExecutionTree } from '../memory/types.js';
 import type { LogGap } from './types.js';
 /** A plain object — not null, not an array, not a primitive. */
 export declare function isPlainish(value: unknown): value is Record<string, unknown>;
+/** A row every reader refuses with `reason` — a gap that keeps its index. */
+export declare function absentRow(reason: string): object;
 /**
  * Read a source's `executionTree` as an {@link ExecutionTree}, or as absent.
  *

package/dist/esm/lib/time-travel/bundles.js

@@ -39,6 +39,19 @@ const GAP_BUNDLE = Object.freeze({
 export function isPlainish(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
+/**
+ * Rows that hold an index for a commit the record does not have (1.1.0) — what a STORED log could not
+ * supply at a position: no readable commit entry (`storedRecord.ts`). Each
+ * carries the reason every reader then reports for its index, so the fold, the cursor and the stored
+ * log say the same thing about it. Kept by identity (a JSON copy of one is an ordinary unreadable row).
+ */
+const ABSENT_ROWS = new WeakMap();
+/** A row every reader refuses with `reason` — a gap that keeps its index. */
+export function absentRow(reason) {
+    const row = Object.freeze({});
+    ABSENT_ROWS.set(row, reason);
+    return row;
+}
 /**
  * Read a source's `executionTree` as an {@link ExecutionTree}, or as absent.
  *
@@ -76,6 +89,9 @@ export function readTree(value) {
  * compatibility break dressed up as validation.
  */
 export function bundleRefusal(row) {
+    const absent = typeof row === 'object' && row !== null ? ABSENT_ROWS.get(row) : undefined;
+    if (absent !== undefined)
+        return absent;
     if (!isPlainish(row)) {
         return `not an object (${row === null ? 'null' : Array.isArray(row) ? 'array' : typeof row})`;
     }