@reticlehq/server 2.11.0 → 2.13.0

package/dist/tools/assert-source.d.ts

@@ -0,0 +1,22 @@
+import type { Predicate } from '../events/predicate-schema.js';
+/**
+ * The `file:line` an ASSERTION is entitled to report — its own evidence, or nothing.
+ *
+ * `reticle_assert` and `reticle_wait_for` drive nothing, so the last act's source is whatever
+ * unrelated action ran before them. Journaling it made an assert on one component claim it had
+ * proven something about another, and an assert that matched nothing claim a location at all — a
+ * wrong file:line in front of an agent, persisted, and read back by `reticle_context` long after
+ * the turn that produced it.
+ *
+ * The one borrow that survives is the documented one, and only on a failure: a predicate with no DOM
+ * clause has no element to point at, and the handler that should have fired the missing signal or
+ * made the missing request lives with the control that was last driven. That is what the tools'
+ * output schemas describe, and it is a pointer to the code under test rather than a guess about
+ * which code this verdict was about.
+ */
+export declare function assertSource(facts: {
+    predicate: Predicate;
+    evidence: unknown;
+    pass: boolean;
+    lastActSource: string | undefined;
+}): string | undefined;

package/dist/tools/assert-source.js

@@ -0,0 +1,53 @@
+import { declaresDom } from '../events/predicate-asks.js';
+/**
+ * Where an assertion's OWN evidence is written, as `file:line`.
+ *
+ * The element descriptors an oracle returns already carry the nearest `data-reticle-source` the build
+ * plugin stamped, so a predicate that matched an element knows exactly where that element lives. It
+ * is only reported when every matched descriptor agrees: two loci and no way to choose is the same
+ * problem as no locus at all, and a guessed pointer costs the agent the trip AND leaves it further
+ * from the code.
+ *
+ * Near-miss evidence is deliberately NOT read. A near miss is a DIFFERENT element than the one the
+ * caller asked about, so its line is a suggestion dressed as a fact.
+ */
+function evidenceSource(evidence) {
+    if (!Array.isArray(evidence) || 0 === evidence.length)
+        return undefined;
+    let agreed;
+    for (const entry of evidence) {
+        if ('object' !== typeof entry || null === entry)
+            return undefined;
+        const found = entry.source;
+        if ('string' !== typeof found || 0 === found.length)
+            return undefined;
+        if (agreed === undefined)
+            agreed = found;
+        else if (agreed !== found)
+            return undefined;
+    }
+    return agreed;
+}
+/**
+ * The `file:line` an ASSERTION is entitled to report — its own evidence, or nothing.
+ *
+ * `reticle_assert` and `reticle_wait_for` drive nothing, so the last act's source is whatever
+ * unrelated action ran before them. Journaling it made an assert on one component claim it had
+ * proven something about another, and an assert that matched nothing claim a location at all — a
+ * wrong file:line in front of an agent, persisted, and read back by `reticle_context` long after
+ * the turn that produced it.
+ *
+ * The one borrow that survives is the documented one, and only on a failure: a predicate with no DOM
+ * clause has no element to point at, and the handler that should have fired the missing signal or
+ * made the missing request lives with the control that was last driven. That is what the tools'
+ * output schemas describe, and it is a pointer to the code under test rather than a guess about
+ * which code this verdict was about.
+ */
+export function assertSource(facts) {
+    const own = evidenceSource(facts.evidence);
+    if (own !== undefined)
+        return own;
+    if (facts.pass || declaresDom(facts.predicate))
+        return undefined;
+    return facts.lastActSource;
+}

package/dist/tools/assert-verdict.d.ts

@@ -1,4 +1,4 @@
-import type { InstrumentationGap } from '@reticlehq/core';
+import type { InstrumentationGap, JournalVerdictEffect } from '@reticlehq/core';
 import type { Predicate } from '../events/predicate.js';
 import type { Session } from '../session/session.js';
 import { type Contradiction } from '../events/contradictions.js';
@@ -15,7 +15,12 @@ import { type Contradiction } from '../events/contradictions.js';
  * consult it. Asserting a moment earlier — while the POST was still open — is the same story with a
  * different name: `request-never-settled`, also unreported.
  */
-export declare function assertVerdict(session: Session, predicate: Predicate, pass: boolean, since: number, 
+export declare function assertVerdict(session: Session, predicate: Predicate, pass: boolean, 
+/**
+ * What the oracle actually looked at. The only thing this verdict is entitled to point at — see
+ * `assertSource`, which reads the matched element descriptors' own `file:line`.
+ */
+evidence: unknown, since: number, 
 /** Set when the assertion was never evaluated — see honesty/verified.ts. */
 inconclusive?: string, 
 /**
@@ -23,9 +28,21 @@ inconclusive?: string,
  * `reticle_wait_for` reach the same disconnect path as the act tools, and a verdict that blames
  * the app for a lost connection is no more honest on this route than on that one.
  */
-observationLost?: boolean): Promise<{
+observationLost?: boolean, 
+/**
+ * Set when code changed since the last verdict with nothing declaring what it was for. Decided by
+ * `isChangeUndeclared` at the call site, which is the only place that can reach the intent ledger —
+ * this path takes a session and no `deps`.
+ */
+changeUndeclared?: boolean): Promise<{
     decision: Record<string, unknown>;
     contradictions: Contradiction[];
     coverage: Record<string, unknown>;
     gaps: InstrumentationGap[];
+    /**
+     * The bounded verdict, in the SAME shape `act_and_wait` writes into its journal action — so the
+     * journal holds one verdict shape rather than two and the run fold that reads it needs no second
+     * case. Built here because this is the one place that holds the typed decision and the predicate.
+     */
+    verdictEffect: JournalVerdictEffect;
 }>;

package/dist/tools/assert-verdict.js

@@ -1,11 +1,11 @@
-import { BlindSpotKind, CaptureLoss, PredicateKind } from '@reticlehq/core';
+import { CaptureLoss, PredicateKind } from '@reticlehq/core';
 import { gapsForAction } from '../honesty/instrumentation-gaps.js';
 import { noteSessionGaps } from '../honesty/gap-ledger.js';
 import { declaresState } from '../events/predicate-asks.js';
 import { isStateUnwatched } from '../honesty/blind-spots.js';
 import { findContradictions } from '../events/contradictions.js';
-import { declaredExpectations } from '../events/declared.js';
-import { blindSpotsFromState, buildCoverageStatement, Coverage, impeachesCapture, transportGapNote, } from '../honesty/blind-spots.js';
+import { declaredExpectations, declaresBodyIndependentChannel } from '../events/declared.js';
+import { absenceBlindSpotNote, blindSpotsFromState, buildCoverageStatement, restsOnCompleteWindow, Coverage, impeachesCapture, transportGapNote, } from '../honesty/blind-spots.js';
 import { buildHonestyBlock } from '../honesty/honesty.js';
 import { hasAcceptedWrite } from '../honesty/accepted-write.js';
 import { unreadWriteLabels } from '../honesty/unread-outcome.js';
@@ -13,17 +13,7 @@ import { decideVerified } from '../honesty/verified.js';
 import { describeWaitTarget } from '../honesty/unsettled.js';
 import { inFlightRequestLabels, repeatedRequestLabels } from './settle-in-flight.js';
 import { gradeOfPredicate } from './assert-grade.js';
-function absenceBlindSpotNote(predicate, spots) {
-    if (predicate.kind !== 'element' || predicate.absent !== true)
-        return undefined;
-    const relevant = spots.filter((spot) => spot.count > 0 &&
-        spot.kind === BlindSpotKind.CROSS_ORIGIN_IFRAME &&
-        undefined !== predicate.query.scope);
-    if (0 === relevant.length)
-        return undefined;
-    const statement = buildCoverageStatement(relevant);
-    return `the absence assertion targeted a region Reticle could not observe (${statement.note ?? 'partial coverage'}), so a passing DOM check cannot prove absence`;
-}
+import { assertSource } from './assert-source.js';
 /**
  * The honesty verdict for a plain `reticle_assert`.
  *
@@ -37,7 +27,12 @@ function absenceBlindSpotNote(predicate, spots) {
  * consult it. Asserting a moment earlier — while the POST was still open — is the same story with a
  * different name: `request-never-settled`, also unreported.
  */
-export async function assertVerdict(session, predicate, pass, since, 
+export async function assertVerdict(session, predicate, pass, 
+/**
+ * What the oracle actually looked at. The only thing this verdict is entitled to point at — see
+ * `assertSource`, which reads the matched element descriptors' own `file:line`.
+ */
+evidence, since, 
 /** Set when the assertion was never evaluated — see honesty/verified.ts. */
 inconclusive, 
 /**
@@ -45,13 +40,19 @@ inconclusive,
  * `reticle_wait_for` reach the same disconnect path as the act tools, and a verdict that blames
  * the app for a lost connection is no more honest on this route than on that one.
  */
-observationLost) {
+observationLost, 
+/**
+ * Set when code changed since the last verdict with nothing declaring what it was for. Decided by
+ * `isChangeUndeclared` at the call site, which is the only place that can reach the intent ledger —
+ * this path takes a session and no `deps`.
+ */
+changeUndeclared) {
     // Scope caveat, stated because it is a real limitation and not a bug: blind spots are tracked per
     // SESSION, not per assertion window, so a cross-origin iframe seen once marks every later verdict
     // in that session partial — including ones about a region it cannot affect. That errs toward
     // over-warning, which is the correct direction here: the failure this guards against is a green
     // that implies coverage it never had, and a needless caveat costs the agent a sentence.
-    const spots = blindSpotsFromState(session.blindSpots());
+    const spots = blindSpotsFromState(session.blindSpots(), session.runtime);
     const statement = buildCoverageStatement(spots);
     const absenceBlindSpot = absenceBlindSpotNote(predicate, spots);
     // Omitted entirely when coverage is full, so an intact page pays nothing and the field's PRESENCE
@@ -80,6 +81,9 @@ observationLost) {
     const declared = declaredExpectations(predicate);
     const contradictions = findContradictions(windowEvents, {
         prior,
+        currentDocumentId: session.currentDocumentId,
+        currentEditEpoch: session.currentEditEpoch,
+        appOrigin: session.url,
         expectedFailures: declared.netFailures,
         renderProved: pass && declared.rendersContent,
         ...(actCursor !== undefined && actCursor >= since ? { actionSince: actCursor } : {}),
@@ -100,17 +104,34 @@ observationLost) {
         // not override it. A fix that lived on one half of the verdict surface would leave the other
         // half broken, and this is the tool agents call most.
         declaredConsequence: predicate.kind !== PredicateKind.SETTLED,
+        ...(declaresBodyIndependentChannel(predicate) ? { independentOfBody: true } : {}),
         ...(inconclusive === undefined ? {} : { inconclusive }),
         ...(true === observationLost ? { observationLost: true } : {}),
         ...(absenceBlindSpot === undefined ? {} : { absenceBlindSpot }),
         honesty: buildHonestyBlock({
             grade: gradeOfPredicate(predicate),
             attribution: 'window',
+            // Did the buffer evict SCARCE evidence belonging to this window, AND does a green here rest on
+            // the window being complete. assert never consulted the buffer at all, on the reasoning that it
+            // "observes an already-open window" — but eviction happens on push regardless of who opened the
+            // window, so `{ console, absent: true }` returned `yes` over a window whose evidence was gone,
+            // which is absence of evidence read as evidence of absence.
+            //
+            // The second half of the condition is not a refinement, it is what keeps this usable. Scarce
+            // loss is recorded for AGE eviction too, so `lostSince(0)` is true on any session past the 60s
+            // cutoff, and assert takes a caller-chosen `since` that is often 0. Impeaching every verdict
+            // over a wide window would make `unknown` the answer to everything — the failure this repo has
+            // already paid for once, when `unclean_capture` became the dominant cause of `unknown` in the
+            // field. The act path needs no such guard: its cursor is the action's own.
+            truncated: session.lostSince(since) && restsOnCompleteWindow(predicate),
             coveragePartial: Coverage.PARTIAL === statement.coverage,
+            ...(statement.note === undefined ? {} : { coverageNote: statement.note }),
             ...(0 === impeachingNotes.length ? {} : { blindSpots: impeachingNotes }),
-            // Which loss, as an enum, beside the prose. `assert` observes an already-open window and never
-            // consults the ring buffer's health, so `buffer_loss` is not one of its answers.
+            // Which loss, as an enum, beside the prose.
             losses: [
+                ...(session.lostSince(since) && restsOnCompleteWindow(predicate)
+                    ? [CaptureLoss.BUFFER_LOSS]
+                    : []),
                 ...(gap === undefined ? [] : [CaptureLoss.TRANSPORT_GAP]),
                 ...(impeaching.note === undefined ? [] : [CaptureLoss.BLIND_SPOT]),
             ],
@@ -131,19 +152,36 @@ observationLost) {
     // state assertion against an app that registers no store.
     const gaps = gapsForAction({
         pass,
-        sourceKnown: session.lastAct.source() !== undefined,
+        ...(changeUndeclared === undefined ? {} : { changeUndeclared }),
+        source: session.lastAct.source(),
         stateAsked: declaresState(predicate),
         stateUnwatched: isStateUnwatched(spots),
+        // What the app DECLARED, so an under-instrumented one is told without having to be asked.
+        hasCapabilities: session.hasCapabilities,
         domMutated: false,
         signalsFired: 0,
         routeChanged: false,
         routeSignalFired: false,
     });
     noteSessionGaps(session, gaps);
+    // The one file:line this verdict is entitled to: its own evidence, or — for a failure with no DOM
+    // clause to point at — the control last driven. Returned so the RESPONSE can echo the same value
+    // the journal keeps; one verdict must never carry two different pointers.
+    const source = assertSource({
+        predicate,
+        evidence,
+        pass,
+        lastActSource: session.lastAct.source(),
+    });
     return {
         decision: decision,
         contradictions,
         coverage,
         gaps,
+        verdictEffect: {
+            claim: describeWaitTarget(predicate),
+            verified: decision.verified,
+            ...(source === undefined ? {} : { source }),
+        },
     };
 }

package/dist/tools/browser-tools.js

@@ -1,3 +1,4 @@
+import { carryReticleIdentity } from './lease-tools.js';
 import { z } from 'zod';
 import { navigateResult } from './navigate-result.js';
 import { awaitArrival } from './navigate-arrival.js';
@@ -64,12 +65,15 @@ export const BROWSER_TOOLS = [
                 // likely to need it. See reload-result.
                 return reloadResult(back);
             }
-            const url = asString(args['url']);
-            if (url === undefined || 0 === url.length)
+            const requested = asString(args['url']);
+            if (requested === undefined || 0 === requested.length)
                 return { ok: false, reason: 'url required' };
             // Record navigate as an action. Its window is usually empty (the page unloads and the SDK
             // reconnects), but the action record itself — "navigated to X" — is the causal fact worth keeping.
             const session = deps.sessions.resolve(asString(args['sessionId']));
+            // A leased tab is addressed by a URL param, so navigating away from it used to strand the
+            // lease — see carryReticleIdentity. A tab that claims no identity is untouched.
+            const url = carryReticleIdentity(session.url, requested);
             session.beginAction(ReticleTool.NAVIGATE, { url });
             // Same floor as the reload path above, for the same reason: going to a new URL replaces the
             // document just as thoroughly. `beginAction` attributes events to this action; it does not move
@@ -88,24 +92,4 @@ export const BROWSER_TOOLS = [
             }
         },
     },
-    {
-        name: ReticleTool.REFRESH,
-        description: 'Reload the connected browser tab. Pass { hard: true } to bypass the browser cache (equivalent to Cmd+Shift+R). The SDK reconnects automatically after the reload.',
-        inputSchema: {
-            hard: z
-                .boolean()
-                .optional()
-                .describe('Set true to bypass the browser cache. Default: false (normal reload).'),
-            ...sessionIdShape,
-        },
-        outputSchema: {
-            ok: z.boolean(),
-        },
-        handler: async (deps, args) => {
-            await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, {
-                hard: true === args['hard'],
-            });
-            return { ok: true };
-        },
-    },
 ];

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

@@ -0,0 +1,48 @@
+/**
+ * Finish a truncated snapshot, or say it could not be finished.
+ *
+ * The snapshot walk stops at its node cap and returns a document-order PREFIX with `truncated:true`.
+ * That flag has always been honest and has never been actionable: it says the read stopped, not
+ * where, so a caller could receive half a page and draw a NEGATIVE conclusion from it — "no error is
+ * shown", "the row is gone" — when the thing was simply past the cut. A read that under-reports is a
+ * verification result that is quietly wrong.
+ *
+ * The walk now names its own frontier (`unread`: refs of the subtrees it never entered), so the cut
+ * is recoverable: re-read each branch at its own path and the union is the whole tree. This is that
+ * loop, plus the half that matters — when the union CANNOT be assembled it says so, and the caller
+ * must not turn an empty result over it into an absence.
+ *
+ * The assembled tree is a UNION of subtrees, not a re-render: each appended chunk is indented from
+ * its own root. Callers scan it line by line (that is what every consumer of `tree` does), so the
+ * indentation restart costs nothing and re-walking the whole page from scratch would cost a lot.
+ */
+/**
+ * How many snapshot round-trips one completion may spend.
+ *
+ * Each is a real command to the page, so this is the cost ceiling of a completed read, not a safety
+ * net. Twelve covers a page whose cut frontier is a handful of branches a couple of levels deep —
+ * the shape a node cap actually produces — while keeping the worst case near a dozen round-trips
+ * rather than a walk of the DOM one subtree at a time.
+ */
+export declare const MAX_COMPLETION_READS = 12;
+/**
+ * How many times the completion may follow a frontier into a new one.
+ *
+ * A branch re-read can itself truncate and name further branches, so this recursion needs a floor
+ * under it independent of the read budget: a hostile or pathologically deep DOM can hand back a new
+ * frontier every round forever. Four rounds (the first read plus three levels of re-reads) is deeper
+ * than a node cap reaches on a real page, and terminates on one that is not real.
+ */
+export declare const MAX_COMPLETION_DEPTH = 4;
+/** Reads one snapshot — whole page when `scope` is undefined, that branch when it is not. */
+export type SnapshotReader = (scope: string | undefined) => Promise<unknown>;
+export interface CompletedRead {
+    /** The union of every subtree that was read. Never a lie about what it contains — only about how much. */
+    tree: string;
+    /** True only when every branch the page cut was read back. A negative conclusion needs this. */
+    complete: boolean;
+    reads: number;
+    /** Why completion stopped short, for the caller to quote. Present ONLY when `complete` is false. */
+    incompleteBecause?: string;
+}
+export declare function readCompleteTree(read: SnapshotReader): Promise<CompletedRead>;

package/dist/tools/complete-snapshot.js

@@ -0,0 +1,75 @@
+import { z } from 'zod';
+/**
+ * Finish a truncated snapshot, or say it could not be finished.
+ *
+ * The snapshot walk stops at its node cap and returns a document-order PREFIX with `truncated:true`.
+ * That flag has always been honest and has never been actionable: it says the read stopped, not
+ * where, so a caller could receive half a page and draw a NEGATIVE conclusion from it — "no error is
+ * shown", "the row is gone" — when the thing was simply past the cut. A read that under-reports is a
+ * verification result that is quietly wrong.
+ *
+ * The walk now names its own frontier (`unread`: refs of the subtrees it never entered), so the cut
+ * is recoverable: re-read each branch at its own path and the union is the whole tree. This is that
+ * loop, plus the half that matters — when the union CANNOT be assembled it says so, and the caller
+ * must not turn an empty result over it into an absence.
+ *
+ * The assembled tree is a UNION of subtrees, not a re-render: each appended chunk is indented from
+ * its own root. Callers scan it line by line (that is what every consumer of `tree` does), so the
+ * indentation restart costs nothing and re-walking the whole page from scratch would cost a lot.
+ */
+/**
+ * How many snapshot round-trips one completion may spend.
+ *
+ * Each is a real command to the page, so this is the cost ceiling of a completed read, not a safety
+ * net. Twelve covers a page whose cut frontier is a handful of branches a couple of levels deep —
+ * the shape a node cap actually produces — while keeping the worst case near a dozen round-trips
+ * rather than a walk of the DOM one subtree at a time.
+ */
+export const MAX_COMPLETION_READS = 12;
+/**
+ * How many times the completion may follow a frontier into a new one.
+ *
+ * A branch re-read can itself truncate and name further branches, so this recursion needs a floor
+ * under it independent of the read budget: a hostile or pathologically deep DOM can hand back a new
+ * frontier every round forever. Four rounds (the first read plus three levels of re-reads) is deeper
+ * than a node cap reaches on a real page, and terminates on one that is not real.
+ */
+export const MAX_COMPLETION_DEPTH = 4;
+const SnapshotShape = z.object({
+    tree: z.string().optional(),
+    truncated: z.boolean().optional(),
+    unread: z.array(z.string()).optional(),
+    unreadOverflow: z.literal(true).optional(),
+});
+export async function readCompleteTree(read) {
+    const parts = [];
+    let frontier = [undefined];
+    let reads = 0;
+    const stop = (because) => ({
+        tree: parts.join('\n'),
+        complete: false,
+        reads,
+        incompleteBecause: because,
+    });
+    for (let round = 0; round < MAX_COMPLETION_DEPTH; round += 1) {
+        const next = [];
+        for (const scope of frontier) {
+            if (reads >= MAX_COMPLETION_READS) {
+                return stop(`the page kept naming unread branches past ${String(MAX_COMPLETION_READS)} reads, so part of it was never seen`);
+            }
+            const parsed = SnapshotShape.safeParse(await read(scope));
+            reads += 1;
+            if (!parsed.success)
+                return stop('a snapshot came back in a shape this read cannot trust');
+            parts.push(parsed.data.tree ?? '');
+            if (true === parsed.data.unreadOverflow) {
+                return stop('the cut named more branches than one snapshot can carry, so the frontier itself is incomplete and no sequence of re-reads can finish this page');
+            }
+            next.push(...(parsed.data.unread ?? []));
+        }
+        if (0 === next.length)
+            return { tree: parts.join('\n'), complete: true, reads };
+        frontier = next;
+    }
+    return stop(`re-reads kept cutting after ${String(MAX_COMPLETION_DEPTH)} rounds, so part of the page was never seen`);
+}

package/dist/tools/coverage-tools.d.ts

@@ -5,5 +5,14 @@ interface Control {
 }
 /** Parse the interactive snapshot into {ref,label} controls, preserving document order. */
 export declare function parseControls(tree: string): Control[];
-export declare const COVERAGE_TOOLS: ToolDef[];
+/**
+ * Build the coverage tool over the dispatchable tool table.
+ *
+ * The table arrives as a thunk rather than an import: `tools.ts` assembles it FROM this module, so
+ * importing it back would close a cycle whose failure mode is a load-order-dependent crash rather
+ * than an error anyone sees while writing it. The thunk is called inside the handler, long after the
+ * table exists. It carries the merged names — the ones `reticle_run` will actually accept — because
+ * a tool that merged into a parent is not something an agent can call or a maintainer can cut.
+ */
+export declare function buildCoverageTools(toolNames: () => readonly string[]): ToolDef[];
 export {};