@allorc/a423-sdk 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 0.2.0
+
+- Add opt-in `@allorc/a423-sdk/workflow` exports: workflow engine, Next.js-compatible handler, typed HTTP client and canonical agreement hashing.
+- Add versioned quotes, bilateral acceptance, role checks, application policies and configurable transitions.
+- Cover funding, execution gate, submission, verification, release, refund, cancellation, expiry, disputes and resolution through explicit adapters.
+- Persist pending operations before effects, stable provider idempotency keys, reconciliation observations and structured evidence.
+- Preserve the 0.1 root API unchanged. Its approval/settlement behaviour is distinct from the new workflow.
+- Add migration instructions and lifecycle/recovery/HTTP tests. No chain adapter, database driver, signer, queue or PDF renderer is bundled.

package/INTEGRATION.md

@@ -0,0 +1,63 @@
+# Integration instructions for the MVP coding agent
+
+Install after the maintainer publishes:
+
+```sh
+npm install @allorc/a423-sdk@0.2.0
+```
+
+For testing before publication, install the maintainer's `npm pack` tarball instead. Do not silently install 0.1 and assume the workflow entry point exists.
+
+## Task
+
+Integrate the opt-in `@allorc/a423-sdk/workflow` API into the existing MVP. Inspect the installed README, declarations and exports first. Preserve the existing app until a complete equivalent journey passes. Do not introduce demo keys, positional signer lookup, unknown-agent fallback, or authentication based only on x-agent-id. Do not deploy or move real funds as part of integration tests.
+
+1. Implement a durable `WorkflowStore` in the app's database using atomic create and version-checked replacement. Store the whole workflow record together. Keep legacy data separate; explicitly migrate records only after reviewing the mapping. Use stable application-assigned job IDs; recover duplicate creates by loading and comparing the record.
+2. Implement authentication and bind authenticated agent IDs to the application's wallet/signer registry. Keep `@allorc/identity` as public identity derivation only. Configure participants as requester, worker and verifier. Reject unknown agents before signing anything.
+3. Define the application's JSON agreement terms and `validateTerms`: task specification, price, raw amount string, token/chain/contract, participant wallets, deadline, artifact requirements and verification/refund/dispute policy. Preserve decimal metadata. Use the returned SHA-256 agreement hash and revision for bilateral acceptance. Do not substitute this for the existing contract's keccak spec hash: explicitly map and verify both formats where needed.
+4. Implement `fund.execute/reconcile`. Use `operation.id` for persistent deduplication; save provider transaction identifiers before waiting. Validate successful funding event plus actual escrow fields against the agreed terms and trusted chain/contract configuration. Return pending while unconfirmed, confirmed with structured observations only when policy passes, and rejected only on definitive failure. Confirm how the actual ABI exposes specHash; do not skip the comparison silently.
+5. Implement `start` as a fresh eligibility gate. Fail closed if escrow configuration, evidence or chain access is missing. Match funding and assigned worker before scheduling execution. Dispatch actual work through the app's durable queue using a deduplicated run key. The SDK itself does not execute an AI agent.
+6. Implement one submission path: store the actual artifact bytes, hash them, persist the manifest/reference, submit the required on-chain commitment, and wait/reconcile before confirming. If durable execution starts asynchronously, it must not report submitted just because the queue accepted it.
+7. Implement `verify`: validate the exact committed artifact against accepted criteria. Only return confirmed after checks pass. A definitive failure returns rejected, then a separately authorized dispute action records the dispute. Record check results and validator version. If revisions are needed, add explicit transitions and define how they interact with already submitted commitments.
+8. Implement `release.execute/reconcile`, checking caller role, recorded verification and actual payment evidence. Verify exact amount/recipient and relevant event. The SDK state guard does not change contract rules; document whether the contract itself requires submission. Never infer successful payment from a broadcast hash alone.
+9. Implement `refund.execute/reconcile` based on actual contract eligibility. The default rule allows requesting a refund while funded/running; the adapter must enforce the deadline and absence of submission. Submitted disputes require an explicit supported resolution policy. Implement `resolve` only when that policy exists; confirmed resolution evidence must state whether money was released, refunded or remains locked. `resolved` alone does not imply payment.
+10. Add application deadline/expiry checks to authorization and the `expire` adapter. Schedule sweeps with authorized roles. Cancellation only applies before funding in the default workflow. Do not claim automatic sweeps or a dispute timeout exist if they are not implemented.
+11. Configure each adapter's `reconcile` to inspect the provider using durable operation records. Unknown outcomes remain pending. Poll/reconcile in a durable worker. Handle configured confirmations, disappearing observations and reorgs according to the app's policy; the SDK does not include a chain watcher. Add explicit corrective transitions/policies if required rather than editing records outside CAS.
+12. Expose `createWorkflowHandler` through a Node-runtime Next.js catch-all route. Use `createWorkflowClient` or documented HTTP endpoints externally. The old root API and new workflow API use distinct models; migrate the client deliberately.
+13. Build machine-readable receipts through `workflow.receipts`. Revalidate chain evidence before generating chain-backed PDFs; derive amounts/participants from validated observations and use actual token decimals. Distinguish cached observations from freshly checked evidence.
+
+## Adapter shape
+
+```ts
+const adapters = {
+  fund: {
+    async execute({ job, input, operation }) {
+      // Deduplicate operation.id durably, enforce agreed terms and submit/observe.
+      return { status: 'pending', reference: 'your-provider-operation-id' };
+    },
+    async reconcile({ job, operation }) {
+      // Query your saved provider operation. Do not blindly resend.
+      return { status: 'confirmed', evidence: { /* independently validated fields */ } };
+    },
+  },
+  // start, submit, verify, release, refund, expire, resolve as applicable.
+};
+```
+
+This is a structural example, not a working escrow adapter. Never return confirmed unconditionally in an actual integration.
+
+## Required validation before replacing MVP routes
+
+- Happy path: create → quote → both accept same revision/hash → fund confirmed → start gate → submit confirmed → verify → release confirmed → JSON/PDF evidence.
+- Quotes: revised terms clear acceptances; stale revision rejected; funding prevents edits; deadline policy rejects expired quotes.
+- Permissions: anonymous/unknown/unrelated actors blocked; each role enforced; identity hash alone cannot authenticate.
+- Funding: wrong amount, token, chain, contract, payer, worker, verifier, deadline or spec commitment blocks work; missing escrow configuration fails closed.
+- Effects: duplicate requests and simultaneous retries produce one provider operation; differing input with reused key rejected; crashes before/after broadcast and before final DB save recover by reconciliation.
+- Submission: asynchronous execution cannot prematurely submit; bytes match committed digest; missing/failed chain submission stays pending/rejected.
+- Verification: bad output never enables release; dispute recorded; unsupported resolution leaves explicit unresolved state.
+- Refund: before deadline rejected; after deadline/unsubmitted succeeds; submitted work obeys contract restrictions.
+- Exceptions: pre-funding cancellation, unfunded expiry, definitive provider rejection and long pending operations.
+- Receipts: correct raw units/decimals, matching funding/payment/refund events and artifact linkage; provider outage is distinguished from absent evidence.
+- Custom use case: prove a second task type or non-chain provider works without modifying SDK internals.
+
+Report changed files, adapter capabilities, test results and unsupported contract guarantees. Keep real-chain tests opt-in. Do not claim every possible workflow or payment provider is implemented merely because adapter hooks exist.

package/README.md

@@ -1,3 +1,107 @@
+# Configurable workflows in 0.2.0
+
+The new `@allorc/a423-sdk/workflow` entry point provides middleware for agent job lifecycles. It supports different task types and payment systems through application-supplied policies and adapters. It does not assume a particular blockchain, token, wallet, artifact format, database or AI framework. This is experimental software with a reference lifecycle; it does not promise every possible business workflow.
+
+The original root exports remain compatible. Choose the workflow entry point for the full lifecycle; do not mix its records with the original root API. See [integration and migration instructions](./INTEGRATION.md).
+
+```ts
+import { createWorkflow, createWorkflowHandler } from '@allorc/a423-sdk/workflow';
+
+const workflow = createWorkflow({
+  store: durableWorkflowStore,
+  adapters: applicationAdapters,
+  validateTerms: validateYourTerms,
+  authorize: checkYourPolicy,
+});
+const handler = createWorkflowHandler({ workflow, authenticate: authenticateRequest });
+// app/api/a423/[...path]/route.ts
+export const runtime = 'nodejs';
+export { handler as GET, handler as POST };
+```
+
+The names `durableWorkflowStore`, `applicationAdapters`, `validateYourTerms`, `checkYourPolicy` and `authenticateRequest` are application implementations, not SDK exports. Configure them once in a server module and import the handler into your route.
+
+## Workflow coverage
+
+| Action | From | Default role | Result | Required adapter |
+|---|---|---|---|---|
+| create | — | requester | draft | none |
+| quote | draft / quoted / accepted | requester or worker | quoted, acceptances reset | none |
+| accept | quoted | requester and worker separately | accepted after both | none |
+| fund | accepted | requester | funded | fund |
+| start | funded | worker | running | start (funding/work gate) |
+| submit | running | worker | submitted | submit |
+| verify | submitted | verifier | verified | verify |
+| release | verified | verifier | paid | release |
+| refund | funded / running | requester | refunded | refund |
+| cancel | draft / quoted / accepted | requester | cancelled | none |
+| expire | draft / quoted / accepted | requester or worker | expired | expire |
+| dispute | submitted / verified | any of the three parties | disputed | none |
+| resolve | disputed | verifier | resolved | resolve |
+
+`resolved` records a completed resolution process; it does not mean paid or refunded. The resolution adapter must record its actual outcome in evidence. Refund eligibility, quote expiry, deadlines, spending limits, asset rules and verification semantics belong in application policies/adapters. There is no automatic timer. A scheduler calls the API using an authenticated participant or an explicitly configured scheduler role.
+
+### Terms and acceptance
+
+Use JSON terms for your domain: task specification, price, asset, raw amount, deadline, wallet addresses, verifier policy and artifact expectations. Put every term you want committed into this object, including parties and settlement configuration where relevant. The SDK does not invent or validate those domain fields; `validateTerms` should throw on invalid terms. Use decimal strings for raw token amounts, not floating point or JSON bigint.
+
+The SDK hashes sorted-key canonical JSON with SHA-256 (array order preserved, no whitespace). Hash inputs must be plain JSON; avoid cyclic structures and sparse arrays. This is the SDK's own format, not a claim of RFC 8785 compatibility. Names and IDs are case-sensitive. A quote stores revision, terms, hash and acceptances. Accept requires both `agreement_hash` and `revision`; editing a quote clears acceptance. Terms cannot be revised after funding begins under the default rules. Hashes establish integrity, not caller identity or legal consent.
+
+### Adapter contract and recovery
+
+Each effect adapter is either an async function or `{ execute, reconcile }`. It receives `{ job, input, operation }` and returns:
+
+```js
+{ status: 'pending', reference: 'provider-operation-reference' }
+{ status: 'confirmed', evidence: { /* domain-specific verified observations */ } }
+{ status: 'rejected', reason: 'definitive rejection' }
+```
+
+Confirmed results require an evidence object. The SDK trusts the adapter's verdict; it cannot independently establish payment, artifact quality or chain finality. An arbitrary reference is not payment proof. Chain adapters should compare configured chain/contract, job ID, amount, token, participants, deadline and commitments against the accepted terms, plus relevant successful transaction events and the chosen finality policy. `start` must recheck eligibility before work is dispatched.
+
+The SDK atomically stores a pending operation before invoking an effect. Its `operation.id` is stable across retries: use it as the provider idempotency key. **Adapters must durably deduplicate effects, including concurrent calls.** Compare-and-set does not make an external payment exactly-once. If execution throws or returns an invalid result, pending remains; inspect/reconcile it. A pending result retains its observation. A rejected result clears pending without advancing state; repeat the same action key returns the stored job, so use a new key only after a definitive rejection and a deliberate new attempt.
+
+`reconcile(id, actor)` calls only the pending adapter's `reconcile`, never its execute method. That implementation should inspect known provider operations, not blindly repeat a transaction. Supply reconciliation for every external effect. Reuse the same adapter configuration and transitions across restarts. Reconciliation can record additional pending observations. No other action runs while an operation remains pending. If a final database save fails, recovery relies on the same persisted operation and provider key.
+
+The SDK does not run agents or background queues. Persist intent and schedule work in adapters; use a durable worker to submit actual output. Do not mark work submitted merely because a worker was queued. Custom transitions can add milestones, rejection/revision loops, manual review, nonpayment completion, or alternative arbitration. Override whole rules with `{ from, roles, to, effect }`; applications assume responsibility for the resulting invariants. Effect adapters must be trusted server code.
+
+### Storage, permissions and receipts
+
+A workflow store implements `get`, atomic insert-if-absent `create`, and atomic version-checked `compareAndSet`. Persist the entire record (state, pending operation, evidence, events, idempotency history) atomically. Use a separate table/namespace from legacy records. The root `createMemoryStore()` also works structurally at runtime for development, but is not durable or suitable for distributed deployment; a typed workflow store should implement the interface from the workflow entry point.
+
+The handler requires authentication. It obtains actor identity from your callback, never from action bodies. Default role checks always run; `authorize` adds application policy and must return exactly true. Creation requires requester authentication, and requester must differ from worker. The verifier may be the requester or a separate participant. Authentication, wallet/key custody, identity-to-wallet binding and proof of ownership remain application responsibilities. `@allorc/identity` only derives public identifiers.
+
+Receipts are JSON snapshots of agreement, submission, stored adapter evidence, events and pending state. They are not freshly queried chain proofs or signed attestations. Render PDFs separately, and revalidate provider evidence if fresh verification is required. Protect credentials and never put secrets in terms, evidence, metadata or events: all participants can read these fields. Records/events grow over time; production storage should enforce application quotas. The HTTP client limits responses to 1 MiB.
+
+### HTTP and client
+
+| Method | Path beneath `/api/a423` | Body |
+|---|---|---|
+| POST | `/jobs` | `{ id, participants, metadata? }` |
+| GET | `/jobs/:id` | — |
+| POST | `/jobs/:id/actions` | `{ action, input }` plus `Idempotency-Key` |
+| POST | `/jobs/:id/reconcile` | `{}` |
+| GET | `/jobs/:id/receipts` | — |
+
+The handler uses standard Web Request/Response, bounded streaming JSON (64 KiB default), explicit errors, and no background HTTP work. IDs and idempotency keys use 1–128 ASCII letters/digits/underscores/hyphens. Create with a stable application-assigned ID; duplicate creation returns conflict, then retrieve and compare the existing record. Every action needs an actor-scoped key; reusing it with different input fails. Transient conflicts should reload and retry using the same key. Authentication callbacks must inspect headers/cookies or a cloned request if they need the body.
+
+```ts
+import { createWorkflowClient } from '@allorc/a423-sdk/workflow';
+const client = createWorkflowClient({
+  baseUrl: 'https://your-app.example/api/a423',
+  headers: () => ({ Authorization: `Bearer ${serverCredential}` }),
+});
+const quote = await client.act(jobId, 'quote', { terms }, { idempotencyKey: 'quote_1' });
+await client.act(jobId, 'accept', {
+  agreement_hash: quote.agreement!.hash,
+  revision: quote.agreement!.revision,
+}, { idempotencyKey: 'accept_1' });
+```
+
+Each participant needs its own credentials. The client does not automatically retry. Default timeout is 30 seconds; adapters should return pending quickly for long operations. Use TLS and appropriate CSRF protection for cookie-authenticated mutations.
+
+## Original 0.1 API documentation
+
 # @allorc/a423-sdk
 
 One experimental package for exposing an agent job API from a Next.js App Router application. Configure a handler, export it from a catch-all route, and use the typed client to offer, accept, submit and approve work.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allorc/a423-sdk",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Experimental Next.js-friendly agent job SDK with typed HTTP client and pluggable storage, authentication and settlement",
   "license": "MIT",
   "type": "commonjs",
@@ -11,6 +11,11 @@
       "types": "./src/index.d.ts",
       "import": "./src/index.mjs",
       "require": "./src/index.cjs"
+    },
+    "./workflow": {
+      "types": "./src/workflow.d.ts",
+      "import": "./src/workflow.mjs",
+      "require": "./src/workflow.cjs"
     }
   },
   "files": [
@@ -22,7 +27,12 @@
     "examples/nextjs/app/api/a423/*/route.ts",
     "README.md",
     "LICENSE",
-    "SECURITY.md"
+    "SECURITY.md",
+    "src/workflow.cjs",
+    "src/workflow.mjs",
+    "src/workflow.d.ts",
+    "INTEGRATION.md",
+    "CHANGELOG.md"
   ],
   "engines": {
     "node": ">=22"

package/src/workflow.cjs

@@ -0,0 +1,215 @@
+'use strict';
+const { createHash, randomUUID } = require('node:crypto');
+const { A423Error } = require('./index.cjs');
+const copy = value => structuredClone(value);
+const error = (code, message, status = 409) => { throw new A423Error(code, message, status); };
+function canonical(value) {
+  if (value === null || typeof value === 'boolean' || typeof value === 'string') return JSON.stringify(value);
+  if (typeof value === 'number' && Number.isFinite(value)) return JSON.stringify(value);
+  if (Array.isArray(value)) {
+    if (Object.keys(value).length !== value.length) throw new TypeError('Use dense JSON arrays');
+    return '[' + value.map(item => canonical(item)).join(',') + ']';
+  }
+  if (value && Object.getPrototypeOf(value) === Object.prototype) return '{' + Object.keys(value).sort().map(k => JSON.stringify(k) + ':' + canonical(value[k])).join(',') + '}';
+  throw new TypeError('Use JSON values only (no undefined, bigint, class instances or nonfinite numbers)');
+}
+function digest(value) { return createHash('sha256').update(canonical(value)).digest('hex'); }
+function identifier(value) { if (typeof value !== 'string' || !/^[A-Za-z0-9_-]{1,128}$/.test(value)) throw new TypeError('IDs must contain 1–128 letters, digits, underscores or hyphens'); return value; }
+const RULES = {
+  quote: { from: ['draft', 'quoted', 'accepted'], roles: ['requester', 'worker'], to: 'quoted' },
+  accept: { from: ['quoted'], roles: ['requester', 'worker'], to: 'quoted' },
+  fund: { from: ['accepted'], roles: ['requester'], to: 'funded', effect: true },
+  start: { from: ['funded'], roles: ['worker'], to: 'running', effect: true },
+  submit: { from: ['running'], roles: ['worker'], to: 'submitted', effect: true },
+  verify: { from: ['submitted'], roles: ['verifier'], to: 'verified', effect: true },
+  release: { from: ['verified'], roles: ['verifier'], to: 'paid', effect: true },
+  refund: { from: ['funded', 'running'], roles: ['requester'], to: 'refunded', effect: true },
+  cancel: { from: ['draft', 'quoted', 'accepted'], roles: ['requester'], to: 'cancelled' },
+  expire: { from: ['draft', 'quoted', 'accepted'], roles: ['requester', 'worker'], to: 'expired', effect: true },
+  dispute: { from: ['submitted', 'verified'], roles: ['requester', 'worker', 'verifier'], to: 'disputed' },
+  resolve: { from: ['disputed'], roles: ['verifier'], to: 'resolved', effect: true }
+};
+/** Pure canonical JSON SHA-256. This is an integrity commitment, not authentication. */
+function hashAgreement(terms) { return digest(terms); }
+function createWorkflow({ store, adapters = {}, authorize, validateTerms, transitions = {} } = {}) {
+  if (!store || ['get', 'create', 'compareAndSet'].some(k => typeof store[k] !== 'function')) throw new TypeError('Supply an atomic workflow store');
+  const rules = copy(RULES);
+  for (const [action, rule] of Object.entries(transitions)) {
+    identifier(action);
+    if (!rule || !Array.isArray(rule.from) || !rule.from.length || !Array.isArray(rule.roles) || !rule.roles.length || typeof rule.to !== 'string' || !rule.to) throw new TypeError('Transitions require from, roles and to');
+    rules[action] = copy(rule);
+  }
+  const stamp = () => new Date().toISOString();
+  async function save(job, next, type, actor, data = {}) {
+    next.version = job.version + 1; next.updated_at = stamp();
+    next.events.push({ sequence: next.events.length + 1, type, actor_id: actor, at: next.updated_at, data: copy(data) });
+    if (!await store.compareAndSet(job.id, job.version, next)) error('CONFLICT', 'Reload and retry', 409);
+    return next;
+  }
+  async function get(id, actor) {
+    identifier(id); identifier(actor);
+    const job = await store.get(id);
+    if (!job || !Object.values(job.participants).includes(actor)) error('NOT_FOUND', 'Job not found', 404);
+    return copy(job);
+  }
+  async function allowed(job, action, actor, input, rule) {
+    if (!rule.roles.some(role => job.participants[role] === actor)) error('FORBIDDEN', 'Actor cannot perform this action', 403);
+    if (authorize && await authorize({ job: copy(job), action, actor, input: copy(input) }) !== true) error('FORBIDDEN', 'Application policy rejected action', 403);
+  }
+  async function complete(job, result) {
+    const pending = job.pending;
+    if (!result || !['confirmed', 'pending', 'rejected'].includes(result.status)) error('INVALID_ADAPTER_RESULT', 'Adapter must return confirmed, pending or rejected', 502);
+    canonical(result);
+    if (result.status === 'pending') {
+      const next = copy(job); next.pending.observation = copy(result);
+      return save(job, next, pending.action + '.pending', pending.actor, result);
+    }
+    if (result.status === 'rejected') {
+      const next = copy(job); next.pending = null;
+      next.operations[pending.key] = { request_hash: pending.request_hash, status: 'rejected', result: copy(result) };
+      return save(job, next, pending.action + '.rejected', pending.actor, result);
+    }
+    if (!result.evidence || typeof result.evidence !== 'object' || Array.isArray(result.evidence)) error('INVALID_ADAPTER_RESULT', 'Confirmed effects require structured evidence', 502);
+    const next = copy(job); next.pending = null; next.state = pending.target;
+    next.operations[pending.key] = { request_hash: pending.request_hash, status: 'confirmed', result: copy(result) };
+    next.evidence.push({ action: pending.action, operation_id: pending.id, evidence: copy(result.evidence) });
+    if (pending.action === 'submit') next.submission = copy(pending.input);
+    return save(job, next, pending.action + '.confirmed', pending.actor, result.evidence);
+  }
+  async function execute(job, reconcile = false) {
+    const pending = job.pending;
+    const adapter = adapters[pending.action];
+    const fn = reconcile ? adapter?.reconcile : (typeof adapter === 'function' ? adapter : adapter?.execute);
+    if (typeof fn !== 'function') error('ADAPTER_REQUIRED', `Configure ${pending.action}${reconcile ? '.reconcile' : ''}`, 501);
+    // Persisted idempotency key is reused even after crashes. Adapters must deduplicate durably.
+    const result = await fn({ job: copy(job), input: copy(pending.input), operation: copy(pending) });
+    return complete(job, result);
+  }
+  return {
+    async create({ id = randomUUID(), participants, metadata = {} }, actor) {
+      identifier(id); identifier(actor);
+      if (!participants || !participants.requester || !participants.worker || !participants.verifier) throw new TypeError('Supply requester, worker and verifier participants');
+      Object.values(participants).forEach(identifier);
+      if (participants.requester === participants.worker || actor !== participants.requester) error('FORBIDDEN', 'Requester must create the job and differ from worker', 403);
+      canonical(metadata); canonical(participants);
+      const at = stamp();
+      const job = { id, protocol: 'a423.workflow.v1', version: 1, state: 'draft', participants: copy(participants), metadata: copy(metadata), agreement: null, submission: null, pending: null, operations: {}, evidence: [], events: [{ sequence: 1, type: 'created', actor_id: actor, at, data: {} }], created_at: at, updated_at: at };
+      if (authorize && await authorize({ job: copy(job), action: 'create', actor, input: {} }) !== true) error('FORBIDDEN', 'Application policy rejected creation', 403);
+      if (!await store.create(job)) error('CONFLICT', 'Job ID already exists');
+      return copy(job);
+    },
+    get,
+    async act(id, action, input, { actor, idempotencyKey } = {}) {
+      identifier(actor); identifier(idempotencyKey); identifier(action); canonical(input);
+      let job = await get(id, actor);
+      const rule = rules[action];
+      if (!rule) error('UNKNOWN_ACTION', 'Unknown workflow action', 400);
+      await allowed(job, action, actor, input, rule);
+      const key = digest([actor, idempotencyKey]);
+      const requestHash = digest([action, input]);
+      if (Object.hasOwn(job.operations, key)) {
+        if (job.operations[key].request_hash !== requestHash) error('IDEMPOTENCY_CONFLICT', 'Key used for another request');
+        return job;
+      }
+      if (job.pending) {
+        if (job.pending.key !== key || job.pending.request_hash !== requestHash) error('OPERATION_PENDING', 'Reconcile or retry the pending operation first');
+        return execute(job);
+      }
+      if (!rule.from.includes(job.state)) error('INVALID_STATE', `Cannot ${action} from ${job.state}`);
+      let next = copy(job);
+      if (action === 'quote') {
+        if (!input || !input.terms || typeof input.terms !== 'object' || Array.isArray(input.terms)) error('INVALID_INPUT', 'Supply a terms object', 400);
+        if (validateTerms) await validateTerms(copy(input.terms));
+        next.agreement = { revision: (job.agreement?.revision || 0) + 1, terms: copy(input.terms), hash: hashAgreement(input.terms), accepted_by: [] };
+      }
+      if (action === 'accept') {
+        if (!input || input.agreement_hash !== job.agreement.hash || input.revision !== job.agreement.revision) error('AGREEMENT_MISMATCH', 'Accept the current agreement hash and revision');
+        next.agreement.accepted_by = [...new Set([...job.agreement.accepted_by, actor])];
+      }
+      if (rule.effect) {
+        if (!adapters[action]) error('ADAPTER_REQUIRED', `Configure ${action} adapter`, 501);
+        next.pending = { id: `a423:${id}:${key}`, key, action, actor, input: copy(input), request_hash: requestHash, target: rule.to, created_at: stamp(), observation: null };
+        job = await save(job, next, action + '.requested', actor);
+        return execute(job);
+      }
+      next.state = action === 'accept' && [job.participants.requester, job.participants.worker].every(p => next.agreement.accepted_by.includes(p)) ? 'accepted' : rule.to;
+      next.operations[key] = { request_hash: requestHash, status: 'confirmed', result: { status: 'confirmed' } };
+      return save(job, next, action, actor, input);
+    },
+    async reconcile(id, actor) {
+      const job = await get(id, actor);
+      if (!job.pending) return job;
+      await allowed(job, job.pending.action, actor, job.pending.input, rules[job.pending.action]);
+      return execute(job, true);
+    },
+    async receipts(id, actor) {
+      const job = await get(id, actor);
+      return { protocol: job.protocol, job_id: id, state: job.state, agreement: job.agreement, submission: job.submission, evidence: job.evidence, events: job.events, pending: job.pending };
+    }
+  };
+}
+function createWorkflowHandler({ workflow, authenticate, basePath = '/api/a423', maxBodyBytes = 65536, onError } = {}) {
+  if (!workflow || typeof authenticate !== 'function' || !/^\/(?:[A-Za-z0-9_-]+\/)*[A-Za-z0-9_-]+$/.test(basePath)) throw new TypeError('Supply workflow, authenticate and valid basePath');
+  if (!Number.isSafeInteger(maxBodyBytes) || maxBodyBytes < 1 || maxBodyBytes > 1048576) throw new TypeError('Invalid maxBodyBytes');
+  const respond = (value, status = 200) => Response.json(value, { status, headers: { 'cache-control': 'no-store' } });
+  return async request => {
+    try {
+      const path = new URL(request.url).pathname;
+      if (!path.startsWith(basePath + '/')) error('NOT_FOUND', 'Route not found', 404);
+      const match = /^\/jobs(?:\/([A-Za-z0-9_-]{1,128})(?:\/(actions|reconcile|receipts))?)?$/.exec(path.slice(basePath.length));
+      if (!match) error('NOT_FOUND', 'Route not found', 404);
+      const [, id, action] = match;
+      const method = !id || action === 'actions' || action === 'reconcile' ? 'POST' : 'GET';
+      if (request.method !== method) { const r = respond({ error: { code: 'METHOD_NOT_ALLOWED', message: `Use ${method}` } }, 405); r.headers.set('allow', method); return r; }
+      const actor = await authenticate(request);
+      if (!actor) error('UNAUTHENTICATED', 'Authentication required', 401);
+      let body;
+      if (method === 'POST') {
+        if (!(request.headers.get('content-type') || '').toLowerCase().startsWith('application/json')) error('INVALID_INPUT', 'Use application/json', 415);
+        const reader = request.body?.getReader(); if (!reader) error('INVALID_INPUT', 'JSON body required', 400);
+        let size = 0; const chunks = [];
+        try { while (true) { const { done, value } = await reader.read(); if (done) break; size += value.byteLength; if (size > maxBodyBytes) { await reader.cancel(); error('BODY_TOO_LARGE', 'Body too large', 413); } chunks.push(Buffer.from(value)); } } finally { reader.releaseLock(); }
+        try { body = JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { error('INVALID_INPUT', 'Invalid JSON', 400); }
+      }
+      if (!id) return respond({ job: await workflow.create(body, actor) }, 201);
+      if (action === 'actions') return respond({ job: await workflow.act(id, body.action, body.input ?? {}, { actor, idempotencyKey: request.headers.get('idempotency-key') }) });
+      if (action === 'reconcile') return respond({ job: await workflow.reconcile(id, actor) });
+      if (action === 'receipts') return respond(await workflow.receipts(id, actor));
+      return respond({ job: await workflow.get(id, actor) });
+    } catch (err) {
+      if (err instanceof A423Error) return respond({ error: { code: err.code, message: err.message } }, err.status);
+      if (err instanceof TypeError) return respond({ error: { code: 'INVALID_INPUT', message: 'Invalid workflow input' } }, 400);
+      if (onError) { try { await onError(err); } catch {} }
+      return respond({ error: { code: 'INTERNAL_ERROR', message: 'Workflow operation failed; inspect and reconcile pending operations' } }, 500);
+    }
+  };
+}
+module.exports = { createWorkflow, createWorkflowHandler, hashAgreement };
+
+function createWorkflowClient({ baseUrl, headers, fetch: fetchImpl = globalThis.fetch, timeoutMs = 30000 } = {}) {
+  const url = new URL(baseUrl);
+  if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || typeof fetchImpl !== 'function' || !Number.isSafeInteger(timeoutMs) || timeoutMs < 1) throw new TypeError('Invalid client options');
+  const base = url.href.replace(/\/$/, '');
+  async function request(path, body, key) {
+    const h = new Headers(typeof headers === 'function' ? await headers() : headers);
+    h.set('accept', 'application/json');
+    if (body !== undefined) h.set('content-type', 'application/json');
+    if (key !== undefined) h.set('idempotency-key', identifier(key));
+    const response = await fetchImpl(base + path, { method: body === undefined ? 'GET' : 'POST', headers: h, body: body === undefined ? undefined : JSON.stringify(body), signal: AbortSignal.timeout(timeoutMs), redirect: 'error' });
+    const reader = response.body?.getReader(); if (!reader) error('INVALID_RESPONSE', 'Missing response body', 502);
+    const chunks = []; let size = 0;
+    try { while (true) { const {done,value} = await reader.read(); if(done) break; size += value.byteLength; if(size > 1048576) { await reader.cancel(); error('INVALID_RESPONSE','Response exceeds 1 MiB',502); } chunks.push(Buffer.from(value)); } } finally { reader.releaseLock(); }
+    let data; try { data=JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { error('INVALID_RESPONSE','Invalid JSON response',502); }
+    if (!response.ok) error(data.error?.code || 'HTTP_ERROR',data.error?.message || 'Request failed',response.status);
+    return data;
+  }
+  const path = id => '/jobs/' + identifier(id);
+  return {
+    async create(input) { return (await request('/jobs',input)).job; },
+    async get(id) { return (await request(path(id))).job; },
+    async act(id,action,input,{idempotencyKey}={}) { identifier(action);identifier(idempotencyKey);return (await request(path(id)+'/actions',{action,input},idempotencyKey)).job; },
+    async reconcile(id) { return (await request(path(id)+'/reconcile',{})).job; },
+    async receipts(id) { return request(path(id)+'/receipts'); }
+  };
+}
+module.exports.createWorkflowClient = createWorkflowClient;

package/src/workflow.d.ts

@@ -0,0 +1,57 @@
+export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
+export interface Agreement { revision: number; terms: { [key: string]: Json }; hash: string; accepted_by: string[] }
+export interface Operation { id: string; key: string; action: string; actor: string; input: Json; request_hash: string; target: string; created_at: string; observation: AdapterResult | null }
+export interface AdapterResult { status: 'pending' | 'confirmed' | 'rejected'; evidence?: { [key: string]: Json }; [key: string]: Json | undefined }
+export interface WorkflowJob {
+  id: string; protocol: 'a423.workflow.v1'; version: number; state: string;
+  participants: { requester: string; worker: string; verifier: string; [role: string]: string };
+  metadata: Json; agreement: Agreement | null; submission: Json;
+  pending: Operation | null;
+  operations: Record<string, { request_hash: string; status: string; result: AdapterResult }>;
+  evidence: Array<{ action: string; operation_id: string; evidence: { [key: string]: Json } }>;
+  events: Array<{ sequence: number; type: string; actor_id: string; at: string; data: Json }>;
+  created_at: string; updated_at: string;
+}
+export interface WorkflowStore {
+  get(id: string): Promise<WorkflowJob | null>;
+  create(job: WorkflowJob): Promise<boolean>;
+  compareAndSet(id: string, expectedVersion: number, job: WorkflowJob): Promise<boolean>;
+}
+export interface AdapterContext { job: WorkflowJob; input: Json; operation: Operation }
+export type Effect = (context: AdapterContext) => Promise<AdapterResult>;
+export interface Transition { from: string[]; roles: string[]; to: string; effect?: boolean }
+export interface WorkflowOptions {
+  store: WorkflowStore;
+  adapters?: Record<string, Effect | { execute: Effect; reconcile?: Effect }>;
+  /** Return true to allow; authenticated actor ID must be supplied by your application. */
+  authorize?(context: { job: WorkflowJob; action: string; actor: string; input: Json }): boolean | Promise<boolean>;
+  /** Throw to reject application-specific terms. */
+  validateTerms?(terms: { [key: string]: Json }): void | Promise<void>;
+  /** Explicit overrides replace the full rule; application is responsible for its invariants. */
+  transitions?: Record<string, Transition>;
+}
+export interface Workflow {
+  create(input: { id?: string; participants: WorkflowJob['participants']; metadata?: Json }, actor: string): Promise<WorkflowJob>;
+  get(id: string, actor: string): Promise<WorkflowJob>;
+  act(id: string, action: string, input: Json, options: { actor: string; idempotencyKey: string }): Promise<WorkflowJob>;
+  reconcile(id: string, actor: string): Promise<WorkflowJob>;
+  receipts(id: string, actor: string): Promise<Pick<WorkflowJob, 'protocol' | 'state' | 'agreement' | 'submission' | 'evidence' | 'events' | 'pending'> & { job_id: string }>;
+}
+export function hashAgreement(terms: Json): string;
+export function createWorkflow(options: WorkflowOptions): Workflow;
+export function createWorkflowHandler(options: {
+  workflow: Workflow; authenticate(request: Request): string | null | Promise<string | null>;
+  basePath?: string; maxBodyBytes?: number; onError?(error: unknown): void | Promise<void>;
+}): (request: Request) => Promise<Response>;
+export interface WorkflowClient {
+  /** Supply a stable id so creation retries can be resolved with get(id). */
+  create(input: Parameters<Workflow['create']>[0]): Promise<WorkflowJob>;
+  get(id: string): Promise<WorkflowJob>;
+  act(id: string, action: string, input: Json, options: { idempotencyKey: string }): Promise<WorkflowJob>;
+  reconcile(id: string): Promise<WorkflowJob>;
+  receipts(id: string): ReturnType<Workflow['receipts']>;
+}
+export function createWorkflowClient(options: {
+  baseUrl: string; headers?: HeadersInit | (() => HeadersInit | Promise<HeadersInit>);
+  fetch?: typeof globalThis.fetch; timeoutMs?: number;
+}): WorkflowClient;

package/src/workflow.mjs

@@ -0,0 +1,2 @@
+import workflow from './workflow.cjs';
+export const { createWorkflow, createWorkflowHandler, createWorkflowClient, hashAgreement } = workflow;