@reticlehq/server 2.14.0 → 3.2.0

package/dist/judgement/runs/verification-sync.js

@@ -0,0 +1,93 @@
+/**
+ * Turn an MCP verification (a `reticle_flow_verify` suite run) into a first-class ReticleVerificationRun:
+ * assemble the artifact from the already-computed replays, persist it to .reticle/runs/ (so
+ * `reticle_run_export` and CI can read it), and — when logged in (cloud creds set) — best-effort push it
+ * to the cloud's `POST /v1/runs` so the team's dashboard Runs tab shows what the agent just verified.
+ *
+ * This is the artifact tier that maps to the dashboard's "Runs" (the OEM/CI-consumable verdict); the
+ * lighter per-flow RunRecord that feeds regression memory is synced separately in flow-replay-run.ts.
+ * Both are best-effort + opt-in: no creds → the artifact still lands on disk, nothing leaves the machine.
+ */
+import { mcpClientIdentity } from '../../surface/mcp/peer/client-identity.js';
+import { RunAgentKind, RunFramework, RunProfile, RunTrigger, } from '@reticlehq/core';
+import { homedir } from 'node:os';
+import { buildVerificationRun, } from './artifact/build-verification-run.js';
+import { mapReplayToFlowResult } from './artifact/replay-mapping.js';
+import { defaultRunId } from './default-run-id.js';
+import { RunStore } from './artifact/run-store.js';
+import { cloudFetch, syncRunToCloud, SyncOutcome } from '../../memory/cloud/cloud-sync.js';
+import { resolveProjectCloud } from '../../memory/cloud/cloud-config.js';
+import { log } from '../../log.js';
+import { rootForProjectId } from '../../memory/project/session-root.js';
+/** The author of record when no MCP peer introduced itself — a CLI run, or a client that skipped the handshake. */
+const RETICLE_MCP_AGENT_ID = 'reticle-mcp';
+/** Assemble the ReticleVerificationRun artifact for a verify suite (pure — no IO). */
+function assembleRun(deps, timed, projectId) {
+    const flows = timed.map((t) => mapReplayToFlowResult(t.replay, t.durationMs));
+    const input = {
+        runId: defaultRunId(),
+        durationMs: flows.reduce((sum, f) => sum + f.durationMs, 0),
+        profile: RunProfile.DEV,
+        project: { name: projectId ?? 'reticle', framework: RunFramework.OTHER },
+        /*
+         * WHICH agent drove this, not merely THAT one did.
+         *
+         * This was hardcoded to 'reticle-mcp', so every run in every workspace claimed the same author.
+         * A dashboard built on it could say "an agent verified this" and never "Claude Code verified
+         * this, Cursor broke it" — which is the question a team actually has once more than one agent
+         * touches the repo. The name is the client's own claim from the MCP handshake; a plain CLI run
+         * with no MCP peer keeps the old id, because inventing a vendor there would be worse than
+         * admitting we do not know.
+         */
+        agent: {
+            id: mcpClientIdentity().name ?? RETICLE_MCP_AGENT_ID,
+            kind: RunAgentKind.CODING_AGENT,
+        },
+        trigger: { kind: RunTrigger.MANUAL },
+        changedFiles: [],
+        flows,
+        checks: [],
+        risks: [],
+        evidence: { consoleErrors: [], networkAnomalies: [], stateAssertions: [], timeline: [] },
+    };
+    return buildVerificationRun(input, () => deps.now());
+}
+/**
+ * Persist the suite's run artifact and best-effort mirror it to the cloud. Never throws into the verify
+ * tool — a disk or network failure is logged and swallowed so the verdict the agent asked for is
+ * unaffected. Returns the runId (for logging/tests); undefined if nothing was produced (empty suite).
+ */
+export async function persistAndSyncVerificationRun(deps, timed, projectId) {
+    if (0 === timed.length)
+        return undefined;
+    let run;
+    // The project the suite ran for, not the directory the daemon was started in. Both halves below
+    // take it: the artifact `reticle_run` reads back through `sessionRoot`, and the cloud link that
+    // decides WHICH DASHBOARD this run is pushed to. The daemon's own directory has no link file, so
+    // a misrouted read silently meant "not attached" — and where it DID have one, the run was pushed
+    // to a dashboard belonging to whoever that checkout was linked to.
+    const root = rootForProjectId(deps, projectId);
+    try {
+        run = assembleRun(deps, timed, projectId);
+        await new RunStore(deps.fs, root).write(run);
+    }
+    catch (error) {
+        log('verification-run-persist-failed', {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+    // Per-project cloud: only push when THIS project has cloud attached AND its policy allows runs.
+    const cloud = await resolveProjectCloud(deps.fs, root, homedir(), process.env);
+    if (null === cloud.config || !cloud.policy.runs)
+        return run.runId; // not attached / runs disabled → local only
+    const result = await syncRunToCloud(run, cloud.config, cloudFetch);
+    if (result.outcome !== SyncOutcome.SYNCED) {
+        log('cloud-run-sync-failed', { runId: run.runId, status: result.status, error: result.error });
+    }
+    // The run is up; its CONTEXT is not. Nudged rather than pushed inline, so the counters and flows
+    // ride the ordinary cycle (with its cursor and its overlap guard) instead of growing a second,
+    // subtly different upload path here.
+    deps.onRunPersisted?.();
+    return run.runId;
+}

package/dist/language/flows/affected-tools.d.ts

@@ -0,0 +1,18 @@
+import type { ToolDef } from '../../surface/tools/tool-kit.js';
+/**
+ * `reticle_affected` — which saved flows must re-verify for a set of changed files.
+ *
+ * This logic already existed as `reticle affected`, deliberately kept off the MCP surface because an
+ * advertised tool costs tokens on every turn whether or not it is used. That reasoning is right, and
+ * this does not change it: the tool is NOT advertised by any profile. It is reachable through
+ * `reticle_run`, so it costs nothing per turn and is still discoverable via `reticle_tools`.
+ *
+ * What the reasoning missed is who holds the question. The AGENT is the one that just edited files
+ * and has to decide what to re-check; a shell command it may not be able to run is not an answer for
+ * an MCP client that has no shell. Leaving it CLI-only meant the party with the diff could not ask
+ * the party with the index.
+ *
+ * Unknown-provenance flows are returned as affected (fail-safe) AND listed separately, so "re-verify
+ * this" is never confused with "this definitely touches your change".
+ */
+export declare const AFFECTED_TOOLS: ToolDef[];

package/dist/language/flows/affected-tools.js

@@ -0,0 +1,83 @@
+import { z } from 'zod';
+import { ReticleTool } from '@reticlehq/core';
+import { loadNamedFlows, resolveChangedFiles } from '../../command/cli/cli-flow-commands.js';
+import { projectDirFor } from '../../memory/project/session-root.js';
+import { sessionRoot, sessionProjectId } from '../../memory/project/session-root.js';
+import { affectedSavedFlows } from './change/flow-sources.js';
+/**
+ * `reticle_affected` — which saved flows must re-verify for a set of changed files.
+ *
+ * This logic already existed as `reticle affected`, deliberately kept off the MCP surface because an
+ * advertised tool costs tokens on every turn whether or not it is used. That reasoning is right, and
+ * this does not change it: the tool is NOT advertised by any profile. It is reachable through
+ * `reticle_run`, so it costs nothing per turn and is still discoverable via `reticle_tools`.
+ *
+ * What the reasoning missed is who holds the question. The AGENT is the one that just edited files
+ * and has to decide what to re-check; a shell command it may not be able to run is not an answer for
+ * an MCP client that has no shell. Leaving it CLI-only meant the party with the diff could not ask
+ * the party with the index.
+ *
+ * Unknown-provenance flows are returned as affected (fail-safe) AND listed separately, so "re-verify
+ * this" is never confused with "this definitely touches your change".
+ */
+export const AFFECTED_TOOLS = [
+    {
+        name: ReticleTool.AFFECTED,
+        description: 'Which saved flows must re-verify for a set of changed files. Pass the files you edited (and/or `since` for a git ref to diff against). Returns { changedFiles, affected, unknownProvenance } — `affected` is what to re-run, and `unknownProvenance` are flows included only because Reticle cannot tell which sources they cover, so they are re-verified by default rather than silently skipped.',
+        example: { files: ['src/App.tsx'] },
+        inputSchema: {
+            files: z
+                .array(z.string())
+                .optional()
+                .describe('Changed file paths, repo-relative (e.g. ["src/App.tsx"]).'),
+            since: z
+                .string()
+                .optional()
+                .describe('Git ref to diff against (e.g. "HEAD~1", "main"). Unioned with `files`.'),
+        },
+        outputSchema: {
+            changedFiles: z.array(z.string()),
+            affected: z.array(z.string()),
+            unknownProvenance: z.array(z.string()),
+        },
+        handler: async (deps, args) => {
+            const files = Array.isArray(args['files'])
+                ? args['files'].filter((f) => 'string' === typeof f)
+                : [];
+            const since = 'string' === typeof args['since'] ? args['since'] : undefined;
+            // Same address as verify_change, resolved the same way. `deps.reticleRoot` is NOT the project
+            // directory this line used to claim it was — it is the daemon's `.reticle` subdirectory, in
+            // whichever tree the MCP host was started in. `undefined` here resolves the single connected
+            // session, which is the same rule the flow lookup below already follows.
+            const changed = await resolveChangedFiles(files, since, projectDirFor(deps, undefined));
+            const changedFiles = changed.files;
+            // No `sessionId` on this tool's surface, and it does not need one: passing `undefined`
+            // resolves the single connected session, and falls back exactly as before when it cannot.
+            // Adding an argument here would be a surface change to fix an addressing bug.
+            const flows = await loadNamedFlows(deps.fs, sessionRoot(deps, undefined), sessionProjectId(deps, undefined));
+            const result = affectedSavedFlows(flows, changedFiles);
+            // Three different situations produced the same empty answer: no files changed, no flows saved,
+            // and a git ref that resolved to nothing. Only the first means "nothing to re-verify"; the
+            // others mean the question could not be answered, and re-running nothing on that basis is how a
+            // regression ships. Say which one it is.
+            const why = 
+            // A git failure OUTRANKS every other explanation: the others describe a question that was
+            // answered, and this one is a question that was not. Reporting "nothing changed" over a
+            // mistyped ref or a shallow clone is how a regression ships past the tool meant to catch it.
+            changed.failed
+                ? `could not read the diff for \`${String(since)}\`, so NOTHING was compared and this result proves nothing: ${changed.reason ?? 'git failed'}`
+                : 0 === flows.length
+                    ? 'no saved flows exist yet, so nothing COULD be affected — record one with reticle_record then reticle_flow_save'
+                    : 0 === changedFiles.length
+                        ? since === undefined && 0 === files.length
+                            ? 'no files were given and no `since` ref was passed, so nothing was compared — pass the files you edited, or a git ref'
+                            : 'nothing changed against that input, so no saved flow needs re-verifying'
+                        : undefined;
+            return {
+                changedFiles,
+                ...result,
+                ...(why === undefined ? {} : { observed: true, note: why }),
+            };
+        },
+    },
+];

package/dist/language/flows/annotate-tools.d.ts

@@ -0,0 +1,15 @@
+import type { ToolDef } from '../../surface/tools/tool-kit.js';
+/**
+ * The reticle_annotate tool. A STRUCTURED annotation (the AnnotationSchema
+ * discriminated union) is compiled into the live recording's per-step expect / flow dynamic[] /
+ * flow success, which reticle_flow_save then folds onto disk. Returns the AnnotateResult envelope
+ * with the compiled-predicate confirmation text ("will assert signal diff:shown").
+ *
+ * FIRST CUT: structured annotations only. A free NATURAL-LANGUAGE annotation never compiles — it
+ * fails AnnotationSchema and is returned as UNKNOWN_KIND. NL → predicate compilation is explicitly
+ * FUTURE; no NL parser exists or is faked here.
+ *
+ * No-active-recording and no-step are SAFE, returned as structured codes (never thrown), so an
+ * agent that annotates at the wrong moment gets a clear error rather than a crash.
+ */
+export declare const ANNOTATE_TOOLS: ToolDef[];

package/dist/language/flows/annotate-tools.js

@@ -0,0 +1,179 @@
+import { z } from 'zod';
+import { aliasParam } from '../../surface/tools/args/alias-args.js';
+import { AnnotationErrorCode, AnnotationSchema } from '@reticlehq/core';
+import { RECOVERY } from '../../surface/tools/error-recovery.js';
+/**
+ * An unknown kind is almost always a free-text annotation, which this tool deliberately refuses to
+ * guess into a predicate. Naming the six kinds turns a dead end into one retry.
+ */
+const UNKNOWN_KIND_RECOVERY = 'Annotations are structured, never free text. Pass one of: ' +
+    '{ kind: "assert-signal", name }, { kind: "assert-visible", testid }, ' +
+    '{ kind: "assert-state", statePath }, { kind: "mark-dynamic", testid }, ' +
+    '{ kind: "success-state", signal|testid }, or { kind: "intent", text }.';
+import { ReticleTool } from '@reticlehq/core';
+import { asString } from '@reticlehq/core';
+import { compileAnnotation } from './annotate-notes/annotate.js';
+import { resolveAnnotateTarget } from './annotate-notes/annotate-target.js';
+/**
+ * The reticle_annotate tool. A STRUCTURED annotation (the AnnotationSchema
+ * discriminated union) is compiled into the live recording's per-step expect / flow dynamic[] /
+ * flow success, which reticle_flow_save then folds onto disk. Returns the AnnotateResult envelope
+ * with the compiled-predicate confirmation text ("will assert signal diff:shown").
+ *
+ * FIRST CUT: structured annotations only. A free NATURAL-LANGUAGE annotation never compiles — it
+ * fails AnnotationSchema and is returned as UNKNOWN_KIND. NL → predicate compilation is explicitly
+ * FUTURE; no NL parser exists or is faked here.
+ *
+ * No-active-recording and no-step are SAFE, returned as structured codes (never thrown), so an
+ * agent that annotates at the wrong moment gets a clear error rather than a crash.
+ */
+export const ANNOTATE_TOOLS = [
+    {
+        name: ReticleTool.ANNOTATE,
+        example: { kind: 'assert-signal', name: 'todos:loaded' },
+        description: 'Attach a STRUCTURED annotation to the active recording, compiling it into the flow. kind: ' +
+            'assert-signal { name, dataMatches? } → the last step asserts that signal; assert-visible ' +
+            '{ testid } → the last step asserts that element is present; assert-state ' +
+            '{ statePath, store?, equals? } → the last step asserts a registered store value (the source ' +
+            'of truth no DOM read can reach); mark-dynamic { testid } → the ' +
+            "flow records that region as LLM-dynamic (replay won't assert its content); success-state " +
+            '{ signal | statePath(+store,+equals) | net(+count) | console(+absent) | testid } → the flow golden ' +
+            'end-condition (statePath asserts a registered store value — the source of truth no DOM read can ' +
+            'reach; net asserts a request fired EXACTLY `count` times — catches double-submit; console+absent ' +
+            'asserts a clean console — catches an action that logs an error). Folded onto disk by reticle_flow_save. ' +
+            'Returns { ok:true, target:step|flow, compiled } (e.g. "will assert signal diff:shown") or ' +
+            '{ ok:false, code } (annotate_no_recording | annotate_no_step | annotate_unknown_kind | ' +
+            'annotate_missing_field). FIRST CUT: structured only — a free natural-language string is ' +
+            'rejected (annotate_unknown_kind), never guessed into a predicate. Pass `flow` to target a ' +
+            "named recording (defaults to 'default'); `name` is the assert-signal's SIGNAL name, not the recording.",
+        inputSchema: {
+            // `flow` selects the recording; `name`/`signal`/`testid`/`dataMatches` are the annotation fields.
+            flow: z.string().optional().describe("Named recording to annotate. Defaults to 'default'."),
+            // Every other flow tool says `flowName`, and reticle_flow_save's own description sends the
+            // agent here — so the spelling it arrives with is the one this tool did not accept.
+            flowName: z
+                .string()
+                .optional()
+                .describe('Alias for `flow` (the name every other flow tool uses).'),
+            kind: z
+                .string()
+                .describe('Annotation kind: assert-signal | assert-visible | assert-state | mark-dynamic | success-state | intent.'),
+            name: z.string().optional().describe('Signal name for assert-signal annotations.'),
+            text: z
+                .string()
+                .optional()
+                .describe("Business goal for an intent annotation, e.g. 'ship a deploy to production'."),
+            testid: z
+                .string()
+                .optional()
+                .describe('data-testid value for assert-visible / mark-dynamic / success-state annotations.'),
+            signal: z.string().optional().describe('Signal name for success-state annotations.'),
+            statePath: z
+                .string()
+                .optional()
+                .describe("Store dot-path for an assert-state (last step) or success-state (golden end) store-truth assertion (e.g. 'deployments.0.status'). With `store` and optional `equals` — asserts the app's source of truth, not just the DOM."),
+            store: z
+                .string()
+                .optional()
+                .describe('Store name for a statePath assert-state/success-state annotation.'),
+            equals: z
+                .unknown()
+                .optional()
+                .describe('Expected value for statePath: a literal, or a { $gte | $contains | $length }.'),
+            hold: z
+                .boolean()
+                .optional()
+                .describe('Treat statePath as an INVARIANT that must still hold AFTER the action settles (a blast-radius "this unrelated path must not have moved" check), not a condition to wait for. Without it a wait-until-true read passes before an over-reaching side-effect lands.'),
+            dataMatches: z
+                .record(z.unknown())
+                .optional()
+                .describe('Key/value pairs the signal payload must match (assert-signal only).'),
+            net: z
+                .object({
+                method: z.string().optional(),
+                urlContains: z.string().optional(),
+                status: z.number().optional(),
+                count: z.number().int().nonnegative().optional(),
+            })
+                .optional()
+                .describe('Network golden end-condition for success-state: the flow succeeds only when EXACTLY `count` requests match { method?, urlContains?, status? } since the action (omit count = presence). Catches the double-submit / retry-storm regression a presence check passes.'),
+            console: z
+                .object({
+                level: z.string().optional(),
+                absent: z.boolean().optional(),
+            })
+                .optional()
+                .describe('Console golden end-condition for success-state: with absent:true the flow succeeds only when the action logged NO console message at `level` (default "error") — "completed with a clean console". Catches an action that logs a caught error/rejection while the UI still renders fine.'),
+            sessionId: z
+                .string()
+                .optional()
+                .describe('Active session ID from reticle_sessions. Omit when only one browser session is open.'),
+            annotation: z
+                .unknown()
+                .optional()
+                .describe('Structured annotation: { kind, name, dataMatches? } for assert-signal; { kind, testid } for assert-visible / mark-dynamic; { kind, signal?, testid? } for success-state.'),
+        },
+        outputSchema: {
+            ok: z.boolean(),
+            recovery: z.string().optional(),
+            target: z.string().optional(),
+            compiled: z.string().optional(),
+            // Set when the compiled annotation would overstate what a replay can check — e.g. a
+            // success-state that flow_save will grade assertion-free (#395).
+            note: z.string().optional(),
+            code: z.string().optional(),
+        },
+        handler: (deps, args) => {
+            // The recording actually RUNNING when there is exactly one, not the literal name `default`.
+            // Reproduced on three apps: a named recording plus an unnamed annotate reported
+            // `annotate_no_step` while the steps sat in the recording the agent had started.
+            const name = resolveAnnotateTarget(asString(aliasParam(args, 'flow', ['flowName'])['flow']), deps.recordings.active());
+            // Structured boundary: a free NL string / unknown kind fails the schema → UNKNOWN_KIND.
+            const parsed = AnnotationSchema.safeParse(args);
+            if (!parsed.success) {
+                return Promise.resolve({
+                    ok: false,
+                    code: AnnotationErrorCode.UNKNOWN_KIND,
+                    recovery: UNKNOWN_KIND_RECOVERY,
+                });
+            }
+            const stepCount = deps.recordings.stepCount(name);
+            const compiled = deps.recordings.getCompiled(name) !== undefined;
+            if (stepCount === undefined && !compiled) {
+                return Promise.resolve({
+                    ok: false,
+                    code: AnnotationErrorCode.NO_ACTIVE_RECORDING,
+                    recovery: RECOVERY.MISSING_RECORDING,
+                });
+            }
+            const outcome = compileAnnotation(parsed.data, stepCount ?? 0);
+            if (!outcome.result.ok) {
+                // Name what IS recording. `annotate_no_step` alone sent the agent off to record MORE steps —
+                // into the same empty recording — when the steps it already has are in another one.
+                const active = deps.recordings.active();
+                const elsewhere = active.filter((r) => r !== name && (deps.recordings.stepCount(r) ?? 0) > 0);
+                if (outcome.result.code === AnnotationErrorCode.NO_STEP_TO_ANNOTATE &&
+                    elsewhere.length > 0) {
+                    return Promise.resolve({
+                        ...outcome.result,
+                        recovery: `'${name}' has no steps yet, but ${elsewhere.map((r) => `'${r}'`).join(', ')} does. Pass \`flow\` to say which recording this belongs to, or drive an action first.`,
+                    });
+                }
+                return Promise.resolve(outcome.result);
+            }
+            const patch = outcome.patch;
+            if (patch !== undefined) {
+                if (patch.dynamicAdd !== undefined)
+                    deps.annotations.addDynamic(name, patch.dynamicAdd);
+                if (patch.success !== undefined)
+                    deps.annotations.setSuccess(name, patch.success);
+                if (patch.intent !== undefined)
+                    deps.annotations.setIntent(name, patch.intent);
+                if (patch.stepIndex !== undefined && patch.stepExpect !== undefined) {
+                    deps.annotations.setStepExpect(name, patch.stepIndex, patch.stepExpect);
+                }
+            }
+            return Promise.resolve(outcome.result);
+        },
+    },
+];

package/dist/language/flows/change/affected.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The file→flow reverse index — the heart of the unavoidable loop. When a file changes, which flows must
+ * re-verify? A flow persists the source files its anchors were stamped from (its "sources manifest"); a
+ * changed file that appears in a flow's manifest makes that flow affected. A flow with NO manifest
+ * (recorded before source stamping, or un-stampable) is `unknown` — and unknown always means affected, never
+ * silently skipped: the loop fails safe toward re-verifying.
+ */
+export interface FlowSources {
+    name: string;
+    /** Repo-relative source files this flow's anchors came from. Empty/absent ⇒ unknown provenance. */
+    sources?: readonly string[];
+}
+export interface AffectedResult {
+    /** Flows to re-verify: those touching a changed file, plus all unknown-provenance flows. */
+    affected: string[];
+    /** Of the affected, which were included only because their provenance is unknown (fail-safe). */
+    unknownProvenance: string[];
+}
+/**
+ * Which flows are affected by a set of changed files. Deterministic; a flow with no sources manifest is
+ * always affected (fail-safe). `changedFiles` and flow sources are matched by normalized path suffix so
+ * a repo-relative change matches an absolute stamp and vice-versa.
+ */
+export declare function affectedFlows(flows: readonly FlowSources[], changedFiles: readonly string[]): AffectedResult;

package/dist/language/flows/change/affected.js

@@ -0,0 +1,35 @@
+/**
+ * The file→flow reverse index — the heart of the unavoidable loop. When a file changes, which flows must
+ * re-verify? A flow persists the source files its anchors were stamped from (its "sources manifest"); a
+ * changed file that appears in a flow's manifest makes that flow affected. A flow with NO manifest
+ * (recorded before source stamping, or un-stampable) is `unknown` — and unknown always means affected, never
+ * silently skipped: the loop fails safe toward re-verifying.
+ */
+/** Normalize a path for comparison — strip a leading./ and any file:line suffix. */
+function normalize(path) {
+    return path.replace(/^\.\//, '').replace(/:\d+(:\d+)?$/, '');
+}
+/**
+ * Which flows are affected by a set of changed files. Deterministic; a flow with no sources manifest is
+ * always affected (fail-safe). `changedFiles` and flow sources are matched by normalized path suffix so
+ * a repo-relative change matches an absolute stamp and vice-versa.
+ */
+export function affectedFlows(flows, changedFiles) {
+    const changed = changedFiles.map(normalize);
+    const matchesChange = (source) => {
+        const s = normalize(source);
+        return changed.some((c) => c === s || c.endsWith(`/${s}`) || s.endsWith(`/${c}`));
+    };
+    const affected = [];
+    const unknownProvenance = [];
+    for (const flow of flows) {
+        if (flow.sources === undefined || 0 === flow.sources.length) {
+            affected.push(flow.name);
+            unknownProvenance.push(flow.name);
+            continue;
+        }
+        if (flow.sources.some(matchesChange))
+            affected.push(flow.name);
+    }
+    return { affected, unknownProvenance };
+}

package/dist/language/flows/change/flow-sources.d.ts

@@ -0,0 +1,19 @@
+import type { FlowStep } from '@reticlehq/core';
+import { type AffectedResult, type FlowSources } from './affected.js';
+/**
+ * A flow's sources manifest, DERIVED from its already-persisted step anchors — no separate storage. A
+ * COMPONENT anchor carries the source file its element was stamped from (via the babel/next plugin);
+ * collecting those files, recursively through act_sequence sub-steps, gives the set of files whose change
+ * should re-verify this flow. A flow with no stamped sources yields an empty manifest → unknown
+ * provenance → always affected (fail-safe), handled by affectedFlows.
+ */
+export declare function flowSources(steps: readonly FlowStep[]): string[];
+/** A saved flow, minimally: its name and steps. */
+export interface NamedFlow {
+    name: string;
+    steps: readonly FlowStep[];
+}
+/** Map saved flows to the {name, sources} the affected index consumes, deriving each manifest. */
+export declare function toFlowSources(flows: readonly NamedFlow[]): FlowSources[];
+/** Which saved flows a set of changed files affects — the derivation + index in one call. */
+export declare function affectedSavedFlows(flows: readonly NamedFlow[], changedFiles: readonly string[]): AffectedResult;

package/dist/language/flows/change/flow-sources.js

@@ -0,0 +1,55 @@
+import { affectedFlows } from './affected.js';
+/**
+ * A flow's sources manifest, DERIVED from its already-persisted step anchors — no separate storage. A
+ * COMPONENT anchor carries the source file its element was stamped from (via the babel/next plugin);
+ * collecting those files, recursively through act_sequence sub-steps, gives the set of files whose change
+ * should re-verify this flow. A flow with no stamped sources yields an empty manifest → unknown
+ * provenance → always affected (fail-safe), handled by affectedFlows.
+ */
+export function flowSources(steps) {
+    const files = new Set();
+    const walk = (list) => {
+        for (const step of list) {
+            /*
+             * ANY anchor that carries a source, not only a COMPONENT one.
+             *
+             * This was `kind === COMPONENT && source !== undefined`, and the `kind` half was the whole
+             * bug. `compileAnchorArgs` attaches the source to a TESTID anchor too — deliberately, with a
+             * comment saying it rides along so a failure can name a file — so the data was already on
+             * disk and simply never read. Measured on this repository's own saved flows: 32 of 40 carry
+             * a source, and every one of them was reported as unknown-provenance.
+             *
+             * What that cost: `verify { action: "change" }` on two edited files replayed FIFTY-TWO flows
+             * in 46 seconds and answered `unknown`, because the fail-safe re-runs everything it cannot
+             * attribute. The fix needs no re-recording — those flows have been carrying the answer the
+             * whole time.
+             */
+            const anchored = step.anchor;
+            if (anchored.source !== undefined)
+                files.add(anchored.source.file);
+            /*
+             * The step's own source, which is where almost every real flow's coverage actually lives.
+             *
+             * Only a COMPONENT anchor had somewhere to put one, and a recorder prefers a TESTID anchor
+             * whenever the element has a testid — so the flows most likely to exist were exactly the ones
+             * that could never say what they cover. Every one came back unknown-provenance and the
+             * fail-safe re-ran the lot: measured against this repo's own saved flows, 52 replayed in 46
+             * seconds to answer `unknown`.
+             */
+            if (step.source !== undefined)
+                files.add(step.source.file);
+            if (step.steps !== undefined)
+                walk(step.steps);
+        }
+    };
+    walk(steps);
+    return [...files];
+}
+/** Map saved flows to the {name, sources} the affected index consumes, deriving each manifest. */
+export function toFlowSources(flows) {
+    return flows.map((flow) => ({ name: flow.name, sources: flowSources(flow.steps) }));
+}
+/** Which saved flows a set of changed files affects — the derivation + index in one call. */
+export function affectedSavedFlows(flows, changedFiles) {
+    return affectedFlows(toFlowSources(flows), changedFiles);
+}

package/dist/language/flows/change/gate.js

@@ -0,0 +1,33 @@
+/**
+ * The completion gate — exits non-zero unless passing artifacts cover the flows affected by the changed
+ * files. This is what makes verification unavoidable: an agent that edits a covered file cannot "finish"
+ * without re-verifying. Flaky flows are quarantined — surfaced, never gate-blocking — because one
+ * unexplained flake that blocks a merge destroys trust in the red. Pure decision; the CLI computes the
+ * inputs (git diff → affected → run artifacts + flake ledger) and maps `pass` to the exit code.
+ */
+export function gateDecision(input) {
+    const passing = new Set(input.passing);
+    const flaky = new Set(input.flaky ?? []);
+    const uncovered = [];
+    const quarantined = [];
+    for (const flow of input.affected) {
+        if (passing.has(flow))
+            continue;
+        if (flaky.has(flow))
+            quarantined.push(flow);
+        else
+            uncovered.push(flow);
+    }
+    // Downgrades and deleted coverage BLOCK. Flakiness is quarantined because a flake is not the agent's
+    // doing; a weakened or deleted assertion is — surfacing it without blocking would leave the gate
+    // trivially gameable, which is the exact failure this gate exists to prevent.
+    const downgraded = [...(input.downgraded ?? [])];
+    const deleted = [...(input.deleted ?? [])];
+    return {
+        pass: 0 === uncovered.length && 0 === downgraded.length && 0 === deleted.length,
+        uncovered,
+        quarantined,
+        downgraded,
+        deleted,
+    };
+}

package/dist/language/flows/decision.d.ts

@@ -0,0 +1,45 @@
+import { type FlowFile, type FlowReplayResult, type ReplayDecision, type SuiteVerdict, SuiteIsolation } from '@reticlehq/core';
+/**
+ * @param intentStatement the ledger's current wording, when the flow is bound to an intent row.
+ * Falls back to the copy on the flow file, which is what a flow saved before the link carries.
+ */
+export declare function buildDecision(result: FlowReplayResult, flow?: FlowFile, intentStatement?: string, 
+/** The flows this one invokes, already loaded — see `unverifiableReason`. */
+invoked?: ReadonlyMap<string, FlowFile>): ReplayDecision;
+/**
+ * Aggregate per-flow replays into one suite verdict — the autonomous loop's consolidated answer
+ * after a build: did anything break, and what's the prioritized fix list. Pure: pass the already
+ * decision-annotated replay results + their flows. Passing flows are counted; only failures carry
+ * detail (token-cheap), each with the actionable decision so the agent fixes without re-querying.
+ */
+/**
+ * Why a green replay still verified nothing, or undefined when it genuinely did.
+ *
+ * A flow with no steps, or one that asserts no observable consequence, replays green no matter what
+ * the app does — the grader already knows this at save time and says so. Counting it as `passed`
+ * turned that warning into "all 1 flow pass", which is a false green in the exact feature sold as
+ * the regression suite. Classified only when the flow file is available; never guessed.
+ */
+export declare function unverifiableReason(flow: FlowFile | undefined, 
+/**
+ * The flows this one invokes, already loaded.
+ *
+ * A composite asserts through what it RUNS. Without these it is graded on the one step it
+ * contains and reported `unverifiable` however thoroughly its sub-journeys check themselves —
+ * which is a warning that is right about the file and wrong about the journey, and the only ways
+ * to silence it are to duplicate assertions into every caller or to stop reading warnings.
+ */
+invoked?: ReadonlyMap<string, FlowFile>): string | undefined;
+/**
+ * @param knownRoutes every route the project has been seen to have — each flow's `startPath`,
+ * including the flows this run held back. Omit it when nothing is known; see `unreached`.
+ */
+export declare function buildSuiteVerdict(runs: ReadonlyArray<{
+    replay: FlowReplayResult;
+    flow?: FlowFile;
+}>, knownRoutes?: readonly string[], 
+/**
+ * How the flows were kept apart. Omitted by callers that have not been taught to say, and then
+ * nothing is claimed — an invented isolation would be worse than a missing one.
+ */
+isolation?: SuiteIsolation): SuiteVerdict;