@reticlehq/server 2.14.0 → 3.2.0

package/dist/surface/tools/args/numeric-bounds.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Shared bounds for numeric TOOL INPUTS.
+ *
+ * An unknown parameter is refused with "They were NOT applied — a result computed without them
+ * would look like an answer." A known parameter carrying a value the code cannot honour is the
+ * same failure: `reticle_state { depth: -5 }` used to return the full unscoped store, because
+ * `capDepth` treats a negative budget as "no cap". The agent cannot tell a bound it asked for
+ * from a bound that was dropped.
+ *
+ * A single rule for every number would be wrong (`since: 0` is a real cursor; `timeout_ms: 0`
+ * on assert means evaluate now; `threshold` is a 0–1 ratio). Each helper below is one policy,
+ * with the sentence for why that bound and not another.
+ */
+import { z } from 'zod';
+/**
+ * Hard cap on "return the first N". The ring buffer holds this many events; asking for a billion
+ * cannot be honoured from memory we do not keep, and would look like a complete listing.
+ */
+export declare const MAX_RESULT_COUNT: 2000;
+/**
+ * Hard cap on a numeric millisecond argument that does NOT block the caller's request.
+ * `timeout_ms: 0` stays legal — it means evaluate once, do not wait.
+ */
+export declare const MAX_TIMEOUT_MS = 120000;
+export declare const MAX_BLOCKING_WAIT_MS: number;
+/**
+ * `capDepth` at this many levels is already past any store an agent can read.
+ *
+ * Not lower: `numeric-args-are-bounded.test.ts` pins depth 50 as legal, because a large depth is a
+ * SCOPE choice and not an error. A ceiling that refuses it would turn a working call into a refusal
+ * in the name of bounding one that never worked.
+ */
+export declare const MAX_STATE_DEPTH = 256;
+/** Scroll-to-find steps. Default is 20; hundreds is searching, thousands is a hang. */
+export declare const MAX_SCROLLS = 200;
+/** Viewport CSS px — matches the clamp the handler already applied, now as a refusal. */
+export declare const MIN_VIEWPORT_PX = 64;
+export declare const MAX_VIEWPORT_PX = 10000;
+/**
+ * A page cursor. 0 is the start of the buffer, so `.positive()` would refuse a legitimate first
+ * page. Negative is not a cursor.
+ */
+export declare const cursorSchema: z.ZodNumber;
+/**
+ * A wait budget in ms. 0 means evaluate now (documented on assert). Negative cannot be honoured.
+ */
+export declare const timeoutMsSchema: z.ZodNumber;
+/**
+ * A count / cap. 0 means "return none", which is a real request. Negative is not.
+ * Capped at the ring-buffer size so a `limit: 1e9` cannot pretend the buffer is larger than it is.
+ */
+export declare const countSchema: z.ZodNumber;
+/**
+ * Store projection depth. Negative used to mean "no cap" inside `capDepth`, which is how
+ * `depth: -5` silently returned the full store — that is the defect this bound closes.
+ *
+ * 0 stays REFUSED, which is the policy already on the surface (a zero-level read is not a read).
+ * `capDepth(v, 0)` does return a size marker, so accepting it would be defensible — but that is a
+ * change to what the tool answers, not a bound on what it cannot honour, and it belongs in its own
+ * change with its own reason.
+ */
+export declare const depthSchema: z.ZodNumber;
+/**
+ * Pixel-diff ratios (`threshold`, `maxRatio`). pixelmatch's threshold and our pass ratio are both
+ * 0..1; `.int()` would refuse 0.01.
+ */
+export declare const ratioSchema: z.ZodNumber;
+/** HTTP status on a mock or a filter. */
+export declare const httpStatusSchema: z.ZodNumber;
+/**
+ * A perturbation seed. Bounded to 32 bits because that is what the generator consumes.
+ *
+ * The bound is not paranoia about size — it is what makes a seed a PROMISE. A value outside this
+ * range is silently coerced by the generator, so two different seeds would produce one run and a
+ * repro recorded against either would be a lie about which.
+ */
+export declare const seedSchema: z.ZodNumber;
+/** Viewport CSS px. `.int()` alone still accepted 5 and 999999, then the handler silently clamped. */
+export declare const viewportPxSchema: z.ZodNumber;
+/** Crawl / scroll step budgets. 0 is a documented no-op on crawl ("raise it to crawl at all"). */
+export declare const stepCountSchema: z.ZodNumber;
+export declare const scrollCountSchema: z.ZodNumber;
+export declare const advanceMsSchema: z.ZodNumber;
+export declare const idleMsSchema: z.ZodNumber;
+/** Delay before a mocked response. 0 is immediate. */
+export declare const delayMsSchema: z.ZodNumber;
+/**
+ * Observe lookback. Must be > 0 — a non-positive window used to mint a FUTURE cursor, so the
+ * tool returned zero events and looked like a quiet page. Capped so `window_ms: 1e12` cannot hang.
+ */
+export declare const windowMsSchema: z.ZodNumber;
+/**
+ * Parallelism for suite replay. 0 (and omit) means sequential. Capped at the session/pool ceiling;
+ * asking for a thousand workers cannot be honoured.
+ */
+export declare const workerCountSchema: z.ZodNumber;
+export declare const listIndexSchema: z.ZodNumber;

package/dist/surface/tools/args/numeric-bounds.js

@@ -0,0 +1,133 @@
+/**
+ * Shared bounds for numeric TOOL INPUTS.
+ *
+ * An unknown parameter is refused with "They were NOT applied — a result computed without them
+ * would look like an answer." A known parameter carrying a value the code cannot honour is the
+ * same failure: `reticle_state { depth: -5 }` used to return the full unscoped store, because
+ * `capDepth` treats a negative budget as "no cap". The agent cannot tell a bound it asked for
+ * from a bound that was dropped.
+ *
+ * A single rule for every number would be wrong (`since: 0` is a real cursor; `timeout_ms: 0`
+ * on assert means evaluate now; `threshold` is a 0–1 ratio). Each helper below is one policy,
+ * with the sentence for why that bound and not another.
+ */
+import { z } from 'zod';
+import { RING_BUFFER_DEFAULTS, TRANSPORT_LIMITS } from '@reticlehq/core';
+/**
+ * Hard cap on "return the first N". The ring buffer holds this many events; asking for a billion
+ * cannot be honoured from memory we do not keep, and would look like a complete listing.
+ */
+export const MAX_RESULT_COUNT = RING_BUFFER_DEFAULTS.MAX_EVENTS;
+/**
+ * Hard cap on a numeric millisecond argument that does NOT block the caller's request.
+ * `timeout_ms: 0` stays legal — it means evaluate once, do not wait.
+ */
+export const MAX_TIMEOUT_MS = 120_000;
+/**
+ * Hard cap on a wait the CALLER BLOCKS ON, which is a different ceiling from the one above.
+ *
+ * A blocking wait is bounded by the client's patience, not by ours. The MCP SDK's default request
+ * timeout is 60s and clients configure it lower; we advertised 120s. A caller who believed the
+ * advertised bound and asked for 90s got a TRANSPORT error at 60s — not a Reticle verdict, not a
+ * near-miss diagnosis, nothing to act on. The wait was honoured right up to the point where the
+ * only thing that could report it had gone.
+ *
+ * So the ceiling is set below the SDK default rather than at it: the margin is what lets Reticle's
+ * own "timed out, here is the near miss" answer beat the client's abort. A refused argument is a
+ * bad ceiling costing one round trip; an accepted one that cannot be delivered costs the drive.
+ *
+ * This does not make long waits possible, and is not meant to — it makes the ADVERTISED bound one
+ * that can actually be honoured. A caller that genuinely needs to outlast this polls: several short
+ * waits, each of which returns a verdict. See #601 for the bounded-wait cursor that would let one
+ * call do it properly.
+ */
+const MCP_SDK_DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
+export const MAX_BLOCKING_WAIT_MS = MCP_SDK_DEFAULT_REQUEST_TIMEOUT_MS - 5_000;
+/**
+ * `capDepth` at this many levels is already past any store an agent can read.
+ *
+ * Not lower: `numeric-args-are-bounded.test.ts` pins depth 50 as legal, because a large depth is a
+ * SCOPE choice and not an error. A ceiling that refuses it would turn a working call into a refusal
+ * in the name of bounding one that never worked.
+ */
+export const MAX_STATE_DEPTH = 256;
+/** A crawl that clicks forever is not a bound. */
+const MAX_CRAWL_STEPS = 500;
+/** Scroll-to-find steps. Default is 20; hundreds is searching, thousands is a hang. */
+export const MAX_SCROLLS = 200;
+/** Fake-clock jump. One day of timers is a test; a billion ms is not. */
+const MAX_ADVANCE_MS = 86_400_000;
+/** Presenter idle window. One hour is a slow app; larger values never fire. */
+const MAX_IDLE_MS = 3_600_000;
+/** Viewport CSS px — matches the clamp the handler already applied, now as a refusal. */
+export const MIN_VIEWPORT_PX = 64;
+export const MAX_VIEWPORT_PX = 10_000;
+/**
+ * A page cursor. 0 is the start of the buffer, so `.positive()` would refuse a legitimate first
+ * page. Negative is not a cursor.
+ */
+export const cursorSchema = z.number().finite().int().nonnegative();
+/**
+ * A wait budget in ms. 0 means evaluate now (documented on assert). Negative cannot be honoured.
+ */
+export const timeoutMsSchema = z.number().finite().int().nonnegative().max(MAX_BLOCKING_WAIT_MS);
+/**
+ * A count / cap. 0 means "return none", which is a real request. Negative is not.
+ * Capped at the ring-buffer size so a `limit: 1e9` cannot pretend the buffer is larger than it is.
+ */
+export const countSchema = z.number().finite().int().nonnegative().max(MAX_RESULT_COUNT);
+/**
+ * Store projection depth. Negative used to mean "no cap" inside `capDepth`, which is how
+ * `depth: -5` silently returned the full store — that is the defect this bound closes.
+ *
+ * 0 stays REFUSED, which is the policy already on the surface (a zero-level read is not a read).
+ * `capDepth(v, 0)` does return a size marker, so accepting it would be defensible — but that is a
+ * change to what the tool answers, not a bound on what it cannot honour, and it belongs in its own
+ * change with its own reason.
+ */
+export const depthSchema = z.number().finite().int().positive().max(MAX_STATE_DEPTH);
+/**
+ * Pixel-diff ratios (`threshold`, `maxRatio`). pixelmatch's threshold and our pass ratio are both
+ * 0..1; `.int()` would refuse 0.01.
+ */
+export const ratioSchema = z.number().finite().min(0).max(1);
+/** HTTP status on a mock or a filter. */
+export const httpStatusSchema = z.number().finite().int().min(100).max(599);
+/**
+ * A perturbation seed. Bounded to 32 bits because that is what the generator consumes.
+ *
+ * The bound is not paranoia about size — it is what makes a seed a PROMISE. A value outside this
+ * range is silently coerced by the generator, so two different seeds would produce one run and a
+ * repro recorded against either would be a lie about which.
+ */
+export const seedSchema = z.number().finite().int().min(0).max(0xffff_ffff);
+/** Viewport CSS px. `.int()` alone still accepted 5 and 999999, then the handler silently clamped. */
+export const viewportPxSchema = z.number().finite().int().min(MIN_VIEWPORT_PX).max(MAX_VIEWPORT_PX);
+/** Crawl / scroll step budgets. 0 is a documented no-op on crawl ("raise it to crawl at all"). */
+export const stepCountSchema = z.number().finite().int().nonnegative().max(MAX_CRAWL_STEPS);
+export const scrollCountSchema = z.number().finite().int().nonnegative().max(MAX_SCROLLS);
+export const advanceMsSchema = z.number().finite().int().nonnegative().max(MAX_ADVANCE_MS);
+export const idleMsSchema = z.number().finite().int().nonnegative().max(MAX_IDLE_MS);
+/** Delay before a mocked response. 0 is immediate. */
+export const delayMsSchema = z.number().finite().int().nonnegative().max(MAX_TIMEOUT_MS);
+/**
+ * Observe lookback. Must be > 0 — a non-positive window used to mint a FUTURE cursor, so the
+ * tool returned zero events and looked like a quiet page. Capped so `window_ms: 1e12` cannot hang.
+ */
+export const windowMsSchema = z.number().finite().int().positive().max(MAX_TIMEOUT_MS);
+/**
+ * Parallelism for suite replay. 0 (and omit) means sequential. Capped at the session/pool ceiling;
+ * asking for a thousand workers cannot be honoured.
+ */
+export const workerCountSchema = z
+    .number()
+    .finite()
+    .int()
+    .nonnegative()
+    .max(TRANSPORT_LIMITS.MAX_SESSIONS);
+/**
+ * A row index / list length in a virtualized table. Those lists are large on purpose; the ring
+ * buffer's 2000 is the wrong ceiling. A billion-row claim is not a list, it is a hang.
+ */
+const MAX_LIST_INDEX = 1_000_000;
+export const listIndexSchema = z.number().finite().int().nonnegative().max(MAX_LIST_INDEX);

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

@@ -0,0 +1,42 @@
+/**
+ * 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 '@reticlehq/engine/evidence/honesty.js';
+import type { Predicate } from '@reticlehq/engine/question/predicate/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/surface/tools/assert/assert-grade.js

@@ -0,0 +1,125 @@
+/**
+ * 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, strongerGrade, weakerGrade } from '@reticlehq/engine/evidence/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;
+        // An AND greens only when EVERY branch held, so the strongest branch is honestly claimable.
+        case PredicateKind.ALL_OF:
+            return combine(predicate.predicates, strongerGrade);
+        // An OR greens on ONE branch and nothing here records which. Claiming the strongest would let a
+        // verdict that proved only presence report `signal`, and a `minGrade: net` gate would trust it.
+        case PredicateKind.ANY_OF:
+            return combine(predicate.predicates, weakerGrade);
+        // Everything else, `not` included: an absence claim is satisfied trivially by a locator that
+        // never matched anything, which is the argument `walk` already makes about negation.
+        default:
+            return HonestyGrade.PRESENCE;
+    }
+}
+/** Fold a combinator's branches on the ladder. No branches proves nothing, so it stays at the floor. */
+function combine(branches, pick) {
+    const grades = branches.map(gradeOfPredicate);
+    const first = grades[0];
+    if (first === undefined)
+        return HonestyGrade.PRESENCE;
+    return grades.reduce(pick, first);
+}

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

@@ -0,0 +1,52 @@
+import type { Predicate } from '@reticlehq/engine/question/predicate/predicate-schema.js';
+import type { Session } from '../../../portal/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/surface/tools/assert/assert-source.js

@@ -0,0 +1,74 @@
+import { declaresDom } from '@reticlehq/engine/question/predicate/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/surface/tools/assert/assert-verdict.d.ts

@@ -0,0 +1,48 @@
+import type { InstrumentationGap, JournalVerdictEffect } from '@reticlehq/core/artifacts';
+import type { Predicate } from '@reticlehq/engine/question/predicate/predicate.js';
+import type { Session } from '../../../portal/session/session.js';
+import { type Contradiction } from '@reticlehq/engine/disagreement/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 engine/src/evidence/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;
+}>;