@reticlehq/server 3.2.0 → 3.3.0

package/dist/judgement/capsule/capsule-store.d.ts

@@ -29,6 +29,18 @@ declare const CapsuleSchema: z.ZodObject<{
     observed: z.ZodString;
     /** Minimal steps to reproduce (prefix-trimmed). */
     steps: z.ZodArray<z.ZodType<FlowStep, z.ZodTypeDef, FlowStep>, "many">;
+    /**
+     * How many times this exact failure has been captured, and when it last was.
+     *
+     * A repeat is not a new capsule -- it is the same one, again. "This failed 37 times, most
+     * recently at T" is strictly MORE than 37 files each holding one timestamp, so folding the
+     * duplicates in adds information rather than discarding it.
+     *
+     * Optional, because a capsule written before these existed has neither and must not be read as
+     * though it were seen once when nobody counted.
+     */
+    seen: z.ZodOptional<z.ZodNumber>;
+    lastSeenAt: z.ZodOptional<z.ZodNumber>;
 }, "strip", z.ZodTypeAny, {
     expected: string;
     origin: string;
@@ -38,6 +50,8 @@ declare const CapsuleSchema: z.ZodObject<{
     createdAt: number;
     observed: string;
     flow?: string | undefined;
+    seen?: number | undefined;
+    lastSeenAt?: number | undefined;
 }, {
     expected: string;
     origin: string;
@@ -47,6 +61,8 @@ declare const CapsuleSchema: z.ZodObject<{
     createdAt: number;
     observed: string;
     flow?: string | undefined;
+    seen?: number | undefined;
+    lastSeenAt?: number | undefined;
 }>;
 export type Capsule = z.infer<typeof CapsuleSchema>;
 /** Capsule ids are filenames — refuse anything that could escape the capsules directory. */
@@ -63,8 +79,21 @@ export declare class CapsuleStore {
     /** Every readable capsule, newest-first — what `reticle capsules` prints. */
     all(): Promise<Capsule[]>;
 }
-/** Deterministic, path-safe capsule id: time-ordered so `list` sorts newest-first for free. */
-export declare function capsuleId(now: number, label: string): string;
+/**
+ * What makes two captures the SAME failure.
+ *
+ * Everything that describes the failure, and nothing that describes the capture: `createdAt` is
+ * excluded because it is precisely what turned every retry of a broken step into a new file, and
+ * `id` because it is derived from this. `flow` is included -- the same assertion failing in two
+ * different journeys is two findings, not one.
+ */
+export declare function capsuleFingerprint(capsule: Omit<Capsule, 'id' | 'createdAt' | 'seen' | 'lastSeenAt'>): string;
+/**
+ * Deterministic, path-safe capsule id: time-ordered so `list` sorts newest-first for free, with the
+ * fingerprint on the END so a duplicate can be found by listing the directory rather than reading
+ * every file in it.
+ */
+export declare function capsuleId(now: number, label: string, fingerprint: string): string;
 /** The minimal reproduction: the steps up to and including the one that failed (prefix trim). */
 export declare function minimalSteps(steps: readonly FlowStep[], failedIndex: number): FlowStep[];
 export {};

package/dist/judgement/capsule/capsule-store.js

@@ -1,4 +1,6 @@
 import { join } from 'node:path';
+import { fnv1a } from '@reticlehq/core';
+import { writeFileAtomic } from '../../memory/project/fs/write-atomic.js';
 import { z } from 'zod';
 import { FlowStepSchema } from '@reticlehq/core';
 import { reticleDirPaths } from '../../memory/project/dir/reticle-dir.js';
@@ -30,6 +32,18 @@ const CapsuleSchema = z.object({
     observed: z.string(),
     /** Minimal steps to reproduce (prefix-trimmed). */
     steps: z.array(FlowStepSchema),
+    /**
+     * How many times this exact failure has been captured, and when it last was.
+     *
+     * A repeat is not a new capsule -- it is the same one, again. "This failed 37 times, most
+     * recently at T" is strictly MORE than 37 files each holding one timestamp, so folding the
+     * duplicates in adds information rather than discarding it.
+     *
+     * Optional, because a capsule written before these existed has neither and must not be read as
+     * though it were seen once when nobody counted.
+     */
+    seen: z.number().int().positive().optional(),
+    lastSeenAt: z.number().optional(),
 });
 /** Capsule ids are filenames — refuse anything that could escape the capsules directory. */
 export function isValidCapsuleId(id) {
@@ -51,9 +65,26 @@ export class CapsuleStore {
             return false;
         try {
             await this.#fs.mkdir(this.#dir);
-            const tmp = `${this.#pathFor(capsule.id)}.tmp`;
-            await this.#fs.writeFile(tmp, `${JSON.stringify(capsule, null, 2)}\n`);
-            await this.#fs.rename(tmp, this.#pathFor(capsule.id));
+            /*
+             * A capture of a failure already on disk folds into it rather than adding a file. Found by
+             * LISTING: the fingerprint is the id's suffix, so this costs one directory read instead of
+             * one read per capsule. An id written before fingerprints existed simply never matches, which
+             * is the correct outcome -- it is left exactly as it was.
+             *
+             * `createdAt` keeps the FIRST sighting. A repeat is the same failure happening again, not a
+             * new one, and the interesting pair is when it started and when it last happened.
+             */
+            const fingerprint = capsuleFingerprint(capsule);
+            const existingId = (await this.list()).find((id) => id.endsWith(`-${fingerprint}`));
+            const previous = existingId === undefined ? undefined : await this.read(existingId);
+            const folded = previous === undefined
+                ? { ...capsule, seen: 1, lastSeenAt: capsule.createdAt }
+                : {
+                    ...previous,
+                    seen: (previous.seen ?? 1) + 1,
+                    lastSeenAt: capsule.createdAt,
+                };
+            await writeFileAtomic(this.#fs, this.#pathFor(folded.id), `${JSON.stringify(folded, null, 2)}\n`);
             return true;
         }
         catch {
@@ -100,10 +131,31 @@ export class CapsuleStore {
         return out;
     }
 }
-/** Deterministic, path-safe capsule id: time-ordered so `list` sorts newest-first for free. */
-export function capsuleId(now, label) {
+/**
+ * What makes two captures the SAME failure.
+ *
+ * Everything that describes the failure, and nothing that describes the capture: `createdAt` is
+ * excluded because it is precisely what turned every retry of a broken step into a new file, and
+ * `id` because it is derived from this. `flow` is included -- the same assertion failing in two
+ * different journeys is two findings, not one.
+ */
+export function capsuleFingerprint(capsule) {
+    return fnv1a(JSON.stringify([
+        capsule.flow ?? '',
+        capsule.origin,
+        capsule.expected,
+        capsule.observed,
+        capsule.steps,
+    ]));
+}
+/**
+ * Deterministic, path-safe capsule id: time-ordered so `list` sorts newest-first for free, with the
+ * fingerprint on the END so a duplicate can be found by listing the directory rather than reading
+ * every file in it.
+ */
+export function capsuleId(now, label, fingerprint) {
     const safe = label.replace(/[^a-zA-Z0-9._-]/g, '-').slice(0, 40);
-    return `${String(now)}-${safe.length > 0 ? safe : 'capsule'}`;
+    return `${String(now)}-${safe.length > 0 ? safe : 'capsule'}-${fingerprint}`;
 }
 /** The minimal reproduction: the steps up to and including the one that failed (prefix trim). */
 export function minimalSteps(steps, failedIndex) {

package/dist/judgement/capsule/capsule.js

@@ -1,4 +1,5 @@
 import { ConsequenceKind, EventType } from '@reticlehq/core';
+import { isDocumentInitiated } from '@reticlehq/engine/question/predicate/predicate-eval.js';
 import { causalSummary } from './causal-summary.js';
 import { firstDivergence } from './divergence.js';
 /**
@@ -34,6 +35,10 @@ export function blastRadius(expected, observed) {
                 continue;
             if (declaredUrls.some((fragment) => url.includes(fragment)))
                 continue;
+            // A subresource the document fetched is the page loading, not a request the action sent: one
+            // navigation is a couple of hundred of them. IPC and beacons carry an initiator too, and stay.
+            if (isDocumentInitiated(event))
+                continue;
             const method = event.data['method'];
             add(`net ${'string' === typeof method ? method : 'request'} ${url}`);
             continue;

package/dist/judgement/capsule/causal-summary.d.ts

@@ -63,6 +63,18 @@ export interface CausalSummary {
     elided?: Partial<Record<CappedList, number>>;
     route?: string;
     signals: string[];
+    /**
+     * Form fields whose value moved in this window, by NAME.
+     *
+     * Names only, never values: a form is where somebody types their password, and the observer that
+     * reports this already refuses to carry one. The names are what an assertion is written against,
+     * and a field moving when nothing should have touched it (or not moving when something should)
+     * is the silently-cleared-field class — which until this channel existed left no trace at all,
+     * because React sets the input PROPERTY and MutationObserver watches attributes.
+     *
+     * Present only when a field moved, so a page with no form pays nothing.
+     */
+    fieldsChanged?: string[];
     layoutShift?: number;
     longTasks: number;
     /**
@@ -114,6 +126,6 @@ interface SummaryContext {
  */
 export declare const MAX_SUMMARY_ENTRIES = 20;
 /** The lists that are capped, named so `elided` can say which one lost entries. */
-type CappedList = 'statePathsChanged' | 'storageKeysChanged' | 'stateDiffs' | 'storageDiffs' | 'signals';
+type CappedList = 'statePathsChanged' | 'storageKeysChanged' | 'stateDiffs' | 'storageDiffs' | 'signals' | 'fieldsChanged';
 export declare function causalSummary(events: readonly ReticleEvent[], context?: SummaryContext): CausalSummary;
 export {};

package/dist/judgement/capsule/causal-summary.js

@@ -69,6 +69,7 @@ export function causalSummary(events, context = {}) {
     const storageDiffs = [];
     let route;
     const signals = [];
+    const fieldsChanged = [];
     let layoutShift;
     let longTasks = 0;
     for (const event of events) {
@@ -131,6 +132,9 @@ export function causalSummary(events, context = {}) {
             case EventType.SIGNAL:
                 pushUnique(signals, data['name']);
                 break;
+            case EventType.FIELD_CHANGE:
+                pushUnique(fieldsChanged, data['field']);
+                break;
             case EventType.PERF:
                 if (data['metric'] === PerfMetric.CLS && 'number' === typeof data['value']) {
                     layoutShift = Math.max(layoutShift ?? 0, data['value']);
@@ -163,6 +167,9 @@ export function causalSummary(events, context = {}) {
         storageDiffs: cap(storageDiffs, 'storageDiffs', elided),
         ...(route === undefined ? {} : { route }),
         signals: cap(signals, 'signals', elided),
+        ...(0 === fieldsChanged.length
+            ? {}
+            : { fieldsChanged: cap(fieldsChanged, 'fieldsChanged', elided) }),
         ...(0 === Object.keys(elided).length ? {} : { elided }),
         ...(layoutShift === undefined ? {} : { layoutShift }),
         longTasks,

package/dist/judgement/domain/domain-model.js

@@ -12,7 +12,7 @@
  *
  * Pure: no IO, no clock. The tool layer loads flows + contract and calls this.
  */
-import { AnchorKind, } from '@reticlehq/core';
+import { AnchorKind, PredicateKind, } from '@reticlehq/core';
 import { classifyFlowAssertions, FlowAssertionGrade } from '../../language/flows/flow-classify.js';
 import { successLabel } from '../../language/flows/flow-success.js';
 import { flowRisk, latestRun, rankByRisk, RiskLevel } from './flow-risk.js';
@@ -25,16 +25,45 @@ function flatten(steps) {
     }
     return out;
 }
+/*
+ * The vocabulary a flow uses, read out of a predicate TREE.
+ *
+ * These were property reads when `expect` was a struct with one slot per kind. A predicate nests, and
+ * the domain model is about what a flow TALKS ABOUT, so the walk goes all the way down: a signal
+ * named inside an `allOf` two levels deep is still a signal this flow depends on, and missing it
+ * would quietly shrink the model that decides which flows a change affects.
+ */
+function walkClauses(predicate) {
+    if (predicate === undefined)
+        return [];
+    if (PredicateKind.ALL_OF === predicate.kind || PredicateKind.ANY_OF === predicate.kind) {
+        return predicate.predicates.flatMap(walkClauses);
+    }
+    if (PredicateKind.NOT === predicate.kind)
+        return walkClauses(predicate.predicate);
+    return [predicate];
+}
+function signalNamesIn(predicate) {
+    return walkClauses(predicate)
+        .filter((c) => PredicateKind.SIGNAL === c.kind)
+        .map((c) => (PredicateKind.SIGNAL === c.kind ? c.name : undefined))
+        .filter((name) => name !== undefined);
+}
+function elementTestidsIn(predicate) {
+    return walkClauses(predicate)
+        .map((c) => (PredicateKind.ELEMENT === c.kind ? c.query.testid : undefined))
+        .filter((testid) => testid !== undefined);
+}
 function flowSignals(flow) {
     const set = new Set();
     for (const step of flatten(flow.steps)) {
         if (step.anchor.kind === AnchorKind.SIGNAL)
             set.add(step.anchor.name);
-        if (step.expect?.signal !== undefined)
-            set.add(step.expect.signal);
+        for (const name of signalNamesIn(step.expect))
+            set.add(name);
     }
-    if (flow.success?.signal !== undefined)
-        set.add(flow.success.signal);
+    for (const name of signalNamesIn(flow.success))
+        set.add(name);
     return [...set];
 }
 function flowTestids(flow) {
@@ -42,11 +71,11 @@ function flowTestids(flow) {
     for (const step of flatten(flow.steps)) {
         if (step.anchor.kind === AnchorKind.TESTID)
             set.add(step.anchor.value);
-        if (step.expect?.element?.testid !== undefined)
-            set.add(step.expect.element.testid);
+        for (const testid of elementTestidsIn(step.expect))
+            set.add(testid);
     }
-    if (flow.success?.element?.testid !== undefined)
-        set.add(flow.success.element.testid);
+    for (const testid of elementTestidsIn(flow.success))
+        set.add(testid);
     return [...set];
 }
 const EMPTY_CONTRACT = { testids: [], signals: [], stores: [], flows: [] };

package/dist/judgement/outcome/assertion-integrity.d.ts

@@ -1,4 +1,4 @@
-import { type FlowExpect } from '@reticlehq/core';
+import { type Predicate } from '@reticlehq/core';
 /**
  * Anti-reward-hacking (research-mandated). Test-gated agents pass gates by WEAKENING assertions — the
  * canonical documented failure. Flows are git-checked and agent-editable, so a mustHold that dropped
@@ -7,10 +7,10 @@ import { type FlowExpect } from '@reticlehq/core';
  * and flow_verify surface it.
  */
 /** True when `after` weakened `before` — a real consequence became a fakeable presence-only check. */
-export declare function isAssertionDowngrade(before: FlowExpect | undefined, after: FlowExpect | undefined): boolean;
+export declare function isAssertionDowngrade(before: Predicate | undefined, after: Predicate | undefined): boolean;
 export interface StepExpect {
     step: number;
-    expect?: FlowExpect;
+    expect?: Predicate;
 }
 interface DowngradeFinding {
     step: number;

package/dist/judgement/phenomena/phenomena.d.ts

@@ -4,7 +4,7 @@ import { PhenomenonType, type JournalAction, type ReticleEvent } from '@reticleh
  * scanning by the agent: the layer names the fault, the agent acts on the name. `pre-hydration-click`
  * lands once the hydration signal (a later item) exists; the three here need only journal data.
  */
-export interface Finding {
+interface Finding {
     phenomenon: PhenomenonType;
     evidence: Record<string, unknown>;
 }
@@ -24,3 +24,4 @@ export declare function detectPreHydrationClicks(events: readonly ReticleEvent[]
 export declare function detectSwallowedErrors(events: readonly ReticleEvent[]): Finding[];
 /** Run every journal-only matcher over a session's events + actions. */
 export declare function detectPhenomena(events: readonly ReticleEvent[], actions: readonly JournalAction[]): Finding[];
+export {};

package/dist/judgement/runs/artifact/gap-report.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The session gap, as a person reads it — and as a Stop hook prints it.
+ *
+ * `gapSummary` folds the journal into what was claimed and what held. This is its only renderer, so
+ * `reticle report` and the hook cannot describe the same session two different ways.
+ */
+import type { GapSummary } from './gap-summary.js';
+/**
+ * One line when the agent finishes without a single `yes`, and nothing otherwise.
+ *
+ * Silent after a `yes` on purpose: a hook that speaks on every stop is a hook people turn off, and the
+ * question it exists to raise is "did anything get proved at all". Every answer that is not a yes is
+ * counted by name — an `unknown` is never folded into anything, because that fold is the false green.
+ */
+export declare function gapHookLine(gap: GapSummary): string | undefined;
+/** The whole gap: held of claimed first, then each kind of not-held with who can act on it. */
+export declare function gapReportLines(gap: GapSummary): string[];

package/dist/judgement/runs/artifact/gap-report.js

@@ -0,0 +1,46 @@
+const HOOK_PREFIX = 'Reticle: not verified.';
+const NO_CLAIM_HOOK = `${HOOK_PREFIX} No claim was checked this session`;
+const NO_CLAIM_REPORT = 'no claims this session, so nothing was verified';
+const plural = (n, word) => `${String(n)} ${word}${1 === n ? '' : 's'}`;
+/**
+ * One line when the agent finishes without a single `yes`, and nothing otherwise.
+ *
+ * Silent after a `yes` on purpose: a hook that speaks on every stop is a hook people turn off, and the
+ * question it exists to raise is "did anything get proved at all". Every answer that is not a yes is
+ * counted by name — an `unknown` is never folded into anything, because that fold is the false green.
+ */
+export function gapHookLine(gap) {
+    if (0 < gap.held)
+        return undefined;
+    if (0 === gap.claims)
+        return NO_CLAIM_HOOK;
+    const parts = [
+        0 < gap.failed ? `${String(gap.failed)} failed` : undefined,
+        0 < gap.undecided ? `${String(gap.undecided)} unknown` : undefined,
+        0 < gap.nothingToProve ? `${String(gap.nothingToProve)} proved nothing` : undefined,
+    ].filter((part) => part !== undefined);
+    return `${HOOK_PREFIX} ${plural(gap.claims, 'claim')}: ${parts.join(', ')}`;
+}
+/** The whole gap: held of claimed first, then each kind of not-held with who can act on it. */
+export function gapReportLines(gap) {
+    if (0 === gap.claims)
+        return [NO_CLAIM_REPORT];
+    const lines = [`${String(gap.held)} of ${plural(gap.claims, 'claim')} held`];
+    if (0 < gap.failed) {
+        const caught = 0 < gap.falseGreensCaught
+            ? `, ${String(gap.falseGreensCaught)} of them a green a channel contradicted`
+            : '';
+        lines.push(`${String(gap.failed)} failed${caught}`);
+    }
+    if (0 < gap.undecided) {
+        const owners = Object.entries(gap.undecidedBy)
+            .map(([owner, n]) => `${owner}: ${String(n)}`)
+            .join(', ');
+        lines.push(`${String(gap.undecided)} unknown${'' === owners ? '' : ` (${owners})`}`);
+    }
+    if (0 < gap.nothingToProve)
+        lines.push(`${String(gap.nothingToProve)} proved nothing`);
+    for (const failure of gap.failures)
+        lines.push(`  ✗ ${failure.claim}`);
+    return lines;
+}

package/dist/judgement/runs/artifact/gap-summary.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The gap, as a number the person who ran the session can see.
+ *
+ * Reticle's whole claim is that it measures the distance between what an agent believed happened
+ * and what did. It measures that on every verdict, writes the answer into the journal, and shows it
+ * to nobody: the counts exist, the reasons exist, the contradictions exist, and no surface anywhere
+ * says "you made 14 claims, 9 held, 2 were false, 3 could not be decided, and here is who owns each
+ * of those three". The value of the product is the one thing it never reports.
+ *
+ * A FOLD over the journal, never a second store — the rule `run-context.ts` next door states, for
+ * the same reason: two ways to compute one number is worse than one way, because the day they
+ * disagree the disagreement lands inside a verdict and a user finds it before we do.
+ *
+ * Nothing here sends anything anywhere, and that is deliberate rather than incidental. This is the
+ * LOCAL half. Whether a fleet-wide version of the same number is worth collecting is a separate
+ * decision with a separate owner, and building the local one first is what makes that decision
+ * answerable from something other than a guess.
+ */
+import { VerifiedReason, VerdictAttribution, type JournalAction } from '@reticlehq/core';
+/** One claim that did not hold, in the words it was made and the engine's reason for refusing it. */
+export interface GapFailure {
+    claim: string;
+    reason?: VerifiedReason;
+}
+export interface GapSummary {
+    /** Actions that asserted something. An action that only drove the app is not a claim. */
+    claims: number;
+    held: number;
+    failed: number;
+    /** `unknown`: Reticle could not tell. Never folded into held or failed — that is the false green. */
+    undecided: number;
+    /**
+     * `no-fault`: nothing was declared, so nothing was checked.
+     *
+     * The fourth answer, kept apart from the other three. Folding it anywhere is how a session that
+     * proved nothing reads as a session that proved something.
+     */
+    nothingToProve: number;
+    /**
+     * WHO can act on each undecided verdict, counted per owner.
+     *
+     * The only part of an `unknown` a reader can do anything with: the four owners imply four
+     * different next moves — wait, fix the app, fix the harness, look again. Empty when nothing was
+     * undecided, and a verdict that recorded no reason contributes to no owner rather than to a
+     * guessed one.
+     */
+    undecidedBy: Partial<Record<VerdictAttribution, number>>;
+    /**
+     * Failures where a CHANNEL disagreed with what the app showed.
+     *
+     * Counted apart from an ordinary failure because they mean different things to the reader: an
+     * assertion that failed is a check doing its job, and a contradiction is a green that would have
+     * been believed. This number is the product's own headline, measured on the reader's own session.
+     */
+    falseGreensCaught: number;
+    failures: GapFailure[];
+}
+export declare function gapSummary(actions: readonly JournalAction[]): GapSummary;

package/dist/judgement/runs/artifact/gap-summary.js

@@ -0,0 +1,85 @@
+/**
+ * The gap, as a number the person who ran the session can see.
+ *
+ * Reticle's whole claim is that it measures the distance between what an agent believed happened
+ * and what did. It measures that on every verdict, writes the answer into the journal, and shows it
+ * to nobody: the counts exist, the reasons exist, the contradictions exist, and no surface anywhere
+ * says "you made 14 claims, 9 held, 2 were false, 3 could not be decided, and here is who owns each
+ * of those three". The value of the product is the one thing it never reports.
+ *
+ * A FOLD over the journal, never a second store — the rule `run-context.ts` next door states, for
+ * the same reason: two ways to compute one number is worse than one way, because the day they
+ * disagree the disagreement lands inside a verdict and a user finds it before we do.
+ *
+ * Nothing here sends anything anywhere, and that is deliberate rather than incidental. This is the
+ * LOCAL half. Whether a fleet-wide version of the same number is worth collecting is a separate
+ * decision with a separate owner, and building the local one first is what makes that decision
+ * answerable from something other than a guess.
+ */
+import { JournalVerdictEffectSchema, Verified, VerifiedReason, VerdictAttribution, verdictAttributionOf, } from '@reticlehq/core';
+/**
+ * The reason, as the engine's own enum, or undefined.
+ *
+ * The journal stores `reason` as a free string rather than the enum — deliberately, because the
+ * ledger has to keep reading records written by an older engine whose vocabulary it cannot know.
+ * So a reason this build does not recognise is treated exactly like an absent one: no owner. The
+ * alternative is attributing an unknown word to one of four buckets, which is inventing an
+ * attribution nobody recorded.
+ */
+function knownReason(reason) {
+    if (reason === undefined)
+        return undefined;
+    const known = Object.values(VerifiedReason);
+    return known.includes(reason) ? reason : undefined;
+}
+/** The verdict a verification tool recorded on this action, if it recorded one. */
+function verdictOf(action) {
+    const parsed = JournalVerdictEffectSchema.safeParse(action.effect);
+    return parsed.success ? parsed.data : undefined;
+}
+export function gapSummary(actions) {
+    const summary = {
+        claims: 0,
+        held: 0,
+        failed: 0,
+        undecided: 0,
+        nothingToProve: 0,
+        undecidedBy: {},
+        falseGreensCaught: 0,
+        failures: [],
+    };
+    for (const action of actions) {
+        const verdict = verdictOf(action);
+        if (verdict === undefined)
+            continue;
+        summary.claims += 1;
+        switch (verdict.verified) {
+            case Verified.YES:
+                summary.held += 1;
+                break;
+            case Verified.NO: {
+                summary.failed += 1;
+                if (VerifiedReason.CONTRADICTED === verdict.reason)
+                    summary.falseGreensCaught += 1;
+                const reason = knownReason(verdict.reason);
+                summary.failures.push(reason === undefined ? { claim: verdict.claim } : { claim: verdict.claim, reason });
+                break;
+            }
+            case Verified.UNKNOWN: {
+                summary.undecided += 1;
+                // A record written before `reason` existed has none, and must not be read as though it did:
+                // counting it under an owner would invent an attribution nobody recorded.
+                const reason = knownReason(verdict.reason);
+                const owner = reason === undefined ? undefined : verdictAttributionOf(reason);
+                if (owner !== undefined && VerdictAttribution.NONE !== owner) {
+                    summary.undecidedBy[owner] = (summary.undecidedBy[owner] ?? 0) + 1;
+                }
+                break;
+            }
+            case Verified.NO_FAULT:
+                summary.nothingToProve += 1;
+                break;
+        }
+    }
+    return summary;
+}

package/dist/judgement/runs/artifact/render-report.js

@@ -35,7 +35,10 @@ const CHECK_GLYPH = {
     [Verified.NO_FAULT]: '–',
 };
 function checkLine(c) {
-    return `  ${CHECK_GLYPH[c.status]} ${c.kind}: ${c.predicate}`;
+    // No kind, no prefix. A check folded from a journal that never recorded one has nothing to name
+    // here, and printing a placeholder would read as a kind.
+    const read = c.kind === undefined ? '' : `${c.kind}: `;
+    return `  ${CHECK_GLYPH[c.status]} ${read}${c.predicate}`;
 }
 function riskLine(r) {
     return `  ⚠ ${r.surface} (${r.severity})${r.gated ? ' [GATED]' : ''} — ${r.detail}`;

package/dist/judgement/runs/artifact/to-artifact.d.ts

@@ -22,8 +22,13 @@ export declare const OVP_ARTIFACT_VERSION = 1;
 export interface ExportedCheck {
     /** What was claimed, as the person or agent wrote it. */
     readonly claim: string;
-    /** Which source of truth answering it required. */
-    readonly reads: PredicateKind;
+    /**
+     * Which source of truth answering it required.
+     *
+     * Absent when the run did not record one -- which is the same rule the rest of this file follows:
+     * a kind nobody wrote down is left out, never filled in with a plausible one.
+     */
+    readonly reads?: PredicateKind;
     /**
      * Was the claim written down before the action, or after it?
      *

package/dist/judgement/runs/artifact/to-artifact.js

@@ -31,7 +31,7 @@ function exportedChecks(run) {
     for (const check of run.checks) {
         decided.push({
             claim: check.predicate,
-            reads: check.kind,
+            ...(check.kind === undefined ? {} : { reads: check.kind }),
             verdict: check.status,
             // Spread, so a value the run did not record leaves the key out rather than writing a
             // comfortable default. `declaredBeforeActing: false` says the claim came afterwards; absent

package/dist/judgement/runs/context-tools.js

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import {} from '@reticlehq/core';
 import { runContextFor } from './artifact/run-context.js';
+import { gapSummary } from './artifact/gap-summary.js';
 import { openSessionIntents } from '../../memory/intent/open-intents.js';
 import { ReticleTool } from '@reticlehq/core';
 import { sessionIdShape } from '../../surface/tools/tool-kit.js';
@@ -27,9 +28,13 @@ const CONTEXT_OUTPUT_SCHEMA = {
     proven: z
         .array(z.unknown())
         .describe('Claims a verdict already settled, each `{ claim, verified, source?, doc?, epoch? }`. Read this before re-driving something: re-proving it is slow, and assuming it is a false green.'),
+    gap: z
+        .object({})
+        .passthrough()
+        .describe('The distance between what was claimed and what held, over THIS session: `{ claims, held, failed, undecided, nothingToProve, undecidedBy, falseGreensCaught, failures }`. `undecidedBy` says WHO can act on each unknown — environment (wait), code (fix the app), harness (fix Reticle or the call), could-not-see (look again). Folded from the same journal as everything else here, so it cannot disagree with it.'),
     remaining: z
         .array(z.string())
-        .describe('The intents from .reticle/intent.json that no verdict has discharged. Derived from the ledger, never a guess at what you meant to do next.'),
+        .describe('The intents from .reticle/intent/ that no verdict has discharged. Derived from the ledger, never a guess at what you meant to do next.'),
 };
 /** The ledger and the live page state this run is folded out of. `[]`/undefined when nothing is connected. */
 async function evidenceFor(deps, sessionId) {
@@ -57,14 +62,27 @@ async function evidenceFor(deps, sessionId) {
 export const CONTEXT_TOOLS = [
     {
         name: ReticleTool.CONTEXT,
-        description: 'What THIS run has already established, so you do not rediscover it. Call it when your own copy is gone: right after a compaction, at the top of a fresh sub-agent, or at the start of a turn you did not begin. Returns `established` (what Reticle OBSERVED, with the source file:line where one was reported), `proven` (claims a verdict already settled, so you neither re-prove them nor assume them) and `remaining` (the intents from .reticle/intent.json that nothing has discharged). It is a FOLD over the journal, never a second store, so it cannot disagree with the ledger. Bounded and superseding rather than accumulating, and anything observed under a replaced document or before your last source edit is already dropped rather than presented as current. Only what Reticle observed goes in: it never reports what you intended or believed.',
+        description: 'What THIS run has already established, so you do not rediscover it. Call it when your own copy is gone: right after a compaction, at the top of a fresh sub-agent, or at the start of a turn you did not begin. Returns `established` (what Reticle OBSERVED, with the source file:line where one was reported), `proven` (claims a verdict already settled, so you neither re-prove them nor assume them) and `remaining` (the intents from .reticle/intent/ that nothing has discharged). It is a FOLD over the journal, never a second store, so it cannot disagree with the ledger. Bounded and superseding rather than accumulating, and anything observed under a replaced document or before your last source edit is already dropped rather than presented as current. Only what Reticle observed goes in: it never reports what you intended or believed.',
         example: {},
         inputSchema: { ...sessionIdShape },
         outputSchema: CONTEXT_OUTPUT_SCHEMA,
         handler: async (deps, args) => {
             const sessionId = asString(args['sessionId']);
             const evidence = await evidenceFor(deps, sessionId);
-            return runContextFor({ ...evidence, intents: await openSessionIntents(deps, sessionId) });
+            const context = runContextFor({
+                ...evidence,
+                intents: await openSessionIntents(deps, sessionId),
+            });
+            /*
+             * The gap rides on `reticle_context` rather than on a tool of its own.
+             *
+             * This is the one call an agent makes when it needs to know what the run has already settled,
+             * which is exactly the moment "and what did NOT settle, and whose problem each of those is"
+             * is worth reading. It is folded from the same journal the rest of this response is folded
+             * from, so it costs one more pass over an array already in hand and cannot disagree with the
+             * `proven` list beside it.
+             */
+            return { ...context, gap: gapSummary(evidence.actions) };
         },
     },
 ];