foottrace 1.0.3 → 1.2.0

package/dist/types/lib/cause/recordCoverage.d.ts

@@ -0,0 +1,24 @@
+import type { CommitBundle } from '../memory/types.js';
+import type { AddRecordGap, PreparedRecordScope, RecordIdentity, RecordLoadFailure, ResolvedRecordNode } from './recordTypes.js';
+import type { Attention, Gap } from './types.js';
+/** Preserve first-observed coverage order while collapsing repeated codes from different evidence paths. */
+export declare function recordGapCollector(): {
+    gaps: Gap[];
+    addGap: AddRecordGap;
+};
+/** Failed loading exposes a fixed category, never the host error or an apparently complete empty graph. */
+export declare function gapForRecordFailure(code: Gap['code']): readonly Gap[];
+/** Return captured mark references without treating an omitted attention map as collected evidence. */
+export declare function attentionForRecordNode(node: ResolvedRecordNode | RecordLoadFailure): readonly Attention[];
+/** Emit host and capture gaps before query-derived gaps so existing evidence order stays stable. */
+export declare function collectScopeCoverage(scope: PreparedRecordScope, bundle: CommitBundle, extraGapCodes: readonly Gap['code'][] | undefined, addGap: AddRecordGap): void;
+/** A read-only identity has no new value life; unqualified executions retain written-key encounter order. */
+export declare function writtenKeysForNode(bundle: CommitBundle, identity: RecordIdentity): string[];
+/** Immediate adjacency caps affect graph coverage even when the caller asks only for parents. */
+export declare function collectForwardCoverage(scope: PreparedRecordScope, identity: RecordIdentity, commitIndex: number, firstCommitIndex: number, maximumEdges: number, addGap: AddRecordGap): void;
+/** Exact attribution requires captured per-write provenance or a validated read-only key context. */
+export declare function readAttributionIsPrecise(scope: PreparedRecordScope, identity: RecordIdentity, bundle: CommitBundle): boolean;
+/** Distinguish conservative attribution from missing collection without marking a proven empty leaf. */
+export declare function collectReadCoverage(scope: PreparedRecordScope, identity: RecordIdentity, precise: boolean, addGap: AddRecordGap): void;
+/** Forward absence is trustworthy only when every potentially consuming execution collected its reads. */
+export declare function allStageReadsCollected(scope: PreparedRecordScope): boolean;

package/dist/types/lib/cause/recordIdentity.d.ts

@@ -0,0 +1,9 @@
+import type { LogAddress } from '../memory/eventPosition.js';
+import type { GraphContext, NodeId } from './types.js';
+import type { RecordIdentity, RecordLoadFailure, RecordNode, RecordScopeLoader, ResolvedRecordNode } from './recordTypes.js';
+/** Parse only the bounded identity encoding; payload fields never become graph addresses. */
+export declare function readNodeIdentity(nodeId: string): RecordIdentity;
+/** Stable field order preserves existing address/execution/key IDs across storage and memory readers. */
+export declare function nodeIdFor(addressInput: LogAddress, node: RecordNode, read?: true): NodeId;
+/** An admitted ID must also match captured evidence before it can introduce a dependency. */
+export declare function resolveRecordNode(nodeId: NodeId, context: GraphContext, loader: RecordScopeLoader): Promise<ResolvedRecordNode | RecordLoadFailure>;

package/dist/types/lib/cause/recordLoading.d.ts

@@ -0,0 +1,7 @@
+import type { LogAddress } from '../memory/eventPosition.js';
+import type { GraphContext, NodeId } from './types.js';
+import type { RecordGraphOptions, RecordScopeHost, RecordScopeLoader } from './recordTypes.js';
+/** Bound caller waiting independently of host cooperation without sharing cancellation between requests. */
+export declare function createRecordScopeLoader(hostLoad: RecordScopeHost, limits: Required<RecordGraphOptions>): RecordScopeLoader;
+/** Discovery must distinguish an unavailable scope from a successfully loaded empty record. */
+export declare function openRecordScope(addressInput: LogAddress, context: GraphContext, loader: RecordScopeLoader): Promise<readonly NodeId[]>;

package/dist/types/lib/cause/recordParents.d.ts

@@ -0,0 +1,4 @@
+import type { RecordInspection, ResolvedRecordNode } from './recordTypes.js';
+import type { Gap } from './types.js';
+/** Derive parent adjacency and its ordered gaps together from the same bounded canonical query. */
+export declare function inspectRecordNode(node: ResolvedRecordNode, maximumEdges: number, extraGapCodes: readonly Gap['code'][] | undefined): RecordInspection;

package/dist/types/lib/cause/recordScope.d.ts

@@ -0,0 +1,8 @@
+import type { LogAddress } from '../memory/eventPosition.js';
+import type { PreparedRecordScope, RecordGraphOptions, RecordScope } from './recordTypes.js';
+/** Read configuration as data so option accessors cannot execute during adapter construction. */
+export declare function recordOptions(options: RecordGraphOptions): Required<RecordGraphOptions>;
+/** Spend one shared field budget before canonical readers see any untrusted scope data. */
+export declare function prepareRecordScope(value: RecordScope, address: LogAddress, maximumCommits: number, maximumFields: number): PreparedRecordScope;
+/** Preserve both stage reads and stronger per-write prefixes, including their original encounter order. */
+export declare function readKeysForStage(scope: PreparedRecordScope, runtimeStageId: string): string[];

package/dist/types/lib/cause/recordTypes.d.ts

@@ -0,0 +1,67 @@
+import type { ControlDependency } from '../memory/backtrack.js';
+import type { LogAddress } from '../memory/eventPosition.js';
+import type { CommitBundle } from '../memory/types.js';
+import type { Adjacency, Attention, CauseGraph, Gap, GraphContext, NodeId } from './types.js';
+/** Explicit complete maps record absence too; an omitted map means it was not collected. */
+export interface RecordScope {
+    readonly address: LogAddress;
+    readonly commitLog: readonly unknown[];
+    readonly reads?: Readonly<Record<string, readonly string[]>>;
+    readonly controlDeps?: Readonly<Record<string, {
+        readonly deciderId: string;
+    }>>;
+    readonly attention?: Readonly<Record<string, readonly Attention[]>>;
+    readonly complete?: boolean;
+}
+export interface RecordNode {
+    readonly runtimeStageId: string;
+    readonly commitIdx?: number;
+    readonly key?: string;
+}
+export interface RecordGraphOptions {
+    readonly maxCommits?: number;
+    readonly maxFields?: number;
+    readonly maxEdges?: number;
+    readonly maxScopes?: number;
+    readonly loadTimeoutMs?: number;
+}
+export interface RecordCauseGraph extends CauseGraph {
+    nodeId(address: LogAddress, node: RecordNode): NodeId;
+    /** Rejects with fixed message/code on discovery failure; never reports an unavailable scope as empty. */
+    openScope(address: LogAddress, context: GraphContext): Promise<readonly NodeId[]>;
+}
+export interface RecordLoaderResult {
+    readonly scope: RecordScope;
+    readonly gaps?: readonly Gap['code'][];
+}
+export interface RecordIdentity extends RecordNode {
+    readonly address: LogAddress;
+    readonly read?: true;
+}
+export interface PreparedRecordScope {
+    address: LogAddress;
+    log: CommitBundle[];
+    reads?: Map<string, string[]>;
+    control?: Map<string, ControlDependency>;
+    marks?: Map<string, readonly Attention[]>;
+    complete: boolean;
+}
+export interface RecordLoadFailure {
+    failure: Gap['code'];
+}
+export type LoadedRecordScope = PreparedRecordScope | RecordLoadFailure;
+export interface ResolvedRecordNode {
+    scope: PreparedRecordScope;
+    identity: RecordIdentity;
+    commitIndex: number;
+}
+export interface RecordInspection {
+    adjacency: Adjacency;
+    gaps: readonly Gap[];
+}
+export type RecordScopeHost = (address: LogAddress, context: GraphContext) => RecordLoaderResult | Promise<RecordLoaderResult>;
+export interface RecordScopeLoader {
+    loadScope(address: LogAddress, context: GraphContext): Promise<LoadedRecordScope>;
+    extraGapCodes(scope: PreparedRecordScope): readonly Gap['code'][] | undefined;
+}
+export type AddRecordGap = (code: Gap['code']) => void;

package/dist/types/lib/cause/recordValidation.d.ts

@@ -0,0 +1,33 @@
+/** Admission before the existing readers touch untrusted record fields. Payloads never leave this module's graph. */
+import type { LogAddress } from '../memory/eventPosition.js';
+import type { CommitBundle } from '../memory/types.js';
+import type { GapCode } from './types.js';
+import { attention as marksOf } from './validation.js';
+import { EvidenceRefusal } from './admission.js';
+export { marksOf };
+/** Loader refusals stay distinct from graph-port refusals so a failed host load keeps its original classification. */
+export declare class RecordRefusal extends EvidenceRefusal {
+    readonly code: GapCode;
+    constructor(code?: GapCode);
+}
+export declare function own(value: unknown, key: string): unknown;
+export declare function names(value: unknown, maximum?: number, path?: boolean): string[];
+export declare function name(value: unknown, path?: boolean): string;
+export declare function list(value: unknown, maximum: number): readonly unknown[];
+export declare function addressOf(value: unknown): LogAddress;
+export declare function spend(budget: {
+    left: number;
+}, count: number): void;
+export declare const addressKey: (a: LogAddress) => string;
+/** Iterative bounded copy: data descriptors only, no getters/toJSON/prototypes or opaque class instances. */
+export declare function dataCopy(value: unknown, budget: {
+    left: number;
+}): unknown;
+export declare function bundleOf(value: unknown, idx: number, budget: {
+    left: number;
+}): CommitBundle;
+export declare function mapOf<T>(value: unknown, limit: number, read: (v: unknown) => T, budget?: {
+    left: number;
+}): Map<string, T> | undefined;
+/** Observe native promises by intrinsic without assimilating a data object's then accessor. */
+export declare function projectLoaded<T, R>(work: () => T | Promise<T>, project: (value: T) => R): Promise<R>;

package/dist/types/lib/cause/session.d.ts

@@ -0,0 +1,30 @@
+import type { CauseGraph, ExplainOptions, Gap, GraphContext, NodeId, WalkLimits } from './types.js';
+export interface Read<T> {
+    readonly value?: T;
+    readonly gap?: Gap;
+}
+type Method = 'parents' | 'children' | 'attention' | 'gaps' | 'roots';
+/** One deadline, memo table and work budget per public query, never per graph or store. */
+export declare class Session {
+    readonly limits: Required<WalkLimits>;
+    readonly context: GraphContext;
+    readonly nodes: Set<string>;
+    readonly controller: AbortController;
+    private readonly cache;
+    private calls;
+    edges: number;
+    private timedOut;
+    private readonly deadline;
+    private readonly timer;
+    private readonly external?;
+    private readonly onAbort;
+    private readonly methods;
+    constructor(graph: CauseGraph, options?: ExplainOptions);
+    dispose(): void;
+    stopGap(id?: NodeId): Gap | undefined;
+    admit(id: NodeId): Gap | undefined;
+    hasRoots(): boolean;
+    read<T>(method: Method, id: NodeId | undefined, project: (raw: unknown) => T): Promise<Read<T>>;
+    invoke<T>(id: NodeId | undefined, work: () => unknown, project: (raw: unknown) => T): Promise<Read<T>>;
+}
+export {};

package/dist/types/lib/cause/storedRecordAdapter.d.ts

@@ -0,0 +1,11 @@
+import type { LogAddress } from '../memory/eventPosition.js';
+import { type RecordCauseGraph, type RecordGraphOptions, type RecordScope } from './recordAdapter.js';
+import type { GraphContext, MaybePromise } from './types.js';
+export interface StoredRecordScope extends Omit<RecordScope, 'address' | 'commitLog' | 'complete'> {
+    readonly entries: readonly unknown[];
+}
+export interface StoredRecordHost {
+    loadLog(address: LogAddress, context: GraphContext): MaybePromise<StoredRecordScope>;
+}
+/** Load one address only. The host owns auth/storage; cancellation is forwarded and waiting is independently bounded. */
+export declare function createStoredRecordGraph(host: StoredRecordHost, options?: RecordGraphOptions): RecordCauseGraph;

package/dist/types/lib/cause/strategies.d.ts

@@ -0,0 +1,3 @@
+import type { NodeId, RootStrategy } from './types.js';
+export declare const largestDrop: (scores: ReadonlyMap<NodeId, number>) => RootStrategy;
+export declare const mostAffected: (counts: ReadonlyMap<NodeId, number>) => RootStrategy;

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

@@ -0,0 +1,90 @@
+/** Names and evidence references only. No state values, messages, credentials or business payloads. */
+export type NodeId = string;
+export type AttentionKind = 'error' | 'unknown-effect' | 'gave-up' | 'timeout' | 'retried' | 'quality-drop' | 'not-collected' | 'outlier' | (string & {});
+export type AttentionReason = 'ERROR_RECORDED' | 'UNKNOWN_EFFECT_RECORDED' | 'RETRY_STOP_RECORDED' | 'TIMEOUT_RECORDED' | 'RETRY_RECORDED' | 'QUALITY_DROP_RECORDED' | 'EVIDENCE_NOT_COLLECTED' | 'OUTLIER_RECORDED' | 'BUSINESS_RULE_MATCHED';
+export interface Attention {
+    readonly kind: AttentionKind;
+    readonly reason: AttentionReason;
+    readonly evidence: readonly string[];
+}
+export type Confidence = 'complete' | 'incomplete';
+export type GapCode = '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 interface Gap {
+    readonly code: GapCode;
+    readonly nodeId?: NodeId;
+    readonly evidence: readonly string[];
+}
+export interface GraphEdge {
+    readonly nodeId: NodeId;
+    readonly kind: 'data' | 'control';
+    readonly attribution: 'per-write' | 'stage' | 'recorded-control';
+    readonly evidence: readonly string[];
+}
+export interface Adjacency {
+    readonly edges: readonly GraphEdge[];
+    readonly complete: boolean;
+}
+export interface GraphContext {
+    readonly signal: AbortSignal;
+}
+export type MaybePromise<T> = T | Promise<T>;
+/** A host owns storage, authentication and service resolution. A node may represent a key-qualified write. */
+export interface CauseGraph {
+    parents(id: NodeId, context: GraphContext): MaybePromise<Adjacency>;
+    children(id: NodeId, context: GraphContext): MaybePromise<Adjacency>;
+    attention(id: NodeId, context: GraphContext): MaybePromise<readonly Attention[]>;
+    gaps(id: NodeId, context: GraphContext): MaybePromise<readonly Gap[]>;
+    /** Optional, bounded discovery seeds; attentionList can instead receive explicit nodeIds. */
+    roots?(context: GraphContext): MaybePromise<readonly NodeId[]>;
+}
+export interface TraversedEdge extends Omit<GraphEdge, 'nodeId'> {
+    readonly from: NodeId;
+    readonly to: NodeId;
+}
+export interface MarkedNode {
+    readonly nodeId: NodeId;
+    readonly attention: readonly Attention[];
+}
+export interface ImpactResult {
+    readonly nodes: readonly NodeId[];
+    readonly edges: readonly TraversedEdge[];
+    readonly confidence: Confidence;
+    readonly gaps: readonly Gap[];
+}
+export interface CauseResult {
+    readonly nodeId: NodeId;
+    readonly attention: readonly Attention[];
+    /** Present only for one supported candidate and complete backward coverage. Not provider-internal proof. */
+    readonly rootCause?: NodeId;
+    /** Selected node → candidate, following recorded dependency edges. */
+    readonly path: readonly NodeId[];
+    readonly alternatives: readonly NodeId[];
+    readonly impact: ImpactResult;
+    readonly confidence: Confidence;
+    readonly gaps: readonly Gap[];
+}
+export interface AttentionListResult {
+    readonly nodes: readonly MarkedNode[];
+    readonly confidence: Confidence;
+    readonly gaps: readonly Gap[];
+}
+export interface WalkLimits {
+    readonly maxNodes?: number;
+    readonly maxDepth?: number;
+    readonly maxEdges?: number;
+    readonly maxCalls?: number;
+    readonly timeoutMs?: number;
+}
+/** A strategy selects a tied best tier of already recorded marked nodes; it cannot introduce identities. */
+export type RootStrategy = (candidates: readonly MarkedNode[], context: GraphContext) => MaybePromise<readonly NodeId[]>;
+/** Reorder all already discovered impact references; never inject or drop evidence. */
+export type ImpactStrategy = (nodes: readonly NodeId[], context: GraphContext) => MaybePromise<readonly NodeId[]>;
+export interface ExplainOptions extends WalkLimits {
+    readonly signal?: AbortSignal;
+    readonly rankRoots?: RootStrategy;
+    readonly rankImpact?: ImpactStrategy;
+}
+export interface AttentionListOptions extends WalkLimits {
+    readonly signal?: AbortSignal;
+    readonly nodeIds?: readonly NodeId[];
+}

package/dist/types/lib/cause/validation.d.ts

@@ -0,0 +1,24 @@
+import type { Adjacency, Attention, Gap, GapCode, NodeId } from './types.js';
+import { EvidenceRefusal } from './admission.js';
+/** Graph-port refusals carry their code through Session; loader refusals are handled at the record boundary. */
+export declare class AdmissionError extends EvidenceRefusal {
+    readonly code: GapCode;
+    constructor(code?: GapCode);
+}
+/**
+ * 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 declare function observePromise(raw: unknown, accept: (raw: unknown) => void, reject: (reason: unknown) => void): boolean;
+export declare function own(value: unknown, key: string): unknown;
+export declare function plain(value: unknown): void;
+export declare function name(value: unknown, maximum?: number): string;
+export declare function list<T>(value: unknown, maximum: number, read: (item: unknown) => T, overflow?: GapCode): readonly T[];
+export declare const refs: (value: unknown) => readonly string[];
+export declare function attention(value: unknown): readonly Attention[];
+export declare function gaps(value: unknown): readonly Gap[];
+export declare function adjacency(value: unknown, maximum: number): Adjacency;
+export declare const nodeIds: (value: unknown, max: number) => readonly NodeId[];
+export declare const gap: (code: GapCode, nodeId?: NodeId) => Gap;
+export declare function uniqueGaps(items: readonly Gap[]): readonly Gap[];

package/dist/types/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/types/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/types/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/types/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;