@ixo/editor 5.40.0 → 6.0.1

package/dist/{store-B-2A-Tlv.d.ts → store-C_KCYNzv.d.ts}

@@ -1,4 +1,4 @@
-import { a7 as FlowNode, ac as FlowNodeAuthzExtension, a5 as FlowNodeRuntimeState, a4 as IxoEditorType, f as UcanService, I as InvocationStore, aa as EvaluationStatus, i as UcanCapability, U as UcanDelegationStore, S as StoredDelegation } from './index-B4Qe8xbv.js';
+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-DL8Yh3Xu.js';
 import * as Y from 'yjs';
 import { Doc, Map } from 'yjs';
 import { MatrixClient } from 'matrix-js-sdk';
@@ -226,17 +226,302 @@ declare const createRuntimeStateManager: (editor?: IxoEditorType | null) => Flow
  */
 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/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/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/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?: any;
-    runtime?: any;
+    flowNode?: FlowNode;
+    runtime?: FlowRuntimeStateManager;
     flowUri?: string;
-    handlers?: any;
-    editor?: any;
-    pendingInvocation?: any;
+    handlers?: ActionHandlers;
+    editor?: IxoEditorType;
+    pendingInvocation?: PendingInvocation;
 }
 /**
  * Lifecycle state of an IXO claims-module collection.
@@ -488,6 +773,273 @@ interface CarbonRetireableBatch {
     /** 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;
+    }) => 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;
@@ -495,582 +1047,332 @@ interface IntegrationExecuteOutcome {
     error?: string;
     code?: 'OK' | 'VALIDATION' | 'AUTH_EXPIRED' | 'UPSTREAM_4XX' | 'UPSTREAM_5XX' | 'RATE_LIMIT' | 'UNKNOWN';
 }
-interface ActionServices {
-    http?: {
-        request: (params: {
-            url: string;
-            method: string;
-            headers?: Record<string, string>;
-            body?: any;
-        }) => Promise<{
-            status: number;
-            headers: Record<string, string>;
-            data: any;
-        }>;
-    };
-    email?: {
-        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;
-        }>;
-    };
-    notify?: {
-        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;
-        }>;
-    };
-    bid?: {
-        submitBid: (params: {
-            collectionId: string;
-            role: string;
-            surveyAnswers: Record<string, any>;
-            entityDid?: 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>;
-    };
-    claim?: {
-        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>;
-    };
+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;
     /**
-     * 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.
+     * 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`.
      */
-    collection?: {
-        /** 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;
-        }>;
-    };
+    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;
+    }>;
     /**
-     * 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.
+     * 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.
      */
-    collectionUsers?: {
-        /**
-         * 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[];
-        }>;
-    };
-    matrix?: {
-        storeCredential: (params: {
-            roomId: string;
-            credentialKey: string;
-            credential: Record<string, any>;
-            cid: string;
-        }) => Promise<{
-            storedAt: string;
-            duplicate: boolean;
-        }>;
-    };
-    integrations?: {
-        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>;
-    };
-    oracle?: {
-        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;
+    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;
         }>;
-        createOracleEntity: (params: {
-            mnemonic: string;
-            address: string;
-            did: string;
-            pubKey: string;
-            pin: string;
-            matrixAccessToken: string;
-            matrixRoomId: string;
+        error?: string;
+    }>;
+    storeConfig: (params: {
+        matrixRoomId: string;
+        config: {
             oracleName: string;
             orgName: string;
             description: string;
             location: string;
-            logoUrl: string;
-            coverImageUrl: string;
-            apiUrl: string;
             price: number;
+            apiUrl: string;
+            entityDid: string;
+            logoUrl: string;
             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<{
+            skills?: string[];
+            mcpServers?: Array<{
                 name: string;
+                url: string;
                 description?: string;
+                authEnvVar?: 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: {
+            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;
-            newApiUrl: string;
-        }) => Promise<{
-            transactionHash: string;
+            adminAddress: string;
+            claimable: number;
         }>;
-    };
+    }) => Promise<{
+        transactionHash: string;
+        harvestedBatchIds: string[];
+        harvestedAmount: number;
+    }>;
     /**
-     * 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.
+     * 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.
      */
-    carbon?: {
-        /**
-         * 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;
+    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 {
     /**
-     * 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.
+     * 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`.
      */
-    entity?: {
-        /**
-         * 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;
-        }>;
-    };
+    transfer: (params: {
+        entityDid: string;
+        recipientDid: string;
+        ownerDid?: string;
+        ownerAddress?: string;
+    }) => Promise<{
+        transactionHash: string;
+        recipientResolved?: string;
+        createdRecipientIid?: boolean;
+    }>;
+}
+/**
+ * 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 {
+    http?: HttpService;
+    email?: EmailService;
+    notify?: NotifyService;
+    bid?: BidService;
+    claim?: ClaimService;
+    collection?: CollectionService;
+    collectionUsers?: CollectionUsersService;
+    matrix?: MatrixCredentialService;
+    integrations?: IntegrationsService;
+    oracle?: OracleService;
+    carbon?: CarbonService;
+    entity?: EntityService;
 }
 interface OutputSchemaField {
     path: string;
@@ -1108,6 +1410,23 @@ interface ActionEventDefinition {
      */
     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". */
@@ -1115,6 +1434,29 @@ interface ActionDefinition<TInputs extends Record<string, any> = Record<string,
     sideEffect: boolean;
     defaultRequiresConfirmation: boolean;
     requiredCapability?: string;
+    /** 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;
     /** 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. */
@@ -1136,9 +1478,10 @@ interface ActionDefinition<TInputs extends Record<string, any> = Record<string,
      *
      * Consumers (trigger picker, flow compiler, event payload picker) prefer
      * `getDynamicEvents(inputs)` when defined and fall back to static `events`
-     * otherwise. The contract is: whatever this returns **is** the event list
-     * for the block — it does not merge with `events`. Include the static
-     * baseline yourself if you want it.
+     * 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[];
     /**
@@ -1147,8 +1490,9 @@ interface ActionDefinition<TInputs extends Record<string, any> = Record<string,
      * refs so survey-derived fields like `output.surveyAnswers.<question>` show
      * up alongside the static baseline.
      *
-     * Returned array **replaces** `outputSchema` for this specific block (no
-     * merging). Include the baseline fields yourself.
+     * 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[];
     /**
@@ -1234,7 +1578,7 @@ interface ExecuteNodeParams {
  */
 declare const executeNode: ({ node, actorDid, actorType, entityRoomId, context, action, pin }: ExecuteNodeParams) => Promise<ExecutionOutcome>;
 
-type ActionExecutionCompletionState = 'completed' | 'failed' | 'awaiting_readback';
+type ActionExecutionCompletionState = 'completed' | 'failed' | 'awaiting_readback' | 'needs_verification';
 
 interface AuthorizationResult {
     authorized: boolean;
@@ -1455,9 +1799,9 @@ declare function readCompiledFlowFromYDoc(yDoc: Doc): CompiledFlow | null;
  */
 declare function decompileToBaseUcanFlow(compiled: CompiledFlow): BaseUcanFlow;
 
-type FlowAgentPublicNodeState = 'Pending' | 'Blocked' | 'Overdue' | 'Done';
+type FlowAgentPublicNodeState = 'Pending' | 'Blocked' | 'Overdue' | 'Done' | 'Active';
 type FlowAgentRunPhase = 'Running' | 'Validating' | 'Failed' | 'Archived';
-type FlowAgentBlockerCause = 'missing_input' | 'failed_upstream' | 'missing_ucan' | 'stale_config' | 'service_error' | 'external_confirmation_pending' | 'validation_mismatch' | 'unknown';
+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' | 'submit_claim' | 'watch_udid' | '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';
@@ -1682,4 +2026,4 @@ declare function appendAgentLedgerEvent(yDoc: Doc, event: Omit<FlowAgentLedgerEv
 }): 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 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 CompiledBlock as a9, type ActorConstraint as aA, type TTLConstraint as aB, type RuntimeRef as aC, type CompiledFlowNode as aD, type TriggerSpec as aE, isRuntimeRef as aF, type CompiledEdge as aa, type FlowAgentBlockerCause as ab, clearRuntimeForTemplateClone as ac, type ActionContext as ad, type ActionResult as ae, canMatches as af, computeAgentCommandId as ag, isCapabilityMatch as ah, isExternalMutation as ai, requiredCapabilityForCommand as aj, resourceMatches as ak, updateAgentCommand as al, type AcquireFlowAgentLeaseParams as am, type CreateAgentCommandParams as an, type EvaluateFlowAgentPolicyParams as ao, type FlowAgentOrchestratorOptions as ap, type FlowAgentServiceOptions as aq, type FlowAgentCommandBase as ar, type FlowAgentCommandStatus as as, type FlowAgentCommandType as at, type FlowAgentLedgerEvent as au, type FlowAgentLedgerEventType as av, type FlowAgentMaps as aw, type FlowAgentPolicyDecision as ax, type FlowAgentRunPhase as ay, type ConditionRef as az, buildFlowNodeFromBlock as b, 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 };
+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 };