@ixo/editor 6.22.0 → 6.23.0

package/dist/{index-BC4ycOwH.d.ts → index-x1R0c9P_.d.ts}

@@ -1,11 +1,154 @@
 import * as _blocknote_core from '@blocknote/core';
 import { BlockSchemaFromSpecs, InlineContentSchema, StyleSchema, BlockNoteEditor, PartialBlock } from '@blocknote/core';
-import * as React from 'react';
-import React__default from 'react';
 import { MatrixClient } from 'matrix-js-sdk';
+import * as Y from 'yjs';
 import { Map, Doc, Array as Array$1 } from 'yjs';
+import * as React from 'react';
+import React__default from 'react';
 import { Delegation } from '@ixo/ucan';
 
+type DID = string;
+type ClaimCollectionURI = string;
+type EvaluationStatus = 'pending' | 'approved' | 'rejected';
+interface LinkedClaim {
+    collectionId: ClaimCollectionURI;
+}
+interface FlowNodeAuthzExtension {
+    linkedClaim?: LinkedClaim;
+}
+/**
+ * Canonical persisted block lifecycle shared by browser and headless writers.
+ *
+ * `pending`, `retry_scheduled`, and `awaiting_human` are orchestration resting
+ * states written by Flow Manager. They must remain part of this union: the
+ * Editor waist validates persisted states, and treating them as unknown would
+ * erase them during read/merge and re-arm work that is already queued.
+ */
+type NodeState = 'idle' | 'pending' | 'running' | 'retry_scheduled' | 'awaiting_human' | 'completed' | 'failed' | 'cancelled' | 'awaiting_readback' | 'needs_verification';
+type ReadBackTerminalState = 'pending' | 'completed' | 'failed';
+interface ActionReadBackMetadata {
+    kind: string;
+    status?: ReadBackTerminalState;
+    correlationId?: string;
+    validationSource?: string;
+    requestedAt?: string;
+    lastCheckedAt?: string;
+    terminalAt?: string;
+    blockId?: string;
+    actionType?: string;
+    actorDid?: DID;
+    invocationCid?: string;
+    capabilityId?: string;
+    pendingInvocation?: {
+        id: string;
+        triggeringBlockId: string;
+        eventName: string;
+        sourceRunId?: string;
+    };
+    [key: string]: any;
+}
+/**
+ * One advisory report from a contracted helper oracle, landed by the flow
+ * manager under `runtime[blockId].serviceReports[serviceRole]`.
+ */
+interface NodeServiceReport {
+    output: Record<string, unknown>;
+    oracleDid: string;
+    invocationId: string;
+    receivedAt: number;
+}
+interface FlowNodeRuntimeState {
+    state?: NodeState;
+    output?: Record<string, any>;
+    executedByDid?: DID;
+    executedAt?: number;
+    /** Monotonic attempt number within this session run. */
+    attempt?: number;
+    /** Stable id for the current/last action execution attempt. */
+    executionId?: string;
+    executionStartedAt?: number;
+    outputSequence?: number;
+    /** Matrix event id at the current head of this action's immutable history. */
+    lastEventId?: string;
+    /** Unix timestamp (ms) when the block first became enabled/activated */
+    enabledAt?: number;
+    /**
+     * Set when a human resolves a `needs_verification` block by confirming the
+     * side effect really happened (see NodeState). It moves the block to
+     * `completed` and tells `verifyCompletion` to trust it despite the missing
+     * declared proof field. Records who confirmed and when for the audit trail.
+     */
+    manuallyVerified?: boolean;
+    manuallyVerifiedByDid?: DID;
+    manuallyVerifiedAt?: number;
+    /** Metadata needed to reconcile an externally completed action later. */
+    readBack?: ActionReadBackMetadata;
+    /** Last explicit completion-contract reconciliation. */
+    reconciledAt?: number;
+    completionSource?: string;
+    invocations?: string[];
+    lastInvocationCid?: string;
+    assignments?: Array<{
+        actorDid: DID;
+        assignedByDid?: DID;
+        at: number;
+        status: 'assigned' | 'accepted' | 'declined';
+    }>;
+    commitments?: Array<{
+        actorDid: DID;
+        at: number;
+        expiresAt?: number;
+    }>;
+    proposals?: Array<{
+        id: string;
+        proposedByDid: DID;
+        proposedAt: number;
+        mode: 'inputs_patch' | 'output_patch';
+        patch: any;
+        rationale?: string;
+        status: 'open' | 'accepted' | 'rejected';
+        decidedByDid?: DID;
+        decidedAt?: number;
+        acceptanceInvocationCid?: string;
+    }>;
+    pendingPayload?: Record<string, unknown>;
+    error?: {
+        message: string;
+        code?: string;
+        at: number;
+        data?: any;
+    };
+    /**
+     * Generic per-block escape hatch for state that does not fit the typed
+     * lifecycle fields above and should survive browser refresh via Yjs.
+     */
+    cache?: Record<string, unknown>;
+    /** Per-instance user-typed values that need to survive reload (e.g. encrypted API keys
+     *  the user entered into a form-style action block). Action blocks own the shape. */
+    userInputs?: Record<string, any>;
+    /**
+     * Advisory oracle reports written by the flow manager, keyed by service
+     * role (e.g. 'evaluation-report'). Service receipts are NOT execution
+     * results: they never touch the node's own state/output and are optional
+     * input to the human decision, not a blocker.
+     */
+    serviceReports?: Record<string, NodeServiceReport>;
+    claimId?: string;
+    submittedByDid?: DID;
+    evaluationStatus?: EvaluationStatus;
+    executionTimestamp?: number;
+}
+interface FlowNodeBase {
+    id: string;
+    type: string;
+    props: Record<string, any>;
+    activationCondition?: {
+        upstreamNodeId: string;
+        requiredStatus: EvaluationStatus;
+    };
+}
+type FlowNode = FlowNodeBase & FlowNodeAuthzExtension;
+
 type ProposalActionType = 'Spend' | 'UpdateMembers' | 'Stake' | 'Join' | 'AuthzExec' | 'AuthzGrant' | 'AuthzRevoke' | 'BurnNft' | 'Mint' | 'Execute' | 'Instantiate' | 'ManageSubDaos' | 'ManageCw721' | 'ManageCw20' | 'Migrate' | 'TransferNft' | 'UpdateAdmin' | 'UpdatePreProposeConfig' | 'UpdateVotingConfig' | 'GovernanceVote' | 'WithdrawTokenSwap' | 'UpdateInfo' | 'Custom' | 'ManageStorageItems' | 'ValidatorActions' | 'PerformTokenSwap' | 'DaoAdminExec' | 'StakeToGroup' | 'SendGroupToken' | 'AcceptToMarketplace' | 'CreateEntity';
 interface Member$1 {
     addr: string;
@@ -4891,129 +5034,6 @@ declare class MatrixMetadataManager {
     dispose(): void;
 }
 
-type DID = string;
-type ClaimCollectionURI = string;
-type EvaluationStatus = 'pending' | 'approved' | 'rejected';
-interface LinkedClaim {
-    collectionId: ClaimCollectionURI;
-}
-interface FlowNodeAuthzExtension {
-    linkedClaim?: LinkedClaim;
-}
-type NodeState = 'idle' | 'running' | 'completed' | 'failed' | 'cancelled' | 'awaiting_readback' | 'needs_verification';
-type ReadBackTerminalState = 'pending' | 'completed' | 'failed';
-interface ActionReadBackMetadata {
-    kind: string;
-    status?: ReadBackTerminalState;
-    correlationId?: string;
-    validationSource?: string;
-    requestedAt?: string;
-    lastCheckedAt?: string;
-    terminalAt?: string;
-    blockId?: string;
-    actionType?: string;
-    actorDid?: DID;
-    invocationCid?: string;
-    capabilityId?: string;
-    pendingInvocation?: {
-        id: string;
-        triggeringBlockId: string;
-        eventName: string;
-        sourceRunId?: string;
-    };
-    [key: string]: any;
-}
-/**
- * One advisory report from a contracted helper oracle, landed by the flow
- * manager under `runtime[blockId].serviceReports[serviceRole]`.
- */
-interface NodeServiceReport {
-    output: Record<string, unknown>;
-    oracleDid: string;
-    invocationId: string;
-    receivedAt: number;
-}
-interface FlowNodeRuntimeState {
-    state?: NodeState;
-    output?: Record<string, any>;
-    executedByDid?: DID;
-    executedAt?: number;
-    /** Unix timestamp (ms) when the block first became enabled/activated */
-    enabledAt?: number;
-    /**
-     * Set when a human resolves a `needs_verification` block by confirming the
-     * side effect really happened (see NodeState). It moves the block to
-     * `completed` and tells `verifyCompletion` to trust it despite the missing
-     * declared proof field. Records who confirmed and when for the audit trail.
-     */
-    manuallyVerified?: boolean;
-    manuallyVerifiedByDid?: DID;
-    manuallyVerifiedAt?: number;
-    /** Metadata needed to reconcile an externally completed action later. */
-    readBack?: ActionReadBackMetadata;
-    invocations?: string[];
-    lastInvocationCid?: string;
-    assignments?: Array<{
-        actorDid: DID;
-        assignedByDid?: DID;
-        at: number;
-        status: 'assigned' | 'accepted' | 'declined';
-    }>;
-    commitments?: Array<{
-        actorDid: DID;
-        at: number;
-        expiresAt?: number;
-    }>;
-    proposals?: Array<{
-        id: string;
-        proposedByDid: DID;
-        proposedAt: number;
-        mode: 'inputs_patch' | 'output_patch';
-        patch: any;
-        rationale?: string;
-        status: 'open' | 'accepted' | 'rejected';
-        decidedByDid?: DID;
-        decidedAt?: number;
-        acceptanceInvocationCid?: string;
-    }>;
-    pendingPayload?: Record<string, unknown>;
-    error?: {
-        message: string;
-        code?: string;
-        at: number;
-        data?: any;
-    };
-    /**
-     * Generic per-block escape hatch for state that does not fit the typed
-     * lifecycle fields above and should survive browser refresh via Yjs.
-     */
-    cache?: Record<string, unknown>;
-    /** Per-instance user-typed values that need to survive reload (e.g. encrypted API keys
-     *  the user entered into a form-style action block). Action blocks own the shape. */
-    userInputs?: Record<string, any>;
-    /**
-     * Advisory oracle reports written by the flow manager, keyed by service
-     * role (e.g. 'evaluation-report'). Service receipts are NOT execution
-     * results: they never touch the node's own state/output and are optional
-     * input to the human decision, not a blocker.
-     */
-    serviceReports?: Record<string, NodeServiceReport>;
-    claimId?: string;
-    submittedByDid?: DID;
-    evaluationStatus?: EvaluationStatus;
-    executionTimestamp?: number;
-}
-interface FlowNodeBase {
-    id: string;
-    type: string;
-    props: Record<string, any>;
-    activationCondition?: {
-        upstreamNodeId: string;
-        requiredStatus: EvaluationStatus;
-    };
-}
-type FlowNode = FlowNodeBase & FlowNodeAuthzExtension;
-
 /**
  * UCAN types for @ixo/ucan integration
  *
@@ -5080,6 +5100,14 @@ interface StoredInvocation {
     executedAt: number;
     /** Flow ID context */
     flowId: string;
+    /**
+     * Session run that produced this invocation.
+     *
+     * Optional for records written before multi-run storage. New execution
+     * surfaces must populate it so audit/status queries cannot mix concurrent
+     * runs of the same flow.
+     */
+    sessionRunId?: string;
     /** Block ID if block-level execution */
     blockId?: string;
     /** Execution result */
@@ -5430,7 +5458,7 @@ interface UcanService {
     getAllDelegations: () => StoredDelegation[];
     getRootDelegation: () => StoredDelegation | null;
     createAndValidateInvocation: (params: CreateInvocationParams, flowId: string, blockId?: string) => Promise<InvocationResult>;
-    executeWithInvocation: <T>(params: CreateInvocationParams, action: () => Promise<T>, flowId: string, blockId?: string) => Promise<ExecutionWithInvocationResult & {
+    executeWithInvocation: <T>(params: CreateInvocationParams, action: () => Promise<T>, flowId: string, blockId?: string, sessionRunId?: string) => Promise<ExecutionWithInvocationResult & {
         actionResult?: T;
     }>;
     validateDelegationChain: (audienceDid: string, capability: UcanCapability) => Promise<DelegationChainValidationResult>;
@@ -5519,9 +5547,36 @@ interface IxoEditorType<BSchema extends IxoBlockSchema = IxoBlockSchema, ISchema
     _yFlow?: Array$1<any>;
     /**
      * Y.Map for runtime per-node state (claim status, timestamps, etc.)
+     *
+     * This is the pre-runs FLAT map, keyed by blockId. It is still a live write
+     * target for already-deployed clients, so every run-scoped write mirrors into
+     * it and every run-scoped read falls back to it
+     * (`core/lib/flowEngine/runs.ts`). Prefer `readActionState` /
+     * `writeActionState` over touching this handle directly.
+     *
+     * PHASE A COMPAT — REMOVAL TRIGGER: when `writeActionState` no longer mirrors
+     * to the flat map (runs.ts compat register item 1).
      * @internal
      */
     _yRuntime?: Map<any>;
+    /**
+     * Y.Map of runs: `runId → Y.Map { meta, actions }`, where `actions` is a
+     * `Y.Map<blockId, FlowNodeRuntimeState>` of PLAIN objects. Empty until an
+     * actor starts a session or migrates a legacy flow — runs are never created
+     * by opening a document or by writing to it.
+     *
+     * Containers are re-resolved from the doc on every access inside `runs.ts` —
+     * never cache the nested `actions` map across a tick, because a losing
+     * concurrent-create merge orphans the reference and writes vanish silently.
+     * @internal
+     */
+    _yRuns?: Map<any>;
+    /**
+     * Y.Map of write-once terminal (closed/cancelled) latches per run. Phase B
+     * writes it; Phase A only attaches it so the shape lands.
+     * @internal
+     */
+    _yRunsTerminal?: Map<any>;
     /**
      * Y.Map for per-node semantic context records written by the flow manager
      * (keyed by block/node id, see NodeContextRecord)
@@ -5559,6 +5614,8 @@ interface IxoEditorType<BSchema extends IxoBlockSchema = IxoBlockSchema, ISchema
      * @internal
      */
     _yAgentLeases?: Map<any>;
+    /** Host-provided Matrix run timeline. */
+    _runEventLog?: RunEventAppender;
     /**
      * Y.Map for queued Xero invoice/payment work items.
      * @internal
@@ -5759,6 +5816,2434 @@ interface IxoBlockProps<TBlock = any> {
     block: TBlock;
 }
 
+interface FlowRuntimeStateManager {
+    get: (nodeId: string) => FlowNodeRuntimeState;
+    update: (nodeId: string, updates: Partial<FlowNodeRuntimeState>) => void;
+}
+/**
+ * The small, public Y.Doc surface needed to clear execution state.
+ *
+ * Keeping this structural prevents a linked consumer with a compatible Yjs
+ * minor version from inheriting this package's private Y.Doc type identity.
+ * Template cleanup only needs map iteration/deletion and one transaction.
+ */
+interface TemplateCloneDocument {
+    getMap(name?: string): {
+        forEach(callback: (value: unknown, key: string) => void): void;
+        delete(key: string): void;
+    };
+    transact(callback: () => void): void;
+}
+/**
+ * `FlowRuntimeStateManager` for an editor.
+ *
+ * IGNITION PHASE A: when a Y.Doc is reachable this delegates to the run-scoped
+ * manager (`runs.ts#createRunScopedRuntimeManager`), so every `update()` made
+ * through it dual-writes the run entry and the flat mirror in one transaction,
+ * and every `get()` resolves the two through the freshness predicate. That is
+ * what makes a *downgrade* — a reset, an unchecked box, a read-back proof
+ * failure — visible on both sides; a flat-only downgrade can never be
+ * materialised into the run and would strand the stale higher state forever
+ * (§9.3 The adoption gate).
+ *
+ * The name is kept because it is public API (`src/index.ts`, `src/core/index.ts`).
+ *
+ * The two non-doc branches are unchanged on purpose: a duck-typed `_yRuntime`
+ * (test stubs, mocks) still gets a plain map manager, and a handle-less editor
+ * still gets the historical in-memory manager rather than a throw — narrowing
+ * that contract is a separate, breaking change.
+ */
+declare const createRuntimeStateManager: (editor?: IxoEditorType | null, runId?: string) => FlowRuntimeStateManager;
+/**
+ * `FlowRuntimeStateManager` for a Y.Doc.
+ *
+ * IGNITION PHASE A: a thin alias for the run-scoped manager over the active
+ * run. Kept as a named export because it is public API and both orchestrators
+ * (flow-manager, flow-agent) import it.
+ */
+declare const createYDocRuntimeManager: (yDoc: Doc, runId?: string) => FlowRuntimeStateManager;
+/**
+ * Clears runtime, invocations, and pending invocations from a Y.Doc.
+ * Used when cloning a flow as a template — the new document should
+ * carry only configuration (intent), not execution history.
+ *
+ * The audit trail (which now also holds run records as `type: 'block.run'`
+ * entries) and pending invocations are observation, not configuration —
+ * both are cleared on template clone.
+ *
+ * `barrierState` belongs to the same class and was missing here: a partially
+ * filled barrier (`block.event.all`) survived the clone, so a single source
+ * firing in the clone could satisfy the barrier using entries emitted in the
+ * *source* flow and queue an invocation whose merged payload mixes two flows.
+ *
+ * `dmNotificationState` is dedup bookkeeping about DMs that were sent for the
+ * source flow's execution; carrying it into a clone suppresses the clone's
+ * first legitimate notification for every block already notified upstream.
+ *
+ * `runs` and `runsTerminal` are where that same execution state now lives
+ * (Ignition Phase A). Clearing the flat `runtime` map without clearing `runs`
+ * would leave the clone pre-completed for every adopted block. Deleting the
+ * outer run key is sufficient — the nested per-run maps go with it.
+ *
+ * `qi.flow.connectionBindings` names one workspace's connected accounts, so it
+ * is cleared too: a clone that kept them would point at a Xero organisation its
+ * own members hold no grant for, and would read as connected while every call
+ * through it fails. The requirements themselves (`qi.flow.connections`) are
+ * configuration and survive, exactly like the participant roster.
+ */
+declare function clearRuntimeForTemplateClone(yDoc: TemplateCloneDocument): void;
+
+/**
+ * Run record stored in the audit trail as `type: 'block.run'`.
+ *
+ * Per Phase 0 #2 (eng review pass 2), run records are NOT a parallel
+ * `_yRunHistory` structure — they ride on the existing `auditTrail` Y.Map
+ * via `useAuditTrail.addEvent`. The shape below is what goes into the
+ * audit trail event's `details` field.
+ *
+ * See `docs/flow-engine/events-and-triggers-plan.md` §3.4, §18, §19.
+ */
+interface RunRecordDetails {
+    /**
+     * Stable identifier for **this execution**, deterministic from invocation
+     * context (`run-<ts>-<rand>` / `readback-<ts>-<rand>`).
+     *
+     * D2 — **NOT the session run, and never renamed.** This is persisted data in
+     * live rooms and it is the `sourceRunId` component of
+     * `computePendingInvocationId`; renaming it forks that join and the same
+     * logical event queues twice. New code calls this the *execution* id and
+     * uses {@link RunRecordDetails.sessionRunId} for the session run.
+     */
+    runId: string;
+    /**
+     * The session run (`runs.ts`) this execution belonged to. Phase A writes it
+     * additively and **nothing reads it** — it exists so Phase B's per-run
+     * history attribution is free, and it deliberately does not participate in
+     * `computePendingInvocationId` (moving the id space is Phase B, together with
+     * `pendingInvocations` and `barrierState`).
+     */
+    sessionRunId?: string;
+    /** Action's output. */
+    output: Record<string, unknown>;
+    /**
+     * Events the action emitted on this run. Persisted as part of the run
+     * record so the reconciliation loop can process them idempotently — even
+     * across page refreshes and across multiple clients.
+     */
+    events: Array<{
+        name: string;
+        payload: Record<string, unknown>;
+    }>;
+    /** ISO timestamp when the action started. */
+    startedAt: string;
+    /** ISO timestamp when the action completed (success or failure). */
+    completedAt: string;
+    /** DID of the actor who signed the invocation that produced this run. */
+    actorDid: string;
+    /** UCAN invocation CID when execution produced one. */
+    invocationCid?: string;
+    /** Capability/proof CID used when no invocation CID was produced. */
+    capabilityId?: string;
+    /** Optional error if the run failed. */
+    error?: {
+        message: string;
+        code?: string;
+    };
+    /** External read-back metadata associated with this run or reconciliation. */
+    readBack?: Record<string, unknown>;
+    /** True when this audit entry was written by external read-back reconciliation. */
+    reconciled?: boolean;
+    /**
+     * If this run was triggered by a pending invocation (i.e. it's a listener
+     * run), the id of that pending invocation. Used to dedup replays and trace
+     * causality back through `triggeredBy`.
+     */
+    fromPendingInvocationId?: string;
+    /**
+     * If this run is a listener run, the (sourceBlockId, eventName) that
+     * caused it. Used by the failure visibility surface to attribute failures
+     * back to the source block (CP-1).
+     */
+    triggeredBy?: {
+        sourceBlockId: string;
+        eventName: string;
+    };
+    /** Source run id for listener runs, stored explicitly for failure lookups. */
+    sourceRunId?: string;
+}
+declare const RUN_RECORD_AUDIT_TYPE = "block.run";
+/**
+ * Pending invocation queued on a listener block.
+ *
+ * Stored in `_yPendingInvocations: Y.Map<blockId, Y.Map<id, PendingInvocation>>`.
+ *
+ * The id is deterministic — derived from
+ * `(sourceBlockId, sourceRunId, listenerBlockId, eventName, eventIndex)` —
+ * so the reconciliation loop can run idempotently from multiple clients
+ * without producing duplicates.
+ *
+ * See `docs/flow-engine/events-and-triggers-plan.md` §3.4, §3.5.1, §18.
+ */
+interface PendingInvocation {
+    /** Deterministic id, see `computePendingInvocationId`. */
+    id: string;
+    /** Block that emitted the event. */
+    triggeringBlockId: string;
+    /** Run id of the triggering source run, used for the deterministic id. */
+    sourceRunId: string;
+    /** Session run that owns this queue entry. Required by Phase B writers. */
+    sessionRunId?: string;
+    /** Event name from the source action's vocabulary. */
+    eventName: string;
+    /** Event index within the source run's `events` array (a single run can emit multiple). */
+    eventIndex: number;
+    /**
+     * The frozen event payload, captured by value at emission time. The
+     * assignee invokes the listener against this payload, not against the
+     * source block's current state. This is the property that makes the
+     * Sally → Mike scenario produce 10 distinct emails even when Mike acts
+     * on them all hours later.
+     */
+    payload: Record<string, unknown>;
+    /**
+     * Snapshots of `nodeId.output.*` ref values that the listener's inputs
+     * reference, captured at queue time. Keyed by the full ref string.
+     *
+     * §3.5.1: ref snapshots are the load-bearing fix for the lag-time
+     * overwrite scenario. If a listener references a non-trigger block's
+     * output (e.g. `evaluateBlock.output.claimId`), that value is captured
+     * here at queue time. Resolution at invocation time prefers the snapshot
+     * over current state, so multiple queued invocations don't drift when
+     * the source re-runs.
+     */
+    refSnapshots: Record<string, unknown>;
+    /** DID of the assigned actor who must invoke this listener. Resolved from `props.assignment.assignedActor.did`. */
+    assigneeDid: string;
+    /** ISO timestamp when the source emission happened. */
+    emittedAt: string;
+    /** ISO timestamp after which this pending invocation is considered expired. Resolved from `FlowCapability.ttl` at queue time. */
+    expiresAt: string;
+}
+/**
+ * Compute a deterministic id for a pending invocation from its content.
+ *
+ * The same (sourceBlockId, sourceRunId, listenerBlockId, eventName,
+ * eventIndex) tuple always produces the same id. This is the property that
+ * makes the reconciliation loop idempotent — re-running it from a different
+ * client, or after a page refresh, produces the same `Y.Map.set` operation
+ * with the same key, which Yjs converges to a single entry.
+ *
+ * Implementation: simple deterministic string concatenation, hashed via a
+ * 32-bit FNV-1a. The id is short and stable; collision risk within a single
+ * flow is negligible because the inputs are scoped (block ids are unique
+ * within a flow, run ids are unique within a block).
+ */
+declare function computePendingInvocationId(args: {
+    sourceBlockId: string;
+    sourceRunId: string;
+    listenerBlockId: string;
+    eventName: string;
+    eventIndex: number;
+    sessionRunId?: string;
+}): string;
+/**
+ * Walk an inputs object and collect every RuntimeRef of the form
+ * `nodeId.output.fieldPath`. Returns a map of `{refString: resolvedValue}`
+ * suitable for storing as `PendingInvocation.refSnapshots`.
+ *
+ * The walker mirrors `resolveRuntimeRefs` in `flowCompiler/resolveRefs.ts`
+ * but reads instead of resolving — it captures the current value of each
+ * ref so the listener can later resolve against the snapshot rather than
+ * against current state.
+ *
+ * See `docs/flow-engine/events-and-triggers-plan.md` §3.5.1.
+ */
+declare function snapshotInputRefs(inputs: unknown, getNodeOutput: (nodeId: string) => Record<string, unknown> | undefined): Record<string, unknown>;
+/**
+ * Get the top-level pending invocations Y.Map from the editor's yDoc.
+ * Lazily creates it if missing.
+ *
+ * Shape: `Y.Map<blockId, Y.Map<pendingInvocationId, PendingInvocation>>`.
+ * The outer map is keyed by listener block id; the inner map is keyed by
+ * deterministic pending invocation id (see `computePendingInvocationId`).
+ */
+declare function getPendingInvocationsMap(yDoc: Y.Doc, sessionRunId?: string): Y.Map<Y.Map<unknown>>;
+/**
+ * Count all pending invocations in one session run without materialising any
+ * missing CRDT containers.
+ */
+declare function countPendingInvocations(yDoc: Y.Doc, sessionRunId?: string): number;
+/**
+ * Get the inner pending-invocations map for a specific listener block.
+ * Lazily creates it if missing. Caller is responsible for being inside a
+ * Yjs transaction if atomic creation matters.
+ */
+declare function getOrCreateBlockPendingMap(yDoc: Y.Doc, blockId: string, sessionRunId?: string): Y.Map<unknown>;
+/**
+ * Read all pending invocations for a block as plain JS objects.
+ * Returns an array sorted by `emittedAt` ascending (oldest first).
+ */
+declare function readPendingInvocations(yDoc: Y.Doc, blockId: string, sessionRunId?: string): PendingInvocation[];
+/**
+ * Idempotently write a pending invocation under its deterministic id.
+ *
+ * Returns true if a new entry was created, false if the id already
+ * existed (meaning another client or a previous reconciliation pass
+ * already queued this invocation). This is the property that makes
+ * `reconcilePendingInvocations` safe to run from multiple clients
+ * simultaneously and across page refreshes — see plan §18.
+ *
+ * Wraps the write in a Yjs transaction so the existence check and the
+ * subsequent set are atomic from the local client's perspective. Concurrent
+ * clients each computing the same id will all converge to a single entry
+ * because Y.Map.set with the same key is last-writer-wins on identical
+ * content.
+ */
+declare function queuePendingInvocation(yDoc: Y.Doc, listenerBlockId: string, invocation: PendingInvocation, sessionRunId?: string): boolean;
+/**
+ * Remove a pending invocation by id. Used when the assignee completes the
+ * invocation (transitioning to a `block.run` audit trail entry) or when
+ * the expiration sweep marks it as expired.
+ */
+declare function removePendingInvocation(yDoc: Y.Doc, listenerBlockId: string, pendingInvocationId: string, sessionRunId?: string): boolean;
+/**
+ * Append a run record to the audit trail for a block. Run records are
+ * stored as audit trail events with `type: 'block.run'` and the structured
+ * data in `details`. Per Phase 0 #2 of eng review pass 2, this avoids
+ * inventing a parallel `_yRunHistory` storage system.
+ *
+ * Y.Array.push from concurrent clients merges correctly — verified by the
+ * existing `useAuditTrail` shipping in production.
+ */
+declare function appendRunRecord(yDoc: Y.Doc, blockId: string, details: RunRecordDetails, userId: string): void;
+/**
+ * Read all run records for a block from the audit trail. Filters audit
+ * trail entries to only those with `type: 'block.run'`.
+ */
+declare function readRunRecords(yDoc: Y.Doc, blockId: string, sessionRunId?: string): RunRecordDetails[];
+/**
+ * A failed listener run, attributed to the source block emission that
+ * triggered it. Used by the failure visibility surface (CP-1) on source
+ * blocks: the source block can show "N listeners failed for your last run".
+ */
+interface FailedListenerRun {
+    /** Block id of the listener whose run failed. */
+    listenerBlockId: string;
+    /** The full RunRecordDetails of the failed listener invocation. */
+    record: RunRecordDetails;
+}
+/**
+ * Find all failed listener runs that were triggered by a specific source
+ * block run. Walks every block's audit trail, filters to listener runs
+ * triggered by (sourceBlockId, sourceRunId), and returns the ones with an
+ * error set.
+ *
+ * Used by the source block UI to show a failure badge linked to a specific
+ * run — if Sally evaluates 10 claims and 2 of Mike's emails fail, Sally
+ * sees "2 failed listeners on claim-G" rather than discovering it days
+ * later in the email service logs.
+ */
+declare function findFailedListenersForSourceRun(yDoc: Y.Doc, sourceBlockId: string, sourceRunId: string, listenerBlockIds: string[]): FailedListenerRun[];
+/**
+ * Replay a previously failed listener run by re-queueing a pending
+ * invocation with the same content. Reuses the original frozen payload
+ * and ref snapshots from the failed run record's audit trail entry, so the
+ * replay sees exactly the same data the original invocation saw.
+ *
+ * CP-2 from the plan. Used by the replay button in the failure visibility
+ * surface. Returns true if a new pending invocation was queued.
+ *
+ * Note: replay does NOT re-derive the deterministic id from the original
+ * source emission, because the original pending invocation's id is already
+ * present (or removed) in the pendingInvocations Y.Map. Instead, replay
+ * generates a fresh id by appending a `:replay-N` suffix to the original.
+ * This means the replay creates a NEW pending invocation that the assignee
+ * can act on, separate from any history of the original.
+ */
+declare function replayFailedListenerRun(yDoc: Y.Doc, failedRecord: RunRecordDetails, listenerBlockId: string, originalPayload: Record<string, unknown>, originalRefSnapshots: Record<string, unknown>, assigneeDid: string, sessionRunId?: string): boolean;
+
+/**
+ * The raw consumer handler bag (mantine `BlocknoteHandlers`), as visible to
+ * action `run()` implementations via `ctx.handlers`. The real interface lives
+ * in the mantine layer and cannot be imported here without a core→mantine
+ * cycle, so this declares only the members actions actually call — loosely
+ * typed, since the parameter shapes are owned by the consumer contract.
+ *
+ * There is deliberately NO index signature: calling an undeclared handler is a
+ * compile error, so a renamed consumer handler surfaces here instead of
+ * failing at runtime. Add the member when an action starts using a new
+ * handler. Prefer `ctx.services.*` (the typed, adapted contract) over
+ * `ctx.handlers` for new actions — this escape hatch exists for actions that
+ * predate `buildServicesFromHandlers`.
+ */
+interface ActionHandlers {
+    askCompanion?: (prompt: string) => Promise<any>;
+    vote?: (...args: any[]) => any;
+    getPreProposalContractAddress?: (...args: any[]) => any;
+    getGroupContractAddress?: (...args: any[]) => any;
+    getProposalContractAddress?: (...args: any[]) => any;
+    createProposal?: (...args: any[]) => any;
+    getUserRoles?: (...args: any[]) => any;
+    getClaimData?: (...args: any[]) => any;
+    requestPin?: (...args: any[]) => any;
+    signCredential?: (...args: any[]) => any;
+    publicFileUpload?: (...args: any[]) => any;
+    createDomain?: (...args: any[]) => any;
+    createAddLinkedResourceMessage?: (...args: any[]) => any;
+    executeTransaction?: (...args: any[]) => any;
+    createGovernanceGroup?: (...args: any[]) => any;
+    getEntityDid?: (...args: any[]) => any;
+    getCurrentUser?: (...args: any[]) => any;
+    createAddLinkedEntityMessage?: (...args: any[]) => any;
+    sourceDomainSpaces?: (...args: any[]) => any;
+    importProtocolTemplatesToSpace?: (...args: any[]) => any;
+    integrations?: {
+        executeTool?: (...args: any[]) => any;
+        fetchCurrentState?: (...args: any[]) => any;
+        getEntityDid?: (...args: any[]) => any;
+    };
+}
+interface ActionContext {
+    actorDid: string;
+    flowId: string;
+    /** Explicit session run; distinct from an individual action execution id. */
+    sessionRunId?: string;
+    nodeId: string;
+    services: ActionServices;
+    flowNode?: FlowNode;
+    runtime?: FlowRuntimeStateManager;
+    flowUri?: string;
+    handlers?: ActionHandlers;
+    editor?: IxoEditorType;
+    /**
+     * The flow document. Present on both execution paths — `editor` is undefined
+     * headless, so an action that needs flow-level configuration (the connection
+     * bindings, say) has to read it from here rather than from the editor.
+     */
+    yDoc?: Doc;
+    pendingInvocation?: PendingInvocation;
+}
+/**
+ * Lifecycle state of an IXO claims-module collection.
+ *
+ * Mirrors `ixo.claims.v1beta1.CollectionState` (the on-chain enum). Carried as
+ * a numeric enum at this boundary so the consumer-side handler can map it
+ * directly onto the SDK enum without a string lookup.
+ *
+ * - `OPEN`    (0) — accepting claims/bids.
+ * - `PAUSED`  (1) — temporarily not accepting submissions.
+ * - `CLOSED`  (2) — permanently closed.
+ */
+declare enum CollectionStateEnum {
+    OPEN = 0,
+    PAUSED = 1,
+    CLOSED = 2
+}
+/**
+ * A single coin amount. Mirrors `cosmos.base.v1beta1.Coin`. `amount` is the
+ * integer base-denom amount carried as a string (no `Long`/`bigint` at this
+ * boundary).
+ */
+interface CollectionCoin {
+    denom: string;
+    amount: string;
+}
+/**
+ * A CW20 token payment leg. Mirrors `ixo.claims.v1beta1.CW20Payment`.
+ */
+interface CollectionCW20Payment {
+    address: string;
+    /** Integer amount carried as a string. */
+    amount: string;
+}
+/**
+ * A CW1155 contract payment leg. Mirrors `ixo.claims.v1beta1.Contract1155Payment`.
+ */
+interface CollectionContract1155Payment {
+    address: string;
+    tokenId: string;
+    /** Integer amount carried as a string. */
+    amount: string;
+}
+/**
+ * One payment leg of a collection (submission / evaluation / approval /
+ * rejection). Mirrors `ixo.claims.v1beta1.Payment`.
+ *
+ * Optional/empty legs are represented by an empty `amount` array. The consumer
+ * handler fills `account` with the collection admin address when creating.
+ */
+interface CollectionPayment {
+    /** Destination/charging account address. */
+    account: string;
+    /** Native-coin amounts. Empty when this leg charges nothing in native coin. */
+    amount: CollectionCoin[];
+    /** Optional CW20 payment legs. */
+    cw20Payment?: CollectionCW20Payment[];
+    /** Optional CW1155 contract payment. */
+    contract_1155Payment?: CollectionContract1155Payment;
+    /** Optional payment timeout in nanoseconds, carried as a string. */
+    timeoutNs?: string;
+    /** Whether this leg is paid by the oracle rather than the claimant. */
+    isOraclePayment?: boolean;
+}
+/**
+ * The four payment legs of a collection. Mirrors `ixo.claims.v1beta1.Payments`.
+ */
+interface Payments {
+    submission?: CollectionPayment;
+    evaluation?: CollectionPayment;
+    approval?: CollectionPayment;
+    rejection?: CollectionPayment;
+}
+/**
+ * Per-intent configuration for a collection. Mirrors the
+ * `ixo.claims.v1beta1.CollectionIntentOptions` shape — controls whether/how
+ * claimants can declare an intent before submitting.
+ */
+interface CollectionIntentOptions {
+    /** Whether intents are enabled on this collection. */
+    allowed?: boolean;
+    /** Optional intent timeout in nanoseconds, carried as a string. */
+    timeoutNs?: string;
+    /** Optional per-intent payment override. */
+    payment?: CollectionPayment;
+}
+/**
+ * Parameters for creating a collection (`MsgCreateCollection`).
+ *
+ * `entity` and `protocol` are template configuration; the consumer resolves the
+ * `signer`/admin from its own wallet context, so it is not part of this
+ * boundary. `quota` is carried as a string (`0` = unlimited).
+ */
+interface CollectionCreateParams {
+    /** Entity (deed) DID the collection belongs to. */
+    entity: string;
+    /** Protocol DID/id the collection follows. */
+    protocol: string;
+    /** Initial lifecycle state. Defaults to OPEN if omitted by the consumer. */
+    state?: CollectionStateEnum;
+    /** ISO-8601 start date. */
+    startDate?: string;
+    /** ISO-8601 end date. */
+    endDate?: string;
+    /** Max number of claims; `0` = unlimited. Carried as a string. */
+    quota?: string;
+    /** Payment configuration for the four claim legs. */
+    payments?: Payments;
+    /** Intent configuration. */
+    intents?: CollectionIntentOptions;
+}
+/**
+ * The full, canonical on-chain state of a collection, returned by every
+ * `collection.*` operation (read or write) and stored verbatim as
+ * `runtime.output`. It is never a delta — see IXO-2573: `output` always holds
+ * the latest full on-chain collection state.
+ *
+ * Field names mirror `ixo.claims.v1beta1.Collection`. Numeric chain types
+ * (`Long`/uint64) are carried as strings; `state` is the numeric enum.
+ */
+interface CollectionState {
+    /** Collection identifier (the chain-assigned id). */
+    collectionId: string;
+    /** Entity (deed) DID the collection belongs to. */
+    entity: string;
+    /** Protocol DID/id the collection follows. */
+    protocol: string;
+    /** Admin address authorised to mutate the collection. */
+    admin?: string;
+    /** Current lifecycle state. */
+    state: CollectionStateEnum;
+    /** ISO-8601 start date, if set. */
+    startDate?: string;
+    /** ISO-8601 end date, if set. */
+    endDate?: string;
+    /** Max number of claims; `0` = unlimited. Carried as a string. */
+    quota: string;
+    /** Number of claims submitted so far. Carried as a string. */
+    count: string;
+    /** Number of claims evaluated so far. Carried as a string. */
+    evaluated?: string;
+    /** Number of approved claims. Carried as a string. */
+    approved?: string;
+    /** Number of rejected claims. Carried as a string. */
+    rejected?: string;
+    /** Number of disputed claims. Carried as a string. */
+    disputed?: string;
+    /** Payment configuration for the four claim legs. */
+    payments?: Payments;
+    /** Intent configuration. */
+    intents?: CollectionIntentOptions;
+}
+/**
+ * Role a grantee holds on a claim collection. Drives which custom claims-module
+ * authorization is granted: `submit` → `SubmitClaimAuthorization`,
+ * `evaluate` → `EvaluateClaimAuthorization` (each carries `[]constraints`, one
+ * per collection). See IXO-2586.
+ */
+type CollectionUserRole = 'submit' | 'evaluate';
+/**
+ * One per-collection authorization constraint held by a grantee for a role.
+ * Carries the LIVE (decremented) limits as read back from chain — the revoke
+ * read-modify-write must preserve these verbatim (IXO-2590), so re-granting
+ * from a template would wrongly reset spent quota.
+ */
+interface CollectionGrantee {
+    /** Grantee bech32 address. */
+    address: string;
+    /** Optional resolved DID (display / audit). */
+    did?: string;
+    /** Role this grant confers. */
+    role: CollectionUserRole;
+    /** Remaining agent quota; `0` = unlimited. Carried as a string. */
+    agentQuota?: string;
+    /** Per-claim max amount cap (evaluate role). */
+    maxAmount?: CollectionCoin[];
+    /** Intent duration in nanoseconds, carried as a string. */
+    intentDurationNs?: string;
+}
+/**
+ * A member enumerated from a group account, used for grant fan-out. Mirrors the
+ * `PODMember` shape produced by the `pod/memberMultiSelect` enumeration
+ * (abstracts cw4 members / token-staking stakers / nft-staking / multisig
+ * signers).
+ */
+interface CollectionMember {
+    address: string;
+    did?: string;
+    role?: string;
+    votingPower?: number;
+}
+/**
+ * DAO DAO classification of an address. On IXO both user accounts and CosmWasm
+ * contracts share the `ixo1…` prefix, so classification is layered: bech32
+ * byte-length heuristic → Wasm `ContractInfo` query → cw2 `{ "info": {} }`
+ * smart query (IXO-2592).
+ */
+interface AddressClassification {
+    /** `user` = plain account; `contract` = CosmWasm contract / module account. */
+    kind: 'user' | 'contract';
+    /** Present when `kind === 'contract'` and cw2 info resolved a DAO DAO group type. */
+    daodao?: {
+        /** cw2 contract name family, e.g. `dao-dao-core`, `cw4-group`, `dao-voting-cw4`. */
+        type: string;
+        /** Whether the contract can itself exercise a granted authz (only dao-core can MsgExec). */
+        canExerciseGrant: boolean;
+    };
+}
+/**
+ * Provenance/identity of a carbon batch (= a CARBON token group; the batch id
+ * is the on-chain token id). `entityDid` + `adminAddress` identify the entity
+ * admin account the batch was minted from — both are REQUIRED to construct a
+ * harvest (the authz grant + exec transfer target that account). The host
+ * `loadBatches` handler performs provenance recovery for transferred batches so
+ * these are populated before the editor ever sees them. See the carbon-credit
+ * technical doc §4–§5 (IXO-2675).
+ */
+interface CarbonBatchRef {
+    /** Token/batch id. */
+    id: string;
+    /** Minter entity DID. */
+    entityDid: string;
+    /** Entity admin account address (the FROM account for a harvest transfer). */
+    adminAddress: string;
+    /** Human-readable entity name, for display. */
+    alsoKnownAs?: string;
+}
+/**
+ * A harvestable batch: held on an entity admin account the user owns but not
+ * yet pulled into their wallet. `claimable` = the admin-held amount that
+ * becomes the user's on harvest.
+ */
+interface CarbonHarvestableBatch extends CarbonBatchRef {
+    /** Harvestable amount (admin-held; becomes user `amount` after harvest). */
+    claimable: number;
+}
+/**
+ * A retireable batch: credits the user already holds in their wallet and can
+ * burn/offset. `entityDid` is best-effort (display/provenance) and not required
+ * to retire — retirement is a single owner-signed message.
+ */
+interface CarbonRetireableBatch {
+    /** Token/batch id. */
+    id: string;
+    /** Amount available in the user's wallet to retire. */
+    amount: number;
+    /** Minter entity DID, when known. */
+    entityDid?: string;
+    /** Human-readable entity name, for display. */
+    alsoKnownAs?: string;
+}
+interface HttpService {
+    request: (params: {
+        url: string;
+        method: string;
+        headers?: Record<string, string>;
+        body?: any;
+    }) => Promise<{
+        status: number;
+        headers: Record<string, string>;
+        data: any;
+    }>;
+}
+interface EmailService {
+    send: (params: {
+        to: string;
+        subject: string;
+        template: string;
+        templateVersion?: string;
+        variables?: Record<string, any>;
+        cc?: string;
+        bcc?: string;
+        replyTo?: string;
+    }) => Promise<{
+        messageId: string;
+        sentAt: string;
+    }>;
+}
+interface NotifyService {
+    send: (params: {
+        channel: string;
+        to: string[];
+        cc?: string[];
+        bcc?: string[];
+        subject?: string;
+        body?: string;
+        bodyType?: 'text' | 'html';
+        from?: string;
+        replyTo?: string;
+    }) => Promise<{
+        messageId: string;
+        sentAt: string;
+    }>;
+}
+interface BidService {
+    submitBid: (params: {
+        collectionId: string;
+        role: string;
+        surveyAnswers: Record<string, any>;
+        entityDid?: string;
+        onBehalfOfAddress?: string;
+    }) => Promise<any>;
+    approveBid: (params: {
+        bidId: string;
+        collectionId: string;
+        did: string;
+        entityDid?: string;
+    }) => Promise<any>;
+    rejectBid: (params: {
+        bidId: string;
+        collectionId: string;
+        did: string;
+        reason: string;
+        entityDid?: string;
+    }) => Promise<any>;
+    approveServiceAgentApplication: (params: {
+        adminAddress: string;
+        collectionId: string;
+        agentQuota: number;
+        deedDid: string;
+        currentUserAddress: string;
+    }) => Promise<void>;
+    approveEvaluatorApplication: (params: {
+        adminAddress: string;
+        collectionId: string;
+        deedDid: string;
+        evaluatorAddress: string;
+        agentQuota?: number;
+        claimIds?: string[];
+        maxAmounts?: Array<{
+            denom: string;
+            amount: string;
+        }>;
+    }) => Promise<void>;
+}
+interface ClaimService {
+    requestPin: (config?: {
+        title?: string;
+        description?: string;
+        submitText?: string;
+    }) => Promise<string>;
+    submitClaim: (params: {
+        surveyData: any;
+        deedDid: string;
+        collectionId: string;
+        adminAddress: string;
+        pin: string;
+        entityDid?: string;
+    }) => Promise<{
+        transactionHash: string;
+        claimId: string;
+    }>;
+    evaluateClaim: (granteeAddress: string, did: string, payload: {
+        claimId: string;
+        collectionId: string;
+        adminAddress: string;
+        status?: number;
+        verificationProof: string;
+        amount?: {
+            denom: string;
+            amount: string;
+        };
+    }) => Promise<{
+        code: number;
+        transactionHash: string;
+        rawLog?: string;
+        height?: number;
+        txIndex?: number;
+        gasWanted?: bigint;
+        gasUsed?: bigint;
+    }>;
+    disputeClaim?: (granteeAddress: string, did: string, payload: {
+        subjectId: string;
+        disputeType: number;
+        reason: string;
+    }) => Promise<any>;
+    getCurrentUser: () => {
+        address: string;
+        did?: string;
+    };
+    createUdid?: (params: any) => Promise<any>;
+}
+/**
+ * Claims-module collection lifecycle service. The editor declares the
+ * contract only; the consumer app implements each method (broadcast on chain,
+ * resolve admin from its wallet context, map string<->Long).
+ *
+ * Per IXO-2573, each write op should broadcast then the dispatcher re-fetches
+ * via `get(...)` so `runtime.output` always holds the latest full
+ * `CollectionState`. `get` is the read-only `refresh` primitive.
+ */
+interface CollectionService {
+    /** Read the full current on-chain state of a collection. */
+    get: (params: {
+        collectionId: string;
+    }) => Promise<CollectionState>;
+    /** Broadcast `MsgCreateCollection`. Returns the new collectionId + tx hash. */
+    create: (params: CollectionCreateParams) => Promise<{
+        transactionHash: string;
+        collectionId: string;
+    }>;
+    /** Broadcast `MsgUpdateCollectionState`. */
+    updateState: (params: {
+        collectionId: string;
+        state: CollectionStateEnum;
+        adminAddress: string;
+    }) => Promise<{
+        transactionHash: string;
+    }>;
+    /** Broadcast `MsgUpdateCollectionDates`. */
+    updateDates: (params: {
+        collectionId: string;
+        startDate?: string;
+        endDate?: string;
+        adminAddress: string;
+    }) => Promise<{
+        transactionHash: string;
+    }>;
+    /** Broadcast `MsgUpdateCollectionQuota`. `quota` carried as a string; `0` = unlimited. */
+    updateQuota: (params: {
+        collectionId: string;
+        quota: string;
+        adminAddress: string;
+    }) => Promise<{
+        transactionHash: string;
+    }>;
+    /** Broadcast `MsgUpdateCollectionPayments`. */
+    updatePayments: (params: {
+        collectionId: string;
+        payments: Payments;
+        adminAddress: string;
+    }) => Promise<{
+        transactionHash: string;
+    }>;
+    /** Broadcast `MsgUpdateCollectionIntents`. */
+    updateIntents: (params: {
+        collectionId: string;
+        intents: CollectionIntentOptions;
+        adminAddress: string;
+    }) => Promise<{
+        transactionHash: string;
+    }>;
+}
+/**
+ * Claim-collection user-management service (IXO-2586). The editor declares the
+ * contract only; the consumer app implements each method (build/broadcast the
+ * claims-module authz messages, query authz grants, classify addresses,
+ * enumerate group members). Extends → replaces the reactive `bid` service.
+ */
+interface CollectionUsersService {
+    /**
+     * Grant submit/evaluate authz for ONE collection to a grantee. The handler
+     * reads the grantee's existing authz for the role's msgTypeUrl and APPENDS a
+     * per-collection constraint (preserving other collections' live values),
+     * then broadcasts `MsgCreateClaimAuthorization` routed via
+     * `MsgGrantEntityAccountAuthz` (entity admin = granter). See IXO-2589.
+     */
+    grant: (params: {
+        granterAdminAddress: string;
+        granteeAddress: string;
+        collectionId: string;
+        role: CollectionUserRole;
+        agentQuota?: string;
+        maxAmount?: CollectionCoin[];
+        intentDurationNs?: string;
+        deedDid?: string;
+    }) => Promise<{
+        transactionHash: string;
+    }>;
+    /**
+     * Per-collection read-modify-write revoke (IXO-2590). Reads the grantee's
+     * live authz, drops the target collection's constraint, and — when other
+     * constraints remain — broadcasts a single atomic tx ordered
+     * `[MsgRevokeEntityAccountAuthz, then one MsgCreateClaimAuthorization per
+     * remaining constraint]`, preserving each remaining constraint's live
+     * (decremented) quota/limits. Short-circuits to a plain revoke when the
+     * target was the only constraint.
+     */
+    revoke: (params: {
+        granterAdminAddress: string;
+        granteeAddress: string;
+        collectionId: string;
+        role: CollectionUserRole;
+    }) => Promise<{
+        transactionHash: string;
+    }>;
+    /**
+     * List the grantees holding a submit/evaluate constraint for a collection.
+     * Queries authz grants against the entity admin account, decodes the
+     * authorizations, and filters constraints by `collectionId` (IXO-2591).
+     */
+    list: (params: {
+        granterAdminAddress: string;
+        collectionId: string;
+    }) => Promise<{
+        grantees: CollectionGrantee[];
+    }>;
+    /** Classify an address as a plain user vs a DAO DAO contract (IXO-2592). */
+    classifyAddress: (params: {
+        address: string;
+    }) => Promise<AddressClassification>;
+    /** Enumerate the members of a group account for grant fan-out (IXO-2592). */
+    enumerateMembers: (params: {
+        groupAddress: string;
+    }) => Promise<{
+        members: CollectionMember[];
+    }>;
+}
+interface MatrixCredentialService {
+    storeCredential: (params: {
+        roomId: string;
+        credentialKey: string;
+        credential: Record<string, any>;
+        cid: string;
+    }) => Promise<{
+        storedAt: string;
+        duplicate: boolean;
+    }>;
+}
+/** Result of any integration tool execution (direct or via a binding). */
+interface IntegrationExecuteOutcome {
+    successful: boolean;
+    data?: Record<string, unknown>;
+    error?: string;
+    code?: 'OK' | 'VALIDATION' | 'AUTH_EXPIRED' | 'UPSTREAM_4XX' | 'UPSTREAM_5XX' | 'RATE_LIMIT' | 'UNKNOWN';
+}
+interface IntegrationsService {
+    executeTool: (args: {
+        toolSlug: string;
+        connectedAccountId: string;
+        arguments: Record<string, unknown>;
+    }) => Promise<IntegrationExecuteOutcome>;
+    fetchCurrentState?: (args: {
+        toolSlug: string;
+        connectedAccountId: string;
+        arguments: Record<string, unknown>;
+    }) => Promise<Record<string, unknown>>;
+    getEntityDid?: () => string | undefined;
+    /**
+     * Execute a tool on the template author's behalf via an opaque, server-side
+     * binding (delegated blocks). The runner never holds the author's
+     * credential — `bindingId` selects it on the worker. Returns the same
+     * outcome shape as `executeTool`.
+     */
+    executeBinding?: (args: {
+        bindingId: string;
+        toolSlug: string;
+        arguments: Record<string, unknown>;
+    }) => Promise<IntegrationExecuteOutcome>;
+}
+interface OracleService {
+    generateWallet: () => Promise<{
+        address: string;
+        did: string;
+        pubKey: string;
+        mnemonic: string;
+    }>;
+    fundWallet: (params: {
+        address: string;
+        amount: number;
+    }) => Promise<{
+        transactionHash: string;
+    }>;
+    createIidDocument: (params: {
+        mnemonic: string;
+        did: string;
+        address: string;
+        pubKey: string;
+    }) => Promise<{
+        did: string;
+        transactionHash: string;
+    }>;
+    registerMatrixAccount: (params: {
+        mnemonic: string;
+        address: string;
+        did: string;
+        pin: string;
+        oracleName: string;
+        avatarUrl?: string;
+    }) => Promise<{
+        matrixUserId: string;
+        matrixAccessToken: string;
+        matrixRoomId: string;
+        matrixDeviceId: string;
+        matrixMnemonic: string;
+        matrixPassword: string;
+        matrixRecoveryPhrase: string;
+        matrixHomeServerUrl: string;
+    }>;
+    createOracleEntity: (params: {
+        mnemonic: string;
+        address: string;
+        did: string;
+        pubKey: string;
+        pin: string;
+        matrixAccessToken: string;
+        matrixRoomId: string;
+        oracleName: string;
+        orgName: string;
+        description: string;
+        location: string;
+        logoUrl: string;
+        coverImageUrl: string;
+        apiUrl: string;
+        price: number;
+        llmModel: string;
+        opening?: string;
+        communicationStyle?: string;
+        capabilities?: string;
+        mcpConfig?: any;
+        parentProtocol?: string;
+    }) => Promise<{
+        entityDid: string;
+        transactionHash: string;
+        /** Multibase-encoded P-256 public key registered as a keyAgreement vm on the oracle entity DID. */
+        encryptionPublicKeyMultibase: string;
+        /** DID verification method id of the P-256 keyAgreement key. */
+        encryptionVerificationMethodId: string;
+    }>;
+    /**
+     * Contract the oracle: ensure the user↔oracle Matrix DM room exists and
+     * the user has joined it. Pure Matrix work — no chain calls, no key setup.
+     * Returns the user↔oracle room id which downstream steps (storeSecrets,
+     * storeConfig) write into.
+     */
+    contract: (params: {
+        oracleEntityDid: string;
+    }) => Promise<{
+        userOracleRoomId: string;
+        userOracleRoomAlias: string;
+    }>;
+    provisionSandbox: (params: {
+        entityDid: string;
+        matrixRoomId: string;
+    }) => Promise<{
+        sandboxUrl: string;
+        status: string;
+    }>;
+    storeSecrets: (params: {
+        matrixRoomId: string;
+        publicKeyMultibase: string;
+        verificationMethodId: string;
+        matrixHomeServerUrl: string;
+        matrixUsername: string;
+        matrixPassword: string;
+        secrets: Record<string, string>;
+        preEncryptedSecrets?: Record<string, string>;
+    }) => Promise<{
+        storedSecrets: string[];
+        roomId: string;
+        freshAccessToken?: string;
+    }>;
+    /** JWE-encrypts a single plaintext value to the oracle's P-256 public key (multibase).
+     *  Used by storeSecrets FlowDetail to encrypt user-typed OpenRouter key at-rest. */
+    encryptForOracle: (params: {
+        plaintext: string;
+        publicKeyMultibase: string;
+    }) => Promise<{
+        jwe: string;
+    }>;
+    /** Reads `ixo.room.secret.index` state events from the matrix room and returns the
+     *  list of secret names already stored. Used for idempotency checks. */
+    readStoredSecrets: (params: {
+        matrixRoomId: string;
+    }) => Promise<{
+        secretNames: string[];
+    }>;
+    /** Returns the network-derived .env constants (RPC URL, matrix homeserver, etc.)
+     *  for the consumer's currently configured network. Used by the storeSecrets
+     *  FlowDetail's "Additional Configuration" display section, and merged into the
+     *  storeConfig state event by the consumer handler. Must be deterministic per network. */
+    getNetworkConstants: (params: {
+        oracleName: string;
+    }) => Promise<{
+        constants: Record<string, string>;
+    }>;
+    validateMcpServer: (params: {
+        url: string;
+        authType?: 'bearer' | 'api-key' | 'none';
+        authToken?: string;
+    }) => Promise<{
+        success: boolean;
+        tools?: Array<{
+            name: string;
+            description?: string;
+        }>;
+        error?: string;
+    }>;
+    storeConfig: (params: {
+        matrixRoomId: string;
+        config: {
+            oracleName: string;
+            orgName: string;
+            description: string;
+            location: string;
+            price: number;
+            apiUrl: string;
+            entityDid: string;
+            logoUrl: string;
+            llmModel: string;
+            opening?: string;
+            communicationStyle?: string;
+            capabilities?: string;
+            skills?: string[];
+            mcpServers?: Array<{
+                name: string;
+                url: string;
+                description?: string;
+                authEnvVar?: string;
+            }>;
+            matrixUserId?: string;
+            matrixAccountRoomId?: string;
+            oracleAddress?: string;
+            oracleDid?: string;
+        };
+    }) => Promise<{
+        configStored: boolean;
+        roomId: string;
+    }>;
+    deploySetup: (params: {
+        name: string;
+        config: Record<string, any>;
+        roomId: string;
+        secrets?: Record<string, string>;
+    }) => Promise<{
+        setupComplete: boolean;
+        stdout?: string;
+        stderr?: string;
+    }>;
+    deployStart: (params: {
+        name: string;
+        entityDid: string;
+        roomId: string;
+        secrets?: Record<string, string>;
+    }) => Promise<{
+        processId: string;
+        status: string;
+        url?: string;
+    }>;
+    updateOracleDomain: (params: {
+        entityDid: string;
+        newApiUrl: string;
+    }) => Promise<{
+        transactionHash: string;
+    }>;
+}
+/**
+ * Carbon credit batch service (IXO-2675). The editor declares the contract
+ * only; the consumer app implements each method (run the owner/admin
+ * reconciliation read, build + broadcast the harvest grant/exec pair and the
+ * retire message, sign via its own wallet/SignX). Both writes are USER-signed
+ * — the editor never signs on the user's behalf.
+ */
+interface CarbonService {
+    /**
+     * Reconcile the user's owner-side and entity-admin-side batches into the
+     * unified view. Pure read (no signing). Performs provenance recovery for
+     * transferred batches so every `harvestableBatch` carries `entityDid` +
+     * `adminAddress`. See technical doc §3–§4.
+     */
+    loadBatches: (params: {
+        ownerAddress: string;
+    }) => Promise<{
+        harvestableBatches: CarbonHarvestableBatch[];
+        retireableBatches: CarbonRetireableBatch[];
+        totalClaimable: number;
+        totalAvailable: number;
+        totalRetired: number;
+    }>;
+    /**
+     * Harvest (claim) the given batches: per entity, grant the owner authz to
+     * transfer out of the entity admin account, then exec that transfer into
+     * the owner's wallet (ordered pairs, 30-min grant). User-signed. See §5.2.
+     */
+    harvest: (params: {
+        ownerAddress: string;
+        tokens: Array<{
+            id: string;
+            entityDid: string;
+            adminAddress: string;
+            claimable: number;
+        }>;
+    }) => Promise<{
+        transactionHash: string;
+        harvestedBatchIds: string[];
+        harvestedAmount: number;
+    }>;
+    /**
+     * Retire (burn/offset) the given amounts from the owner's wallet. Single
+     * owner-signed `MsgRetireToken`. Irreversible. `jurisdiction` arrives
+     * pre-composed as a string (default "Global"); `reason` defaults to
+     * "offset". See §5.1.
+     */
+    retire: (params: {
+        owner: string;
+        reason?: string;
+        jurisdiction?: string;
+        tokens: Array<{
+            id: string;
+            amount: number;
+        }>;
+    }) => Promise<{
+        transactionHash: string;
+        retiredBatchIds: string[];
+        retiredAmount: number;
+    }>;
+}
+/**
+ * Entity (domain) ownership service (IXO-2696). The editor declares the
+ * contract only; the consumer app implements `transfer` — resolve a group
+ * recipient to its DAO controller, ensure the recipient has an IID document,
+ * build + broadcast `MsgTransferEntity`, and sign via its own wallet/SignX.
+ * USER-signed and IRREVERSIBLE — the editor never signs on the user's behalf.
+ */
+interface EntityService {
+    /**
+     * Transfer ownership of `entityDid` to `recipientDid`. The consumer resolves
+     * a `did:ixo:entity:` group recipient to its `did:ixo:wasm:` controller
+     * (reported back as `recipientResolved` when changed) and creates the
+     * recipient's IID document first if it is missing (`createdRecipientIid`).
+     * `ownerDid`/`ownerAddress` default to the connected user inside the host.
+     * Proof of a real transfer is the returned `transactionHash`.
+     */
+    transfer: (params: {
+        entityDid: string;
+        recipientDid: string;
+        ownerDid?: string;
+        ownerAddress?: string;
+    }) => Promise<{
+        transactionHash: string;
+        recipientResolved?: string;
+        createdRecipientIid?: boolean;
+    }>;
+}
+/**
+ * KYC verification service (qi/kyc.verify). The editor declares the contract
+ * only; the consumer app implements each method against its KYC server
+ * (create/read the ComplyCube evaluation, mint the hosted verification URL,
+ * persist the SD-JWT credential to the user's Matrix vault). The server's
+ * status is the single source of truth for the lifecycle
+ * (`verify → review → clear → issuing → issued → complete`, failure states
+ * `rejected|attention|error`, plus `unknown`) — the editor only polls it.
+ *
+ * PII boundary: survey answers flow INTO `initiate` but never back out —
+ * action outputs carry only `credentialCid`, `credentialType`, `protocolId`,
+ * and `status`.
+ */
+interface KycService {
+    /**
+     * Load the KYC protocol's details form + the user's current server-side
+     * state. `credentialType` is the vault index key of the credential this
+     * protocol issues (e.g. 'kycamllevel1' | 'kycamllevel2'); hosts default it
+     * to level 1 when omitted — `hasExistingCredential` refers to THAT type
+     * only, so a level-2 flow is never satisfied by a level-1 credential.
+     */
+    loadForm(params: {
+        protocolDid: string;
+        credentialType?: string;
+    }): Promise<{
+        protocolId: string;
+        claimCollectionId?: string;
+        deedOfferId?: string;
+        surveyJson: Record<string, unknown>;
+        hasExistingCredential: boolean;
+        /** Non-PII metadata of matching Vault credentials, oldest first. */
+        existingCredentials?: Array<{
+            cid: string;
+            credentialType: string;
+            storedAt?: string;
+            issuerDid?: string;
+        }>;
+        status: string;
+    }>;
+    /** Submit the details form; the server creates the ComplyCube evaluation. */
+    initiate(params: {
+        protocolId: string;
+        claimCollectionId?: string;
+        deedOfferId?: string;
+        data: Record<string, unknown>;
+    }): Promise<{
+        status: string;
+    }>;
+    /** Mint the hosted-webview verification URL for the user's evaluation. */
+    getVerificationUrl(params: {
+        protocolId: string;
+    }): Promise<{
+        url: string;
+    }>;
+    /** Read the current server-side lifecycle status. */
+    getStatus(params: {
+        protocolId: string;
+    }): Promise<{
+        status: string;
+    }>;
+    /**
+     * Save the issued SD-JWT credential to the user's Matrix vault room and
+     * move the server status to `complete`. Idempotent — re-saving an
+     * already-saved credential of the same `credentialType` returns the
+     * existing CID (defaults to level 1 when omitted).
+     */
+    saveCredential(params: {
+        protocolId: string;
+        credentialType?: string;
+        credentialCid?: string;
+    }): Promise<{
+        credentialCid: string;
+        credentialType: string;
+    }>;
+}
+interface BlueprintService {
+    execute(params: {
+        action: string;
+        inputs: Record<string, unknown>;
+        actorDid: string;
+        flowId: string;
+        nodeId: string;
+    }): Promise<{
+        receiptRef: string;
+        result?: Record<string, unknown>;
+    }>;
+}
+interface FlowRunLifecycleService {
+    start(params: {
+        actorDid: string;
+        flowId: string;
+        flowUri?: string;
+        label?: string;
+    }): Promise<{
+        runId: string;
+        eventId?: string;
+        startedAt?: number;
+    }>;
+    close(params: {
+        actorDid: string;
+        flowId: string;
+        flowUri?: string;
+        runId: string;
+        allowIncomplete?: boolean;
+    }): Promise<{
+        status: 'closed';
+        eventId?: string;
+        closedAt?: number;
+    }>;
+    cancel(params: {
+        actorDid: string;
+        flowId: string;
+        flowUri?: string;
+        runId: string;
+        reason?: string;
+    }): Promise<{
+        status: 'cancelled';
+        eventId?: string;
+        cancelledAt?: number;
+    }>;
+}
+/**
+ * The full service contract an action execution context can carry. Composed
+ * from the per-domain service interfaces above so consumers can implement and
+ * type one domain at a time; the runtime shape is unchanged.
+ */
+interface ActionServices {
+    blueprint?: BlueprintService;
+    /** Explicit session lifecycle capability supplied by browser/headless hosts. */
+    flowRuns?: FlowRunLifecycleService;
+    http?: HttpService;
+    email?: EmailService;
+    notify?: NotifyService;
+    bid?: BidService;
+    claim?: ClaimService;
+    collection?: CollectionService;
+    collectionUsers?: CollectionUsersService;
+    matrix?: MatrixCredentialService;
+    integrations?: IntegrationsService;
+    oracle?: OracleService;
+    carbon?: CarbonService;
+    entity?: EntityService;
+    kyc?: KycService;
+}
+interface OutputSchemaField {
+    path: string;
+    displayName: string;
+    type: 'string' | 'number' | 'boolean' | 'object' | 'array';
+    description?: string;
+    /**
+     * For `type === 'array'`: the shape of each element. Drives item-scoped
+     * reference pickers (e.g. the Xero invoice LineItems iterative mapper,
+     * where each cell refs into `{{item.<field>}}`).
+     */
+    itemSchema?: OutputSchemaField[];
+}
+/**
+ * A typed event that an action can emit when it runs.
+ *
+ * Events drive the trigger/listener model: another block can declare a
+ * `block.event` trigger on a (sourceBlockId, eventName) pair, and when this
+ * action emits a matching event, a pending invocation is queued on the
+ * listener block. See `docs/flow-engine/events-and-triggers-plan.md` for the full model.
+ */
+interface ActionEventDefinition {
+    /** Stable identifier — used in trigger declarations and ref strings. */
+    name: string;
+    /** Human-readable label shown in the trigger picker UI. */
+    displayName: string;
+    /** Short description shown as inline hint in the trigger picker. */
+    description: string;
+    /** Schema of the event payload. Same shape as `outputSchema`. */
+    payloadSchema: OutputSchemaField[];
+    /**
+     * Field paths from `payloadSchema` (in order) shown inline in the
+     * pending-invocation list so the assignee can distinguish queued
+     * invocations at a glance. E.g. `['claimId', 'evaluatedAt']`.
+     */
+    pendingDisplayFields?: string[];
+}
+/**
+ * Declares what counts as proof that this action's side effect actually
+ * happened. Enforced centrally by `executeActionBlock`: a run that returns
+ * success without satisfying its proof declaration is recorded as
+ * `state: 'failed'` (code `PROOF_MISSING`), never as `completed`.
+ *
+ * - `{ fields }` — at least one of the listed output paths (dot notation
+ *   allowed) must be truthy. Empty arrays and `false` do not count.
+ * - `{ validate }` — custom predicate over the raw output.
+ * - `'none'` — explicit opt-out for actions with no side effect to prove
+ *   (pure selection/config actions). Must be stated, not omitted.
+ */
+type ActionProofDeclaration = {
+    fields: string[];
+} | {
+    validate: (output: Record<string, unknown>) => boolean;
+} | 'none';
+interface ActionRunContext {
+    runId: string;
+    flowId?: string;
+    flowUri?: string;
+    actorDid?: string;
+    nodeId?: string;
+    /** Read-only service capabilities available to `done.check`. */
+    services?: ActionServices;
+    now: number;
+}
+interface CompletionCheck {
+    done: boolean | 'unknown';
+    source: string;
+    output?: Record<string, unknown>;
+    reason?: string;
+}
+/**
+ * Canonical completion semantics for one run of an action. Every registered
+ * action declares one — see {@link ActionDefinition.done}.
+ */
+interface ActionDoneContract<TInputs extends Record<string, any> = Record<string, any>> {
+    /** Pure fold used by session summaries and the default close condition. */
+    isDone: (actionState: FlowNodeRuntimeState, runContext: ActionRunContext) => boolean;
+    /** Optional side-effect-free external read used by explicit reconciliation. */
+    check?: (params: {
+        inputs: TInputs;
+        actionState: FlowNodeRuntimeState;
+        ctx: ActionRunContext;
+    }) => Promise<CompletionCheck>;
+}
+interface ActionDefinition<TInputs extends Record<string, any> = Record<string, any>> {
+    type: string;
+    /** UCAN-style ability string used by the flow compiler, e.g., "bid/submit". */
+    can?: string;
+    sideEffect: boolean;
+    defaultRequiresConfirmation: boolean;
+    requiredCapability?: string;
+    /**
+     * Who performs the execution once inputs are complete.
+     *
+     * - 'agent' (the default) — a headless orchestrator may run `run()` itself
+     *   or delegate it to a capable oracle.
+     * - 'human' — only a human surface (Portal FlowDetail) may execute: the
+     *   side effect needs an authority the orchestrator does not hold, e.g. a
+     *   chain transaction signed as the entity admin. Orchestrators still
+     *   gather inputs and notify the human, but must never run or delegate
+     *   the action themselves.
+     */
+    executionOwner?: 'agent' | 'human';
+    /** Proof-of-execution declaration. See {@link ActionProofDeclaration}. */
+    proof: ActionProofDeclaration;
+    /**
+     * How many times this action is meant to run within a single flow.
+     *
+     * - 'once' (the default) — a one-shot step that reaches a terminal
+     *   `completed` state and is then Done.
+     * - 'many' — a standing, repeatable capability that can fire any number of
+     *   times on a cadence the flow (not the action) decides — e.g. submitting a
+     *   claim every month. A repeatable block never latches to a terminal Done:
+     *   a `completed` runtime entry means "has fired at least once", and its real
+     *   progress is the count of successful runs in the audit trail, not this
+     *   single summary entry. Such blocks never withhold the flow.
+     */
+    cardinality?: 'once' | 'many';
+    /**
+     * Canonical completion semantics for a run. Required: every action states
+     * how one of its runs folds to Done, and `isActionDone` consults nothing
+     * else. Most actions are Done when the run reached `completed` and use the
+     * shared {@link doneWhenCompleted} contract; repeatable (`many`) actions use
+     * {@link neverDone}. Declare a bespoke contract when Done-ness depends on an
+     * output field, a quota, or an external system (see `qi/kyc.verify`).
+     */
+    done: ActionDoneContract<TInputs>;
+    /**
+     * How dynamic resolver results combine with the static `events` /
+     * `outputSchema` baselines. 'merge' (the default) dedupes by event name /
+     * field path with the dynamic entry winning; 'replace' hands the resolver
+     * full control of the vocabulary (needed e.g. to hide the baseline until
+     * configuration is complete).
+     */
+    dynamicResolutionMode?: 'merge' | 'replace';
+    inputSchema?: object;
+    /**
+     * Machine-readable mirror of the required-input preamble in `run()`: given a
+     * fully-merged inputs object, returns the names of inputs still missing or
+     * blank (empty array = ready to execute). External orchestrators call this
+     * via `getMissingActionInputs` BEFORE queuing execution so a missing input
+     * becomes a prompt to a human rather than a failed run.
+     *
+     * Only define this when requiredness is conditional — it branches on other
+     * inputs (skip flags, group types, either-of-two-fields) and therefore
+     * cannot be derived from `inputSchema.required`, which is the default
+     * derivation. Keep it directly above `run()` and keep the two in lockstep:
+     * every presence throw in `run()` must be predicted here. Presence only —
+     * value validity (ranges, formats, duplicates) stays in `run()`.
+     */
+    getMissingInputs?: (inputs: TInputs) => string[];
+    /** Static output schema for action types with predictable output (e.g. email.send).
+     *  For action types with dynamic output (e.g. http.request), the schema is user-defined in inputs. */
+    outputSchema?: OutputSchemaField[];
+    /**
+     * Typed vocabulary of events this action can emit. Drives the trigger
+     * picker UI and compile-time validation of `block.event` triggers.
+     */
+    events?: ActionEventDefinition[];
+    /**
+     * Optional per-block event resolver. Called with the block's current
+     * template inputs; returns the event vocabulary that applies to this
+     * specific block.
+     *
+     * Use this when the event schema depends on configuration the designer
+     * picks at template time. For example, `qi/claim.submit` only knows the
+     * shape of `surveyAnswers` once a claim collection has been chosen —
+     * returning `[]` until then hides the block from the trigger picker.
+     *
+     * Consumers (trigger picker, flow compiler, event payload picker) prefer
+     * `getDynamicEvents(inputs)` when defined and fall back to static `events`
+     * otherwise. By default the result is MERGED with the static `events`
+     * baseline (deduped by name, dynamic wins). Set
+     * `dynamicResolutionMode: 'replace'` when the resolver must control the
+     * full vocabulary (e.g. returning [] to hide the baseline).
+     */
+    getDynamicEvents?: (inputs: TInputs) => ActionEventDefinition[];
+    /**
+     * Optional per-block output-schema resolver. Symmetric to `getDynamicEvents`
+     * but for `outputSchema` — drives the reference picker for `${block.field}`
+     * refs so survey-derived fields like `output.surveyAnswers.<question>` show
+     * up alongside the static baseline.
+     *
+     * By default the returned array is MERGED with the static `outputSchema`
+     * baseline (deduped by path, dynamic wins); `dynamicResolutionMode:
+     * 'replace'` gives the resolver full control.
+     */
+    getDynamicOutputSchema?: (inputs: TInputs) => OutputSchemaField[];
+    /**
+     * Whether this action can be wired to a `block.event` trigger.
+     * False (the default) for user-interaction-driven actions like forms,
+     * claims, and evaluations — they always run as `manual`. True for actions
+     * where it makes sense for an event to nudge a human assignee to invoke
+     * them (email, http, notify).
+     *
+     * The trigger picker UI is hidden for blocks whose action type has this
+     * set to false.
+     */
+    eligibleForEventTrigger?: boolean;
+    run: (inputs: TInputs, ctx: ActionContext) => Promise<ActionResult>;
+}
+/**
+ * Result returned by an action's `run()` function.
+ *
+ * The optional `events` array is the explicit emission surface — actions
+ * declare which named events they're emitting on this particular run, with
+ * the payload by value. The runtime persists these as part of the run record
+ * and the reconciliation loop turns them into pending invocations on
+ * subscribed listener blocks.
+ */
+interface ActionResult {
+    output: Record<string, any>;
+    events?: Array<{
+        name: string;
+        payload: Record<string, any>;
+    }>;
+    completion?: {
+        state?: 'completed' | 'awaiting_readback';
+        readBack?: Record<string, any>;
+    };
+}
+
+/** Top-level Y.Doc map owning the write-once terminal (closed/cancelled) latch per run. */
+declare const RUNS_TERMINAL_MAP_KEY = "runsTerminal";
+/**
+ * Whether a record written with `recordRunId` belongs to `sessionRunId`.
+ *
+ * Records written before sessions existed carry no `sessionRunId` at all. They
+ * belong to the unsessioned document, so they match only while the flow is
+ * still unmigrated — migration stamps the real run id onto every one of them,
+ * after which this is a plain equality test and no record is ownerless.
+ *
+ * Every "does this record belong to this session" test goes through here, so
+ * the answer cannot drift between the readers of commands, leases, ledger
+ * entries and invocations.
+ */
+declare function isRecordInRun(recordRunId: string | undefined, sessionRunId: string): boolean;
+/**
+ * The run id to report for a record whose own `sessionRunId` may be absent.
+ *
+ * Readers hand back types that require the field, so an untagged record needs
+ * *some* answer. When the caller asked for a specific session the record has
+ * already matched it, so that is the honest owner; otherwise it is unsessioned.
+ * Callers must not substitute a literal here — the sentinel stays private so it
+ * cannot become load-bearing outside this file again.
+ */
+declare function resolveRecordRunId(recordRunId: string | undefined, requestedRunId?: string): string;
+/**
+ * Root metadata key describing which runtime layout is authoritative.
+ *
+ * Version 1 is the Phase A coexistence layout: one legacy run plus the flat
+ * `runtime` mirror. Version 2 is the multi-run layout: every caller supplies a
+ * run id and the flat map is neither read nor written.
+ */
+declare const RUN_STORAGE_VERSION_KEY = "runStorageVersion";
+type RunStorageVersion = 1 | 2;
+/**
+ * The Phase A layout. Inferred for a document that carries pre-session history,
+ * or declared by one that pins the key — never a fallback for a document whose
+ * key is simply absent. Production writes only version 2 (migration and
+ * `startRun`); the declared form exists so a caller that must pin the
+ * coexistence layout, chiefly a test exercising the flat-map mirror, can say so
+ * instead of relying on a default that no longer points that way.
+ */
+declare const LEGACY_RUN_STORAGE_VERSION: RunStorageVersion;
+/** The Phase B layout used by explicit, parallel runs. */
+declare const MULTI_RUN_STORAGE_VERSION: RunStorageVersion;
+/**
+ * Whether {@link adoptLegacyRuntime} may materialise. Read it; never cache it.
+ *
+ * See {@link LEGACY_RUNTIME_ADOPTION_DEFAULT} for the flip condition.
+ */
+declare function isLegacyRuntimeAdoptionEnabled(): boolean;
+interface RunMeta {
+    /** Monotonic per-flow sequence number, for humans and ordering. */
+    seq: number;
+    startedAt: number;
+    startedByDid?: string;
+    label?: string;
+    /**
+     * How this run came to exist. `'migrated'` marks the single session that
+     * absorbed a legacy document's pre-session history; it is an ordinary session
+     * in every other respect.
+     */
+    origin?: 'started' | 'migrated';
+    /**
+     * Frozen when the run is created: the sequenced action block ids in this run
+     * plus a hash of the compiled graph.
+     *
+     * **A run without one is not a session.** It is a phantom from a build that
+     * created containers on connect, and the lifecycle refuses to close it rather
+     * than computing a summary against the live document.
+     */
+    manifest?: {
+        blockIds: string[];
+        defHash: string;
+    };
+}
+interface RunTerminalRecord {
+    status: 'closed' | 'cancelled';
+    at: number;
+    by?: string;
+    closeInvocationCid?: string;
+    /** Matrix event that won the terminal transition. */
+    terminalEventId?: string;
+    /** Per-block `isDone` snapshotted at close time. Phase B populates it. */
+    summary?: Record<string, boolean>;
+}
+/** The runs container. Re-resolve on every call; never cache the result. */
+declare function getRunsMap(yDoc: Y.Doc): Y.Map<Y.Map<unknown>>;
+/** The write-once terminal latch map. Re-resolve on every call. */
+declare function getRunsTerminalMap(yDoc: Y.Doc): Y.Map<RunTerminalRecord>;
+/**
+ * Read the document's runtime layout without mutating it.
+ *
+ * **Sessions are the default; the Phase A layout is not a fallback.** A missing
+ * version key is not evidence of a legacy document — it is the state of every
+ * document nobody has latched yet, including ones created moments ago by paths
+ * that copy a doc rather than compile one (template instantiation, protocol
+ * import). Treating the absent key as version 1 made those flows demand a
+ * migration that would move nothing.
+ *
+ * So the discriminator is the *presence of pre-session history*, the same
+ * predicate the compiler latches on. Version 1 is reported only for a document
+ * that actually has flat-map history to migrate; everything else is version 2,
+ * whether or not it carries the key. An explicit key always wins — that is what
+ * `migrateFlowToSessions` writes to make the transition permanent, and it is
+ * what keeps a migrated document on version 2 after its history is seeded into
+ * the first session.
+ */
+declare function getRunStorageVersion(yDoc: Y.Doc): RunStorageVersion;
+/** Whether flat-map compatibility is still part of this document's interface. */
+declare function usesLegacyRuntimeCompatibility(yDoc: Y.Doc): boolean;
+declare class ExplicitRunRequiredError extends Error {
+    constructor(message?: string);
+}
+declare class UnknownRunError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+declare class TerminalRunExecutionError extends Error {
+    readonly runId: string;
+    readonly blockId: string;
+    constructor(runId: string, blockId: string);
+}
+/** Definition flag shared by manifest construction, execution guards and UI. */
+declare function isBelowTheLineBlock(block: {
+    props?: Record<string, unknown>;
+} | null | undefined): boolean;
+/**
+ * Resolve an execution target without turning the advisory active-run pointer
+ * into authority. Version 2 requires a real, named run supplied by the caller.
+ *
+ * Version 1 is a legacy, unmigrated document. It has no run container and never
+ * gains one from a write: the returned {@link UNSESSIONED_RUN_ID} addresses
+ * nothing, reads resolve to the flat map, and writes go flat-only. That is the
+ * pre-session behaviour, preserved exactly, until the flow is migrated.
+ */
+declare function resolveRunIdForExecution(yDoc: Y.Doc, requestedRunId?: string): string;
+/**
+ * Ordinary sequenced actions stop with the run. Explicit below-the-line
+ * actions remain available for post-close work and continue appending history.
+ */
+declare function assertRunActionExecutionAllowed(yDoc: Y.Doc, runId: string, block: {
+    id?: string;
+    props?: Record<string, unknown>;
+}): void;
+/**
+ * Create the run container if it is missing. Transactional, idempotent, and
+ * safe against the concurrent-create race.
+ *
+ * **The race:** two clients concurrently doing `runs.get(id) ?? new Y.Map()`
+ * produce two detached `Y.Map`s. The merge keeps one and *silently discards
+ * everything ever written into the loser*, with no error. Phase A aggravates
+ * this whenever two clients start or migrate the same flow at once.
+ * The in-transaction re-check closes the local window; the flat mirror written
+ * by {@link writeActionState} is the second net that makes the remote window
+ * survivable.
+ *
+ * Returns the LIVE container. **Never cache it across a tick** — a losing merge
+ * orphans the reference and subsequent writes vanish with no error.
+ */
+declare function ensureRun(yDoc: Y.Doc, runId: string, meta?: Partial<RunMeta>): Y.Map<unknown>;
+/**
+ * The run's actions map, re-resolved from the doc on every call.
+ * Returns `undefined` if the run does not exist — this is a pure read and must
+ * never write (a read-only viewer calls it).
+ */
+declare function getRunActionsMap(yDoc: Y.Doc, runId: string): Y.Map<FlowNodeRuntimeState> | undefined;
+/** Read a run's `meta`. Returns `undefined` when the run does not exist. */
+declare function getRunMeta(yDoc: Y.Doc, runId: string): RunMeta | undefined;
+interface MultiRunMigrationResult {
+    actionStates: number;
+    pendingInvocations: number;
+    barrierEntries: number;
+}
+/**
+ * Whether this document carries pre-session execution history.
+ *
+ * True means the flat `runtime` map holds at least one real action state, so
+ * migrating produces a session with something in it. Reserved `__`-prefixed
+ * keys (DM dedup) are not history: a flow that only ever sent a notification has
+ * never executed anything.
+ */
+declare function hasLegacyRuntimeHistory(yDoc: Y.Doc): boolean;
+/**
+ * Delete the container that pre-migration builds created on every connect.
+ *
+ * Such a container is not a session — it has no frozen manifest, so the
+ * lifecycle cannot close it, yet it is enumerated by every surface that lists
+ * runs and therefore shows up as a phantom the user can neither finish nor
+ * remove. Returns whether anything was deleted.
+ *
+ * Collected when deleting it provably loses nothing:
+ *
+ * - it holds no action states of its own — there is no copy to destroy; or
+ * - the document is version 1, where the dual-write guarantees every state in
+ *   the phantom is also in the flat map.
+ *
+ * Under version 2 a container that does hold states is the only copy of them,
+ * so it is left alone regardless of how it got its name. A run bearing a
+ * manifest is a real session and is never touched.
+ *
+ * The empty case is not hypothetical: a pre-session build created this
+ * container on *every connect*, so a flow that was opened but never executed
+ * has a phantom and no flat history — and with sessions as the default that
+ * document is version 2, where the version gate alone would strand the phantom
+ * as an unfinishable, unremovable session.
+ */
+declare function collectPhantomLegacyRun(yDoc: Y.Doc): boolean;
+/**
+ * Seed a newly created run with the document's pre-session history: the
+ * freshness winner for every legacy action, plus pending invocations and
+ * partial barriers.
+ *
+ * **Cannot downgrade anything.** The run is created by migration immediately
+ * before this call, so every block resolves with no run entry — rule (a) of
+ * {@link resolveActionState} makes the flat side the winner every time, and
+ * there is nothing on the run side to lose. That is what lets a legacy document
+ * be seeded while the global adoption gate remains closed.
+ *
+ * Does **not** write the version latch: the caller flips it at the end of the
+ * same transaction, after every part of the migration has succeeded.
+ */
+declare function seedRunFromLegacyRuntime(yDoc: Y.Doc, runId: string): MultiRunMigrationResult;
+/** Latch the document onto the multi-run layout. */
+declare function setMultiRunStorage(yDoc: Y.Doc): void;
+/**
+ * Mark a document as multi-run without migrating anything.
+ *
+ * For newly created documents, which have no legacy history to carry over, and
+ * for tests that build runs explicitly.
+ */
+declare function enableMultiRunStorage(yDoc: Y.Doc): void;
+/**
+ * Read a block's action state for a run.
+ *
+ * **Resolves** the run entry against the flat `runtime[blockId]` through
+ * {@link resolveActionState} — it does not merely fall back when the run entry
+ * is missing. A run entry that exists but is *staler* than the flat mirror (an
+ * old tab or a not-yet-upgraded orchestrator finished the block; or the run
+ * entry is the `idle` seed left by `initializeRuntime`) must read as the
+ * advanced value, or the auto-execute gate re-arms and the side effect fires
+ * twice.
+ *
+ * Always returns a fresh copy, never a reference into the doc. Never writes —
+ * safe on a read-only viewer and before the doc has connected. (Convergence is
+ * `adoptLegacyRuntime`'s job, and it is a writer; reads only correct what they
+ * hand back.)
+ *
+ * PHASE A COMPAT — REMOVAL TRIGGER: the flat resolution goes when dual-write
+ * goes (compat register item 2), and only after `adoptLegacyRuntime` has run
+ * against every live room.
+ */
+declare function readActionState(yDoc: Y.Doc, runId: string, blockId: string): FlowNodeRuntimeState;
+/**
+ * Enumerate one run through the same interface as {@link readActionState}.
+ *
+ * During Phase A this iterates the union of run and flat keys and resolves each
+ * value through the freshness predicate. During Phase B it reads only the named
+ * run. Consumers use this instead of touching either storage container.
+ */
+declare function readActionStates(yDoc: Y.Doc, runId: string): Record<string, FlowNodeRuntimeState>;
+/**
+ * Merge `updates` into a block's action state.
+ *
+ * **ONE transaction, ONE `prev` read.** The returned `prev` is the single
+ * pre-write snapshot the caller must use for completion guards. Two separate
+ * read-modify-write calls (one for the run, one for the mirror) would evaluate
+ * `prev.state !== 'completed'` twice → two run records → two pending
+ * invocations on every downstream listener → **double execution of a
+ * side-effecting action**. That is the single most likely way this project
+ * causes a real double payment, so the contract is enforced here rather than
+ * left to call sites.
+ *
+ * `prev` is the **resolved** value ({@link resolveActionState}), not the raw
+ * run entry. This is load-bearing for the same guard: if an old tab already
+ * completed the block in the flat map while the run still holds the `idle`
+ * seed, a raw `prev` would read `idle`, the guard would fire, and
+ * `step.completed` would be emitted a second time — one pending invocation per
+ * downstream listener, all over again.
+ */
+declare function writeActionState(yDoc: Y.Doc, runId: string, blockId: string, updates: Partial<FlowNodeRuntimeState>): {
+    prev: FlowNodeRuntimeState;
+    next: FlowNodeRuntimeState;
+};
+/**
+ * **Replace** a block's action state in the run AND the flat mirror, in one
+ * transaction. The opposite of {@link writeActionState}: nothing is merged, the
+ * previous value is discarded on both sides.
+ *
+ * This is the primitive every *reset* path must use — flow rebuild, per-node
+ * re-initialisation, the user's "Reset" affordance. A reset that touches only
+ * the flat map is the most dangerous write in Phase A: {@link resolveActionState}
+ * rule (a) makes a surviving `completed` run entry beat the fresh `idle` flat
+ * entry, so the block reads **pre-completed** — a rebuilt flow shows green ticks
+ * for work nobody did in it, and a "Reset" button appears to do nothing. Because
+ * CRDT history is immutable, that wrong state is permanent in a live room.
+ *
+ * Writing the *identical* object to both sides is what makes the pair converge:
+ * the two entries are then indistinguishable, so the predicate falls through to
+ * the deterministic tiebreak and {@link adoptLegacyRuntime} has nothing to
+ * materialise.
+ */
+declare function resetActionState(yDoc: Y.Doc, runId: string, blockId: string, value?: FlowNodeRuntimeState): void;
+/**
+ * Delete a block's action state from the run AND the flat mirror, in one
+ * transaction. Used when the block itself is removed from the flow.
+ *
+ * Deleting only the flat entry leaves the run holding the deleted block's last
+ * state; a block re-added under the same id (block ids are deterministic —
+ * `flow_block_<nodeId>`) then reads as already-executed.
+ *
+ * **Never creates the run container.** A delete on a doc that has no run yet is
+ * a no-op on the run side, not a reason to materialise `runs` — a doc that has
+ * never been adopted must not gain a container from a removal.
+ *
+ * Phase A has exactly one run, but this deletes from the *named* run only,
+ * never every run: in Phase B removing a block must not rewrite the history of
+ * runs that already executed it.
+ */
+declare function deleteActionState(yDoc: Y.Doc, runId: string, blockId: string): void;
+/**
+ * Drop **all** per-action execution state: every run container, the write-once
+ * terminal latch, and the flat `runtime` map. One transaction.
+ *
+ * This is the full-rebuild wipe. It deletes every run, not just the active one:
+ * a rebuild replaces the definition wholesale, so no run's state is meaningful
+ * against it any more.
+ *
+ * Deliberately narrower than `clearRuntimeForTemplateClone` — it does not touch
+ * `auditTrail`, `invocations`, `pendingInvocations` or `barrierState`, matching
+ * exactly what the rebuild path cleared before runs existed. Widening it further
+ * is a separate behaviour change.
+ *
+ * ## Why the DM dedup map is in scope, and is NOT a widening
+ *
+ * Wiping the flat map wipes the `__dm_notifications` / `__dm_notifications_pending`
+ * keys along with everything else, because those records used to *live* there.
+ * Clearing the flat map and not the dedicated map does not preserve DM state —
+ * it **forks** it, in the one direction that is loudest:
+ *
+ * - an already-deployed client reads only the legacy keys, sees an empty bag,
+ *   and re-DMs the assignee of every block in the rebuilt flow;
+ * - a new client reads the union, still sees the pre-rebuild records, and stays
+ *   silent.
+ *
+ * So the two generations disagree about who has been notified, which is the
+ * exact split `dmNotificationState`'s dual-write exists to prevent. Clearing
+ * both restores the pre-runs behaviour byte for byte: a full rebuild resets DM
+ * dedup, and both generations agree that it did. `clearRuntimeForTemplateClone`
+ * already clears both for the same reason.
+ */
+declare function clearAllActionState(yDoc: Y.Doc): void;
+/**
+ * Resolve every flat `runtime` entry against its run entry and **materialise
+ * the winner into the run**. Returns the number of entries actually written.
+ *
+ * This is the writer half of the freshness contract, and the reason the doc
+ * *converges* rather than merely reading correctly on each peer. Adoption is
+ * **not absent-only**: skipping any key the run already has would make it dead
+ * code the moment `initializeRuntime` seeds `{state:'idle'}` for every block,
+ * and would strand every later flat write — an old tab completing a payment, a
+ * not-yet-upgraded flow-manager finishing a claim, or the mirror of a container
+ * that lost the concurrent-create race — outside the run forever.
+ *
+ * It is still **never a downgrade**: {@link resolveActionState}'s rule (a) means
+ * a staler flat entry (an old tab re-seeding `idle` after a new tab completed
+ * the block) loses, so nothing here can resurrect a pre-execution state on top
+ * of a completed one and re-arm the auto-execute gate.
+ *
+ * **Idempotent by construction.** A materialised value is a copy of the flat
+ * entry, so the next pass resolves the pair via the deterministic tiebreak
+ * (rule (d)) back to `'run'` — no write, and a reported count of zero.
+ *
+ * ## THE ADOPTION GATE (§9.3) — **NOT discharged**
+ *
+ * **Gated, default OFF** — see {@link isLegacyRuntimeAdoptionEnabled} for the
+ * full, cross-repo flip condition. While the gate is closed this is a pure no-op
+ * returning `0`: it does not read, does not open a transaction, and does not
+ * create the `actions` container. The gate is enforced here rather than at the
+ * call sites so that no call site — present or future — can forget it.
+ *
+ * It was once declared discharged on the strength of a grep over `editor/src`.
+ * That is the wrong scope: `flow-manager` is a live writer of flow runtime state
+ * (§9.6), is pinned to a pre-runs editor, and still writes a flat-only `failed`
+ * with no `executedAt` — which this predicate can never materialise. The two
+ * things that keep the gate honest, and why neither alone is enough, are written
+ * out at {@link isLegacyRuntimeAdoptionEnabled}: the flag covers the repos no
+ * test here can see, the guard covers this one.
+ *
+ * - `no-runtime-writer-outside-waist.test.ts` greps the whole of `src/` and
+ *   fails on any runtime-map write outside this file's allowlist. Its allowlist
+ *   is per-line where feasible, and it must never gain an entry without a §9.3
+ *   argument.
+ * - `adoption-live.repro.test.ts` pins the four originally-reproduced defects
+ *   (checkbox uncheck, reset-after-failed, read-back proof failure, 50 idempotent
+ *   passes) plus the stall — all with the gate explicitly **opened**, because
+ *   that is the only configuration in which they are reachable.
+ *
+ * `ensureRun` was never gated: an empty run container is harmless and
+ * idempotent. It is *materialising stale winners* that has to wait.
+ *
+ * PHASE A COMPAT — REMOVAL TRIGGER: Phase B, once `writeActionState` no longer
+ * mirrors to the flat map (compat register item 3).
+ */
+declare function adoptLegacyRuntime(yDoc: Y.Doc, runId: string): number;
+/**
+ * Subscribe to every change that can alter what {@link readActionState} returns
+ * for any block. Returns the unsubscribe function.
+ *
+ * **Two sources, not one — this is the "block completed but UI still spinning"
+ * trap.** The flat map is a *flat* `Y.Map`, so a shallow `observe` on it sees
+ * every per-block write. `runs` is a *nested* container, so a shallow `observe`
+ * on it fires only when a whole run is added or replaced — a change to
+ * `runs[runId].actions[blockId]` would never reach the handler at all. That
+ * failure presents as a block that completed in the doc while its UI keeps
+ * spinning, which reads as a Matrix sync problem rather than a code bug, so it
+ * is subscribed here in the waist instead of at each call site.
+ *
+ * - `observeDeep` on `runs` covers per-block action writes **and** the container
+ *   replacement that follows a losing concurrent-create merge.
+ * - `observe` on the flat map covers an already-deployed client's write, so it
+ *   is visible immediately rather than waiting for an adoption pass.
+ *
+ * Both fire for a dual-write, so handlers must be cheap and idempotent — the
+ * `shallowEqual` gate in `useNodeRuntime` is what keeps the extra fanout free.
+ *
+ * PHASE A COMPAT — REMOVAL TRIGGER: the flat-map subscription goes with the
+ * mirror write and the read resolution (compat register items 1 and 2).
+ */
+declare function subscribeToActionState(yDoc: Y.Doc, handler: () => void): () => void;
+/**
+ * The session a surface should show, or `undefined` when the flow has none.
+ *
+ * `undefined` is a real answer, not a failure: a new flow has no session until
+ * an actor starts one, and a legacy flow has none until it is migrated. Read
+ * surfaces must render that state rather than substituting a run id — a
+ * fabricated id is what made an unstarted flow display a phantom session.
+ *
+ * The pointer is advisory and is only honoured when it names a run that
+ * actually exists, so a stale pointer (a cloned template, a deleted run) reads
+ * as "no session" rather than as a missing container.
+ */
+declare function resolveActiveRunId(yDoc?: Y.Doc): string | undefined;
+/**
+ * The run id a **read** should resolve against, or `undefined` when there is
+ * nothing to read.
+ *
+ * The read-side counterpart to {@link resolveRunIdForExecution}, which throws
+ * rather than returning nothing — right for a write, wrong for a status panel
+ * or a reference resolver, where "this flow has no session yet" is an ordinary
+ * thing to render.
+ *
+ * A legacy, unmigrated document still has state to show: it lives in the flat
+ * map, and the unsessioned id reaches it.
+ */
+declare function resolveRunIdForRead(yDoc: Y.Doc, requestedRunId?: string): string | undefined;
+/**
+ * `FlowRuntimeStateManager` over a run. Drop-in for `createYDocRuntimeManager`.
+ *
+ * **Throws rather than degrading.** `createRuntimeStateManager` silently
+ * returns an in-memory `Map` when it cannot resolve a doc; under runs that
+ * means the action executes, the side effect happens, and nothing persists — so
+ * the next reader sees an un-run block and executes it again. A throw surfaces
+ * as a failed block, which is recoverable; a silent memory manager is not.
+ */
+declare function createRunScopedRuntimeManager(yDoc: Y.Doc, runId: string): FlowRuntimeStateManager;
+/**
+ * Duck-typed `{ get(blockId) }` shim for `referenceResolver`'s `options.yRuntime`,
+ * which only ever calls `.get(blockId)`. Returns `undefined` for an unknown
+ * block, exactly as the flat `Y.Map` it replaces does, so every existing
+ * `stored?.output` read behaves identically.
+ *
+ * Resolves from the doc on every `get` — the reader object may safely be
+ * memoised, but the container it reads must not be.
+ *
+ * Uses the same {@link resolveActionState} predicate as {@link readActionState}:
+ * a reference like `{{block.output.txHash}}` must see the same value the block's
+ * own UI does, or a downstream action signs against a run entry that a stale
+ * `idle` seed is hiding.
+ *
+ * PHASE A COMPAT — REMOVAL TRIGGER: compat register item 2.
+ */
+declare function createRunRuntimeReader(yDoc: Y.Doc, runId: string): {
+    get(blockId: string): FlowNodeRuntimeState | undefined;
+};
+/**
+ * {@link createRunRuntimeReader} plus the `.doc` handle, for the `_yRuntime`
+ * slot of a **synthetic editor** — the `{ _yDoc, _yRuntime, document }` object
+ * `actionExecutor` and `readBackReconciler` fabricate when they are driven
+ * headlessly from a Y.Doc.
+ *
+ * Two properties matter:
+ *
+ * 1. **Read-only.** There is no `set`. The headless write path goes through
+ *    {@link writeActionState} directly, so there is exactly one duck-typed
+ *    handle in the system and it cannot write. A synthetic `_yRuntime` that
+ *    was the raw flat `Y.Map` (what these call sites used before Ignition) is a
+ *    writer outside this waist by construction.
+ * 2. **`.doc` is present**, because `editor._yRuntime?.doc` is an established
+ *    way to reach the Y.Doc in this repo (`useEntities.ts`, `DebugButton.tsx`),
+ *    and the shim must not be the thing that breaks it.
+ *
+ * PHASE A COMPAT — REMOVAL TRIGGER: compat register item 2, with the reader.
+ */
+declare function createRunRuntimeReaderWithDoc(yDoc: Y.Doc, runId: string): {
+    get(blockId: string): FlowNodeRuntimeState | undefined;
+    doc: Y.Doc;
+};
+
+/**
+ * # Migrating a pre-session document
+ *
+ * Everything here exists to answer one question about records written before
+ * sessions existed: **which session owns them?**
+ *
+ * The old answer was a hard-coded constant every repo agreed to read as "the
+ * legacy run" (`sessionRunId ?? LEGACY_RUN_ID`). That put a document-shaped
+ * fact in a string literal, so ownership was re-derived, identically and by
+ * hand, in a dozen places across three repositories — and a record's owner
+ * changed meaning if any one of them disagreed.
+ *
+ * Migration answers it once, in the data: every untagged record is stamped with
+ * the id of the session that absorbs the document's history. Afterwards nothing
+ * infers ownership, and no constant needs to survive.
+ *
+ * This is the only module that rewrites history, which is why it is separate
+ * from the waist: `runs.ts` owns *action state*, and nothing there should learn
+ * the shape of an agent lease or an invocation.
+ */
+/** One counter per container touched, so a migration can report what it moved. */
+interface StampedRecordCounts {
+    commands: number;
+    leases: number;
+    ledgerEvents: number;
+    invocations: number;
+    runRecords: number;
+}
+
+type RunJsonValue = null | string | number | boolean | RunJsonObject | RunJsonValue[];
+interface RunJsonObject {
+    [key: string]: RunJsonValue;
+}
+type LifecycleRunEventInput = {
+    runId: string;
+    kind: 'run.started';
+    payload: {
+        invocationCid?: string;
+        definitionRevision?: string;
+        label?: string;
+    };
+    idempotencyKey: string;
+    ts?: number;
+    blockId?: never;
+} | {
+    runId: string;
+    kind: 'run.closed';
+    payload: {
+        invocationCid?: string;
+        summary?: RunJsonObject;
+    };
+    idempotencyKey: string;
+    ts?: number;
+    blockId?: never;
+} | {
+    runId: string;
+    kind: 'run.cancelled';
+    payload: {
+        invocationCid?: string;
+        reason?: string;
+        summary?: RunJsonObject;
+    };
+    idempotencyKey: string;
+    ts?: number;
+    blockId?: never;
+} | {
+    runId: string;
+    kind: 'definition.changed';
+    payload: {
+        revision: string;
+        previousRevision?: string;
+        changedBlockIds?: string[];
+        summary?: string;
+    };
+    idempotencyKey: string;
+    ts?: number;
+    blockId?: never;
+};
+type ActionRunEventInput = {
+    runId: string;
+    blockId: string;
+    kind: 'action.started';
+    payload: {
+        attempt: number;
+        executionId?: string;
+        invocationCid?: string;
+        input?: RunJsonValue;
+    };
+    idempotencyKey: string;
+    ts?: number;
+} | {
+    runId: string;
+    blockId: string;
+    kind: 'action.output';
+    payload: {
+        attempt: number;
+        executionId?: string;
+        output: RunJsonValue;
+    };
+    idempotencyKey: string;
+    ts?: number;
+} | {
+    runId: string;
+    blockId: string;
+    kind: 'action.done';
+    payload: {
+        attempt: number;
+        executionId?: string;
+        durationMs?: number;
+        output?: RunJsonValue;
+    };
+    idempotencyKey: string;
+    ts?: number;
+} | {
+    runId: string;
+    blockId: string;
+    kind: 'action.failed';
+    payload: {
+        attempt: number;
+        executionId?: string;
+        durationMs?: number;
+        error: {
+            message: string;
+            name?: string;
+            code?: string;
+            retryable?: boolean;
+            details?: RunJsonValue;
+        };
+    };
+    idempotencyKey: string;
+    ts?: number;
+};
+type RunLogEventInput = {
+    runId: string;
+    blockId?: string;
+    kind: 'log';
+    payload: {
+        level: 'debug' | 'info' | 'warn' | 'error';
+        message: string;
+        data?: RunJsonValue;
+    };
+    idempotencyKey: string;
+    ts?: number;
+};
+type RunEventInput = LifecycleRunEventInput | ActionRunEventInput | RunLogEventInput;
+/** Assignment-compatible with matrix-crdt's IRoomEventLog. */
+interface RunEventAppender {
+    append(event: RunEventInput): Promise<string>;
+}
+type RunLifecycleCapability = 'flow/run.start' | 'flow/run.close';
+interface RunLifecycleAuthorizationRequest {
+    can: RunLifecycleCapability;
+    with: string;
+    actorDid: string;
+    runId?: string;
+}
+interface RunLifecycleAuthorizationDecision {
+    allowed: boolean;
+    reason?: string;
+    invocationCid?: string;
+}
+type RunLifecycleAuthorizer = (request: RunLifecycleAuthorizationRequest) => Promise<RunLifecycleAuthorizationDecision> | RunLifecycleAuthorizationDecision;
+interface RunManifest {
+    blockIds: string[];
+    defHash: string;
+}
+interface RunDefinitionBlock {
+    id?: string;
+    type?: string;
+    props?: Record<string, unknown>;
+    children?: RunDefinitionBlock[];
+}
+interface RunDefinitionSnapshot {
+    manifest: RunManifest;
+    actionTypes: Record<string, string>;
+}
+interface RunSnapshot {
+    id: string;
+    meta: RunMeta;
+    terminal?: RunTerminalRecord;
+}
+declare class RunLifecycleAuthorizationError extends Error {
+    readonly capability: RunLifecycleCapability;
+    constructor(capability: RunLifecycleCapability, message: string);
+}
+declare class RunNotReadyError extends Error {
+    readonly incompleteBlockIds: string[];
+    constructor(incompleteBlockIds: string[]);
+}
+/**
+ * The flow predates sessions and has not been migrated, so it has no session to
+ * act on. Thrown by `startRun` rather than quietly migrating on the caller's
+ * behalf: migration is one-way and changes how every client reads the document,
+ * which is a decision for an actor, not a side effect of pressing Start.
+ */
+declare class FlowNotMigratedError extends Error {
+    readonly flowUri: string;
+    constructor(flowUri: string);
+}
+/**
+ * The run exists but has no frozen manifest, so there is no definition to judge
+ * completeness against.
+ *
+ * Reaching this means the run was created by something other than `startRun` or
+ * `migrateFlowToSessions` — in practice a container left behind by a build that
+ * created one on connect. Computing a summary against the *live* document
+ * instead would let an unstarted flow report work as belonging to a session
+ * nobody opened.
+ */
+declare class RunNotMigratedError extends Error {
+    readonly runId: string;
+    constructor(runId: string);
+}
+declare function computeRunDefinitionHash(definition: unknown): string;
+/** Convert arbitrary action data into Matrix-event-safe JSON. */
+declare function toRunJsonValue(value: unknown): RunJsonValue;
+declare function buildRunDefinitionSnapshot(blocks: RunDefinitionBlock[], definition?: unknown): RunDefinitionSnapshot;
+declare function createRunUlid(timestamp?: number): string;
+declare function createRunId(seq: number, timestamp?: number): string;
+declare function listRuns(yDoc: Y.Doc): RunSnapshot[];
+declare function listOpenRuns(yDoc: Y.Doc): RunSnapshot[];
+declare function setAdvisoryActiveRunId(yDoc: Y.Doc, runId: string): void;
+interface StartRunParams {
+    yDoc: Y.Doc;
+    flowUri: string;
+    actorDid: string;
+    definition: RunDefinitionSnapshot;
+    /** Live block tree used to dispatch authored `trigger: flow.start` actions. */
+    document?: RunDefinitionBlock[];
+    eventLog: RunEventAppender;
+    authorize: RunLifecycleAuthorizer;
+    label?: string;
+    now?: () => number;
+}
+interface StartRunResult {
+    run: RunSnapshot;
+    eventId: string;
+    flowStartInvocations: number;
+}
+declare function startRun(params: StartRunParams): Promise<StartRunResult>;
+interface MigrateFlowParams {
+    yDoc: Y.Doc;
+    flowUri: string;
+    actorDid: string;
+    /** Frozen into the migrated session, exactly as `startRun` freezes its own. */
+    definition: RunDefinitionSnapshot;
+    eventLog: RunEventAppender;
+    authorize: RunLifecycleAuthorizer;
+    label?: string;
+}
+interface MigrateFlowResult {
+    /** The session that now owns the document's history, or `undefined` when
+     *  there was no history to carry and the document was simply latched. */
+    run?: RunSnapshot;
+    eventId?: string;
+    seeded: MultiRunMigrationResult;
+    stamped?: StampedRecordCounts;
+    phantomCollected: boolean;
+    alreadyMigrated: boolean;
+}
+/**
+ * Turn a pre-session document into a session-based one, **one way**.
+ *
+ * What already happened in the flow becomes its first session: an ordinary open
+ * run carrying the same action states, pending invocations and partial barriers,
+ * closable and tickable like any other. A document with no history has nothing
+ * to carry, so it is simply latched and the actor starts session 1 normally.
+ *
+ * ## Order matters
+ *
+ * The timeline event is appended **before** anything is written to the document,
+ * exactly as `startRun` does it: a transient Matrix failure must leave the
+ * document completely unchanged rather than latched onto a layout whose history
+ * nobody can see. Everything after it is one transaction, so a document is
+ * never observed half-migrated — history seeded but unlatched, or latched with
+ * records still pointing nowhere.
+ *
+ * Idempotent. A second call sees the latch and returns `alreadyMigrated`.
+ */
+declare function migrateFlowToSessions(params: MigrateFlowParams): Promise<MigrateFlowResult>;
+declare function computeRunSummary(yDoc: Y.Doc, runId: string, actionTypes: Record<string, string>, context: Omit<ActionRunContext, 'runId'>): Record<string, boolean>;
+interface CloseRunParams {
+    yDoc: Y.Doc;
+    flowUri: string;
+    runId: string;
+    actorDid: string;
+    actionTypes: Record<string, string>;
+    eventLog: RunEventAppender;
+    authorize: RunLifecycleAuthorizer;
+    allowIncomplete?: boolean;
+    now?: () => number;
+}
+interface FinishRunResult {
+    terminal: RunTerminalRecord;
+    created: boolean;
+    eventId?: string;
+}
+declare function closeRun(params: CloseRunParams): Promise<FinishRunResult>;
+interface CancelRunParams extends Omit<CloseRunParams, 'allowIncomplete'> {
+    reason?: string;
+}
+declare function cancelRun(params: CancelRunParams): Promise<FinishRunResult>;
+interface RunDefinitionDrift {
+    changed: boolean;
+    previousRevision?: string;
+    revision: string;
+    changedBlockIds: string[];
+}
+declare function detectRunDefinitionDrift(yDoc: Y.Doc, runId: string, definition: RunDefinitionSnapshot): RunDefinitionDrift;
+declare function recordRunDefinitionDrift(yDoc: Y.Doc, runId: string, definition: RunDefinitionSnapshot, eventLog: RunEventAppender, now?: number): Promise<RunDefinitionDrift & {
+    eventId?: string;
+}>;
+declare function readRunActionStates(yDoc: Y.Doc, runId: string, blockIds: string[]): Record<string, FlowNodeRuntimeState>;
+
 /**
  * Capability types for UCAN-based authorization
  */
@@ -5866,6 +8351,10 @@ interface IxoCollaborativeEditorOptions extends IxoEditorOptions {
     user: IxoCollaborativeUser;
     matrixClient: MatrixClient;
     roomId: string;
+    /** Explicit session used by lifecycle work for this editor surface. */
+    sessionRunId?: string;
+    /** Matrix-backed append surface for the run timeline. */
+    runEventLog?: RunEventAppender;
     /**
      * User permissions for the collaborative document
      * @default { write: false }
@@ -5898,4 +8387,4 @@ interface IxoEditorConfig {
     tableHandles: boolean;
 }
 
-export { type MatrixRoom as $, AuthzExecActionTypes as A, BlocknoteProvider as B, type VoteResponse as C, type DelegationChainValidationResult as D, type VoteInfo as E, type Vote as F, type User as G, type Addr as H, type InvocationStore as I, type Uint128 as J, type Expiration as K, type Status as L, type Threshold as M, type Votes as N, type CosmosMsgForEmpty as O, type ProposalResponse as P, type ProposalAction as Q, type ListProtocolDeedsWithTemplatesParams as R, type StoredDelegation as S, type Timestamp as T, type UcanDelegationStore as U, ValidatorActionType as V, type ProtocolDeedWithTemplates as W, type ProtocolTemplateSummary as X, type ImportProtocolTemplatesToSpaceParams as Y, type ImportProtocolTemplateResult as Z, type MatrixPrivacySettings as _, createMemoryUcanDelegationStore as a, type MatrixSpace as a0, type MatrixSubspace as a1, type MatrixSpaceStructure as a2, type Translate as a3, type FlowNodeRuntimeState as a4, type IxoEditorType as a5, type FlowMetadata as a6, type FlowNode as a7, type DID as a8, type ClaimCollectionURI as a9, type EvaluationStatus as aa, type LinkedClaim as ab, type FlowNodeAuthzExtension as ac, type NodeServiceReport as ad, type NodeState as ae, type ReadBackTerminalState as af, type ActionReadBackMetadata as ag, type FlowNodeBase as ah, type InvocationRequest as ai, type InvocationResult as aj, type ExecutionWithInvocationResult as ak, type FindProofsResult as al, type CreateRootDelegationParams as am, type CreateDelegationParams as an, type CreateInvocationParams as ao, type IxoBlockProps as ap, type VisualizationRenderer as aq, type DynamicListData as ar, type DynamicListDataProvider as as, type DynamicListPanelRenderer as at, type DomainCardRenderer as au, type DomainCardData as av, type UnlMapConfig as aw, createInvocationStore as b, createUcanDelegationStore as c, createMemoryInvocationStore as d, createUcanService as e, type UcanService as f, type UcanServiceConfig as g, type UcanServiceHandlers as h, type UcanCapability as i, type StoredInvocation as j, type DelegationGrant as k, type IxoEditorOptions as l, type IxoEditorTheme as m, type IxoEditorConfig as n, type IxoCollaborativeUser as o, type IxoCollaborativeEditorOptions as p, blockSpecs as q, getExtraSlashMenuItems as r, useBlocknoteHandlers as s, useTranslate as t, useBlocknoteContext as u, StakeType as v, type BlocknoteHandlers as w, type BlocknoteContextValue as x, type BlockRequirements as y, type SingleChoiceProposal as z };
+export { type ImportProtocolTemplateResult as $, AuthzExecActionTypes as A, BlocknoteProvider as B, type SingleChoiceProposal as C, type DelegationChainValidationResult as D, type VoteResponse as E, type FlowRuntimeStateManager as F, type VoteInfo as G, type Vote as H, type InvocationStore as I, type User as J, type Addr as K, type Uint128 as L, type Expiration as M, type Status as N, type Threshold as O, type ProposalResponse as P, type Votes as Q, type CosmosMsgForEmpty as R, type StoredDelegation as S, type Timestamp as T, type UcanDelegationStore as U, ValidatorActionType as V, type ProposalAction as W, type ListProtocolDeedsWithTemplatesParams as X, type ProtocolDeedWithTemplates as Y, type ProtocolTemplateSummary as Z, type ImportProtocolTemplatesToSpaceParams as _, createUcanDelegationStore as a, assertRunActionExecutionAllowed as a$, type MatrixPrivacySettings as a0, type MatrixRoom as a1, type MatrixSpace as a2, type MatrixSubspace as a3, type MatrixSpaceStructure as a4, type Translate as a5, type FlowNode as a6, type FlowNodeAuthzExtension as a7, type EvaluationStatus as a8, type IxoEditorType as a9, type FlowMetadata as aA, createYDocRuntimeManager as aB, clearRuntimeForTemplateClone as aC, LEGACY_RUN_STORAGE_VERSION as aD, MULTI_RUN_STORAGE_VERSION as aE, RUNS_TERMINAL_MAP_KEY as aF, RUN_STORAGE_VERSION_KEY as aG, adoptLegacyRuntime as aH, clearAllActionState as aI, collectPhantomLegacyRun as aJ, createRunRuntimeReader as aK, createRunRuntimeReaderWithDoc as aL, createRunScopedRuntimeManager as aM, deleteActionState as aN, enableMultiRunStorage as aO, ensureRun as aP, getRunActionsMap as aQ, getRunMeta as aR, getRunsMap as aS, getRunsTerminalMap as aT, getRunStorageVersion as aU, hasLegacyRuntimeHistory as aV, isLegacyRuntimeAdoptionEnabled as aW, isRecordInRun as aX, readActionState as aY, readActionStates as aZ, resetActionState as a_, type PendingInvocation as aa, type ActionServices as ab, type ActionHandlers as ac, type RunEventAppender as ad, type ActionResult as ae, type ActionDefinition as af, type FlowNodeRuntimeState as ag, type IxoBlockProps as ah, type VisualizationRenderer as ai, type DynamicListData as aj, type DynamicListDataProvider as ak, type DynamicListPanelRenderer as al, type DomainCardRenderer as am, type DomainCardData as an, type UnlMapConfig as ao, type ActionDoneContract as ap, type ActionEventDefinition as aq, type OutputSchemaField as ar, type RunEventInput as as, type RunJsonValue as at, type ActionRunContext as au, type CompletionCheck as av, type ActionReadBackMetadata as aw, type ReadBackTerminalState as ax, type ActionProofDeclaration as ay, type RunRecordDetails as az, createMemoryUcanDelegationStore as b, type CollectionService as b$, isBelowTheLineBlock as b0, resolveActiveRunId as b1, resolveRecordRunId as b2, resolveRunIdForExecution as b3, resolveRunIdForRead as b4, seedRunFromLegacyRuntime as b5, setMultiRunStorage as b6, subscribeToActionState as b7, usesLegacyRuntimeCompatibility as b8, writeActionState as b9, RunNotReadyError as bA, type CancelRunParams as bB, type CloseRunParams as bC, type ActionRunEventInput as bD, type FinishRunResult as bE, type MigrateFlowParams as bF, type MigrateFlowResult as bG, type LifecycleRunEventInput as bH, type RunDefinitionBlock as bI, type RunDefinitionDrift as bJ, type RunDefinitionSnapshot as bK, type RunJsonObject as bL, type RunLogEventInput as bM, type RunLifecycleAuthorizationDecision as bN, type RunLifecycleAuthorizationRequest as bO, type RunLifecycleAuthorizer as bP, type RunLifecycleCapability as bQ, type RunManifest as bR, type RunSnapshot as bS, type StartRunParams as bT, type StartRunResult as bU, type ActionContext as bV, type HttpService as bW, type EmailService as bX, type NotifyService as bY, type BidService as bZ, type ClaimService as b_, ExplicitRunRequiredError as ba, TerminalRunExecutionError as bb, UnknownRunError as bc, type RunMeta as bd, type MultiRunMigrationResult as be, type RunStorageVersion as bf, type RunTerminalRecord as bg, buildRunDefinitionSnapshot as bh, cancelRun as bi, closeRun as bj, computeRunDefinitionHash as bk, computeRunSummary as bl, createRunId as bm, createRunUlid as bn, detectRunDefinitionDrift as bo, listOpenRuns as bp, listRuns as bq, migrateFlowToSessions as br, readRunActionStates as bs, recordRunDefinitionDrift as bt, setAdvisoryActiveRunId as bu, startRun as bv, toRunJsonValue as bw, FlowNotMigratedError as bx, RunLifecycleAuthorizationError as by, RunNotMigratedError as bz, createRuntimeStateManager as c, type CollectionUsersService as c0, type MatrixCredentialService as c1, type IntegrationsService as c2, type OracleService as c3, type CarbonService as c4, type EntityService as c5, type FlowRunLifecycleService as c6, appendRunRecord as c7, readRunRecords as c8, getPendingInvocationsMap as c9, countPendingInvocations as ca, getOrCreateBlockPendingMap as cb, readPendingInvocations as cc, queuePendingInvocation as cd, removePendingInvocation as ce, findFailedListenersForSourceRun as cf, replayFailedListenerRun as cg, snapshotInputRefs as ch, computePendingInvocationId as ci, RUN_RECORD_AUDIT_TYPE as cj, type FailedListenerRun as ck, type DID as cl, type ClaimCollectionURI as cm, type LinkedClaim as cn, type NodeServiceReport as co, type NodeState as cp, type FlowNodeBase as cq, type InvocationRequest as cr, type InvocationResult as cs, type ExecutionWithInvocationResult as ct, type FindProofsResult as cu, type CreateRootDelegationParams as cv, type CreateDelegationParams as cw, type CreateInvocationParams as cx, createInvocationStore as d, createMemoryInvocationStore as e, createUcanService as f, type UcanService as g, type UcanServiceConfig as h, type UcanServiceHandlers as i, type UcanCapability as j, type StoredInvocation as k, type DelegationGrant as l, type IxoEditorOptions as m, type IxoEditorTheme as n, type IxoEditorConfig as o, type IxoCollaborativeUser as p, type IxoCollaborativeEditorOptions as q, blockSpecs as r, getExtraSlashMenuItems as s, useBlocknoteHandlers as t, useBlocknoteContext as u, useTranslate as v, StakeType as w, type BlocknoteHandlers as x, type BlocknoteContextValue as y, type BlockRequirements as z };