@ixo/flow-work 0.1.1 → 0.3.0

package/dist/capability.d.ts

@@ -1,4 +1,47 @@
 import type { z } from 'zod';
+/**
+ * What the listener hands a capability handler alongside its validated inputs:
+ * the invocation's identity and the UCAN delegation that authorized it. The
+ * listener has already verified the delegation (audience, capability, caveats)
+ * before the handler runs — this context is for handlers that need to *act* on
+ * it, not re-check it.
+ *
+ * A handler that calls a downstream UCAN-guarded service (e.g. the Composio
+ * worker) uses `delegation` to re-mint a fresh, service-targeted invocation
+ * from the same authorization chain, or mints a self-signed one when it acts
+ * as the oracle itself. `invocationId` / `nodeId` are the natural idempotency
+ * key for writes bound to a single flow node.
+ */
+export interface FlowWorkInvocationContext {
+    /** Unique id of this invocation — stable across redelivery. */
+    invocationId: string;
+    /** DID of the manager authenticated by the exact UCAN invoker binding. */
+    managerDid: string;
+    /** The capability ability invoked (equals the handler's `can`). */
+    capability: string;
+    /** The work discriminator invoked (equals the handler's `actionType`). */
+    actionType: string;
+    /** The flow node this work is bound to. */
+    nodeId: string;
+    /** Exact UCAN `with` resource. */
+    resource: string;
+    /** Stable commitment to the validated inputs. */
+    inputHash: string;
+    attempt: number;
+    /** Absolute Unix epoch deadline in milliseconds. */
+    deadline: number;
+    /** Additional contract caveats included exactly in the UCAN nb grant. */
+    contractCaveats: Record<string, unknown>;
+    /** This oracle's DID — the delegation audience. */
+    audience: string;
+    /**
+     * The serialized UCAN delegation (base64 CAR) that authorized this
+     * invocation, already validated by the listener. Pass it to
+     * `ucan.createInvocationFromDelegation(...)` to act on the delegator's
+     * behalf against a downstream service.
+     */
+    delegation: string;
+}
 /**
  * A contractable capability: the unit of work this oracle accepts from
  * flow-manager. `can` is what flow-manager discovers and delegates
@@ -9,7 +52,7 @@ import type { z } from 'zod';
 export interface FlowWorkCapability<Schema extends z.ZodType = z.ZodType> {
     /** Capability ability, e.g. 'flow/diagnose'. Must match the UCAN grant. */
     can: string;
-    /** Work discriminator within the capability, e.g. 'diagnose_http_request'. */
+    /** Work discriminator within the capability, e.g. 'diagnose_action'. */
     actionType: string;
     description: string;
     /**
@@ -20,7 +63,18 @@ export interface FlowWorkCapability<Schema extends z.ZodType = z.ZodType> {
     claimSchemas?: string[];
     /** Validates the invocation's `inputs` before the handler runs. */
     inputSchema: Schema;
-    handler: (inputs: z.infer<Schema>) => Promise<unknown>;
+    /**
+     * Optional trust-boundary validation for the handler result before a
+     * success receipt is posted. Invalid output becomes an `output_invalid`
+     * failure receipt and never reaches flow-manager as advisory state.
+     */
+    outputSchema?: z.ZodType;
+    /**
+     * Runs the work. Receives the validated inputs and the invocation context.
+     * Pure, self-contained handlers (no downstream auth) may ignore the second
+     * argument; handlers that call UCAN-guarded services use its `delegation`.
+     */
+    handler: (inputs: z.infer<Schema>, context: FlowWorkInvocationContext) => Promise<unknown>;
 }
 export declare function findCapability(capabilities: readonly FlowWorkCapability[], can: string, actionType: string): FlowWorkCapability | undefined;
 //# sourceMappingURL=capability.d.ts.map

package/dist/capability.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;IACtE,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,OAAO,EAAE,CAAC,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACxD;AAED,wBAAgB,cAAc,CAC5B,YAAY,EAAE,SAAS,kBAAkB,EAAE,EAC3C,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB,kBAAkB,GAAG,SAAS,CAIhC"}
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAE7B;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,yBAAyB;IACxC,+DAA+D;IAC/D,YAAY,EAAE,MAAM,CAAC;IACrB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,mEAAmE;IACnE,UAAU,EAAE,MAAM,CAAC;IACnB,0EAA0E;IAC1E,UAAU,EAAE,MAAM,CAAC;IACnB,2CAA2C;IAC3C,MAAM,EAAE,MAAM,CAAC;IACf,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAC;IACjB,iDAAiD;IACjD,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,oDAAoD;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,yEAAyE;IACzE,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACzC,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB;;;;;OAKG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;IACtE,2EAA2E;IAC3E,GAAG,EAAE,MAAM,CAAC;IACZ,wEAAwE;IACxE,UAAU,EAAE,MAAM,CAAC;IACnB,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;IACxB,mEAAmE;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,CAAC,OAAO,CAAC;IACzB;;;;OAIG;IACH,OAAO,EAAE,CACP,MAAM,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EACvB,OAAO,EAAE,yBAAyB,KAC/B,OAAO,CAAC,OAAO,CAAC,CAAC;CACvB;AAED,wBAAgB,cAAc,CAC5B,YAAY,EAAE,SAAS,kBAAkB,EAAE,EAC3C,GAAG,EAAE,MAAM,EACX,UAAU,EAAE,MAAM,GACjB,kBAAkB,GAAG,SAAS,CAIhC"}

package/dist/capability.js.map

@@ -1 +1 @@
-{"version":3,"file":"capability.js","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AA0BA,MAAM,UAAU,cAAc,CAC5B,YAA2C,EAC3C,GAAW,EACX,UAAkB;IAElB,OAAO,YAAY,CAAC,IAAI,CACtB,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,KAAK,GAAG,IAAI,KAAK,CAAC,UAAU,KAAK,UAAU,CAChE,CAAC;AACJ,CAAC"}
+{"version":3,"file":"capability.js","sourceRoot":"","sources":["../src/capability.ts"],"names":[],"mappings":"AAoFA,MAAM,UAAU,cAAc,CAC5B,YAA2C,EAC3C,GAAW,EACX,UAAkB;IAElB,OAAO,YAAY,CAAC,IAAI,CACtB,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,GAAG,KAAK,GAAG,IAAI,KAAK,CAAC,UAAU,KAAK,UAAU,CAChE,CAAC;AACJ,CAAC"}

package/dist/flow-work.plugin.d.ts

@@ -12,13 +12,11 @@ export declare class FlowWorkPlugin extends OraclePlugin {
     readonly version = "0.1.0";
     readonly manifest: PluginManifest;
     readonly configSchema: z.ZodObject<{
-        FLOW_WORK_TRUSTED_HOMESERVERS: z.ZodString;
         ORACLE_ENTITY_DID: z.ZodString;
         BLOCKSYNC_GRAPHQL_URL: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>;
-    readonly autoDetectHint = "FLOW_WORK_TRUSTED_HOMESERVERS";
     constructor(options: FlowWorkPluginOptions);
-    autoDetect(env: NodeJS.ProcessEnv): boolean;
+    autoDetect(): boolean;
     getNestModules(ctx?: PluginContext): DynamicModule[];
 }
 //# sourceMappingURL=flow-work.plugin.d.ts.map

package/dist/flow-work.plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flow-work.plugin.d.ts","sourceRoot":"","sources":["../src/flow-work.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,CAAC,EACD,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,KAAK,aAAa,EAGnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,KAAK,GAAG,MAAM,eAAe,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AA4B1D,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,GAAG,CAAC,YAAY,CAAC;IAC/B,YAAY,EAAE,kBAAkB,EAAE,CAAC;CACpC;AAED,qBAAa,cAAe,SAAQ,YAAY;IAWlC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAVpC,QAAQ,CAAC,IAAI,eAAe;IAE5B,QAAQ,CAAC,OAAO,WAAW;IAE3B,QAAQ,CAAC,QAAQ,iBAAY;IAE7B,SAAkB,YAAY;;;;sBAAgB;IAE9C,SAAkB,cAAc,mCAAmC;gBAEtC,OAAO,EAAE,qBAAqB;IAIlD,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC,UAAU,GAAG,OAAO;IAI3C,cAAc,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,aAAa,EAAE;CAiD9D"}
+{"version":3,"file":"flow-work.plugin.d.ts","sourceRoot":"","sources":["../src/flow-work.plugin.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,YAAY,EACZ,CAAC,EACD,KAAK,aAAa,EAClB,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAC7B,OAAO,EAEL,KAAK,aAAa,EAGnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,KAAK,KAAK,GAAG,MAAM,eAAe,CAAC;AAC1C,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AA0B1D,MAAM,WAAW,qBAAqB;IACpC,YAAY,EAAE,GAAG,CAAC,YAAY,CAAC;IAC/B,YAAY,EAAE,kBAAkB,EAAE,CAAC;CACpC;AAED,qBAAa,cAAe,SAAQ,YAAY;IASlC,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC,QAAQ,CAAC,IAAI,eAAe;IAE5B,QAAQ,CAAC,OAAO,WAAW;IAE3B,QAAQ,CAAC,QAAQ,iBAAY;IAE7B,SAAkB,YAAY;;;sBAAgB;gBAEjB,OAAO,EAAE,qBAAqB;IAMlD,UAAU,IAAI,OAAO;IAIrB,cAAc,CAAC,GAAG,CAAC,EAAE,aAAa,GAAG,aAAa,EAAE;CAsE9D"}

package/dist/flow-work.plugin.js

@@ -10,8 +10,6 @@ import { FlowWorkListener } from './listener.js';
 import { adaptMatrixClient } from './matrix-port.js';
 import { buildDelegationValidator } from './ucan.js';
 const configSchema = z.object({
-    /** Comma-separated homeserver domains whose room invites are accepted. */
-    FLOW_WORK_TRUSTED_HOMESERVERS: z.string().trim().min(1),
     /** This oracle's DID — the expected UCAN delegation audience. */
     ORACLE_ENTITY_DID: z.string().trim().min(1),
     /** Blocksync GraphQL endpoint for did:ixo key resolution. */
@@ -19,7 +17,7 @@ const configSchema = z.object({
 });
 const manifest = {
     title: 'Flow Work',
-    summary: 'Accepts contracted work from flow-manager: joins trusted rooms, validates UCAN-delegated ' +
+    summary: 'Accepts contracted work from flow-manager: joins invited rooms, validates UCAN-delegated ' +
         'ixo.flow.work.invoke events, runs the declared capability handler, and posts receipts.',
     whenToUse: [],
     whenNotToUse: [],
@@ -35,26 +33,23 @@ export class FlowWorkPlugin extends OraclePlugin {
     version = '0.1.0';
     manifest = manifest;
     configSchema = configSchema;
-    autoDetectHint = 'FLOW_WORK_TRUSTED_HOMESERVERS';
     constructor(options) {
         super();
         this.options = options;
     }
-    autoDetect(env) {
-        return Boolean(env.FLOW_WORK_TRUSTED_HOMESERVERS?.trim());
+    // Active whenever the oracle registers it in main.ts — the contract surface
+    // has no trust allowlists to gate on, so there is nothing to auto-detect.
+    autoDetect() {
+        return true;
     }
     getNestModules(ctx) {
         if (!ctx)
             throw new Error('FlowWorkPlugin requires a PluginContext');
         const config = configSchema.parse(ctx.config);
-        const trustedHomeservers = config.FLOW_WORK_TRUSTED_HOMESERVERS.split(',')
-            .map((value) => value.trim())
-            .filter((value) => value.length > 0);
         const logger = ctx.logger;
         const listener = new FlowWorkListener({
             port: adaptMatrixClient(this.options.matrixClient),
             oracleDid: config.ORACLE_ENTITY_DID,
-            trustedHomeservers,
             capabilities: this.options.capabilities,
             validateDelegation: buildDelegationValidator({
                 oracleDid: config.ORACLE_ENTITY_DID,
@@ -64,15 +59,29 @@ export class FlowWorkPlugin extends OraclePlugin {
         });
         const matrixClient = this.options.matrixClient;
         class FlowWorkLifecycle {
+            initialStateBootstrapped = false;
+            syncHandler = (state) => {
+                if (!this.initialStateBootstrapped &&
+                    (state === 'PREPARED' || state === 'SYNCING')) {
+                    this.initialStateBootstrapped = true;
+                    void listener.bootstrap().catch((error) => {
+                        logger.error(`[flow-work] post-sync bootstrap failed: ${error instanceof Error ? error.message : String(error)}`);
+                    });
+                }
+            };
             onModuleInit() {
+                // Register flow-work listeners before initial sync can emit invites,
+                // timeline events, or state transitions.
+                listener.start();
+                matrixClient.on('sync', this.syncHandler);
                 // The shared client is also used by EditorPlugin; only start it if
                 // nothing else has.
                 if (!matrixClient.clientRunning) {
                     void matrixClient.startClient();
                 }
-                listener.start();
             }
             onModuleDestroy() {
+                matrixClient.removeListener('sync', this.syncHandler);
                 listener.stop();
             }
         }

package/dist/flow-work.plugin.js.map

@@ -1 +1 @@
-{"version":3,"file":"flow-work.plugin.js","sourceRoot":"","sources":["../src/flow-work.plugin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"flow-work.plugin.js","sourceRoot":"","sources":["../src/flow-work.plugin.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { FlowWorkPlugin, type FlowWorkPluginOptions, } from './flow-work.plugin.js';
-export { findCapability, type FlowWorkCapability } from './capability.js';
-export { FlowWorkListener, homeserverOf } from './listener.js';
-export { adaptMatrixClient, type FlowWorkMatrixPort } from './matrix-port.js';
-export { FLOW_WORK_ASSIGN_EVENT, FLOW_WORK_INVOKE_EVENT, FLOW_WORK_RECEIPT_EVENT, flowWorkInvokeSchema, type FlowWorkErrorCode, type FlowWorkInvoke, type FlowWorkReceipt, } from './protocol.js';
+export { findCapability, type FlowWorkCapability, type FlowWorkInvocationContext, } from './capability.js';
+export { FlowWorkListener } from './listener.js';
+export { adaptMatrixClient, type FlowWorkInvite, type FlowWorkMatrixPort, type FlowWorkRoomEvent, } from './matrix-port.js';
+export { FLOW_WORK_ASSIGN_EVENT, FLOW_WORK_BINDING_FIELDS, FLOW_WORK_INVOKE_EVENT, FLOW_WORK_READY_EVENT, FLOW_WORK_RECEIPT_EVENT, computeFlowWorkInputHash, flowWorkAssignSchema, flowWorkBindingSchema, flowWorkInvokeSchema, flowWorkNbFor, flowWorkReadySchema, flowWorkReceiptSchema, sameFlowWorkBinding, sameFlowWorkNb, type FlowWorkAssign, type FlowWorkBinding, type FlowWorkErrorCode, type FlowWorkInvoke, type FlowWorkNb, type FlowWorkReady, type FlowWorkReceipt, } from './protocol.js';
 export { buildDelegationValidator, type DelegationValidator } from './ucan.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAAE,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAAE,KAAK,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC9E,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,wBAAwB,EAAE,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,KAAK,qBAAqB,GAC3B,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,cAAc,EACd,KAAK,kBAAkB,EACvB,KAAK,yBAAyB,GAC/B,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EACL,iBAAiB,EACjB,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,iBAAiB,GACvB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,EACd,KAAK,cAAc,EACnB,KAAK,eAAe,EACpB,KAAK,iBAAiB,EACtB,KAAK,cAAc,EACnB,KAAK,UAAU,EACf,KAAK,aAAa,EAClB,KAAK,eAAe,GACrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,wBAAwB,EAAE,KAAK,mBAAmB,EAAE,MAAM,WAAW,CAAC"}

package/dist/index.js

@@ -1,7 +1,7 @@
 export { FlowWorkPlugin, } from './flow-work.plugin.js';
-export { findCapability } from './capability.js';
-export { FlowWorkListener, homeserverOf } from './listener.js';
-export { adaptMatrixClient } from './matrix-port.js';
-export { FLOW_WORK_ASSIGN_EVENT, FLOW_WORK_INVOKE_EVENT, FLOW_WORK_RECEIPT_EVENT, flowWorkInvokeSchema, } from './protocol.js';
+export { findCapability, } from './capability.js';
+export { FlowWorkListener } from './listener.js';
+export { adaptMatrixClient, } from './matrix-port.js';
+export { FLOW_WORK_ASSIGN_EVENT, FLOW_WORK_BINDING_FIELDS, FLOW_WORK_INVOKE_EVENT, FLOW_WORK_READY_EVENT, FLOW_WORK_RECEIPT_EVENT, computeFlowWorkInputHash, flowWorkAssignSchema, flowWorkBindingSchema, flowWorkInvokeSchema, flowWorkNbFor, flowWorkReadySchema, flowWorkReceiptSchema, sameFlowWorkBinding, sameFlowWorkNb, } from './protocol.js';
 export { buildDelegationValidator } from './ucan.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GAEf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,cAAc,EAA2B,MAAM,iBAAiB,CAAC;AAC1E,OAAO,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAC/D,OAAO,EAAE,iBAAiB,EAA2B,MAAM,kBAAkB,CAAC;AAC9E,OAAO,EACL,sBAAsB,EACtB,sBAAsB,EACtB,uBAAuB,EACvB,oBAAoB,GAIrB,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,wBAAwB,EAA4B,MAAM,WAAW,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,GAEf,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EACL,cAAc,GAGf,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AACjD,OAAO,EACL,iBAAiB,GAIlB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EACL,sBAAsB,EACtB,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,uBAAuB,EACvB,wBAAwB,EACxB,oBAAoB,EACpB,qBAAqB,EACrB,oBAAoB,EACpB,aAAa,EACb,mBAAmB,EACnB,qBAAqB,EACrB,mBAAmB,EACnB,cAAc,GAQf,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,wBAAwB,EAA4B,MAAM,WAAW,CAAC"}

package/dist/listener.d.ts

@@ -8,44 +8,57 @@ export interface FlowWorkLogger {
 }
 export interface FlowWorkListenerOptions {
     port: FlowWorkMatrixPort;
-    /** This oracle's DID — invocations addressed elsewhere are ignored. */
+    /** This oracle entity DID — the expected UCAN delegation audience. */
     oracleDid: string;
-    /** Homeserver domains whose room invites are accepted. */
-    trustedHomeservers: readonly string[];
     capabilities: readonly FlowWorkCapability[];
     validateDelegation: DelegationValidator;
     logger: FlowWorkLogger;
-    /** How many recent room events to scan for an existing receipt. */
+    /** Delay before retrying an unchanged ready/receipt state publication. */
+    receiptRetryMs?: number;
+    /** Injectable wall clock for deadline tests. */
+    now?: () => number;
+    /** @deprecated v2 receipt replay uses Matrix current state, never a timeline scan. */
     receiptScanLimit?: number;
 }
-/** Hostname of '@user:server.tld' or a bare/prefixed server name. */
-export declare function homeserverOf(value: string): string | null;
 /**
- * The oracle side of the flow-work contract: accepts invites from trusted
- * homeservers, executes UCAN-authorized `ixo.flow.work.invoke` events via
- * the declared capability handlers, and posts `ixo.flow.work.receipt`s.
+ * Oracle-side flow-work v2 state machine.
+ *
+ * Assignment and ready are durable state events. Invoke remains a timeline
+ * command. Receipt is durable state keyed by invocationId, so restart replay
+ * does not depend on a recent-event window.
  */
 export declare class FlowWorkListener {
     private readonly options;
-    private readonly trusted;
+    private readonly assignments;
     private readonly active;
     private readonly completed;
+    private readonly pendingReceipts;
+    private readonly publishedReceipts;
+    private readonly publishing;
+    private readonly retryTimers;
+    private readonly readyTimers;
     private unsubscribe;
+    private started;
     constructor(options: FlowWorkListenerOptions);
+    /** Subscribe synchronously before any Matrix initial sync is started. */
     start(): void;
     stop(): void;
+    /** Reconcile invitations and current assignment state after initial sync. */
+    bootstrap(): Promise<void>;
+    private now;
+    private retryMs;
     private handleInvite;
+    private bootstrapRoom;
     private handleRoomEvent;
-    /**
-     * Bind nb caveats to the invocation before executing. A delegation minted
-     * for one claim schema must not be reusable with unrelated claim data:
-     * `nb.claimSchema` requires the invocation's `inputs.claimSchemaId` to be
-     * present and equal.
-     */
-    private enforceCaveats;
+    private handleAssignment;
+    private hasOwnReady;
+    private acknowledgeAssignment;
+    private handleInvocation;
     private execute;
-    private hasExistingReceipt;
-    private postFailure;
-    private postReceipt;
+    /** Preserve service contract caveats after the full exact nb comparison. */
+    private enforceCaveats;
+    private hasOwnReceipt;
+    private publishReceipt;
+    private scheduleReceiptRetry;
 }
 //# sourceMappingURL=listener.d.ts.map

package/dist/listener.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,KAAK,EAEV,kBAAkB,EAEnB,MAAM,kBAAkB,CAAC;AAS1B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAErD,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,kBAAkB,CAAC;IACzB,uEAAuE;IACvE,SAAS,EAAE,MAAM,CAAC;IAClB,0DAA0D;IAC1D,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC;IACtC,YAAY,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC5C,kBAAkB,EAAE,mBAAmB,CAAC;IACxC,MAAM,EAAE,cAAc,CAAC;IACvB,mEAAmE;IACnE,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AAYD,qEAAqE;AACrE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBzD;AAMD;;;;GAIG;AACH,qBAAa,gBAAgB;IAMf,OAAO,CAAC,QAAQ,CAAC,OAAO;IALpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,WAAW,CAAyB;gBAEf,OAAO,EAAE,uBAAuB;IAa7D,KAAK,IAAI,IAAI;IAuBb,IAAI,IAAI,IAAI;YAKE,YAAY;YAcZ,eAAe;IAgE7B;;;;;OAKG;IACH,OAAO,CAAC,cAAc;YAiBR,OAAO;IAqDrB,OAAO,CAAC,kBAAkB;YAYZ,WAAW;YAcX,WAAW;CAQ1B"}
+{"version":3,"file":"listener.d.ts","sourceRoot":"","sources":["../src/listener.ts"],"names":[],"mappings":"AAAA,OAAO,EAAkB,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAC1E,OAAO,KAAK,EAEV,kBAAkB,EAEnB,MAAM,kBAAkB,CAAC;AAmB1B,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,WAAW,CAAC;AAErD,MAAM,WAAW,cAAc;IAC7B,GAAG,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC3B,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,KAAK,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;CAC9B;AAED,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,kBAAkB,CAAC;IACzB,sEAAsE;IACtE,SAAS,EAAE,MAAM,CAAC;IAClB,YAAY,EAAE,SAAS,kBAAkB,EAAE,CAAC;IAC5C,kBAAkB,EAAE,mBAAmB,CAAC;IACxC,MAAM,EAAE,cAAc,CAAC;IACvB,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,gDAAgD;IAChD,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IACnB,sFAAsF;IACtF,gBAAgB,CAAC,EAAE,MAAM,CAAC;CAC3B;AA4BD;;;;;;GAMG;AACH,qBAAa,gBAAgB;IAkBf,OAAO,CAAC,QAAQ,CAAC,OAAO;IAjBpC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyC;IACrE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAqB;IAC5C,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAqB;IAC/C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqC;IACrE,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAqC;IACvE,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAqB;IAChD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAGxB;IACJ,OAAO,CAAC,QAAQ,CAAC,WAAW,CAGxB;IACJ,OAAO,CAAC,WAAW,CAAyB;IAC5C,OAAO,CAAC,OAAO,CAAS;gBAEK,OAAO,EAAE,uBAAuB;IAM7D,yEAAyE;IACzE,KAAK,IAAI,IAAI;IA8Bb,IAAI,IAAI,IAAI;IAUZ,6EAA6E;IACvE,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;IAShC,OAAO,CAAC,GAAG;IAIX,OAAO,CAAC,OAAO;YAKD,YAAY;YAQZ,aAAa;YASb,eAAe;YAUf,gBAAgB;IAoE9B,OAAO,CAAC,WAAW;YAcL,qBAAqB;YAmCrB,gBAAgB;YAqHhB,OAAO;IA+FrB,4EAA4E;IAC5E,OAAO,CAAC,cAAc;IAiBtB,OAAO,CAAC,aAAa;YAcP,cAAc;IA2B5B,OAAO,CAAC,oBAAoB;CAS7B"}