@reticlehq/server 2.11.0 → 2.13.0

package/dist/flows/flow-replay.js

@@ -1,4 +1,5 @@
 import { span } from '../trace.js';
+import { routePathOf } from '../events/predicate-route.js';
 import { AnchorKind, DriftReason, EventType, ReticleCommand, QueryBy, PredicateKind, } from '@reticlehq/core';
 import { asRecord, asString } from '../tools/tools-helpers.js';
 import { replayActionArgs, ambiguousTestidNote, queryRefs } from './replay.js';
@@ -198,8 +199,14 @@ function currentRoute(session) {
     if (last === undefined)
         return undefined;
     const data = last.data ?? {};
+    // The ROUTER's path. This field answers "which page did this step run on", and the document
+    // pathname is `/` on every page of a hash-routed app — so a whole desktop replay reported `/` for
+    // every step. Sixth place the same reading was wrong; see routePathOf.
     const pathname = asString(data['pathname']) ?? asString(data['to']);
-    return pathname !== undefined && pathname.length > 0 ? pathname : undefined;
+    if (pathname === undefined || 0 === pathname.length)
+        return undefined;
+    const routed = routePathOf(pathname, asString(data['hash']) ?? '');
+    return routed.length > 0 ? routed : undefined;
 }
 /** Pathname only (drop origin + query) so a net URL stays terse in the journey. */
 function trimUrl(url) {
@@ -294,7 +301,9 @@ async function runTestidStep(session, step, index, value, dynamic, confirmDanger
         act = await session.command(ReticleCommand.ACT, {
             ref,
             action: step.action ?? '',
-            args: replayActionArgs(step.args, confirmDangerous),
+            // `value` is the anchor's own name — the field this step types into — so a redacted fill can
+            // be supplied from RETICLE_SECRET_<FIELD> without the flow carrying the secret.
+            args: replayActionArgs(step.args, confirmDangerous, value),
         });
     }
     finally {

package/dist/flows/flow-step-runners.d.ts

@@ -30,6 +30,14 @@ export declare function runComponentStep(session: FlowReplaySession, step: FlowS
  */
 export declare function isDegradedAnchor(anchor: FlowAnchor): boolean;
 export declare function degradedStepResult(step: FlowStep, index: number, label: string): FlowStepResult;
+/**
+ * QUERY args for an element anchor — null when the anchor addresses no element.
+ *
+ * Exported for `arriveAtStartPath`, which has to ask "can step 1 resolve where we already are?"
+ * before deciding to navigate. Sharing this mapping rather than repeating it keeps that question and
+ * the step runner's own resolution asking the same thing of the same anchor.
+ */
+export declare function anchorQueryArgs(anchor: FlowAnchor): Record<string, unknown> | null;
 /**
  * Run an act_sequence step: resolve every sub-step's OWN anchor, then dispatch the whole thing as one
  * ACT_SEQUENCE — the same shape `replayProgram` already uses, so a recorded sequence and a saved one

package/dist/flows/flow-step-runners.js

@@ -181,8 +181,14 @@ export function degradedStepResult(step, index, label) {
         },
     };
 }
-/** QUERY args for an element anchor — null when the anchor addresses no element. */
-function anchorQueryArgs(anchor) {
+/**
+ * QUERY args for an element anchor — null when the anchor addresses no element.
+ *
+ * Exported for `arriveAtStartPath`, which has to ask "can step 1 resolve where we already are?"
+ * before deciding to navigate. Sharing this mapping rather than repeating it keeps that question and
+ * the step runner's own resolution asking the same thing of the same anchor.
+ */
+export function anchorQueryArgs(anchor) {
     if (anchor.kind === AnchorKind.TESTID)
         return { by: QueryBy.TESTID, value: anchor.value };
     if (anchor.kind === AnchorKind.COMPONENT)

package/dist/flows/flow-store-for-session.d.ts

@@ -0,0 +1,31 @@
+/**
+ * The flow store a SESSION's flows belong in.
+ *
+ * `deps.flows` is bound to the daemon's own root at construction, which is right only when the
+ * daemon happens to have been started in the project it is driving. A user-scoped MCP registration
+ * is the common case and the editor starts it wherever it likes, so "where the daemon was launched"
+ * and "which app is being verified" are usually different directories.
+ *
+ * This used to live inside flow-tools and was applied at exactly ONE of ten call sites. The result
+ * is the half-applied state `sessionRoot` warns about in its own comment, reached in practice:
+ *
+ *   - the HUD listed the daemon repo's flows while driving somebody else's app — Electron and Tauri
+ *     flows shown over a React dashboard, none of which existed in the checkout being verified
+ *   - `flow_replay` answered `flow_not_found` for a flow sitting on disk, because it looked in the
+ *     daemon's root while `reticle verify` (which roots itself at cwd) replayed the same flow fine
+ *   - and the two save paths disagreed with each other, so where a flow landed depended on which
+ *     tool wrote it
+ *
+ * Reported as "running the daemon from here but taking the directory from there", which is exactly
+ * what it was.
+ *
+ * Rebinding is cheap — a FlowStore is a filesystem port, a root and a clock — and the common case
+ * allocates nothing: when no resolver is wired, or it names the root already in use, `deps.flows` is
+ * returned unchanged.
+ */
+import { FlowStore } from './flows.js';
+import type { ToolDeps } from '../tools/tool-kit.js';
+export declare function flowsForSession(deps: ToolDeps, projectId: string | undefined): {
+    flows: FlowStore;
+    root: string;
+};

package/dist/flows/flow-store-for-session.js

@@ -0,0 +1,33 @@
+/**
+ * The flow store a SESSION's flows belong in.
+ *
+ * `deps.flows` is bound to the daemon's own root at construction, which is right only when the
+ * daemon happens to have been started in the project it is driving. A user-scoped MCP registration
+ * is the common case and the editor starts it wherever it likes, so "where the daemon was launched"
+ * and "which app is being verified" are usually different directories.
+ *
+ * This used to live inside flow-tools and was applied at exactly ONE of ten call sites. The result
+ * is the half-applied state `sessionRoot` warns about in its own comment, reached in practice:
+ *
+ *   - the HUD listed the daemon repo's flows while driving somebody else's app — Electron and Tauri
+ *     flows shown over a React dashboard, none of which existed in the checkout being verified
+ *   - `flow_replay` answered `flow_not_found` for a flow sitting on disk, because it looked in the
+ *     daemon's root while `reticle verify` (which roots itself at cwd) replayed the same flow fine
+ *   - and the two save paths disagreed with each other, so where a flow landed depended on which
+ *     tool wrote it
+ *
+ * Reported as "running the daemon from here but taking the directory from there", which is exactly
+ * what it was.
+ *
+ * Rebinding is cheap — a FlowStore is a filesystem port, a root and a clock — and the common case
+ * allocates nothing: when no resolver is wired, or it names the root already in use, `deps.flows` is
+ * returned unchanged.
+ */
+import { FlowStore } from './flows.js';
+export function flowsForSession(deps, projectId) {
+    const resolved = deps.artifactRootFor?.(projectId);
+    if (resolved === undefined || resolved.root === deps.reticleRoot) {
+        return { flows: deps.flows, root: deps.reticleRoot };
+    }
+    return { flows: new FlowStore(deps.fs, resolved.root, { now: deps.now }), root: resolved.root };
+}

package/dist/flows/flow-success.js

@@ -38,9 +38,21 @@ export function successLabel(success) {
 export function successToPredicate(success, dynamic) {
     const parts = [];
     if (success.signal !== undefined) {
-        parts.push(success.signalData !== undefined
-            ? { kind: PredicateKind.SIGNAL, name: success.signal, dataMatches: success.signalData }
-            : { kind: PredicateKind.SIGNAL, name: success.signal });
+        const signal = {
+            kind: PredicateKind.SIGNAL,
+            name: success.signal,
+        };
+        if (success.signalData !== undefined)
+            signal.dataMatches = success.signalData;
+        if (success.signalCount !== undefined) {
+            signal.count = success.signalCount;
+            // Same post-settle reasoning as net.count: the success waiter is wait-until-true, so an exact
+            // count is transiently satisfied the instant the FIRST matching signal fires — before a
+            // double-fire's duplicate arrives. Gating on `settled` forces the count to be read only after
+            // the app goes quiet, by which point the duplicate IS counted and the over-count fails.
+            parts.push({ kind: PredicateKind.SETTLED });
+        }
+        parts.push(signal);
     }
     if (success.net !== undefined) {
         const net = { kind: PredicateKind.NET };

package/dist/flows/flow-tools.js

@@ -5,8 +5,9 @@ import { FlowErrorCode, RecordedSaveError, ReplayStatus, } from '@reticlehq/core
 import { recordSuiteFlakes } from './suite-flakes.js';
 import { ReticleTool } from '../tools/tool-names.js';
 import { asNumber, asString } from '../tools/tools-helpers.js';
+import { workerCountSchema } from '../tools/numeric-bounds.js';
 import { log } from '../log.js';
-import { syncFlowToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
+import { cloudFetch, syncFlowToCloud, SyncOutcome } from '../cloud/cloud-sync.js';
 import { mapWithConcurrency, resolveConcurrency } from './parallel-suite.js';
 import { acquireLeasedSession } from '../tools/lease-tools.js';
 import { homedir } from 'node:os';
@@ -14,14 +15,15 @@ import { resolveProjectCloud } from '../cloud/cloud-config.js';
 import { buildSuiteVerdict } from './decision.js';
 import { classifyFlowAssertions } from './flow-classify.js';
 import { isValidFlowName, flowPath } from '../project/reticle-dir.js';
-import { FlowStore } from './flows.js';
+import {} from './flows.js';
+import { flowsForSession } from './flow-store-for-session.js';
 import { replayNamedFlow, flowErrorMessage, latestRecordedFlow, sessionProjectId, } from './flow-replay-run.js';
 import { persistAndSyncVerificationRun } from '../runs/verification-sync.js';
 import { runServerVerify } from './server-verify.js';
 import { healFlow } from './heal-run.js';
 export { replayNamedFlow } from './flow-replay-run.js';
 /**
- * Best-effort mirror of a just-saved flow to Reticle Cloud (only when logged in — both cloud env vars
+ * Best-effort mirror of a just-saved flow to Reticle (only when logged in — both cloud env vars
  * set). Fire-and-forget: resolves the config, POSTs via the platform fetch, and logs the outcome. Any
  * failure is swallowed so a network hiccup never affects the local save.
  */
@@ -30,7 +32,7 @@ async function syncSavedFlowToCloud(deps, flow, projectId) {
     const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
     if (null === cloud.config || !cloud.policy.flows)
         return; // not attached / flows disabled → local only
-    const result = await syncFlowToCloud(flow, cloud.config, projectId, (url, init) => fetch(url, init));
+    const result = await syncFlowToCloud(flow, cloud.config, projectId, cloudFetch);
     if (result.outcome !== SyncOutcome.SYNCED) {
         log('cloud-flow-sync-failed', { flow: flow.name, status: result.status, error: result.error });
     }
@@ -69,23 +71,16 @@ export function leaseFailureReplay(name, error) {
 /** Stand-in path for a flow whose name fails the path-segment guard — never a real join. */
 const INVALID_FLOW_NAME_PATH = '(invalid flow name — not a usable path)';
 /**
- * The flow store a SESSION's artifacts belong in, and the root it resolved to.
+ * How a save reports that nobody said what the flow is for.
  *
- * `deps.flows` is bound to the daemon's own root at construction, which is right only when the
- * daemon happens to have been started in the project it is driving. When a resolver is wired and it
- * names a different project, the write has to go there instead — so the store is rebound for this
- * call. Rebinding is cheap: a FlowStore is a filesystem port, a root and a clock.
- *
- * Returns `deps.flows` unchanged when nothing is wired or the roots already agree, so the common
- * case allocates nothing and behaves exactly as before.
+ * Declared once and shared by every save tool: an undeclared field is stripped from
+ * `structuredContent` by a schema-strict MCP client, so a save path that forgot this line would
+ * report the nudge to the unit tests and to nobody else.
  */
-function flowsForSession(deps, projectId) {
-    const resolved = deps.artifactRootFor?.(projectId);
-    if (resolved === undefined || resolved.root === deps.reticleRoot) {
-        return { flows: deps.flows, root: deps.reticleRoot };
-    }
-    return { flows: new FlowStore(deps.fs, resolved.root, { now: deps.now }), root: resolved.root };
-}
+const INTENT_GAP_FIELD = z
+    .unknown()
+    .optional()
+    .describe('Present ONLY when the flow was saved with nothing saying what it is for: { kind, missing, cost, fix }. The flow is on disk either way — this never blocks a save. Close it by saving again with `intent`, or by setting the flow file’s `intentId` to an intent already in the ledger. Nothing here is ever derived from the flow name, the steps or the assertions: a guessed goal reads as the author’s own words.');
 export const FLOW_TOOLS = [
     {
         name: ReticleTool.FLOW_SAVE,
@@ -97,7 +92,15 @@ export const FLOW_TOOLS = [
                 .describe('Alias for `flowName` (the name reticle_annotate uses).'),
             flowName: z
                 .string()
-                .describe('Name for the flow file (saved to .reticle/flows/<flowName>.json). Use again in reticle_flow{action:"load"} / reticle_flow_replay.'),
+                .describe('Which RECORDING to save — the name reticle_record{start} was called with. This is a lookup key, not the filename: pass `saveAs` to choose that.'),
+            saveAs: z
+                .string()
+                .optional()
+                .describe('Name for the flow file (.reticle/flows/<saveAs>.json), and the name reticle_flow{action:"load"} / reticle_flow_replay take. Omit to reuse the recording name.'),
+            intent: z
+                .string()
+                .optional()
+                .describe('What this flow is FOR, in prose: which user does what, and what should become true. Answer it here rather than in a second call. Without it the flow still saves, but the day it goes red the report can only name the step that broke, not the thing that stopped being true.'),
             sessionId: z
                 .string()
                 .optional()
@@ -124,6 +127,7 @@ export const FLOW_TOOLS = [
                 warning: z.string().optional(),
             })
                 .optional(),
+            intentGap: INTENT_GAP_FIELD,
             error: z.string().optional(),
             code: z.string().optional(),
         },
@@ -131,14 +135,44 @@ export const FLOW_TOOLS = [
             const name = asString(aliasParam(args, 'flowName', ['flow'])['flowName']) ?? '';
             const program = deps.recordings.getCompiled(name);
             if (program === undefined) {
+                /*
+                 * Name what DOES exist.
+                 *
+                 * `flowName` here is the RECORDING's name, while every other flow tool reads it as the name
+                 * to save AS — so recording `default` and saving as `sign-in` looks obviously right and
+                 * answers "no compiled recording by that name". The old message then said "record one
+                 * first", which is advice to repeat the step that just succeeded. Cost a real investigation
+                 * before the names were compared.
+                 */
+                const held = deps.recordings.compiled();
                 return Promise.resolve({
-                    error: flowErrorMessage(FlowErrorCode.NO_RECORDING),
+                    error: 0 === held.length
+                        ? flowErrorMessage(FlowErrorCode.NO_RECORDING)
+                        : `no recording named '${name}'. This is the name the RECORDING was made under, not ` +
+                            `the name to save it as — stopped and ready to save: ${held.map((n) => `'${n}'`).join(', ')}.`,
                     code: FlowErrorCode.NO_RECORDING,
                 });
             }
+            // The name to save AS, which is not the name looked up above.
+            //
+            // `flowName` selects the recording; a recording is named at `record{start}`, often `default`
+            // or whatever the drive began as. Every other flow tool reads a flow name as the thing you
+            // load and replay, so a caller naming their flow at save time had no way to do it and had to
+            // `mv` the file on disk. The error message below already had to explain this ambiguity; that
+            // it needed explaining is the bug (#698).
+            const saveAs = asString(args['saveAs']);
+            if (saveAs !== undefined && !isValidFlowName(saveAs)) {
+                return Promise.resolve({
+                    error: `'${saveAs}' is not a usable flow name — it becomes a filename under .reticle/flows/.`,
+                    code: FlowErrorCode.INVALID_NAME,
+                });
+            }
             // fold any structured annotations (expect/dynamic/success/intent) onto the saved flow.
+            // Keyed by the RECORDING name: annotations were left against the recording, not the file.
             const success = deps.annotations.success(name);
-            const intent = deps.annotations.intent(name);
+            // The inline argument wins over an annotation left from an earlier call: it is the more recent
+            // statement, and it is the one the author just typed.
+            const intent = asString(args['intent']) ?? deps.annotations.intent(name);
             const annotations = {
                 stepExpect: deps.annotations.stepExpect(name),
                 dynamic: deps.annotations.dynamic(name),
@@ -152,7 +186,8 @@ export const FLOW_TOOLS = [
             if (emptyRefusal !== undefined)
                 return Promise.resolve(emptyRefusal);
             const { flows, root } = flowsForSession(deps, projectId);
-            return flows.save(program, annotations, projectId).then(async (res) => {
+            const toSave = saveAs === undefined ? program : { ...program, name: saveAs };
+            return flows.save(toSave, annotations, projectId).then(async (res) => {
                 if (!res.ok)
                     return { error: flowErrorMessage(res.code), code: res.code };
                 deps.annotations.clear(name);
@@ -193,7 +228,10 @@ export const FLOW_TOOLS = [
         // received string") — caught driving the live demo.
         handler: (deps, args) => {
             const projectId = sessionProjectId(deps, asString(args['sessionId']));
-            return deps.flows.list(projectId).then((names) => ({
+            // The APP's flows, not the daemon's. Listing where the daemon was launched is what showed a
+            // React dashboard a HUD full of Electron and Tauri flows from an unrelated checkout.
+            const { flows: store, root } = flowsForSession(deps, projectId);
+            return store.list(projectId).then((names) => ({
                 // `list` deliberately returns invalid names so they are reported rather than silently
                 // dropped — but the declared outputSchema requires `path` on EVERY entry, and omitting it made
                 // a strict MCP client reject the whole listing (the agent then sees no flows at all, which is
@@ -201,7 +239,7 @@ export const FLOW_TOOLS = [
                 // gets an explanatory marker instead of a joined filesystem path, which is what must never
                 // happen for a traversal-shaped name.
                 flows: names.map((name) => isValidFlowName(name)
-                    ? { name, path: flowPath(deps.reticleRoot, name, projectId) }
+                    ? { name, path: flowPath(root, name, projectId) }
                     : { name, path: INVALID_FLOW_NAME_PATH }),
             }));
         },
@@ -350,8 +388,7 @@ export const FLOW_TOOLS = [
                 .array(z.string())
                 .optional()
                 .describe('Flow names to verify. Omit to verify every saved flow.'),
-            parallel: z
-                .number()
+            parallel: workerCountSchema
                 .optional()
                 .describe('Run this many flows at once, each in its own isolated leased browser context (needs the browser pool). Clamped to the pool capacity and the flow count. Omit for the sequential single-tab run.'),
             sessionId: z
@@ -380,7 +417,7 @@ export const FLOW_TOOLS = [
             const projectId = sessionProjectId(deps, sessionId);
             const requested = Array.isArray(args['names'])
                 ? args['names'].filter((n) => 'string' === typeof n)
-                : await deps.flows.list(projectId);
+                : await flowsForSession(deps, projectId).flows.list(projectId);
             // verify:server — hand the whole suite to the hosted runner; it records the verification itself.
             const cloud = await resolveProjectCloud(deps.fs, deps.reticleRoot, homedir(), process.env);
             const server = await runServerVerify(deps, cloud, sessionId, requested);
@@ -417,7 +454,9 @@ export const FLOW_TOOLS = [
                 const parallelRuns = await Promise.all(outcomes.map(async (o, i) => {
                     const name = requested[i] ?? '';
                     const replay = o.ok && o.value !== undefined ? o.value.replay : leaseFailureReplay(name, o.error);
-                    const loaded = await deps.flows.load(name, projectId).catch(() => null);
+                    const loaded = await flowsForSession(deps, projectId)
+                        .flows.load(name, projectId)
+                        .catch(() => null);
                     const flow = loaded !== null && loaded.ok ? loaded.value : undefined;
                     return flow === undefined ? { replay } : { replay, flow };
                 }));
@@ -441,7 +480,9 @@ export const FLOW_TOOLS = [
             for (const flowName of requested) {
                 const start = deps.now();
                 const replay = await replayNamedFlow(deps, { flowName, sessionId });
-                const loaded = await deps.flows.load(flowName, projectId).catch(() => null);
+                const loaded = await flowsForSession(deps, projectId)
+                    .flows.load(flowName, projectId)
+                    .catch(() => null);
                 const flow = loaded !== null && loaded.ok ? loaded.value : undefined;
                 runs.push(flow === undefined ? { replay } : { replay, flow });
                 timed.push({ replay, durationMs: deps.now() - start });
@@ -477,6 +518,10 @@ export const FLOW_TOOLS = [
                 .string()
                 .optional()
                 .describe('Override the flow name embedded in the recorded flow. Omit to use the recorder-assigned name.'),
+            intent: z
+                .string()
+                .optional()
+                .describe('What this flow is FOR, in prose: which user does what, and what should become true. The recorder captures clicks, not goals, so this is the only place the goal can come from. Without it the flow still saves, but the day it goes red the report can only name the step that broke.'),
             ...{
                 sessionId: z
                     .string()
@@ -491,6 +536,7 @@ export const FLOW_TOOLS = [
             stepCount: z.number().optional(),
             degraded: z.number().optional(),
             empty: z.boolean().optional(),
+            intentGap: INTENT_GAP_FIELD,
             error: z.string().optional(),
             code: z.string().optional(),
         },
@@ -504,16 +550,24 @@ export const FLOW_TOOLS = [
                 };
             }
             const override = asString(aliasParam(args, 'flowName', ['flow'])['flowName']);
-            const flow = override !== undefined ? { ...recorded.flow, name: override } : recorded.flow;
+            const intent = asString(args['intent']);
+            const flow = {
+                ...recorded.flow,
+                ...(override === undefined ? {} : { name: override }),
+                ...(intent === undefined ? {} : { intent }),
+            };
             // The store stamps the project into the file AND routes it to the per-project subdir (a shared
             // daemon serves many apps), so location and content agree from one source of truth.
             const emptyRecorded = emptyFlowRefusal(flow.steps.length, flow.name);
             if (emptyRecorded !== undefined)
                 return emptyRecorded;
-            const res = await deps.flows.saveFlow(flow, session.projectId);
+            // Resolved like every other path now. This save used to go to the daemon's root while the
+            // recorded-flow save resolved per session, so where a flow landed depended on which tool wrote
+            // it — and the pair that disagreed were the two ways to save the same thing.
+            const res = await flowsForSession(deps, session.projectId).flows.saveFlow(flow, session.projectId);
             if (!res.ok)
                 return { error: flowErrorMessage(res.code), code: res.code };
-            // If logged into Reticle Cloud, mirror the saved flow to the team's regression suite. Best-effort
+            // If logged in to Reticle, mirror the saved flow to the team's regression suite. Best-effort
             // and non-blocking: the flow is already on disk, so a sync failure never fails the save.
             void syncSavedFlowToCloud(deps, flow, session.projectId);
             // Return the SaveSummary as-is ({ name, stepCount, degraded, empty }) — the outputSchema

package/dist/flows/flows.d.ts

@@ -1,5 +1,5 @@
 import { FlowErrorCode } from '@reticlehq/core';
-import type { FlowAnchor, FlowExpect, FlowFile, FlowStep, HealChange } from '@reticlehq/core';
+import type { FlowAnchor, FlowExpect, FlowFile, FlowStep, HealChange, InstrumentationGap } from '@reticlehq/core';
 import type { CompiledProgram, RecordedStep } from './recordings.js';
 import type { FileSystemPort } from '../project/fs-port.js';
 /** A monotonic clock injected for createdAt — never call Date.now inside the store (rule 7). */
@@ -19,6 +19,14 @@ export declare function anchorForStep(args: Record<string, unknown>): {
     anchor: FlowAnchor;
     degraded: boolean;
 };
+/**
+ * What a redacted fill value is replaced WITH.
+ *
+ * Replaced, never dropped. Replay still needs a step there, and a flow that silently loses its
+ * password step drifts at sign-in forever with no explanation of why. The placeholder also tells a
+ * reader what to do: the value belongs in the environment, not in a file they are about to commit.
+ */
+export declare const REDACTED_FILL = "<redacted: supply at replay>";
 /**
  * Pure: map one normalized RecordedStep → FlowStep with a semantic anchor (+ degraded marker).
  * A ref-only (stable:false) step is recorded with a best-effort anchor and degraded:true —
@@ -30,6 +38,11 @@ interface SaveSummary {
     stepCount: number;
     degraded: number;
     empty: boolean;
+    /**
+     * Present only when the flow was saved with nothing saying what it is for. Never blocks the save,
+     * and absent the moment the flow carries prose or an `intentId`. See `flowIntentGap`.
+     */
+    intentGap?: InstrumentationGap;
 }
 /**
  * The structured annotations folded onto a flow at save time: per-step