@reticlehq/server 2.11.0 → 2.12.0

package/dist/events/predicate-schema.js

@@ -32,7 +32,22 @@ const PREDICATE_ALIASES = {
     // things to prove at once, so failing it is expensive at the worst moment.
     [PredicateKind.ALL_OF]: { of: 'predicates' },
     [PredicateKind.ANY_OF]: { of: 'predicates' },
+    // `of` on `not` for the same reason it is accepted on the composites above — an agent that learned
+    // the spelling one line earlier applies it to the third composite, and `not` was the one that
+    // rejected it. The refusal did name `predicate`, but naming a field still costs the round trip
+    // that produced no verdict, and the guess is unambiguous: `not` has exactly one child.
+    [PredicateKind.NOT]: { of: 'predicate' },
 };
+/**
+ * The word half the assertion world spells `kind`.
+ *
+ * A discriminated union rejects `{ type: "text", ... }` with "Invalid discriminator value" on a field
+ * the caller never wrote, so the reply reads as being about `kind` — which is absent — and never
+ * says the word `type`. Observed on a live drive as the first rung of a ladder: one field name
+ * learned per rejected call, each costing a verdict. No predicate kind declares a `type` field, so
+ * lifting it is unambiguous, and an explicit `kind` still wins.
+ */
+const KIND_SPELLING = 'type';
 /**
  * Element-query fields an agent writes FLAT on an `element` predicate instead of nested under
  * `query`. `reticle_query` takes exactly these at the top level, so an agent that has just located
@@ -144,11 +159,20 @@ export function describeResidual(element, field) {
                 : element.name;
     return `${element.role} "${element.name}" ${field}=${JSON.stringify(reading)}`;
 }
+/** `type` read as the discriminator when — and only when — `kind` is absent. */
+function renameKindSpelling(obj) {
+    if (obj['kind'] !== undefined || 'string' !== typeof obj[KIND_SPELLING])
+        return obj;
+    const out = { ...obj, kind: obj[KIND_SPELLING] };
+    delete out[KIND_SPELLING];
+    return out;
+}
 /** Rename known aliases before parse; an explicit canonical key always wins. */
 function applyPredicateAliases(input) {
     if (typeof input !== 'object' || null === input || Array.isArray(input))
         return input;
-    const obj = input;
+    const given = input;
+    const obj = renameKindSpelling(given);
     const kind = 'string' === typeof obj['kind'] ? obj['kind'] : '';
     const aliases = PREDICATE_ALIASES[kind];
     let out = obj;
@@ -269,6 +293,17 @@ function predicateUnion() {
             kind: z.literal(PredicateKind.SIGNAL),
             name: z.string().optional(),
             dataMatches: z.record(z.unknown()).optional(),
+            /**
+             * Exact number of matching signals since the action — presence becomes cardinality.
+             *
+             * The double-fire is the defect no state-only oracle can see: a handler wired twice fires
+             * the signal twice, the store ends up in the right shape either way, and a presence check
+             * is green on both. The wrong-name variant is the same blind spot from the other side — the
+             * intended signal fires once while a mistyped sibling fires alongside it, and only a count
+             * scoped to the matched name tells the two apart. Omit = presence (≥1); `0` asserts the
+             * signal never fired, which is a claim in its own right and NOT the same as omitting it.
+             */
+            count: z.number().int().nonnegative().optional(),
             since: z.number().optional(),
         })
             .strict(),
@@ -304,13 +339,89 @@ export const PredicateSchema = z.lazy(() => z.preprocess(applyPredicateAliases,
  * wall. Empty for a kind that is not in the union.
  */
 export function predicateFieldsFor(kind) {
+    const shape = shapeForKind(kind);
+    if (null === shape)
+        return [];
+    return Object.keys(shape).filter((field) => 'kind' !== field);
+}
+/**
+ * The union option for `kind`, or null when the kind is not one.
+ *
+ * One place that walks the union, so the field list and the nested lookup cannot disagree about
+ * which option a kind resolves to — and so adding a third reader is a call rather than a fourth
+ * copy of the same loop.
+ */
+function shapeForKind(kind) {
     for (const option of predicateUnion().options) {
         const literal = option.shape['kind'];
-        if (literal instanceof z.ZodLiteral && literal.value === kind) {
-            return Object.keys(option.shape).filter((field) => 'kind' !== field);
-        }
+        if (literal instanceof z.ZodLiteral && literal.value === kind)
+            return option.shape;
+    }
+    return null;
+}
+/**
+ * Is this tool parameter ACTUALLY the predicate union?
+ *
+ * Not a name check. `until` is overloaded on this surface — the act/assert family means a predicate
+ * by it, while reticle_observe / _network / _console mean a NUMBER, an upper cursor bound — so any
+ * caller keying on the word would treat a numeric parameter as a predicate and describe it to the
+ * agent as an object. Keying on the schema cannot make that mistake.
+ *
+ * Lives beside the schema because two callers now ask the question: the lean tool surface, which
+ * compacts these parameters, and `reticle_tools`, which spells their grammar out on request. Two
+ * spellings of "is this a predicate" is one chance for the surface and the grammar to disagree.
+ */
+export function isPredicateParam(schema) {
+    const inner = schema instanceof z.ZodOptional ? schema.unwrap() : schema;
+    return inner === PredicateSchema || inner === PredicateSchema.optional();
+}
+/**
+ * Every kind's fields, in one block an agent can write a predicate from.
+ *
+ * The tool surface advertises the KIND list and points at `reticle_tools` for the fields, because
+ * inlining the 12-variant recursive union in the declared JSON Schema costs thousands of characters
+ * per predicate parameter, re-sent every turn, to describe a grammar most calls use one variant of.
+ * That trade is right — but the pointer has to land somewhere, and it landed on a parameter
+ * description reading "same shape as reticle_assert". So the grammar was reachable from nothing, and
+ * an agent that could not find `route`'s fields fell back to a `text` check where a route check was
+ * meant: the weaker oracle, which is the expensive half of an undiscoverable grammar.
+ *
+ * Derived from the schema, like `predicateFieldsFor` and for the same reason: a hand-written grammar
+ * that drifts is worse than none, because the agent trusts it and retries into the same wall.
+ */
+export function predicateGrammar() {
+    const grammar = {};
+    for (const kind of Object.values(PredicateKind)) {
+        const nested = predicateNestedFieldsFor(kind);
+        grammar[kind] = predicateFieldsFor(kind)
+            .map((field) => {
+            const keys = nested[field];
+            return undefined === keys ? field : `${field} { ${keys.join(', ')} }`;
+        })
+            .join(', ');
     }
-    return [];
+    return grammar;
+}
+/**
+ * The keys of a field that is an object, once its wrappers are peeled. Empty for anything else.
+ *
+ * Exported so the wrapper handling is asserted against THIS function rather than through the
+ * rendered sentence. Reached only that way, a wrapper it fails to peel returns `[]`, the old
+ * message prints unchanged, and nothing reddens — a regression with no symptom.
+ *
+ * No top-level predicate field is currently declared behind a wrapper, so the real schema exercises
+ * none of these paths; that is exactly why they are worth a case each.
+ */
+export function nestedKeysOf(schema) {
+    if (undefined === schema)
+        return [];
+    const inner = unwrapSchema(schema);
+    // `instanceof z.ZodObject` narrows to ZodObject<any>, whose `.shape` is `any`. Name the shape
+    // type so the keys are read off something typed rather than laundering an `any` through
+    // Object.keys.
+    if (!(inner instanceof z.ZodObject))
+        return [];
+    return Object.keys(inner.shape);
 }
 /** Peel optional/nullable/default/effects wrappers off a field to reach the schema underneath. */
 function unwrapSchema(schema) {
@@ -341,24 +452,16 @@ function unwrapSchema(schema) {
  * list is worse than none, because the agent trusts it and retries into the same wall.
  */
 export function predicateNestedFieldsFor(kind) {
-    for (const option of predicateUnion().options) {
-        const literal = option.shape['kind'];
-        if (!(literal instanceof z.ZodLiteral) || literal.value !== kind)
+    const shape = shapeForKind(kind);
+    if (null === shape)
+        return {};
+    const nested = {};
+    for (const [field, schema] of Object.entries(shape)) {
+        if ('kind' === field)
             continue;
-        const nested = {};
-        for (const [field, schema] of Object.entries(option.shape)) {
-            if ('kind' === field)
-                continue;
-            const inner = unwrapSchema(schema);
-            // `instanceof z.ZodObject` narrows to ZodObject<any>, whose `.shape` is `any`. Name the shape
-            // type so the keys are read off something typed rather than laundering an `any` through
-            // Object.keys.
-            if (inner instanceof z.ZodObject) {
-                const shape = inner.shape;
-                nested[field] = Object.keys(shape);
-            }
-        }
-        return nested;
+        const keys = nestedKeysOf(schema);
+        if (0 < keys.length)
+            nested[field] = keys;
     }
-    return {};
+    return nested;
 }

package/dist/events/predicate.d.ts

@@ -19,6 +19,21 @@ export interface PredicateSession {
      * navigates simply omits it and route falls back to change-only, as before.
      */
     url?: string;
+    /**
+     * The document currently under observation, as the session derived it from its own event stream.
+     *
+     * Every oracle below that reads the window asks "what happened here", and a window is scoped by
+     * time and by ring-buffer capacity and by nothing else — so it can still hold the traffic, console
+     * output and signals of a page a full navigation or a reload has already thrown away. Answering a
+     * predicate with one of those is true about the bytes and false about the world, in whichever
+     * direction it lands: a stale event that satisfies the assertion is a false green, and one that
+     * refutes it is a false red.
+     *
+     * Optional, and undefined means nobody could say which document is current — `isSameDocument`
+     * treats absence as current on both sides, so the engine then behaves exactly as it did before this
+     * existed. Named to match `Session.currentDocumentId`, which is what supplies it in production.
+     */
+    currentDocumentId?: string | undefined;
     /**
      * Learned per-ref ambient-churn counts (real-time regions that churn with no action driving them).
      * The settle oracle drops events on learned-ambient refs so a chat/ticker page can still go quiet.

package/dist/events/predicate.js

@@ -1,4 +1,4 @@
-import { ElementState, PredicateKind, ReticleCommand, } from '@reticlehq/core';
+import { ElementState, PredicateKind, ReticleCommand, isSameDocument, } from '@reticlehq/core';
 import { log } from '../log.js';
 import { bindSpanContext } from '../trace.js';
 import { selectPath, capDepth } from '../session/state-select.js';
@@ -6,6 +6,7 @@ import { describeTestidMiss } from './testid-near-miss.js';
 import { predicateToExpectedLinks } from '../capsule/predicate-to-links.js';
 import { isAmbient, ambientKeyOf } from '../journal/ambient.js';
 import { evalRoute } from './predicate-route.js';
+import { describeSuperseded } from './observed-in-window.js';
 import { PredicateSchema, matchValue, evalNet, evalConsole, evalAnimation, evalSignal, evalSettled, residualQueryChecks, satisfiesResiduals, describeResidual, } from './predicate-eval.js';
 export { PredicateSchema, PredicateKind };
 /**
@@ -397,6 +398,23 @@ async function evalState(session, p) {
         evidence: { store: storeName, path: p.path, value: capDepth(selection.value, 1) },
     };
 }
+/**
+ * Oracles whose ONLY source of truth is the event window.
+ *
+ * Element, text and state read the page as it is right now, so supersession cannot reach them. Route
+ * is the deliberate omission: it has a second source — where the app is at this moment — and a
+ * reload is precisely the case it was given that fallback for, so emptying its window must not take
+ * the answer away.
+ */
+const WINDOW_ONLY_KINDS = new Set([
+    PredicateKind.NET,
+    PredicateKind.CONSOLE,
+    PredicateKind.ANIMATION,
+    PredicateKind.SIGNAL,
+    PredicateKind.SETTLED,
+]);
+/** Names the oracle that answered, in the same shape every other `assertion` here uses. */
+const SUPERSEDED_ASSERTION = 'window.evidence-superseded';
 /** The predicate's own event-time floor, if its kind carries one. */
 function predicateSince(predicate) {
     return 'since' in predicate && 'number' === typeof predicate.since ? predicate.since : 0;
@@ -411,7 +429,28 @@ diagnose = true) {
     // `since` from the act it just performed is scoping the assertion to that action's aftermath. It is
     // applied here, once, rather than in each eval: the floor means the same thing for every kind that
     // reads the event stream, and net/console re-applying it is a no-op.
-    const events = session.eventsSince(Math.max(since, predicateSince(predicate)));
+    const raw = session.eventsSince(Math.max(since, predicateSince(predicate)));
+    // Scoped ONCE, here, for the same reason the contradiction pass scopes at its own choke point:
+    // reasoning about a dead page's evidence is a defect in every oracle below rather than in whichever
+    // one happened to read it, and this is the single place they all take their window from.
+    const events = raw.filter((e) => isSameDocument(e.documentId, session.currentDocumentId));
+    const superseded = raw.length - events.length;
+    // An empty window was always allowed to mean "it did not happen"; that reading is only unsafe once
+    // supersession is what emptied it. Without this, dropping stale evidence would trade a wrong pass
+    // for a wrong FAILURE — and a failure names a component and sends an agent to fix working code.
+    // `inconclusive` is the established way to say "nothing was proven and nobody could have proven
+    // it", and `decideVerified` already reads it as UNKNOWN ahead of the failure clause.
+    if (superseded > 0 && 0 === events.length && WINDOW_ONLY_KINDS.has(predicate.kind)) {
+        const reason = describeSuperseded('observations', superseded);
+        return {
+            pass: false,
+            failureReason: reason,
+            inconclusive: reason,
+            observed: 'every observation in this window belongs to a document since replaced',
+            expected: `evidence recorded under the document now on screen for ${predicate.kind}`,
+            assertion: SUPERSEDED_ASSERTION,
+        };
+    }
     switch (predicate.kind) {
         case PredicateKind.ELEMENT:
             return evalElement(session, predicate.query, predicate.state, predicate.absent ?? false, diagnose);

package/dist/flows/coverage.d.ts

@@ -33,14 +33,6 @@ export interface Coverage {
 }
 /** The gate's outcome when the project has recorded no flows at all — not a pass, and not a failure. */
 export declare const NO_FLOWS = "no_flows";
-/**
- * What to do about it, since the empty state is otherwise indistinguishable from success.
- *
- * Names the TOOLS, not a `reticle record` CLI verb: this CLI does not dispatch one, and a suggestion
- * that errors is a second dead end on top of the first (see suggested-commands-exist.test.ts). Same
- * wording as the empty-suite verdict, which is the same situation reached from `reticle verify`.
- */
-export declare const NO_FLOWS_NOTE = "no flows recorded \u2014 nothing was checked. Record one with reticle_record { action: \"start\" }, then reticle_flow_save.";
 /** The gate's flow-coverage line. `pct` and `outcome` are mutually exclusive by construction. */
 export interface FlowCoverageReport {
     covered: number;

package/dist/flows/coverage.js

@@ -13,7 +13,7 @@ export const NO_FLOWS = 'no_flows';
  * that errors is a second dead end on top of the first (see suggested-commands-exist.test.ts). Same
  * wording as the empty-suite verdict, which is the same situation reached from `reticle verify`.
  */
-export const NO_FLOWS_NOTE = 'no flows recorded — nothing was checked. Record one with reticle_record { action: "start" }, then reticle_flow_save.';
+const NO_FLOWS_NOTE = 'no flows recorded — nothing was checked. Record one with reticle_record { action: "start" }, then reticle_flow_save.';
 /**
  * Report flow coverage so that an EMPTY suite cannot be read as a passing one.
  *

package/dist/flows/decision.d.ts

@@ -1,5 +1,9 @@
 import { type FlowFile, type FlowReplayResult, type ReplayDecision, type SuiteVerdict } from '@reticlehq/core';
-export declare function buildDecision(result: FlowReplayResult, flow?: FlowFile): ReplayDecision;
+/**
+ * @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): 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

package/dist/flows/decision.js

@@ -29,19 +29,45 @@ function whereInSource(step, flow) {
         : undefined;
     return source === undefined ? undefined : `${source.file}:${String(source.line)}`;
 }
-export function buildDecision(result, flow) {
+/**
+ * The business outcome that stopped being true, said before the mechanism that broke it.
+ *
+ * Order is the point. The intent is what makes a failure legible — a human or an agent reading
+ * "step 3 assertion failed" has to reconstruct the stakes — and the mechanical detail underneath is
+ * what makes it actionable. Dropping either one costs something, so the summary carries both.
+ */
+const INTENT_BROKEN_PREFIX = 'NO LONGER TRUE: ';
+/**
+ * What a report says when nothing declared what the flow is for.
+ *
+ * Never an intent derived from step names: a guessed goal reads as the product owner's words and an
+ * agent will act on it. The same rule as the source pointer — absence stays honest.
+ */
+const NO_INTENT_ON_PASS = 'no intent declared, so this proves the steps ran, not what they were for — declare one with reticle_intent.';
+const NO_INTENT_ON_FAIL = 'no intent declared, so this names the mechanism, not the stakes.';
+/** `<intent> — <mechanical>`, or the mechanical sentence plus the honest absence. */
+function withIntent(mechanical, statement) {
+    return statement === undefined
+        ? `${mechanical} — ${NO_INTENT_ON_FAIL}`
+        : `${INTENT_BROKEN_PREFIX}"${statement}" — ${mechanical}`;
+}
+/**
+ * @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 function buildDecision(result, flow, intentStatement) {
     const { name, status, steps } = result;
+    const intentSaid = intentStatement ?? flow?.intent;
     if (status === ReplayStatus.OK) {
         // Green — but is it green-for-the-right-reason? A flow that asserts no consequence can pass while
         // broken, so the honest next action is to add one.
         const grade = flow !== undefined ? classifyFlowAssertions(flow) : undefined;
         const verifiesOutcome = true === grade?.hasConsequenceAssertion;
-        const intent = flow?.intent;
         return {
             verdict: 'pass',
-            summary: intent !== undefined
-                ? `"${name}" passed — intent "${intent}" ${verifiesOutcome ? 'verified' : 'NOT asserted'}.`
-                : `"${name}" passed (${steps.length} steps).`,
+            summary: intentSaid !== undefined
+                ? `"${name}" passed — intent "${intentSaid}" ${verifiesOutcome ? 'verified' : 'NOT asserted'}.`
+                : `"${name}" passed (${steps.length} steps) — ${NO_INTENT_ON_PASS}`,
             nextAction: verifiesOutcome
                 ? 'none — the flow held and its consequence was observed.'
                 : 'add a consequence assertion (assert-signal / success-state) so this flow can fail when the feature breaks.',
@@ -58,7 +84,7 @@ export function buildDecision(result, flow) {
                 : undefined;
         return {
             verdict: 'drift',
-            summary: `"${name}" drifted at step ${step.step} (${step.anchor}).`,
+            summary: withIntent(`"${name}" drifted at step ${step.step} (${step.anchor}).`, intentSaid),
             whatChanged: drift.reason,
             ...(where !== undefined ? { whereInSource: where } : {}),
             ...(fix !== undefined ? { suggestedFix: fix } : {}),
@@ -72,7 +98,7 @@ export function buildDecision(result, flow) {
     const isSuccessOracle = step?.tool === SUCCESS_STEP_TOOL;
     return {
         verdict: 'fail',
-        summary: `"${name}" failed${step !== undefined ? ` at step ${step.step} (${step.anchor})` : ''}.`,
+        summary: withIntent(`"${name}" failed${step !== undefined ? ` at step ${step.step} (${step.anchor})` : ''}.`, intentSaid),
         whatChanged: message,
         ...(where !== undefined ? { whereInSource: where } : {}),
         nextAction: isSuccessOracle

package/dist/flows/flake.d.ts

@@ -43,8 +43,6 @@ export declare const FlakeFileSchema: z.ZodObject<{
         runs: number;
     }>;
 }>;
-/** Minimum unchanged-code replays before flakiness can be judged (too few = noise). */
-export declare const DEFAULT_MIN_FLAKE_RUNS = 5;
 export declare function emptyRecord(): FlakeRecord;
 /** Accrue one unchanged-code replay outcome. */
 export declare function recordOutcome(record: FlakeRecord, passed: boolean): FlakeRecord;

package/dist/flows/flake.js

@@ -14,7 +14,7 @@ export const FlakeFileSchema = z.object({
     flows: z.record(FlakeRecordSchema),
 });
 /** Minimum unchanged-code replays before flakiness can be judged (too few = noise). */
-export const DEFAULT_MIN_FLAKE_RUNS = 5;
+const DEFAULT_MIN_FLAKE_RUNS = 5;
 export function emptyRecord() {
     return { runs: 0, fails: 0 };
 }

package/dist/flows/flow-intent.d.ts

@@ -0,0 +1,52 @@
+import { type FlowFile, type InstrumentationGap } from '@reticlehq/core';
+import { IntentStore } from '../intent/intent-store.js';
+/** The ledger id a flow's own prose goal is declared under. */
+export declare function flowIntentId(flowName: string): string;
+/** The verdict that a replay of this flow, at this time, constitutes — what `provenBy` records. */
+export declare function flowReplayVerdictId(flowName: string, at: number): string;
+/**
+ * Promote a flow's prose goal into the ledger and stamp the id back onto the flow.
+ *
+ * The binding is attached only when the flow asserts an observable consequence, because that is the
+ * only case where replaying it green proves anything. A flow that asserts nothing leaves its intent
+ * `declared` — and `dischargeIntent` refuses to prove an unbound intent, so an assertion-free flow
+ * can never discharge one. That is the whole guard, and it is the ledger's own rule, not a new one.
+ *
+ * Returns the flow unchanged (and writes nothing) when there is no intent, so a flow file saved
+ * before any of this existed keeps its exact bytes.
+ */
+export declare function linkFlowIntent(store: IntentStore, flow: FlowFile): Promise<FlowFile>;
+/**
+ * The nudge a flow saved without an intent earns, or nothing.
+ *
+ * Every save path routes through here, so the three of them cannot drift into three different ways
+ * of saying the same thing. It says it in the vocabulary the instrumentation gaps already use — what
+ * is missing, what it costs, and the one change that closes it — because "nobody said what this is
+ * for" is the same finding `undeclared-change` makes about an edit, one artifact later.
+ *
+ * Deliberately generic. It names no step, no assertion and not even the flow, for the reason this
+ * file already gives twice: anything specific enough to identify the goal is specific enough to be
+ * read AS the goal. It also never fails the save — a flow with no intent is still far better than no
+ * flow, and a verification tool that refuses to record work is one people route around.
+ */
+export declare function flowIntentGap(flow: FlowFile): InstrumentationGap | undefined;
+/**
+ * What the ledger currently says this flow is for, or undefined when nothing declared it.
+ *
+ * Read from the ledger rather than from the flow file's own copy: the ledger is where an amendment
+ * lands, and a report that quotes the stale copy would be the two-vocabularies problem all over
+ * again — one sentence in review, a different one in the failure message.
+ */
+export declare function flowIntentStatement(store: IntentStore, flow: FlowFile): Promise<string | undefined>;
+/**
+ * Record that this replay proved the flow's intent. False when there was nothing to prove.
+ *
+ * Best-effort by construction: `IntentStore.discharge` returns false rather than throwing on an
+ * unknown or unbound id, because discharge runs off the back of a verdict and must never be the
+ * reason one fails to return.
+ */
+export declare function dischargeFlowIntent(store: IntentStore, flow: FlowFile, proof: {
+    verdictId: string;
+    grade: string;
+    at: number;
+}): Promise<boolean>;

package/dist/flows/flow-intent.js

@@ -0,0 +1,123 @@
+import { InstrumentationGapKind, instrumentationGap, } from '@reticlehq/core';
+import { IntentStore } from '../intent/intent-store.js';
+import { classifyFlowAssertions } from './flow-classify.js';
+/**
+ * The link between a saved flow and the intent ledger — what the flow is FOR.
+ *
+ * A replay used to report only in the language of the DOM: step 3 drifted, this assertion failed.
+ * True, actionable, and illegible — the reader still had to reconstruct what stopped working. The
+ * ledger in `.reticle/intent.json` already holds the other half (prose statements, declared → bound
+ * → proved, and the verdict that discharged each one), so a flow does not need its own notion of
+ * intent. It needs an id.
+ *
+ * Nothing here derives an intent from step names. A flow that declares none reports that it declares
+ * none — a guessed intent puts words in the product owner's mouth and an agent will act on them,
+ * which is strictly worse than the honest absence.
+ */
+/** Namespaced so a flow-declared intent never collides with one an agent declared by hand. */
+const FLOW_INTENT_ID_PREFIX = 'flow:';
+const FLOW_VERDICT_ID_PREFIX = 'flow_replay:';
+const ID_SEPARATOR = ':';
+/** The ledger id a flow's own prose goal is declared under. */
+export function flowIntentId(flowName) {
+    return `${FLOW_INTENT_ID_PREFIX}${flowName}`;
+}
+/** The verdict that a replay of this flow, at this time, constitutes — what `provenBy` records. */
+export function flowReplayVerdictId(flowName, at) {
+    return `${FLOW_VERDICT_ID_PREFIX}${flowName}${ID_SEPARATOR}${String(at)}`;
+}
+/**
+ * Which ledger row this flow answers to, or nothing.
+ *
+ * An explicit `intentId` wins, so a flow can discharge an intent that was declared before it existed.
+ * Otherwise the flow's own prose implies one. A flow with neither has no intent, and says so.
+ */
+function intentIdOf(flow) {
+    if (flow.intentId !== undefined)
+        return flow.intentId;
+    // TRIMMED, not merely defined. `intent: "   "` satisfied `!== undefined` and silenced the gap, so
+    // a flow whose stated goal is whitespace looked identical on disk to one somebody thought about.
+    //
+    // The worse direction of the two: this gap is the ONLY thing that would ever tell anyone the flow
+    // has no goal, so suppressing it wrongly means the flow replays for months and the day it goes red
+    // the report names the broken step and nothing else — the precise failure it was written to
+    // prevent. Found by probing the seam rather than reading it.
+    return undefined === flow.intent || '' === flow.intent.trim()
+        ? undefined
+        : flowIntentId(flow.name);
+}
+/**
+ * Promote a flow's prose goal into the ledger and stamp the id back onto the flow.
+ *
+ * The binding is attached only when the flow asserts an observable consequence, because that is the
+ * only case where replaying it green proves anything. A flow that asserts nothing leaves its intent
+ * `declared` — and `dischargeIntent` refuses to prove an unbound intent, so an assertion-free flow
+ * can never discharge one. That is the whole guard, and it is the ledger's own rule, not a new one.
+ *
+ * Returns the flow unchanged (and writes nothing) when there is no intent, so a flow file saved
+ * before any of this existed keeps its exact bytes.
+ */
+export async function linkFlowIntent(store, flow) {
+    const id = intentIdOf(flow);
+    if (id === undefined)
+        return flow;
+    if (flow.intent !== undefined) {
+        await store.declare([{ id, statement: flow.intent, surface: { flow: flow.name } }]);
+    }
+    if (classifyFlowAssertions(flow).hasConsequenceAssertion) {
+        await store.bind(id, { flow: flow.name });
+    }
+    return { ...flow, intentId: id };
+}
+/**
+ * The nudge a flow saved without an intent earns, or nothing.
+ *
+ * Every save path routes through here, so the three of them cannot drift into three different ways
+ * of saying the same thing. It says it in the vocabulary the instrumentation gaps already use — what
+ * is missing, what it costs, and the one change that closes it — because "nobody said what this is
+ * for" is the same finding `undeclared-change` makes about an edit, one artifact later.
+ *
+ * Deliberately generic. It names no step, no assertion and not even the flow, for the reason this
+ * file already gives twice: anything specific enough to identify the goal is specific enough to be
+ * read AS the goal. It also never fails the save — a flow with no intent is still far better than no
+ * flow, and a verification tool that refuses to record work is one people route around.
+ */
+export function flowIntentGap(flow) {
+    if (intentIdOf(flow) !== undefined)
+        return undefined;
+    return instrumentationGap(InstrumentationGapKind.NO_FLOW_INTENT, 'this flow declares no intent, so nothing on disk says what it is meant to prove', 'it will replay for months, and the day it goes red the report can only name the step that broke — not the thing that stopped being true — so whoever reads it has to reconstruct the goal from the steps before they can tell a real regression from a moved button');
+}
+/**
+ * What the ledger currently says this flow is for, or undefined when nothing declared it.
+ *
+ * Read from the ledger rather than from the flow file's own copy: the ledger is where an amendment
+ * lands, and a report that quotes the stale copy would be the two-vocabularies problem all over
+ * again — one sentence in review, a different one in the failure message.
+ */
+export async function flowIntentStatement(store, flow) {
+    const id = intentIdOf(flow);
+    if (id === undefined)
+        return undefined;
+    const found = (await store.read()).find((intent) => intent.id === id);
+    return found?.statement ?? flow.intent;
+}
+/**
+ * Record that this replay proved the flow's intent. False when there was nothing to prove.
+ *
+ * Best-effort by construction: `IntentStore.discharge` returns false rather than throwing on an
+ * unknown or unbound id, because discharge runs off the back of a verdict and must never be the
+ * reason one fails to return.
+ */
+export async function dischargeFlowIntent(store, flow, proof) {
+    const id = intentIdOf(flow);
+    if (id === undefined)
+        return false;
+    try {
+        return await store.discharge(id, proof);
+    }
+    catch {
+        // A ledger that cannot be written is a small problem; a verdict that never returns because of
+        // one is a large problem. The replay already succeeded — the proof is simply not recorded.
+        return false;
+    }
+}