@ixo/oracle-runtime-workers 0.22.0 → 0.23.0

package/README.md

@@ -104,19 +104,21 @@ lifetime are in [operations](docs/operations.md).
 
 ## Documentation
 
-| Page                                       | What it covers                                                                                |
-| ------------------------------------------ | --------------------------------------------------------------------------------------------- |
-| [architecture](docs/architecture.md)       | The objects, the gateway split, self-sovereign storage, cost model, workerd rules, tasks      |
-| [node-parity](docs/node-parity.md)         | What is identical to the Node runtime, what differs, what is Workers-only, what is not ported |
-| [configuration](docs/configuration.md)     | Wrangler config, migrations, every env var and binding, `createOracleWorker` options, setup   |
-| [operations](docs/operations.md)           | Routes, status fields, gateway and user-object lifecycle, the ChatGPT proxy, the runbook      |
-| [chat-delivery](docs/chat-delivery.md)     | Chat replies on WhatsApp and Matrix: profiles, Reply Plans, artefacts and their links         |
-| [channels](docs/channels.md)               | The IXO Channels ingress: authorization, retries, Reply Plans, Matrix continuity              |
-| [frontend-bridge](docs/frontend-bridge.md) | Browser tools and AG-UI actions over the socket: one invocation, one socket, unknown outcomes |
-| [pod-creator](docs/pod-creator.md)         | The POD Creator plugin: roles, state in `ctx.kv`, the create path and its launch gate         |
-| [ixo-transaction](docs/ixo-transaction.md) | The opt-in wallet-signing plugin: chain ids, signing outcomes, the mainnet receipt rule       |
-| [testing](docs/testing.md)                 | Unit, harness e2e, the devnet feature matrix, stress                                          |
-| [load-tests](docs/load-tests.md)           | Measurements and the findings that shaped the gateway                                         |
+| Page                                                     | What it covers                                                                                     |
+| -------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| [architecture](docs/architecture.md)                     | The objects, the gateway split, self-sovereign storage, cost model, workerd rules, tasks           |
+| [node-parity](docs/node-parity.md)                       | What is identical to the Node runtime, what differs, what is Workers-only, what is not ported      |
+| [configuration](docs/configuration.md)                   | Wrangler config, migrations, every env var and binding, `createOracleWorker` options, setup        |
+| [operations](docs/operations.md)                         | Routes, status fields, gateway and user-object lifecycle, the ChatGPT proxy, the runbook           |
+| [chat-delivery](docs/chat-delivery.md)                   | Chat replies on WhatsApp and Matrix: profiles, Reply Plans, artefacts and their links              |
+| [channels](docs/channels.md)                             | The IXO Channels ingress: authorization, retries, Reply Plans, Matrix continuity                   |
+| [frontend-bridge](docs/frontend-bridge.md)               | Browser tools and AG-UI actions over the socket: one invocation, one socket, unknown outcomes      |
+| [pod-creator](docs/pod-creator.md)                       | The POD Creator plugin: roles, state in `ctx.kv`, the create path and its launch gate              |
+| [ixo-transaction](docs/ixo-transaction.md)               | The opt-in wallet-signing plugin: chain ids, signing outcomes, the mainnet receipt rule            |
+| [action-proposals](docs/action-proposals.md)             | Action cards: a transfer prepared from chat, signed in the Portal, verified on chain, receipted    |
+| [topic-action-proposals](docs/topic-action-proposals.md) | Topic cards: discussion drafts and claim-access grants as multi-step journals with one-use permits |
+| [testing](docs/testing.md)                               | Unit, harness e2e, the devnet feature matrix, stress                                               |
+| [load-tests](docs/load-tests.md)                         | Measurements and the findings that shaped the gateway                                              |
 
 ## Status (September 2026)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ixo/oracle-runtime-workers",
-  "version": "0.22.0",
+  "version": "0.23.0",
   "description": "QiForge oracle runtime for Cloudflare Workers — Durable Object per user (SQLite in WASM over DO storage), Matrix E2EE gateway Durable Object, Hono HTTP/SSE shell.",
   "private": false,
   "publishConfig": {
@@ -19,6 +19,8 @@
   "exports": {
     ".": "./src/index.ts",
     "./gateway": "./src/gateway-worker.ts",
+    "./hub-actions/client": "./src/hub-actions/client.ts",
+    "./hub-actions/request": "./src/hub-actions/request.ts",
     "./prompt": "./src/core/prompt-composer.ts"
   },
   "files": [
@@ -31,6 +33,7 @@
     "!src/plugins/pod-creator/test-fixtures.ts"
   ],
   "dependencies": {
+    "@ixo/action-protocol": "0.4.1",
     "@blocknote/server-util": "0.29.1",
     "@composio/core": "0.10.0",
     "@composio/langchain": "0.9.2",
@@ -58,9 +61,12 @@
     "wa-sqlite": "1.0.0",
     "yjs": "13.6.32",
     "zod": "^4.4.3",
-    "@ixo/common": "1.7.0",
-    "@ixo/ixo-transaction": "0.1.0",
-    "@ixo/ucan": "2.2.1"
+    "@ixo/impactxclient-sdk": "^3.0.0",
+    "protobufjs": "^7.6.5",
+    "@ixo/topic-protocol": "1.0.0-rc.8",
+    "@ixo/common": "1.7.1",
+    "@ixo/ixo-transaction": "0.2.0",
+    "@ixo/ucan": "2.3.0"
   },
   "devDependencies": {
     "@cloudflare/vitest-pool-workers": "^0.22.0",

package/src/action-proposals/policy.ts

@@ -0,0 +1,54 @@
+import type { ActionProposalSubject } from '@ixo/ixo-transaction/action-proposals';
+import { ActionProposalConflict } from './store';
+
+/** How long a prepared card can be claimed: the plugin's expiry and the owner object's ceiling. */
+export const ACTION_PROPOSAL_TTL_MS = 15 * 60_000;
+/** How far a card's `createdAt` may sit from the object's clock. */
+export const ACTION_PROPOSAL_CLOCK_SKEW_MS = 5 * 60_000;
+
+type Network = ActionProposalSubject['action']['network'];
+
+/**
+ * What the owner object requires of every card before it is stored, whichever
+ * plugin prepared it: the authenticated owner signs from their own account,
+ * on a non-mainnet chain the Worker is configured for and can verify against,
+ * stamped now, expiring inside the policy window. The contract schema already
+ * pins the memo to the card id and one transfer per card.
+ */
+export function assertActionProposalPolicy(
+  subject: ActionProposalSubject,
+  policy: {
+    ownerDid: string;
+    chainIds: Readonly<Record<Network, string>>;
+    rpc: Readonly<Record<Network, string | undefined>>;
+    now: number;
+  },
+): void {
+  if (subject.ownerDid !== policy.ownerDid)
+    throw new ActionProposalConflict('Proposal owner mismatch');
+  if (subject.action.network === 'mainnet')
+    throw new ActionProposalConflict('Mainnet action proposals are disabled');
+  if (subject.action.signerAddress !== policy.ownerDid.replace(/^did:ixo:/, ''))
+    throw new ActionProposalConflict(
+      'The signer must be the authenticated account',
+    );
+  if (subject.action.chainId !== policy.chainIds[subject.action.network])
+    throw new ActionProposalConflict(
+      'Chain ID does not match the configured network',
+    );
+  // A card the Worker could never verify would sit `unknown` for ever.
+  if (!policy.rpc[subject.action.network])
+    throw new ActionProposalConflict(
+      `No chain endpoint is configured for ${subject.action.network}`,
+    );
+  const createdAt = Date.parse(subject.createdAt);
+  if (Math.abs(createdAt - policy.now) > ACTION_PROPOSAL_CLOCK_SKEW_MS)
+    throw new ActionProposalConflict('Proposal timestamp is not current');
+  if (
+    Date.parse(subject.expiresAt) >
+    policy.now + ACTION_PROPOSAL_TTL_MS + ACTION_PROPOSAL_CLOCK_SKEW_MS
+  )
+    throw new ActionProposalConflict(
+      'Proposal expiry exceeds the policy window',
+    );
+}

package/src/action-proposals/reconcile.ts

@@ -0,0 +1,87 @@
+import type { ActionProposal } from '@ixo/ixo-transaction/action-proposals';
+import {
+  TRANSACTION_CARD_BOUND_MISMATCH,
+  TRANSACTION_REJECTIONS,
+  type ActionProposalStore,
+} from './store';
+import { TRANSACTION_NOT_FOUND, verifyActionTransaction } from './verify';
+export async function refreshActionProposal(
+  store: ActionProposalStore,
+  proposal: ActionProposal,
+  rpc: string | undefined,
+  fetcher: typeof fetch = fetch,
+  /** The caller's wall budget: an abort ends the lookup like an RPC outage. */
+  signal?: AbortSignal,
+): Promise<{ proposal: ActionProposal; attempted: boolean }> {
+  if (
+    proposal.lifecycle.status !== 'unknown' ||
+    !proposal.lifecycle.transactionHash ||
+    proposal.lifecycle.executionBlockedAt
+  )
+    return { proposal, attempted: false };
+  if (!(await store.claimVerification(proposal.ownerDid, proposal.id)))
+    return { proposal, attempted: false };
+  if (!rpc) {
+    // No endpoint for this card's network (removed after the card was
+    // prepared; preparation refuses such a network): the cooldown slot is
+    // spent so the alarm backs off and stops instead of ticking every second.
+    console.warn(
+      `[action-proposals] verification of ${proposal.id} pending: no RPC configured for ${proposal.action.network}`,
+    );
+    return { proposal, attempted: false };
+  }
+  try {
+    const verified = await verifyActionTransaction(
+      proposal,
+      proposal.lifecycle.transactionHash,
+      rpc,
+      fetcher,
+      signal,
+    );
+    return {
+      proposal:
+        (await store.recordVerified(
+          proposal.ownerDid,
+          proposal.id,
+          verified,
+        )) ?? proposal,
+      attempted: true,
+    };
+  } catch (error) {
+    // Indexing lag, an RPC outage and a byte mismatch all leave the card
+    // `unknown`; the reason is for the operator, never for the user. A
+    // memo mismatch proves the hash is not this card's, so a later
+    // reconcile may replace it; a transaction with this card's memo and
+    // other messages is the owner's card-bound effect gone wrong, so the
+    // card is blocked with the hash listed.
+    const message = error instanceof Error ? error.message : String(error);
+    console.warn(
+      `[action-proposals] verification of ${proposal.id} pending: ${message}`,
+    );
+    if (message === TRANSACTION_NOT_FOUND)
+      // Inside the grace window after the hash arrived this is the
+      // broadcast or the indexer still in flight, not a spent attempt.
+      await store.deferNotFound(
+        proposal.ownerDid,
+        proposal.id,
+        proposal.lifecycle.transactionHash,
+      );
+    else if (message === TRANSACTION_CARD_BOUND_MISMATCH)
+      await store.blockExecution(
+        proposal.ownerDid,
+        proposal.id,
+        message,
+        proposal.lifecycle.transactionHash,
+      );
+    else if (TRANSACTION_REJECTIONS.has(message))
+      await store.markTransactionRejected(
+        proposal.ownerDid,
+        proposal.id,
+        proposal.lifecycle.transactionHash,
+      );
+    return {
+      proposal: (await store.get(proposal.ownerDid, proposal.id)) ?? proposal,
+      attempted: true,
+    };
+  }
+}