@punica/editor 1.0.6 → 1.0.8

package/types/punica.module.flow.primitives.d.ts

@@ -0,0 +1,700 @@
+/// <reference path="./punica.module.flow.d.ts" />
+/// <reference path="./punica.module.flow.engine.d.ts" />
+
+declare module 'punica' {
+  // eslint-disable-next-line @typescript-eslint/no-namespace
+  export namespace flow {
+    /**
+     * Trinity verification seam — every `ivyNode` / `flowBook` ref in a
+     * `FlowBookDocument` is checked against this predicate at validation
+     * time. Substrate's `validator.module.ts` plumbs it through
+     * `unifiedCapabilityRegistry.getCapability(...)`; unit tests inject
+     * a deterministic set without touching the registry.
+     *
+     * Anayasal sözleşme: CONSTITUTION § 0.1 — a flow document may name
+     * a capability from any of the three origins (extension /
+     * instruction-class / ivy-node) and the validator walks a single
+     * registry surface. Returning `false` for a referenced id means the
+     * Trinity invariant is broken; load-time rejection is the safest
+     * signal.
+     */
+    export type CapabilityLookup = (capabilityId: string) => boolean;
+
+    /**
+     * Built-in primitive node kinds carried by `FlowBookDocument` graphs.
+     * Substrate ships the executor surface (4.C); host extensions can
+     * register additional kinds via the node registry. Primitives are
+     * deliberately small — they exist so a domain author can compose
+     * branches/loops/error-handling without writing custom capabilities.
+     *
+     *  - 'if' / 'else' : predicate-gated branch
+     *  - 'forEach'     : collection iteration with max-iterations cap
+     *  - 'while'       : predicate-driven loop with max-iterations cap
+     *  - 'try'/'catch'/'finally' : structured error handling triplet
+     *  - 'lambda'      : inline pure transform (explicit alternative to
+     *                    "wrap every transform as a capability")
+     */
+    export type FlowPrimitiveKind =
+      | 'if'
+      | 'else'
+      | 'forEach'
+      | 'while'
+      | 'try'
+      | 'catch'
+      | 'finally'
+      | 'lambda';
+
+    /**
+     * Redaction directive per node, intersected with the capability's
+     * declared `dataClassification` at persistence time (4.J). Substrate
+     * `artifactStore` honors this when serializing inputs/outputs to the
+     * run record; `'all'` redacts both surfaces, `'none'` is the default.
+     */
+    export type RedactionPolicy = 'none' | 'input' | 'output' | 'all';
+
+    /**
+     * Checkpoint format version. The substrate ships a single literal
+     * (`'1'`) and a `CheckpointMigrator` surface (4.H) so future versions
+     * can be transformed forward without breaking persisted state.
+     */
+    export type CheckpointVersion = '1';
+
+    /**
+     * Migration transformer pinned to a semver pair. The substrate ships
+     * an empty registry; hosts inject transformers via
+     * `flow.migrate` (4.F). `from` and `to` follow semver (`major.minor.patch`);
+     * the substrate accepts any string and defers semver parsing to the
+     * registry to keep this surface I/O-free.
+     */
+    export interface FlowMigrationTransformer {
+      from: string;
+      to: string;
+      transform(doc: FlowBookDocument): FlowBookDocument;
+    }
+
+    /**
+     * Severity emitted by lint rules. Mirrors `ValidationSeverity` but
+     * adds `'info'` so style/hygiene rules can surface without elevating
+     * to a build break.
+     */
+    export type FlowLintSeverity = 'error' | 'warning' | 'info';
+
+    /**
+     * One finding produced by a lint rule. `path` is a dot-path into
+     * `FlowBookDocument` (e.g. `graph.nodes[2].ref.id`); `nodeId` is the
+     * resolved node id when applicable. `code` is the rule's stable
+     * machine identifier (e.g. `WF_UNKNOWN_CAPABILITY`).
+     */
+    export interface FlowLintIssue {
+      ruleId: string;
+      severity: FlowLintSeverity;
+      message: string;
+      path?: string;
+      nodeId?: NodeId;
+      code?: string;
+    }
+
+    /**
+     * Aggregated lint result returned by `FlowLinter.lint(...)`. `ok` is
+     * false when at least one `error`-severity issue is present;
+     * warnings and infos do not affect `ok`.
+     */
+    export interface FlowLintResult {
+      ok: boolean;
+      issues: FlowLintIssue[];
+    }
+
+    /**
+     * Context the substrate passes into each lint rule. Pure analyzer
+     * surface — rules MUST NOT close over global state or perform I/O;
+     * anything they need is on `ctx`.
+     *
+     *  - `hasCapability` mirrors the validator's Trinity seam — the
+     *    `capability-not-declared` rule uses it to flag refs to ids
+     *    the unified registry has never heard of.
+     *  - `getCapability` returns the full `CapabilityDefinition` so
+     *    schema-aware rules (`schema-mismatch`,
+     *    `idempotency-required-but-no-key`) can inspect policy + IO
+     *    schemas without performing registry I/O.
+     *  - `maxSubflowDepth` lets the `subflow-depth-exceeded` rule
+     *    use a custom cap (CI may pass a tighter value than the
+     *    runtime `MAX_SUBFLOW_DEPTH`).
+     */
+    export interface FlowLintContext {
+      hasCapability?: CapabilityLookup;
+      getCapability?: (id: string) => CapabilityDefinition | undefined;
+      maxSubflowDepth?: number;
+    }
+
+    /**
+     * Substrate-shipped lint aggregator (flow linter). Pure analyzer:
+     * `lint(spec, ctx?)` runs every registered rule against the
+     * `FlowBookDocument` and returns a single aggregated
+     * `FlowLintResult`. `register` / `unregister` let extensions
+     * add custom rules without forking the substrate. The default
+     * rule set (7 rules — `capability-not-declared`,
+     * `unreachable-node`, `dep-cycle`,
+     * `idempotency-required-but-no-key`, `schema-mismatch`,
+     * `infinite-loop`, `subflow-depth-exceeded`) is shipped by the
+     * substrate; `reset()` restores it.
+     */
+    export interface FlowLinter {
+      lint(spec: FlowBookDocument, ctx?: FlowLintContext): FlowLintResult;
+      register(rule: FlowLintRule): void;
+      unregister(ruleId: string): boolean;
+      list(): readonly string[];
+      reset(): void;
+    }
+
+    /**
+     * A single lint rule. Substrate ships a fixed rule set (4.E); host
+     * extensions can register additional rules via the linter registry.
+     * `check` MUST be pure (deterministic + no I/O) so the analyzer is
+     * usable in CI without booting the runtime.
+     */
+    export interface FlowLintRule {
+      id: string;
+      severity: FlowLintSeverity;
+      check(spec: FlowBookDocument, ctx: FlowLintContext): FlowLintIssue[];
+    }
+
+    /**
+     * Stable identifier for a trigger registered through a
+     * `TriggerProvider`.
+     */
+    export type TriggerId = string;
+
+    /**
+     * Trigger kind discriminator. `'manual'` is the substrate default
+     * (`ManualTriggerProvider` ships in 4.G). `'scheduled'`,
+     * `'webhook'`, and `'event'` are host territory (cron parser, HTTP
+     * server, kernel-event binding live outside the substrate). The
+     * trailing `string` widening lets hosts introduce custom kinds
+     * without a substrate change.
+     */
+    export type TriggerKind =
+      | 'manual'
+      | 'scheduled'
+      | 'webhook'
+      | 'event'
+      | (string & {});
+
+    /**
+     * Declarative trigger definition. `flowId` is the capability id of
+     * the flow to start when the trigger fires; `config` is opaque to
+     * the substrate and interpreted by the host provider.
+     */
+    export interface TriggerDefinition {
+      id: TriggerId;
+      kind: TriggerKind;
+      flowId: CapabilityId;
+      config?: JSONObject;
+      disabled?: boolean;
+    }
+
+    /**
+     * Per-firing context delivered to the registered callback. The
+     * substrate threads `correlationId` into the resulting run so the
+     * audit ring can link trigger firing → run start.
+     */
+    export interface TriggerFiringContext {
+      triggerId: TriggerId;
+      firedAtMs: number;
+      payload?: JSONValue;
+      correlationId?: string;
+    }
+
+    /**
+     * Callback handed to `TriggerProvider.register`. Substrate calls
+     * this when the host provider observes the trigger has fired; the
+     * default implementation starts a run for `trigger.flowId`.
+     */
+    export type TriggerCallback = (
+      ctx: TriggerFiringContext
+    ) => void | Promise<void>;
+
+    /**
+     * Handle returned by `TriggerProvider.register`. `unsubscribe` is
+     * idempotent — calling twice is a no-op.
+     */
+    export interface TriggerSubscription {
+      triggerId: TriggerId;
+      unsubscribe(): void;
+    }
+
+    /**
+     * Lifecycle event surfaced through `TriggerProvider.subscribe`.
+     * Substrate uses this to emit the `flow.trigger.fired` kernel event
+     * (event correlation / audit) and to drive trigger-firing observability dashboards
+     * (host territory). Discriminated by `type`.
+     */
+    export type TriggerEvent =
+      | {
+          type: 'registered';
+          triggerId: TriggerId;
+          kind: TriggerKind;
+          ts: number;
+        }
+      | { type: 'unregistered'; triggerId: TriggerId; ts: number }
+      | {
+          type: 'fired';
+          triggerId: TriggerId;
+          ts: number;
+          payload?: JSONValue;
+          correlationId?: string;
+        }
+      | {
+          type: 'error';
+          triggerId: TriggerId;
+          ts: number;
+          error: { code?: string; message: string };
+        };
+
+    /**
+     * Substrate-defined value reference for primitive nodes. Predicates,
+     * loop collections, and lambda inputs read from either a literal
+     * inline value or a dot-path against the per-run `nodeOutputs` map
+     * the engine populates as upstream nodes produce structured output.
+     *
+     *  - `{ kind: 'literal', value }`            — inline value
+     *  - `{ kind: 'path', path: 'nodeA.foo.b' }` — dot-path into outputs
+     *
+     * Path semantics: the first segment is a node id; the remainder is
+     * a property chain. Missing segments resolve to `undefined`; the
+     * resolver never throws on a miss so primitive executors can
+     * surface a structured "predicate undefined" artifact instead of
+     * crashing the run.
+     */
+    export type PrimitiveValueRef =
+      | { kind: 'literal'; value: JSONValue }
+      | { kind: 'path'; path: string };
+
+    /**
+     * Result of resolving a `PrimitiveValueRef` against the per-run
+     * `nodeOutputs` map. Substrate uses a discriminated shape so
+     * primitive executors can disambiguate "resolved to undefined"
+     * from "the value was actually undefined".
+     */
+    export type PrimitiveValueResolution =
+      | { ok: true; value: JSONValue }
+      | { ok: false; reason: 'missing-node' | 'missing-path' | 'invalid-ref' };
+
+    /**
+     * `node.data` shape for the `'if'` primitive. The executor evaluates
+     * `predicate` (truthy/falsy semantics on the resolved value) and
+     * records `{ taken: 'then' | 'else' }` as the node's artifact.
+     * `thenBodyFlowId` / `elseBodyFlowId` reference subflows (subflow
+     * spawning); flow primitives only records the decision, the actual subflow dispatch
+     * lands when `flow.runSubflow` ships.
+     *
+     * `'else'` primitives are paired-marker nodes for graph readability
+     * and have no data of their own — the dispatch decision lives on
+     * the `'if'` node.
+     */
+    export interface IfPrimitiveData {
+      predicate: PrimitiveValueRef;
+      thenBodyFlowId?: CapabilityId;
+      elseBodyFlowId?: CapabilityId;
+    }
+
+    /**
+     * `node.data` shape for the `'forEach'` primitive. `collection`
+     * must resolve to an array (or `null`/`undefined`, treated as
+     * empty). `maxIterations` is mandatory — the substrate refuses
+     * to ship an unbounded loop primitive; the lint engine (4.E)
+     * upgrades absence to an `infinite-loop` finding. `itemBinding`
+     * is the property name an iteration body uses to read the current
+     * item from its subflow input (`{ [itemBinding]: item, index }`).
+     */
+    export interface ForEachPrimitiveData {
+      collection: PrimitiveValueRef;
+      bodyFlowId: CapabilityId;
+      maxIterations: number;
+      itemBinding?: string;
+    }
+
+    /**
+     * `node.data` shape for the `'while'` primitive. `predicate` is
+     * re-evaluated on every iteration; `maxIterations` is the
+     * substrate's hard safety cap. Same forward-defer note as
+     * `ForEachPrimitiveData`.
+     */
+    export interface WhilePrimitiveData {
+      predicate: PrimitiveValueRef;
+      bodyFlowId: CapabilityId;
+      maxIterations: number;
+    }
+
+    /**
+     * `node.data` shape for the `'try'` primitive. `tryBodyFlowId`
+     * runs first; on uncaught failure the engine dispatches
+     * `catchBodyFlowId` (when present) with the error structured as
+     * the catch body's input. `finallyBodyFlowId` always runs once,
+     * after either success or catch. `'catch'` and `'finally'` are
+     * marker primitives — their data is empty and they are present
+     * for graph readability + the lint engine's pairing checks.
+     */
+    export interface TryCatchFinallyPrimitiveData {
+      tryBodyFlowId: CapabilityId;
+      catchBodyFlowId?: CapabilityId;
+      finallyBodyFlowId?: CapabilityId;
+    }
+
+    /**
+     * `node.data` shape for the `'lambda'` primitive. `lambdaId`
+     * resolves through `punica.flow.primitives.lambdas` (substrate
+     * ships an empty registry; hosts / extensions register pure
+     * transforms). `input` resolves through `PrimitiveValueRef`;
+     * the transform's return value is recorded as the node's artifact
+     * and threaded into `nodeOutputs[nodeId]`.
+     */
+    export interface LambdaPrimitiveData {
+      lambdaId: string;
+      input?: PrimitiveValueRef;
+    }
+
+    /**
+     * Per-invocation context handed to a registered lambda. Substrate
+     * keeps this small + immutable so transforms can be deterministic;
+     * I/O and side-effects are explicitly out of scope (lambdas that
+     * need them should be modelled as capabilities instead).
+     */
+    export interface LambdaContext {
+      nodeId: NodeId;
+      attemptCorrelationId: string;
+      traceId: string;
+    }
+
+    /**
+     * Pure transform body. Lambdas SHOULD be deterministic (same input
+     * + same context → same output) and MUST NOT throw for control
+     * flow — surface domain errors by returning a structured payload.
+     */
+    export type LambdaFn = (
+      input: JSONValue,
+      ctx: LambdaContext
+    ) => JSONValue | Promise<JSONValue>;
+
+    /**
+     * Substrate-shipped registry for lambda transforms. Hosts /
+     * extensions register pure transforms; the `'lambda'` primitive
+     * looks them up by id at execution time. Substrate ships an empty
+     * registry; real transforms are host / extension territory.
+     */
+    export interface LambdaRegistry {
+      register(id: string, fn: LambdaFn): void;
+      unregister(id: string): boolean;
+      get(id: string): LambdaFn | undefined;
+      list(): readonly string[];
+      clear(): void;
+    }
+
+    /**
+     * Primitive-side façade exposed at `punica.flow.primitives`.
+     * Substrate ships the `lambdas` registry (flow primitives) and the
+     * pure `linter` aggregator (flow linter); future sub-steps
+     * (4.F migrator) extend this with additional analysis surfaces.
+     */
+    export interface PrimitivesApi {
+      lambdas: LambdaRegistry;
+      linter: FlowLinter;
+      migrations: MigrationRegistry;
+      checkpoints: CheckpointsApi;
+    }
+
+    /**
+     * Host-injected trigger surface (D7). Substrate ships the interface
+     * + `ManualTriggerProvider` default (4.G); real `scheduled`,
+     * `webhook`, and `event` providers are host territory (cron parser,
+     * HTTP server with HMAC verification + rate limit, kernel-event
+     * binding). LLM/FS provider injection pattern: substrate defines contract +
+     * test fixture, host injects production impl.
+     *
+     *  - `register` subscribes a callback to a trigger and returns an
+     *    idempotent handle.
+     *  - `unregister` returns `true` when the trigger existed.
+     *  - `list` is a snapshot of currently registered triggers.
+     *  - `subscribe` is the lifecycle observer (registered / fired /
+     *    error); the returned function unsubscribes.
+     */
+    export interface TriggerProvider {
+      register(
+        trigger: TriggerDefinition,
+        callback: TriggerCallback
+      ): TriggerSubscription;
+      unregister(triggerId: TriggerId): boolean;
+      list(): readonly TriggerDefinition[];
+      subscribe(listener: (event: TriggerEvent) => void): () => void;
+    }
+
+    /**
+     * Substrate-shipped checkpoint format version (run status / checkpoints). The
+     * substrate ships a single literal (`'1'`); future versions are
+     * introduced by registering a `CheckpointMigrator` that walks
+     * from the prior version forward. The literal is pinned in
+     * `flow.CheckpointVersion` so callers cannot drift.
+     */
+    export interface CheckpointMigrator {
+      from: CheckpointVersion | string;
+      to: CheckpointVersion | string;
+      migrate(checkpoint: JSONValue): JSONValue;
+    }
+
+    /**
+     * Age policy for resume-time checkpoint reads (run status / checkpoints,
+     * F26). Substrate honors `maxAgeMs` — a checkpoint older than
+     * the cap is rejected at resume and the run restarts from
+     * scratch (substrate refuses to silently replay stale state).
+     * Hosts that want unbounded retention pass `undefined` (the
+     * default) — substrate then trusts the host's storage policy.
+     */
+    export interface CheckpointAgePolicy {
+      maxAgeMs?: number;
+    }
+
+    /**
+     * Substrate-shipped registry for `CheckpointMigrator` entries.
+     * Same shape as `MigrationRegistry` (4.F) but operates on
+     * checkpoint payloads rather than FlowBookDocuments. Substrate
+     * ships an EMPTY registry — hosts inject migrators when the
+     * checkpoint version moves forward.
+     */
+    export interface CheckpointMigratorRegistry {
+      register(migrator: CheckpointMigrator): void;
+      unregister(from: string, to: string): boolean;
+      find(from: string, to: string): CheckpointMigrator | undefined;
+      list(): readonly CheckpointMigrator[];
+      clear(): void;
+    }
+
+    /**
+     * Façade exposed at `punica.flow.primitives.checkpoints`. Bundles
+     * the migrator registry + the substrate-shipped pure age helper
+     * (`isFresh(savedAtMs, policy, nowMs?)`).
+     */
+    export interface CheckpointsApi {
+      migrators: CheckpointMigratorRegistry;
+      isFresh(
+        savedAtMs: number,
+        policy?: CheckpointAgePolicy,
+        nowMs?: number
+      ): boolean;
+    }
+
+    /**
+     * Host-swappable triggers façade (flow triggers). Substrate ships
+     * `ManualTriggerProvider` as the default; hosts inject a custom
+     * provider (scheduled / webhook / event) via `setProvider`. The
+     * `manager` field is always the currently-active provider —
+     * mirrors the FS provider injection pattern: substrate
+     * defines the contract + a substrate-default fixture, host owns
+     * the real implementation.
+     */
+    export interface TriggersApi {
+      manager: TriggerProvider;
+      /**
+       * Swap the active provider. Substrate clears every subscription
+       * routed through the previous provider before handing control
+       * over so the host never inherits stale callbacks.
+       */
+      setProvider(provider: TriggerProvider): void;
+      /**
+       * Restore the substrate default (`ManualTriggerProvider`).
+       * Used by tests + by hosts that want to revert to manual after
+       * disabling a scheduled provider at runtime.
+       */
+      resetProvider(): void;
+    }
+
+    /**
+     * Substrate-shipped triggers façade exposed at
+     * `punica.flow.triggers`. flow triggers ships `ManualTriggerProvider`
+     * as the substrate default; hosts inject scheduled / webhook /
+     * event impls.
+     */
+    export const triggers: TriggersApi;
+
+    /**
+     * Substrate-shipped primitives façade. Exposed at
+     * `punica.flow.primitives`. Surfaces the lambda registry +
+     * (subflow spawning) the recursion-guard cap; future sub-steps
+     * (4.E linter, 4.F migrator) extend this with additional
+     * pure-analysis surfaces.
+     */
+    export const primitives: PrimitivesApi;
+
+    /**
+     * Policy for handling a `FlowBookDocument` whose `version` differs
+     * from the runtime's expected version (flow migration).
+     *
+     *  - `'auto-migrate'` — attempt to apply registered transformers
+     *    in sequence; if no chain is found, fall back to `'reject'`.
+     *  - `'warn'`         — emit a warning but execute the spec as-is.
+     *  - `'reject'`       — refuse to load the spec. Substrate default.
+     *
+     * Substrate's pragmatic stance: silent acceptance of mismatched
+     * versions is the worst option (a flow that "works" on a stale
+     * substrate may silently drop fields). The host picks one of the
+     * three explicitly; substrate ships no implicit fallback.
+     */
+    export type VersionMismatchPolicy = 'auto-migrate' | 'warn' | 'reject';
+
+    /**
+     * Outcome of a `flow.migrate` invocation. Discriminated by `ok`:
+     * a successful migration returns the transformed document + the
+     * chain of transformer ids that ran; a failed migration carries
+     * a stable `reason` code so callers can branch programmatically.
+     *
+     *  - `'no-path'`        — no transformer chain reaches the target.
+     *  - `'transformer-threw'` — a transformer threw mid-chain. The
+     *    document is left at the last successfully-migrated state.
+     *  - `'invalid-result'` — a transformer returned a document that
+     *    failed substrate validation. Same partial-progress semantics
+     *    as `'transformer-threw'`.
+     *  - `'no-migrate-policy'` — the caller selected `'reject'` and
+     *    the input version did not match the target.
+     */
+    export type MigrationFailureReason =
+      | 'no-path'
+      | 'transformer-threw'
+      | 'invalid-result'
+      | 'no-migrate-policy';
+
+    export type MigrationResult =
+      | {
+          ok: true;
+          document: FlowBookDocument;
+          appliedTransformers: readonly string[];
+          fromVersion: string;
+          toVersion: string;
+        }
+      | {
+          ok: false;
+          reason: MigrationFailureReason;
+          message: string;
+          partialDocument?: FlowBookDocument;
+          appliedTransformers: readonly string[];
+        };
+
+    /**
+     * Input payload accepted by the substrate `flow.migrate`
+     * capability + the `MigrationRegistry.migrate` orchestrator
+     * (flow migration). `targetVersion` is the version the caller wants
+     * to land at; substrate looks up a transformer chain from
+     * `document.version` to `targetVersion`. When `policy` is
+     * `'auto-migrate'` and the chain is empty (spec already at
+     * target), substrate returns `{ ok: true, appliedTransformers: [] }`.
+     */
+    export interface MigrationInvocation {
+      document: FlowBookDocument;
+      targetVersion: string;
+      policy?: VersionMismatchPolicy;
+    }
+
+    /**
+     * Substrate-shipped registry for `FlowMigrationTransformer`
+     * entries. The substrate ships an EMPTY registry — real
+     * transformers are host territory (matching the
+     * `LambdaRegistry` + `TriggerProvider` pattern). `find(from, to)`
+     * returns the registered chain (single-hop or composite) the
+     * substrate planner can apply; `migrate(input)` orchestrates
+     * the full sequence with policy-driven mismatch handling.
+     */
+    export interface MigrationRegistry {
+      register(transformer: FlowMigrationTransformer): void;
+      unregister(from: string, to: string): boolean;
+      find(from: string, to: string): FlowMigrationTransformer | undefined;
+      list(): readonly FlowMigrationTransformer[];
+      clear(): void;
+      /**
+       * Apply a transformer chain to `input.document` until it
+       * reaches `input.targetVersion`. Substrate honors the
+       * `policy` argument: `'reject'` refuses any mismatch,
+       * `'warn'` returns the original doc unchanged with a
+       * note in the failure path, `'auto-migrate'` performs the
+       * full chain. Pure relative to the registry's transformer
+       * functions — no kernel access.
+       */
+      migrate(input: MigrationInvocation): MigrationResult;
+    }
+
+    /**
+     * Substrate hard cap on subflow recursion depth (subflow spawning).
+     * `flow.runSubflow` rejects any invocation whose `parentDepth + 1`
+     * would exceed this value with a `SUBFLOW_DEPTH_EXCEEDED` error.
+     * The 4.E lint engine surfaces a `subflow-depth-exceeded` finding
+     * for graphs whose statically-derivable depth pierces the cap.
+     *
+     * Substrate's anayasal stance: a runaway flow that spawns
+     * subflows in a cycle would silently exhaust the host's stack /
+     * approval queue; a substrate cap is the safest default. Hosts
+     * cannot lift this cap — the substrate ships the constant
+     * because the contract is "substrate, not host, owns the safety
+     * floor" (fail-closed ethos).
+     */
+    export const MAX_SUBFLOW_DEPTH: 8;
+
+    /**
+     * Substrate error code for a depth-cap violation. Surfaced both
+     * by the runtime `flow.runSubflow` capability and by the 4.E
+     * lint engine.
+     */
+    export const SUBFLOW_DEPTH_EXCEEDED_CODE: 'SUBFLOW_DEPTH_EXCEEDED';
+
+    /**
+     * Input payload accepted by the `flow.runSubflow` capability
+     * (subflow spawning). The substrate spawns a fresh `RunRecord` for the
+     * subflow, threads the parent's workspace + depth, and inherits
+     * the parent's approval scope (D5: `'once'` is per-workspace + per
+     * session, so a parent's `'once'` approval is naturally honored
+     * by the child as long as `workspaceId` matches — F33 dedup).
+     *
+     *  - `spec`           — required `FlowBookDocument` to run.
+     *  - `workspaceId`    — inherited from the parent run; the
+     *                       substrate refuses to spawn a subflow into
+     *                       a different workspace by default.
+     *  - `input`          — optional structured input threaded into
+     *                       the child's `flow-input` node.
+     *  - `parentRunId`    — id of the spawning run; recorded on the
+     *                       child for audit (event correlation / audit timeline
+     *                       stitching).
+     *  - `parentTraceId`  — trace correlation id propagated so
+     *                       parent + child appear on the same audit
+     *                       timeline.
+     *  - `parentDepth`    — current depth of the spawning run
+     *                       (`0` for top-level). Substrate rejects
+     *                       any invocation with
+     *                       `parentDepth + 1 > MAX_SUBFLOW_DEPTH`.
+     *  - `filePathOrUri`  — optional source ref forwarded for
+     *                       notebookCell-backed flows.
+     */
+    export interface SubflowInvocation {
+      spec: FlowBookDocument;
+      workspaceId?: string;
+      input?: JSONValue;
+      parentRunId?: string;
+      parentTraceId?: string;
+      parentDepth?: number;
+      filePathOrUri?: string;
+    }
+
+    /**
+     * Result returned by the `flow.runSubflow` capability after the
+     * child run reaches a terminal state. Substrate always returns
+     * the structured shape — exceptions are reserved for synchronous
+     * pre-flight failures (`SUBFLOW_DEPTH_EXCEEDED`, missing spec,
+     * missing engine). Run-time failures surface as
+     * `status: 'FAILED'` + `error`.
+     */
+    export interface SubflowResult {
+      runId: string;
+      parentRunId?: string;
+      depth: number;
+      status: engine.RunStatus;
+      output?: JSONValue;
+      error?: { message: string; code?: string; nodeId?: string };
+      startedAtMs?: number;
+      endedAtMs?: number;
+    }
+  }
+}