@voltro/plugin-ai-flows 0.70.0 → 0.71.1

package/dist/index.d.ts

@@ -1,8 +1,10 @@
+import { AnyTool } from '@voltro/ai';
 import { AppContext } from '@voltro/runtime';
 import { ColumnBuilder } from '@voltro/database';
 import { ColumnDefinition } from '@voltro/database';
 import { Effect } from 'effect';
 import { FieldDefinitions } from '@voltro/database';
+import { GenerateTextOptions } from '@voltro/ai';
 import { ProviderConfig } from '@voltro/ai';
 import { Schema } from 'effect';
 import { Table } from '@voltro/database';
@@ -15,6 +17,10 @@ import { WorkflowInstance } from '@effect/workflow/WorkflowEngine';
 export declare interface AgentResolution {
     readonly system: string;
     readonly model: string;
+    /** Already authorized tools for this persona/run; never serialized into IR. */
+    readonly tools?: Record<string, AnyTool>;
+    /** Bound for this agent's model/tool loop, independent of the planner. Default 8. */
+    readonly maxSteps?: number;
 }
 
 /** `ai_flow_runs` — one execution. Reactive: the engine patches this row
@@ -33,6 +39,20 @@ export declare const aiFlowRunsTable: Table<"_voltro_ai_flow_runs", FieldDefinit
     readonly source: ColumnBuilder<string | null, "text", boolean>;
     /** Correlation + idempotency key (→ the workflow's idempotencyKey). */
     readonly requestId: ColumnBuilder<string, "text", boolean>;
+    /** Last observed admission answer, not current execution state. Null means
+     * no answer was recorded, not that submission did not reach the engine. */
+    readonly workflowStart: ColumnBuilder<{
+        readonly status: "dropped" | "skipped" | "running" | "succeeded" | "queued" | "replayed";
+        readonly id: string;
+        readonly executionId: string | null;
+        readonly workflowName: string;
+        readonly deferral?: {
+            readonly mode: string;
+            readonly retryAfterMs: number | null;
+            readonly dueAt: number | null;
+            readonly intentId: string | null;
+        } | undefined;
+    } | null, "json", boolean>;
     /** Brief values, keyed by `BriefField.key`. */
     readonly input: ColumnBuilder<Record<string, unknown> | null, "json", boolean>;
     /** The result bundle: `outputKey → value` (what the UI's result dialog reads). */
@@ -41,7 +61,7 @@ export declare const aiFlowRunsTable: Table<"_voltro_ai_flow_runs", FieldDefinit
     readonly steps: ColumnBuilder<readonly RunStep[] | null, "json", boolean>;
     readonly currentStep: ColumnBuilder<number, "integer", true>;
     readonly totalSteps: ColumnBuilder<number, "integer", true>;
-    /** The HITL answer, written by `respond`. */
+    /** The HITL answer projected by the engine after consuming its signal. */
     readonly humanResponse: ColumnBuilder<HumanResponse | null, "json", boolean>;
     /** Staged follow-up when the chain requires confirmation. */
     readonly chainPending: ColumnBuilder<ChainPending | null, "json", boolean>;
@@ -305,8 +325,8 @@ export declare type ConditionOp = typeof ConditionOp.Type;
  *  auto-stamped by the runtime. */
 export declare const createFlow: (ctx: AppContext, fields: Record<string, unknown>) => Effect.Effect<Readonly<Record<string, unknown>>, never, never>;
 
-/** Deterministic per-slot request id: same flow + same 15-min slot ⇒ same id. */
-export declare const cronRequestId: (flowRef: string, now: Date) => string;
+/** Tenant, flow and absolute minute identify one cadence submission. */
+export declare const cronRequestId: (flowRef: string, now: Date, tenantId: string | null) => string;
 
 /**
  * Declare a code-first flow. Normalizes to the Flow IR, validates its `{{ref}}`
@@ -342,9 +362,15 @@ export declare const deleteFlow: (ctx: AppContext, args: {
 export declare const describeCondition: (condition: StepCondition) => string;
 
 export declare interface EngineDeps {
-    /** Resolve an `agent` step's `agentRef` → system prompt + model. Absent →
-     *  agent steps with an `agentRef` fail with FlowCapabilityMissing. */
-    readonly resolveAgent?: (agentRef: string) => Effect.Effect<AgentResolution, FlowNotFound, unknown>;
+    /** Resolve an agent in the durable run's tenant, in deterministic steps AND
+     *  the agentic `run_agent` tool. Do not infer tenancy from the current subject:
+     *  a crash resume may run as system. Absent → FlowCapabilityMissing. */
+    readonly resolveAgent?: (agentRef: string, run: MediaRunContext) => Effect.Effect<AgentResolution, FlowNotFound, unknown>;
+    /** Additional tools for the agentic planner, resolved inside its durable step.
+     *  The original flow reference and durable tenant are scope, not authorization.
+     *  Enforce current access in this callback and the tools. Internal planner names
+     *  cannot be replaced. Deterministic agent tools belong to AgentResolution. */
+    readonly resolveTools?: (flowRef: string, run: MediaRunContext) => Effect.Effect<Record<string, AnyTool>, FlowCapabilityMissing, unknown>;
     /** Media generator for image/video/audio steps (`makeMediaGenerator` in
      *  `mediaAdapter.ts` is the @voltro/ai-backed implementation). */
     readonly generateMedia?: MediaGenerator;
@@ -555,6 +581,43 @@ declare const FlowNotFound_base: Schema.TaggedErrorClass<FlowNotFound, "FlowNotF
     message: typeof Schema.String;
 }>;
 
+/** No review-delivery confirmation. Unknown delivery may already have been consumed. */
+declare class FlowReviewDeliveryError extends FlowReviewDeliveryError_base {
+}
+
+declare const FlowReviewDeliveryError_base: Schema.TaggedErrorClass<FlowReviewDeliveryError, "FlowReviewDeliveryError", {
+    readonly _tag: Schema.tag<"FlowReviewDeliveryError">;
+} & {
+    runId: typeof Schema.String;
+    reason: Schema.Literal<["runtime-unavailable", "invalid-run", "invalid-response", "delivery-unknown"]>;
+    message: typeof Schema.String;
+}>;
+
+/** Bind the answer to the review actually displayed, not the latest waiting step. */
+export declare const FlowReviewInput: Schema.Struct<{
+    runId: typeof Schema.NonEmptyString;
+    stepIndex: Schema.filter<typeof Schema.Int>;
+    response: Schema.Struct<{
+        decision: Schema.optional<Schema.Literal<["approve", "reject"]>>;
+        value: Schema.optional<typeof Schema.String>;
+        text: Schema.optional<typeof Schema.String>;
+        respondedAt: Schema.optional<typeof Schema.String>;
+    }>;
+}>;
+
+export declare type FlowReviewInput = typeof FlowReviewInput.Type;
+
+/** Delivery accepted; consumption and the run's eventual outcome remain reactive state. */
+export declare const FlowReviewReceipt: Schema.Struct<{
+    runId: typeof Schema.NonEmptyString;
+    stepIndex: Schema.filter<typeof Schema.Int>;
+    executionId: typeof Schema.NonEmptyString;
+    eventId: typeof Schema.NonEmptyString;
+    status: Schema.Literal<["accepted"]>;
+}>;
+
+export declare type FlowReviewReceipt = typeof FlowReviewReceipt.Type;
+
 /** A flow run row could not be found. */
 declare class FlowRunNotFound extends FlowRunNotFound_base {
 }
@@ -601,6 +664,26 @@ export declare interface FlowSegment {
  */
 export declare const flowSegments: (steps: ReadonlyArray<FlowStep>) => ReadonlyArray<FlowSegment>;
 
+/** Submission evidence, separate from the flow run's execution status. */
+export declare const FlowStartReceipt: Schema.Struct<{
+    runId: typeof Schema.NonEmptyString;
+    requestId: typeof Schema.NonEmptyString;
+    admission: Schema.Struct<{
+        id: typeof Schema.String;
+        workflowName: typeof Schema.String;
+        executionId: Schema.NullOr<typeof Schema.String>;
+        status: Schema.Literal<["running", "succeeded", "queued", "dropped", "skipped", "replayed"]>;
+        deferral: Schema.optional<Schema.Struct<{
+            mode: typeof Schema.String;
+            dueAt: Schema.NullOr<typeof Schema.Number>;
+            retryAfterMs: Schema.NullOr<typeof Schema.Number>;
+            intentId: Schema.NullOr<typeof Schema.String>;
+        }>>;
+    }>;
+}>;
+
+export declare type FlowStartReceipt = typeof FlowStartReceipt.Type;
+
 /** Flow-definition lifecycle. */
 export declare const FlowStatus: Schema.Literal<["draft", "active", "archived"]>;
 
@@ -631,11 +714,11 @@ export declare const FlowStep: Schema.Struct<{
     }>, Schema.Struct<{
         from: Schema.Literal<["step"]>;
         ref: typeof Schema.String;
+        artifact: Schema.optional<Schema.filter<typeof Schema.Int>>;
     }>]>>>;
-    /** Allowed sub-agent id/name. The framework resolves a real id; any
-     *  legacy-numeric bridge stays in the consumer app's mapping. */
+    /** Allowed sub-agent id/name, resolved and authorized by the host. */
     agentRef: Schema.optional<typeof Schema.String>;
-    /** JSON Schema of the desired object (adapted to an Effect Schema at run). */
+    /** JSON Schema of the desired object, preserved and validated at run. */
     schema: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
     reviewMode: Schema.optional<Schema.Literal<["approve", "choice", "text"]>>;
     options: Schema.optional<Schema.Array$<Schema.Struct<{
@@ -719,6 +802,7 @@ export declare const flowStep: {
         description?: string;
         prompt: string;
         model?: string;
+        params?: FlowTextParams;
         outputKey?: string;
     } & StepControls) => FlowStepDraft;
     /** An image/video/audio generation. */
@@ -728,6 +812,7 @@ export declare const flowStep: {
         prompt: string;
         model?: string;
         params?: Record<string, unknown>;
+        mediaInputs?: MediaInputs;
         outputKey?: string;
     } & StepControls) => FlowStepDraft;
     /** Delegate to an allowed sub-agent (text-only). */
@@ -737,6 +822,7 @@ export declare const flowStep: {
         agentRef: string;
         prompt: string;
         model?: string;
+        params?: FlowTextParams;
         outputKey?: string;
     } & StepControls) => FlowStepDraft;
     /** Return a JSON object validated against a JSON Schema. */
@@ -746,6 +832,7 @@ export declare const flowStep: {
         prompt: string;
         schema: Record<string, unknown>;
         model?: string;
+        params?: FlowTextParams;
         outputKey?: string;
     } & StepControls) => FlowStepDraft;
     /** Free-text guidance — the interpolated prompt itself is the output. */
@@ -771,6 +858,8 @@ export declare const flowStep: {
 /** A step without its `id` — `defineFlow` assigns stable index-based ids. */
 export declare type FlowStepDraft = Omit<FlowStep, 'id'>;
 
+export declare type FlowTextParams = Pick<GenerateTextOptions, 'maxTokens' | 'temperature' | 'providerOptions'>;
+
 /** The recorded `app.config.ts` tunables. */
 export declare const getAiFlowsDefaults: () => AiFlowsDefaults;
 
@@ -795,7 +884,7 @@ export declare const HUMAN_REVIEW_TIMEOUT_ENV = "VOLTRO_AI_FLOW_HUMAN_REVIEW_TIM
  *  eventually settles instead of pinning a run forever. */
 export declare const HUMAN_REVIEW_TIMEOUT_HOURS_DEFAULT: number;
 
-/** The HITL answer, written by `respond`. */
+/** The HITL answer; the engine projects it after consuming the durable signal. */
 export declare const HumanResponse: Schema.Struct<{
     decision: Schema.optional<Schema.Literal<["approve", "reject"]>>;
     value: Schema.optional<typeof Schema.String>;
@@ -859,25 +948,6 @@ export declare const Json: Schema.Record$<typeof Schema.String, typeof Schema.Un
 
 export declare type Json = typeof Json.Type;
 
-/** A JSON-Schema node as stored on a `structured` step. */
-export declare type JsonSchemaNode = Record<string, unknown>;
-
-/**
- * Adapt a `structured` step's JSON Schema to the Effect `Schema` the engine
- * hands `generateObject`. An absent / unusable schema falls back to the open
- * record, so a step authored without one behaves exactly as before.
- *
- * ```ts
- * jsonSchemaToEffectSchema({
- *   type: 'object',
- *   properties: { title: { type: 'string' }, tags: { type: 'array', items: { type: 'string' } } },
- *   required: ['title'],
- * })
- * // ≡ Schema.Struct({ title: Schema.String, tags: Schema.optional(Schema.Array(Schema.String)) })
- * ```
- */
-export declare const jsonSchemaToEffectSchema: (jsonSchema: JsonSchemaNode | undefined) => Schema.Schema<unknown, unknown>;
-
 /** Launch a fresh run of a flow (by code name or row id). Validates the brief,
  *  creates the run row, and starts the durable `flow.run` workflow. */
 export declare const launchFlow: (ctx: AppContext, args: {
@@ -885,9 +955,20 @@ export declare const launchFlow: (ctx: AppContext, args: {
     input?: Record<string, unknown>;
     source?: "manual" | "cron";
 }) => Effect.Effect<{
-    runId: string;
-    requestId: string;
-    status: RunStatus;
+    readonly runId: string;
+    readonly requestId: string;
+    readonly admission: {
+        readonly status: "dropped" | "skipped" | "running" | "succeeded" | "queued" | "replayed";
+        readonly id: string;
+        readonly executionId: string | null;
+        readonly workflowName: string;
+        readonly deferral?: {
+            readonly mode: string;
+            readonly retryAfterMs: number | null;
+            readonly dueAt: number | null;
+            readonly intentId: string | null;
+        } | undefined;
+    };
 }, FlowNotFound | FlowBriefIncomplete, never>;
 
 /** All stored flows for the caller's tenant. */
@@ -898,7 +979,7 @@ export declare const listRegisteredFlows: () => ReadonlyArray<FlowIR>;
 
 /**
  * Build a `MediaGenerator` from a persistence adapter. Generates via @voltro/ai,
- * persists the artifact, and returns `{ url, costMicroUsd, requestId? }`. Any
+ * persists every artifact, and returns `{ artifacts, costMicroUsd }`. Any
  * failure (generation or persistence) surfaces as a typed `FlowCapabilityMissing`
  * so the engine records a clean per-step error.
  */
@@ -928,6 +1009,26 @@ export declare const MAX_STEPS_MAX = 100;
 
 export declare const MAX_STEPS_MIN = 1;
 
+/** One persisted media artifact. Storage identity is not a provider request ID.
+ *  Exactly one artifact per result has role `primary`; other roles are host-defined. */
+export declare const MediaArtifact: Schema.Struct<{
+    url: typeof Schema.NonEmptyString;
+    mediaType: typeof Schema.NonEmptyString;
+    role: typeof Schema.NonEmptyString;
+    storageRefId: Schema.optional<typeof Schema.NonEmptyString>;
+    providerMetadata: Schema.optional<typeof Schema.Unknown>;
+}>;
+
+export declare type MediaArtifact = typeof MediaArtifact.Type;
+
+export declare const MediaArtifacts: Schema.filter<Schema.Array$<Schema.Struct<{
+    url: typeof Schema.NonEmptyString;
+    mediaType: typeof Schema.NonEmptyString;
+    role: typeof Schema.NonEmptyString;
+    storageRefId: Schema.optional<typeof Schema.NonEmptyString>;
+    providerMetadata: Schema.optional<typeof Schema.Unknown>;
+}>>>;
+
 /** Host-supplied media generator for image/video/audio steps — `@voltro/ai`'s
  *  `generateImage` / `generateVideo` / `generateSpeech` plug in here via the
  *  app's server re-export (see `mediaAdapter.ts`). */
@@ -936,7 +1037,7 @@ export declare type MediaGenerator = (args: {
     readonly model?: string;
     readonly prompt: string;
     readonly params?: Record<string, unknown>;
-    readonly inputs?: Record<string, unknown>;
+    readonly inputs?: ResolvedMediaInputs;
     /** The run this artifact belongs to — pin persistence to `run.tenantId` rather
      *  than the current subject, so a system/bootstrap resume stores it correctly. */
     readonly run: MediaRunContext;
@@ -948,12 +1049,13 @@ export declare const MediaInputs: Schema.Record$<typeof Schema.String, Schema.Un
 }>, Schema.Struct<{
     from: Schema.Literal<["step"]>;
     ref: typeof Schema.String;
+    artifact: Schema.optional<Schema.filter<typeof Schema.Int>>;
 }>]>>;
 
 export declare type MediaInputs = typeof MediaInputs.Type;
 
-/** A media-input slot for a video `generate` step — either an uploaded URL or a
- *  reference to a prior step's output. Keyed by capability slot name
+/** A media-input slot — an absolute HTTP(S) uploaded URL or a reference to a
+ *  brief field/prior step's URL output. Keyed by capability slot name
  *  (`referenceImageUrl`, `lastFrameImageUrl`, `referenceVideoUrl`, …). */
 export declare const MediaInputSlot: Schema.Union<[Schema.Struct<{
     from: Schema.Literal<["upload"]>;
@@ -961,6 +1063,7 @@ export declare const MediaInputSlot: Schema.Union<[Schema.Struct<{
 }>, Schema.Struct<{
     from: Schema.Literal<["step"]>;
     ref: typeof Schema.String;
+    artifact: Schema.optional<Schema.filter<typeof Schema.Int>>;
 }>]>;
 
 export declare type MediaInputSlot = typeof MediaInputSlot.Type;
@@ -977,21 +1080,28 @@ export declare interface MediaPersist {
         data: Uint8Array | string;
         mediaType: string;
         run: MediaRunContext;
-    }) => Promise<StoredMedia>;
+    }) => Effect.Effect<StoredMedia, unknown, unknown>;
     /** Re-host a provider URL (StorageService.ingestUrl). If absent, a provider
      *  video URL is used as-is (no re-hosting). */
-    readonly ingestUrl?: (url: string, run: MediaRunContext) => Promise<StoredMedia>;
+    readonly ingestUrl?: (url: string, run: MediaRunContext) => Effect.Effect<StoredMedia, unknown, unknown>;
 }
 
-/** Media generation result (the host generator persists the artifact + returns
- *  a hosted URL). */
-export declare interface MediaResult {
-    readonly url: string;
-    readonly costMicroUsd?: number;
-    readonly requestId?: string;
-}
+export declare const MediaResult: Schema.Struct<{
+    artifacts: Schema.filter<Schema.Array$<Schema.Struct<{
+        url: typeof Schema.NonEmptyString;
+        mediaType: typeof Schema.NonEmptyString;
+        role: typeof Schema.NonEmptyString;
+        storageRefId: Schema.optional<typeof Schema.NonEmptyString>;
+        providerMetadata: Schema.optional<typeof Schema.Unknown>;
+    }>>>;
+    costMicroUsd: Schema.optional<Schema.filter<typeof Schema.Finite>>;
+    /** A provider/usage correlation only, never a storage reference. */
+    requestId: Schema.optional<typeof Schema.NonEmptyString>;
+}>;
 
-/** The run a media step executes within, resolved from the durable RUN ROW —
+export declare type MediaResult = typeof MediaResult.Type;
+
+/** The run an agent or media step executes within, resolved from the durable RUN ROW —
  *  not the caller subject. This is the difference between a normal call and a
  *  resume: a BOOTSTRAP/crash resume runs under a tenant-less `SYSTEM_SUBJECT`,
  *  so a host that persists artifacts per tenant cannot read the tenant from
@@ -999,7 +1109,7 @@ export declare interface MediaResult {
  *  under the old fallback, write into the wrong tenant. The engine reads the run
  *  row it already loads and hands the original tenant down here, so persistence
  *  continues in the right place on replay. */
-declare interface MediaRunContext {
+export declare interface MediaRunContext {
     readonly runId: string;
     /** The run's tenant as stamped when it was created, or `null` for a
      *  single-tenant app. Authoritative on resume, where the subject has none. */
@@ -1034,6 +1144,10 @@ export declare const registerFlow: (ir: FlowIR) => void;
 /** Test seam — forget the recorded tunables. */
 export declare const resetAiFlowsDefaults: () => void;
 
+declare const ResolvedMediaInputs: Schema.Record$<typeof Schema.String, Schema.filter<typeof Schema.String>>;
+
+declare type ResolvedMediaInputs = typeof ResolvedMediaInputs.Type;
+
 /**
  * Resolve a human step's park bound down the precedence ladder. Pure — the env
  * read is passed in so a test can drive it without touching `process.env`.
@@ -1068,26 +1182,37 @@ export declare const resolveMaxChainDepth: (deps?: {
     readonly env?: NodeJS.ProcessEnv;
 }) => number;
 
-/** Record a human's answer to a `waiting` run + signal the parked workflow to
- *  resume. The signal is addressed to THAT STEP's own durable deferred — one
- *  shared name meant a later review resolved with an earlier answer. */
-export declare const respondToFlow: (ctx: AppContext, args: {
-    runId: string;
-    response: HumanResponse;
-}) => Effect.Effect<{
-    runId: string;
-    stepIndex: number;
-}, FlowRunNotFound | FlowNotAwaitingResponse, never>;
+/** Deliver to the displayed review's actual workflow execution. The engine, not
+ *  this sender, projects the consumed answer into humanResponse. A lost delivery
+ *  acknowledgement is unknown, never a fabricated successful response. */
+export declare const respondToFlow: (ctx: AppContext, args: FlowReviewInput) => Effect.Effect<{
+    readonly status: "accepted";
+    readonly executionId: string;
+    readonly runId: string;
+    readonly eventId: string;
+    readonly stepIndex: number;
+}, FlowRunNotFound | FlowNotAwaitingResponse | FlowReviewDeliveryError, never>;
 
-/** Re-run a run from its first unfinished step. Reuses the SAME requestId so the
- *  workflow's idempotencyKey resolves to the same execution → journal replay
- *  resumes (deterministic runs skip already-succeeded steps). */
+/** Resubmit the persisted input under the same requestId. The returned admission
+ * decides whether anything started; a replay is not a new execution. Previous
+ * execution evidence stays intact until the executor actually changes it. */
 export declare const retryFlow: (ctx: AppContext, args: {
     runId: string;
 }) => Effect.Effect<{
-    runId: string;
-    requestId: string;
-    status: RunStatus;
+    readonly runId: string;
+    readonly requestId: string;
+    readonly admission: {
+        readonly status: "dropped" | "skipped" | "running" | "succeeded" | "queued" | "replayed";
+        readonly id: string;
+        readonly executionId: string | null;
+        readonly workflowName: string;
+        readonly deferral?: {
+            readonly mode: string;
+            readonly retryAfterMs: number | null;
+            readonly dueAt: number | null;
+            readonly intentId: string | null;
+        } | undefined;
+    };
 }, FlowRunNotFound, never>;
 
 export declare const ReviewMode: Schema.Literal<["approve", "choice", "text"]>;
@@ -1105,7 +1230,8 @@ export declare type ReviewOption = typeof ReviewOption.Type;
  * Evaluate every enabled flow's cadence against `now` and start a `flow.run` per
  * match. Returns the started request ids. Idempotent across replicas +
  * re-invocations within a slot (deterministic requestId + the run-row insert
- * tolerates the duplicate). Never throws — a single bad flow can't abort the tick.
+ * tolerates the duplicate). Candidate-read failures reject immediately. Per-flow
+ * failures are collected and reject after the remaining candidates are attempted.
  */
 export declare const runCadenceTick: (ctx: AppContext, now?: Date) => Promise<{
     readonly matched: number;
@@ -1150,6 +1276,14 @@ export declare const RunStep: Schema.Struct<{
     requestId: Schema.optional<typeof Schema.String>;
     /** Hosted media artifact URL (image/video/audio), via storage. */
     url: Schema.optional<typeof Schema.String>;
+    /** All media variants, including roles and storage references; url projects the primary artifact. */
+    artifacts: Schema.optional<Schema.filter<Schema.Array$<Schema.Struct<{
+        url: typeof Schema.NonEmptyString;
+        mediaType: typeof Schema.NonEmptyString;
+        role: typeof Schema.NonEmptyString;
+        storageRefId: Schema.optional<typeof Schema.NonEmptyString>;
+        providerMetadata: Schema.optional<typeof Schema.Unknown>;
+    }>>>>;
     /** Inline text output (rendered as markdown). */
     output: Schema.optional<Schema.Struct<{
         text: typeof Schema.String;
@@ -1182,6 +1316,7 @@ export declare interface RunStep {
     readonly costMicroUsd?: number | undefined;
     readonly requestId?: string | undefined;
     readonly url?: string | undefined;
+    readonly artifacts?: ReadonlyArray<MediaArtifact> | undefined;
     readonly output?: {
         readonly text: string;
     } | undefined;
@@ -1267,8 +1402,8 @@ export declare type Visibility = typeof Visibility.Type;
  * derive the step's signal name.
  *
  * Read from the LIVE TIMELINE the engine wrote when it parked (`steps[i].status
- * === 'waiting'`), with `currentStep` as the fallback for a row whose timeline
- * hasn't been written yet. Deliberately NOT re-resolved from the flow definition:
+ * === 'waiting'`). Missing or ambiguous identity refuses; neither currentStep
+ * nor zero is a substitute for an actual review. NOT re-resolved from the definition:
  * a definition edited mid-run would hand back a different plan than the one the
  * run's journal pinned, and the answer would be delivered to the wrong step.
  */