@allorc/a423-sdk 0.1.0 → 0.3.0

package/src/escrow/index.cjs

@@ -0,0 +1,137 @@
+'use strict';
+const { Contract, Interface, TypedDataEncoder, Transaction, getAddress, sha256, toUtf8Bytes, ZeroHash } = require('ethers');
+const { hashAgreement } = require('../workflow.cjs');
+const artifact = require('./artifact.json');
+const ABI = artifact.abi;
+const TOKEN_ABI = ['function allowance(address,address) view returns(uint256)','function approve(address,uint256) returns(bool)'];
+const TERMS_TYPES = { Terms: [ ['jobId','bytes32'],['payer','address'],['worker','address'],['verifier','address'],['arbitrator','address'],['amount','uint256'],['workDeadline','uint64'],['reviewDeadline','uint64'],['resolutionDeadline','uint64'],['timeoutWorkerBps','uint16'],['agreementHash','bytes32'] ].map(([name,type])=>({name,type})) };
+const transitions = {
+  dispute: {from:['submitted','verified'],roles:['requester','worker','verifier'],to:'disputed',effect:true},
+  resolve: {from:['disputed'],roles:['arbitrator'],to:'settled',effect:true},
+  timeout: {from:['funded','running','submitted','verified','disputed'],roles:['requester','worker','verifier','arbitrator'],to:'settled',effect:true}
+};
+function check(condition,message) { if(!condition) throw new Error('Escrow: '+message); }
+function positive(value,name) { check(typeof value==='string' && /^[1-9][0-9]*$/.test(value),name+' must be a positive decimal string');const n=BigInt(value);check(n<(1n<<256n),name+' exceeds uint256');return n; }
+function bytes32(value) { check(typeof value==='string' && /^0x[0-9a-fA-F]{64}$/.test(value) && value!==ZeroHash,'nonzero bytes32 required');return value; }
+function escrowTerms(job,{chainId,contractAddress,tokenAddress}) {
+  check(job.agreement && hashAgreement(job.agreement.terms)===job.agreement.hash,'agreement hash mismatch');
+  const e=job.agreement.terms.escrow;
+  check(e && e.chain_id===String(chainId) && getAddress(e.contract)===getAddress(contractAddress) && getAddress(e.token)===getAddress(tokenAddress),'chain, contract or token mismatch');
+  const integer=(value,name)=>{check(Number.isSafeInteger(value)&&value>0,name+' must be positive integer seconds');return value;};
+  const t={jobId:sha256(toUtf8Bytes('a423:escrow:v1:'+job.id)),payer:getAddress(e.payer),worker:getAddress(e.worker),verifier:getAddress(e.verifier),arbitrator:getAddress(e.arbitrator),amount:positive(e.amount,'amount'),workDeadline:integer(e.work_deadline,'work_deadline'),reviewDeadline:integer(e.review_deadline,'review_deadline'),resolutionDeadline:integer(e.resolution_deadline,'resolution_deadline'),timeoutWorkerBps:e.timeout_worker_bps,agreementHash:bytes32('0x'+job.agreement.hash)};
+  check(t.workDeadline<t.reviewDeadline && t.reviewDeadline<t.resolutionDeadline,'deadlines must be increasing');
+  check(Number.isInteger(t.timeoutWorkerBps)&&t.timeoutWorkerBps>=0&&t.timeoutWorkerBps<=10000,'invalid timeout allocation');
+  check(t.payer!==t.worker && ![t.payer,t.worker].includes(t.arbitrator),'invalid party separation');
+  return t;
+}
+function workerConsent(job,configuration) { const terms=escrowTerms(job,configuration);return {domain:{name:'A423Escrow',version:'1',chainId:configuration.chainId,verifyingContract:getAddress(configuration.contractAddress)},types:TERMS_TYPES,value:terms}; }
+/** Test-only journal. Production must persist records and reserve nonces atomically across instances. */
+function createMemoryTransactionStore() {
+  const records=new Map(),nonces=new Map(),reservations=new Map();
+  return {
+    async get(id){return records.has(id)?structuredClone(records.get(id)):null;},
+    async create(id,record){if(records.has(id))return false;records.set(id,structuredClone(record));return true;},
+    async reserveNonce(scope,minimum,operationId){const key=scope+':'+operationId;if(reservations.has(key))return reservations.get(key);const nonce=Math.max(minimum,nonces.get(scope)||0);nonces.set(scope,nonce+1);reservations.set(key,nonce);return nonce;}
+  };
+}
+function createEscrowAdapters({provider,chainId,contractAddress,tokenAddress,signerFor,addressFor,transactions,confirmations,validateArtifact}={}) {
+  check(provider && typeof signerFor==='function' && typeof addressFor==='function','provider, signerFor and addressFor required');
+  check(Number.isSafeInteger(chainId)&&chainId>0 && Number.isSafeInteger(confirmations)&&confirmations>0,'explicit chain ID and positive confirmations required');
+  check(transactions && ['get','create','reserveNonce'].every(k=>typeof transactions[k]==='function'),'durable transaction journal required');
+  const config={chainId,contractAddress:getAddress(contractAddress),tokenAddress:getAddress(tokenAddress)};
+  const contract=new Contract(config.contractAddress,ABI,provider), iface=new Interface(ABI), token=new Contract(config.tokenAddress,TOKEN_ABI,provider);
+  async function context(job) {
+    check(Number((await provider.getNetwork()).chainId)===chainId,'RPC chain mismatch');
+    check(getAddress(await contract.token())===config.tokenAddress,'contract token mismatch');
+    const t=escrowTerms(job,config);
+    for(const [role,field] of [['requester','payer'],['worker','worker'],['verifier','verifier'],['arbitrator','arbitrator']]) check(job.participants[role] && getAddress(await addressFor(job.participants[role]))===t[field],role+' wallet mismatch');
+    return t;
+  }
+  function match(snapshot,t) {
+    for(const key of Object.keys(t)) check(String(snapshot.terms[key]).toLowerCase()===String(t[key]).toLowerCase(),'on-chain '+key+' mismatch');
+  }
+  async function receipt(hash) {
+    const r=await provider.getTransactionReceipt(hash);
+    if(!r)return null;
+    const head=await provider.getBlock('latest');
+    const block=await provider.getBlock(r.blockNumber);
+    if(!block || block.hash!==r.blockHash || head.number-r.blockNumber+1<confirmations)return null;
+    return r;
+  }
+  async function send(ctx,suffix,to,data,reconcile) {
+    const id=ctx.operation.id+':'+suffix;
+    let record=await transactions.get(id);
+    if(!record && reconcile)return {status:'pending',reference:id};
+    if(!record) {
+      const signer=await signerFor(ctx.operation.actor);
+      const address=getAddress(await signer.getAddress());
+      check(address===getAddress(await addressFor(ctx.operation.actor)),'signer ownership mismatch');
+      const minimum=await provider.getTransactionCount(address,'pending');
+      let request;
+      try {request=await signer.populateTransaction({to,data,nonce:minimum,chainId});}
+      catch(err) {if(err.code==='CALL_EXCEPTION' || err.code==='INSUFFICIENT_FUNDS')return {status:'rejected',reason:'Transaction preflight rejected before signing'};throw err;}
+      const nonce=await transactions.reserveNonce(`${chainId}:${address}`,minimum,id);
+      request.nonce=nonce;
+      const raw=await signer.signTransaction(request);
+      const tx=Transaction.from(raw);
+      check(tx.from===address && Number(tx.chainId)===chainId && tx.to===getAddress(to) && tx.data===data && tx.nonce===nonce && tx.value===0n,'signed transaction mismatch');
+      await transactions.create(id,{hash:tx.hash,raw,to:getAddress(to),data,from:address});
+      record=await transactions.get(id);
+    }
+    check(record.to===getAddress(to) && record.data===data && record.from===getAddress(await addressFor(ctx.operation.actor)),'journal request mismatch');
+    let r=await receipt(record.hash);
+    if(!r && !reconcile) {
+      try {await provider.broadcastTransaction(record.raw);} catch(err) {if(!await provider.getTransaction(record.hash))throw err;}
+      r=await receipt(record.hash);
+    }
+    if(!r)return {status:'pending',reference:record.hash};
+    if(r.status!==1)return {status:'rejected',reason:'Transaction reverted',reference:record.hash};
+    return {receipt:r};
+  }
+  async function observe(ctx,t,suffix,method,args,eventName,validate,reconcile) {
+    let sent;
+    if(ctx.input.transaction_hash) {
+      check(/^0x[0-9a-fA-F]{64}$/.test(ctx.input.transaction_hash),'invalid transaction hash');
+      const r=await receipt(ctx.input.transaction_hash);
+      sent=!r?{status:'pending',reference:ctx.input.transaction_hash}:r.status===1?{receipt:r}:{status:'rejected',reason:'Transaction reverted',reference:ctx.input.transaction_hash};
+    } else sent=await send(ctx,suffix,config.contractAddress,iface.encodeFunctionData(method,args),reconcile);
+    if(!sent.receipt)return sent;
+    const r=sent.receipt;
+    const logs=r.logs.filter(log=>getAddress(log.address)===config.contractAddress).map(log=>{try{return iface.parseLog(log);}catch{return null;}});
+    const event=logs.find(log=>log?.name===eventName && log.args.jobId===t.jobId);
+    check(event,'matching '+eventName+' event missing');
+    const snapshot=await contract.getJob(t.jobId,{blockTag:r.blockNumber});match(snapshot,t);validate(snapshot,event);
+    return {status:'confirmed',evidence:{chain_id:String(chainId),contract:config.contractAddress,token:config.tokenAddress,job_id:t.jobId,agreement_hash:t.agreementHash,transaction_hash:r.hash,block_number:r.blockNumber,block_hash:r.blockHash,confirmations,event:eventName,amount:t.amount.toString(),payer:t.payer,worker:t.worker,verifier:t.verifier,arbitrator:t.arbitrator,result_hash:snapshot.resultHash,worker_paid:snapshot.workerPaid.toString(),state:Number(snapshot.state),observed_at:new Date().toISOString()}};
+  }
+  function adapter(run){return {execute:ctx=>run(ctx,false),reconcile:ctx=>run(ctx,true)};}
+  const state=(s,n)=>check(Number(s.state)===n,'unexpected escrow state');
+  const settled=(s,e,t)=>{check([5,6,7].includes(Number(s.state)),'not settled');check(e.args.workerAmount+e.args.payerAmount===t.amount && e.args.workerAmount===s.workerPaid,'settlement amount mismatch');};
+  return {
+    fund:adapter(async(ctx,reconcile)=>{
+      const t=await context(ctx.job);
+      check([ctx.job.participants.requester,ctx.job.participants.worker].every(p=>ctx.job.agreement.accepted_by.includes(p)),'both acceptances required');
+      if(typeof ctx.input.worker_signature!=='string')return {status:'rejected',reason:'worker_signature required'};
+      // Consent is checked locally as well as by the contract before moving tokens.
+      const {verifyTypedData}=require('ethers');const c=workerConsent(ctx.job,config);
+      try {if(getAddress(verifyTypedData(c.domain,c.types,c.value,ctx.input.worker_signature))!==t.worker)return {status:'rejected',reason:'Invalid worker consent'};} catch {return {status:'rejected',reason:'Invalid worker consent'};}
+      // Never send further approvals if the funding transaction already exists in the journal.
+      if(!ctx.input.transaction_hash && !await transactions.get(ctx.operation.id+':fund')) {
+        let allowance=await token.allowance(t.payer,config.contractAddress);
+        if(allowance<t.amount) {
+          if(allowance>0n){const reset=await send(ctx,'approve_zero',config.tokenAddress,token.interface.encodeFunctionData('approve',[config.contractAddress,0]),reconcile);if(!reset.receipt)return reset;}
+          const approval=await send(ctx,'approve',config.tokenAddress,token.interface.encodeFunctionData('approve',[config.contractAddress,t.amount]),reconcile);if(!approval.receipt)return approval;
+        }
+      }
+      return observe(ctx,t,'fund','fund',[t,ctx.input.worker_signature],'Funded',(s,e)=>{check(Number(s.state)>0,'missing funded job');check(e.args.amount===t.amount && getAddress(e.args.payer)===t.payer && getAddress(e.args.worker)===t.worker && e.args.agreementHash===t.agreementHash,'funding event mismatch');},reconcile);
+    }),
+    start:adapter(async ctx=>{const t=await context(ctx.job);const block=await provider.getBlock('latest');const safeNumber=block.number-confirmations+1;check(safeNumber>=0,'insufficient confirmation depth');const safe=await provider.getBlock(safeNumber);const confirmed=await contract.getJob(t.jobId,{blockTag:safeNumber});match(confirmed,t);state(confirmed,1);const s=await contract.getJob(t.jobId,{blockTag:block.number});match(s,t);state(s,1);check(block.timestamp<=t.workDeadline,'work deadline passed');return {status:'confirmed',evidence:{chain_id:String(chainId),contract:config.contractAddress,job_id:t.jobId,block_number:safe.number,block_hash:safe.hash,confirmations,amount:t.amount.toString(),agreement_hash:t.agreementHash}};}),
+    submit:adapter(async(ctx,r)=>{const t=await context(ctx.job);const hash=bytes32(ctx.input.result_hash);return observe(ctx,t,'submit','submit',[t.jobId,hash],'Submitted',(s,e)=>{check(Number(s.state)>=2,'missing submission');check(s.resultHash===hash && e.args.resultHash===hash,'artifact commitment mismatch');},r);}),
+    verify:adapter(async(ctx,r)=>{const t=await context(ctx.job);const hash=bytes32(ctx.job.submission?.result_hash);if(!r && !await transactions.get(ctx.operation.id+':verify')){check(typeof validateArtifact==='function','validateArtifact callback required');if(await validateArtifact({job:structuredClone(ctx.job),resultHash:hash})!==true)return {status:'rejected',reason:'Artifact verification failed'};}return observe(ctx,t,'verify','verify',[t.jobId,hash],'Verified',(s,e)=>{check(Number(s.state)>=3,'missing verification');check(s.resultHash===hash && e.args.resultHash===hash,'verified artifact mismatch');},r);}),
+    release:adapter(async(ctx,r)=>{const t=await context(ctx.job);return observe(ctx,t,'release','release',[t.jobId],'Settled',(s,e)=>{state(s,5);settled(s,e,t);check(e.args.workerAmount===t.amount && Number(e.args.reason)===0,'not a full release');},r);}),
+    refund:adapter(async(ctx,r)=>{const t=await context(ctx.job);return observe(ctx,t,'refund','refundExpired',[t.jobId],'Settled',(s,e)=>{state(s,6);settled(s,e,t);check(e.args.payerAmount===t.amount && Number(e.args.reason)===1,'not an expiry refund');},r);}),
+    dispute:adapter(async(ctx,r)=>{const t=await context(ctx.job);const reason=bytes32(ctx.input.reason_hash);return observe(ctx,t,'dispute','dispute',[t.jobId,reason],'Disputed',(s,e)=>{check(Number(s.state)>=4,'missing dispute');check(e.args.reasonHash===reason,'reason mismatch');},r);}),
+    resolve:adapter(async(ctx,r)=>{const t=await context(ctx.job);check(typeof ctx.input.worker_amount==='string' && /^(0|[1-9][0-9]*)$/.test(ctx.input.worker_amount),'worker_amount must be decimal string');const amount=BigInt(ctx.input.worker_amount);check(amount<=t.amount,'resolution exceeds escrow');return observe(ctx,t,'resolve','resolve',[t.jobId,amount],'Settled',(s,e)=>{settled(s,e,t);check(e.args.workerAmount===amount && Number(e.args.reason)===2,'resolution mismatch');},r);}),
+    timeout:adapter(async(ctx,r)=>{const t=await context(ctx.job);const method=['funded','running'].includes(ctx.job.state)?'refundExpired':'timeout';return observe(ctx,t,'timeout',method,[t.jobId],'Settled',(s,e)=>{settled(s,e,t);const expected=method==='refundExpired'?0n:(t.amount*BigInt(t.timeoutWorkerBps))/10000n;check(e.args.workerAmount===expected && Number(e.args.reason)===(method==='refundExpired'?1:3),'timeout allocation mismatch');},r);})
+  };
+}
+module.exports={createEscrowAdapters,createMemoryTransactionStore,workerConsent,escrowTerms,escrowTransitions:transitions,ESCROW_ABI:ABI,ESCROW_BYTECODE:artifact.bytecode};

package/src/escrow/index.d.mts

@@ -0,0 +1,36 @@
+import type { Provider, Signer, TypedDataField, InterfaceAbi } from 'ethers';
+import type { WorkflowJob, AdapterContext, AdapterResult, Transition } from '../workflow.js';
+export interface EscrowConfiguration { chainId: number; contractAddress: string; tokenAddress: string }
+export interface ContractTerms {
+  jobId: string; payer: string; worker: string; verifier: string; arbitrator: string;
+  amount: bigint; workDeadline: number; reviewDeadline: number; resolutionDeadline: number;
+  timeoutWorkerBps: number; agreementHash: string;
+}
+export interface TransactionRecord { hash: string; raw: string; to: string; data: string; from: string }
+export interface TransactionStore {
+  get(id: string): Promise<TransactionRecord | null>;
+  /** Atomic insert if absent; caller reads winner before broadcasting. */
+  create(id: string, record: TransactionRecord): Promise<boolean>;
+  /** Atomically reserve a nonce per chain/address; same operationId always returns same nonce. */
+  reserveNonce(scope: string, minimum: number, operationId: string): Promise<number>;
+}
+export interface EscrowAdapter { execute(context: AdapterContext): Promise<AdapterResult>; reconcile(context: AdapterContext): Promise<AdapterResult> }
+export interface EscrowAdapterOptions extends EscrowConfiguration {
+  provider: Provider;
+  /** Requires populateTransaction + offline signTransaction support; no silent wallet approval. */
+  signerFor(actor: string): Promise<Signer>;
+  addressFor(actor: string): Promise<string>;
+  transactions: TransactionStore;
+  confirmations: number;
+  validateArtifact?(context: { job: WorkflowJob; resultHash: string }): Promise<boolean>;
+}
+export function createEscrowAdapters(options: EscrowAdapterOptions): Record<'fund'|'start'|'submit'|'verify'|'release'|'refund'|'dispute'|'resolve'|'timeout', EscrowAdapter>;
+export function createMemoryTransactionStore(): TransactionStore;
+export function escrowTerms(job: WorkflowJob, config: EscrowConfiguration): ContractTerms;
+export function workerConsent(job: WorkflowJob, config: EscrowConfiguration): {
+  domain: { name: string; version: string; chainId: number; verifyingContract: string };
+  types: Record<string, TypedDataField[]>; value: ContractTerms;
+};
+export const escrowTransitions: Record<string, Transition>;
+export const ESCROW_ABI: InterfaceAbi;
+export const ESCROW_BYTECODE: string;

package/src/escrow/index.d.ts

@@ -0,0 +1,36 @@
+import type { Provider, Signer, TypedDataField, InterfaceAbi } from 'ethers';
+import type { WorkflowJob, AdapterContext, AdapterResult, Transition } from '../workflow.js';
+export interface EscrowConfiguration { chainId: number; contractAddress: string; tokenAddress: string }
+export interface ContractTerms {
+  jobId: string; payer: string; worker: string; verifier: string; arbitrator: string;
+  amount: bigint; workDeadline: number; reviewDeadline: number; resolutionDeadline: number;
+  timeoutWorkerBps: number; agreementHash: string;
+}
+export interface TransactionRecord { hash: string; raw: string; to: string; data: string; from: string }
+export interface TransactionStore {
+  get(id: string): Promise<TransactionRecord | null>;
+  /** Atomic insert if absent; caller reads winner before broadcasting. */
+  create(id: string, record: TransactionRecord): Promise<boolean>;
+  /** Atomically reserve a nonce per chain/address; same operationId always returns same nonce. */
+  reserveNonce(scope: string, minimum: number, operationId: string): Promise<number>;
+}
+export interface EscrowAdapter { execute(context: AdapterContext): Promise<AdapterResult>; reconcile(context: AdapterContext): Promise<AdapterResult> }
+export interface EscrowAdapterOptions extends EscrowConfiguration {
+  provider: Provider;
+  /** Requires populateTransaction + offline signTransaction support; no silent wallet approval. */
+  signerFor(actor: string): Promise<Signer>;
+  addressFor(actor: string): Promise<string>;
+  transactions: TransactionStore;
+  confirmations: number;
+  validateArtifact?(context: { job: WorkflowJob; resultHash: string }): Promise<boolean>;
+}
+export function createEscrowAdapters(options: EscrowAdapterOptions): Record<'fund'|'start'|'submit'|'verify'|'release'|'refund'|'dispute'|'resolve'|'timeout', EscrowAdapter>;
+export function createMemoryTransactionStore(): TransactionStore;
+export function escrowTerms(job: WorkflowJob, config: EscrowConfiguration): ContractTerms;
+export function workerConsent(job: WorkflowJob, config: EscrowConfiguration): {
+  domain: { name: string; version: string; chainId: number; verifyingContract: string };
+  types: Record<string, TypedDataField[]>; value: ContractTerms;
+};
+export const escrowTransitions: Record<string, Transition>;
+export const ESCROW_ABI: InterfaceAbi;
+export const ESCROW_BYTECODE: string;

package/src/escrow/index.mjs

@@ -0,0 +1,2 @@
+import escrow from './index.cjs';
+export const { createEscrowAdapters, createMemoryTransactionStore, workerConsent, escrowTerms, escrowTransitions, ESCROW_ABI, ESCROW_BYTECODE } = escrow;

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;