@voltro/plugin-ai-flows 0.33.0 → 0.35.0

package/dist/index.d.ts

@@ -42,20 +42,18 @@ export declare const aiFlowRunsTable: Table<"_voltro_ai_flow_runs", FieldDefinit
     readonly currentStep: ColumnBuilder<number, "integer", true>;
     readonly totalSteps: ColumnBuilder<number, "integer", true>;
     /** The HITL answer, written by `respond`. */
-    readonly humanResponse: ColumnBuilder<{
-        readonly value?: string | undefined;
-        readonly text?: string | undefined;
-        readonly decision?: "approve" | "reject" | undefined;
-        readonly respondedAt?: string | undefined;
-    } | null, "json", boolean>;
+    readonly humanResponse: ColumnBuilder<HumanResponse | null, "json", boolean>;
     /** Staged follow-up when the chain requires confirmation. */
-    readonly chainPending: ColumnBuilder<{
-        readonly status: "pending" | "confirmed" | "dismissed";
-        readonly input: {
-            readonly [x: string]: unknown;
-        };
-        readonly flowRef: string;
-    } | null, "json", boolean>;
+    readonly chainPending: ColumnBuilder<ChainPending | null, "json", boolean>;
+    /**
+     * Why a declared `chainTo` did NOT start — a cycle, or the depth ceiling.
+     *
+     * A column rather than a log line, because the run row is what a user looks
+     * at: a chain that silently does not fire is indistinguishable from a chain
+     * that was never declared, and "the second flow never ran" is precisely the
+     * report this would otherwise generate.
+     */
+    readonly chainRefusal: ColumnBuilder<string | null, "text", boolean>;
     /** Accumulated cost in micro-USD (app view projects to €/cents). */
     readonly costMicroUsd: ColumnBuilder<number, "integer", true>;
     readonly durationMs: ColumnBuilder<number | null, "integer", boolean>;
@@ -79,6 +77,15 @@ export declare const aiFlowRunsTable: Table<"_voltro_ai_flow_runs", FieldDefinit
     readonly updatedBy: ColumnDefinition<string | null, "reference", boolean>;
 }, true, never>;
 
+/** Tunables an `aiFlowsPlugin({...})` call can set from `app.config.ts`. */
+export declare interface AiFlowsDefaults {
+    /** Park bound for a `human` step, in ms. `0` = wait forever. */
+    readonly humanReviewTimeoutMs?: number;
+    /** How many flows one `chainTo` chain may traverse. See
+     *  {@link MAX_CHAIN_DEPTH_DEFAULT}. */
+    readonly maxChainDepth?: number;
+}
+
 /**
  * The AI-Flows plugin. Install it in `app.config.ts` `plugins: [...]`. It
  * contributes the canonical `ai_flows` + `ai_flow_runs` tables plus the
@@ -94,6 +101,59 @@ export declare const aiFlowsPlugin: (options?: AiFlowsPluginOptions) => VoltroPl
 export declare interface AiFlowsPluginOptions {
     /** Namespace for this plugin's routes / inspect endpoints. Default `aiFlows`. */
     readonly alias?: string;
+    /**
+     * Contribute this plugin's tables via `extendSchema.tables`. Default `true`.
+     *
+     * Set `false` when your app ALREADY declares equivalent tables and you want to
+     * keep them — the seam this exists for. The plugin then contributes no DDL and
+     * the declarative differ never proposes its tables; everything else (routes,
+     * inspect, interceptors) is unchanged.
+     *
+     * **What you take over, exactly:** `_voltro_ai_flows` (definitions) and
+     * `_voltro_ai_flow_runs` (runs). The retention sweep registered below still
+     * targets `_voltro_ai_flow_runs` by name, so your table inherits the same TTL
+     * — which is the intent, but say so to whoever owns that table.
+     *
+     * It is not offered on every plugin, and the omissions are deliberate rather
+     * than unfinished: a `tables: false` that quietly disables a table carrying an
+     * AUTHORIZATION or SAFETY decision — the SAML replay cache, SCIM provisioning
+     * state, billing's usage counters, cdc-out's outbox — is a security regression
+     * shipped as an ergonomics feature. Those plugins need a named store seam
+     * first, not a boolean.
+     */
+    readonly tables?: boolean;
+    /**
+     * How long a `human` step parks awaiting its review before the run fails, in
+     * ms. Default 7 days (`VOLTRO_AI_FLOW_HUMAN_REVIEW_TIMEOUT_HOURS` overrides at
+     * deploy time); `0` = wait forever. A flow's `humanTimeoutMs` and a step's own
+     * `timeoutMs` both outrank this.
+     */
+    readonly humanReviewTimeoutMs?: number;
+    /**
+     * How long a FINISHED flow run is kept, in ms. Default 90 days
+     * (`VOLTRO_AI_FLOW_RUNS_TTL_HOURS`).
+     *
+     * `_voltro_ai_flow_runs` stores every step's full output plus review payloads
+     * and grows with traffic, so it is registered with the framework retention
+     * sweep like every other run-family table. Two properties of that policy are
+     * deliberate:
+     *
+     * - **Only TERMINAL runs are swept.** The predicate is status-aware
+     *   (`succeeded | failed | cancelled`), so a run parked on a human review
+     *   survives regardless of age — a plain time-TTL would delete the pending
+     *   approvals this plugin exists to support.
+     * - **Media artifacts are NOT swept with the row.** A run's steps carry hosted
+     *   URLs whose blobs belong to the storage plugin; deleting the row orphans
+     *   them. Keep this TTL at or above the app's own media-purge window, or purge
+     *   by run id before the row ages out.
+     */
+    readonly runsTtlMs?: number;
+    /**
+     * Ceiling on rows ONE inspect call may return (`/flows`, `/runs`). Default
+     * 200. A run row carries every step's full output, so the page size is a real
+     * response-size knob, not a formality.
+     */
+    readonly inspectPageMax?: number;
 }
 
 /** `ai_flows` — a reusable flow DEFINITION (the data front door persists these;
@@ -115,33 +175,12 @@ export declare const aiFlowsTable: Table<"_voltro_ai_flows", FieldDefinitions<{
     /** The ordered plan (`FlowStep[]`); null ≡ empty. */
     readonly steps: ColumnBuilder<readonly FlowStep[] | null, "json", boolean>;
     /** The launch-form brief (`BriefField[]`). */
-    readonly inputSchema: ColumnBuilder<readonly {
-        readonly key: string;
-        readonly type: "number" | "boolean" | "text" | "textarea";
-        readonly required?: boolean | undefined;
-        readonly label: string;
-        readonly placeholder?: string | undefined;
-    }[] | null, "json", boolean>;
-    readonly chainTo: ColumnBuilder<{
-        readonly flowRef: string;
-        readonly mappings: readonly {
-            readonly sourceKey: string;
-            readonly targetKey: string;
-        }[];
-        readonly requireConfirmation?: boolean | undefined;
-    } | null, "json", boolean>;
-    readonly cadence: ColumnBuilder<{
-        readonly frequency?: "weekly" | "monthly" | undefined;
-        readonly repeats: readonly number[];
-        readonly intervalWeeks?: number | undefined;
-        readonly anchorDate?: string | undefined;
-        readonly weekOfMonth?: 1 | 2 | 3 | 4 | "last" | undefined;
-        readonly hour?: number | undefined;
-        readonly minute?: 0 | 15 | 30 | 45 | undefined;
-        readonly defaultInput?: {
-            readonly [x: string]: unknown;
-        } | undefined;
-    } | null, "json", boolean>;
+    readonly inputSchema: ColumnBuilder<readonly BriefField[] | null, "json", boolean>;
+    readonly chainTo: ColumnBuilder<FlowChain | null, "json", boolean>;
+    readonly cadence: ColumnBuilder<FlowCadence | null, "json", boolean>;
+    /** Flow-wide park bound for `human` steps, in ms (a step's own `timeoutMs`
+     *  wins). Null → the plugin default. `0` = wait forever. */
+    readonly humanTimeoutMs: ColumnBuilder<number | null, "integer", boolean>;
     /** Master on/off — gates scheduling. */
     readonly isEnabled: ColumnBuilder<boolean, "boolean", true>;
     readonly metadata: ColumnBuilder<Record<string, unknown> | null, "json", boolean>;
@@ -177,7 +216,17 @@ export declare const BriefField: Schema.Struct<{
     placeholder: Schema.optional<typeof Schema.String>;
 }>;
 
-export declare type BriefField = typeof BriefField.Type;
+/** An INTERFACE for the same reason as {@link FlowStep} — it is reached from an
+ *  exported table (`aiFlows.inputSchema`), so an alias to a mapped type gets
+ *  expanded structurally into the api report, in an order that is not stable
+ *  across build scopes. The `Equals` pin below fails to compile on any drift. */
+export declare interface BriefField {
+    readonly key: string;
+    readonly label: string;
+    readonly type: 'text' | 'textarea' | 'number' | 'boolean';
+    readonly required?: boolean | undefined;
+    readonly placeholder?: string | undefined;
+}
 
 /**
  * Build the `flow.run` executor over a live `AppContext` + injected capabilities.
@@ -221,7 +270,12 @@ export declare const ChainPending: Schema.Struct<{
     status: Schema.Literal<["pending", "confirmed", "dismissed"]>;
 }>;
 
-export declare type ChainPending = typeof ChainPending.Type;
+/** An INTERFACE — reached from `aiFlowRuns.chainPending`; see {@link BriefField}. */
+export declare interface ChainPending {
+    readonly flowRef: string;
+    readonly input: Json;
+    readonly status: 'pending' | 'confirmed' | 'dismissed';
+}
 
 export declare const clampMaxSteps: (n: number | null | undefined) => number;
 
@@ -231,6 +285,11 @@ export declare const clearRegistry: () => void;
 /** Every `{{ref}}` name referenced in `text` (order-preserving, may repeat). */
 export declare const collectRefs: (text: string) => ReadonlyArray<string>;
 
+/** The comparison a `when:` performs. */
+export declare const ConditionOp: Schema.Literal<["truthy", "falsy", "eq", "neq", "contains"]>;
+
+export declare type ConditionOp = typeof ConditionOp.Type;
+
 /** Create a flow row. Generates an id when absent; tenant/audit columns are
  *  auto-stamped by the runtime. */
 export declare const createFlow: (ctx: AppContext, fields: Record<string, unknown>) => Effect.Effect<Readonly<Record<string, unknown>>, never, never>;
@@ -257,6 +316,9 @@ export declare interface DefineFlowInput {
     };
     readonly chain?: FlowChain;
     readonly cadence?: FlowCadence;
+    /** Flow-wide park bound for every `human` step that sets no `timeoutMs` of its
+     *  own, in ms. `0` = wait forever. */
+    readonly humanTimeoutMs?: number;
 }
 
 /** Hard-delete a flow row by id. Returns whether a row was removed. */
@@ -264,11 +326,16 @@ export declare const deleteFlow: (ctx: AppContext, args: {
     id: string;
 }) => Effect.Effect<boolean, never, never>;
 
+/** A one-line rendering for the run timeline and the editor preview. Exported
+ *  so the reason a step was skipped is the SAME sentence in both places. */
+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>;
-    /** Media generator for image/video/audio steps (task #31 plugs in here). */
+    /** Media generator for image/video/audio steps (`makeMediaGenerator` in
+     *  `mediaAdapter.ts` is the @voltro/ai-backed implementation). */
     readonly generateMedia?: MediaGenerator;
     /** Fallback model per modality when a step omits `model`. */
     readonly defaultModels?: {
@@ -288,11 +355,39 @@ export declare interface EngineDeps {
     /** Long-term-memory prefix prepended to the orchestrator system prompt (wire
      *  to the app's ai_user_memories). Best-effort. */
     readonly memoryPrefix?: (ownerId: string | null) => Effect.Effect<string, never, unknown>;
+    /** Default park bound for `human` steps in ms, for flows that set none. Sits
+     *  between the flow's own `humanTimeoutMs` and the `aiFlowsPlugin({...})`
+     *  option / `VOLTRO_AI_FLOW_HUMAN_REVIEW_TIMEOUT_HOURS` (see `defaults.ts`).
+     *  `0` = wait forever. */
+    readonly humanReviewTimeoutMs?: number;
+    /** How many flows one `chainTo` chain may traverse, INCLUDING the flow that
+     *  started it. Sits between nothing and the `aiFlowsPlugin({...})` option /
+     *  `VOLTRO_AI_FLOW_MAX_CHAIN_DEPTH` (see `defaults.ts`). A cycle is refused
+     *  separately and cannot be raised by this number. */
+    readonly maxChainDepth?: number;
 }
 
+/**
+ * Evaluate `condition` against a run context.
+ *
+ * A condition on a ref the context does not carry evaluates as ABSENT — false
+ * for `truthy`/`eq`/`contains`, true for `falsy`/`neq`. That asymmetry is the
+ * honest reading of "the producing step did not run", and it is why
+ * `validateFlow` refuses a dangling ref at registration: at run time, a typo and
+ * a genuinely-skipped producer are indistinguishable here.
+ */
+export declare const evaluateCondition: (condition: StepCondition, context: Readonly<Record<string, unknown>>) => boolean;
+
 /** The canonical name the launch action starts + the app re-export registers. */
 export declare const FLOW_RUN_WORKFLOW = "flow.run";
 
+/** Deploy-time override for {@link FLOW_RUNS_TTL_HOURS_DEFAULT}, in hours. */
+export declare const FLOW_RUNS_TTL_ENV = "VOLTRO_AI_FLOW_RUNS_TTL_HOURS";
+
+/** Framework default retention for `_voltro_ai_flow_runs`: 90 days of finished
+ *  runs. Only TERMINAL runs are swept — see `index.ts`. */
+export declare const FLOW_RUNS_TTL_HOURS_DEFAULT: number;
+
 /** A required brief field was blank at launch. */
 declare class FlowBriefIncomplete extends FlowBriefIncomplete_base {
 }
@@ -322,7 +417,25 @@ export declare const FlowCadence: Schema.Struct<{
     defaultInput: Schema.optional<Schema.Record$<typeof Schema.String, typeof Schema.Unknown>>;
 }>;
 
-export declare type FlowCadence = typeof FlowCadence.Type;
+/**
+ * An INTERFACE — reached from `aiFlows.cadence`; see {@link BriefField}.
+ *
+ * This one is not hypothetical: a single-package `api:report` and a
+ * full-monorepo build emitted `hour`/`minute` in DIFFERENT positions inside the
+ * structurally-expanded alias, so the api-surface gate rejected a file nobody
+ * had touched, showing the same members moving. That is the exact failure
+ * {@link FlowStep}'s comment describes.
+ */
+export declare interface FlowCadence {
+    readonly frequency?: 'weekly' | 'monthly' | undefined;
+    readonly repeats: ReadonlyArray<number>;
+    readonly intervalWeeks?: number | undefined;
+    readonly anchorDate?: string | undefined;
+    readonly weekOfMonth?: 1 | 2 | 3 | 4 | 'last' | undefined;
+    readonly hour?: number | undefined;
+    readonly minute?: 0 | 15 | 30 | 45 | undefined;
+    readonly defaultInput?: Json | undefined;
+}
 
 /** A generation step required a capability the host did not provide (e.g. a
  *  media modality with no configured generator, or storage for the artifact). */
@@ -347,7 +460,15 @@ export declare const FlowChain: Schema.Struct<{
     requireConfirmation: Schema.optional<typeof Schema.Boolean>;
 }>;
 
-export declare type FlowChain = typeof FlowChain.Type;
+/** An INTERFACE — reached from `aiFlows.chainTo`; see {@link BriefField}. */
+export declare interface FlowChain {
+    readonly flowRef: string;
+    readonly mappings: ReadonlyArray<{
+        readonly targetKey: string;
+        readonly sourceKey: string;
+    }>;
+    readonly requireConfirmation?: boolean | undefined;
+}
 
 /** The raw flow definition either front door supplies before normalization.
  *  Optional fields tolerate explicit `undefined` (row reads produce it). */
@@ -361,6 +482,7 @@ export declare interface FlowDefinitionInput {
     readonly orchestratorInstructions?: string | null | undefined;
     readonly chain?: FlowChain | null | undefined;
     readonly cadence?: FlowCadence | null | undefined;
+    readonly humanTimeoutMs?: number | null | undefined;
 }
 
 /** The single representation the engine interprets, from either front door. */
@@ -376,6 +498,10 @@ export declare interface FlowIR {
     };
     readonly chain?: FlowChain;
     readonly cadence?: FlowCadence;
+    /** Flow-wide default for a `human` step's park bound, in ms. A step's own
+     *  `timeoutMs` wins; absent here too → the engine/plugin default. `0` = wait
+     *  forever. */
+    readonly humanTimeoutMs?: number;
 }
 
 /** A lifecycle event the host can turn into a notification (best-effort). */
@@ -436,8 +562,34 @@ export declare interface FlowRunPayload {
     readonly input: Record<string, unknown>;
     readonly source: 'manual' | 'cron';
     readonly requestId: string;
+    readonly chainPath?: ReadonlyArray<string> | undefined;
+}
+
+/** One unit of execution: a single step, or a set that runs concurrently. */
+export declare interface FlowSegment {
+    /** `undefined` for an ungrouped single step. */
+    readonly group?: string | undefined;
+    /** The steps in this segment, with their ORIGINAL indices — the durable step
+     *  name and the timeline slot both key off the index, so it travels. */
+    readonly steps: ReadonlyArray<{
+        readonly index: number;
+        readonly step: FlowStep;
+    }>;
 }
 
+/**
+ * Split a step list into execution segments.
+ *
+ * Only CONSECUTIVE steps sharing a group name form a segment. A group that
+ * reappears after an interruption forms a SECOND segment — which is almost
+ * certainly not what the author meant, so `validateFlow` refuses it rather than
+ * letting this function silently produce two sequential fan-outs from what reads
+ * like one. This function stays permissive on purpose: it is used by the
+ * validator, and a validator whose input has already been sanitised cannot
+ * report on it.
+ */
+export declare const flowSegments: (steps: ReadonlyArray<FlowStep>) => ReadonlyArray<FlowSegment>;
+
 /** Flow-definition lifecycle. */
 export declare const FlowStatus: Schema.Literal<["draft", "active", "archived"]>;
 
@@ -479,6 +631,29 @@ export declare const FlowStep: Schema.Struct<{
         value: typeof Schema.String;
         label: typeof Schema.String;
     }>>>;
+    /** Gate this step on a prior value. Absent → the step always runs. A step
+     *  whose condition is false is SKIPPED, not failed: it produces no output, so
+     *  anything referencing its `outputKey` sees an absent value. */
+    when: Schema.optional<Schema.Struct<{
+        ref: typeof Schema.String;
+        op: Schema.Literal<["truthy", "falsy", "eq", "neq", "contains"]>;
+        value: Schema.optional<typeof Schema.Unknown>;
+    }>>;
+    /**
+     * Fan-out group. CONSECUTIVE steps sharing a group name run CONCURRENTLY,
+     * each still journaled as its own durable step.
+     *
+     * Steps in one group may not reference each other's outputs — they have no
+     * order between them — and `validateFlow` refuses a flow that tries. A `human`
+     * step may not join a group either: it suspends the whole workflow, which is
+     * not a thing one branch of a fan-out can do.
+     */
+    group: Schema.optional<typeof Schema.String>;
+    /** `human` step only — how long the run parks awaiting this review before it
+     *  fails, in milliseconds. Omitted → the flow's `humanTimeoutMs`, then the
+     *  engine/plugin default (see `resolveHumanReviewTimeoutMs`). `0` means WAIT
+     *  FOREVER (the park is slot-free, so an unbounded wait costs no worker). */
+    timeoutMs: Schema.optional<typeof Schema.Number>;
 }>;
 
 /**
@@ -519,6 +694,9 @@ export declare interface FlowStep {
     readonly schema?: Json | undefined;
     readonly reviewMode?: ReviewMode | undefined;
     readonly options?: ReadonlyArray<ReviewOption> | undefined;
+    readonly when?: StepCondition | undefined;
+    readonly group?: string | undefined;
+    readonly timeoutMs?: number | undefined;
 }
 
 /** Typed builders for each step kind — terser + safer than hand-writing the
@@ -531,7 +709,7 @@ export declare const flowStep: {
         prompt: string;
         model?: string;
         outputKey?: string;
-    }) => FlowStepDraft;
+    } & StepControls) => FlowStepDraft;
     /** An image/video/audio generation. */
     media: (modality: Modality, o: {
         title?: string;
@@ -540,7 +718,7 @@ export declare const flowStep: {
         model?: string;
         params?: Record<string, unknown>;
         outputKey?: string;
-    }) => FlowStepDraft;
+    } & StepControls) => FlowStepDraft;
     /** Delegate to an allowed sub-agent (text-only). */
     agent: (o: {
         title?: string;
@@ -549,7 +727,7 @@ export declare const flowStep: {
         prompt: string;
         model?: string;
         outputKey?: string;
-    }) => FlowStepDraft;
+    } & StepControls) => FlowStepDraft;
     /** Return a JSON object validated against a JSON Schema. */
     structured: (o: {
         title?: string;
@@ -558,15 +736,16 @@ export declare const flowStep: {
         schema: Record<string, unknown>;
         model?: string;
         outputKey?: string;
-    }) => FlowStepDraft;
+    } & StepControls) => FlowStepDraft;
     /** Free-text guidance — the interpolated prompt itself is the output. */
     note: (o: {
         title?: string;
         description?: string;
         prompt: string;
         outputKey?: string;
-    }) => FlowStepDraft;
-    /** Pause for human review. */
+    } & StepControls) => FlowStepDraft;
+    /** Pause for human review. `timeoutMs` bounds the park (default: the flow's
+     *  `humanTimeoutMs`, then the plugin default — 7 days; `0` = wait forever). */
     human: (o: {
         title?: string;
         description?: string;
@@ -574,12 +753,16 @@ export declare const flowStep: {
         options?: ReadonlyArray<ReviewOption>;
         prompt?: string;
         outputKey?: string;
-    }) => FlowStepDraft;
+        timeoutMs?: number;
+    } & Pick<StepControls, "when">) => FlowStepDraft;
 };
 
 /** A step without its `id` — `defineFlow` assigns stable index-based ids. */
 export declare type FlowStepDraft = Omit<FlowStep, 'id'>;
 
+/** The recorded `app.config.ts` tunables. */
+export declare const getAiFlowsDefaults: () => AiFlowsDefaults;
+
 /** One stored flow by id, or undefined (tenant-scoped by the runtime). */
 export declare const getFlow: (ctx: AppContext, args: {
     id: string;
@@ -588,8 +771,18 @@ export declare const getFlow: (ctx: AppContext, args: {
 /** Resolve a code-registered flow by name, or `undefined` for a data flow. */
 export declare const getRegisteredFlow: (name: string) => FlowIR | undefined;
 
-/** The signal a `human` step parks on; `respondToFlow` sends it to resume. */
-export declare const HUMAN_RESPONSE_SIGNAL = "flow-human-response";
+/** Namespace of the signal a `human` step parks on. Never used on its own —
+ *  the signal a step actually awaits is {@link humanResponseSignalName}. */
+export declare const HUMAN_RESPONSE_SIGNAL_PREFIX = "flow-human-response";
+
+/** Deploy-time override for {@link HUMAN_REVIEW_TIMEOUT_HOURS_DEFAULT}, in
+ *  hours. `0` (or a negative value) means WAIT FOREVER. */
+export declare const HUMAN_REVIEW_TIMEOUT_ENV = "VOLTRO_AI_FLOW_HUMAN_REVIEW_TIMEOUT_HOURS";
+
+/** Framework default park bound for a human review: 7 days. Long enough to
+ *  survive a weekend + a holiday Monday, short enough that an abandoned review
+ *  eventually settles instead of pinning a run forever. */
+export declare const HUMAN_REVIEW_TIMEOUT_HOURS_DEFAULT: number;
 
 /** The HITL answer, written by `respond`. */
 export declare const HumanResponse: Schema.Struct<{
@@ -599,17 +792,81 @@ export declare const HumanResponse: Schema.Struct<{
     respondedAt: Schema.optional<typeof Schema.String>;
 }>;
 
-export declare type HumanResponse = typeof HumanResponse.Type;
+/** An INTERFACE — reached from `aiFlowRuns.humanResponse`; see {@link BriefField}. */
+export declare interface HumanResponse {
+    readonly decision?: 'approve' | 'reject' | undefined;
+    readonly value?: string | undefined;
+    readonly text?: string | undefined;
+    readonly respondedAt?: string | undefined;
+}
+
+/**
+ * The signal name ONE human step parks on, derived from that step's position in
+ * the (journal-pinned) plan.
+ *
+ * **Why this is per-step and not one constant.** `awaitSignalSuspending` derives
+ * its `DurableDeferred` from workflow-name + signal-name per execution, so a
+ * single `'flow-human-response'` for every human step in a flow meant the SECOND
+ * review awaited the deferred the FIRST answer had already completed — it
+ * resolved instantly, with the first reviewer's payload, and the run finished
+ * carrying an approval nobody gave. Measured before the fix: a two-review flow,
+ * one answer, `status: 'succeeded'`, `output: { first: 'answer-one', second:
+ * 'answer-one' }`. The same collision aliased the wait's durable timeout clock
+ * (`await-signal-timeout/<name>`), so the second park inherited the first's
+ * expiry too.
+ *
+ * **Why the INDEX is the identity.** It must be identical on every replay and
+ * derivable by the responder without re-resolving the flow definition (which may
+ * have been edited mid-run). The step list is pinned in the run's journal at
+ * step 0, so a step's index is fixed for the life of the run; the responder
+ * reads it back off the run row's live timeline. A counter, a clock, or a
+ * `randomUUID` would all break replay; the authored step `id` would break the
+ * moment a definition is re-ordered under a live run.
+ */
+export declare const humanResponseSignalName: (stepIndex: number) => string;
 
 /** Replace `{{key}}` with `context[key]` (objects/arrays JSON-stringified; an
  *  absent/null value renders empty). */
 export declare const interpolate: (text: string, context: Record<string, unknown>) => string;
 
+/**
+ * Truthiness, defined once so the engine and the editor cannot disagree.
+ *
+ * Deliberately NOT JavaScript's: `0` and `''` are falsy in JS, and a step gated
+ * on a count or a generated string would then be skipped for a legitimate value.
+ * A flow author writing `when: { ref: 'count', op: 'truthy' }` means "there is a
+ * count", not "the count is non-zero" — the second is `{ op: 'neq', value: 0 }`,
+ * which they can say if they mean it.
+ *
+ * Absent, null and the empty ARRAY are the falsy set: those are the three
+ * shapes a step that produced nothing actually leaves behind.
+ */
+export declare const isTruthy: (v: unknown) => boolean;
+
 /** A JSON value (for `params` / `input` / a `structured` step's JSON Schema). */
 export declare const Json: Schema.Record$<typeof Schema.String, typeof Schema.Unknown>;
 
 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: {
@@ -638,6 +895,20 @@ export declare const makeMediaGenerator: (persist: MediaPersist, opts?: {
     readonly resolveModel?: (model: string) => ProviderConfig;
 }) => MediaGenerator;
 
+/**
+ * How many flows one chain may traverse, including the flow that started it.
+ *
+ * Five, because a chain is a hand-authored pipeline and nobody writes six on
+ * purpose — but the number is a FIELD rather than a constant precisely because
+ * "nobody does that" is an assumption about other people's apps. A cycle is
+ * refused separately and unconditionally; this bounds the acyclic case, where
+ * every hop is a real LLM run somebody pays for.
+ */
+export declare const MAX_CHAIN_DEPTH_DEFAULT = 5;
+
+/** Deploy-time override for {@link MAX_CHAIN_DEPTH_DEFAULT}. */
+export declare const MAX_CHAIN_DEPTH_ENV = "VOLTRO_AI_FLOW_MAX_CHAIN_DEPTH";
+
 /** Legacy default was 30, clamped to [1,100]. (Distinct from `@voltro/ai`'s
  *  own `maxSteps` default of 8 for a single tool loop.) */
 export declare const MAX_STEPS_DEFAULT = 30;
@@ -734,6 +1005,9 @@ export declare type Modality = typeof Modality.Type;
  */
 export declare const nextRuns: (cadence: FlowCadence, from: Date, count?: number) => ReadonlyArray<Date>;
 
+/** Group names that appear in more than one segment — a non-contiguous group. */
+export declare const nonContiguousGroups: (segments: ReadonlyArray<FlowSegment>) => ReadonlyArray<string>;
+
 /**
  * Lower a raw flow definition (from code or a row) to the normalized IR:
  * default the mode, clamp maxSteps, sanitize outputKeys, drop empties. Pure +
@@ -745,16 +1019,52 @@ export declare const normalizeFlow: (def: FlowDefinitionInput) => FlowIR;
  *  `defineFlow` when the module is loaded. */
 export declare const registerFlow: (ir: FlowIR) => void;
 
+/** Test seam — forget the recorded tunables. */
+export declare const resetAiFlowsDefaults: () => void;
+
+/**
+ * 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`.
+ */
+export declare const resolveHumanReviewTimeoutMs: (input: {
+    readonly step?: {
+        readonly timeoutMs?: number | undefined;
+    };
+    readonly flow?: {
+        readonly humanTimeoutMs?: number | undefined;
+    };
+    readonly deps?: {
+        readonly humanReviewTimeoutMs?: number | undefined;
+    };
+    readonly env?: NodeJS.ProcessEnv;
+}) => number;
+
 /** Resolve the IR: code registry by name first, else the stored `ai_flows` row. */
 export declare const resolveIr: (ctx: AppContext, flowRef: string) => Effect.Effect<FlowIR, FlowNotFound>;
 
+/**
+ * Resolve the chain-depth ceiling down the same ladder as every other tunable:
+ * engine deps → plugin option (`app.config.ts`) → env → framework default.
+ *
+ * A value below 1 is IGNORED rather than honoured. `0` would mean "no flow may
+ * chain at all", which is expressible by not declaring a chain, and reading it
+ * literally would turn a typo into a silently disabled feature — the same
+ * reasoning `msFromHoursEnv` applies to a negative timeout.
+ */
+export declare const resolveMaxChainDepth: (deps?: {
+    readonly maxChainDepth?: number | undefined;
+    readonly env?: NodeJS.ProcessEnv;
+}) => number;
+
 /** Record a human's answer to a `waiting` run + signal the parked workflow to
- *  resume. (The park itself lands with the slot-freeing await, task #32/#35.) */
+ *  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>;
 
 /** Re-run a run from its first unfinished step. Reuses the SAME requestId so the
@@ -819,7 +1129,7 @@ export declare const RunStep: Schema.Struct<{
     title: typeof Schema.String;
     description: Schema.optional<typeof Schema.String>;
     type: Schema.Literal<["agent", "generate", "structured", "note", "human"]>;
-    status: Schema.Literal<["pending", "running", "waiting", "succeeded", "failed"]>;
+    status: Schema.Literal<["pending", "running", "waiting", "succeeded", "failed", "skipped"]>;
     startedAt: Schema.optional<typeof Schema.String>;
     completedAt: Schema.optional<typeof Schema.String>;
     /** Per-step cost in micro-USD (the app view projects to €/cents). */
@@ -833,6 +1143,9 @@ export declare const RunStep: Schema.Struct<{
         text: typeof Schema.String;
     }>>;
     errorMessage: Schema.optional<typeof Schema.String>;
+    /** Why a `skipped` step was skipped — the rendered condition, so the timeline
+     *  says "{{approved}} is not set" instead of leaving a silent gap. */
+    skipReason: Schema.optional<typeof Schema.String>;
     review: Schema.optional<Schema.Struct<{
         mode: Schema.Literal<["approve", "choice", "text"]>;
         options: Schema.optional<Schema.Array$<Schema.Struct<{
@@ -861,16 +1174,48 @@ export declare interface RunStep {
         readonly text: string;
     } | undefined;
     readonly errorMessage?: string | undefined;
+    readonly skipReason?: string | undefined;
     readonly review?: RunReview | undefined;
 }
 
-export declare const RunStepStatus: Schema.Literal<["pending", "running", "waiting", "succeeded", "failed"]>;
+export declare const RunStepStatus: Schema.Literal<["pending", "running", "waiting", "succeeded", "failed", "skipped"]>;
 
 export declare type RunStepStatus = typeof RunStepStatus.Type;
 
 /** Sanitize an outputKey to the `{{ref}}`-safe charset. */
 export declare const sanitizeOutputKey: (key: string) => string;
 
+/** Record the `app.config.ts` tunables (called by the plugin factory). */
+export declare const setAiFlowsDefaults: (defaults: AiFlowsDefaults) => void;
+
+declare const StepCondition: Schema.Struct<{
+    /** A brief-field key or an EARLIER step's `outputKey`. */
+    ref: typeof Schema.String;
+    op: Schema.Literal<["truthy", "falsy", "eq", "neq", "contains"]>;
+    /** The right-hand side for `eq` / `neq` / `contains`. Ignored by the unary ops. */
+    value: Schema.optional<typeof Schema.Unknown>;
+}>;
+
+/** An INTERFACE, for the same api-report reason as `FlowStep` — it is reached
+ *  from an exported table column, and an alias to a mapped type gets expanded
+ *  structurally in an order that is not stable across build scopes. */
+declare interface StepCondition {
+    readonly ref: string;
+    readonly op: ConditionOp;
+    readonly value?: unknown;
+}
+export { StepCondition }
+export { StepCondition as StepConditionType }
+
+/** Gating + fan-out, accepted by every builder. Kept as one type so a new
+ *  builder cannot quietly omit them — the six builders below spread it. */
+declare interface StepControls {
+    /** Run this step only when the condition holds; otherwise SKIP it. */
+    readonly when?: StepCondition;
+    /** Consecutive steps sharing a group run CONCURRENTLY. */
+    readonly group?: string;
+}
+
 /** The five step types. `generate` fans out to four modalities. */
 export declare const StepType: Schema.Literal<["agent", "generate", "structured", "note", "human"]>;
 
@@ -905,4 +1250,16 @@ export declare const Visibility: Schema.Literal<["private", "organization", "sha
 
 export declare type Visibility = typeof Visibility.Type;
 
+/**
+ * Which human step a `waiting` run is parked on — the index the engine used to
+ * 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:
+ * 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.
+ */
+export declare const waitingStepIndex: (row: Record<string, unknown>) => number;
+
 export { }