@reticlehq/server 2.14.0 → 3.2.0

package/dist/events/stale-response.js

@@ -1,186 +0,0 @@
-import { ContradictionKind, EventType } from '@reticlehq/core';
-function pathOf(url) {
-    const q = url.indexOf('?');
-    return -1 === q ? url : url.slice(0, q);
-}
-function queryOf(url) {
-    const q = url.indexOf('?');
-    return -1 === q ? '' : url.slice(q + 1);
-}
-/**
- * Parameters that ENUMERATE a collection rather than select within it.
- *
- * Two overlapping reads that differ only in these are a fan-out, not a race: an app fetching page 0
- * and page 5 in parallel wants both, and whichever lands last is not overwriting the other. Measured
- * against a synthetic dashboard doing parallel pagination — every run reported a race, because the
- * requests do overlap and do settle out of order, and the original rule looked no further than that.
- *
- * A filter race differs in a SELECTING parameter (`status`, `q`, a date range): the second request
- * makes the first obsolete, both answer into the same view, and the slower one wins.
- */
-const ENUMERATING_PARAMS = new Set([
-    'page',
-    'offset',
-    'cursor',
-    'limit',
-    'size',
-    'per_page',
-    'perPage',
-    'pageSize',
-    'after',
-    'before',
-    'start',
-    'end',
-]);
-/** Whether the two queries differ ONLY in how much of the same collection they ask for. */
-function differsOnlyByEnumeration(first, second) {
-    const a = new URLSearchParams(first);
-    const b = new URLSearchParams(second);
-    const keys = new Set([...a.keys(), ...b.keys()]);
-    let differed = false;
-    for (const key of keys) {
-        if (a.get(key) === b.get(key))
-            continue;
-        if (!ENUMERATING_PARAMS.has(key))
-            return false;
-        differed = true;
-    }
-    return differed;
-}
-/** Pair NET_PENDING with its NET_REQUEST by the id both carry. Unpaired events are still in flight. */
-function flights(events) {
-    const issued = new Map();
-    const out = [];
-    for (const event of events) {
-        const id = 'string' === typeof event.data['id'] ? event.data['id'] : undefined;
-        if (id === undefined)
-            continue;
-        const at = 'number' === typeof event.t ? event.t : 0;
-        if (event.type === EventType.NET_PENDING) {
-            const url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
-            const method = 'string' === typeof event.data['method'] ? event.data['method'] : 'GET';
-            issued.set(id, { url, method, at });
-            continue;
-        }
-        if (event.type !== EventType.NET_REQUEST)
-            continue;
-        const start = issued.get(id);
-        if (start === undefined)
-            continue; // started before this window — its ordering is unknowable
-        out.push({
-            id,
-            url: start.url,
-            method: start.method.toUpperCase(),
-            issuedAt: start.at,
-            settledAt: at,
-        });
-    }
-    return out;
-}
-/**
- * Most recent flights compared per endpoint.
- *
- * The comparison is pairwise, so an unbounded window is quadratic: measured at 548ms for 2000
- * concurrent reads of one endpoint, paid on EVERY verdict. A verdict that costs half a second is a
- * verdict agents stop asking for. Racing requests are adjacent in time by definition, so the most
- * recent flights are where a race can be; older ones cannot overlap them anyway.
- *
- * Bounded rather than silent: this is a detection ceiling, not a truncation of reported data — a race
- * among more than this many simultaneous reads of ONE endpoint goes unreported, and that is a
- * deliberate trade for a hot path that runs on every assert.
- */
-const MAX_FLIGHTS_PER_PATH = 60;
-/** The one contradiction, or none. Reported once per window — a race is a fact about the window. */
-/**
- * How long after a superseded response lands we look for the app reacting to it.
- *
- * A handler runs on the microtask that resolves the fetch; the render follows within a frame or two.
- * Beyond this the connection between the response and any change is speculation.
- */
-const APPLY_WINDOW_MS = 500;
-/**
- * How far BEFORE the completion stamp a reaction still counts as reacting to it.
- *
- * Not a fudge factor — a correction for which of the two is stamped first. `NET_REQUEST` is emitted
- * when the observer's wrapper sees the fetch settle, and the app's own handler runs on the same
- * microtask; in practice the app's state write, signal and DOM text land at or a millisecond BEFORE
- * the completion event that caused them.
- *
- * So a strictly-forward window could not see the application at all, and the rule could never fire on
- * real traffic however plainly the app misbehaved. Sixteen passing unit tests did not catch that,
- * because synthetic events are written with the reaction placed after the cause.
- */
-const APPLY_SLACK_MS = 100;
-/**
- * Did the app REACT to this response — did anything user-visible move after it landed?
- *
- * The question the rule could not previously ask, and the difference between a defect and a
- * correctly-handled race. An app that guards against superseded responses still RACES: two requests
- * overlap and settle out of order exactly as before. What it does not do is act on the loser.
- *
- * Without this check the rule fires identically on both, which is worse than not having it: a
- * detector that accuses correct code teaches people to ignore it, and it takes the true positives
- * down with it.
- */
-function appliedAfter(events, settledAt) {
-    return events.some((event) => {
-        if (event.t < settledAt - APPLY_SLACK_MS || event.t > settledAt + APPLY_WINDOW_MS)
-            return false;
-        return (event.type === EventType.STATE_CHANGE ||
-            event.type === EventType.SIGNAL ||
-            event.type === EventType.DOM_TEXT ||
-            event.type === EventType.DOM_ADDED ||
-            event.type === EventType.DOM_REMOVED ||
-            event.type === EventType.DOM_ATTR);
-    });
-}
-export function findStaleResponses(events) {
-    // Grouped by path first: two reads of DIFFERENT endpoints can never race, and comparing them was
-    // the bulk of the work on any real page, which talks to many endpoints at once.
-    const byPath = new Map();
-    for (const flight of flights(events)) {
-        if (flight.method !== 'GET')
-            continue;
-        const path = pathOf(flight.url);
-        const group = byPath.get(path) ?? [];
-        group.push(flight);
-        byPath.set(path, group);
-    }
-    for (const group of byPath.values()) {
-        const reads = group.slice(-MAX_FLIGHTS_PER_PATH);
-        const found = raceIn(reads, events);
-        if (found !== undefined)
-            return [found];
-    }
-    return [];
-}
-function raceIn(reads, events) {
-    for (const first of reads) {
-        for (const second of reads) {
-            if (first.id === second.id)
-                continue;
-            if (second.issuedAt <= first.issuedAt)
-                continue; // `first` must be the earlier request
-            if (second.issuedAt >= first.settledAt)
-                continue; // sequential, not overlapping
-            if (second.settledAt >= first.settledAt)
-                continue; // settled in order — no race
-            if (queryOf(first.url) === queryOf(second.url))
-                continue; // a retry, not a superseding query
-            // Parallel pagination is not a race — see differsOnlyByEnumeration.
-            if (differsOnlyByEnumeration(queryOf(first.url), queryOf(second.url)))
-                continue;
-            // The race happened. Whether it MATTERS is whether the app acted on the loser — an app that
-            // drops superseded responses races just as visibly and is not broken.
-            if (!appliedAfter(events, first.settledAt))
-                continue;
-            return {
-                kind: ContradictionKind.STALE_RESPONSE_APPLIED,
-                claim: `both reads of ${pathOf(first.url)} returned successfully and the page settled`,
-                counter: `the SUPERSEDED request (${queryOf(first.url)}) settled ${String(Math.max(0, first.settledAt - second.settledAt))}ms AFTER the one that replaced it (${queryOf(second.url)}), so the screen is showing the older query's data`,
-                detail: 'a filter/search race: the newer request was issued while the older was still in flight, and the older answered last, so whichever query the server happens to be slower at wins — unless the app cancels superseded requests or drops responses that no longer match current state',
-            };
-        }
-    }
-    return undefined;
-}

package/dist/events/testid-near-miss.d.ts

@@ -1,22 +0,0 @@
-/**
- * Turning "no element matched {testid: …}" into something an agent can act on.
- *
- * `reticle_query` on a missing testid already returns the testids that ARE present, so a typo is one
- * step from fixed. The same failure through a PREDICATE — `act_and_wait { until: { kind:'element',
- * query:{ testid } } }` — said only "no element matched" and stopped, naming nothing.
- *
- * The near-miss machinery covered an element in the wrong STATE and a wrong NAME for a role (which
- * even lists the names it saw). Testid — the anchor this codebase calls the gold standard — had
- * none, and it is the one agents use most.
- *
- * It also just became the highest-traffic failure in the product: putting act_and_wait on the
- * verification path means agents assert far more, so a failed element assertion is now the common
- * case rather than the rare one.
- */
-/**
- * The "…but these ARE here" clause, or undefined when there is nothing useful to say.
- *
- * Returns the empty string when the queried testid is itself present: the miss was then about STATE,
- * not presence, and "you asked for X; X is present" reads as a contradiction rather than a hint.
- */
-export declare function describeTestidMiss(wanted: string, present: readonly string[]): string | undefined;

package/dist/events/testid-near-miss.js

@@ -1,33 +0,0 @@
-/**
- * Turning "no element matched {testid: …}" into something an agent can act on.
- *
- * `reticle_query` on a missing testid already returns the testids that ARE present, so a typo is one
- * step from fixed. The same failure through a PREDICATE — `act_and_wait { until: { kind:'element',
- * query:{ testid } } }` — said only "no element matched" and stopped, naming nothing.
- *
- * The near-miss machinery covered an element in the wrong STATE and a wrong NAME for a role (which
- * even lists the names it saw). Testid — the anchor this codebase calls the gold standard — had
- * none, and it is the one agents use most.
- *
- * It also just became the highest-traffic failure in the product: putting act_and_wait on the
- * verification path means agents assert far more, so a failed element assertion is now the common
- * case rather than the rare one.
- */
-/** Enough to recognise the one you meant; not so many that a large page floods the message. */
-const MAX_LISTED = 12;
-/**
- * The "…but these ARE here" clause, or undefined when there is nothing useful to say.
- *
- * Returns the empty string when the queried testid is itself present: the miss was then about STATE,
- * not presence, and "you asked for X; X is present" reads as a contradiction rather than a hint.
- */
-export function describeTestidMiss(wanted, present) {
-    if (0 === present.length)
-        return undefined;
-    if (present.includes(wanted))
-        return '';
-    const shown = present.slice(0, MAX_LISTED);
-    const rest = present.length - shown.length;
-    const tail = rest > 0 ? `, and ${String(rest)} more` : '';
-    return `testids present here: ${shown.join(', ')}${tail}`;
-}

package/dist/events/unit-mismatch.d.ts

@@ -1,16 +0,0 @@
-import { type ReticleEvent } from '@reticlehq/core';
-import type { OwnContradiction } from './contradictions.js';
-/**
- * @param prior events from BEFORE the window, used only to learn what the API has stated.
- *
- * The scale error is a disagreement with a value the API gave EARLIER — by definition before the
- * action that sends it back. `reticle_assert` scopes its window to the last act's cursor, so the
- * stating response falls outside it and `known` is empty exactly when it matters. Measured live on
- * the payments panel: `reticle_observe` over a wide window reported the mismatch while `assert` on
- * the same session reported none — the verdict tool, the one an agent gates on, was the blind one.
- *
- * Prior events TEACH, they are never themselves findings: widening the window instead would make
- * every other rule blame this action for events it did not cause, and would re-report every earlier
- * mistake on every assert.
- */
-export declare function findUnitMismatches(events: readonly ReticleEvent[], prior?: readonly ReticleEvent[]): OwnContradiction[];

package/dist/events/unit-mismatch.js

@@ -1,167 +0,0 @@
-import { ContradictionKind, EventType } from '@reticlehq/core';
-/**
- * The app sent a money value back in a DIFFERENT unit than the API gave it.
- *
- * Payment APIs overwhelmingly speak minor units — Stripe, Razorpay, Adyen, PayPal all state amounts
- * in paise/cents as integers. A UI renders that as a major-unit string, and the bug is writing the
- * rendered number back into the field the integer came from.
- *
- * Measured on a real payments dashboard: `GET /payments` returns `amount: 118701` for a payment, the
- * row renders "₹1,187.01", and the refund posts `{"amount": 1187.01}` into the same field. The server
- * takes 1187 paise and answers `200 {"status": "processed"}`. That is a 100x UNDER-REFUND, and every
- * channel agrees it worked: the status is 200, the payload says processed, the UI advances, the page
- * settles, and the number in the request is exactly the number on the screen. Nothing disagrees,
- * because the disagreement is with a value the API returned EARLIER in the session.
- *
- * Which is the point: this is only visible to something holding the whole request timeline with
- * bodies. A snapshot cannot see it, a status column cannot see it, and a human reading the request
- * sees the amount they expected.
- *
- * Not a heuristic about decimals. Firing on "an amount had a fractional part" would accuse every API
- * that legitimately uses major units. This fires only when the SAME field of the SAME entity was
- * observed at a different scale — a comparison, not a guess.
- */
-/** Fields worth comparing. Deliberately short: money, not every number an app sends. */
-const MONEY_FIELDS = new Set(['amount', 'value', 'price', 'total', 'fee', 'cost', 'balance']);
-/**
- * Scales that indicate a minor/major confusion. 100 covers two-decimal currencies; 1000 covers the
- * three-decimal ones (KWD, BHD, JOD, TND).
- */
-const SCALES = [100, 1000];
-/**
- * Prefixed ids (`pay_NkT10001`) and uuids, matched anywhere in a URL or a string field.
- *
- * Numeric ids are handled separately by path segment: `/api/orders/9/capture` is at least as common
- * as a prefixed id, and a bare `9` cannot be pattern-matched out of arbitrary text without matching
- * every other number too.
- */
-const ID_PATTERN = /[A-Za-z]{2,}_[A-Za-z0-9]{2,}|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}/g;
-function parse(raw) {
-    if (typeof raw !== 'string' || 0 === raw.length)
-        return undefined;
-    try {
-        return JSON.parse(raw);
-    }
-    catch {
-        return undefined;
-    }
-}
-/** Every (id, field, value) triple in a payload, from objects that carry an id of their own. */
-function moneyByEntity(node, into) {
-    if (Array.isArray(node)) {
-        for (const item of node)
-            moneyByEntity(item, into);
-        return;
-    }
-    if (typeof node !== 'object' || null === node)
-        return;
-    const record = node;
-    // An id may arrive as a number (`{"id": 9}`) — normalised so a numeric path segment matches it.
-    const raw = record['id'];
-    const id = 'string' === typeof raw ? raw : 'number' === typeof raw ? String(raw) : undefined;
-    if (id !== undefined) {
-        for (const [key, value] of Object.entries(record)) {
-            if (!MONEY_FIELDS.has(key) || typeof value !== 'number')
-                continue;
-            const fields = into.get(id) ?? new Map();
-            fields.set(key, value);
-            into.set(id, fields);
-        }
-    }
-    for (const value of Object.values(record))
-        moneyByEntity(value, into);
-}
-/** Ids named anywhere in a URL or a request payload — how a write says which entity it targets. */
-function idsIn(url, body) {
-    const found = new Set(url.match(ID_PATTERN) ?? []);
-    // Numeric path segments: `/api/orders/9/capture` names entity 9.
-    for (const segment of url.split('?')[0]?.split('/') ?? []) {
-        if (segment.length > 0 && /^\d+$/.test(segment))
-            found.add(segment);
-    }
-    if ('object' === typeof body && body !== null) {
-        for (const value of Object.values(body)) {
-            if ('string' === typeof value)
-                for (const id of value.match(ID_PATTERN) ?? [])
-                    found.add(id);
-        }
-    }
-    return Array.from(found);
-}
-/** The scale between a known value and a sent one, or undefined when they are consistent. */
-function scaleBetween(known, sent) {
-    if (0 === sent || 0 === known)
-        return undefined;
-    for (const scale of SCALES) {
-        // A tolerance, because the major-unit form is a rounded render of the minor one.
-        if (Math.abs(known - sent * scale) <= scale / 2)
-            return scale;
-    }
-    return undefined;
-}
-/**
- * @param prior events from BEFORE the window, used only to learn what the API has stated.
- *
- * The scale error is a disagreement with a value the API gave EARLIER — by definition before the
- * action that sends it back. `reticle_assert` scopes its window to the last act's cursor, so the
- * stating response falls outside it and `known` is empty exactly when it matters. Measured live on
- * the payments panel: `reticle_observe` over a wide window reported the mismatch while `assert` on
- * the same session reported none — the verdict tool, the one an agent gates on, was the blind one.
- *
- * Prior events TEACH, they are never themselves findings: widening the window instead would make
- * every other rule blame this action for events it did not cause, and would re-report every earlier
- * mistake on every assert.
- */
-export function findUnitMismatches(events, prior = []) {
-    // What the API has told us about each entity so far, in the API's own units.
-    const known = new Map();
-    for (const event of prior) {
-        if (event.type !== EventType.NET_REQUEST)
-            continue;
-        const body = parse(event.data['responseBody']);
-        if (body !== undefined)
-            moneyByEntity(body, known);
-    }
-    const found = [];
-    const seen = new Set();
-    for (const event of events) {
-        if (event.type !== EventType.NET_REQUEST)
-            continue;
-        const url = 'string' === typeof event.data['url'] ? event.data['url'] : '';
-        const requestBody = parse(event.data['requestBody']);
-        // Compare BEFORE recording this call's own response, or a request that echoes its own reply
-        // would compare against itself.
-        if ('object' === typeof requestBody && requestBody !== null) {
-            const sentFields = requestBody;
-            for (const id of idsIn(url, requestBody)) {
-                const fields = known.get(id);
-                if (fields === undefined)
-                    continue;
-                for (const [key, sent] of Object.entries(sentFields)) {
-                    if (!MONEY_FIELDS.has(key) || typeof sent !== 'number')
-                        continue;
-                    const priorValue = fields.get(key);
-                    if (priorValue === undefined)
-                        continue;
-                    const scale = scaleBetween(priorValue, sent);
-                    if (scale === undefined)
-                        continue;
-                    const key2 = `${id}:${key}`;
-                    if (seen.has(key2))
-                        continue;
-                    seen.add(key2);
-                    found.push({
-                        kind: ContradictionKind.UNIT_MISMATCH,
-                        claim: `the request sent ${key}=${String(sent)} and the server accepted it`,
-                        counter: `the API reports ${key}=${String(priorValue)} for ${id} — the value sent is ${String(scale)}x SMALLER, i.e. a major-unit number written into a minor-unit field`,
-                        detail: `${url} — at this scale the operation moves ${String(sent)} minor units instead of ${String(priorValue)}; nothing else can see this, because the number sent is exactly the number rendered on screen`,
-                    });
-                }
-            }
-        }
-        const responseBody = parse(event.data['responseBody']);
-        if (responseBody !== undefined)
-            moneyByEntity(responseBody, known);
-    }
-    return found;
-}

package/dist/flows/affected-tools.d.ts

@@ -1,18 +0,0 @@
-import type { ToolDef } from '../tools/tools.js';
-/**
- * `reticle_affected` — which saved flows must re-verify for a set of changed files.
- *
- * This logic already existed as `reticle affected`, deliberately kept off the MCP surface because an
- * advertised tool costs tokens on every turn whether or not it is used. That reasoning is right, and
- * this does not change it: the tool is NOT advertised by any profile. It is reachable through
- * `reticle_run`, so it costs nothing per turn and is still discoverable via `reticle_tools`.
- *
- * What the reasoning missed is who holds the question. The AGENT is the one that just edited files
- * and has to decide what to re-check; a shell command it may not be able to run is not an answer for
- * an MCP client that has no shell. Leaving it CLI-only meant the party with the diff could not ask
- * the party with the index.
- *
- * Unknown-provenance flows are returned as affected (fail-safe) AND listed separately, so "re-verify
- * this" is never confused with "this definitely touches your change".
- */
-export declare const AFFECTED_TOOLS: ToolDef[];

package/dist/flows/affected-tools.js

@@ -1,80 +0,0 @@
-import { z } from 'zod';
-import { ReticleTool } from '../tools/tool-names.js';
-import { loadNamedFlows, resolveChangedFiles } from '../cli/cli-flow-commands.js';
-import { sessionRoot, sessionProjectId } from '../project/session-root.js';
-import { affectedSavedFlows } from './flow-sources.js';
-/**
- * `reticle_affected` — which saved flows must re-verify for a set of changed files.
- *
- * This logic already existed as `reticle affected`, deliberately kept off the MCP surface because an
- * advertised tool costs tokens on every turn whether or not it is used. That reasoning is right, and
- * this does not change it: the tool is NOT advertised by any profile. It is reachable through
- * `reticle_run`, so it costs nothing per turn and is still discoverable via `reticle_tools`.
- *
- * What the reasoning missed is who holds the question. The AGENT is the one that just edited files
- * and has to decide what to re-check; a shell command it may not be able to run is not an answer for
- * an MCP client that has no shell. Leaving it CLI-only meant the party with the diff could not ask
- * the party with the index.
- *
- * Unknown-provenance flows are returned as affected (fail-safe) AND listed separately, so "re-verify
- * this" is never confused with "this definitely touches your change".
- */
-export const AFFECTED_TOOLS = [
-    {
-        name: ReticleTool.AFFECTED,
-        description: 'Which saved flows must re-verify for a set of changed files. Pass the files you edited (and/or `since` for a git ref to diff against). Returns { changedFiles, affected, unknownProvenance } — `affected` is what to re-run, and `unknownProvenance` are flows included only because Reticle cannot tell which sources they cover, so they are re-verified by default rather than silently skipped.',
-        example: { files: ['src/App.tsx'] },
-        inputSchema: {
-            files: z
-                .array(z.string())
-                .optional()
-                .describe('Changed file paths, repo-relative (e.g. ["src/App.tsx"]).'),
-            since: z
-                .string()
-                .optional()
-                .describe('Git ref to diff against (e.g. "HEAD~1", "main"). Unioned with `files`.'),
-        },
-        outputSchema: {
-            changedFiles: z.array(z.string()),
-            affected: z.array(z.string()),
-            unknownProvenance: z.array(z.string()),
-        },
-        handler: async (deps, args) => {
-            const files = Array.isArray(args['files'])
-                ? args['files'].filter((f) => 'string' === typeof f)
-                : [];
-            const since = 'string' === typeof args['since'] ? args['since'] : undefined;
-            // Same address as verify_change, resolved the same way: `deps.reticleRoot` is the configured
-            // project directory (the daemon's cwd is not), and the session names which project's flows.
-            const changed = await resolveChangedFiles(files, since, deps.reticleRoot);
-            const changedFiles = changed.files;
-            // No `sessionId` on this tool's surface, and it does not need one: passing `undefined`
-            // resolves the single connected session, and falls back exactly as before when it cannot.
-            // Adding an argument here would be a surface change to fix an addressing bug.
-            const flows = await loadNamedFlows(deps.fs, sessionRoot(deps, undefined), sessionProjectId(deps, undefined));
-            const result = affectedSavedFlows(flows, changedFiles);
-            // Three different situations produced the same empty answer: no files changed, no flows saved,
-            // and a git ref that resolved to nothing. Only the first means "nothing to re-verify"; the
-            // others mean the question could not be answered, and re-running nothing on that basis is how a
-            // regression ships. Say which one it is.
-            const why = 
-            // A git failure OUTRANKS every other explanation: the others describe a question that was
-            // answered, and this one is a question that was not. Reporting "nothing changed" over a
-            // mistyped ref or a shallow clone is how a regression ships past the tool meant to catch it.
-            changed.failed
-                ? `could not read the diff for \`${String(since)}\`, so NOTHING was compared and this result proves nothing: ${changed.reason ?? 'git failed'}`
-                : 0 === flows.length
-                    ? 'no saved flows exist yet, so nothing COULD be affected — record one with reticle_record then reticle_flow_save'
-                    : 0 === changedFiles.length
-                        ? since === undefined && 0 === files.length
-                            ? 'no files were given and no `since` ref was passed, so nothing was compared — pass the files you edited, or a git ref'
-                            : 'nothing changed against that input, so no saved flow needs re-verifying'
-                        : undefined;
-            return {
-                changedFiles,
-                ...result,
-                ...(why === undefined ? {} : { observed: true, note: why }),
-            };
-        },
-    },
-];

package/dist/flows/affected.d.ts

@@ -1,24 +0,0 @@
-/**
- * The file→flow reverse index — the heart of the unavoidable loop. When a file changes, which flows must
- * re-verify? A flow persists the source files its anchors were stamped from (its "sources manifest"); a
- * changed file that appears in a flow's manifest makes that flow affected. A flow with NO manifest
- * (recorded before v2.2, or un-stampable) is `unknown` — and unknown always means affected, never
- * silently skipped: the loop fails safe toward re-verifying.
- */
-export interface FlowSources {
-    name: string;
-    /** Repo-relative source files this flow's anchors came from. Empty/absent ⇒ unknown provenance. */
-    sources?: readonly string[];
-}
-export interface AffectedResult {
-    /** Flows to re-verify: those touching a changed file, plus all unknown-provenance flows. */
-    affected: string[];
-    /** Of the affected, which were included only because their provenance is unknown (fail-safe). */
-    unknownProvenance: string[];
-}
-/**
- * Which flows are affected by a set of changed files. Deterministic; a flow with no sources manifest is
- * always affected (fail-safe). `changedFiles` and flow sources are matched by normalized path suffix so
- * a repo-relative change matches an absolute stamp and vice-versa.
- */
-export declare function affectedFlows(flows: readonly FlowSources[], changedFiles: readonly string[]): AffectedResult;

package/dist/flows/affected.js

@@ -1,35 +0,0 @@
-/**
- * The file→flow reverse index — the heart of the unavoidable loop. When a file changes, which flows must
- * re-verify? A flow persists the source files its anchors were stamped from (its "sources manifest"); a
- * changed file that appears in a flow's manifest makes that flow affected. A flow with NO manifest
- * (recorded before v2.2, or un-stampable) is `unknown` — and unknown always means affected, never
- * silently skipped: the loop fails safe toward re-verifying.
- */
-/** Normalize a path for comparison — strip a leading./ and any file:line suffix. */
-function normalize(path) {
-    return path.replace(/^\.\//, '').replace(/:\d+(:\d+)?$/, '');
-}
-/**
- * Which flows are affected by a set of changed files. Deterministic; a flow with no sources manifest is
- * always affected (fail-safe). `changedFiles` and flow sources are matched by normalized path suffix so
- * a repo-relative change matches an absolute stamp and vice-versa.
- */
-export function affectedFlows(flows, changedFiles) {
-    const changed = changedFiles.map(normalize);
-    const matchesChange = (source) => {
-        const s = normalize(source);
-        return changed.some((c) => c === s || c.endsWith(`/${s}`) || s.endsWith(`/${c}`));
-    };
-    const affected = [];
-    const unknownProvenance = [];
-    for (const flow of flows) {
-        if (flow.sources === undefined || 0 === flow.sources.length) {
-            affected.push(flow.name);
-            unknownProvenance.push(flow.name);
-            continue;
-        }
-        if (flow.sources.some(matchesChange))
-            affected.push(flow.name);
-    }
-    return { affected, unknownProvenance };
-}

package/dist/flows/annotate-tools.d.ts

@@ -1,15 +0,0 @@
-import type { ToolDef } from '../tools/tools.js';
-/**
- * The reticle_annotate tool. A STRUCTURED annotation (the AnnotationSchema
- * discriminated union) is compiled into the live recording's per-step expect / flow dynamic[] /
- * flow success, which reticle_flow_save then folds onto disk. Returns the AnnotateResult envelope
- * with the compiled-predicate confirmation text ("will assert signal diff:shown").
- *
- * FIRST CUT: structured annotations only. A free NATURAL-LANGUAGE annotation never compiles — it
- * fails AnnotationSchema and is returned as UNKNOWN_KIND. NL → predicate compilation is explicitly
- * FUTURE; no NL parser exists or is faked here.
- *
- * No-active-recording and no-step are SAFE, returned as structured codes (never thrown), so an
- * agent that annotates at the wrong moment gets a clear error rather than a crash.
- */
-export declare const ANNOTATE_TOOLS: ToolDef[];