@reticlehq/server 2.14.0 → 3.2.0

package/dist/events/event-filters.d.ts

@@ -1,121 +0,0 @@
-import { type ReticleEvent } from '@reticlehq/core';
-/**
- * The friendly bucket names reticle_observe's `filters` param advertises → the real event types.
- *
- * The schema promised `dom | net | route | console | animation | signal`, but the handler filtered
- * with `filters.includes(e.type)` against types like `net.request` and `dom.added` — so every
- * documented value matched nothing, and an agent passing `filters:['net']` to trim its payload got an
- * EMPTY timeline instead. Empty reads as "the app did nothing" — a false green produced by using the
- * feature exactly as documented. Mapping the bucket to its member types makes the documented values
- * work; raw types are still accepted (see eventMatchesFilters) so neither spelling surprises a caller.
- */
-export declare const OBSERVE_FILTER_BUCKETS: Record<string, readonly string[]>;
-/**
- * True when an event passes an observe `filters` allowlist. A filter entry matches either as a bucket
- * name (`net` keeps every net.* type) or as a raw event type (`net.request`). Unknown entries match
- * nothing rather than throwing — a typo narrows the result, it never crashes the observe.
- */
-export declare function eventMatchesFilters(e: ReticleEvent, filters: readonly string[]): boolean;
-/**
- * Match a net.request event against optional method/url/status/ok filters (reticle_network).
- *
- * `ok` is the filter the tool's own description points at for desktop IPC, whose 200/500 is derived
- * rather than sent by any server. A still-PENDING call never matches an `ok` filter in either
- * direction: unresolved is not the same as failed, and answering "yes, it failed" about a request
- * still in flight is the false green this whole surface exists to prevent.
- */
-export declare function matchNet(e: ReticleEvent, method: string | undefined, urlContains: string | undefined, status: number | undefined, ok?: boolean): boolean;
-/**
- * Reconcile network events into completed calls + still-in-flight calls. A NET_PENDING whose
- * `id` never gets a matching NET_REQUEST is an unresolved/hung request — the case
- * completion-only logging is blind to. Pending events are annotated `{ status: 'pending',
- * pending: true }` so a numeric `status` filter excludes them but `urlContains`/`method` match.
- */
-export declare function reconcileNet(events: ReticleEvent[]): ReticleEvent[];
-/**
- * Strip the grader-only raw URL before an event is rendered to the agent.
- *
- * `urlRaw` exists so `urlContains` can match a path redaction rewrote. It is a secret-bearing field
- * by construction (the whole reason `url` was redacted) and must never appear in observe, evidence,
- * or a network listing.
- */
-export declare function withoutUrlRaw(event: unknown): unknown;
-/** Compact network-call summary for reticle_network output — drops event plumbing (t, type,
- * sessionId, ref, id, initiator, ok) the agent never needs, keeping only method/url/status/ms.
- * This is the bulk of the token cost: raw ReticleEvent objects are ~5x larger than this. */
-interface NetCallView {
-    method: string;
-    url: string;
-    status?: number | string;
-    statusText?: string;
-    contentType?: string;
-    responseSize?: number;
-    requestBody?: string;
-    responseBody?: string;
-    bodyTruncated?: boolean;
-    ms?: number;
-    /** Authoritative response headers merged from the driven (CDP) path — present only when driven. */
-    headers?: Record<string, string>;
-    /**
-     * A fire-and-forget desktop IPC send (`ipcRenderer.send`): dispatched, outcome unknowable.
-     *
-     * Carried into the projection on purpose. Such a record has no `status` and no `ok`, and without
-     * this flag a reader has no way to tell "the outcome is unknown" from "the fields were dropped" —
-     * which is the reading that turns an unverifiable call into an assumed success.
-     */
-    oneWay?: boolean;
-}
-export declare function projectNetCall(e: ReticleEvent, includeBodies?: boolean): NetCallView;
-/**
- * Compact console-log summary for reticle_console output.
- *
- * `stack`/`source` are the only localization signal a console failure carries — there is no element
- * to map to a component here, so without them "an error was logged" is the whole report and the agent
- * has to go find the origin itself. The browser already keeps this lean by capturing a stack for
- * console.error only; the projection used to discard even that.
- */
-interface ConsoleLogView {
-    level: string;
-    text: string;
-    stack?: string;
-    source?: string;
-}
-export declare function projectConsoleLog(e: ReticleEvent): ConsoleLogView;
-/** True for any console.* / uncaught-error event (the reticle_console universe). */
-export declare function isConsoleEvent(e: ReticleEvent): boolean;
-/** Match a console/error event against an optional level filter (reticle_console). */
-export declare function matchConsole(e: ReticleEvent, level: string | undefined): boolean;
-/** One present network call summarized for a zero-match hint. */
-interface NetCallSummary {
-    method: string;
-    url: string;
-    status?: number;
-}
-/**
- * Near-miss for reticle_network: when a filter matched zero calls, describe what DID fire so the
- * agent self-corrects ("POST /x 200 matched nothing, but these 3 requests happened") instead of
- * reading a bare []. `allNet` is every net.request in the window (pre-filter).
- */
-interface NetEmptyHint {
-    totalInWindow: number;
-    /** Up to HINT_SAMPLE_MAX present calls (most-recent first). */
-    present: NetCallSummary[];
-}
-export declare function netEmptyHint(allNet: ReticleEvent[]): NetEmptyHint;
-/** Per-level console counts in the window — the body of a zero-match console hint. */
-interface ConsoleLevelCounts {
-    log: number;
-    warn: number;
-    error: number;
-}
-/**
- * Near-miss for reticle_console: when a level filter matched zero logs, report what levels ARE
- * present so the agent knows the page isn't silent ("0 errors, but 3 warns + 5 logs"). `allConsole`
- * is every console/error event in the window (pre-filter).
- */
-interface ConsoleEmptyHint {
-    totalInWindow: number;
-    byLevel: ConsoleLevelCounts;
-}
-export declare function consoleEmptyHint(allConsole: ReticleEvent[]): ConsoleEmptyHint;
-export {};

package/dist/events/event-filters.js

@@ -1,215 +0,0 @@
-import { EventType, URL_RAW, urlForMatch } from '@reticlehq/core';
-import { asString, asNumber } from '../tools/tools-helpers.js';
-import { mergeNetworkDetail } from '../input/network-detail.js';
-/**
- * The friendly bucket names reticle_observe's `filters` param advertises → the real event types.
- *
- * The schema promised `dom | net | route | console | animation | signal`, but the handler filtered
- * with `filters.includes(e.type)` against types like `net.request` and `dom.added` — so every
- * documented value matched nothing, and an agent passing `filters:['net']` to trim its payload got an
- * EMPTY timeline instead. Empty reads as "the app did nothing" — a false green produced by using the
- * feature exactly as documented. Mapping the bucket to its member types makes the documented values
- * work; raw types are still accepted (see eventMatchesFilters) so neither spelling surprises a caller.
- */
-export const OBSERVE_FILTER_BUCKETS = {
-    dom: [EventType.DOM_ADDED, EventType.DOM_REMOVED, EventType.DOM_ATTR, EventType.DOM_TEXT],
-    net: [EventType.NET_REQUEST, EventType.NET_PENDING, EventType.NET_STREAM],
-    route: [EventType.ROUTE_CHANGE],
-    console: [EventType.CONSOLE_ERROR, EventType.ERROR_UNCAUGHT],
-    animation: [EventType.ANIM_START, EventType.ANIM_END],
-    signal: [EventType.SIGNAL],
-    // perf/state/storage are single-type buckets. They resolve through the raw-type fallback anyway,
-    // but naming them keeps the advertised vocabulary and the real one identical — the mismatch between
-    // those two is the bug this map exists to fix, so leaving observable types out of it would reopen it.
-    perf: [EventType.PERF],
-    state: [EventType.STATE_CHANGE],
-    storage: [EventType.STORAGE_CHANGE],
-};
-/**
- * True when an event passes an observe `filters` allowlist. A filter entry matches either as a bucket
- * name (`net` keeps every net.* type) or as a raw event type (`net.request`). Unknown entries match
- * nothing rather than throwing — a typo narrows the result, it never crashes the observe.
- */
-export function eventMatchesFilters(e, filters) {
-    for (const f of filters) {
-        // `Object.hasOwn`, not a bare index: a plain-object map inherits from Object.prototype, so a
-        // filter value like "toString" or "hasOwnProperty" would resolve to the inherited FUNCTION and
-        // then `.includes` would throw — a crash on an odd-but-harmless agent input. Only an OWN key is a
-        // real bucket; anything else falls through to the raw-type comparison.
-        const bucket = Object.hasOwn(OBSERVE_FILTER_BUCKETS, f) ? OBSERVE_FILTER_BUCKETS[f] : undefined;
-        if (bucket !== undefined ? bucket.includes(e.type) : e.type === f)
-            return true;
-    }
-    return false;
-}
-/**
- * Match a net.request event against optional method/url/status/ok filters (reticle_network).
- *
- * `ok` is the filter the tool's own description points at for desktop IPC, whose 200/500 is derived
- * rather than sent by any server. A still-PENDING call never matches an `ok` filter in either
- * direction: unresolved is not the same as failed, and answering "yes, it failed" about a request
- * still in flight is the false green this whole surface exists to prevent.
- */
-export function matchNet(e, method, urlContains, status, ok) {
-    const d = e.data;
-    if (method !== undefined && asString(d['method'])?.toUpperCase() !== method.toUpperCase()) {
-        return false;
-    }
-    if (urlContains !== undefined && !urlForMatch(d).includes(urlContains)) {
-        return false;
-    }
-    if (status !== undefined && asNumber(d['status']) !== status)
-        return false;
-    if (ok !== undefined && d['ok'] !== ok)
-        return false;
-    return true;
-}
-/**
- * Reconcile network events into completed calls + still-in-flight calls. A NET_PENDING whose
- * `id` never gets a matching NET_REQUEST is an unresolved/hung request — the case
- * completion-only logging is blind to. Pending events are annotated `{ status: 'pending',
- * pending: true }` so a numeric `status` filter excludes them but `urlContains`/`method` match.
- */
-export function reconcileNet(events) {
-    // Fold CDP-authoritative detail (driven path) onto the matching in-page request first, so the driven
-    // view carries the full headers/status the page-side wrapper couldn't see (no-op when none present).
-    events = mergeNetworkDetail(events);
-    const completed = events.filter((e) => e.type === EventType.NET_REQUEST);
-    const doneIds = new Set(completed.map((e) => asString(e.data['id'])).filter((id) => id !== undefined));
-    const unresolved = events
-        .filter((e) => {
-        if (e.type !== EventType.NET_PENDING)
-            return false;
-        const id = asString(e.data['id']);
-        return id === undefined || !doneIds.has(id);
-    })
-        .map((e) => ({ ...e, data: { ...e.data, status: 'pending', pending: true } }));
-    return [...completed, ...unresolved].sort((a, b) => a.t - b.t);
-}
-/**
- * Strip the grader-only raw URL before an event is rendered to the agent.
- *
- * `urlRaw` exists so `urlContains` can match a path redaction rewrote. It is a secret-bearing field
- * by construction (the whole reason `url` was redacted) and must never appear in observe, evidence,
- * or a network listing.
- */
-export function withoutUrlRaw(event) {
-    if (typeof event !== 'object' || null === event)
-        return event;
-    const rec = event;
-    const data = rec['data'];
-    if (typeof data !== 'object' || null === data || !(URL_RAW in data))
-        return event;
-    const { [URL_RAW]: _raw, ...rest } = data;
-    return { ...rec, data: rest };
-}
-export function projectNetCall(e, includeBodies = true) {
-    const status = e.data['status'];
-    const ms = asNumber(e.data['durationMs']);
-    const statusText = asString(e.data['statusText']);
-    const contentType = asString(e.data['contentType']);
-    const responseSize = asNumber(e.data['responseSize']);
-    const requestBody = asString(e.data['requestBody']);
-    const responseBody = asString(e.data['responseBody']);
-    const view = {
-        method: asString(e.data['method']) ?? '',
-        url: asString(e.data['url']) ?? '',
-    };
-    if ('number' === typeof status || 'string' === typeof status)
-        view.status = status;
-    if (statusText !== undefined)
-        view.statusText = statusText;
-    if (contentType !== undefined)
-        view.contentType = contentType;
-    if (responseSize !== undefined)
-        view.responseSize = responseSize;
-    // Bodies dominate the payload of the most-called read tool, and are only occasionally the part
-    // anyone wanted — `bodies: false` on reticle_network drops them for a body-free listing (#401).
-    if (includeBodies && requestBody !== undefined)
-        view.requestBody = requestBody;
-    if (includeBodies && responseBody !== undefined)
-        view.responseBody = responseBody;
-    if (includeBodies &&
-        (true === e.data['requestBodyTruncated'] || true === e.data['responseBodyTruncated'])) {
-        view.bodyTruncated = true;
-    }
-    if (ms !== undefined)
-        view.ms = ms;
-    if (true === e.data['oneWay'])
-        view.oneWay = true;
-    const headers = e.data['headers'];
-    if (headers !== null && 'object' === typeof headers) {
-        view.headers = headers;
-    }
-    return view;
-}
-/**
- * How many stack frames reach the agent.
- *
- * A raw stack is mostly framework internals, and padding a failure report with them is not free —
- * the frames that identify the origin are the first few, and everything after is context the agent
- * has to read past. Four keeps the error line plus the app frames that actually called it.
- */
-const MAX_STACK_FRAMES = 4;
-/** Trim a stack to the frames that locate the fault. */
-function topFrames(stack) {
-    return stack.split('\n').slice(0, MAX_STACK_FRAMES).join('\n');
-}
-export function projectConsoleLog(e) {
-    const level = e.type === EventType.ERROR_UNCAUGHT ? 'error' : e.type.replace('console.', '');
-    const view = { level, text: asString(e.data['message']) ?? '' };
-    const stack = asString(e.data['stack']);
-    if (stack !== undefined && stack.length > 0)
-        view.stack = topFrames(stack);
-    // An uncaught error reports its origin as discrete fields rather than in a stack; render them in
-    // the same file:line form the element descriptors use so the agent reads one shape everywhere.
-    const source = asString(e.data['source']);
-    const line = e.data['line'];
-    if (source !== undefined && source.length > 0) {
-        view.source = 'number' === typeof line ? `${source}:${String(line)}` : source;
-    }
-    return view;
-}
-/** True for any console.* / uncaught-error event (the reticle_console universe). */
-export function isConsoleEvent(e) {
-    return (e.type === EventType.CONSOLE_LOG ||
-        e.type === EventType.CONSOLE_WARN ||
-        e.type === EventType.CONSOLE_ERROR ||
-        e.type === EventType.CONSOLE_INFO ||
-        e.type === EventType.CONSOLE_DEBUG ||
-        e.type === EventType.ERROR_UNCAUGHT);
-}
-/** Match a console/error event against an optional level filter (reticle_console). */
-export function matchConsole(e, level) {
-    if (!isConsoleEvent(e))
-        return false;
-    if (level === undefined)
-        return true;
-    return (e.type === `console.${level}` || ('error' === level && e.type === EventType.ERROR_UNCAUGHT));
-}
-/** How many present calls/levels a zero-match hint samples before truncating. */
-const HINT_SAMPLE_MAX = 5;
-export function netEmptyHint(allNet) {
-    const present = allNet
-        .slice(-HINT_SAMPLE_MAX)
-        .reverse()
-        .map((e) => {
-        const status = asNumber(e.data['status']);
-        const base = { method: asString(e.data['method']) ?? '', url: asString(e.data['url']) ?? '' };
-        return status === undefined ? base : { ...base, status };
-    });
-    return { totalInWindow: allNet.length, present };
-}
-export function consoleEmptyHint(allConsole) {
-    const byLevel = { log: 0, warn: 0, error: 0 };
-    for (const e of allConsole) {
-        if (e.type === EventType.CONSOLE_LOG)
-            byLevel.log += 1;
-        else if (e.type === EventType.CONSOLE_WARN)
-            byLevel.warn += 1;
-        else if (e.type === EventType.CONSOLE_ERROR || e.type === EventType.ERROR_UNCAUGHT) {
-            byLevel.error += 1;
-        }
-    }
-    return { totalInWindow: allConsole.length, byLevel };
-}

package/dist/events/json-salvage.d.ts

@@ -1,33 +0,0 @@
-/**
- * Read what CAN be read out of a truncated JSON payload.
- *
- * Response bodies are capped (8192 bytes) so one enormous payload cannot blow the transport budget.
- * The cap is right; treating what it produces as "no body" is not. Measured on a 10,000-row console:
- * the list response is 19,932 bytes, arrives truncated mid-object, `JSON.parse` throws, and every
- * body-based check — currency reconciliation, per-item failures, unit mismatches — silently reported
- * nothing on the one page with the most data to be wrong about.
- *
- * Worse, the tool then advised turning on body capture, which was already on. Advice that cannot
- * work is more expensive than silence: it sends the reader to change a setting that is already
- * correct, and teaches them the tool does not know what it is looking at.
- *
- * A truncated array of records is still mostly complete records. This recovers the ones that closed
- * before the cut and reports how many it had to drop, so a partial answer is delivered AS partial
- * rather than as a clean one.
- */
-interface Salvaged {
-    /** Parsed values — one whole body, or the records recovered from a truncated one. */
-    values: unknown[];
-    /** True when the payload was incomplete and only part of it could be read. */
-    partial: boolean;
-}
-/**
- * Parse a body, falling back to whole records when it was cut short.
- *
- * The nesting caveat is real and stated rather than hidden: an object cut mid-nesting contributes its
- * completed CHILDREN instead of itself, so a salvaged set can hold records the envelope would have
- * grouped differently. For field-level comparison — is this id's currency rendered correctly — that
- * costs nothing, because each record still carries its own id and its own fields.
- */
-export declare function salvageJson(raw: string): Salvaged;
-export {};

package/dist/events/json-salvage.js

@@ -1,96 +0,0 @@
-/**
- * Read what CAN be read out of a truncated JSON payload.
- *
- * Response bodies are capped (8192 bytes) so one enormous payload cannot blow the transport budget.
- * The cap is right; treating what it produces as "no body" is not. Measured on a 10,000-row console:
- * the list response is 19,932 bytes, arrives truncated mid-object, `JSON.parse` throws, and every
- * body-based check — currency reconciliation, per-item failures, unit mismatches — silently reported
- * nothing on the one page with the most data to be wrong about.
- *
- * Worse, the tool then advised turning on body capture, which was already on. Advice that cannot
- * work is more expensive than silence: it sends the reader to change a setting that is already
- * correct, and teaches them the tool does not know what it is looking at.
- *
- * A truncated array of records is still mostly complete records. This recovers the ones that closed
- * before the cut and reports how many it had to drop, so a partial answer is delivered AS partial
- * rather than as a clean one.
- */
-/**
- * Complete `{...}` objects inside a truncated payload, in order.
- *
- * NOT top-level ones: a cut body is typically `{"rows":[{…},{…},{…` where the OUTER brace never
- * closes, so nothing at depth 0 completes and a depth-0 scan recovers exactly nothing. The records
- * are one level in.
- *
- * Objects are kept only at the SHALLOWEST depth at which anything closes — that is the record level.
- * Keeping every depth would also return each record's nested children (a shipment's legs, an order's
- * line items), and those carry their own `id` and `status`, which would pollute the comparison with
- * values that were never meant to be rendered as rows.
- */
-function completeObjects(text) {
-    const found = [];
-    let depth = 0;
-    const starts = [];
-    let inString = false;
-    let escaped = false;
-    for (let i = 0; i < text.length; i += 1) {
-        const ch = text[i];
-        if (inString) {
-            if (escaped)
-                escaped = false;
-            else if ('\\' === ch)
-                escaped = true;
-            else if ('"' === ch)
-                inString = false;
-            continue;
-        }
-        if ('"' === ch) {
-            inString = true;
-            continue;
-        }
-        if ('{' === ch) {
-            starts.push(i);
-            depth += 1;
-            continue;
-        }
-        if ('}' === ch) {
-            depth -= 1;
-            // A negative depth means the cut removed an opening brace; nothing further is trustworthy.
-            if (depth < 0)
-                break;
-            const start = starts.pop();
-            if (start !== undefined)
-                found.push({ depth: depth + 1, text: text.slice(start, i + 1) });
-        }
-    }
-    if (0 === found.length)
-        return [];
-    const shallowest = Math.min(...found.map((f) => f.depth));
-    return found.filter((f) => f.depth === shallowest).map((f) => f.text);
-}
-/**
- * Parse a body, falling back to whole records when it was cut short.
- *
- * The nesting caveat is real and stated rather than hidden: an object cut mid-nesting contributes its
- * completed CHILDREN instead of itself, so a salvaged set can hold records the envelope would have
- * grouped differently. For field-level comparison — is this id's currency rendered correctly — that
- * costs nothing, because each record still carries its own id and its own fields.
- */
-export function salvageJson(raw) {
-    try {
-        return { values: [JSON.parse(raw)], partial: false };
-    }
-    catch {
-        // fall through to record-level recovery
-    }
-    const values = [];
-    for (const chunk of completeObjects(raw)) {
-        try {
-            values.push(JSON.parse(chunk));
-        }
-        catch {
-            // a chunk that still will not parse is simply not recovered
-        }
-    }
-    return { values, partial: true };
-}

package/dist/events/lineage.d.ts

@@ -1,52 +0,0 @@
-/**
- * Where a runtime value came from: state path ← the signal that preceded it ← the request behind it.
- *
- * The prior art this issue names (`firatorhan/sentinel`'s `get_lineage`) builds the same chain by
- * picking "the most recent action whose payload contains this value", then "an API call whose type
- * matches". That is CORRELATION, and for a devtool a human reads it is the right trade — the reader
- * discounts it on sight.
- *
- * Reticle's output is read by an agent that acts on it, so the same chain presented as fact is the
- * false-green shape this project exists to refuse. The join here is deliberately no cleverer than
- * theirs; what is different is that every link carries how much it is worth:
- *
- * - a state path that changed is OBSERVED — we have the event;
- * - "this signal caused it" is INFERRED, and the wording says so;
- * - several candidates are NAMED rather than narrowed to the most recent, because choosing is the
- *   one thing a correlation cannot justify;
- * - no candidate says the value was not seen to pass through one, and reaches for nothing.
- *
- * Read-only. Produces no verdict, is not reachable from an assert path, and changes nothing.
- */
-import { type ReticleEvent } from '@reticlehq/core';
-/** What the caller is asking about. `value` narrows a path that changed more than once. */
-export interface LineageQuery {
-    path: string;
-    value?: string;
-}
-/** One line of the chain, with the confidence that produced it. */
-export interface LineageLink {
-    /** Which stream this came from. */
-    kind: 'state' | 'signal' | 'net';
-    /** The rendered line, already carrying its own hedge. */
-    text: string;
-    /** True only when this is an event we hold. A join is never observed. */
-    observed: boolean;
-    /** Every candidate, when more than one could explain the link. Present only when ambiguous. */
-    candidates?: string[];
-}
-export interface Lineage {
-    /** False when the path was never seen to change — a different answer from an empty chain. */
-    found: boolean;
-    chain: LineageLink[];
-    /** Why the chain stops where it does, when it stops early. */
-    note?: string;
-}
-/**
- * The chain, most recent change first.
- *
- * Stops at the first link with nothing to point at, and says why. Walking past a gap would mean
- * joining across a hole in the evidence, which is exactly the step that turns a correlation into a
- * claim.
- */
-export declare function traceLineage(events: readonly ReticleEvent[], query: LineageQuery): Lineage;

package/dist/events/lineage.js

@@ -1,122 +0,0 @@
-/**
- * Where a runtime value came from: state path ← the signal that preceded it ← the request behind it.
- *
- * The prior art this issue names (`firatorhan/sentinel`'s `get_lineage`) builds the same chain by
- * picking "the most recent action whose payload contains this value", then "an API call whose type
- * matches". That is CORRELATION, and for a devtool a human reads it is the right trade — the reader
- * discounts it on sight.
- *
- * Reticle's output is read by an agent that acts on it, so the same chain presented as fact is the
- * false-green shape this project exists to refuse. The join here is deliberately no cleverer than
- * theirs; what is different is that every link carries how much it is worth:
- *
- * - a state path that changed is OBSERVED — we have the event;
- * - "this signal caused it" is INFERRED, and the wording says so;
- * - several candidates are NAMED rather than narrowed to the most recent, because choosing is the
- *   one thing a correlation cannot justify;
- * - no candidate says the value was not seen to pass through one, and reaches for nothing.
- *
- * Read-only. Produces no verdict, is not reachable from an assert path, and changes nothing.
- */
-import { EventType } from '@reticlehq/core';
-import { asString } from '../tools/tools-helpers.js';
-/**
- * How far back to look for a cause.
- *
- * Wide enough for a fetch → dispatch → render sequence, narrow enough that an unrelated signal a
- * page-load earlier cannot be offered as a candidate. Not a correctness bound: widening it produces
- * MORE named candidates, never a wrong single answer, because ambiguity is reported rather than
- * resolved.
- */
-const CAUSE_WINDOW_MS = 5_000;
-function stateChangesFor(events, query) {
-    return events.filter((e) => {
-        if (e.type !== EventType.STATE_CHANGE)
-            return false;
-        const path = asString(e.data['path']);
-        if (path === undefined || !path.includes(query.path))
-            return false;
-        if (query.value === undefined)
-            return true;
-        return String(e.data['value']) === query.value;
-    });
-}
-/** Events of one kind inside the causal window before `t`, oldest first. */
-function precursors(events, type, t) {
-    return events.filter((e) => e.type === type && e.t < t && e.t >= t - CAUSE_WINDOW_MS);
-}
-/**
- * Render an inferred link, hedged according to how many things could explain it.
- *
- * The wording IS the deliverable. `← USER_FETCH_SUCCESS` reads as fact; the two forms below read as
- * what they are, and a reader who skims still sees the hedge because it is in the first few words.
- */
-function inferredLink(kind, labels) {
-    const one = labels[0] ?? '';
-    if (1 === labels.length) {
-        return { kind, text: `← likely ${one} (inferred from timing, 1 candidate)`, observed: false };
-    }
-    return {
-        kind,
-        text: `← ambiguous: ${String(labels.length)} candidates (${labels.join(', ')}) — not resolved, because timing alone cannot choose between them`,
-        observed: false,
-        candidates: labels,
-    };
-}
-function signalLabel(e) {
-    return asString(e.data['name']) ?? '(unnamed signal)';
-}
-function netLabel(e) {
-    const method = asString(e.data['method']) ?? 'GET';
-    const url = asString(e.data['url']) ?? '(unknown url)';
-    const status = e.data['status'];
-    return `${method} ${url}${'number' === typeof status ? ` (${String(status)})` : ''}`;
-}
-/**
- * The chain, most recent change first.
- *
- * Stops at the first link with nothing to point at, and says why. Walking past a gap would mean
- * joining across a hole in the evidence, which is exactly the step that turns a correlation into a
- * claim.
- */
-export function traceLineage(events, query) {
-    const changes = stateChangesFor(events, query);
-    const latest = changes[changes.length - 1];
-    if (latest === undefined) {
-        return {
-            found: false,
-            chain: [],
-            note: `'${query.path}' was never seen to change in this window, so there is nothing to trace back from. It may be set before Reticle connected, or held somewhere no registered store exposes.`,
-        };
-    }
-    const observedValue = String(latest.data['value']);
-    const chain = [
-        {
-            kind: 'state',
-            text: `${asString(latest.data['path']) ?? query.path} = ${observedValue}  (observed: state change at ${String(latest.t)}ms)`,
-            observed: true,
-        },
-    ];
-    const signals = precursors(events, EventType.SIGNAL, latest.t);
-    if (0 === signals.length) {
-        return {
-            found: true,
-            chain,
-            note: 'No signal fired in the window before this change, so the value was not seen to pass through one. Nothing further is claimed — the change is real, its cause is not in evidence.',
-        };
-    }
-    chain.push(inferredLink('signal', signals.map(signalLabel)));
-    // Anchored on the OLDEST candidate signal: a request that preceded any of them could have produced
-    // it, and narrowing to the newest would quietly discard candidates for the link below.
-    const anchor = signals[0]?.t ?? latest.t;
-    const calls = precursors(events, EventType.NET_REQUEST, anchor);
-    if (0 === calls.length) {
-        return {
-            found: true,
-            chain,
-            note: 'No request preceded that signal in the window, so the chain stops there rather than joining across a gap in the evidence.',
-        };
-    }
-    chain.push(inferredLink('net', calls.map(netLabel)));
-    return { found: true, chain };
-}

package/dist/events/net-evidence.d.ts

@@ -1,21 +0,0 @@
-/**
- * What a network verdict returns as its PROOF.
- *
- * Split out of predicate-eval.ts, which sits at the size backstop, and split HERE because this is a
- * separate question from "did the predicate hold": that file decides the answer, this one decides
- * what is shown to justify it. The two failure modes differ too. A wrong verdict is a wrong verdict;
- * wrong evidence is a verdict nobody can check, or one that costs forty times what it is worth.
- */
-import { PredicateKind } from '@reticlehq/core';
-import type { Predicate } from './predicate-schema.js';
-/**
- * The matched call, as the proof of the claim that was actually made.
- *
- * A predicate asking about status and url is proved by status and url; returning the whole payload
- * beside them is cost with no bearing on the verdict. A predicate asking `bodyContains` is proved BY
- * the body, and that one keeps it in full — clipping a body a check consumed would be weakening the
- * check to make it cheaper, which is the trade this codebase does not make.
- */
-export declare function netEvidence(data: Record<string, unknown>, p: Extract<Predicate, {
-    kind: typeof PredicateKind.NET;
-}>): unknown;