foottrace 1.0.3 → 1.2.0

package/dist/esm/lib/cause/validation.js

@@ -0,0 +1,134 @@
+import { boundedList, boundedName, EvidenceRefusal, ownData } from './admission.js';
+/** Graph-port refusals carry their code through Session; loader refusals are handled at the record boundary. */
+export class AdmissionError extends EvidenceRefusal {
+    code;
+    constructor(code = 'invalid-data') {
+        super(code, 'Invalid cause evidence');
+        this.code = code;
+    }
+}
+/**
+ * Only ordinary native promise wrappers belong to the async host contract.
+ * An own constructor could run an accessor/species during intrinsic then().
+ * Exotic wrappers remain the trusted host's responsibility, including rejection handling.
+ */
+export function observePromise(raw, accept, reject) {
+    if (!raw || typeof raw !== 'object' || Object.getPrototypeOf(raw) !== Promise.prototype)
+        return false;
+    if (Object.getOwnPropertyDescriptor(raw, 'constructor'))
+        throw new AdmissionError();
+    try {
+        Promise.prototype.then.call(raw, accept, reject);
+    }
+    catch {
+        throw new AdmissionError();
+    }
+    return true;
+}
+const refuseGraph = (code) => new AdmissionError(code);
+const graphDescriptors = { translateTrapErrors: false, requireOwnValue: false };
+export function own(value, key) {
+    return ownData(value, key, refuseGraph, graphDescriptors);
+}
+export function plain(value) {
+    if (!value || typeof value !== 'object' || ![Object.prototype, null].includes(Object.getPrototypeOf(value)))
+        throw new AdmissionError();
+}
+export function name(value, maximum = 2048) {
+    return boundedName(value, maximum, refuseGraph);
+}
+export function list(value, maximum, read, overflow = 'invalid-data') {
+    return boundedList(value, maximum, read, {
+        refuse: refuseGraph,
+        overflow,
+        freeze: true,
+        descriptors: graphDescriptors,
+    });
+}
+const reasons = new Set([
+    'ERROR_RECORDED',
+    'UNKNOWN_EFFECT_RECORDED',
+    'RETRY_STOP_RECORDED',
+    'TIMEOUT_RECORDED',
+    'RETRY_RECORDED',
+    'QUALITY_DROP_RECORDED',
+    'EVIDENCE_NOT_COLLECTED',
+    'OUTLIER_RECORDED',
+    'BUSINESS_RULE_MATCHED',
+]);
+const codes = new Set([
+    'not-collected',
+    'untracked-input',
+    'redacted',
+    'conservative',
+    'scope-boundary',
+    'invalid-data',
+    'unavailable',
+    'timeout',
+    'cancelled',
+    'cycle',
+    'node-limit',
+    'depth-limit',
+    'edge-limit',
+    'call-limit',
+    'truncated',
+    'strategy-failed',
+]);
+export const refs = (value) => list(value, 16, (item) => name(item, 512));
+export function attention(value) {
+    return list(value, 32, (item) => {
+        plain(item);
+        const kind = own(item, 'kind'), reason = own(item, 'reason');
+        if (typeof kind !== 'string' ||
+            !/^[A-Za-z][A-Za-z0-9_-]{0,63}$/.test(kind) ||
+            typeof reason !== 'string' ||
+            !reasons.has(reason))
+            throw new AdmissionError();
+        const evidence = refs(own(item, 'evidence'));
+        if (kind !== 'not-collected' && evidence.length === 0)
+            throw new AdmissionError();
+        return Object.freeze({ kind, reason: reason, evidence });
+    });
+}
+export function gaps(value) {
+    return list(value, 32, (item) => {
+        plain(item);
+        const code = own(item, 'code'), nodeId = own(item, 'nodeId');
+        if (typeof code !== 'string' || !codes.has(code))
+            throw new AdmissionError();
+        return Object.freeze({
+            code: code,
+            ...(nodeId === undefined ? {} : { nodeId: name(nodeId) }),
+            evidence: refs(own(item, 'evidence')),
+        });
+    });
+}
+export function adjacency(value, maximum) {
+    plain(value);
+    const complete = own(value, 'complete');
+    if (typeof complete !== 'boolean')
+        throw new AdmissionError();
+    const edges = list(own(value, 'edges'), maximum, (item) => {
+        plain(item);
+        const nodeId = name(own(item, 'nodeId')), kind = own(item, 'kind'), attribution = own(item, 'attribution');
+        if ((kind !== 'data' && kind !== 'control') ||
+            (attribution !== 'per-write' && attribution !== 'stage' && attribution !== 'recorded-control') ||
+            (kind === 'control' && attribution !== 'recorded-control') ||
+            (kind === 'data' && attribution === 'recorded-control'))
+            throw new AdmissionError();
+        return Object.freeze({ nodeId, kind, attribution, evidence: refs(own(item, 'evidence')) });
+    }, 'edge-limit');
+    return Object.freeze({ edges, complete });
+}
+export const nodeIds = (value, max) => list(value, max, (item) => name(item), 'node-limit');
+export const gap = (code, nodeId) => Object.freeze({ code, ...(nodeId === undefined ? {} : { nodeId }), evidence: Object.freeze([]) });
+export function uniqueGaps(items) {
+    const seen = new Set();
+    return Object.freeze(items.filter((item) => {
+        const key = JSON.stringify(item);
+        if (seen.has(key))
+            return false;
+        seen.add(key);
+        return true;
+    }));
+}

package/dist/esm/lib/cause/walk.d.ts

@@ -0,0 +1,12 @@
+import type { Gap, MarkedNode, NodeId, TraversedEdge } from './types.js';
+import { Session } from './session.js';
+export interface Walk {
+    readonly nodes: readonly NodeId[];
+    readonly marked: readonly MarkedNode[];
+    readonly edges: readonly TraversedEdge[];
+    readonly gaps: readonly Gap[];
+}
+/** BFS discovers the shallowest arrival; a repeated diamond node is not a cycle. */
+export declare function walk(session: Session, seeds: readonly NodeId[], direction: 'parents' | 'children'): Promise<Walk>;
+export declare function frontier(result: Walk): readonly MarkedNode[];
+export declare function pathTo(edges: readonly TraversedEdge[], start: NodeId, target: NodeId): readonly NodeId[];

package/dist/esm/lib/cause/walk.js

@@ -0,0 +1,174 @@
+import { adjacency, attention, gap, gaps, uniqueGaps } from './validation.js';
+/** BFS discovers the shallowest arrival; a repeated diamond node is not a cycle. */
+export async function walk(session, seeds, direction) {
+    const queue = [], seen = new Set(), marks = [], edges = [], missing = [];
+    const enqueue = (id, depth) => {
+        if (seen.has(id))
+            return;
+        const refusal = session.admit(id);
+        if (refusal) {
+            missing.push(refusal);
+            return;
+        }
+        seen.add(id);
+        queue.push([id, depth]);
+    };
+    for (const id of seeds)
+        enqueue(id, 0);
+    for (let index = 0; index < queue.length; index++) {
+        const [id, depth] = queue[index], stopped = session.stopGap(id);
+        if (stopped) {
+            missing.push(stopped);
+            break;
+        }
+        const marked = await session.read('attention', id, attention);
+        if (marked.gap)
+            missing.push(marked.gap);
+        if (marked.value?.length) {
+            marks.push(Object.freeze({ nodeId: id, attention: marked.value }));
+            if (marked.value.some((item) => item.kind === 'not-collected'))
+                missing.push(gap('not-collected', id));
+        }
+        const coverage = await session.read('gaps', id, gaps);
+        if (coverage.gap)
+            missing.push(coverage.gap);
+        if (coverage.value)
+            missing.push(...coverage.value);
+        const page = await session.read(direction, id, (raw) => adjacency(raw, session.limits.maxEdges));
+        if (page.gap) {
+            missing.push(page.gap);
+            continue;
+        }
+        if (!page.value)
+            continue;
+        if (!page.value.complete)
+            missing.push(gap('not-collected', id));
+        if (depth >= session.limits.maxDepth) {
+            if (page.value.edges.length)
+                missing.push(gap('depth-limit', id));
+            continue;
+        }
+        for (const edge of page.value.edges) {
+            if (session.edges >= session.limits.maxEdges) {
+                missing.push(gap('edge-limit', id));
+                break;
+            }
+            session.edges++;
+            const refusal = session.admit(edge.nodeId);
+            if (refusal) {
+                missing.push(refusal);
+                continue;
+            }
+            edges.push(Object.freeze({
+                from: id,
+                to: edge.nodeId,
+                kind: edge.kind,
+                attribution: edge.attribution,
+                evidence: edge.evidence,
+            }));
+            if (edge.attribution === 'stage')
+                missing.push(gap('conservative', id));
+            enqueue(edge.nodeId, depth + 1);
+        }
+    }
+    if (hasCycle(edges))
+        missing.push(gap('cycle'));
+    return Object.freeze({
+        nodes: Object.freeze(queue.map((row) => row[0])),
+        marked: Object.freeze(marks),
+        edges: Object.freeze(edges),
+        gaps: uniqueGaps(missing),
+    });
+}
+/** Iterative three-colour walk; shared nodes remain distinguishable from back edges. */
+function hasCycle(edges) {
+    const next = new Map();
+    for (const edge of edges) {
+        if (!next.has(edge.from))
+            next.set(edge.from, []);
+        next.get(edge.from).push(edge.to);
+    }
+    const state = new Map();
+    for (const seed of next.keys()) {
+        if (state.has(seed))
+            continue;
+        const stack = [[seed, 0]];
+        state.set(seed, 1);
+        while (stack.length) {
+            const frame = stack[stack.length - 1], children = next.get(frame[0]) ?? [];
+            if (frame[1] >= children.length) {
+                state.set(frame[0], 2);
+                stack.pop();
+                continue;
+            }
+            const child = children[frame[1]++];
+            if (state.get(child) === 1)
+                return true;
+            if (!state.has(child)) {
+                state.set(child, 1);
+                stack.push([child, 0]);
+            }
+        }
+    }
+    return false;
+}
+export function frontier(result) {
+    const marked = new Set(result.marked
+        .filter((item) => item.attention.some((mark) => mark.kind !== 'not-collected'))
+        .map((item) => item.nodeId));
+    const pending = new Map(result.nodes.map((id) => [id, 0]));
+    const dependents = new Map();
+    for (const edge of result.edges) {
+        pending.set(edge.from, (pending.get(edge.from) ?? 0) + 1);
+        if (!dependents.has(edge.to))
+            dependents.set(edge.to, []);
+        dependents.get(edge.to).push(edge.from);
+    }
+    // Process causal ancestors first, propagating one boolean through the DAG.
+    // This is O(nodes + edges), rather than a fresh ancestry scan per marked node.
+    const queue = [...pending].filter(([, count]) => count === 0).map(([id]) => id);
+    const earlierMark = new Set(), eligible = new Set();
+    for (let i = 0; i < queue.length; i++) {
+        const id = queue[i];
+        if (marked.has(id) && !earlierMark.has(id))
+            eligible.add(id);
+        for (const dependent of dependents.get(id) ?? []) {
+            if (marked.has(id) || earlierMark.has(id))
+                earlierMark.add(dependent);
+            const count = pending.get(dependent) - 1;
+            pending.set(dependent, count);
+            if (count === 0)
+                queue.push(dependent);
+        }
+    }
+    // Nodes left in a cycle cannot supply a validated earliest ancestor.
+    return result.marked.filter((item) => eligible.has(item.nodeId));
+}
+export function pathTo(edges, start, target) {
+    const queue = [start], previous = new Map([[start, undefined]]);
+    const next = new Map();
+    for (const edge of edges) {
+        if (!next.has(edge.from))
+            next.set(edge.from, []);
+        next.get(edge.from).push(edge.to);
+    }
+    for (let i = 0; i < queue.length; i++) {
+        const id = queue[i];
+        if (id === target)
+            break;
+        for (const child of next.get(id) ?? [])
+            if (!previous.has(child)) {
+                previous.set(child, id);
+                queue.push(child);
+            }
+    }
+    if (!previous.has(target))
+        return Object.freeze([]);
+    const path = [];
+    let id = target;
+    while (id !== undefined) {
+        path.push(id);
+        id = previous.get(id);
+    }
+    return Object.freeze(path.reverse());
+}

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;
 }