@reticlehq/server 2.14.0 → 3.2.0

package/dist/judgement/domain/domain-tools.d.ts

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

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

@@ -0,0 +1,96 @@
+import { z } from 'zod';
+import { projectForRoot } from '../../memory/project/project-for-root.js';
+import { sessionRoot } from '../../memory/project/session-root.js';
+import { asNumber, asString } from '@reticlehq/core';
+import { ReticleTool } from '@reticlehq/core';
+import { countSchema } from '../../surface/tools/args/numeric-bounds.js';
+import { readContract } from '../../memory/project/dir/reticle-dir.js';
+import { buildDomainModel } from './domain-model.js';
+import { proposeInstrumentation } from '../oracles/self-instrument.js';
+import { instrumentationGapsForFlows } from '../oracles/flow-instrument-gaps.js';
+/**
+ * reticle_domain — the "learn the app before testing it" tool. Synthesizes every saved flow + the
+ * registered capabilities into a compact domain model: the journeys, what each asserts, and the
+ * GAPS (declared signals/testids no flow verifies). An agent reads this once instead of crawling
+ * the whole app or reading all the source — and it points straight at untested intent.
+ */
+/** Flows detailed when the caller does not ask for a specific count. */
+const DEFAULT_FLOW_DETAIL_LIMIT = 25;
+export const DOMAIN_TOOLS = [
+    {
+        name: ReticleTool.DOMAIN,
+        description: 'Read the app domain model BEFORE testing: every saved flow with its assertion grade, the consequence that MUST hold for it (mustHold = what it actually tests), the anchors/signals it exercises, plus GAPS — declared signals/testids that NO flow asserts (untested intent), and flows that assert no observable consequence. Use this to decide what to test and where the real risk is, instead of crawling the whole app. Reads .reticle/flows/ + .reticle/contract.json (no browser needed).',
+        inputSchema: {
+            limit: countSchema
+                .optional()
+                .describe('Most-recent N flows to detail. Defaults to 25 — the per-flow list grows with every saved flow (measured at ~11KB / ~2,700 tokens at 22 flows) and a large project would spend most of an agent context on flows it is not asking about. `flowCount` is always the true total, and the gaps/coverage summary is computed over ALL flows regardless, so capping the detail never changes the analysis.'),
+        },
+        outputSchema: {
+            flowCount: z.number(),
+            flows: z.array(z.object({
+                name: z.string(),
+                steps: z.number(),
+                grade: z.string(),
+                asserts: z.boolean(),
+                mustHold: z
+                    .string()
+                    .optional()
+                    .describe('The success consequence that must hold for this flow (what it actually tests).'),
+                warning: z.string().optional(),
+                signals: z.array(z.string()),
+                testids: z.array(z.string()),
+            })),
+            declared: z.object({
+                testids: z.number(),
+                signals: z.array(z.string()),
+                stores: z.array(z.string()),
+            }),
+            flowsTruncated: z
+                .number()
+                .optional()
+                .describe('How many flows were omitted from `flows` by `limit`. Absent means the listing is complete. gaps/coverage always cover every flow.'),
+            coverage: z.object({
+                asserted: z.number(),
+                presenceOnly: z.number(),
+                assertionFree: z.number(),
+            }),
+            gaps: z.object({
+                unassertedFlows: z.array(z.string()),
+                declaredUntestedSignals: z.array(z.string()),
+                declaredUntestedTestids: z.array(z.string()),
+            }),
+            riskRanked: z
+                .array(z.string())
+                .describe('Flow names worst-risk first (run history + assertion quality). Test these first.'),
+            summary: z.string(),
+            instrumentation: z
+                .array(z.unknown())
+                .optional()
+                .describe('Ready-to-apply instrumentation proposals for gaps that have a source location — { file, line, insert, rationale }. Apply, re-verify, and the app’s observability compounds.'),
+        },
+        handler: async (deps, args) => {
+            const names = await deps.flows.list();
+            const flows = [];
+            for (const name of names) {
+                const loaded = await deps.flows.load(name);
+                if (loaded.ok)
+                    flows.push(loaded.value);
+            }
+            const root = sessionRoot(deps, asString(args['sessionId']));
+            const contract = await readContract(deps.fs, root);
+            const project = await projectForRoot(deps, root).read();
+            const runs = project.ok ? project.file.runs : [];
+            const model = buildDomainModel(flows, contract.ok ? contract.capabilities : null, runs);
+            // Self-instrumentation: turn located gaps (unasserted flows with a source stamp) into apply-ready diffs.
+            const stepsByName = new Map(flows.map((f) => [f.name, f.steps]));
+            const instrumentation = proposeInstrumentation(instrumentationGapsForFlows(model.gaps.unassertedFlows, stepsByName));
+            // The per-flow detail is capped; `flowCount`, `gaps` and `coverage` are computed over every
+            // flow, so the ANALYSIS is never truncated — only the listing an agent reads past is.
+            const cap = asNumber(args['limit']) ?? DEFAULT_FLOW_DETAIL_LIMIT;
+            const capped = model.flows.length > cap
+                ? { ...model, flows: model.flows.slice(-cap), flowsTruncated: model.flows.length - cap }
+                : model;
+            return instrumentation.length > 0 ? { ...capped, instrumentation } : capped;
+        },
+    },
+];

package/dist/judgement/domain/flow-risk.js

@@ -0,0 +1,80 @@
+/**
+ * Risk-rank flows so an agent tests the riskiest first. Risk combines two signals:
+ *  - run history (.reticle/project.json): a flow whose last run errored/drifted, or passed but with
+ * console/network errors, is riskier than one that passed clean; a never-run flow is unknown.
+ * - assertion quality (flow-classify): a flow that asserts no consequence is risky EVEN when it
+ * "passes" — a green assertion-free flow is false confidence (Fowler/Dodds), so it can't be
+ * trusted to catch a regression.
+ *
+ * Taking the worse of the two means "passed clean last time" never hides "but it asserts nothing".
+ * Pure: no IO, no clock.
+ */
+import { RunStatus } from '@reticlehq/core';
+import { FlowAssertionGrade } from '../../language/flows/flow-classify.js';
+export const RiskLevel = {
+    HIGH: 'high',
+    MEDIUM: 'medium',
+    LOW: 'low',
+    UNKNOWN: 'unknown',
+};
+// Test-priority order: a known failure first, then a known weakness, then a NEVER-RUN flow
+// (unvalidated — worth running before a known-clean one), then a clean low-risk flow last.
+const RANK = {
+    [RiskLevel.HIGH]: 3,
+    [RiskLevel.MEDIUM]: 2,
+    [RiskLevel.UNKNOWN]: 1,
+    [RiskLevel.LOW]: 0,
+};
+/** Most recent run for a flow name (by `at`), or undefined if it has never been recorded. */
+export function latestRun(name, runs) {
+    let best;
+    for (const run of runs) {
+        if (run.name === name && (best === undefined || run.at > best.at))
+            best = run;
+    }
+    return best;
+}
+function runRisk(run) {
+    if (run === undefined)
+        return { level: RiskLevel.UNKNOWN, reason: 'never run' };
+    if (run.status === RunStatus.ERROR || run.status === RunStatus.FAIL) {
+        return { level: RiskLevel.HIGH, reason: 'last run failed' };
+    }
+    if (run.status === RunStatus.DRIFT)
+        return { level: RiskLevel.HIGH, reason: 'last run drifted' };
+    const errors = (run.evidence?.consoleErrors ?? 0) + (run.evidence?.networkErrors ?? 0);
+    if (errors > 0) {
+        return {
+            level: RiskLevel.MEDIUM,
+            reason: `last run passed but logged ${String(errors)} error(s)`,
+        };
+    }
+    return { level: RiskLevel.LOW, reason: 'last run passed clean' };
+}
+function gradeRisk(grade) {
+    if (grade === FlowAssertionGrade.ASSERTION_FREE) {
+        return {
+            level: RiskLevel.MEDIUM,
+            reason: 'asserts no consequence — a green run proves little',
+        };
+    }
+    if (grade === FlowAssertionGrade.PRESENCE_ONLY) {
+        return { level: RiskLevel.LOW, reason: 'presence-only assertion' };
+    }
+    return { level: RiskLevel.LOW, reason: 'asserts a consequence' };
+}
+/** The worse of run-history risk and assertion-quality risk. */
+export function flowRisk(grade, run) {
+    const r = runRisk(run);
+    const g = gradeRisk(grade);
+    const top = RANK[r.level] >= RANK[g.level] ? r : g;
+    return run === undefined
+        ? { level: top.level, reason: top.reason }
+        : { level: top.level, reason: top.reason, lastStatus: run.status };
+}
+/** Order flow names worst-risk first (HIGH→UNKNOWN), ties broken by name for stable output. */
+export function rankByRisk(entries) {
+    return [...entries]
+        .sort((a, b) => RANK[b.risk.level] - RANK[a.risk.level] || a.name.localeCompare(b.name))
+        .map((e) => e.name);
+}

package/dist/judgement/oracles/propose-consequences.d.ts

@@ -0,0 +1,22 @@
+import { type ReticleEvent } from '@reticlehq/core';
+/**
+ * Given the window a recording captured, propose ranked `mustHold` predicates — the practical answer
+ * to "you recorded a flow, now what should it assert?".
+ *
+ * Ranking follows the consequence tiering: a signal (the app attested it) beats net/state/route
+ * (observable consequences) beats presence (a wrong or healed locator can fake it). Deterministic,
+ * and accepting a proposal is one ordinary tool call.
+ */
+interface ProposedConsequence {
+    /** A predicate object, directly usable as a mustHold. */
+    predicate: Record<string, unknown>;
+    /** Ranking tier: 0 strongest (signal) … 2 weakest (presence). */
+    tier: number;
+    /** Human label for the proposal. */
+    label: string;
+    /** True for presence-only proposals — flagged because they can be faked. */
+    weak: boolean;
+}
+/** Propose ranked consequences from a recorded event window. Deduped; strongest first. */
+export declare function proposeConsequences(events: readonly ReticleEvent[]): ProposedConsequence[];
+export {};

package/dist/judgement/oracles/propose-consequences.js

@@ -0,0 +1,106 @@
+import { EventType, PredicateKind } from '@reticlehq/core';
+import { routeOfEvent } from '@reticlehq/engine/question/predicate/predicate-route.js';
+const TIER = { SIGNAL: 0, CONSEQUENCE: 1, PRESENCE: 2 };
+function pathname(url) {
+    if (typeof url !== 'string')
+        return undefined;
+    try {
+        return new URL(url, 'http://x').pathname;
+    }
+    catch {
+        return url;
+    }
+}
+/** Propose ranked consequences from a recorded event window. Deduped; strongest first. */
+export function proposeConsequences(events) {
+    const seen = new Set();
+    const proposals = [];
+    const add = (key, proposal) => {
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        proposals.push(proposal);
+    };
+    for (const event of events) {
+        const data = event.data;
+        switch (event.type) {
+            case EventType.SIGNAL: {
+                const name = data['name'];
+                if ('string' === typeof name) {
+                    add(`signal:${name}`, {
+                        predicate: { kind: PredicateKind.SIGNAL, name },
+                        tier: TIER.SIGNAL,
+                        label: `signal "${name}" fires`,
+                        weak: false,
+                    });
+                }
+                break;
+            }
+            case EventType.NET_REQUEST: {
+                const path = pathname(data['url']);
+                const method = 'string' === typeof data['method'] ? data['method'] : 'GET';
+                if (path !== undefined) {
+                    add(`net:${method} ${path}`, {
+                        predicate: {
+                            kind: PredicateKind.NET,
+                            method,
+                            urlContains: path,
+                            status: data['status'],
+                        },
+                        tier: TIER.CONSEQUENCE,
+                        label: `${method} ${path} responds`,
+                        weak: false,
+                    });
+                }
+                break;
+            }
+            case EventType.STATE_CHANGE: {
+                const name = data['name'];
+                if ('string' === typeof name) {
+                    add(`state:${name}`, {
+                        predicate: { kind: PredicateKind.STATE, store: name, path: data['path'] },
+                        tier: TIER.CONSEQUENCE,
+                        label: `state "${name}" changes`,
+                        weak: false,
+                    });
+                }
+                break;
+            }
+            case EventType.ROUTE_CHANGE: {
+                const routed = routeOfEvent(data);
+                if (routed !== undefined) {
+                    // `pathname`, not `to`: the evaluator has never accepted `to`, so this surface was handing
+                    // the agent a predicate reticle_assert refuses with "unknown field to". A proposal that
+                    // cannot be evaluated is worse than no proposal — see the schema check in the test.
+                    //
+                    // And the ROUTER's path, not the document's: under a hash router the document pathname is
+                    // `/` on every page, so proposing it proposes an assertion that says nothing about where
+                    // the app went. See routeOfEvent.
+                    const to = routed.routePath;
+                    add(`route:${to}`, {
+                        predicate: { kind: PredicateKind.ROUTE, pathname: to },
+                        tier: TIER.CONSEQUENCE,
+                        label: `route changes to ${to}`,
+                        weak: false,
+                    });
+                }
+                break;
+            }
+            case EventType.DOM_ADDED: {
+                const name = data['name'];
+                if ('string' === typeof name && name.length > 0) {
+                    add(`presence:${name}`, {
+                        predicate: { kind: PredicateKind.ELEMENT, name },
+                        tier: TIER.PRESENCE,
+                        label: `"${name}" appears (presence only — prefer a consequence)`,
+                        weak: true,
+                    });
+                }
+                break;
+            }
+            default:
+                break;
+        }
+    }
+    return proposals.sort((a, b) => a.tier - b.tier);
+}

package/dist/judgement/outcome/predicate-to-expect.d.ts

@@ -0,0 +1,44 @@
+/**
+ * The assertion the agent MADE, in the shape a saved flow can keep.
+ *
+ * `reticle_act_and_wait { until }` is how agents assert — nearly every asserting call in a day of telemetry
+ * carried an `until`. `compileActStep` recorded only the ACTION, so a flow saved after an asserted
+ * drive came back graded `assertion-free`: "performs actions but asserts no observable consequence —
+ * it will pass even if the feature is broken." The agent had already said what success meant;
+ * Reticle discarded it and then warned the agent that the flow asserts nothing.
+ *
+ * That is the regression-suite story failing at its last step. "Record once, verify forever" is only
+ * worth anything if the recorded flow can go RED, and locally 32 of 39 saved flows cannot.
+ *
+ * The inverse of `successToPredicate`. Only the kinds FlowExpect can express are carried: `settled`
+ * is a wait rather than a claim, and `animation`/`anyOf`/`not` have no representation at all (`route` gained one — see its case below).
+ * Inventing one would write an assertion into the file that the agent never made, which is worse
+ * than recording none — a flow that asserts something nobody chose is a false green with extra steps.
+ */
+import type { FlowExpect } from '@reticlehq/core';
+import type { Predicate } from '@reticlehq/engine/question/predicate/predicate.js';
+export declare function predicateToExpect(predicate: Predicate): FlowExpect | undefined;
+/**
+ * The subset a REPLAY actually enforces.
+ *
+ * The rule has never changed: never write an assertion into a flow file that nothing evaluates. A
+ * flow reporting `grade: "asserted"` while its assertion is read by no one is a false green, in the
+ * feature whose entire purpose is preventing them.
+ *
+ * What changed is the SET. This kept only `element.testid` and `state`, because for a long time
+ * those were the only kinds replay checked — and the note here said lifting it "requires replay to
+ * evaluate them per step". Replay now does exactly that: `assertStepExpect` compiles every
+ * remaining kind through `successToPredicate` and waits on it. The condition was met and the filter
+ * was not updated, so the two drifted.
+ *
+ * That drift had a cost, and it fell on the agent. `reticle_act_and_wait { until }` IS the agent
+ * saying what success means, and `net` is overwhelmingly what it says. Every one of those was
+ * discarded at capture, so an agent-recorded flow reached disk assertion-free BY CONSTRUCTION and
+ * `reticle_verify` then correctly called it `unverifiable` — the record → save → verify path
+ * completing all the way to a run that could never be a pass. Found by driving it.
+ *
+ * The list below is exactly what `successToPredicate` reads, including an element located by
+ * role or name. A testid is also asserted directly against the DOM by the step runner. Anything
+ * it cannot compile is still dropped.
+ */
+export declare function enforcedOnReplay(expect: FlowExpect | undefined): FlowExpect | undefined;

package/dist/judgement/outcome/predicate-to-expect.js

@@ -0,0 +1,148 @@
+import { PredicateKind } from '@reticlehq/core';
+/** Merge two partial expectations; later keys win only where the earlier one said nothing. */
+function merge(into, from) {
+    return { ...from, ...into };
+}
+export function predicateToExpect(predicate) {
+    switch (predicate.kind) {
+        case PredicateKind.SIGNAL: {
+            if (predicate.name === undefined)
+                return undefined;
+            const signal = { signal: predicate.name };
+            if (predicate.dataMatches !== undefined)
+                signal.signalData = predicate.dataMatches;
+            if (predicate.count !== undefined)
+                signal.signalCount = predicate.count;
+            return signal;
+        }
+        case PredicateKind.ROUTE: {
+            // Carried, not invented: the agent said "until the route is X" in so many words. The kinds
+            // below this comment's twin in the header — animation, anyOf, not — stay refused because
+            // there the file would gain a claim nobody made.
+            const route = {};
+            if (predicate.pathname !== undefined)
+                route.pathname = predicate.pathname;
+            if (predicate.contains !== undefined)
+                route.contains = predicate.contains;
+            return 0 === Object.keys(route).length ? undefined : { route };
+        }
+        case PredicateKind.NET: {
+            const net = {};
+            if (predicate.method !== undefined)
+                net.method = predicate.method;
+            if (predicate.urlContains !== undefined)
+                net.urlContains = predicate.urlContains;
+            if (predicate.status !== undefined)
+                net.status = predicate.status;
+            if (predicate.count !== undefined)
+                net.count = predicate.count;
+            return 0 === Object.keys(net).length ? undefined : { net };
+        }
+        case PredicateKind.CONSOLE: {
+            // `contains` has no representation in FlowExpect.console (core keeps `level` and `absent`
+            // and nothing else). Copying the rest through anyway would record an assertion the agent
+            // never made: {console, level:'warn', contains:'no-op', absent:true} would save "no warn
+            // entries at all", a false red on any unrelated warning, and in the presence direction it
+            // saves a strictly weaker claim than the one chosen. This file's own rule applies: record
+            // nothing rather than something different, so the flow stays assertion-free there instead.
+            if (predicate.contains !== undefined)
+                return undefined;
+            const console_ = {};
+            if (predicate.level !== undefined)
+                console_.level = predicate.level;
+            if (predicate.absent !== undefined)
+                console_.absent = predicate.absent;
+            return 0 === Object.keys(console_).length ? undefined : { console: console_ };
+        }
+        case PredicateKind.ELEMENT: {
+            const element = {};
+            if (predicate.query.testid !== undefined)
+                element.testid = predicate.query.testid;
+            if (predicate.query.role !== undefined)
+                element.role = predicate.query.role;
+            if (predicate.query.name !== undefined)
+                element.name = predicate.query.name;
+            return 0 === Object.keys(element).length ? undefined : { element };
+        }
+        case PredicateKind.STATE: {
+            const state = { path: predicate.path };
+            if (predicate.store !== undefined)
+                state.store = predicate.store;
+            if (predicate.equals !== undefined)
+                state.equals = predicate.equals;
+            return { state };
+        }
+        case PredicateKind.ALL_OF: {
+            // `settled` members drop out on their own by returning undefined.
+            let combined;
+            for (const part of predicate.predicates) {
+                const expect = predicateToExpect(part);
+                if (expect === undefined)
+                    continue;
+                combined = combined === undefined ? expect : merge(combined, expect);
+            }
+            return combined;
+        }
+        default:
+            // settled | route | animation | anyOf | not — nothing FlowExpect can say honestly.
+            return undefined;
+    }
+}
+/**
+ * The subset a REPLAY actually enforces.
+ *
+ * The rule has never changed: never write an assertion into a flow file that nothing evaluates. A
+ * flow reporting `grade: "asserted"` while its assertion is read by no one is a false green, in the
+ * feature whose entire purpose is preventing them.
+ *
+ * What changed is the SET. This kept only `element.testid` and `state`, because for a long time
+ * those were the only kinds replay checked — and the note here said lifting it "requires replay to
+ * evaluate them per step". Replay now does exactly that: `assertStepExpect` compiles every
+ * remaining kind through `successToPredicate` and waits on it. The condition was met and the filter
+ * was not updated, so the two drifted.
+ *
+ * That drift had a cost, and it fell on the agent. `reticle_act_and_wait { until }` IS the agent
+ * saying what success means, and `net` is overwhelmingly what it says. Every one of those was
+ * discarded at capture, so an agent-recorded flow reached disk assertion-free BY CONSTRUCTION and
+ * `reticle_verify` then correctly called it `unverifiable` — the record → save → verify path
+ * completing all the way to a run that could never be a pass. Found by driving it.
+ *
+ * The list below is exactly what `successToPredicate` reads, including an element located by
+ * role or name. A testid is also asserted directly against the DOM by the step runner. Anything
+ * it cannot compile is still dropped.
+ */
+export function enforcedOnReplay(expect) {
+    if (expect === undefined)
+        return undefined;
+    const kept = {};
+    // The step runner asserts a testid against the live DOM before the predicate engine. Role and
+    // name are not that path: successToPredicate compiles them, and dropping them here made a
+    // recorded `until` by button name vanish so the saved flow could not go red.
+    const element = expect.element;
+    if (undefined !== element &&
+        (undefined !== element.testid || undefined !== element.role || undefined !== element.name)) {
+        kept.element = element;
+    }
+    // Everything `successToPredicate` can compile. Replay evaluates EVERY kind of expect through it
+    // (see assertStepExpect); this list is what that function actually reads.
+    if (expect.state !== undefined)
+        kept.state = expect.state;
+    if (expect.signal !== undefined)
+        kept.signal = expect.signal;
+    if (expect.signalData !== undefined)
+        kept.signalData = expect.signalData;
+    if (expect.signalCount !== undefined)
+        kept.signalCount = expect.signalCount;
+    if (expect.net !== undefined)
+        kept.net = expect.net;
+    if (expect.console !== undefined)
+        kept.console = expect.console;
+    // `route` joined the list the day FlowExpect gained the field. This filter and
+    // `successToPredicate` are two allowlists for one question — "can replay check this?" — and the
+    // note above records them drifting once already. They drifted again here, in the same direction,
+    // within an hour: the field was added, the mapping was added, and a route assertion still reached
+    // disk as nothing because THIS list had not heard of it. Found by driving, not by a test.
+    if (expect.route !== undefined)
+        kept.route = expect.route;
+    return 0 === Object.keys(kept).length ? undefined : kept;
+}

package/dist/judgement/runs/artifact/build-verification-run.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The verification-run assembler. A PURE mapping from already-produced verification results
+ * (flow-replay outcomes, standalone checks, risks, evidence, repair packets) into the stable
+ * ReticleVerificationRun artifact, with a deterministic verdict computed here. The clock is injected
+ * (the single `createdAt` site — never Date.now in logic, per rule 7). Gathering the inputs from a
+ * live session is a separate adapter concern; this file owns the shape + the verdict rules so both
+ * the MCP path and the programmatic Replay/Verify API produce byte-identical verdicts.
+ */
+import { type ReticleVerificationRun, type RunVerdict } from '@reticlehq/core';
+/**
+ * Everything a caller supplies; schemaVersion/createdAt/verdict are filled/computed by the builder.
+ * runId is a plain string here (string in) — the schema brands it to RunId on the way out (branded out),
+ * so construction sites stay ergonomic while consumers get the nominal type.
+ */
+export type VerificationRunInput = Omit<ReticleVerificationRun, 'schemaVersion' | 'createdAt' | 'verdict' | 'runId'> & {
+    runId: string;
+};
+/**
+ * Compute the verdict deterministically from the run's flows, checks, and risks.
+ * Rules (in order): a gated risk blocks → FAIL; mixed pass+fail → PARTIAL; any fail → FAIL;
+ * nothing proved either way → UNKNOWN; else PASS.
+ *
+ * A check that came out `unknown` or `no-fault` counts as NEITHER, which is what those words mean.
+ * A run of nothing but undetermined checks therefore reaches UNKNOWN rather than PASS -- the whole
+ * reason those two values now survive into the artifact instead of being dropped at its door.
+ * Confidence: nothing ran → LOW; an oracle-backed flow or any check ran → HIGH; only smoke → MEDIUM.
+ */
+export declare function computeVerdict(input: VerificationRunInput): RunVerdict;
+/**
+ * Assemble the final, schema-valid ReticleVerificationRun. Stamps schemaVersion + createdAt (injected
+ * clock) and computes the verdict; the result is parsed through the protocol schema so a malformed
+ * input can never escape as an "artifact".
+ */
+export declare function buildVerificationRun(input: VerificationRunInput, now: () => number): ReticleVerificationRun;

package/dist/judgement/runs/artifact/build-verification-run.js

@@ -0,0 +1,83 @@
+/**
+ * The verification-run assembler. A PURE mapping from already-produced verification results
+ * (flow-replay outcomes, standalone checks, risks, evidence, repair packets) into the stable
+ * ReticleVerificationRun artifact, with a deterministic verdict computed here. The clock is injected
+ * (the single `createdAt` site — never Date.now in logic, per rule 7). Gathering the inputs from a
+ * live session is a separate adapter concern; this file owns the shape + the verdict rules so both
+ * the MCP path and the programmatic Replay/Verify API produce byte-identical verdicts.
+ */
+import { ReticleVerificationRunSchema, RUN_FILE_VERSION, Verified, RunConfidence, RunFlowStatus, VerdictStatus, } from '@reticlehq/core';
+import { redactForProfile } from './profile-redact.js';
+/**
+ * Compute the verdict deterministically from the run's flows, checks, and risks.
+ * Rules (in order): a gated risk blocks → FAIL; mixed pass+fail → PARTIAL; any fail → FAIL;
+ * nothing proved either way → UNKNOWN; else PASS.
+ *
+ * A check that came out `unknown` or `no-fault` counts as NEITHER, which is what those words mean.
+ * A run of nothing but undetermined checks therefore reaches UNKNOWN rather than PASS -- the whole
+ * reason those two values now survive into the artifact instead of being dropped at its door.
+ * Confidence: nothing ran → LOW; an oracle-backed flow or any check ran → HIGH; only smoke → MEDIUM.
+ */
+export function computeVerdict(input) {
+    const passes = input.flows.filter((f) => f.status === RunFlowStatus.PASS || f.status === RunFlowStatus.HEALED)
+        .length + input.checks.filter((c) => c.status === Verified.YES).length;
+    const fails = input.flows.filter((f) => f.status === RunFlowStatus.FAIL).length +
+        input.checks.filter((c) => c.status === Verified.NO).length;
+    const blockingRisks = input.risks.filter((r) => r.gated).length;
+    const reasons = [];
+    for (const f of input.flows) {
+        if (f.status === RunFlowStatus.FAIL) {
+            reasons.push(f.failureReason !== undefined
+                ? `flow ${f.name}: ${f.failureReason}`
+                : `flow ${f.name} failed`);
+        }
+    }
+    for (const c of input.checks) {
+        if (c.status === Verified.NO)
+            reasons.push(`check failed: ${c.predicate}`);
+    }
+    for (const r of input.risks) {
+        if (r.gated)
+            reasons.push(`blocked: ${r.surface} risk — ${r.detail}`);
+    }
+    let status;
+    if (blockingRisks > 0)
+        status = VerdictStatus.FAIL;
+    else if (fails > 0 && passes > 0)
+        status = VerdictStatus.PARTIAL;
+    else if (fails > 0)
+        status = VerdictStatus.FAIL;
+    else if (0 === passes) {
+        // Nothing passed and nothing failed, so nothing was proved -- an empty run, or one whose every
+        // flow was skipped. Reporting that as PASS is the false green this whole file exists to prevent:
+        // every consumer here reads `status` and none reads `confidence`, so a caveat parked in the
+        // confidence field would never reach the person deciding whether to ship.
+        status = VerdictStatus.UNKNOWN;
+        reasons.push('nothing ran, so nothing was proved');
+    }
+    else
+        status = VerdictStatus.PASS;
+    const ran = input.flows.length + input.checks.length;
+    let confidence;
+    if (0 === ran)
+        confidence = RunConfidence.LOW;
+    else if (input.flows.some((f) => f.oracle !== undefined) || input.checks.length > 0)
+        confidence = RunConfidence.HIGH;
+    else
+        confidence = RunConfidence.MEDIUM;
+    return { status, reasons, confidence, blockingRisks };
+}
+/**
+ * Assemble the final, schema-valid ReticleVerificationRun. Stamps schemaVersion + createdAt (injected
+ * clock) and computes the verdict; the result is parsed through the protocol schema so a malformed
+ * input can never escape as an "artifact".
+ */
+export function buildVerificationRun(input, now) {
+    const run = {
+        schemaVersion: RUN_FILE_VERSION,
+        createdAt: now(),
+        verdict: computeVerdict(input),
+        ...input,
+    };
+    return redactForProfile(ReticleVerificationRunSchema.parse(run));
+}