@reticlehq/server 2.14.0 → 3.2.0

package/dist/journal/ambient.d.ts

@@ -1,47 +0,0 @@
-import { z } from 'zod';
-import type { ReticleEvent } from '@reticlehq/core';
-/**
- * Ambient-region learning. On a real-time app (chat, tickers, presence) whole DOM regions churn with
- * NO action driving them — an event with no `actionId`. Left unlearned, they make `settled` never fire
- * and flood every summary. This learns, per element ref, how often it churns ambiently; a ref past the
- * threshold is treated as ambient and excluded from the settle oracle, summaries, and envelopes. The
- * map is a learned, persisted per-app fact (like the contract) — confirmable, not silent.
- *
- * Global, not per-flow: the journal already sees the churn across every session, so the map sharpens
- * over time. Only UNATTRIBUTED churn counts — an event caused by an action is signal, never ambient.
- */
-/** Per-region ambient churn counts. */
-export type AmbientCounts = Record<string, number>;
-/**
- * The identity ambient learning counts against. Prefer the emitted `region` (the stable CONTAINER of a
- * mutation) over the element ref: a churning feed appends a NEW element every tick (fresh ref) and a
- * removed element has no ref at all, so per-ref counts never accumulate and the region is never learned.
- * The container persists, so it is the only key that converges. Falls back to the ref for events that
- * mutate a single stable element (a ticker's text).
- */
-export declare function ambientKeyOf(event: {
-    ref?: string | undefined;
-    data?: Record<string, unknown>;
-}): string | undefined;
-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>;
-}>;
-/** A ref must churn ambiently at least this many times before it is treated as ambient. */
-export declare const DEFAULT_AMBIENT_THRESHOLD = 20;
-/** Fold a batch of events into the running ambient counts. Only unattributed, ref-bearing events count. */
-export declare function accumulateAmbient(counts: AmbientCounts, events: readonly ReticleEvent[]): AmbientCounts;
-/** Whether a ref has churned ambiently often enough to be excluded from oracles/summaries. */
-export declare function isAmbient(counts: AmbientCounts, ref: string | undefined, threshold?: number): boolean;
-/**
- * Drop events on learned-ambient regions — the exclusion the settle oracle and summaries apply. An
- * action-attributed event is ALWAYS kept, even on an ambient ref: if an action caused a change there,
- * it is signal, not background churn.
- */
-export declare function excludeAmbient(counts: AmbientCounts, events: readonly ReticleEvent[], threshold?: number): ReticleEvent[];

package/dist/journal/ambient.js

@@ -1,47 +0,0 @@
-import { z } from 'zod';
-/**
- * The identity ambient learning counts against. Prefer the emitted `region` (the stable CONTAINER of a
- * mutation) over the element ref: a churning feed appends a NEW element every tick (fresh ref) and a
- * removed element has no ref at all, so per-ref counts never accumulate and the region is never learned.
- * The container persists, so it is the only key that converges. Falls back to the ref for events that
- * mutate a single stable element (a ticker's text).
- */
-export function ambientKeyOf(event) {
-    const region = event.data?.['region'];
-    if ('string' === typeof region && region.length > 0)
-        return region;
-    return event.ref;
-}
-export const AmbientFileSchema = z.object({
-    version: z.literal(1),
-    regions: z.record(z.number()),
-});
-/** A ref must churn ambiently at least this many times before it is treated as ambient. */
-export const DEFAULT_AMBIENT_THRESHOLD = 20;
-/** Fold a batch of events into the running ambient counts. Only unattributed, ref-bearing events count. */
-export function accumulateAmbient(counts, events) {
-    const next = { ...counts };
-    for (const event of events) {
-        if (event.actionId !== undefined)
-            continue; // attributed to an action → signal, not ambient
-        const key = ambientKeyOf(event);
-        if (key === undefined)
-            continue;
-        next[key] = (next[key] ?? 0) + 1;
-    }
-    return next;
-}
-/** Whether a ref has churned ambiently often enough to be excluded from oracles/summaries. */
-export function isAmbient(counts, ref, threshold = DEFAULT_AMBIENT_THRESHOLD) {
-    if (ref === undefined)
-        return false;
-    return (counts[ref] ?? 0) >= threshold;
-}
-/**
- * Drop events on learned-ambient regions — the exclusion the settle oracle and summaries apply. An
- * action-attributed event is ALWAYS kept, even on an ambient ref: if an action caused a change there,
- * it is signal, not background churn.
- */
-export function excludeAmbient(counts, events, threshold) {
-    return events.filter((event) => event.actionId !== undefined || !isAmbient(counts, event.ref, threshold));
-}

package/dist/journal/attach-journal.d.ts

@@ -1,30 +0,0 @@
-import type { FileSystemPort } from '../project/fs-port.js';
-import { JournalRecorder, type JournalReader } from './journal-recorder.js';
-/** The minimal Session surface the journal attachment needs (Session satisfies it structurally). */
-export interface JournalTarget {
-    readonly id: string;
-    /** Milliseconds since the session connected — the recorder's injected clock. */
-    elapsed(): number;
-    setJournal(recorder: JournalRecorder, reader?: JournalReader): void;
-}
-interface JournalAttachDeps {
-    fs: FileSystemPort;
-    reticleRoot: string;
-    /** Journaling is on by default; the opt-out (`.reticle.json` journal:false / env) sets this false. */
-    enabled: boolean;
-}
-/**
- * Build the per-session journal attachment the bridge fires on session creation. Off when disabled;
- * skips a session whose id is not a safe path segment (never crashes the live session over a
- * journaling concern). The recorder's clock is the session's own elapsed time.
- *
- * That skip used to be SILENT, which is the part that mattered. The id becomes a directory name, so
- * one that is not a safe path segment cannot be journalled — but the session itself connects and
- * drives perfectly well, so the only observable difference is that the durable causal record for it
- * does not exist. Every query that reads back through the journal then returns nothing, and nothing
- * anywhere says why. An app self-assigning an unusual id gets a quietly degraded session; a hostile
- * one gets the same, which is why this is worth a line either way. Nothing escapes the directory —
- * the guard holds, and that is exactly why the failure is invisible rather than loud.
- */
-export declare function makeJournalAttach(deps: JournalAttachDeps): (session: JournalTarget) => void;
-export {};

package/dist/journal/attach-journal.js

@@ -1,30 +0,0 @@
-import { log } from '../log.js';
-import { isValidSessionId } from '../project/reticle-dir.js';
-import { JournalRecorder } from './journal-recorder.js';
-import { SessionJournal } from './session-journal.js';
-/**
- * Build the per-session journal attachment the bridge fires on session creation. Off when disabled;
- * skips a session whose id is not a safe path segment (never crashes the live session over a
- * journaling concern). The recorder's clock is the session's own elapsed time.
- *
- * That skip used to be SILENT, which is the part that mattered. The id becomes a directory name, so
- * one that is not a safe path segment cannot be journalled — but the session itself connects and
- * drives perfectly well, so the only observable difference is that the durable causal record for it
- * does not exist. Every query that reads back through the journal then returns nothing, and nothing
- * anywhere says why. An app self-assigning an unusual id gets a quietly degraded session; a hostile
- * one gets the same, which is why this is worth a line either way. Nothing escapes the directory —
- * the guard holds, and that is exactly why the failure is invisible rather than loud.
- */
-export function makeJournalAttach(deps) {
-    return (session) => {
-        if (!deps.enabled)
-            return;
-        if (!isValidSessionId(session.id)) {
-            log('journal_skipped_unsafe_session_id', { sessionId: session.id });
-            return;
-        }
-        const journal = new SessionJournal(deps.fs, deps.reticleRoot, session.id);
-        // Same SessionJournal is both the write sink and the read fall-through for queries after eviction.
-        session.setJournal(new JournalRecorder(journal, { now: () => session.elapsed() }), journal);
-    };
-}

package/dist/journal/envelope-store.d.ts

@@ -1,16 +0,0 @@
-import type { FileSystemPort } from '../project/fs-port.js';
-import { type RouteEnvelope } from './envelope.js';
-/**
- * Persists the learned per-route envelopes at `.reticle/envelopes.json`. Local, single-project statistics
- * (single-player memory stays OSS — OSS-VS-SERVER). Loads never throw: a missing, malformed, or
- * wrong-version file degrades to no envelopes, so a bad baseline can never crash a drive; the deviation
- * report just falls back to the causal summary until the envelope rebuilds.
- */
-export declare class EnvelopeStore {
-    #private;
-    constructor(fs: FileSystemPort, root: string);
-    /** Absolute path of the backing file — the key a caller uses to serialize its read-modify-write. */
-    get path(): string;
-    load(): Promise<Map<string, RouteEnvelope>>;
-    save(envelopes: ReadonlyMap<string, RouteEnvelope>): Promise<void>;
-}

package/dist/journal/envelope-store.js

@@ -1,61 +0,0 @@
-import { z } from 'zod';
-import { dirname } from 'node:path';
-import { reticleDirPaths } from '../project/reticle-dir.js';
-import { RouteEnvelopeSchema } from './envelope.js';
-/** Bumped on any breaking change to the persisted envelope shape (matches the runs/contract convention). */
-const ENVELOPE_FILE_VERSION = 1;
-const EnvelopeFileSchema = z.object({
-    version: z.literal(ENVELOPE_FILE_VERSION),
-    routes: z.record(RouteEnvelopeSchema),
-});
-/**
- * Persists the learned per-route envelopes at `.reticle/envelopes.json`. Local, single-project statistics
- * (single-player memory stays OSS — OSS-VS-SERVER). Loads never throw: a missing, malformed, or
- * wrong-version file degrades to no envelopes, so a bad baseline can never crash a drive; the deviation
- * report just falls back to the causal summary until the envelope rebuilds.
- */
-export class EnvelopeStore {
-    #fs;
-    #path;
-    constructor(fs, root) {
-        this.#fs = fs;
-        this.#path = reticleDirPaths(root).envelopes;
-    }
-    /** Absolute path of the backing file — the key a caller uses to serialize its read-modify-write. */
-    get path() {
-        return this.#path;
-    }
-    async load() {
-        let text;
-        try {
-            text = await this.#fs.readFile(this.#path);
-        }
-        catch (error) {
-            if (this.#fs.isNotFound(error))
-                return new Map();
-            throw error;
-        }
-        let parsed;
-        try {
-            parsed = JSON.parse(text);
-        }
-        catch {
-            return new Map();
-        }
-        const result = EnvelopeFileSchema.safeParse(parsed);
-        if (!result.success)
-            return new Map();
-        return new Map(Object.entries(result.data.routes));
-    }
-    async save(envelopes) {
-        await this.#fs.mkdir(dirname(this.#path));
-        const routes = {};
-        for (const [route, envelope] of envelopes)
-            routes[route] = envelope;
-        const body = `${JSON.stringify({ version: ENVELOPE_FILE_VERSION, routes }, null, 2)}\n`;
-        // Atomic publish: write a temp sibling then rename, so a crash never leaves a half-written baseline.
-        const tmp = `${this.#path}.tmp`;
-        await this.#fs.writeFile(tmp, body);
-        await this.#fs.rename(tmp, this.#path);
-    }
-}

package/dist/journal/envelope.d.ts

@@ -1,230 +0,0 @@
-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;
-        };
-        consoleErrors: {
-            count: number;
-            mean: number;
-            m2: number;
-            max: number;
-        };
-        netErrors: {
-            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;
-        };
-        consoleErrors: {
-            count: number;
-            mean: number;
-            m2: number;
-            max: number;
-        };
-        netErrors: {
-            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;
-        };
-        consoleErrors: {
-            count: number;
-            mean: number;
-            m2: number;
-            max: number;
-        };
-        netErrors: {
-            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;
-        };
-        consoleErrors: {
-            count: number;
-            mean: number;
-            m2: number;
-            max: number;
-        };
-        netErrors: {
-            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/journal/journal-query.d.ts

@@ -1,32 +0,0 @@
-import type { ReticleEvent } from '@reticlehq/core';
-/** 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[];
-/** Apply since/until/actionId bounds to an event list. */
-export declare function filterEvents(events: readonly ReticleEvent[], options: EventQueryOptions): ReticleEvent[];

package/dist/journal/journal-query.js

@@ -1,52 +0,0 @@
-/**
- * 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;
-    });
-}
-/** 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/journal/journal-recorder.d.ts

@@ -1,61 +0,0 @@
-import { type JournalAction, 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>;
-}
-/** 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[]>;
-}
-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. */
-    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 {};