@reticlehq/server 2.7.0 → 2.9.0

package/dist/tools/react-grace.js

@@ -0,0 +1,90 @@
+/**
+ * "The app ignored this response" is only sayable once the app has had a chance to read it.
+ *
+ * `response-ignored` fires when a write succeeded on the server and nothing on the client moved. It
+ * is a real and valuable finding — a lost write, a response parsed into the void, a render that never
+ * happened. It is also an ACCUSATION, and it is decided by where a window happens to end.
+ *
+ * Waiting for in-flight requests before taking the verdict made that boundary dangerous in a way it
+ * was not before. Previously the write was still pending when the window closed, so it never reached
+ * the settled list and this rule could not fire at all. Now the response lands inside the window BY
+ * DESIGN — and the app's re-render happens in a later task, a few milliseconds after it. Close the
+ * window in that gap and every channel agrees that the app took a successful write and did nothing.
+ *
+ * The verdict is then `verified:"no"` on a completely correct application, produced entirely by where
+ * we chose to stop looking. For a verification tool that is the more damaging direction of error: a
+ * false green is a missed catch, but a false accusation sends someone to fix code that is not broken,
+ * and it is how the instrument stops being believed.
+ *
+ * So the response is not the end of the window — the app's REACTION to it is. The grace is paid only
+ * in the exact case that would otherwise be accused: a successful mutating write with nothing moved
+ * after it. Every other action returns without a single poll.
+ *
+ * Deliberately short. This covers a task-boundary re-render, not a slow app: if nothing has moved
+ * within the grace, "ignored" has become an honest description and the finding should stand.
+ */
+import { EventType, MUTATING_METHODS } from '@reticlehq/core';
+/**
+ * How long to let the app react. A React commit after a resolved fetch is one or two task hops; this
+ * is generous against that and still far too short to paper over an app that genuinely dropped the
+ * response.
+ */
+const REACTION_GRACE_MS = 300;
+/** Poll cadence — the same as the settle wait, for the same reason. */
+const POLL_MS = 50;
+/** Movement that would clear `response-ignored`; mirrors `uiAdvanced` in the detector. */
+const MOVEMENT = new Set([
+    EventType.DOM_ADDED,
+    EventType.DOM_REMOVED,
+    EventType.DOM_ATTR,
+    EventType.DOM_TEXT,
+    EventType.STATE_CHANGE,
+    EventType.ROUTE_CHANGE,
+]);
+function moved(events) {
+    return events.some((e) => MOVEMENT.has(e.type));
+}
+/**
+ * Is this a window that would be wrongly accused if it ended right now?
+ *
+ * True only for the accusable shape: a SUCCESSFUL MUTATING request settled, and nothing has moved. A
+ * read that changed nothing is a prefetch, a failed write is a different finding entirely, and an
+ * action that already moved the UI has nothing to wait for — none of them buy a grace period.
+ *
+ * "Mutating" is read from the same constant the accuser uses rather than restated here. Restating it
+ * is how `IPC` came to be absent from this list and present in that one, so on a desktop app every
+ * successful write skipped the grace and a correct app was told it had ignored its own response.
+ */
+export function awaitsReaction(events) {
+    if (moved(events))
+        return false;
+    return events.some((e) => {
+        if (e.type !== EventType.NET_REQUEST)
+            return false;
+        const method = 'string' === typeof e.data['method'] ? e.data['method'].toUpperCase() : '';
+        const ok = e.data['ok'];
+        return MUTATING_METHODS.includes(method) && true === ok;
+    });
+}
+/**
+ * Wait, bounded by BOTH the grace and the caller's remaining budget, for the app to react to a write
+ * it has just been told succeeded.
+ *
+ * Returns whether the app moved. A `false` is not a verdict — it hands the question back to the
+ * contradiction engine, which will raise `response-ignored` exactly as it does today. The point is
+ * only that by then the app has been given its chance, so the finding means what it says.
+ */
+export async function waitForReaction(session, since, budgetMs, opts) {
+    if (!awaitsReaction(session.eventsSince(since)))
+        return true;
+    const window = Math.min(REACTION_GRACE_MS, budgetMs);
+    if (window <= 0)
+        return false;
+    const deadline = session.elapsed() + window;
+    while (session.elapsed() < deadline) {
+        await opts.sleep(Math.min(POLL_MS, deadline - session.elapsed()));
+        if (moved(session.eventsSince(since)))
+            return true;
+    }
+    return false;
+}

package/dist/tools/read-tools.js

@@ -11,7 +11,7 @@ import { replayProgram } from '../flows/replay.js';
 import { diffLines } from '../project/baselines.js';
 import { selectPath, capDepth, projectComponentState } from '../session/state-select.js';
 import { costHint } from '../session/output-budget.js';
-import { buildReactionReport } from '../events/reaction.js';
+import { buildReactionReport, summarizeReaction } from '../events/reaction.js';
 import { asString, asNumber, parseInteractive } from './tools-helpers.js';
 import { sessionIdShape, commandOrThrow, snapshotTree } from './tool-kit.js';
 import { bufferEnvelope } from '../session/session-health.js';
@@ -39,6 +39,15 @@ function unanchoredWarning(count) {
 const HUD_LEVELS = ['info', 'warn', 'error'];
 const HUD_LEVEL_LIST = HUD_LEVELS.join(' | ');
 const hudLevelEnum = z.enum(HUD_LEVELS);
+/**
+ * How deep an unscoped `reticle_state` read goes before collapsing to size markers.
+ *
+ * 3 keeps every store name and every top-level key visible — enough to see what exists and to name a
+ * `path` — while collapsing the collections that make an unscoped read enormous. Measured on the
+ * bench fixture: unbounded 10,119 B, depth 4 1,323 B, depth 3 596 B, depth 2 322 B. Two loses the
+ * per-store keys, which is the orientation the next call needs.
+ */
+const DEFAULT_STATE_DEPTH = 1;
 export const READ_TOOLS = [
     {
         name: ReticleTool.BASELINE_SAVE,
@@ -178,17 +187,33 @@ export const READ_TOOLS = [
             const report = buildReactionReport(events, session.elapsed() - rec.cursor);
             // Self-generating oracles: propose ranked mustHold from what the recorded window actually did.
             const proposedConsequences = proposeConsequences(events);
-            return Promise.resolve({
+            const digest = summarizeReaction(report);
+            // Say that the timeline was left out, and where it lives.
+            //
+            // Dropping the raw events is right: they were most of a response large enough to truncate the
+            // part that mattered. But a field that simply stops appearing is indistinguishable from one
+            // this version never had, and an agent cannot ask for something it does not know exists. The
+            // same rule the capped diff arrays follow: a trim is never silent.
+            const timeline = events.length > 0
+                ? {
+                    timeline_omitted: `${String(events.length)} event(s) were recorded and are not included here. Call reticle_observe { since: ${String(rec.cursor)} } for the raw timeline.`,
+                }
+                : {};
+            const body = {
                 recordingName: name,
                 program,
+                ...timeline,
                 ...(unstable > 0
                     ? {
                         warning: unanchoredWarning(unstable),
                     }
                     : {}),
                 ...(proposedConsequences.length > 0 ? { proposedConsequences } : {}),
-                ...report,
-                cost: costHint(report, events.length),
+                ...digest,
+            };
+            return Promise.resolve({
+                ...body,
+                cost: costHint(body, events.length),
             });
         },
     },
@@ -379,7 +404,44 @@ export const READ_TOOLS = [
                 return { ...root, storeNames: names };
             }
             if (path === undefined && depth === undefined) {
-                return { ...root, storeNames: names }; // unchanged shape, safe storeNames
+                // An unscoped read used to hand back the WHOLE store tree: 10,119 bytes on this repo's own
+                // fixture. A tool result is not paid once — it stays in the conversation and is re-sent on
+                // every later turn, so one such read cost roughly 34,000 tokens across a 16-turn run.
+                //
+                // The VALUES are bounded; the ENVELOPE is not touched. `{ stores, storeNames, component }`
+                // is the documented shape and callers depend on it — a first attempt applied the bound by
+                // routing through the path selector, which silently changed the reply to `{ found, value }`
+                // and took the component projection and the bridge round-trip with it. Capping in place
+                // keeps every store name and the component read exactly where they were; only collections
+                // deeper than the bound collapse to a marker like "[Array(40)]", which still says what is
+                // there and how much of it.
+                //
+                // A default, not a cap: any explicit `depth` is honoured at any value, and `path` reads a
+                // sub-tree at full fidelity. Nothing became unreachable, only cheaper by default.
+                const stores = root.stores;
+                const bounded = 'object' === typeof stores && null !== stores
+                    ? Object.fromEntries(Object.entries(stores).map(([k, v]) => [k, capDepth(v, DEFAULT_STATE_DEPTH)]))
+                    : undefined;
+                // Say that it was bounded, and only when it actually was. A read that quietly hands back
+                // less than it was asked for is the shape of a false green: the agent sees
+                // `deployments: "[Array(40)]"`, concludes it has read the store, and asserts over a summary.
+                // The marker alone is suggestive; this makes it explicit and names the way to the real value.
+                const trimmed = bounded !== undefined && JSON.stringify(bounded) !== JSON.stringify(stores);
+                return {
+                    ...root,
+                    ...(bounded === undefined ? {} : { stores: bounded }),
+                    storeNames: names,
+                    ...(trimmed
+                        ? {
+                            truncation: {
+                                note: `bounded to depth ${String(DEFAULT_STATE_DEPTH)} per store — this is NOT the ` +
+                                    'whole store. Values shown as "[Array(n)]" or "{…n keys}" were collapsed; read ' +
+                                    'one with { store, path } (e.g. { store:"app", path:"deployments.0" }) or pass ' +
+                                    'an explicit `depth` for more.',
+                            },
+                        }
+                        : {}),
+                };
             }
             // Back-compat: an older browser returned the whole store; scope it here (may already be
             // size-truncated in transit for a very large store — that is the limitation this fix removes

package/dist/tools/resolve-target.d.ts

@@ -0,0 +1,33 @@
+/** One candidate the browser returned for a target query. */
+export interface TargetCandidate {
+    ref?: unknown;
+    role?: unknown;
+    name?: unknown;
+    visible?: unknown;
+}
+/** What the resolution produced: a ref to act on, or the reason there isn't one. */
+export type TargetResolution = {
+    readonly kind: 'ref';
+    readonly ref: string;
+} | {
+    readonly kind: 'error';
+    readonly message: string;
+};
+/**
+ * Turn a target QUERY into the single ref an action can be performed on.
+ *
+ * `act_and_wait` took only a `ref`, so every verification cost a `reticle_query` turn first just to
+ * learn one string. The advertised tool surface is re-sent on every turn, so that extra turn was not
+ * a small cost: measured on the wire, a two-turn verification spent 10,756 of its 11,235 tokens on
+ * schema and 479 on the actual answers. Removing the turn removes half the schema bill.
+ *
+ * Ambiguity is an ERROR, never a pick. Choosing "the first match" would let a verification act on a
+ * different element than the author meant and still report success, which is the false green this
+ * product exists to prevent — and the failure is invisible, because the verdict describes the
+ * element it DID act on. The message names the candidates so the caller can narrow rather than guess.
+ *
+ * Invisible matches are filtered before counting: a hidden duplicate is a common way for a
+ * legitimately unambiguous query to look ambiguous, and refusing on it would push callers back to
+ * the two-turn path for no gain.
+ */
+export declare function resolveTargetRef(candidates: readonly unknown[]): TargetResolution;

package/dist/tools/resolve-target.js

@@ -0,0 +1,53 @@
+import { asRecord } from './tools-helpers.js';
+/**
+ * Turn a target QUERY into the single ref an action can be performed on.
+ *
+ * `act_and_wait` took only a `ref`, so every verification cost a `reticle_query` turn first just to
+ * learn one string. The advertised tool surface is re-sent on every turn, so that extra turn was not
+ * a small cost: measured on the wire, a two-turn verification spent 10,756 of its 11,235 tokens on
+ * schema and 479 on the actual answers. Removing the turn removes half the schema bill.
+ *
+ * Ambiguity is an ERROR, never a pick. Choosing "the first match" would let a verification act on a
+ * different element than the author meant and still report success, which is the false green this
+ * product exists to prevent — and the failure is invisible, because the verdict describes the
+ * element it DID act on. The message names the candidates so the caller can narrow rather than guess.
+ *
+ * Invisible matches are filtered before counting: a hidden duplicate is a common way for a
+ * legitimately unambiguous query to look ambiguous, and refusing on it would push callers back to
+ * the two-turn path for no gain.
+ */
+export function resolveTargetRef(candidates) {
+    const all = candidates.map((c) => asRecord(c));
+    const visible = all.filter((c) => c.visible !== false);
+    const usable = visible.length > 0 ? visible : all;
+    if (0 === usable.length) {
+        return {
+            kind: 'error',
+            message: 'target matched no element. Nothing was acted on and no verdict is possible — widen the ' +
+                'query, or take a reticle_snapshot to see what is actually on the page.',
+        };
+    }
+    if (usable.length > 1) {
+        const named = usable
+            .slice(0, 5)
+            .map((c) => {
+            const role = 'string' === typeof c.role ? c.role : '?';
+            const name = 'string' === typeof c.name ? c.name : '';
+            const ref = 'string' === typeof c.ref ? c.ref : '?';
+            return name.length > 0 ? `${ref} (${role} "${name}")` : `${ref} (${role})`;
+        })
+            .join(', ');
+        return {
+            kind: 'error',
+            message: `target matched ${String(usable.length)} elements and an action must not guess between ` +
+                `them: ${named}. Narrow the query (add role/name/testid or a scope), or pass an explicit ` +
+                '`ref` from reticle_query.',
+        };
+    }
+    const only = usable[0];
+    const ref = only === undefined ? undefined : only.ref;
+    if ('string' !== typeof ref || 0 === ref.length) {
+        return { kind: 'error', message: 'target matched an element with no usable ref.' };
+    }
+    return { kind: 'ref', ref };
+}

package/dist/tools/settle-in-flight.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Spend the budget you were given before reporting that you ran out of certainty.
+ *
+ * `waitForPredicate` resolves the instant the predicate holds. On an app that navigates
+ * optimistically — which is normal, correct behaviour, and the norm on exactly the flows agents
+ * verify most: login, submit, save — that instant arrives while the write is still in flight. The
+ * verdict was then taken over a window the app had not finished writing, and came back
+ * `unknown / unsettled` with a recovery note asking the CALLER to re-check.
+ *
+ * Measured on the most common flow there is: a login that genuinely succeeded returned at 492ms out
+ * of an 8000ms budget. The declared signal had fired with matching data, state had moved from
+ * anonymous to authenticated, the token was in storage, honesty grade was `signal` and capture
+ * integrity was clean. Seven and a half seconds of authorised waiting went unused, and the agent was
+ * handed a shrug.
+ *
+ * A false NEGATIVE is not the mirror of a false positive here. A false positive stops an agent early;
+ * a false negative makes it redo work that already succeeded, and — far worse — teaches it to
+ * discount the verdict channel. The verdict channel is the entire product, and an agent that learns
+ * to ignore `unknown` will ignore the true ones too.
+ *
+ * What this does NOT do is decide the request succeeded. At 492ms nobody can know that, and inventing
+ * a green here would be the exact defect this product exists to prevent. It waits for the answer
+ * rather than guessing at it:
+ *
+ *   - everything settles → the normal contradiction machinery sees the real responses, so a failure
+ *     still contradicts and a success no longer looks like an absence;
+ *   - still in flight when the budget genuinely runs out → `unsettled`, as before, but now an honest
+ *     limit instead of an early exit.
+ */
+/** Just the shape this needs — a real Session satisfies it, and a test can supply it. */
+export interface SettleSource {
+    eventsSince(cursor: number): readonly {
+        type: string;
+        data: Record<string, unknown>;
+    }[];
+    elapsed(): number;
+}
+interface WaitOpts {
+    /** Injected so the wait is testable without real time passing (rule: never call the clock inline). */
+    sleep(ms: number): Promise<void>;
+}
+/**
+ * Requests that started in this window and have not come back.
+ *
+ * A settle for a request this window never saw START is ignored on purpose: the window is floored at
+ * the act cursor, so a response belonging to an earlier action can land inside it, and counting that
+ * as progress would let unrelated traffic close the window early.
+ */
+export declare function inFlightRequestIds(events: readonly {
+    type: string;
+    data: Record<string, unknown>;
+}[]): string[];
+/**
+ * The same outstanding requests, as "METHOD url" — what an unsettled verdict has to be able to name.
+ *
+ * A correlation id is the right key for the wait and useless in a sentence: an agent told that
+ * `r-17` is open cannot act on it, while `POST /api/login` is the thing to re-check or to assert
+ * directly. Read off the NET_PENDING the window already holds, so this costs one pass over events
+ * that are in hand.
+ */
+export declare function inFlightRequestLabels(events: readonly {
+    type: string;
+    data: Record<string, unknown>;
+}[]): string[];
+/**
+ * Endpoints called MORE THAN ONCE in this window, busiest first, as "METHOD url ×N".
+ *
+ * The other half of an honest `unsettled`. A retrying query against a dead backend leaves nothing in
+ * flight — every attempt comes back, then the next one fires — so the verdict fell through to "what
+ * kept the page busy was its own churn (a poll, a timer, an animation)", which names three things
+ * and points at none of them. Measured in the field: on an app with a background retry loop
+ * `act_and_wait` could never return a pass, and nothing in the verdict said which endpoint to look
+ * at. This does not judge the repetition — a poll is legitimate — it reports it, which is all an
+ * agent needs to tell "my assertion was wrong" from "this app never quiets".
+ */
+export declare function repeatedRequestLabels(events: readonly {
+    type: string;
+    data: Record<string, unknown>;
+}[]): string[];
+export interface SettleResult {
+    /** True when nothing this window started is still outstanding. */
+    settled: boolean;
+    /** What was still open when the wait ended — empty when `settled`. */
+    stillInFlight: string[];
+}
+/**
+ * Wait, bounded by `budgetMs`, for the requests this window started to come back.
+ *
+ * Returns immediately when nothing is in flight, so the common green path — an action with no traffic
+ * — pays nothing at all. A zero or negative budget means no wait: the caller may have spent the whole
+ * timeout reaching the predicate, and a negative deadline must mean "stop", never "loop forever".
+ */
+export declare function waitForInFlight(session: SettleSource, since: number, budgetMs: number, opts: WaitOpts): Promise<SettleResult>;
+export {};

package/dist/tools/settle-in-flight.js

@@ -0,0 +1,146 @@
+/**
+ * Spend the budget you were given before reporting that you ran out of certainty.
+ *
+ * `waitForPredicate` resolves the instant the predicate holds. On an app that navigates
+ * optimistically — which is normal, correct behaviour, and the norm on exactly the flows agents
+ * verify most: login, submit, save — that instant arrives while the write is still in flight. The
+ * verdict was then taken over a window the app had not finished writing, and came back
+ * `unknown / unsettled` with a recovery note asking the CALLER to re-check.
+ *
+ * Measured on the most common flow there is: a login that genuinely succeeded returned at 492ms out
+ * of an 8000ms budget. The declared signal had fired with matching data, state had moved from
+ * anonymous to authenticated, the token was in storage, honesty grade was `signal` and capture
+ * integrity was clean. Seven and a half seconds of authorised waiting went unused, and the agent was
+ * handed a shrug.
+ *
+ * A false NEGATIVE is not the mirror of a false positive here. A false positive stops an agent early;
+ * a false negative makes it redo work that already succeeded, and — far worse — teaches it to
+ * discount the verdict channel. The verdict channel is the entire product, and an agent that learns
+ * to ignore `unknown` will ignore the true ones too.
+ *
+ * What this does NOT do is decide the request succeeded. At 492ms nobody can know that, and inventing
+ * a green here would be the exact defect this product exists to prevent. It waits for the answer
+ * rather than guessing at it:
+ *
+ *   - everything settles → the normal contradiction machinery sees the real responses, so a failure
+ *     still contradicts and a success no longer looks like an absence;
+ *   - still in flight when the budget genuinely runs out → `unsettled`, as before, but now an honest
+ *     limit instead of an early exit.
+ */
+import { EventType, isDevToolingUrl } from '@reticlehq/core';
+/**
+ * The dev toolchain talking about ITSELF is not the app finishing its work.
+ *
+ * `evalSettled` and `findContradictions` both drop it already; this file read the raw window, so the
+ * exclusion was cosmetic exactly where it decides a verdict. Reported from a real drive: a
+ * deliberately disabled control — no state change, no storage change, zero application requests —
+ * was graded on the strength of a Next webpack hot-update the same payload printed as ignored.
+ */
+const isDevTooling = (data) => isDevToolingUrl('string' === typeof data['url'] ? data['url'] : undefined);
+/** How often to re-read the buffer. Short enough to return promptly, long enough not to spin. */
+const POLL_MS = 50;
+const idOf = (data) => 'string' === typeof data['id'] ? data['id'] : undefined;
+/**
+ * Requests that started in this window and have not come back.
+ *
+ * A settle for a request this window never saw START is ignored on purpose: the window is floored at
+ * the act cursor, so a response belonging to an earlier action can land inside it, and counting that
+ * as progress would let unrelated traffic close the window early.
+ */
+export function inFlightRequestIds(events) {
+    const settled = new Set();
+    for (const e of events) {
+        if (e.type !== EventType.NET_REQUEST)
+            continue;
+        const id = idOf(e.data);
+        if (id !== undefined)
+            settled.add(id);
+    }
+    const open = [];
+    for (const e of events) {
+        if (e.type !== EventType.NET_PENDING || isDevTooling(e.data))
+            continue;
+        const id = idOf(e.data);
+        if (id !== undefined && !settled.has(id) && !open.includes(id))
+            open.push(id);
+    }
+    return open;
+}
+/**
+ * The same outstanding requests, as "METHOD url" — what an unsettled verdict has to be able to name.
+ *
+ * A correlation id is the right key for the wait and useless in a sentence: an agent told that
+ * `r-17` is open cannot act on it, while `POST /api/login` is the thing to re-check or to assert
+ * directly. Read off the NET_PENDING the window already holds, so this costs one pass over events
+ * that are in hand.
+ */
+export function inFlightRequestLabels(events) {
+    const open = new Set(inFlightRequestIds(events));
+    const labels = [];
+    for (const e of events) {
+        if (e.type !== EventType.NET_PENDING)
+            continue;
+        const id = idOf(e.data);
+        if (id === undefined || !open.has(id))
+            continue;
+        open.delete(id); // one label per request, however many times its start was recorded
+        const method = 'string' === typeof e.data['method'] ? e.data['method'] : 'request';
+        const url = 'string' === typeof e.data['url'] ? e.data['url'] : 'an unreported url';
+        labels.push(`${method} ${url}`);
+    }
+    return labels;
+}
+/** Enough to recognise the loop; a busy dashboard must not spend the verdict on a URL list. */
+const MAX_REPEATED = 3;
+/** One call is traffic. Two to the same endpoint inside one window is a repeat. */
+const MIN_REPEATS = 2;
+/**
+ * Endpoints called MORE THAN ONCE in this window, busiest first, as "METHOD url ×N".
+ *
+ * The other half of an honest `unsettled`. A retrying query against a dead backend leaves nothing in
+ * flight — every attempt comes back, then the next one fires — so the verdict fell through to "what
+ * kept the page busy was its own churn (a poll, a timer, an animation)", which names three things
+ * and points at none of them. Measured in the field: on an app with a background retry loop
+ * `act_and_wait` could never return a pass, and nothing in the verdict said which endpoint to look
+ * at. This does not judge the repetition — a poll is legitimate — it reports it, which is all an
+ * agent needs to tell "my assertion was wrong" from "this app never quiets".
+ */
+export function repeatedRequestLabels(events) {
+    const counts = new Map();
+    for (const e of events) {
+        if (e.type !== EventType.NET_REQUEST || isDevTooling(e.data))
+            continue;
+        const method = 'string' === typeof e.data['method'] ? e.data['method'] : 'request';
+        const url = 'string' === typeof e.data['url'] ? e.data['url'] : 'an unreported url';
+        const key = `${method} ${url}`;
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return [...counts.entries()]
+        .filter(([, count]) => count >= MIN_REPEATS)
+        .sort(([, a], [, b]) => b - a)
+        .slice(0, MAX_REPEATED)
+        .map(([key, count]) => `${key} ×${String(count)}`);
+}
+/**
+ * Wait, bounded by `budgetMs`, for the requests this window started to come back.
+ *
+ * Returns immediately when nothing is in flight, so the common green path — an action with no traffic
+ * — pays nothing at all. A zero or negative budget means no wait: the caller may have spent the whole
+ * timeout reaching the predicate, and a negative deadline must mean "stop", never "loop forever".
+ */
+export async function waitForInFlight(session, since, budgetMs, opts) {
+    let open = inFlightRequestIds(session.eventsSince(since));
+    if (0 === open.length)
+        return { settled: true, stillInFlight: [] };
+    if (budgetMs <= 0)
+        return { settled: false, stillInFlight: open };
+    const deadline = session.elapsed() + budgetMs;
+    while (session.elapsed() < deadline) {
+        // Never overshoot the budget: the last sleep is trimmed to whatever is actually left.
+        await opts.sleep(Math.min(POLL_MS, deadline - session.elapsed()));
+        open = inFlightRequestIds(session.eventsSince(since));
+        if (0 === open.length)
+            return { settled: true, stillInFlight: [] };
+    }
+    return { settled: false, stillInFlight: open };
+}

package/dist/tools/snapshot-delta.d.ts

@@ -21,16 +21,24 @@ export type SnapshotDeltaMode = (typeof SnapshotDeltaMode)[keyof typeof Snapshot
 interface SnapshotDelta {
     added: string[];
     removed: string[];
+    changed: string[];
     addedCount: number;
     removedCount: number;
 }
+/** Where focus moved, when it moved. Absent fields mean nothing held focus on that side. */
+export interface FocusChange {
+    from?: string;
+    to?: string;
+}
 type DeltaDecision = {
     mode: typeof SnapshotDeltaMode.FULL;
 } | {
     mode: typeof SnapshotDeltaMode.UNCHANGED;
+    focusChanged?: FocusChange;
 } | {
     mode: typeof SnapshotDeltaMode.DELTA;
     delta: SnapshotDelta;
+    focusChanged?: FocusChange;
 };
 /** Pure: decide full vs delta vs unchanged given the previous tree (same route) and the next tree. */
 export declare function snapshotDelta(prevTree: string | undefined, nextTree: string): DeltaDecision;
@@ -38,6 +46,8 @@ export declare function snapshotDelta(prevTree: string | undefined, nextTree: st
 export declare class SnapshotCache {
     #private;
     constructor(max?: number);
+    /** True when an entry exists for this key (regardless of route match). */
+    has(key: string): boolean;
     /** Last tree for this key IF the route still matches; undefined when absent or route changed. */
     recall(key: string, route: string): string | undefined;
     remember(key: string, route: string, tree: string): void;