@reticlehq/server 2.14.0 → 3.2.0

package/dist/bridge/bridge.test-harness.d.ts

@@ -1,65 +0,0 @@
-import { type ElementQuery } from '@reticlehq/core';
-import type { Bridge } from './bridge.js';
-import { type ToolDeps } from '../tools/tools.js';
-/** A stand-in for the real @reticlehq/browser SDK: replies to commands and emits events. */
-export declare class FakeBrowser {
-    #private;
-    private readonly sessionId;
-    private readonly hasCapabilities;
-    matcher: (query: ElementQuery) => boolean;
-    /** When false, the browser pretends it has no CAPABILITIES handler (older build). */
-    handlesCapabilities: boolean;
-    /** When false, ACT results omit a testid (element has no data-testid → unstable step). */
-    actHasTestid: boolean;
-    /** Provenance the real browser captures alongside the anchor; undefined = app built without it. */
-    actSource: {
-        file: string;
-        line: number;
-    } | undefined;
-    /** DOM mutations the browser counted inside the acted element; undefined = it counted none. */
-    actMutatedWithin: number | undefined;
-    /** when false, ACT reports settled:false + settleReason:'timeout' (throttled-tab path). */
-    actSettled: boolean;
-    /** When false, QUERY by testid returns no match (testid not in current DOM at replay). */
-    queryResolves: boolean;
-    /** Records every command the bridge sent (for replay assertions). */
-    readonly received: {
-        name: string;
-        args: Record<string, unknown>;
-    }[];
-    /**
-     * The snapshot tree to return. Mutable so tests can vary the page between calls.
-     *
-     * The counters are optional because the fields they stand for are: the browser omits `nodes`-
-     * adjacent diagnostics on a page that has nothing to report, and a test asserting on one has to be
-     * able to send a payload shaped like the real thing.
-     */
-    snapshotResult: {
-        tree: string;
-        status: Record<string, unknown>;
-        nodes?: number;
-        hiddenSkipped?: number;
-        leanSkipped?: number;
-    };
-    constructor(port: number, sessionId: string, hasCapabilities?: boolean);
-    open(): Promise<void>;
-    /** Re-send the HELLO on the live socket, the way the SDK does when capabilities register late. */
-    reannounce(overrides?: {
-        sessionId?: string;
-        hasCapabilities?: boolean;
-    }): void;
-    emit(type: string, data: Record<string, unknown>, ref?: string): void;
-    close(): void;
-}
-/**
- * Poll until `cond` holds.
- *
- * The default was 2000ms and the fifty-browser test blew it on the Windows runner at 5155ms — a
- * statement about the machine, not about the bridge. Raising it is safe in a way that raising a
- * fixed sleep would not be: this POLLS every 10ms and resolves the instant the condition holds, so
- * a passing test is not slowed by one millisecond and only a genuinely failing one waits longer.
- */
-export declare function waitUntil(cond: () => boolean, timeoutMs?: number): Promise<void>;
-export declare const callTool: (deps: ToolDeps, name: string, args?: Record<string, unknown>) => Promise<unknown>;
-/** Builds the ToolDeps wired to a running bridge, with a frozen clock for deterministic tests. */
-export declare function makeDeps(bridge: Bridge): ToolDeps;

package/dist/bridge/bridge.test-harness.js

@@ -1,230 +0,0 @@
-import { WebSocket } from 'ws';
-import { RETICLE_WS_PATH, ReticleCommand, LOOPBACK_HOST, MessageKind, } from '@reticlehq/core';
-import { BaselineStore } from '../project/baselines.js';
-import { createNodeFileSystem } from '../project/fs-port.js';
-import { RecordingStore } from '../flows/recordings.js';
-import { FlowStore } from '../flows/flows.js';
-import { ProjectStore } from '../project/project-store.js';
-import { AnnotationStore } from '../flows/annotation-store.js';
-import { TOOLS } from '../tools/tools.js';
-/** The app-advertised testable surface a FakeBrowser reports for an reticle_capabilities round-trip. */
-const FAKE_CAPABILITIES = {
-    testids: ['toast'],
-    signals: ['webhook:received'],
-    stores: ['cart'],
-    flows: [{ name: 'pay', steps: ['fill', 'click'] }],
-};
-/** A stand-in for the real @reticlehq/browser SDK: replies to commands and emits events. */
-export class FakeBrowser {
-    sessionId;
-    hasCapabilities;
-    #ws;
-    matcher = () => false;
-    /** When false, the browser pretends it has no CAPABILITIES handler (older build). */
-    handlesCapabilities = true;
-    /** When false, ACT results omit a testid (element has no data-testid → unstable step). */
-    actHasTestid = true;
-    /** Provenance the real browser captures alongside the anchor; undefined = app built without it. */
-    actSource = undefined;
-    /** DOM mutations the browser counted inside the acted element; undefined = it counted none. */
-    actMutatedWithin = undefined;
-    /** when false, ACT reports settled:false + settleReason:'timeout' (throttled-tab path). */
-    actSettled = true;
-    /** When false, QUERY by testid returns no match (testid not in current DOM at replay). */
-    queryResolves = true;
-    /** Records every command the bridge sent (for replay assertions). */
-    received = [];
-    /**
-     * The snapshot tree to return. Mutable so tests can vary the page between calls.
-     *
-     * The counters are optional because the fields they stand for are: the browser omits `nodes`-
-     * adjacent diagnostics on a page that has nothing to report, and a test asserting on one has to be
-     * able to send a payload shaped like the real thing.
-     */
-    snapshotResult = {
-        tree: '- button "Pay" (ref=e7)\n- dialog "Order confirmed" (ref=e12)',
-        status: { route: '/checkout' },
-    };
-    constructor(port, sessionId, hasCapabilities = false) {
-        this.sessionId = sessionId;
-        this.hasCapabilities = hasCapabilities;
-        // Real browsers always send an Origin on the WS handshake; simulate a loopback app page.
-        this.#ws = new WebSocket(`ws://${LOOPBACK_HOST}:${String(port)}${RETICLE_WS_PATH}`, {
-            origin: 'http://localhost',
-        });
-    }
-    open() {
-        return new Promise((resolve) => {
-            this.#ws.on('open', () => {
-                this.#send({
-                    kind: MessageKind.HELLO,
-                    protocolVersion: 1,
-                    sessionId: this.sessionId,
-                    url: 'http://localhost:3000/checkout',
-                    title: 'Checkout',
-                    adapters: [],
-                    hasCapabilities: this.hasCapabilities,
-                });
-                this.#ws.on('message', (raw) => {
-                    this.#onMessage(JSON.parse(raw.toString('utf8')));
-                });
-                resolve();
-            });
-        });
-    }
-    /** Re-send the HELLO on the live socket, the way the SDK does when capabilities register late. */
-    reannounce(overrides = {}) {
-        this.#send({
-            kind: MessageKind.HELLO,
-            protocolVersion: 1,
-            sessionId: overrides.sessionId ?? this.sessionId,
-            url: 'http://localhost:3000/checkout',
-            title: 'Checkout',
-            adapters: [],
-            hasCapabilities: overrides.hasCapabilities ?? this.hasCapabilities,
-        });
-    }
-    emit(type, data, ref) {
-        this.#send({
-            kind: MessageKind.EVENT,
-            event: { t: 0, type, sessionId: this.sessionId, ref, data },
-        });
-    }
-    close() {
-        this.#ws.close();
-    }
-    #onMessage(msg) {
-        if (msg['kind'] !== MessageKind.COMMAND)
-            return;
-        const id = msg['id'];
-        const name = msg['name'];
-        const args = (msg['args'] ?? {});
-        this.received.push({ name, args });
-        let result = { ok: true };
-        if (name === ReticleCommand.ACT) {
-            result = {
-                ok: true,
-                ref: args['ref'],
-                action: args['action'],
-                dispatched: true,
-                settled: this.actSettled,
-                settleReason: this.actSettled ? null : 'timeout',
-                effect: {
-                    dispatched: true,
-                    ...(this.actMutatedWithin === undefined
-                        ? {}
-                        : { domMutatedWithin: this.actMutatedWithin }),
-                },
-                ...(this.actHasTestid ? { testid: 'pay-btn' } : {}),
-                ...(this.actSource === undefined ? {} : { source: this.actSource }),
-            };
-        }
-        else if (name === ReticleCommand.ACT_SEQUENCE) {
-            const steps = (Array.isArray(args['steps']) ? args['steps'] : []);
-            result = {
-                count: steps.length,
-                steps: steps.map((s) => ({
-                    ref: s['ref'],
-                    action: s['action'],
-                    ...(this.actHasTestid ? { testid: 'pay-btn' } : {}),
-                    ...(this.actSource === undefined ? {} : { source: this.actSource }),
-                })),
-            };
-        }
-        else if (name === ReticleCommand.QUERY) {
-            result = {
-                elements: this.queryResolves
-                    ? [{ ref: 'e7', role: 'button', name: 'Pay', states: [], visible: true }]
-                    : [],
-            };
-        }
-        else if (name === ReticleCommand.MATCH) {
-            const query = (args['query'] ?? {});
-            const matched = this.matcher(query);
-            result = {
-                matched,
-                count: matched ? 1 : 0,
-                elements: matched
-                    ? [
-                        {
-                            ref: 'e12',
-                            role: 'dialog',
-                            name: 'Order confirmed',
-                            states: ['visible'],
-                            visible: true,
-                        },
-                    ]
-                    : [],
-            };
-        }
-        else if (name === ReticleCommand.STATE_READ) {
-            result = {
-                stores: { workspace: { tab: 'workspace' === args['store'] ? 'open' : 'all' } },
-                storeNames: ['workspace'],
-                component: args['ref'] !== undefined ? { component: 'PayButton', hooks: [0] } : undefined,
-            };
-        }
-        else if (name === ReticleCommand.SNAPSHOT) {
-            result = this.snapshotResult;
-        }
-        else if (name === ReticleCommand.CAPABILITIES) {
-            if (!this.handlesCapabilities) {
-                this.#send({
-                    kind: MessageKind.COMMAND_RESULT,
-                    id,
-                    ok: false,
-                    error: `unknown command '${name}'`,
-                });
-                return;
-            }
-            result = FAKE_CAPABILITIES;
-        }
-        this.#send({ kind: MessageKind.COMMAND_RESULT, id, ok: true, result });
-    }
-    #send(obj) {
-        this.#ws.send(JSON.stringify(obj));
-    }
-}
-/**
- * Poll until `cond` holds.
- *
- * The default was 2000ms and the fifty-browser test blew it on the Windows runner at 5155ms — a
- * statement about the machine, not about the bridge. Raising it is safe in a way that raising a
- * fixed sleep would not be: this POLLS every 10ms and resolves the instant the condition holds, so
- * a passing test is not slowed by one millisecond and only a genuinely failing one waits longer.
- */
-export function waitUntil(cond, timeoutMs = 15_000) {
-    return new Promise((resolve, reject) => {
-        const start = Date.now();
-        const tick = () => {
-            if (cond())
-                return resolve();
-            if (Date.now() - start > timeoutMs)
-                return reject(new Error('waitUntil timed out'));
-            setTimeout(tick, 10);
-        };
-        tick();
-    });
-}
-export const callTool = (deps, name, args = {}) => {
-    const tool = TOOLS.find((t) => t.name === name);
-    if (tool === undefined)
-        throw new Error(`no tool ${name}`);
-    return tool.handler(deps, args);
-};
-/** Builds the ToolDeps wired to a running bridge, with a frozen clock for deterministic tests. */
-export function makeDeps(bridge) {
-    return {
-        sessions: bridge.sessions,
-        baselines: new BaselineStore(),
-        recordings: new RecordingStore(),
-        flows: new FlowStore(createNodeFileSystem(), '/tmp/reticle-test/.reticle', { now: () => 0 }),
-        project: new ProjectStore(createNodeFileSystem(), '/tmp/reticle-test/.reticle', {
-            now: () => 0,
-        }),
-        annotations: new AnnotationStore(),
-        fs: createNodeFileSystem(),
-        reticleRoot: '/tmp/reticle-test/.reticle',
-        now: () => 0,
-    };
-}

package/dist/capsule/capsule-store.d.ts

@@ -1,71 +0,0 @@
-import { z } from 'zod';
-import { type FlowStep } from '@reticlehq/core';
-import type { FileSystemPort } from '../project/fs-port.js';
-/**
- * Bug capsules. When an assertion fails, the evidence that explains it is in hand exactly once —
- * at the moment of the failure. A capsule persists that moment as a *replayable artifact*: the minimal
- * failing steps, the consequence that was supposed to hold, and the divergence that was observed instead.
- *
- * This is deliberately fail-to-pass shaped (SWE-bench style): a capsule reproduces a bug NOW and, once the
- * fix lands, it is exactly a regression flow. Capsules are ordinary flow files plus evidence, so they
- * replay through the existing machinery rather than needing a second runner.
- */
-/**
- * The capsule file-format version. Declared ABOVE the schema so the schema, the writer and this
- * constant cannot disagree: the number was previously written as a bare `1` in three places — here,
- * in the schema literal, and in act-capsule's writer — with the named one used by nobody.
- */
-export declare const CAPSULE_VERSION = 1;
-declare const CapsuleSchema: z.ZodObject<{
-    version: z.ZodLiteral<1>;
-    id: z.ZodString;
-    /** The flow the failure happened in, when it came from one (a bare assert has no flow). */
-    flow: z.ZodOptional<z.ZodString>;
-    createdAt: z.ZodNumber;
-    /** Why it was captured — a failed assertion, a crawl anomaly, a human review pin. */
-    origin: z.ZodString;
-    /** The consequence that was supposed to hold. */
-    expected: z.ZodString;
-    /** What was observed instead — the first-divergence sentence. */
-    observed: z.ZodString;
-    /** Minimal steps to reproduce (prefix-trimmed). */
-    steps: z.ZodArray<z.ZodType<FlowStep, z.ZodTypeDef, FlowStep>, "many">;
-}, "strip", z.ZodTypeAny, {
-    origin: string;
-    expected: string;
-    id: string;
-    version: 1;
-    steps: FlowStep[];
-    observed: string;
-    createdAt: number;
-    flow?: string | undefined;
-}, {
-    origin: string;
-    expected: string;
-    id: string;
-    version: 1;
-    steps: FlowStep[];
-    observed: string;
-    createdAt: number;
-    flow?: string | undefined;
-}>;
-export type Capsule = z.infer<typeof CapsuleSchema>;
-/** Capsule ids are filenames — refuse anything that could escape the capsules directory. */
-export declare function isValidCapsuleId(id: string): boolean;
-export declare class CapsuleStore {
-    #private;
-    constructor(fs: FileSystemPort, root: string);
-    /** Persist a capsule. Best-effort by design: capturing evidence must never fail the run that found it. */
-    save(capsule: Capsule): Promise<boolean>;
-    /** Capsule ids on disk, newest-first by id (ids are time-prefixed). Never throws. */
-    list(): Promise<string[]>;
-    /** Read one capsule; undefined when missing or malformed (never throws). */
-    read(id: string): Promise<Capsule | undefined>;
-    /** Every readable capsule, newest-first — what `reticle capsules` prints. */
-    all(): Promise<Capsule[]>;
-}
-/** Deterministic, path-safe capsule id: time-ordered so `list` sorts newest-first for free. */
-export declare function capsuleId(now: number, label: string): string;
-/** The minimal reproduction: the steps up to and including the one that failed (prefix trim). */
-export declare function minimalSteps(steps: readonly FlowStep[], failedIndex: number): FlowStep[];
-export {};

package/dist/capsule/capsule-store.js

@@ -1,114 +0,0 @@
-import { join } from 'node:path';
-import { z } from 'zod';
-import { FlowStepSchema } from '@reticlehq/core';
-import { reticleDirPaths } from '../project/reticle-dir.js';
-/**
- * Bug capsules. When an assertion fails, the evidence that explains it is in hand exactly once —
- * at the moment of the failure. A capsule persists that moment as a *replayable artifact*: the minimal
- * failing steps, the consequence that was supposed to hold, and the divergence that was observed instead.
- *
- * This is deliberately fail-to-pass shaped (SWE-bench style): a capsule reproduces a bug NOW and, once the
- * fix lands, it is exactly a regression flow. Capsules are ordinary flow files plus evidence, so they
- * replay through the existing machinery rather than needing a second runner.
- */
-/**
- * The capsule file-format version. Declared ABOVE the schema so the schema, the writer and this
- * constant cannot disagree: the number was previously written as a bare `1` in three places — here,
- * in the schema literal, and in act-capsule's writer — with the named one used by nobody.
- */
-export const CAPSULE_VERSION = 1;
-const CapsuleSchema = z.object({
-    version: z.literal(CAPSULE_VERSION),
-    id: z.string(),
-    /** The flow the failure happened in, when it came from one (a bare assert has no flow). */
-    flow: z.string().optional(),
-    createdAt: z.number(),
-    /** Why it was captured — a failed assertion, a crawl anomaly, a human review pin. */
-    origin: z.string(),
-    /** The consequence that was supposed to hold. */
-    expected: z.string(),
-    /** What was observed instead — the first-divergence sentence. */
-    observed: z.string(),
-    /** Minimal steps to reproduce (prefix-trimmed). */
-    steps: z.array(FlowStepSchema),
-});
-/** Capsule ids are filenames — refuse anything that could escape the capsules directory. */
-export function isValidCapsuleId(id) {
-    return /^[a-zA-Z0-9._-]+$/.test(id) && id !== '.' && id !== '..' && id.length <= 128;
-}
-export class CapsuleStore {
-    #fs;
-    #dir;
-    constructor(fs, root) {
-        this.#fs = fs;
-        this.#dir = reticleDirPaths(root).capsules;
-    }
-    #pathFor(id) {
-        return join(this.#dir, `${id}.json`);
-    }
-    /** Persist a capsule. Best-effort by design: capturing evidence must never fail the run that found it. */
-    async save(capsule) {
-        if (!isValidCapsuleId(capsule.id))
-            return false;
-        try {
-            await this.#fs.mkdir(this.#dir);
-            const tmp = `${this.#pathFor(capsule.id)}.tmp`;
-            await this.#fs.writeFile(tmp, `${JSON.stringify(capsule, null, 2)}\n`);
-            await this.#fs.rename(tmp, this.#pathFor(capsule.id));
-            return true;
-        }
-        catch {
-            return false;
-        }
-    }
-    /** Capsule ids on disk, newest-first by id (ids are time-prefixed). Never throws. */
-    async list() {
-        try {
-            if (!(await this.#fs.exists(this.#dir)))
-                return [];
-            const entries = await this.#fs.readdir(this.#dir);
-            return entries
-                .filter((e) => e.endsWith('.json'))
-                .map((e) => e.slice(0, -'.json'.length))
-                .sort()
-                .reverse();
-        }
-        catch {
-            return [];
-        }
-    }
-    /** Read one capsule; undefined when missing or malformed (never throws). */
-    async read(id) {
-        if (!isValidCapsuleId(id))
-            return undefined;
-        try {
-            const parsed = JSON.parse(await this.#fs.readFile(this.#pathFor(id)));
-            const result = CapsuleSchema.safeParse(parsed);
-            return result.success ? result.data : undefined;
-        }
-        catch {
-            return undefined;
-        }
-    }
-    /** Every readable capsule, newest-first — what `reticle capsules` prints. */
-    async all() {
-        const out = [];
-        for (const id of await this.list()) {
-            const capsule = await this.read(id);
-            if (capsule !== undefined)
-                out.push(capsule);
-        }
-        return out;
-    }
-}
-/** Deterministic, path-safe capsule id: time-ordered so `list` sorts newest-first for free. */
-export function capsuleId(now, label) {
-    const safe = label.replace(/[^a-zA-Z0-9._-]/g, '-').slice(0, 40);
-    return `${String(now)}-${safe.length > 0 ? safe : 'capsule'}`;
-}
-/** The minimal reproduction: the steps up to and including the one that failed (prefix trim). */
-export function minimalSteps(steps, failedIndex) {
-    if (failedIndex < 0)
-        return [...steps];
-    return steps.slice(0, failedIndex + 1);
-}

package/dist/capsule/capsule.d.ts

@@ -1,18 +0,0 @@
-import { type ReticleEvent } from '@reticlehq/core';
-import { type CausalSummary } from './causal-summary.js';
-import { type Divergence, type ExpectedLink } from './divergence.js';
-/**
- * The divergence capsule (Tier 2) — the whole packet on a red: the attributed causal summary, the
- * FIRST divergence (where declared ≠ observed), and the BLAST RADIUS (truth that changed OUTSIDE the
- * declared consequence — an act that also fired an undeclared signal or mutated an unexpected store).
- * Blast radius is how a "green" that did extra damage still gets caught. Pure composition of the parts;
- * the paste-ready repair packet and wiring onto red results build on this.
- */
-export interface DivergenceCapsule {
-    summary: CausalSummary;
-    firstDivergence: Divergence | null;
-    /** Observed consequences not in the declared set — unexpected side effects. */
-    blastRadius: string[];
-}
-/** Compose the full capsule from the declared chain and the observed (attributed) event window. */
-export declare function buildDivergenceCapsule(expected: readonly ExpectedLink[], observed: readonly ReticleEvent[], truncated?: boolean): DivergenceCapsule;

package/dist/capsule/capsule.js

@@ -1,35 +0,0 @@
-import { ConsequenceKind, EventType } from '@reticlehq/core';
-import { causalSummary } from './causal-summary.js';
-import { firstDivergence } from './divergence.js';
-/** Observed signal/state changes the flow never declared — the side effects. */
-function blastRadius(expected, observed) {
-    const declaredSignals = new Set(expected
-        .filter((l) => ConsequenceKind.SIGNAL === l.kind)
-        .map((l) => l.name));
-    const declaredStates = new Set(expected
-        .filter((l) => ConsequenceKind.STATE === l.kind)
-        .map((l) => l.name));
-    const radius = [];
-    const add = (value) => {
-        if (!radius.includes(value))
-            radius.push(value);
-    };
-    for (const event of observed) {
-        const name = event.data['name'];
-        if (typeof name !== 'string')
-            continue;
-        if (event.type === EventType.SIGNAL && !declaredSignals.has(name))
-            add(`signal ${name}`);
-        if (event.type === EventType.STATE_CHANGE && !declaredStates.has(name))
-            add(`state ${name}`);
-    }
-    return radius;
-}
-/** Compose the full capsule from the declared chain and the observed (attributed) event window. */
-export function buildDivergenceCapsule(expected, observed, truncated = false) {
-    return {
-        summary: causalSummary(observed, { truncated }),
-        firstDivergence: firstDivergence(expected, observed, truncated),
-        blastRadius: blastRadius(expected, observed),
-    };
-}

package/dist/capsule/causal-summary.d.ts

@@ -1,119 +0,0 @@
-import { type ReticleEvent } from '@reticlehq/core';
-/**
- * The causal summary (Tier 1) — the bounded ~50–100 token block on EVERY act, green included: what the
- * app did in the act's window, as counts + a headline, not a raw event dump. Diffs come from the
- * storage/state events; attribution from. Pure composition over the attributed event window.
- */
-interface StateDiff {
-    path: string;
-    from: unknown;
-    to: unknown;
-    /**
-     * WHEN this path moved, in the session's elapsed ms.
-     *
-     * The whole reason a transient was invisible. A store that ends internally consistent can have been
-     * inconsistent on the way there, and a from→to pair cannot express that — measured on a real
-     * merchant dashboard, an account switch moved `accountId` immediately and `payments` 160 ms later,
-     * so for 160 ms the header named one tenant while the rows belonged to another. Both diffs were
-     * reported; nothing said they were 160 ms apart, and waiting for the page to settle is by
-     * construction waiting for the evidence to disappear. The timestamp was on the event all along.
-     */
-    atMs: number;
-}
-interface StorageDiff {
-    key: string;
-    from?: unknown;
-    to?: unknown;
-}
-export interface CausalSummary {
-    /**
-     * `total`/`errors` describe the APP's traffic. `ignoredDevTooling` is the count of calls the dev
-     * toolchain made about itself (Next's error overlay, HMR, the Vite client — see
-     * `DevToolingChannel`), which Reticle deliberately leaves out of the settle decision and out of
-     * contradiction hunting. Present only when there were any: a trim is never silent, so an agent can
-     * always see that something was ignored and go read it in the timeline.
-     */
-    net: {
-        total: number;
-        errors: number;
-        ignoredDevTooling?: number;
-        headline?: string;
-    };
-    consoleErrors: number;
-    statePathsChanged: string[];
-    storageKeysChanged: string[];
-    /** Before→after for each changed store path — the diffs, not just the names. Values capped. */
-    stateDiffs: StateDiff[];
-    /**
-     * How long the store took to stop moving: last state change − first, in ms. Present only when more
-     * than one path changed, because with a single change there is no interval to describe.
-     *
-     * A FACT, not a verdict. Many apps update progressively and that is fine; calling every stagger a
-     * defect would make this a noise generator. But a non-zero value is the exact window in which the
-     * UI showed a MIXTURE of old and new, and that window is where the tenant-mismatch class of bug
-     * lives — so it is stated once, cheaply, and the agent decides.
-     */
-    stateSettleMs?: number;
-    /** Before→after for each changed storage key. Values capped. */
-    storageDiffs: StorageDiff[];
-    /**
-     * How many entries each list dropped to stay within MAX_SUMMARY_ENTRIES. Present only when
-     * something was dropped, so a trim is never silent — the same rule `ignoredDevTooling` follows.
-     */
-    elided?: Partial<Record<CappedList, number>>;
-    route?: string;
-    signals: string[];
-    layoutShift?: number;
-    longTasks: number;
-    /**
-     * TRUE when no store was subscribed, so `statePathsChanged`/`stateDiffs` are empty because nothing
-     * was watching — not because the app changed nothing.
-     *
-     * The two readings are the same empty list, and the wrong one is the one an agent takes: "state
-     * did not change" is a claim about the app, and this codebase would rather say "I could not see"
-     * than say something confident and wrong. Present only when the channel is dark, so a wired app
-     * pays nothing and the field's PRESENCE is what carries the meaning — the same rule
-     * `stateSettleMs` and `elided` follow.
-     */
-    stateUnwatched?: true;
-    /**
-     * TRUE when the ring buffer evicted events belonging to this window, so every count and list here
-     * is a FLOOR, not a total — `net.total: 0` means "none survived", never "none happened".
-     *
-     * The same distinction `stateUnwatched` draws, from the other cause, and it was the more expensive
-     * one. A field app rewrote one localStorage key thousands of times a minute; the no-op writes
-     * starved the buffer (`held: 2000, dropped: 70482`), and the verdict for that window reported
-     * `net.total: 0`, `stateDiffs: []` and "state never changed" — while a POST that had returned 200
-     * in that exact window carried the entire root cause in its body. The agent read the zero and was
-     * about to report "clicking Accept fires no network request", which points a developer at the
-     * click handler instead of at the payload the server rejected.
-     *
-     * `honesty.integrity.losses` already said `buffer_loss`. It was not enough: the headline fields an
-     * agent reads to form a verdict are these, and a bare `0` several levels above a nested integrity
-     * flag reads as a fact. The absolute and the caveat must not be separable, so the caveat rides on
-     * the summary that carries the absolutes.
-     */
-    truncated?: true;
-}
-/** What only the SESSION knows — level facts the event window cannot contain. See `stateUnwatched`. */
-interface SummaryContext {
-    stateUnwatched?: boolean;
-    /** Did the buffer drop events from this window — see `CausalSummary.truncated`. */
-    truncated?: boolean;
-}
-/**
- * THE INVARIANT: every field of this summary has a bounded size that does not depend on how much the
- * app did. A verdict travels in the same payload as its evidence, so an unbounded evidence field is
- * an unbounded chance that the verdict is the part a client truncates — and an agent that cannot read
- * the verdict has run the verification and got nothing, which is indistinguishable from not running
- * it. Measured: one click on a page with a registered TanStack Query store returned ~363KB, because
- * `capValue` bounded each diff and nothing bounded the COUNT of them.
- *
- * 20 keeps the signal that is actually read — the first paths to move, and the settle window over all
- * of them — while the full names of everything that changed stay one `reticle_state` call away.
- */
-export declare const MAX_SUMMARY_ENTRIES = 20;
-/** The lists that are capped, named so `elided` can say which one lost entries. */
-type CappedList = 'statePathsChanged' | 'storageKeysChanged' | 'stateDiffs' | 'storageDiffs' | 'signals';
-export declare function causalSummary(events: readonly ReticleEvent[], context?: SummaryContext): CausalSummary;
-export {};