@reticlehq/server 2.14.0 → 3.2.0

package/dist/memory/journal/envelope.d.ts

@@ -0,0 +1,230 @@
+import { z } from 'zod';
+import type { SegmentRollup } from './rollups.js';
+/**
+ * The expected-envelope model — the OSS statistical engine behind the deviation report. Per-metric
+ * running stats (Welford, so we never store every sample) accumulate across runs of the same route;
+ * a new segment is compared against them and flagged when a metric runs high. The *math* is open; the
+ * fleet-calibrated thresholds are the paid layer (see OSS-VS-SERVER). We only flag INCREASES
+ * (slower, more errors, more requests) — a segment doing less than expected is not a regression.
+ */
+/** Online mean/variance/max for one metric (Welford's algorithm). Immutable: addStat returns a copy. */
+interface MetricStats {
+    count: number;
+    mean: number;
+    /** Sum of squared deviations (Welford M2); variance = m2/(count-1). */
+    m2: number;
+    max: number;
+}
+export declare function emptyStats(): MetricStats;
+export declare function addStat(stats: MetricStats, x: number): MetricStats;
+export declare function stddev(stats: MetricStats): number;
+/** How many stddevs above the mean `x` sits (0 when there's no spread yet). */
+export declare function zScore(stats: MetricStats, x: number): number;
+/** The metrics an envelope tracks per route. */
+declare const ENVELOPE_METRICS: readonly ["durationMs", "net", "netErrors", "consoleErrors"];
+type EnvelopeMetric = (typeof ENVELOPE_METRICS)[number];
+export interface RouteEnvelope {
+    route: string;
+    /** Runs that contributed a sample — below MIN_ENVELOPE_SAMPLES the envelope is too green to judge. */
+    samples: number;
+    stats: Record<EnvelopeMetric, MetricStats>;
+}
+/** Below this, an envelope is noise — the deviation report falls back to the causal summary. */
+export declare const MIN_ENVELOPE_SAMPLES = 3;
+/** Persisted shape of a route envelope. Validated on load; a bad file degrades to no envelope. */
+export declare const RouteEnvelopeSchema: z.ZodObject<{
+    route: z.ZodString;
+    samples: z.ZodNumber;
+    stats: z.ZodObject<{
+        durationMs: z.ZodObject<{
+            count: z.ZodNumber;
+            mean: z.ZodNumber;
+            m2: z.ZodNumber;
+            max: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }>;
+        net: z.ZodObject<{
+            count: z.ZodNumber;
+            mean: z.ZodNumber;
+            m2: z.ZodNumber;
+            max: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }>;
+        netErrors: z.ZodObject<{
+            count: z.ZodNumber;
+            mean: z.ZodNumber;
+            m2: z.ZodNumber;
+            max: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }>;
+        consoleErrors: z.ZodObject<{
+            count: z.ZodNumber;
+            mean: z.ZodNumber;
+            m2: z.ZodNumber;
+            max: z.ZodNumber;
+        }, "strip", z.ZodTypeAny, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }, {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        }>;
+    }, "strip", z.ZodTypeAny, {
+        durationMs: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        net: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        netErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        consoleErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+    }, {
+        durationMs: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        net: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        netErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        consoleErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+    }>;
+}, "strip", z.ZodTypeAny, {
+    route: string;
+    samples: number;
+    stats: {
+        durationMs: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        net: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        netErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        consoleErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+    };
+}, {
+    route: string;
+    samples: number;
+    stats: {
+        durationMs: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        net: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        netErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+        consoleErrors: {
+            count: number;
+            mean: number;
+            m2: number;
+            max: number;
+        };
+    };
+}>;
+export declare function emptyEnvelope(route: string): RouteEnvelope;
+/** Fold one observed segment into the envelope as a new sample. */
+export declare function addSegmentToEnvelope(envelope: RouteEnvelope, segment: SegmentRollup): RouteEnvelope;
+/** One metric of one segment running abnormally high against its envelope. */
+export interface Deviation {
+    route: string;
+    metric: EnvelopeMetric;
+    observed: number;
+    expectedMean: number;
+    z: number;
+}
+/**
+ * Compare a segment against its envelope. Returns the metrics running high (z above threshold),
+ * ranked most-severe first. Empty when the envelope is too green (< MIN_ENVELOPE_SAMPLES) — the caller
+ * falls back to the causal summary in that case.
+ */
+export declare function compareSegment(envelope: RouteEnvelope, segment: SegmentRollup, zThreshold?: number): Deviation[];
+export {};

package/dist/memory/journal/journal-query.d.ts

@@ -0,0 +1,66 @@
+import type { JournalWriteLoss, ReticleEvent } from '@reticlehq/core';
+import type { JournalReader } from './journal-recorder.js';
+/** The slice of the ring buffer a journal-backed query reads. `RingBuffer` satisfies it structurally. */
+export interface QueryBuffer {
+    since(cursor: number): ReticleEvent[];
+    bufferHealth(): {
+        total: number;
+        dropped: number;
+    };
+}
+/** Filter bounds for a journal-backed event query. All optional; omitted = unbounded on that axis. */
+export interface EventQueryOptions {
+    /** Lower time bound (inclusive), elapsed ms — the act cursor semantics of `eventsSince`. */
+    since?: number | undefined;
+    /** Upper time bound (inclusive), elapsed ms — the new `until` param. */
+    until?: number | undefined;
+    /** Keep only events attributed to this action id — answers "what did action N cause". */
+    actionId?: string | undefined;
+}
+/**
+ * Merge the durable journal's events with the ring buffer's, de-duplicated by `seq` (unique per
+ * session), ordered by `seq` (falling back to `t` for any pre-2.2 event without one). Neither source is
+ * a strict superset — the journal holds everything already flushed (incl. evicted), the buffer holds the
+ * most-recent tail that may not be flushed yet — so the union is the complete picture.
+ *
+ * ...for THIS connection. The session id survives a reload (it lives in sessionStorage), so the next
+ * connection reopens the same journal file while `seq` and `t` both restart at zero in the fresh
+ * page. Once the buffer has evicted anything — permanent about a minute into any session — every
+ * query falls through to that file and the PREVIOUS connection's tail arrives carrying timestamps
+ * that look like this connection's. Field reports: contradictions from before an explicit
+ * `reticle_session end`, two logins from different runs counted as one duplicate write, and findings
+ * from before a `since` cursor the caller had passed explicitly (`since` filters on `t`, which is
+ * exactly the field that restarted).
+ *
+ * The buffer is the authority on what this connection has emitted: the journal is written from the
+ * same stream and can only lag it, so nothing beyond the buffer's newest seq can belong here.
+ * Overlapping seqs need no rule — appends are ordered, so the newest write already wins the dedupe.
+ */
+export declare function mergeEventsBySeq(journal: readonly ReticleEvent[], buffer: readonly ReticleEvent[]): ReticleEvent[];
+/**
+ * The events a query answers with: the ring buffer's, merged with the durable journal's **only when
+ * the buffer has evicted** (so a healthy session pays no disk cost), then filtered by
+ * since/until/actionId. This is how "what did action N cause" is answered after the buffer has
+ * dropped the evidence — the substrate's whole point.
+ */
+export declare function readQueryEvents(reader: JournalReader | undefined, buffer: QueryBuffer, options: EventQueryOptions): Promise<ReticleEvent[]>;
+/**
+ * What the durable ledger could not WRITE, when a query would read from it.
+ *
+ * The event ledger stops at a byte ceiling, so a journal-backed window can be missing exactly the
+ * evidence that would have refuted an absence claim. The in-band `truncated` record cannot carry
+ * this on its own: it is stamped with the `t` of the last refused event, and `filterEvents` above
+ * bounds on `t` — so a window opened after the ceiling was reached holds no marker, no events, and
+ * nothing to distinguish it from a window in which nothing happened.
+ *
+ * Reported ONLY while the buffer has evicted, which is the same condition `readQueryEvents` uses to
+ * fall through to disk. While the buffer still holds the window, the ledger's state says nothing
+ * about that window's completeness, and saying it anyway would impeach healthy verdicts for the
+ * rest of every session that ever hit its cap. Live ring data is never discarded over this.
+ *
+ * A reader with no opinion answers `undefined`, which means NOT MEASURED. It must never be read as
+ * "nothing was lost" — see `JournalReader.readWriteLoss`.
+ */
+export declare function readJournalWriteLoss(reader: JournalReader | undefined, buffer: QueryBuffer): Promise<JournalWriteLoss | undefined>;
+/** Apply since/until/actionId bounds to an event list. */
+export declare function filterEvents(events: readonly ReticleEvent[], options: EventQueryOptions): ReticleEvent[];

package/dist/memory/journal/journal-query.js

@@ -0,0 +1,98 @@
+/**
+ * Merge the durable journal's events with the ring buffer's, de-duplicated by `seq` (unique per
+ * session), ordered by `seq` (falling back to `t` for any pre-2.2 event without one). Neither source is
+ * a strict superset — the journal holds everything already flushed (incl. evicted), the buffer holds the
+ * most-recent tail that may not be flushed yet — so the union is the complete picture.
+ *
+ * ...for THIS connection. The session id survives a reload (it lives in sessionStorage), so the next
+ * connection reopens the same journal file while `seq` and `t` both restart at zero in the fresh
+ * page. Once the buffer has evicted anything — permanent about a minute into any session — every
+ * query falls through to that file and the PREVIOUS connection's tail arrives carrying timestamps
+ * that look like this connection's. Field reports: contradictions from before an explicit
+ * `reticle_session end`, two logins from different runs counted as one duplicate write, and findings
+ * from before a `since` cursor the caller had passed explicitly (`since` filters on `t`, which is
+ * exactly the field that restarted).
+ *
+ * The buffer is the authority on what this connection has emitted: the journal is written from the
+ * same stream and can only lag it, so nothing beyond the buffer's newest seq can belong here.
+ * Overlapping seqs need no rule — appends are ordered, so the newest write already wins the dedupe.
+ */
+export function mergeEventsBySeq(journal, buffer) {
+    // ponytail: an EMPTY buffer cannot say where this connection has got to, so nothing is dropped
+    // there — a fresh connection emits page-health immediately, so the window is small and the safe
+    // direction is keeping evidence rather than inventing a boundary.
+    let newest;
+    for (const event of buffer) {
+        if ('number' === typeof event.seq && (newest === undefined || event.seq > newest)) {
+            newest = event.seq;
+        }
+    }
+    const bySeq = new Map();
+    const noSeq = [];
+    for (const event of [...journal, ...buffer]) {
+        if ('number' !== typeof event.seq) {
+            noSeq.push(event);
+            continue;
+        }
+        if (newest !== undefined && event.seq > newest)
+            continue;
+        bySeq.set(event.seq, event);
+    }
+    return [...bySeq.values(), ...noSeq].sort((a, b) => {
+        if (a.seq !== undefined && b.seq !== undefined)
+            return a.seq - b.seq;
+        return a.t - b.t;
+    });
+}
+/**
+ * Does a query read the durable journal at all, or is the buffer still authoritative?
+ *
+ * One expression, three callers, because the two public functions below are only honest while this
+ * is true. Kept here rather than on `Session` so the rule sits beside the merge and filter rules it
+ * governs; two copies of it would drift into a verdict that impeached itself over a file it never
+ * opened.
+ */
+function readsJournal(reader, buffer) {
+    return reader !== undefined && buffer.bufferHealth().dropped > 0;
+}
+/**
+ * The events a query answers with: the ring buffer's, merged with the durable journal's **only when
+ * the buffer has evicted** (so a healthy session pays no disk cost), then filtered by
+ * since/until/actionId. This is how "what did action N cause" is answered after the buffer has
+ * dropped the evidence — the substrate's whole point.
+ */
+export async function readQueryEvents(reader, buffer, options) {
+    if (!readsJournal(reader, buffer)) {
+        return filterEvents(buffer.since(options.since ?? 0), options);
+    }
+    const durable = (await reader?.readEvents()) ?? [];
+    return filterEvents(mergeEventsBySeq(durable, buffer.since(0)), options);
+}
+/**
+ * What the durable ledger could not WRITE, when a query would read from it.
+ *
+ * The event ledger stops at a byte ceiling, so a journal-backed window can be missing exactly the
+ * evidence that would have refuted an absence claim. The in-band `truncated` record cannot carry
+ * this on its own: it is stamped with the `t` of the last refused event, and `filterEvents` above
+ * bounds on `t` — so a window opened after the ceiling was reached holds no marker, no events, and
+ * nothing to distinguish it from a window in which nothing happened.
+ *
+ * Reported ONLY while the buffer has evicted, which is the same condition `readQueryEvents` uses to
+ * fall through to disk. While the buffer still holds the window, the ledger's state says nothing
+ * about that window's completeness, and saying it anyway would impeach healthy verdicts for the
+ * rest of every session that ever hit its cap. Live ring data is never discarded over this.
+ *
+ * A reader with no opinion answers `undefined`, which means NOT MEASURED. It must never be read as
+ * "nothing was lost" — see `JournalReader.readWriteLoss`.
+ */
+export async function readJournalWriteLoss(reader, buffer) {
+    if (!readsJournal(reader, buffer))
+        return undefined;
+    return (await reader?.readWriteLoss?.()) ?? undefined;
+}
+/** Apply since/until/actionId bounds to an event list. */
+export function filterEvents(events, options) {
+    return events.filter((event) => (options.since === undefined || event.t >= options.since) &&
+        (options.until === undefined || event.t <= options.until) &&
+        (options.actionId === undefined || event.actionId === options.actionId));
+}

package/dist/memory/journal/journal-recorder.d.ts

@@ -0,0 +1,109 @@
+import { type JournalAction, type JournalWriteLoss, type ReticleEvent } from '@reticlehq/core';
+/** Where a recorder persists. `SessionJournal` satisfies this structurally. */
+export interface JournalSink {
+    appendEvents(events: readonly ReticleEvent[]): Promise<void>;
+    appendAction(action: JournalAction): Promise<void>;
+}
+/**
+ * What a durable read could NOT produce — the report that travels beside the events.
+ *
+ * The journal is append-only and one session's file is never pruned, so a long-lived session's
+ * ledger outgrows what a JavaScript string can hold and the read has to stop somewhere; and what a
+ * reader keeps across many reads has to stop somewhere too. Where it stopped is not a detail: an
+ * agent reading a short answer it cannot tell apart from a complete one is the false green this
+ * whole layer exists to prevent. Absent means nothing was lost.
+ */
+export interface JournalReadLoss {
+    /**
+     * Journal bytes not represented in the answer — skipped past by a read that would have exceeded
+     * its ceiling, plus the bytes of records evicted after parsing. A floor, not a total: the record
+     * straddling a cut is discarded with them and is not counted here.
+     */
+    droppedBytes: number;
+    /** Parsed records evicted from the retained set. Exact, unlike `droppedBytes`. */
+    droppedEvents: number;
+    /**
+     * Latest timestamp of parsed cache evictions, inclusive. Omitted after a byte cut skips
+     * unparsed records: their time range is unknown even when newer bytes survive.
+     */
+    lostThroughT?: number;
+    /** Human-and-agent readable summary. Present so a consumer never has to compose one. */
+    note: string;
+}
+/** Read side of the durable journal — the fall-through source when the ring buffer has evicted. */
+export interface JournalReader {
+    readEvents(): Promise<ReticleEvent[]>;
+    /**
+     * The action ledger. Optional because a test double is a partial reader, and nothing that only
+     * needs events should be forced to grow a second method to satisfy the type.
+     */
+    readActions?(): Promise<JournalAction[]>;
+    /**
+     * What the reads so far could not reach. Optional on the same reasoning as `readActions`: a reader
+     * that omits it declares no loss, which is the behaviour every partial double already had.
+     */
+    readLoss?(): JournalReadLoss | undefined;
+    /**
+     * What the WRITER could not put on disk: the ledger's closure report, when its byte ceiling
+     * refused a batch. `undefined` means nothing was refused.
+     *
+     * Optional for the same reason `readActions` is, and absence means NOT MEASURED rather than "no
+     * loss" — a reader that cannot answer must not be made to answer "clean". The separate question
+     * of what a bounded READ declined to hand back belongs to the reader that bounded it; this one is
+     * only ever about writes that never happened.
+     */
+    readWriteLoss?(): Promise<JournalWriteLoss | undefined>;
+}
+interface JournalRecorderOptions {
+    /** Injected elapsed-ms clock (never read from Date here — the clock-injection rule). */
+    now: () => number;
+    /** Flush the pending-event batch once this many accumulate. */
+    flushAt?: number;
+}
+/**
+ * Owns action-window attribution and batched, order-preserving journaling — the durable half of the
+ * causal spine, kept out of Session so neither file bloats. Every stamped event is `observe`d: if an
+ * action is active (dispatch→settle), the event is attributed to it (`attribution:"window"` — a time
+ * heuristic, never presented as dataflow truth) and its seq folds into the action's range. Writes are
+ * serialized on one chain so `events.jsonl` never interleaves and an action is always persisted after
+ * the events it closed. Sink writes are best-effort: a failed local journal write must never break the
+ * live session, so errors are swallowed.
+ */
+export declare class JournalRecorder {
+    #private;
+    constructor(sink: JournalSink, options: JournalRecorderOptions);
+    /**
+     * Attribute (if an action is active), enqueue for journaling, and return the possibly-stamped event.
+     *
+     * Reticle fetching its own SDK is attributed and returned like anything else but never written to
+     * disk. That is a decision about what is worth KEEPING, so it is taken here, where the journal is
+     * written, and not in a reader: a reader that hid these would leave the bytes on disk and the
+     * cost unpaid, and a second reader would still find them and disagree about what happened.
+     */
+    observe(event: ReticleEvent): ReticleEvent;
+    /** Open an attribution window. One action is active at a time (the agent drives sequentially). */
+    beginAction(actionId: string, tool: string, args: Record<string, unknown>): void;
+    /** Close the active window: persist its buffered events, then the action record. No-op if none active. */
+    finishAction(effect?: unknown, settled?: boolean, settledInMs?: number): void;
+    /**
+     * Append one action record for a tool that PROVED something without driving the page.
+     *
+     * `reticle_assert` produces a verdict and moves nothing, so it must never open an attribution
+     * window: while one is open every observed event is stamped with that action's id, and stamping
+     * ambient traffic with an assertion's id would manufacture a causal link that does not exist —
+     * exactly what `EventAttribution.WINDOW` is carefully labelled to avoid claiming. So this writes
+     * the record and leaves `#active` precisely as it found it: an act window open across an assert
+     * keeps attributing to itself, which is the truth of what caused those events.
+     *
+     * `settled` is left unset for the same reason — nothing was dispatched, so there is no settle
+     * outcome to report, and the run fold skips actions that state none rather than inventing one.
+     *
+     * Ordering rides the same chain as `finishAction`: buffered events flush first, so a record is
+     * always persisted after the events that preceded it. Records land in the order verdicts were
+     * REACHED, so an assert taken mid-window is written before the act it interrupted.
+     */
+    recordAction(actionId: string, tool: string, args: Record<string, unknown>, effect?: unknown): void;
+    /** Persist any buffered events now (call on session end). Awaits the write chain to settle. */
+    flush(): Promise<void>;
+}
+export {};

package/dist/memory/journal/journal-recorder.js

@@ -0,0 +1,153 @@
+import { EventAttribution, JOURNAL_FILE_VERSION, } from '@reticlehq/core';
+import { isSelfObservation } from './self-observation.js';
+import { log } from '../../log.js';
+/**
+ * Logged the FIRST time a journal write is lost, and never again for that recorder.
+ *
+ * The swallow stays — a failed local journal write must never break a live session, and a tool call
+ * is not the place to learn the disk is full. But a loss that says nothing is how a journal wrote
+ * nothing for a whole session while the session reported healthy and reads kept answering from the
+ * in-memory cache. Once per recorder, on the existing daemon-log channel: enough to find in the
+ * daemon log when somebody asks why a journal file is short, quiet enough that a full disk does not
+ * produce one line per batch.
+ */
+const JOURNAL_WRITE_LOST = 'journal_write_lost';
+const DEFAULT_FLUSH_AT = 64;
+/**
+ * Owns action-window attribution and batched, order-preserving journaling — the durable half of the
+ * causal spine, kept out of Session so neither file bloats. Every stamped event is `observe`d: if an
+ * action is active (dispatch→settle), the event is attributed to it (`attribution:"window"` — a time
+ * heuristic, never presented as dataflow truth) and its seq folds into the action's range. Writes are
+ * serialized on one chain so `events.jsonl` never interleaves and an action is always persisted after
+ * the events it closed. Sink writes are best-effort: a failed local journal write must never break the
+ * live session, so errors are swallowed.
+ */
+export class JournalRecorder {
+    #sink;
+    #now;
+    #flushAt;
+    #pending = [];
+    #active;
+    #chain = Promise.resolve();
+    #lossReported = false;
+    constructor(sink, options) {
+        this.#sink = sink;
+        this.#now = options.now;
+        this.#flushAt = options.flushAt ?? DEFAULT_FLUSH_AT;
+    }
+    /**
+     * Attribute (if an action is active), enqueue for journaling, and return the possibly-stamped event.
+     *
+     * Reticle fetching its own SDK is attributed and returned like anything else but never written to
+     * disk. That is a decision about what is worth KEEPING, so it is taken here, where the journal is
+     * written, and not in a reader: a reader that hid these would leave the bytes on disk and the
+     * cost unpaid, and a second reader would still find them and disagree about what happened.
+     */
+    observe(event) {
+        let out = event;
+        const active = this.#active;
+        if (active !== undefined) {
+            out = { ...event, actionId: active.actionId, attribution: EventAttribution.WINDOW };
+            if ('number' === typeof event.seq) {
+                active.seqFrom =
+                    active.seqFrom === undefined ? event.seq : Math.min(active.seqFrom, event.seq);
+                active.seqTo = active.seqTo === undefined ? event.seq : Math.max(active.seqTo, event.seq);
+            }
+        }
+        // Attribution above still runs, and the return value is what the live ring buffer stores — the
+        // session keeps seeing this event. What is declined is the DURABLE copy: see isSelfObservation.
+        if (!isSelfObservation(out)) {
+            this.#pending.push(out);
+            if (this.#pending.length >= this.#flushAt)
+                this.#enqueueFlush();
+        }
+        return out;
+    }
+    /** Open an attribution window. One action is active at a time (the agent drives sequentially). */
+    beginAction(actionId, tool, args) {
+        this.#active = { actionId, tool, args, tStart: this.#now() };
+    }
+    /** Close the active window: persist its buffered events, then the action record. No-op if none active. */
+    finishAction(effect, settled, settledInMs) {
+        const active = this.#active;
+        if (active === undefined)
+            return;
+        this.#active = undefined;
+        const action = {
+            v: JOURNAL_FILE_VERSION,
+            actionId: active.actionId,
+            tool: active.tool,
+            args: active.args,
+            effect,
+            settled,
+            settledInMs,
+            seqRange: active.seqFrom === undefined || active.seqTo === undefined
+                ? undefined
+                : { from: active.seqFrom, to: active.seqTo },
+            tRange: { from: active.tStart, to: this.#now() },
+            at: active.tStart,
+        };
+        this.#enqueueFlush();
+        this.#chain = this.#chain
+            .then(() => this.#sink.appendAction(action))
+            .catch((error) => this.#reportLoss(error));
+    }
+    /**
+     * Append one action record for a tool that PROVED something without driving the page.
+     *
+     * `reticle_assert` produces a verdict and moves nothing, so it must never open an attribution
+     * window: while one is open every observed event is stamped with that action's id, and stamping
+     * ambient traffic with an assertion's id would manufacture a causal link that does not exist —
+     * exactly what `EventAttribution.WINDOW` is carefully labelled to avoid claiming. So this writes
+     * the record and leaves `#active` precisely as it found it: an act window open across an assert
+     * keeps attributing to itself, which is the truth of what caused those events.
+     *
+     * `settled` is left unset for the same reason — nothing was dispatched, so there is no settle
+     * outcome to report, and the run fold skips actions that state none rather than inventing one.
+     *
+     * Ordering rides the same chain as `finishAction`: buffered events flush first, so a record is
+     * always persisted after the events that preceded it. Records land in the order verdicts were
+     * REACHED, so an assert taken mid-window is written before the act it interrupted.
+     */
+    recordAction(actionId, tool, args, effect) {
+        const at = this.#now();
+        const action = {
+            v: JOURNAL_FILE_VERSION,
+            actionId,
+            tool,
+            args,
+            effect,
+            // No window was opened, so no event carries this id: `seqRange` is omitted rather than
+            // invented, because any range here would claim an attribution that never happened. `tRange` is
+            // required by the schema and the honest value is the instant the verdict was recorded — a span
+            // of zero, which is exactly how much time this action attributed events over.
+            tRange: { from: at, to: at },
+            at,
+        };
+        this.#enqueueFlush();
+        this.#chain = this.#chain
+            .then(() => this.#sink.appendAction(action))
+            .catch((error) => this.#reportLoss(error));
+    }
+    /** Persist any buffered events now (call on session end). Awaits the write chain to settle. */
+    async flush() {
+        this.#enqueueFlush();
+        await this.#chain;
+    }
+    #enqueueFlush() {
+        if (0 === this.#pending.length)
+            return;
+        const batch = this.#pending;
+        this.#pending = [];
+        this.#chain = this.#chain
+            .then(() => this.#sink.appendEvents(batch))
+            .catch((error) => this.#reportLoss(error));
+    }
+    /** Swallow a lost write, but say so once. See JOURNAL_WRITE_LOST. */
+    #reportLoss(error) {
+        if (this.#lossReported)
+            return;
+        this.#lossReported = true;
+        log(JOURNAL_WRITE_LOST, { error: error instanceof Error ? error.message : String(error) });
+    }
+}

package/dist/memory/journal/on-disk/ambient-file.d.ts

@@ -0,0 +1,21 @@
+import { z } from 'zod';
+/**
+ * The shape of the file the learned ambient map is kept in.
+ *
+ * Only the storing of the map lives here. What counts as background churn is a judgement about what
+ * happened on the page, and that reasoning sits with the rules that decide a verdict, in
+ * `events/ambient.ts`.
+ *
+ * Example of a valid file: `{ "version": 1, "regions": { "#chat-feed": 43 } }` — the chat feed has
+ * changed on its own forty-three times, with no action to explain it.
+ */
+export declare const AmbientFileSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    regions: z.ZodRecord<z.ZodString, z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    version: 1;
+    regions: Record<string, number>;
+}, {
+    version: 1;
+    regions: Record<string, number>;
+}>;