@reticlehq/server 2.14.0 → 3.2.0

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

@@ -1,42 +0,0 @@
-/**
- * Grade a single assertion predicate as a CONSEQUENCE or a mere PRESENCE check — the same distinction
- * classifyFlowAssertions applies to saved flows, now applied to ad-hoc reticle_assert calls.
- *
- * Why (grounded, same sources as flow-classify): a test that only checks an element is present is
- * weak — a locator healed to the wrong element, or a stale render, can satisfy it while the feature
- * is broken (Fowler, *Assertion-Free Testing*; Dodds, *Make Your Test Fail*). A signal/net assertion
- * verifies an observable consequence a wrong element cannot fake. When an agent asserts only
- * presence, we pass the verdict but nudge it toward a consequence — the success-oracle thesis.
- *
- * Pure: no IO, no clock.
- */
-import { HonestyGrade } from '../honesty/honesty.js';
-import type { Predicate } from '../events/predicate.js';
-export declare const PRESENCE_ONLY_ADVICE = "This predicate only checks element/text presence, not an observable consequence. A locator healed to the wrong element (or a stale render) can satisfy it while the feature is broken. Prefer a { signal } or { net } assertion (or allOf it with one) so green means the feature actually worked.";
-/**
- * True when the predicate asserts ONLY element/text presence with no signal/net consequence anywhere
- * — the weak pattern worth nudging. A predicate that mixes in a consequence, or that checks something
- * other than presence (route/console/settled), is not flagged.
- */
-/**
- * Advice for an assertion pinned to a status Reticle derived rather than one a server sent.
- */
-export declare const DERIVED_IPC_STATUS_ADVICE: string;
-/**
- * Does this predicate pin an IPC call to a status code?
- *
- * The 200/500 on an IPC record is a convenience so `reticle_network { status }` keeps working across
- * runtimes — it is not something any server sent. An assertion built on it is really an assertion
- * about Reticle's encoding, and would silently stop meaning what it meant if that encoding changed.
- * Recognised by the `ipc://` scheme, so a genuine HTTP status is never second-guessed.
- */
-export declare function assertsDerivedIpcStatus(predicate: Predicate): boolean;
-export declare function isPresenceOnlyAssertion(predicate: Predicate): boolean;
-/**
- * The tier a predicate actually proves, for the honesty block on a verdict.
- *
- * A signal or a network consequence is evidence the APP produced; a state read is one step removed;
- * presence of an element is the weakest, because a wrong or healed element can satisfy it. The
- * verdict carries this so "it passed" is always qualified by what it passed on.
- */
-export declare function gradeOfPredicate(predicate: Predicate): HonestyGrade;

package/dist/tools/assert-grade.js

@@ -1,108 +0,0 @@
-/**
- * Grade a single assertion predicate as a CONSEQUENCE or a mere PRESENCE check — the same distinction
- * classifyFlowAssertions applies to saved flows, now applied to ad-hoc reticle_assert calls.
- *
- * Why (grounded, same sources as flow-classify): a test that only checks an element is present is
- * weak — a locator healed to the wrong element, or a stale render, can satisfy it while the feature
- * is broken (Fowler, *Assertion-Free Testing*; Dodds, *Make Your Test Fail*). A signal/net assertion
- * verifies an observable consequence a wrong element cannot fake. When an agent asserts only
- * presence, we pass the verdict but nudge it toward a consequence — the success-oracle thesis.
- *
- * Pure: no IO, no clock.
- */
-import { isConsequenceKind, isPresenceKind, PredicateKind } from '@reticlehq/core';
-import { HonestyGrade } from '../honesty/honesty.js';
-export const PRESENCE_ONLY_ADVICE = 'This predicate only checks element/text presence, not an observable consequence. A locator healed to the wrong element (or a stale render) can satisfy it while the feature is broken. Prefer a { signal } or { net } assertion (or allOf it with one) so green means the feature actually worked.';
-function walk(predicate, negated = false) {
-    if (PredicateKind.ALL_OF === predicate.kind || PredicateKind.ANY_OF === predicate.kind) {
-        const subs = predicate.predicates.map((p) => walk(p, negated));
-        return {
-            consequence: subs.some((s) => s.consequence),
-            presence: subs.some((s) => s.presence),
-        };
-    }
-    // Under a NOT, checking content strengthens nothing, so the exemption below must not apply. The
-    // nudge warns that a healed or wrong locator can satisfy the predicate, and for an ABSENCE claim a
-    // wrong locator satisfies it trivially: "the error message is gone" is true of a selector that
-    // never matched anything in the first place. Negation makes a presence check weaker, not stronger.
-    if (PredicateKind.NOT === predicate.kind)
-        return walk(predicate.predicate, true);
-    // Leaf: classify against the single source of truth in core. Kinds that are neither consequence
-    // nor presence (route/console/settled/animation) correctly return false for both.
-    return {
-        consequence: isConsequenceKind(predicate.kind),
-        presence: isPresenceKind(predicate.kind) && (negated || !assertsElementContent(predicate)),
-    };
-}
-/**
- * An element predicate that checks the element's CONTENT, not merely that it is there.
- *
- * The presence nudge exists because "a locator healed to the wrong element, or a stale render, can
- * satisfy this while the feature is broken". That is exactly true of `{ element, role, name }` and
- * exactly false of `{ element, role, name, value: "274.58" }`: a wrong element now has to carry the
- * same value to pass, which is the thing the nudge is warning cannot be relied on.
- *
- * Kept as a nudge-level distinction rather than a new honesty grade. The grade still reads
- * `presence`, which UNDERSTATES what was proved, and understating is the safe direction for a field
- * whose whole job is to qualify a green. Telling an agent that a value check "only checks presence"
- * is the direction that costs something: it argues for replacing an assertion that is already sound.
- */
-function assertsElementContent(predicate) {
-    if (predicate.kind !== PredicateKind.ELEMENT)
-        return false;
-    return predicate.query?.value !== undefined || predicate.query?.text !== undefined;
-}
-/**
- * True when the predicate asserts ONLY element/text presence with no signal/net consequence anywhere
- * — the weak pattern worth nudging. A predicate that mixes in a consequence, or that checks something
- * other than presence (route/console/settled), is not flagged.
- */
-/**
- * Advice for an assertion pinned to a status Reticle derived rather than one a server sent.
- */
-export const DERIVED_IPC_STATUS_ADVICE = 'This asserts on a status code Reticle DERIVED — IPC has none. Prefer `{ ok: false }`, which ' +
-    'describes what the app did rather than how Reticle encoded it, and cannot drift if that encoding ' +
-    'changes. The `error` field carries the message the main process or Rust command actually returned.';
-/**
- * Does this predicate pin an IPC call to a status code?
- *
- * The 200/500 on an IPC record is a convenience so `reticle_network { status }` keeps working across
- * runtimes — it is not something any server sent. An assertion built on it is really an assertion
- * about Reticle's encoding, and would silently stop meaning what it meant if that encoding changed.
- * Recognised by the `ipc://` scheme, so a genuine HTTP status is never second-guessed.
- */
-export function assertsDerivedIpcStatus(predicate) {
-    if (PredicateKind.ALL_OF === predicate.kind || PredicateKind.ANY_OF === predicate.kind) {
-        return predicate.predicates.some(assertsDerivedIpcStatus);
-    }
-    if (PredicateKind.NOT === predicate.kind)
-        return assertsDerivedIpcStatus(predicate.predicate);
-    if (predicate.kind !== PredicateKind.NET)
-        return false;
-    return (predicate.status !== undefined &&
-        predicate.ok === undefined &&
-        (predicate.urlContains ?? '').startsWith('ipc://'));
-}
-export function isPresenceOnlyAssertion(predicate) {
-    const kinds = walk(predicate);
-    return kinds.presence && !kinds.consequence;
-}
-/**
- * The tier a predicate actually proves, for the honesty block on a verdict.
- *
- * A signal or a network consequence is evidence the APP produced; a state read is one step removed;
- * presence of an element is the weakest, because a wrong or healed element can satisfy it. The
- * verdict carries this so "it passed" is always qualified by what it passed on.
- */
-export function gradeOfPredicate(predicate) {
-    switch (predicate.kind) {
-        case PredicateKind.SIGNAL:
-            return HonestyGrade.SIGNAL;
-        case PredicateKind.NET:
-            return HonestyGrade.NET;
-        case PredicateKind.STATE:
-            return HonestyGrade.STATE;
-        default:
-            return HonestyGrade.PRESENCE;
-    }
-}

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

@@ -1,52 +0,0 @@
-import type { Predicate } from '../events/predicate-schema.js';
-import type { Session } from '../session/session.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;
-    /**
-     * Set when the verdict could not be EVALUATED rather than evaluated and found false.
-     *
-     * A file:line reads as a precise, well-attributed finding about that file. Attaching one to a
-     * reading that proved nothing sends the investigation into correct code: reported against a
-     * wedged Next.js dev server, where a route verdict named `components/.../header.tsx:53` and the
-     * reporter nearly filed "the header Sign Up link is broken" — the server was answering nothing at
-     * all, on every route.
-     *
-     * Gated here rather than in the route oracle, because every producer of an inconclusive verdict
-     * has the same problem: a throttled tab, a superseded window, an unreadable locator. One guard
-     * where all of them route through.
-     */
-    inconclusive?: string | undefined;
-}): string | undefined;
-/**
- * The file:line an assertion may report — see `assertSource`.
- *
- * Neither `reticle_assert` nor `reticle_wait_for` drives anything, so the last act's source is about
- * some earlier action and not about this verdict. The pointer comes from the assertion's own matched
- * evidence; the last driven control is borrowed only for a RED whose predicate has no DOM clause at
- * all, which is the failure that genuinely has no element to point at.
- */
-export declare function assertionSource(session: Session, predicate: Predicate, verdict: {
-    pass: boolean;
-    evidence?: unknown;
-    inconclusive?: string;
-}): {
-    source?: string;
-};

package/dist/tools/assert-source.js

@@ -1,74 +0,0 @@
-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;
-    // Nothing was proven and nobody could have proven it — so there is nothing to point at.
-    if (facts.inconclusive !== undefined)
-        return undefined;
-    return facts.lastActSource;
-}
-/**
- * The file:line an assertion may report — see `assertSource`.
- *
- * Neither `reticle_assert` nor `reticle_wait_for` drives anything, so the last act's source is about
- * some earlier action and not about this verdict. The pointer comes from the assertion's own matched
- * evidence; the last driven control is borrowed only for a RED whose predicate has no DOM clause at
- * all, which is the failure that genuinely has no element to point at.
- */
-export function assertionSource(session, predicate, verdict) {
-    const source = assertSource({
-        predicate,
-        evidence: verdict.evidence,
-        pass: verdict.pass,
-        lastActSource: session.lastAct.source(),
-        ...(verdict.inconclusive === undefined ? {} : { inconclusive: verdict.inconclusive }),
-    });
-    return source === undefined ? {} : { source };
-}

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

@@ -1,48 +0,0 @@
-import type { InstrumentationGap, JournalVerdictEffect } from '@reticlehq/core/artifacts';
-import type { Predicate } from '../events/predicate.js';
-import type { Session } from '../session/session.js';
-import { type Contradiction } from '../events/contradictions.js';
-/**
- * The honesty verdict for a plain `reticle_assert`.
- *
- * This is the single field an agent reads, and it was missing from the most-used verdict path.
- * `act_and_wait` has always returned it; `reticle_assert` returned a bare `pass: true`.
- *
- * Measured on a shipments console: a dispatch answered 202 Accepted, the row rendered "dispatched"
- * optimistically, an assert taken right after the click returned `pass: true` with no caveat, and the
- * server reverted the write to "held" 1.2s later. The 202 machinery that exists precisely to report
- * that as `verified: "unknown"` was never reached, because the tool an agent actually calls did not
- * 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, 
-/**
- * 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, 
-/**
- * Set when the tab went away mid-wait, so the assertion was never OBSERVED. `reticle_assert` and
- * `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, 
-/**
- * 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,197 +0,0 @@
-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, 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';
-import { decideVerified } from '../honesty/verified.js';
-import { describeWaitTarget, namedNetIsInFlight } from '../honesty/unsettled.js';
-import { inFlightRequestLabels, repeatedRequestLabels } from './settle-in-flight.js';
-import { gradeOfPredicate } from './assert-grade.js';
-import { assertSource } from './assert-source.js';
-/**
- * The honesty verdict for a plain `reticle_assert`.
- *
- * This is the single field an agent reads, and it was missing from the most-used verdict path.
- * `act_and_wait` has always returned it; `reticle_assert` returned a bare `pass: true`.
- *
- * Measured on a shipments console: a dispatch answered 202 Accepted, the row rendered "dispatched"
- * optimistically, an assert taken right after the click returned `pass: true` with no caveat, and the
- * server reverted the write to "held" 1.2s later. The 202 machinery that exists precisely to report
- * that as `verified: "unknown"` was never reached, because the tool an agent actually calls did not
- * 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, 
-/**
- * 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, 
-/**
- * Set when the tab went away mid-wait, so the assertion was never OBSERVED. `reticle_assert` and
- * `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, 
-/**
- * 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(), 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
-    // is the warning.
-    const coverage = Coverage.PARTIAL === statement.coverage
-        ? {
-            coverage: statement.note ?? Coverage.PARTIAL,
-            coverage_spots: statement.spots.map((sp) => ({ kind: sp.kind, count: sp.count })),
-        }
-        : {};
-    const windowEvents = await session.queryEvents({ since });
-    // Everything before the window, passed as LEARNING material only. A scale error disagrees with a
-    // value the API stated earlier in the session, which an action-scoped window can never contain —
-    // measured live, `observe` over a wide window reported `unit-mismatch` while `assert` on the same
-    // session reported none. Attribution is unchanged: findings still come only from windowEvents.
-    const prior = since > 0 ? (await session.queryEvents({ since: 0 })).filter((e) => e.t < since) : [];
-    // The last act, when it falls inside the window being judged. Without it `duplicate-request` counted
-    // `method + url` across whatever window the caller asked for, so two legitimate separate saves to one
-    // endpoint were reported as a double submit — the instrument accusing the app of something nobody
-    // could show it did. An assert taken over a window that predates the act attributes nothing, and the
-    // rule then stays quiet.
-    const actCursor = session.lastAct.cursor();
-    // The same declaration the act path reads. `reticle_assert` is the other half of the verdict
-    // surface, and an error path declared here deserves the same answer it gets there — a fix that
-    // lived only on the act path would leave the sibling caller broken.
-    const declared = declaredExpectations(predicate);
-    const contradictions = findContradictions(windowEvents, {
-        prior,
-        currentDocumentId: session.currentDocumentId,
-        currentEditEpoch: session.currentEditEpoch,
-        appOrigin: session.url,
-        expectedFailures: declared.netFailures,
-        namedNetUrls: declared.netUrls,
-        renderProved: pass && declared.rendersContent,
-        ...(actCursor !== undefined && actCursor >= since ? { actionSince: actCursor } : {}),
-    });
-    // Only a spot that IMPEACHES the capture downgrades a general verdict. Structural boundaries are
-    // reported as coverage; the narrower absence exception is computed separately above.
-    const impeaching = buildCoverageStatement(spots.filter((sp) => impeachesCapture(sp.kind)));
-    // A gap in the WINDOW, as opposed to a standing limit of the page. Both mean the same thing to the
-    // rule — part of what happened was not seen — so both belong in `blindSpots`, which is the only
-    // input `decideVerified` reads for that.
-    const gap = transportGapNote(windowEvents);
-    const impeachingNotes = [impeaching.note, gap].filter((n) => n !== undefined);
-    const outcomePending = hasAcceptedWrite(windowEvents);
-    const outcomeUnread = unreadWriteLabels(windowEvents);
-    const stillInFlight = inFlightRequestLabels(windowEvents);
-    const effectiveInconclusive = inconclusive ?? (!pass ? session.preconditionFailure?.() : undefined);
-    const decision = decideVerified({
-        pass,
-        // So the unread-body remedy can check it applies to THIS page. Threaded rather than
-        // looked up inside decideVerified, which is pure and has no session.
-        ...(session.sdkVersion === undefined ? {} : { sdkVersion: session.sdkVersion }),
-        // Same rule as the act path: the caller named a consequence, so a settlement-only finding must
-        // 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 } : {}),
-        ...(effectiveInconclusive === undefined ? {} : { inconclusive: effectiveInconclusive }),
-        ...(true === observationLost ? { observationLost: true, lastUrl: session.url } : {}),
-        ...(absenceBlindSpot === undefined ? {} : { absenceBlindSpot }),
-        ...(namedNetIsInFlight(predicate, stillInFlight) ? { namedRequestInFlight: true } : {}),
-        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.
-            losses: [
-                ...(session.lostSince(since) && restsOnCompleteWindow(predicate)
-                    ? [CaptureLoss.BUFFER_LOSS]
-                    : []),
-                ...(gap === undefined ? [] : [CaptureLoss.TRANSPORT_GAP]),
-                ...(impeaching.note === undefined ? [] : [CaptureLoss.BLIND_SPOT]),
-            ],
-        }),
-        contradictions,
-        ...(outcomePending ? { outcomePending } : {}),
-        ...(outcomeUnread.length > 0 ? { outcomeUnread } : {}),
-        // Same detail the act path supplies: this route reaches UNSETTLED through an absence-derived
-        // contradiction, and "the window closed before the app finished" is no more actionable here.
-        unsettled: {
-            waitedFor: describeWaitTarget(predicate),
-            stillInFlight,
-            repeated: repeatedRequestLabels(windowEvents),
-        },
-    });
-    // The same rule the act path uses, fed by what THIS path knows. An assertion drives nothing, so
-    // only two of the four gates can fire here: a red with no remembered source to point at, and a
-    // state assertion against an app that registers no store.
-    const gaps = gapsForAction({
-        pass,
-        ...(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,
-        // Whether the build TURNED the source stamp off, so a red with no file:line prescribes the
-        // right fix. `false` from the page is the only value that means anything; absent is unknown.
-        ...(false === session.sourceMapping ? { sourceMappingDisabled: true } : {}),
-        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.d.ts

@@ -1,2 +0,0 @@
-import type { ToolDef } from './tools.js';
-export declare const BROWSER_TOOLS: ToolDef[];

package/dist/tools/browser-tools.js

@@ -1,115 +0,0 @@
-import { carryReticleIdentity } from './lease-tools.js';
-import { z } from 'zod';
-import { navigateResult } from './navigate-result.js';
-import { awaitArrival, idsAtTarget, ARRIVAL_TIMEOUT_MS } from './navigate-arrival.js';
-import { reloadResult } from './reload-result.js';
-import { waitForReconnect, RELOAD_RECONNECT_TIMEOUT_MS } from '../session/session-reconnect.js';
-import { ReticleCommand } from '@reticlehq/core';
-import { ReticleTool } from './tool-names.js';
-import { asNumber, asString } from './tools-helpers.js';
-import { sessionIdShape, commandOrThrow } from './tool-kit.js';
-import { timeoutMsSchema } from './numeric-bounds.js';
-export const BROWSER_TOOLS = [
-    {
-        name: ReticleTool.NAVIGATE,
-        example: { url: '/settings' },
-        description: 'Navigate the connected browser tab to a URL, or reload it in place with { reload: true } (add { hard: true } to bypass the cache). `ok` means the navigation was DISPATCHED — the SDK is torn down by the navigation, so the page itself cannot report on it. The daemon then waits up to `timeout_ms` (default 5000) for the SDK to reconnect: `confirmed:true` with a new `sessionId` means the page arrived and you can act immediately. `confirmed:false` means it did not arrive within that window (reported as `waitedMs`) — the page may be slow, uninstrumented, or not there. A slow SPA can take 30-60s to reattach: raise `timeout_ms` rather than polling reticle_sessions.',
-        inputSchema: {
-            url: z.string().optional().describe('The URL to navigate to. Omit when using reload.'),
-            reload: z
-                .boolean()
-                .optional()
-                .describe('Reload the current page instead of navigating (replaces the former standalone refresh tool).'),
-            hard: z
-                .boolean()
-                .optional()
-                .describe('With reload:true, bypass the browser cache (Cmd+Shift+R). Default: false.'),
-            timeout_ms: timeoutMsSchema
-                .optional()
-                .describe('How long to wait for the page to come back (the SDK reconnecting at the new URL, or under the same id on a reload) before answering confirmed:false. Default 5000. 0 looks once without waiting. An SPA reattaching under HMR has been measured at 30-60s — say so here instead of polling reticle_sessions.'),
-            ...sessionIdShape,
-        },
-        outputSchema: {
-            ok: z.boolean(),
-            url: z.string().optional(),
-            reason: z.string().optional(),
-            // Present on a dispatched navigation: nothing here can see the new document, so arrival is
-            // reported as unconfirmed rather than implied by `ok`. See navigate-result.ts.
-            confirmed: z.boolean().optional(),
-            /** The session the SDK reconnected as, when arrival was confirmed — it is a NEW id. */
-            sessionId: z.string().optional(),
-            /**
-             * On confirmed:false — the budget (ms) that expired without the page coming back. Says which
-             * of "Reticle stopped waiting" and "the page never came back" you are looking at.
-             */
-            waitedMs: z.number().optional(),
-            note: z.string().optional(),
-        },
-        handler: async (deps, args) => {
-            // reload:true is the absorbed reticle_refresh — same command, one fewer advertised tool.
-            if (true === args['reload']) {
-                // The reload branch has its own default, sized for a cold dev-server rebuild; the caller's
-                // budget overrides it for the same reason it overrides the arrival wait below.
-                const timeoutMs = asNumber(args['timeout_ms']) ?? RELOAD_RECONNECT_TIMEOUT_MS;
-                const before = deps.sessions.resolve(asString(args['sessionId']));
-                // The verdict floor moves HERE, before the page goes away. A reload destroys the document,
-                // so every request that failed under the old one belongs to a page that no longer exists —
-                // and a later assert defaulting its window to "the last thing that happened" must not reach
-                // back past this point. Reported from the field as an assertion whose clauses all passed
-                // coming back `contradicted` by hundreds of 500s against resources that were already gone.
-                before.lastAct.markNavigated(before.elapsed());
-                await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.REFRESH, {
-                    hard: true === args['hard'],
-                });
-                // WAIT for the page to come back, rather than telling the agent to. The id survives the
-                // reload, but the seconds between dispatch and the new HELLO are seconds in which every call
-                // lands in the old, disconnected session — measured as reticle_run failing 5 of 5 on a page
-                // that was healthy immediately afterwards. Returns on the first poll in the common case.
-                const back = await waitForReconnect({
-                    current: () => deps.sessions.get(before.id),
-                    previous: before,
-                    timeoutMs,
-                    now: deps.now,
-                    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
-                });
-                // Not a bare `{ ok: true }`. The URL branch below already discloses that `ok` means
-                // DISPATCHED — the reload branch had identical semantics and said nothing, on the path most
-                // likely to need it. See reload-result.
-                return reloadResult(back, timeoutMs);
-            }
-            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);
-            // Sampled BEFORE dispatch, because that is the only moment it can be known. A session already
-            // sitting on the target is not evidence that THIS navigation arrived — and the arrival scan,
-            // which reads whatever is at the target afterwards, cannot tell the two apart on its own.
-            const priorIds = idsAtTarget(deps.sessions, url);
-            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
-            // the window a later assert judges over, and those are two different jobs.
-            session.lastAct.markNavigated(session.elapsed());
-            try {
-                const result = (await commandOrThrow(deps, asString(args['sessionId']), ReticleCommand.NAVIGATE, { url }));
-                // `ok` is the browser accepting the instruction, not the page arriving — see navigate-result.
-                // The daemon is the only party that CAN see arrival (the SDK reconnects to it), so it looks,
-                // for as long as the caller said to, instead of telling the agent to go poll
-                // reticle_sessions itself. A refusal skips the wait: there is nothing to wait FOR.
-                const timeoutMs = asNumber(args['timeout_ms']) ?? ARRIVAL_TIMEOUT_MS;
-                const arrival = true === result.ok
-                    ? await awaitArrival(deps.sessions, url, { navigatedId: session.id, priorIds }, timeoutMs)
-                    : null;
-                return navigateResult(result, arrival, timeoutMs);
-            }
-            finally {
-                session.finishAction();
-            }
-        },
-    },
-];

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

@@ -1,2 +0,0 @@
-import type { ToolDef } from './tools.js';
-export declare const CONTRACT_TOOLS: ToolDef[];