@ixo/editor 6.22.0 → 6.24.0

package/dist/store-Ba-HGtSG.d.ts

@@ -1,2144 +0,0 @@
-import { a7 as FlowNode, ac as FlowNodeAuthzExtension, a4 as FlowNodeRuntimeState, a5 as IxoEditorType, f as UcanService, I as InvocationStore, aa as EvaluationStatus, i as UcanCapability, U as UcanDelegationStore, S as StoredDelegation } from './index-BC4ycOwH.js';
-import * as Y from 'yjs';
-import { Doc, Map } from 'yjs';
-import { MatrixClient } from 'matrix-js-sdk';
-
-/** Condition that gates when a capability activates. */
-interface ConditionRef {
-    /** ID of the upstream capability whose output is checked. */
-    sourceId: string;
-    /** Output field path to inspect, e.g., "decision". */
-    field: string;
-    /** Comparison operator. */
-    operator: 'eq' | 'neq' | 'gt' | 'lt' | 'in' | 'exists';
-    /** Value to compare against (omit for 'exists'). */
-    value?: unknown;
-    /** What happens when the condition is (not) met. */
-    effect?: {
-        action: 'enable' | 'disable' | 'hide' | 'show';
-        message?: string;
-    };
-}
-/** Authorization constraint for a capability. */
-interface ActorConstraint {
-    /** Whitelisted actor DIDs. */
-    authorisedActors?: string[];
-    /** Parent capability URI for delegation chain. */
-    parentCapability?: string;
-}
-/** Time-to-live constraint for a capability. */
-interface TTLConstraint {
-    /** Hard deadline (ISO 8601 date string). */
-    absoluteDueDate?: string;
-    /** Duration from when the block becomes enabled (ISO 8601 duration, e.g., "P7D"). */
-    fromEnablement?: string;
-    /** Duration from when an actor commits (ISO 8601 duration, e.g., "PT2H"). */
-    fromCommitment?: string;
-}
-/**
- * A single capability in a Base UCAN flow plan.
- *
- * UCAN semantics:
- *   can  = the action
- *   with = the resource or scope
- *   nb   = typed caveats, inputs, parameters
- *
- * Workflow semantics (kept separate from nb):
- *   condition, trigger, parallelGroup, phase
- */
-interface FlowCapability {
-    /** Stable node identifier for this step. */
-    id: string;
-    /** UCAN-style ability string, e.g., "bid/submit", "email/send". */
-    can: string;
-    /** Resource URI, e.g., "ixo:flow:{flowId}" or "ixo:flow:{flowId}:{nodeId}". */
-    with: string;
-    /** Typed caveats / input parameters. Shape is dictated by the action registry. */
-    nb?: Record<string, unknown>;
-    /** Condition that must be met for this capability to activate. */
-    condition?: ConditionRef;
-    /** Capabilities sharing a parallelGroup run concurrently. */
-    parallelGroup?: string;
-    /** Semantic grouping for layout lanes. */
-    phase?: string;
-    /** Who can execute this step. */
-    actor?: ActorConstraint;
-    /** Time-to-live constraints. */
-    ttl?: TTLConstraint;
-    /**
-     * When and how this block fires. Defaults to `{ type: 'manual' }` if absent
-     * (i.e. block runs only when a user explicitly invokes it).
-     *
-     * `block.event` triggers turn this block into a listener: when the source
-     * block emits an event matching `eventName`, a pending invocation is
-     * queued on this block and the assigned actor is DM'd to invoke it. See
-     * `docs/flow-engine/events-and-triggers-plan.md` §3.7 and §18 for the full model.
-     *
-     * Triggers are a NEW sibling field on FlowCapability (decided in eng review
-     * pass 2 phase 0 #1). They are NOT an extension of `condition`. The decompile
-     * branch's author needs to add `props.trigger` parsing when their work merges.
-     */
-    trigger?: TriggerSpec;
-    /** Display title (falls back to can statement). */
-    title?: string;
-    /** Description of what this step does. */
-    description?: string;
-    /** Icon identifier. */
-    icon?: string;
-}
-/**
- * Trigger declaration for a block. When and how it fires.
- */
-/** A single event source in a barrier trigger. */
-interface TriggerSource {
-    /** ID of the block that emits the event. */
-    sourceBlockId: string;
-    /** Name of the event (must match an event declared on the source action's `events` vocabulary). */
-    eventName: string;
-    /** Namespace alias for payload access: `trigger.payload.<alias>.*` */
-    alias: string;
-    /**
-     * When `true`, this source does NOT block queuing — the barrier fires once all
-     * *required* (non-optional) sources have fired. If an optional source fired before
-     * the barrier completes, its payload is merged in; if it never fires, it's skipped.
-     * Defaults to `false` (required) for backward compatibility.
-     */
-    optional?: boolean;
-}
-interface TriggerSpec {
-    /**
-     * - `manual`: block runs only when a user explicitly invokes it (default).
-     * - `flow.start`: block runs when the flow execution begins.
-     * - `block.event`: block runs each time another block emits a matching event.
-     * - `block.event.all`: block runs once ALL listed sources have emitted (barrier/join).
-     */
-    type: 'manual' | 'flow.start' | 'block.event' | 'block.event.all';
-    /** Required when `type === 'block.event'`. ID of the block that emits the event. */
-    sourceBlockId?: string;
-    /** Required when `type === 'block.event'`. Name of the event (must match an event declared on the source action's `events` vocabulary). */
-    eventName?: string;
-    /** Required when `type === 'block.event.all'`. Array of event sources — ALL must fire before the listener is queued. */
-    sources?: TriggerSource[];
-}
-/**
- * The Base UCAN flow plan — the intermediate representation between
- * user intent and the compiled flow graph.
- *
- * capabilities is an ordered list. Each capability carries its own stable `id`.
- */
-interface BaseUcanFlow {
-    kind: 'qi.flow.base-ucan';
-    version: '1.0';
-    flowId: string;
-    title: string;
-    goal?: string;
-    meta?: {
-        entityDid?: string;
-        flowUri?: string;
-        rootIssuer?: string;
-    };
-    /** Ordered capabilities, each with its own stable node ID. */
-    capabilities: FlowCapability[];
-}
-/** A reference to an upstream node's output field. Format: "nodeId.output.fieldPath" */
-interface RuntimeRef {
-    $ref: string;
-}
-declare function isRuntimeRef(value: unknown): value is RuntimeRef;
-/** A single block ready for insertion into BlockNote. */
-interface CompiledBlock {
-    /** Pre-generated stable block ID. */
-    id: string;
-    /** BlockNote block type (e.g., "action"). */
-    type: string;
-    /** Block props — all values are strings per BlockNote convention. */
-    props: Record<string, string>;
-}
-/**
- * An edge in the flow graph. Currently only `kind: 'trigger'` edges are
- * synthesized — they come from `block.event` triggers and represent the
- * source → listener relationship visually on the canvas.
- */
-interface CompiledEdge {
-    id: string;
-    source: string;
-    target: string;
-    kind: 'trigger';
-    condition?: ConditionRef;
-}
-/** A compiled flow node stored in qi.flow.nodes. */
-interface CompiledFlowNode {
-    id: string;
-    blockId: string;
-    can: string;
-    with: string;
-    registryType: string;
-    title: string;
-    description: string;
-    props: Record<string, string>;
-    phase?: string;
-    parallelGroup?: string;
-    actor?: ActorConstraint;
-}
-/** The complete compiled output from the Base UCAN compiler. */
-interface CompiledFlow {
-    /** Flow metadata for qi.flow.meta and Y.Map('root'). */
-    meta: {
-        flowId: string;
-        title: string;
-        goal?: string;
-        version: string;
-        flowOwnerDid: string;
-        flowUri?: string;
-        compiledAt: string;
-        compiledFrom: 'BaseUcanFlow';
-    };
-    /** Blocks to insert into BlockNote, in topological order. */
-    blocks: CompiledBlock[];
-    /** Flow graph nodes, keyed by node ID. */
-    nodes: Record<string, CompiledFlowNode>;
-    /** Dependency edges. */
-    edges: CompiledEdge[];
-    /** Topological order of node IDs. */
-    order: string[];
-    /** nodeId → blockId mapping. */
-    blockIndex: Record<string, string>;
-}
-/** Strategy for how a compiled flow is applied to an existing document. */
-type FlowStrategy = 'full' | 'merge' | 'patch';
-
-declare const buildAuthzFromProps: (props: Record<string, any>) => FlowNodeAuthzExtension;
-declare const buildFlowNodeFromBlock: (block: any) => FlowNode;
-
-interface FlowRuntimeStateManager {
-    get: (nodeId: string) => FlowNodeRuntimeState;
-    update: (nodeId: string, updates: Partial<FlowNodeRuntimeState>) => void;
-}
-declare const createRuntimeStateManager: (editor?: IxoEditorType | null) => 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.
- */
-declare function clearRuntimeForTemplateClone(yDoc: Doc): 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 run, deterministic from invocation context. */
-    runId: 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;
-    /** 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;
-}): 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): Y.Map<Y.Map<unknown>>;
-/**
- * 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): 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): 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): 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): 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): 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): 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;
-    nodeId: string;
-    services: ActionServices;
-    flowNode?: FlowNode;
-    runtime?: FlowRuntimeStateManager;
-    flowUri?: string;
-    handlers?: ActionHandlers;
-    editor?: IxoEditorType;
-    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>;
-    }>;
-}
-/**
- * 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;
-    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 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';
-    /**
-     * 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>;
-    };
-}
-
-interface NodeActionResult {
-    claimId?: string;
-    evaluationStatus?: EvaluationStatus;
-    submittedByDid?: string;
-    payload?: any;
-}
-interface ExecutionContext {
-    runtime: FlowRuntimeStateManager;
-    /** UCAN service — optional for v0.x flows, required for v1.0.0+ */
-    ucanService?: UcanService;
-    /** Invocation store — optional for v0.x flows */
-    invocationStore?: InvocationStore;
-    flowUri: string;
-    flowId: string;
-    flowOwnerDid: string;
-    /** Flow schema version. When set, controls whether UCAN is enforced. */
-    schemaVersion?: string;
-    now?: () => number;
-}
-interface ExecutionOutcome {
-    success: boolean;
-    stage: 'authorization' | 'claim' | 'action' | 'complete';
-    error?: string;
-    result?: NodeActionResult;
-    capabilityId?: string;
-    invocationCid?: string;
-}
-interface ExecuteNodeParams {
-    node: FlowNode;
-    actorDid: string;
-    actorType: 'entity' | 'user';
-    entityRoomId?: string;
-    context: ExecutionContext;
-    action: () => Promise<NodeActionResult>;
-    pin: string;
-}
-/**
- * Execute a node.
- *
- * The pipeline adapts based on the flow's schema version (via context.schemaVersion):
- *
- * **v0.x (legacy):** activation → action → runtime update.
- * UCAN authorization and invocations are skipped when ucanService is not available.
- *
- * **v1.0.0+:** activation → UCAN authorization → invocation → action → runtime update.
- * Requires a configured ucanService with valid delegation chains.
- */
-declare const executeNode: ({ node, actorDid, actorType, entityRoomId, context, action, pin }: ExecuteNodeParams) => Promise<ExecutionOutcome>;
-
-type ActionExecutionCompletionState = 'completed' | 'failed' | 'awaiting_readback' | 'needs_verification';
-
-interface AuthorizationResult {
-    authorized: boolean;
-    reason?: string;
-    capabilityId?: string;
-    proofCids?: string[];
-}
-/**
- * Check if an actor is authorized to execute a block.
- *
- * Behaviour depends on the flow's schema version:
- * - v0.x (or no version): UCAN is optional. If ucanService is unavailable,
- *   execution is allowed without a delegation chain.
- * - v1.0.0+: UCAN is required. A valid delegation chain must exist.
- */
-declare const isAuthorized: (blockId: string, actorDid: string, ucanService: UcanService | undefined, flowUri: string, schemaVersion?: string) => Promise<AuthorizationResult>;
-
-/** Registry interface expected by the compiler (keeps it pure / testable). */
-interface CompilerRegistry {
-    getActionByCan(can: string): ActionDefinition | undefined;
-}
-/**
- * Compile a Base UCAN flow plan into blocks, graph state, and metadata.
- *
- * This is a **pure function** — no React, no Yjs, no side effects.
- * The output is consumed by `hydrateFlowFromPlan()`.
- */
-declare function compileBaseUcanFlow(plan: BaseUcanFlow, registry: CompilerRegistry): CompiledFlow;
-
-/** Describes what changed when merging two compiled flows. */
-interface MergeResult {
-    /** The merged compiled flow (full state). */
-    merged: CompiledFlow;
-    /** Node IDs that were added (new in incoming, not in existing). */
-    added: string[];
-    /** Node IDs that were replaced (patch only — existed and was overwritten). */
-    replaced: string[];
-    /** Node IDs that were kept unchanged from existing. */
-    kept: string[];
-}
-/**
- * Merge an incoming compiled flow into an existing one.
- *
- * This is a **pure function** — no Yjs, no side effects.
- *
- * Strategies:
- * - `merge`: existing nodes win on ID collision. Incoming nodes with new IDs
- *   are added. Existing nodes are never modified.
- * - `patch`: incoming nodes overwrite existing nodes on ID collision. Incoming
- *   nodes with new IDs are added. Existing nodes not in incoming are kept.
- *
- * Edges in the merged result are the union of edges from both sides, filtered
- * to those whose source and target both exist in the merged node set, with
- * duplicates collapsed by edge id. Order is the merged node insertion order
- * (existing first, then newly added) — there is no topological sort because
- * there is no inferred dependency relationship.
- */
-declare function mergeCompiledFlows(existing: CompiledFlow, incoming: CompiledFlow, strategy: 'merge' | 'patch'): MergeResult;
-
-interface SetupFlowOptions {
-    /** The Base UCAN flow plan to compile. */
-    plan: BaseUcanFlow;
-    /** Matrix room ID to hydrate the flow into. */
-    roomId: string;
-    /** Authenticated Matrix client. */
-    matrixClient: MatrixClient;
-    /** DID of the user setting up the flow. */
-    creatorDid: string;
-    /** Optional doc ID override (defaults to plan.flowId). */
-    docId?: string;
-    /**
-     * Room ID of the template this flow was instantiated from, if any.
-     * Recorded into the root map as `source_template_id` for lineage tracking.
-     */
-    templateId?: string;
-    /**
-     * How to apply the plan to the existing document.
-     * - `full` (default): wipe existing flow state and rebuild entirely.
-     * - `merge`: keep existing blocks, add new capabilities from the plan.
-     * - `patch`: replace matching nodes, add new ones, keep the rest.
-     */
-    strategy?: FlowStrategy;
-}
-interface SetupFlowResult {
-    /** The compiled flow artifacts. */
-    compiled: CompiledFlow;
-    /** The room ID (same as input, for convenience). */
-    roomId: string;
-    /** The flow ID from the plan. */
-    flowId: string;
-}
-interface ReadFlowOptions {
-    /** Matrix room ID to read from. */
-    roomId: string;
-    /** Authenticated Matrix client. */
-    matrixClient: MatrixClient;
-}
-interface ReadFlowResult {
-    /** The current flow plan in BaseUcanFlow format (what the agent reads/writes). */
-    plan: BaseUcanFlow;
-    /** The compiled flow state (lower-level representation). */
-    compiled: CompiledFlow;
-    /** The room ID (same as input, for convenience). */
-    roomId: string;
-}
-/**
- * Read the current Base UCAN flow plan from a Matrix room.
- *
- * Connects to the room, reads the Y.Doc, decompiles the flow state
- * back into a `BaseUcanFlow`, and disconnects. Returns `null` if the
- * room has no flow state.
- *
- * **This is the lower-level API.** It exists for cases where you need
- * to read a flow from a room you are NOT currently editing — e.g.
- * cross-room operations or background reads. For the common case of
- * "read the flow the user is currently looking at," use
- * `readFlowFromEditor(editor)` instead. That function takes no
- * parameters from the agent and reads from the editor's existing
- * Y.Doc directly — no Matrix connection, no async, no room ID
- * resolution. The browser tool that exposes `read_flow` to the AI
- * agent should wrap `readFlowFromEditor`, not this function.
- */
-declare function readFlowAsBaseUcan(options: ReadFlowOptions): Promise<ReadFlowResult | null>;
-/**
- * Minimal editor shape required by `readFlowFromEditor` and the active
- * editor registry. The full `IxoEditorType` is fine to pass — this is
- * just a structural lower bound so test harnesses can construct fake
- * editors without pulling in React dependencies.
- */
-interface ReadableEditor {
-    _yDoc?: Y.Doc;
-    getRoomId?: () => string;
-}
-/**
- * Read the current flow from a specific editor instance, synchronously.
- *
- * Use this when you have an editor reference in hand (e.g. from inside a
- * React component, a test, or a multi-editor host that needs to target a
- * specific instance). For the common case of "read the flow the user is
- * currently looking at," prefer the parameterless `readFlow()` below — it
- * uses the active editor registry so you don't have to thread an editor
- * reference through your call sites.
- *
- * Returns `null` ONLY when the editor's Y.Doc has no flow state at all
- * (no nodes AND no meta). An empty `flowId` string is no longer treated
- * as "no flow" — that was the historical bug where successful
- * `setup_flow` calls authored with `flowId: ""` (the documented agent
- * convention) showed up as null on subsequent reads.
- */
-declare function readFlowFromEditor(editor: ReadableEditor): ReadFlowResult | null;
-/**
- * Register an editor as the current active editor. Called by the editor's
- * mount hook when the document is connected and ready. Pass `null` on
- * unmount to clear the registry.
- *
- * If a different editor is already registered, it is replaced silently —
- * the most recent registration wins. This matches the single-editor
- * assumption above.
- */
-declare function setActiveEditor(editor: ReadableEditor | null): void;
-/**
- * Get the currently registered active editor, or null if none is set.
- * Provided for cases where a caller wants to check the registry directly
- * (e.g. for diagnostics) without going through `readFlow()`.
- */
-declare function getActiveEditor(): ReadableEditor | null;
-/**
- * Read the current flow from the active editor, with no parameters at all.
- *
- * This is the parameterless API the AI agent's `read_flow` browser tool
- * should wrap. The browser tool literally becomes `read_flow: () => readFlow()`.
- *
- * Returns `null` if there is no active editor registered (e.g. the editor
- * hasn't finished mounting yet, or no editor is open in this JS context),
- * OR if the active editor's Y.Doc has no flow state at all.
- *
- * If `null` is returned and the user is referencing an existing flow, that
- * is a hard signal to STOP and report to the user — never silently rebuild,
- * because the duplicate-blocks bug is the inevitable consequence.
- */
-declare function readFlow(): ReadFlowResult | null;
-/**
- * One-shot function that compiles a Base UCAN flow plan and writes it
- * into a Matrix room's Y.Doc. After this completes, the room is a
- * normal flow that anyone can open via `useCreateCollaborativeIxoEditor`.
- *
- * Supports three strategies:
- * - `full` (default): clears any existing flow and rebuilds from scratch.
- * - `merge`: adds new capabilities alongside existing ones.
- * - `patch`: replaces matching nodes and adds new ones.
- */
-declare function setupFlowFromBaseUcan(options: SetupFlowOptions): Promise<SetupFlowResult>;
-
-/**
- * Read the current compiled flow state from a live Y.Doc.
- *
- * This is the inverse of `hydrateYDocFromCompiledFlow`. It extracts the flow
- * graph state from Yjs maps so that the pure merge/patch logic can operate
- * on plain objects.
- *
- * Returns `null` if the document has no flow state.
- */
-declare function readCompiledFlowFromYDoc(yDoc: Doc): CompiledFlow | null;
-
-/**
- * Reconstruct a BaseUcanFlow plan from a CompiledFlow.
- *
- * This is the inverse of `compileBaseUcanFlow`. It allows the AI agent to
- * read the current flow in the same format it writes — a plain capability
- * list it can reason about, modify, and pass back to the compiler.
- *
- * This is a **pure function** — no Yjs, no side effects.
- *
- * Note: some information is lossy (e.g. conditions are stored as a JSON
- * string in props and are not fully round-tripped back to ConditionRef).
- * The core capability data (can, with, nb, trigger, actor, ttl, metadata)
- * is fully preserved.
- */
-declare function decompileToBaseUcanFlow(compiled: CompiledFlow): BaseUcanFlow;
-
-type FlowAgentPublicNodeState = 'Pending' | 'Blocked' | 'Overdue' | 'Done';
-type FlowAgentRunPhase = 'Running' | 'Validating' | 'Failed' | 'Archived';
-type FlowAgentBlockerCause = 'missing_input' | 'failed_upstream' | 'missing_ucan' | 'stale_config' | 'service_error' | 'external_confirmation_pending' | 'validation_mismatch' | 'unverified_completion' | 'awaiting_verification' | 'unknown';
-type FlowAgentCommandType = 'diagnose_blocker' | 'assign_actor' | 'notify_actor' | 'execute_action' | 'validate_external_state' | 'archive_flow' | 'propose_config_change';
-type FlowAgentCommandStatus = 'queued' | 'leased' | 'running' | 'confirmed' | 'awaiting_readback' | 'failed' | 'skipped';
-type FlowAgentLedgerEventType = 'agent.decision' | 'agent.command' | 'agent.validation' | 'agent.escalation' | 'agent.memory';
-interface FlowAgentActor {
-    did: string;
-    matrixUserId?: string;
-    displayName?: string;
-    skills?: string[];
-}
-interface FlowAgentLease {
-    id: string;
-    commandId: string;
-    nodeId: string;
-    actorDid: string;
-    acquiredAt: number;
-    expiresAt: number;
-    epoch: number;
-}
-interface FlowAgentNodeSnapshot {
-    nodeId: string;
-    blockType: string;
-    actionType?: string;
-    title?: string;
-    runtime: FlowNodeRuntimeState;
-    publicState: FlowAgentPublicNodeState;
-    blockerCause?: FlowAgentBlockerCause;
-    assigneeDid?: string;
-    dueAt?: number;
-    pendingInvocationCount: number;
-}
-interface FlowAgentCommandBase {
-    id: string;
-    type: FlowAgentCommandType;
-    flowId: string;
-    flowUri: string;
-    nodeId: string;
-    actorDid: string;
-    status: FlowAgentCommandStatus;
-    capability: UcanCapability;
-    idempotencyKey: string;
-    createdAt: number;
-    updatedAt: number;
-    reason: string;
-    payload: Record<string, unknown>;
-    lease?: FlowAgentLease;
-    error?: string;
-}
-type FlowAgentCommand = FlowAgentCommandBase;
-interface FlowAgentLedgerEvent {
-    id: string;
-    type: FlowAgentLedgerEventType;
-    flowId: string;
-    nodeId?: string;
-    commandId?: string;
-    actorDid: string;
-    timestamp: number;
-    details: Record<string, unknown>;
-}
-interface FlowAgentMaps {
-    outbox: Map<FlowAgentCommand>;
-    leases: Map<FlowAgentLease>;
-}
-interface FlowAgentPolicyDecision {
-    allowed: boolean;
-    reason: string;
-    capability: UcanCapability;
-    proofCids: string[];
-}
-interface FlowAgentContext {
-    yDoc: Doc;
-    editor?: IxoEditorType;
-    blocks?: unknown[];
-    flowId: string;
-    flowUri: string;
-    actor: FlowAgentActor;
-    now?: () => number;
-}
-interface FlowAgentCommandResult {
-    commandId: string;
-    success: boolean;
-    output?: Record<string, unknown>;
-    confirmed?: boolean;
-    completionState?: ActionExecutionCompletionState;
-    status?: FlowAgentCommandStatus;
-    error?: string;
-}
-interface FlowAgentExecutor {
-    executeAction?: (command: FlowAgentCommand, context: FlowAgentContext) => Promise<FlowAgentCommandResult>;
-    assignActor?: (command: FlowAgentCommand, context: FlowAgentContext) => Promise<FlowAgentCommandResult>;
-    notifyActor?: (command: FlowAgentCommand, context: FlowAgentContext) => Promise<FlowAgentCommandResult>;
-    validateExternalState?: (command: FlowAgentCommand, context: FlowAgentContext) => Promise<FlowAgentCommandResult>;
-    archiveFlow?: (command: FlowAgentCommand, context: FlowAgentContext) => Promise<FlowAgentCommandResult>;
-    proposeConfigChange?: (command: FlowAgentCommand, context: FlowAgentContext) => Promise<FlowAgentCommandResult>;
-    diagnoseBlocker?: (command: FlowAgentCommand, context: FlowAgentContext) => Promise<FlowAgentCommandResult>;
-}
-interface FlowAgentTickResult {
-    flowDone: boolean;
-    snapshots: FlowAgentNodeSnapshot[];
-    queuedCommands: FlowAgentCommand[];
-    executedCommands: FlowAgentCommandResult[];
-}
-
-interface CreateAgentCommandParams {
-    type: FlowAgentCommandType;
-    flowId: string;
-    flowUri: string;
-    nodeId: string;
-    actor: FlowAgentActor;
-    reason: string;
-    payload?: Record<string, unknown>;
-    now?: number;
-}
-declare function createAgentCommand({ type, flowId, flowUri, nodeId, actor, reason, payload, now }: CreateAgentCommandParams): FlowAgentCommand;
-declare function validateAgentCommand(command: FlowAgentCommand): {
-    valid: boolean;
-    error?: string;
-};
-declare function isExternalMutation(type: FlowAgentCommandType): boolean;
-
-interface BuildFlowAgentContextParams {
-    yDoc: Doc;
-    flowId: string;
-    flowUri?: string;
-    actor: FlowAgentActor;
-    blocks?: unknown[];
-    editor?: IxoEditorType;
-    now?: () => number;
-}
-/**
- * Builds the host-facing runtime context expected by the Flow Agent.
- *
- * Headless hosts own Matrix login, room joins, and Y.Doc sync. Once a host has
- * a live room document and an agent identity, this helper gives it the stable
- * context shape to pass into `tickFlowAgent` or `FlowAgentService`.
- */
-declare function buildFlowAgentContext({ yDoc, flowId, flowUri, actor, blocks, editor, now }: BuildFlowAgentContextParams): FlowAgentContext;
-
-interface AcquireFlowAgentLeaseParams {
-    leases: Map<FlowAgentLease>;
-    commandId: string;
-    nodeId: string;
-    actorDid: string;
-    now?: number;
-    ttlMs?: number;
-}
-declare function acquireFlowAgentLease({ leases, commandId, nodeId, actorDid, now, ttlMs, }: AcquireFlowAgentLeaseParams): FlowAgentLease | null;
-declare function validateFlowAgentLease(leases: Map<FlowAgentLease>, lease: FlowAgentLease, now?: number): boolean;
-declare function releaseFlowAgentLease(leases: Map<FlowAgentLease>, lease: FlowAgentLease): boolean;
-declare function cleanupExpiredFlowAgentLeases(leases: Map<FlowAgentLease>, now?: number): FlowAgentLease[];
-
-declare function requiredCapabilityForCommand(type: FlowAgentCommandType, flowUri: string, nodeId: string): UcanCapability;
-declare function isCapabilityMatch(granted: UcanCapability, required: UcanCapability): boolean;
-declare function canMatches(granted: string, required: string): boolean;
-declare function resourceMatches(granted: string, required: string): boolean;
-interface EvaluateFlowAgentPolicyParams {
-    actorDid: string;
-    commandType: FlowAgentCommandType;
-    flowUri: string;
-    nodeId: string;
-    delegationStore?: UcanDelegationStore;
-    delegations?: StoredDelegation[];
-    now?: number;
-}
-declare function evaluateFlowAgentPolicy({ actorDid, commandType, flowUri, nodeId, delegationStore, delegations, now, }: EvaluateFlowAgentPolicyParams): FlowAgentPolicyDecision;
-
-interface FlowAgentOrchestratorOptions {
-    delegationStore?: UcanDelegationStore;
-    delegations?: StoredDelegation[];
-    candidateActors?: FlowAgentActor[];
-    executor?: FlowAgentExecutor;
-    leaseTtlMs?: number;
-    archiveWhenDone?: boolean;
-}
-declare function planRalphLoopCommands(context: FlowAgentContext, options?: FlowAgentOrchestratorOptions): {
-    snapshots: FlowAgentNodeSnapshot[];
-    queuedCommands: FlowAgentCommand[];
-    flowDone: boolean;
-};
-declare function executeQueuedAgentCommands(context: FlowAgentContext, options?: FlowAgentOrchestratorOptions): Promise<FlowAgentCommandResult[]>;
-declare function tickFlowAgent(context: FlowAgentContext, options?: FlowAgentOrchestratorOptions): Promise<FlowAgentTickResult>;
-
-interface FlowAgentServiceOptions extends FlowAgentOrchestratorOptions {
-    intervalMs?: number;
-    onTick?: (result: FlowAgentTickResult) => void | Promise<void>;
-    onError?: (error: unknown) => void;
-}
-/**
- * Headless-service adapter boundary.
- *
- * Host applications own Matrix login, room joins, and Y.Doc sync. Once they
- * have a live Y.Doc/editor snapshot, this service provides the deterministic
- * Ralph-loop tick and command execution cycle.
- */
-declare class FlowAgentService {
-    private readonly context;
-    private readonly options;
-    private timer;
-    private running;
-    constructor(context: FlowAgentContext, options?: FlowAgentServiceOptions);
-    tick(): Promise<FlowAgentTickResult>;
-    start(): void;
-    stop(): void;
-}
-
-declare function getFlowAgentMaps(yDoc: Doc): FlowAgentMaps;
-declare function computeAgentCommandId(params: {
-    flowId: string;
-    nodeId: string;
-    type: string;
-    payload: Record<string, unknown>;
-}): string;
-declare function queueAgentCommand(yDoc: Doc, command: FlowAgentCommand): {
-    command: FlowAgentCommand;
-    created: boolean;
-};
-declare function readQueuedAgentCommands(yDoc: Doc): FlowAgentCommand[];
-declare function updateAgentCommand(yDoc: Doc, commandId: string, patch: Partial<FlowAgentCommand>): FlowAgentCommand | null;
-declare function appendAgentLedgerEvent(yDoc: Doc, event: Omit<FlowAgentLedgerEvent, 'id'> & {
-    id?: string;
-}): FlowAgentLedgerEvent;
-declare function readAgentLedgerEvents(yDoc: Doc, eventType?: FlowAgentLedgerEventType): FlowAgentLedgerEvent[];
-
-export { type FlowAgentContext as $, type AuthorizationResult as A, type BaseUcanFlow as B, type CompilerRegistry as C, buildFlowAgentContext as D, type ExecuteNodeParams as E, type FlowRuntimeStateManager as F, cleanupExpiredFlowAgentLeases as G, createAgentCommand as H, evaluateFlowAgentPolicy as I, executeQueuedAgentCommands as J, getFlowAgentMaps as K, planRalphLoopCommands as L, type MergeResult as M, type NodeActionResult as N, queueAgentCommand as O, readAgentLedgerEvents as P, readQueuedAgentCommands as Q, type ReadFlowOptions as R, type SetupFlowOptions as S, releaseFlowAgentLease as T, tickFlowAgent as U, validateAgentCommand as V, validateFlowAgentLease as W, type BuildFlowAgentContextParams as X, type FlowAgentActor as Y, type FlowAgentCommand as Z, type FlowAgentCommandResult as _, buildAuthzFromProps as a, type FlowAgentRunPhase as a$, type FlowAgentExecutor as a0, type FlowAgentLease as a1, type FlowAgentNodeSnapshot as a2, type FlowAgentPublicNodeState as a3, type FlowAgentTickResult as a4, type ActionDefinition as a5, type ActionEventDefinition as a6, type OutputSchemaField as a7, type ActionServices as a8, type ActionProofDeclaration as a9, removePendingInvocation as aA, findFailedListenersForSourceRun as aB, replayFailedListenerRun as aC, snapshotInputRefs as aD, computePendingInvocationId as aE, RUN_RECORD_AUDIT_TYPE as aF, type PendingInvocation as aG, type FailedListenerRun as aH, canMatches as aI, computeAgentCommandId as aJ, isCapabilityMatch as aK, isExternalMutation as aL, requiredCapabilityForCommand as aM, resourceMatches as aN, updateAgentCommand as aO, type AcquireFlowAgentLeaseParams as aP, type CreateAgentCommandParams as aQ, type EvaluateFlowAgentPolicyParams as aR, type FlowAgentOrchestratorOptions as aS, type FlowAgentServiceOptions as aT, type FlowAgentCommandBase as aU, type FlowAgentCommandStatus as aV, type FlowAgentCommandType as aW, type FlowAgentLedgerEvent as aX, type FlowAgentLedgerEventType as aY, type FlowAgentMaps as aZ, type FlowAgentPolicyDecision as a_, type RunRecordDetails as aa, type CompiledBlock as ab, type CompiledEdge as ac, type ActionHandlers as ad, type FlowAgentBlockerCause as ae, clearRuntimeForTemplateClone as af, type ActionContext as ag, type HttpService as ah, type EmailService as ai, type NotifyService as aj, type BidService as ak, type ClaimService as al, type CollectionService as am, type CollectionUsersService as an, type MatrixCredentialService as ao, type IntegrationsService as ap, type OracleService as aq, type CarbonService as ar, type EntityService as as, type ActionResult as at, appendRunRecord as au, readRunRecords as av, getPendingInvocationsMap as aw, getOrCreateBlockPendingMap as ax, readPendingInvocations as ay, queuePendingInvocation as az, buildFlowNodeFromBlock as b, type ConditionRef as b0, type ActorConstraint as b1, type TTLConstraint as b2, type RuntimeRef as b3, type CompiledFlowNode as b4, type TriggerSpec as b5, isRuntimeRef as b6, createRuntimeStateManager as c, type ExecutionOutcome as d, executeNode as e, type ExecutionContext as f, readFlowFromEditor as g, readFlow as h, isAuthorized as i, setActiveEditor as j, getActiveEditor as k, compileBaseUcanFlow as l, readCompiledFlowFromYDoc as m, mergeCompiledFlows as n, decompileToBaseUcanFlow as o, type SetupFlowResult as p, type ReadFlowResult as q, readFlowAsBaseUcan as r, setupFlowFromBaseUcan as s, type ReadableEditor as t, type FlowCapability as u, type CompiledFlow as v, type FlowStrategy as w, FlowAgentService as x, acquireFlowAgentLease as y, appendAgentLedgerEvent as z };