@allorc/a423-sdk 0.5.0 → 0.8.1

package/SECURITY.md

@@ -1,5 +1,7 @@
 # Security
 
+For the 0.6 accepted cancellation JSON → escrow execution → confirmed receipt subflow, see [CANCELLATION.md](./CANCELLATION.md). The 0.5 contract is unchanged; an accepted instruction is not proof of payment.
+
 Experimental SDK and independently unaudited reference escrow. Use local/testnet evaluation until the deployment and operational model receive independent review.
 
 Reference-contract custody is distinct from the legacy root API, which has no funded escrow. Authority credentials identify keys approved by your operator registry; they are not proof of legal-company status. Administrative enrollment/revocation capabilities must not be exposed to untrusted callers. Use explicit trust roots, TLS, short credential lifetimes, revocation checks and rate-limited proof endpoints.
@@ -15,3 +17,7 @@ Reorg watchers quarantine stale/unavailable evidence; they cannot guarantee fina
 Report vulnerabilities privately through the repository's configured security reporting channel. Do not post credentials, customer records or live exploit details publicly. No completed independent audit is claimed.
 
 Closing settlements in 0.5 require a new deployment and exact current proposal acceptance. Publishing freezes ordinary release, but cannot reverse a release already mined. Proposals never extend original refund/resolution deadlines. Unsubmitted partial-work claims do not remove the original expiry refund right; arbitrary expenses are not automatically owed. First valid closing settlement/refund/arbitration/timeout wins; no later operation can settle the same job again. See SETTLEMENT.md.
+
+## Off-chain profit policy (0.8)
+
+Private cost snapshots and exception decisions live in backend KV, not agreement terms/events. Configure role-aware projectors and never share worker-private responses through public caches. The policy is opt-in and cannot constrain direct external contract calls or prove costs are real. Owner exceptions must be checked by a trusted server approval system, never client flags. Malformed-pending recovery requires an adapter impossibility proof and refuses any known signed/external intent; do not add permissive recovery hooks. See PROFIT-POLICY.md.

package/SETTLEMENT.md

@@ -1,5 +1,9 @@
 # Negotiated closing settlements — 0.5.0
 
+[Start here: installation, arguments and lifecycle maps](./README.md) · [All examples](./examples/README.md)
+
+For the 0.6 accepted cancellation JSON → escrow execution → confirmed receipt subflow, see [CANCELLATION.md](./CANCELLATION.md). The 0.5 contract is unchanged; an accepted instruction is not proof of payment.
+
 This release adds a closing negotiation for cancellation and partial-work compensation. A party proposes a worker payment, the other can counter or accept, and the contract pays the agreed amount and refunds the remainder atomically. It closes the whole job. **It does not introduce partial releases while continuing work or milestone payments.**
 
 ## Separate facts

package/examples/README.md

@@ -0,0 +1,29 @@
+# A423 examples
+
+Start with the [main README](../README.md) for installation, configuration arguments and lifecycle diagrams. These examples target the source version in `package.json`; check the installed npm version before copying newer APIs.
+
+| Example | Purpose | Chain activity |
+|---|---|---|
+| [quickstart.mjs](./quickstart.mjs) | Runnable in-memory agreement and pure profit calculation | None; no wallet or funding adapter |
+| [operations-server.mjs](./operations-server.mjs) | Localhost HTTP shell around a configured application handler | Only through your explicitly configured adapters/signers |
+| [operations-dashboard.html](./operations-dashboard.html) | Reference UI for states, wallet consent, cancellation JSON, receipts and private economics | Actions use the authenticated backend |
+| [nextjs/lib/a423.ts](./nextjs/lib/a423.ts) | Older root API example | No settlement adapter; records approval only |
+| [client.mjs](./client.mjs) | Older root API client example | Depends on the configured server; not the reference workflow client |
+
+Run the no-chain example from the source repository:
+
+```sh
+node examples/quickstart.mjs
+```
+
+After installing the package in another app, copy the quickstart file and run it there; it imports public package entry points.
+
+For the modern escrow path, construct `createEscrowApplication` with your authority, durable storage, deployment registry, signing/spending approvals and artifact validator. Mount its handler in Next.js with the Node runtime or use the local shell. The old `examples/nextjs` code intentionally demonstrates the preserved root API; do not mistake it for the new escrow workflow.
+
+The shell requires your own configuration module exporting `applicationOptions`:
+
+```sh
+A423_CONFIG_MODULE=/absolute/path/config.mjs node examples/operations-server.mjs
+```
+
+The operational worker separately requires `workerOptions`; see [OPERATIONS.md](../OPERATIONS.md). Installing a package, mounting an HTTP handler and running a keeper are separate steps. No example supplies default credentials, signing keys or a deployed contract.

package/examples/operations-dashboard.html

@@ -7,10 +7,10 @@
 const $=id=>document.getElementById(id);let credential='';
 async function api(path,body,key){const response=await fetch(path,{method:body===undefined?'GET':'POST',headers:{authorization:'Bearer '+credential,...(body===undefined?{}:{'content-type':'application/json'}),...(key?{'idempotency-key':key}:{})},body:body===undefined?undefined:JSON.stringify(body)});const data=await response.json();if(!response.ok)throw Error(JSON.stringify(data));return data;}
 function show(error){$('status').textContent=error.message||String(error);}
-async function load(){credential=$('token').value;const data=await api('/api/state');$('jobs').replaceChildren();for(const job of data.a423.jobs){const article=document.createElement('article');const title=document.createElement('h2');title.textContent=job.id+' · '+job.state+(job.safety?.blocked?' · SAFETY HOLD':'')+(job.pending?' · '+job.pending.action+' pending':'');article.append(title);const info=document.createElement('pre');info.textContent=JSON.stringify({work_status:job.work_status,escrow_ledger:job.escrow_ledger,negotiation:job.negotiation,safety:job.safety,participants:job.participants,agreement:job.agreement,submission:job.submission,evidence:job.evidence},null,2);article.append(info);
-const action=document.createElement('select');for(const value of ['quote','accept','fund','start','submit','verify','release','refund','dispute','resolve','timeout','propose_settlement','counter_settlement','accept_settlement','cancel','expire']){const o=document.createElement('option');o.textContent=value;action.append(o);}const input=document.createElement('textarea');input.value='{}';action.onchange=()=>{const p=job.negotiation?.current;if(['propose_settlement','counter_settlement'].includes(action.value))input.value=JSON.stringify({expected_revision:p?.escrow_version||0,worker_amount:p?.worker_amount||'0',expires_at:Math.min(Math.floor(Date.now()/1000)+3600,job.agreement?.terms.escrow.resolution_deadline||0),reason:'Explain completed work and proposed compensation',claims:[]},null,2);if(action.value==='accept_settlement'&&p)input.value=JSON.stringify({expected_revision:p.escrow_version,proposal_hash:p.proposal_hash},null,2);};const key=document.createElement('input');key.value=crypto.randomUUID();key.title='Keep this key when retrying the same action';const run=document.createElement('button');run.textContent='Run action';run.onclick=async()=>{try{await api('/api/a423/jobs/'+job.id+'/actions',{action:action.value,input:JSON.parse(input.value)},key.value);await load();}catch(e){show(e);}};
+async function load(){credential=$('token').value;const data=await api('/api/state');$('jobs').replaceChildren();for(const job of data.a423.jobs){const article=document.createElement('article');const title=document.createElement('h2');title.textContent=job.id+' · '+job.state+(job.safety?.blocked?' · SAFETY HOLD':'')+(job.pending?' · '+job.pending.action+' pending':'');article.append(title);if(job.profit){const economics=document.createElement('p');const p=job.profit;economics.textContent=p.cost_basis_raw!==undefined?'Raw token units · Cost: '+p.cost_basis_raw+' · Target payout: '+p.target_payout+' · Minimum: '+p.min_payout+' · Current: '+p.projected_payout_raw+' · '+(p.receipt_confirmed?'Realized':'Projected')+' profit: '+(p.receipt_confirmed?p.realized_profit_raw:p.projected_profit_raw)+' · Margin bps: '+(p.receipt_confirmed?p.realized_margin_bps:p.projected_margin_bps)+' · '+p.target_status:'Proposed payout: '+(p.proposed_payout_raw??'—')+' · Confirmed payout: '+(p.realized_payout_raw??'pending');article.append(economics);}const info=document.createElement('pre');info.textContent=JSON.stringify({epoch:job.epoch,pre_funding_cancellations:job.pre_funding_cancellations,profit:job.profit,work_status:job.work_status,escrow_ledger:job.escrow_ledger,negotiation:job.negotiation,subflows:job.subflows,active_subflow_id:job.active_subflow_id,safety:job.safety,participants:job.participants,agreement:job.agreement,submission:job.submission,evidence:job.evidence},null,2);article.append(info);
+const action=document.createElement('select');for(const value of ['quote','accept','fund','start','submit','verify','release','refund','dispute','resolve','timeout','propose_settlement','counter_settlement','approve_cancellation','execute_cancellation','accept_settlement','cancel','decline','reopen','expire']){const o=document.createElement('option');o.textContent=value;action.append(o);}const input=document.createElement('textarea');input.value='{}';action.onchange=()=>{input.value=JSON.stringify({expected_epoch:job.epoch||0},null,2);if(action.value==='reopen')input.value=JSON.stringify({cancellation_id:job.pre_funding_cancellations?.at(-1)?.id},null,2);const p=job.negotiation?.current;if(['propose_settlement','counter_settlement'].includes(action.value))input.value=JSON.stringify({expected_revision:p?.escrow_version||0,worker_amount:p?.worker_amount||'0',expires_at:Math.min(Math.floor(Date.now()/1000)+3600,job.agreement?.terms.escrow.resolution_deadline||0),reason:'Explain completed work and proposed compensation',claims:[]},null,2);if(['accept_settlement','approve_cancellation'].includes(action.value)&&p)input.value=JSON.stringify({expected_revision:p.escrow_version,proposal_hash:p.proposal_hash},null,2);if(action.value==='execute_cancellation')input.value=JSON.stringify({instruction_id:job.subflows?.find(s=>s.kind==='cancellation')?.instruction?.id||''},null,2);};const key=document.createElement('input');key.value=crypto.randomUUID();key.title='Keep this key when retrying the same action';const run=document.createElement('button');run.textContent='Run action';run.onclick=async()=>{try{await api('/api/a423/jobs/'+job.id+(action.value==='approve_cancellation'?'/cancellation/accept':'/actions'),action.value==='approve_cancellation'?{expected_epoch:job.epoch||0,...JSON.parse(input.value)}:{action:action.value,input:{expected_epoch:job.epoch||0,...JSON.parse(input.value)}},key.value);await load();}catch(e){show(e);}};
 const consent=document.createElement('button');consent.textContent='Sign worker consent with wallet';consent.onclick=async()=>{try{if(!window.ethereum)throw Error('EIP-1193 wallet required');const typed=await api('/api/a423-worker-consent/'+job.id);const accounts=await window.ethereum.request({method:'eth_requestAccounts'});if(accounts[0].toLowerCase()!==typed.value.worker.toLowerCase())throw Error('Choose the agreed worker account');const signature=await window.ethereum.request({method:'eth_signTypedData_v4',params:[accounts[0],JSON.stringify({domain:typed.domain,primaryType:'Terms',types:{EIP712Domain:[{name:'name',type:'string'},{name:'version',type:'string'},{name:'chainId',type:'uint256'},{name:'verifyingContract',type:'address'}],...typed.types},message:typed.value})]});input.value=JSON.stringify({worker_signature:signature},null,2);action.value='fund';show('Worker signed. Share the public signature with the authenticated payer to fund.');}catch(e){show(e);}};
 const receipts=document.createElement('button');receipts.textContent='Fresh JSON receipt';receipts.onclick=async()=>{try{info.textContent=JSON.stringify(await api('/api/a423-receipts/'+job.id),null,2);}catch(e){show(e);}};const pdf=document.createElement('button');pdf.textContent='Fresh PDF';pdf.onclick=async()=>{try{const r=await fetch('/api/a423-receipts/'+job.id+'.pdf',{headers:{authorization:'Bearer '+credential}});if(!r.ok)throw Error('Evidence unavailable');const url=URL.createObjectURL(await r.blob());const a=document.createElement('a');a.href=url;a.download=job.id+'.pdf';a.click();setTimeout(()=>URL.revokeObjectURL(url),10000);}catch(e){show(e);}};
-const closing=document.createElement('button');closing.textContent='Sign current closing split';closing.onclick=async()=>{try{if(!window.ethereum)throw Error('EIP-1193 wallet required');const typed=await api('/api/a423-settlement-consent/'+job.id);const accounts=await window.ethereum.request({method:'eth_requestAccounts'});const address=accounts[0].toLowerCase(),terms=job.agreement.terms.escrow;const field=address===terms.payer.toLowerCase()?'payer_signature':address===terms.worker.toLowerCase()?'worker_signature':null;if(!field)throw Error('Choose the agreed payer or worker wallet');if(!confirm('Close this job: '+typed.value.workerAmount+' raw units to worker, '+typed.value.payerAmount+' refunded. Review the claim and wallet prompt.'))return;const signature=await window.ethereum.request({method:'eth_signTypedData_v4',params:[accounts[0],JSON.stringify({domain:typed.domain,primaryType:'ClosingSettlement',types:{EIP712Domain:[{name:'name',type:'string'},{name:'version',type:'string'},{name:'chainId',type:'uint256'},{name:'verifyingContract',type:'address'}],...typed.types},message:typed.value})]});let previous={};try{previous=JSON.parse(input.value);}catch{}input.value=JSON.stringify({...previous,expected_revision:typed.value.escrowVersion,proposal_hash:typed.value.proposalHash,[field]:signature},null,2);action.value='accept_settlement';show('Signed closing split. Combine both parties’ signatures to relay, or let the counterparty accept directly.');}catch(e){show(e);}};article.append(action,input,key,run,consent,closing,receipts,pdf);$('jobs').append(article);}show('Loaded '+data.a423.jobs.length+' workflows');}
+const closing=document.createElement('button');closing.textContent='Sign current closing split';closing.onclick=async()=>{try{if(!window.ethereum)throw Error('EIP-1193 wallet required');const typed=await api('/api/a423-settlement-consent/'+job.id);const accounts=await window.ethereum.request({method:'eth_requestAccounts'});const address=accounts[0].toLowerCase(),terms=job.agreement.terms.escrow;const field=address===terms.payer.toLowerCase()?'payer_signature':address===terms.worker.toLowerCase()?'worker_signature':null;if(!field)throw Error('Choose the agreed payer or worker wallet');if(!confirm('Close this job: '+typed.value.workerAmount+' raw units to worker, '+typed.value.payerAmount+' refunded. Review the claim and wallet prompt.'))return;const signature=await window.ethereum.request({method:'eth_signTypedData_v4',params:[accounts[0],JSON.stringify({domain:typed.domain,primaryType:'ClosingSettlement',types:{EIP712Domain:[{name:'name',type:'string'},{name:'version',type:'string'},{name:'chainId',type:'uint256'},{name:'verifyingContract',type:'address'}],...typed.types},message:typed.value})]});let previous={};try{previous={expected_epoch:job.epoch||0,...JSON.parse(input.value)};}catch{}input.value=JSON.stringify({...previous,expected_revision:typed.value.escrowVersion,proposal_hash:typed.value.proposalHash,[field]:signature},null,2);action.value='approve_cancellation';show('Signed closing split. Combine both wallet signatures, then Run action to save acceptance and forward to escrow.');}catch(e){show(e);}};const cancellation=document.createElement('button');cancellation.textContent='Confirmed cancellation receipt';cancellation.onclick=async()=>{try{info.textContent=JSON.stringify(await api('/api/a423/jobs/'+job.id+'/cancellation/receipt'),null,2);}catch(e){show(e);}};const instruction=document.createElement('button');instruction.textContent='Accepted cancellation JSON';instruction.onclick=async()=>{try{info.textContent=JSON.stringify(await api('/api/a423/jobs/'+job.id+'/cancellation/instruction'),null,2);}catch(e){show(e);}};article.append(action,input,key,run,consent,closing,instruction,cancellation,receipts,pdf);$('jobs').append(article);}show('Loaded '+data.a423.jobs.length+' workflows');}
 $('refresh').onclick=()=>load().catch(show);$('createButton').onclick=async()=>{try{credential=$('token').value;await api('/api/a423/jobs',JSON.parse($('create').value));await load();}catch(e){show(e);}};
 </script></html>

package/examples/quickstart.mjs

@@ -0,0 +1,33 @@
+// In-memory workflow and policy example. No on-chain transactions or keys.
+import {createMemoryStore} from '@allorc/a423-sdk';
+import {createWorkflow} from '@allorc/a423-sdk/workflow';
+import {createSettlementPolicy} from '@allorc/a423-sdk/policy';
+
+const workflow = createWorkflow({store: createMemoryStore()});
+const id = 'research-001';
+await workflow.create({
+  id,
+  participants: {requester: 'buyer', worker: 'researcher', verifier: 'reviewer'},
+}, 'buyer');
+
+let job = await workflow.act(id, 'quote', {
+  terms: {description: 'Prepare a research brief', amount_raw: '200'},
+}, {actor: 'researcher', idempotencyKey: 'quote-1'});
+
+const acceptance = {
+  revision: job.agreement.revision,
+  agreement_hash: job.agreement.hash,
+};
+await workflow.act(id, 'accept', acceptance, {
+  actor: 'buyer', idempotencyKey: 'buyer-accept-1',
+});
+job = await workflow.act(id, 'accept', acceptance, {
+  actor: 'researcher', idempotencyKey: 'worker-accept-1',
+});
+
+const plan = createSettlementPolicy().evaluate({
+  cost_basis_raw: '100', budget_raw: '300', escrow_raw: '300',
+});
+console.log(job.state);              // accepted; no funding has occurred
+console.log(plan.target_payout);     // 200: 50% gross-margin target
+console.log(plan.recommended_payout);// 200: fits budget and escrow caps

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@allorc/a423-sdk",
-  "version": "0.5.0",
-  "description": "Experimental Next.js-friendly agent job SDK with typed HTTP client and pluggable storage, authentication and settlement",
+  "version": "0.8.1",
+  "description": "Experimental backend SDK for agent job agreements, durable workflows, ERC-20 escrow, negotiated settlement and configurable profit policies",
   "license": "MIT",
   "type": "commonjs",
   "main": "./src/index.cjs",
@@ -41,6 +41,11 @@
       "types": "./src/operations/index.d.ts",
       "import": "./src/operations/index.mjs",
       "require": "./src/operations/index.cjs"
+    },
+    "./policy": {
+      "types": "./src/policy/index.d.ts",
+      "import": "./src/policy/index.mjs",
+      "require": "./src/policy/index.cjs"
     }
   },
   "files": [
@@ -73,7 +78,13 @@
     "LEGACY.md",
     "scripts/operations-worker.mjs",
     "src/closing.cjs",
-    "SETTLEMENT.md"
+    "SETTLEMENT.md",
+    "src/cancellation.cjs",
+    "CANCELLATION.md",
+    "src/policy",
+    "PROFIT-POLICY.md",
+    "examples/quickstart.mjs",
+    "examples/README.md"
   ],
   "engines": {
     "node": ">=22.13"

package/src/cancellation.cjs

@@ -0,0 +1,74 @@
+'use strict';
+const {createHash}=require('node:crypto');
+const {hashAgreement}=require('./workflow.cjs');
+const {settlementProposal}=require('./closing.cjs');
+const clone=structuredClone;
+function check(ok,message){if(!ok)throw new TypeError(message);}
+function cancellationSubflowId(job){check(job.agreement,'Agreement required');return 'cancellation_'+hashAgreement([job.id,job.agreement.hash]);}
+function getCancellationSubflow(job){return clone((job.subflows||[]).find(s=>s.kind==='cancellation')||null);}
+function canonicalProposal(job){
+ const p=job.negotiation?.current;check(p,'Closing proposal required');
+ const canonical=settlementProposal(job,{worker_amount:p.worker_amount,payer_amount:p.payer_amount,expected_revision:p.escrow_version-1,expires_at:p.expires_at,reason:p.reason,claims:p.claims});
+ check(canonical.proposal_hash===p.proposal_hash,'Proposal claims or allocation changed');return canonical;
+}
+/** Constructs a JSON instruction. Cryptographic approval is checked separately by the escrow adapter. */
+function createCancellationInstruction(job,{payer_signature,worker_signature}={}){
+ const p=canonicalProposal(job),e=job.agreement.terms.escrow;
+ const address=x=>{check(typeof x==='string'&&/^0x[0-9a-fA-F]{40}$/.test(x),'Invalid escrow address');return x.toLowerCase();};
+ const signature=x=>check(typeof x==='string'&&x.length<=32768&&/^0x(?:[0-9a-fA-F]{2})*$/.test(x),'Both wallet signature proofs required');
+ signature(payer_signature);signature(worker_signature);
+ const body={version:'a423.cancellation_instruction.v1',purpose:'close_job',funds_status:'not_executed',job_id:job.id,subflow_id:cancellationSubflowId(job),agreement_hash:'0x'+job.agreement.hash,chain_id:e.chain_id,escrow_contract:address(e.contract),token:address(e.token),onchain_job_id:'0x'+createHash('sha256').update('a423:escrow:v1:'+job.id).digest('hex'),escrow_version:p.escrow_version,proposal_hash:p.proposal_hash,expires_at:p.expires_at,payer:{agent_id:job.participants.requester,address:address(e.payer),amount:p.payer_amount},worker:{agent_id:job.participants.worker,address:address(e.worker),amount:p.worker_amount},proposal:p};
+ return {id:'cancel_instruction_'+hashAgreement(body),...body,authorization:{scheme:'eip712_closing_settlement_v1',payer_signature,worker_signature}};
+}
+function validateCancellationInstruction(job,instruction){
+ check(instruction&&instruction.authorization?.scheme==='eip712_closing_settlement_v1','Cancellation authorization required');
+ const expected=createCancellationInstruction(job,instruction.authorization);
+ check(hashAgreement(expected)===hashAgreement(instruction),'Cancellation instruction changed or does not match this proposal');
+ return clone(instruction);
+}
+function createCancellationReceipt(job,evidence,instruction=null){
+ const e=job.agreement?.terms.escrow;
+ check(e&&evidence?.event==='Settled'&&[5,6,7].includes(evidence.state)&&/^0x[0-9a-fA-F]{64}$/.test(evidence.transaction_hash),'Confirmed closing transaction required');
+ check(evidence.chain_id===e.chain_id&&evidence.contract.toLowerCase()===e.contract.toLowerCase()&&evidence.token.toLowerCase()===e.token.toLowerCase()&&evidence.agreement_hash==='0x'+job.agreement.hash,'Closing evidence destination mismatch');
+ check(evidence.job_id==='0x'+createHash('sha256').update('a423:escrow:v1:'+job.id).digest('hex'),'Closing evidence job mismatch');
+ const amount=BigInt(e.amount),paid=BigInt(evidence.worker_paid);
+ check(evidence.amount===e.amount&&paid>=0n&&paid<=amount&&((evidence.state===5&&paid===amount)||(evidence.state===6&&paid===0n)||(evidence.state===7&&paid>0n&&paid<amount)),'Invalid actual allocation');
+ check(evidence.payer.toLowerCase()===e.payer.toLowerCase()&&evidence.worker.toLowerCase()===e.worker.toLowerCase(),'Closing evidence parties mismatch');
+ const reason=evidence.settlement_reason;check([0,1,2,3,4].includes(reason),'Unknown closing outcome');
+ const mutual=reason===4;
+ if(mutual&&instruction){validateCancellationInstruction(job,instruction);check(instruction.worker.amount===paid.toString()&&instruction.proposal_hash===evidence.proposal_hash&&instruction.escrow_version===evidence.escrow_version,'Instruction was not the executed allocation');}
+ const proof=Object.fromEntries(Object.entries(evidence).filter(([key])=>!['observed_at','instruction_id'].includes(key)));
+ const body={version:'a423.cancellation_receipt.v1',status:'confirmed',job_id:job.id,subflow_id:cancellationSubflowId(job),agreement_hash:'0x'+job.agreement.hash,outcome:['verified_payment','expiry_refund','arbitrated_split','timeout_allocation','mutual_cancellation'][reason],instruction_id:mutual&&instruction?instruction.id:null,prior_instruction_id:instruction?.id||null,allocations:{worker:{address:e.worker.toLowerCase(),amount:paid.toString()},payer:{address:e.payer.toLowerCase(),amount:(amount-paid).toString()}},remaining_locked:'0',evidence:proof};
+ return {id:'cancel_receipt_'+hashAgreement(body),...body};
+}
+function validateCancellationReceipt(job,receipt){
+ check(receipt?.version==='a423.cancellation_receipt.v1','Final cancellation receipt required');
+ const instruction=getCancellationSubflow(job)?.instruction||null;
+ const expected=createCancellationReceipt(job,receipt.evidence,instruction);
+ check(hashAgreement(expected)===hashAgreement(receipt),'Final cancellation receipt changed');return clone(receipt);
+}
+function updateCancellationSubflow(previous,next,{action,actor,phase,input={},evidence={},instruction,error,at}){
+ const old=getCancellationSubflow(previous);
+ if(!old&&!['propose_settlement','counter_settlement','approve_cancellation','execute_cancellation','accept_settlement'].includes(action))return;
+ const s=old||{id:cancellationSubflowId(previous),kind:'cancellation',parent_job_id:previous.id,status:'negotiating',started_at:at,updated_at:at,proposal_revision:previous.negotiation?.current?.escrow_version||0,instruction:null,receipt:null,events:[]};
+ if(phase==='requested'){
+  if(['propose_settlement','counter_settlement'].includes(action))s.status='proposal_pending';
+  if(action==='approve_cancellation')s.status='acceptance_pending';
+  if(action==='execute_cancellation')s.status='execution_pending';
+ }
+ if(phase==='pending'&&action==='execute_cancellation')s.execution_reference=evidence.reference||null;
+ if(phase==='rejected'){
+  s.status=action==='execute_cancellation'?'execution_failed':s.instruction?'accepted':previous.negotiation?.current?'negotiating':'proposal_rejected';s.last_error=error||'Operation rejected';
+ }
+ if(phase==='confirmed'){
+  if(['propose_settlement','counter_settlement'].includes(action)){s.status='negotiating';s.proposal_revision=evidence.escrow_version;s.instruction=null;s.last_error=null;}
+  if(action==='approve_cancellation'){s.status='accepted';s.instruction=clone(instruction);s.accepted_at=at;s.approved_by=[previous.participants.requester,previous.participants.worker];s.last_error=null;}
+  if(action==='dispute')s.status='disputed';
+  if(['execute_cancellation','accept_settlement','refund','resolve','timeout','release'].includes(action)&&evidence.event==='Settled'){
+   s.receipt=createCancellationReceipt(previous,evidence,s.instruction);s.status='completed';s.completed_at=at;s.execution_reference=evidence.transaction_hash;s.closing_action=action;s.last_error=null;
+  }
+ }
+ s.updated_at=at;s.events.push({sequence:s.events.length+1,type:action+'.'+phase,actor_id:actor,at,data:{proposal_hash:evidence.proposal_hash||previous.negotiation?.current?.proposal_hash||null,instruction_id:s.instruction?.id||null,receipt_id:s.receipt?.id||null,error:error||null}});
+ next.subflows=[...(next.subflows||previous.subflows||[]).filter(flow=>flow.id!==s.id),s];next.active_subflow_id=['completed','proposal_rejected'].includes(s.status)?null:s.id;
+}
+module.exports={cancellationSubflowId,getCancellationSubflow,createCancellationInstruction,validateCancellationInstruction,createCancellationReceipt,validateCancellationReceipt,updateCancellationSubflow};

package/src/escrow/cancellation.cjs

@@ -0,0 +1,34 @@
+'use strict';
+const {Contract,TypedDataEncoder,verifyTypedData,getAddress}=require('ethers');
+const {createCancellationInstruction,validateCancellationInstruction}=require('../cancellation.cjs');
+function check(ok,message){if(!ok)throw new TypeError(message);}
+function cancellationCall(instruction){
+ check(instruction?.version==='a423.cancellation_instruction.v1'&&instruction.authorization?.scheme==='eip712_closing_settlement_v1','Signed cancellation instruction required');
+ return {functionName:'settleByConsent',args:[{jobId:instruction.onchain_job_id,agreementHash:instruction.agreement_hash,escrowVersion:instruction.escrow_version,workerAmount:BigInt(instruction.worker.amount),payerAmount:BigInt(instruction.payer.amount),proposalHash:instruction.proposal_hash,expiresAt:instruction.expires_at},instruction.authorization.payer_signature,instruction.authorization.worker_signature]};
+}
+async function verifyCancellationAuthorization(job,instruction,{provider,chainId,contractAddress,tokenAddress}={}){
+ validateCancellationInstruction(job,instruction);
+ const {escrowTerms,ESCROW_ABI,settlementConsent}=require('./index.cjs');
+ const config={chainId,contractAddress,tokenAddress},terms=escrowTerms(job,config),typed=settlementConsent(job,config);
+ if(Number((await provider.getNetwork()).chainId)!==chainId)throw Error('RPC chain mismatch');
+ const escrow=new Contract(contractAddress,ESCROW_ABI,provider),block=await provider.getBlock('latest');
+ if(getAddress(await escrow.token())!==getAddress(tokenAddress))throw Error('Escrow token mismatch');
+ const snapshot=await escrow.getJob(terms.jobId,{blockTag:block.number});
+ const invalid=message=>({valid:false,reason:message});
+ for(const [key,value] of Object.entries(terms))if(String(snapshot.terms[key]).toLowerCase()!==String(value).toLowerCase())return invalid('On-chain agreement mismatch');
+ if(Number(snapshot.state)!==8)return invalid('Escrow is not negotiating');
+ const p=snapshot.proposal;
+ if(Number(p.revision)!==instruction.escrow_version||p.proposalHash!==instruction.proposal_hash||p.workerAmount.toString()!==instruction.worker.amount||Number(p.expiresAt)!==instruction.expires_at)return invalid('On-chain cancellation proposal changed');
+ const proposer=job.negotiation.current.proposer_id===job.participants.requester?terms.payer:job.negotiation.current.proposer_id===job.participants.worker?terms.worker:null;
+ if(!proposer||getAddress(p.proposer)!==getAddress(proposer))return invalid('Proposal owner mismatch');
+ if(block.timestamp>instruction.expires_at||block.timestamp>terms.resolutionDeadline)return invalid('Cancellation approval expired');
+ const digest=TypedDataEncoder.hash(typed.domain,typed.types,typed.value);
+ for(const [account,signature] of [[terms.payer,instruction.authorization.payer_signature],[terms.worker,instruction.authorization.worker_signature]]){
+  if(await provider.getCode(account,block.number)!=='0x'){
+   const wallet=new Contract(account,['function isValidSignature(bytes32,bytes) view returns(bytes4)'],provider);
+   try{if(await wallet.isValidSignature(digest,signature,{blockTag:block.number})!=='0x1626ba7e')return invalid('Invalid smart-wallet approval');}catch(error){if(error.code==='CALL_EXCEPTION')return invalid('Smart-wallet approval rejected');throw error;}
+  }else{try{if(getAddress(verifyTypedData(typed.domain,typed.types,typed.value,signature))!==getAddress(account))return invalid('Invalid party approval');}catch{return invalid('Invalid party approval');}}
+ }
+ return {valid:true,checked_block:block.number};
+}
+module.exports={createCancellationInstruction,validateCancellationInstruction,cancellationCall,verifyCancellationAuthorization};

package/src/escrow/index.cjs

@@ -6,6 +6,8 @@ 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 = {
+  approve_cancellation: {from:['settlement_negotiation'],roles:['requester','worker'],to:'settlement_negotiation',effect:true},
+  execute_cancellation: {from:['settlement_negotiation'],roles:['requester','worker'],to:'settled',effect:true},
   propose_settlement: {from:['funded','running','submitted','verified'],roles:['requester','worker'],to:'settlement_negotiation',effect:true},
   counter_settlement: {from:['settlement_negotiation'],roles:['requester','worker'],to:'settlement_negotiation',effect:true},
   accept_settlement: {from:['settlement_negotiation'],roles:['requester','worker'],to:'settled',effect:true},
@@ -128,6 +130,36 @@ function createEscrowAdapters({provider,chainId,contractAddress,tokenAddress,sig
   }
   const proposeAdapter=adapter(async(ctx,r)=>{ctx.settlementActorAddress=getAddress(await addressFor(ctx.operation.actor));return propose(ctx,r);});
   return {
+    approve_cancellation:adapter(async ctx=>{
+      await context(ctx.job);const p=ctx.job.negotiation?.current;
+      if(!p||ctx.input.expected_revision!==p.escrow_version||ctx.input.proposal_hash!==p.proposal_hash)return {status:'rejected',reason:'Approve the exact current proposal'};
+      const {createCancellationInstruction,verifyCancellationAuthorization}=require('./cancellation.cjs');let instruction;
+      try{instruction=createCancellationInstruction(ctx.job,ctx.input);}catch(error){return {status:'rejected',reason:error.message};}
+      const verified=await verifyCancellationAuthorization(ctx.job,instruction,{provider,...config});
+      if(!verified.valid)return {status:'rejected',reason:verified.reason};
+      return {status:'confirmed',evidence:{kind:'a423.cancellation_acceptance.v1',instruction,checked_block:verified.checked_block,funds_moved:false}};
+    }),
+    execute_cancellation:adapter(async(ctx,r)=>{
+      const t=await context(ctx.job);const {getCancellationSubflow,validateCancellationInstruction}=require('../cancellation.cjs');
+      const instruction=getCancellationSubflow(ctx.job)?.instruction;
+      if(!instruction||ctx.input.instruction_id!==instruction.id)return {status:'rejected',reason:'Accepted cancellation instruction required'};
+      try{validateCancellationInstruction(ctx.job,instruction);}catch(error){return {status:'rejected',reason:error.message};}
+      const {verifyCancellationAuthorization,cancellationCall}=require('./cancellation.cjs');
+      if(!ctx.input.transaction_hash&&!await transactions.get(ctx.operation.id+':execute_cancellation')){
+        const verified=await verifyCancellationAuthorization(ctx.job,instruction,{provider,...config});if(!verified.valid)return {status:'rejected',reason:verified.reason};
+      }
+      const call=cancellationCall(instruction);
+      const result=await observe(ctx,t,'execute_cancellation',call.functionName,call.args,'Settled',(s,e)=>{
+        settled(s,e,t);check(Number(e.args.reason)===4&&e.args.workerAmount.toString()===instruction.worker.amount&&e.args.payerAmount.toString()===instruction.payer.amount&&Number(s.proposal.revision)===instruction.escrow_version&&s.proposal.proposalHash===instruction.proposal_hash,'Instruction allocation mismatch');
+      },r);
+      if(result.status==='confirmed'){
+        const receipt=await provider.getTransactionReceipt(result.evidence.transaction_hash);
+        const accepted=receipt.logs.filter(l=>getAddress(l.address)===config.contractAddress).map(l=>{try{return iface.parseLog(l);}catch{return null;}}).find(e=>e?.name==='SettlementAccepted'&&e.args.jobId===t.jobId);
+        check(accepted&&Number(accepted.args.revision)===instruction.escrow_version&&accepted.args.proposalHash===instruction.proposal_hash,'Instruction acceptance event missing');
+        result.evidence.instruction_id=instruction.id;
+      }
+      return result;
+    }),
     propose_settlement:proposeAdapter,
     counter_settlement:proposeAdapter,
     accept_settlement:adapter(async(ctx,r)=>{
@@ -169,7 +201,14 @@ function createEscrowAdapters({provider,chainId,contractAddress,tokenAddress,sig
       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);}),
+    submit:Object.assign(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);}),{rejectPending:async ctx=>{
+      const t=await context(ctx.job);let malformed=false;try{bytes32(ctx.input.result_hash);}catch{malformed=true;}
+      check(malformed&&!ctx.input.transaction_hash&&!ctx.operation.observation?.reference&&!ctx.operation.observation?.transaction_hash&&!ctx.operation.observation?.evidence?.transaction_hash,'Only syntactically impossible submissions without external transaction references can be rejected');
+      check(typeof transactions.list==='function','Transaction journal inventory required');
+      check(!(await transactions.list()).some(record=>record.id===ctx.operation.id||record.id.startsWith(ctx.operation.id+':')),'Journaled intent exists; reconcile instead');
+      const snapshot=await contract.getJob(t.jobId);match(snapshot,t);check(snapshot.resultHash===ZeroHash,'On-chain submission exists; reconcile instead');
+      return {status:'rejected',never_executable:true,reason:'Malformed result_hash cannot encode a submit transaction',checked_chain_id:String(chainId)};
+    }}),
     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);}),
@@ -180,4 +219,4 @@ function createEscrowAdapters({provider,chainId,contractAddress,tokenAddress,sig
 }
 module.exports={createEscrowAdapters,createMemoryTransactionStore,workerConsent,escrowTerms,escrowTransitions:transitions,ESCROW_ABI:ABI,ESCROW_BYTECODE:artifact.bytecode};
 
-Object.assign(module.exports,require('./services.cjs'),require('./negotiation.cjs'));
+Object.assign(module.exports,require('./services.cjs'),require('./negotiation.cjs'),require('./cancellation.cjs'));

package/src/escrow/index.d.mts

@@ -16,7 +16,7 @@ export interface TransactionStore {
   /** 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 EscrowAdapter { execute(context: AdapterContext): Promise<AdapterResult>; reconcile(context: AdapterContext): Promise<AdapterResult>;rejectPending?(context: AdapterContext): Promise<AdapterResult> }
 export interface EscrowAdapterOptions extends EscrowConfiguration {
   provider: Provider;
   /** Requires populateTransaction + offline signTransaction support; no silent wallet approval. */
@@ -27,7 +27,7 @@ export interface EscrowAdapterOptions extends EscrowConfiguration {
   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'|'propose_settlement'|'counter_settlement'|'accept_settlement', EscrowAdapter>;
+export function createEscrowAdapters(options: EscrowAdapterOptions): Record<'fund'|'start'|'submit'|'verify'|'release'|'refund'|'dispute'|'resolve'|'timeout'|'propose_settlement'|'counter_settlement'|'accept_settlement'|'approve_cancellation'|'execute_cancellation', EscrowAdapter>;
 export function createMemoryTransactionStore(): TransactionStore;
 export function escrowTerms(job: WorkflowJob, config: EscrowConfiguration): ContractTerms;
 export function workerConsent(job: WorkflowJob, config: EscrowConfiguration): {
@@ -49,3 +49,7 @@ export function createEscrowIndexer(options: {provider: Provider;chainId: number
 
 export function settlementProposal(job: WorkflowJob,input: {worker_amount: string;payer_amount?: string;expected_revision: number;expires_at: number;reason: string;claims?: import('../workflow.js').SettlementClaim[]}): import('../workflow.js').SettlementProposal;
 export function settlementConsent(job: WorkflowJob,configuration: EscrowConfiguration): {domain: {name: string;version: string;chainId: number;verifyingContract: string};types: Record<string,TypedDataField[]>;value: {jobId: string;agreementHash: string;escrowVersion: number;workerAmount: bigint;payerAmount: bigint;proposalHash: string;expiresAt: number}};
+
+export {createCancellationInstruction,validateCancellationInstruction} from '../workflow.js';
+export function cancellationCall(instruction: import('../workflow.js').CancellationInstruction): {functionName: 'settleByConsent';args: [ReturnType<typeof settlementConsent>['value'],string,string]};
+export function verifyCancellationAuthorization(job: WorkflowJob,instruction: import('../workflow.js').CancellationInstruction,options: EscrowConfiguration & {provider: Provider}): Promise<{valid: boolean;checked_block?: number;reason?: string}>;

package/src/escrow/index.d.ts

@@ -16,7 +16,7 @@ export interface TransactionStore {
   /** 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 EscrowAdapter { execute(context: AdapterContext): Promise<AdapterResult>; reconcile(context: AdapterContext): Promise<AdapterResult>;rejectPending?(context: AdapterContext): Promise<AdapterResult> }
 export interface EscrowAdapterOptions extends EscrowConfiguration {
   provider: Provider;
   /** Requires populateTransaction + offline signTransaction support; no silent wallet approval. */
@@ -27,7 +27,7 @@ export interface EscrowAdapterOptions extends EscrowConfiguration {
   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'|'propose_settlement'|'counter_settlement'|'accept_settlement', EscrowAdapter>;
+export function createEscrowAdapters(options: EscrowAdapterOptions): Record<'fund'|'start'|'submit'|'verify'|'release'|'refund'|'dispute'|'resolve'|'timeout'|'propose_settlement'|'counter_settlement'|'accept_settlement'|'approve_cancellation'|'execute_cancellation', EscrowAdapter>;
 export function createMemoryTransactionStore(): TransactionStore;
 export function escrowTerms(job: WorkflowJob, config: EscrowConfiguration): ContractTerms;
 export function workerConsent(job: WorkflowJob, config: EscrowConfiguration): {
@@ -49,3 +49,7 @@ export function createEscrowIndexer(options: {provider: Provider;chainId: number
 
 export function settlementProposal(job: WorkflowJob,input: {worker_amount: string;payer_amount?: string;expected_revision: number;expires_at: number;reason: string;claims?: import('../workflow.js').SettlementClaim[]}): import('../workflow.js').SettlementProposal;
 export function settlementConsent(job: WorkflowJob,configuration: EscrowConfiguration): {domain: {name: string;version: string;chainId: number;verifyingContract: string};types: Record<string,TypedDataField[]>;value: {jobId: string;agreementHash: string;escrowVersion: number;workerAmount: bigint;payerAmount: bigint;proposalHash: string;expiresAt: number}};
+
+export {createCancellationInstruction,validateCancellationInstruction} from '../workflow.js';
+export function cancellationCall(instruction: import('../workflow.js').CancellationInstruction): {functionName: 'settleByConsent';args: [ReturnType<typeof settlementConsent>['value'],string,string]};
+export function verifyCancellationAuthorization(job: WorkflowJob,instruction: import('../workflow.js').CancellationInstruction,options: EscrowConfiguration & {provider: Provider}): Promise<{valid: boolean;checked_block?: number;reason?: string}>;

package/src/escrow/index.mjs

@@ -1,2 +1,2 @@
 import escrow from './index.cjs';
-export const { createEscrowAdapters, createMemoryTransactionStore, workerConsent, escrowTerms, escrowTransitions, ESCROW_ABI, ESCROW_BYTECODE, createEscrowRegistry, createEvidenceRevalidator, createManagedSigner, createDelegationAuthorizer, replacePendingTransaction, createFeeReplacementWorker, createEscrowIndexer, settlementProposal, settlementConsent } = escrow;
+export const { createEscrowAdapters, createMemoryTransactionStore, workerConsent, escrowTerms, escrowTransitions, ESCROW_ABI, ESCROW_BYTECODE, createEscrowRegistry, createEvidenceRevalidator, createManagedSigner, createDelegationAuthorizer, replacePendingTransaction, createFeeReplacementWorker, createEscrowIndexer, settlementProposal, settlementConsent, createCancellationInstruction, validateCancellationInstruction, cancellationCall, verifyCancellationAuthorization } = escrow;

package/src/escrow/negotiation.cjs

@@ -5,7 +5,7 @@ function check(ok,message){if(!ok)throw new TypeError(message);}
 const {settlementProposal}=require('../closing.cjs');
 function settlementConsent(job,configuration){
  const {escrowTerms}=require('./index.cjs');const t=escrowTerms(job,configuration),p=job.negotiation?.current;
- check(p&&job.negotiation.status==='open','Open settlement proposal required');
+ check(p&&['open','accepted'].includes(job.negotiation.status),'Open settlement proposal required');
  const canonical=settlementProposal(job,{worker_amount:p.worker_amount,payer_amount:p.payer_amount,expected_revision:p.escrow_version-1,expires_at:p.expires_at,reason:p.reason,claims:p.claims});
  check(canonical.proposal_hash===p.proposal_hash,'Stored proposal claims or allocation changed');
  return {domain:{name:'A423Escrow',version:'1',chainId:configuration.chainId,verifyingContract:getAddress(configuration.contractAddress)},types:TYPES,value:{jobId:t.jobId,agreementHash:t.agreementHash,escrowVersion:p.escrow_version,workerAmount:BigInt(p.worker_amount),payerAmount:BigInt(p.payer_amount),proposalHash:p.proposal_hash,expiresAt:p.expires_at}};

package/src/escrow/services.cjs

@@ -5,7 +5,7 @@ const {validateEscrowEvidence}=require('../operations/index.cjs');
 function check(ok,message){if(!ok)throw Error(message);}
 function createEscrowRegistry(configurations){
  const map=new Map();for(const c of configurations){const key=c.chainId+':'+getAddress(c.contractAddress).toLowerCase();check(!map.has(key),'Duplicate escrow configuration');map.set(key,createEscrowAdapters(c));}
- const actions=['fund','start','submit','verify','release','refund','dispute','resolve','timeout','propose_settlement','counter_settlement','accept_settlement'];const result={};for(const action of actions){result[action]={};for(const method of ['execute','reconcile'])result[action][method]=ctx=>{const e=ctx.job.agreement?.terms.escrow;const adapter=map.get(e?.chain_id+':'+getAddress(e?.contract).toLowerCase());check(adapter,'Escrow not registered');return adapter[action][method](ctx);};}return result;
+ const actions=['fund','start','submit','verify','release','refund','dispute','resolve','timeout','propose_settlement','counter_settlement','accept_settlement','approve_cancellation','execute_cancellation'];const result={};for(const action of actions){result[action]={};for(const method of ['execute','reconcile','rejectPending'])result[action][method]=ctx=>{const e=ctx.job.agreement?.terms.escrow;const adapter=map.get(e?.chain_id+':'+getAddress(e?.contract).toLowerCase());check(adapter,'Escrow not registered');check(typeof adapter[action][method]==='function','Recovery unsupported for this action');return adapter[action][method](ctx);};}return result;
 }
 /** Fresh historical evidence verification. Returns invalid, insufficient_confirmations, or valid; RPC failures throw. */
 function createEvidenceRevalidator({provider,chainId,contractAddress,tokenAddress,confirmations}={}){

package/src/operations/application.cjs

@@ -1,20 +1,26 @@
 'use strict';
 const {createWorkflowHandler}=require('../workflow.cjs');
-function createChatTools({workflow,store,queue,actor}={}){
+function createChatTools({workflow,store,queue,actor,profitFor,policyPromptFor}={}){
  const {enqueueRunningJobs}=require('./index.cjs');
  const act=(action)=>async({job_id,input={},idempotency_key})=>workflow.act(job_id,action,input,{actor,idempotencyKey:idempotency_key});
  return {
+  list_jobs:async()=>Promise.all((await store.list({actor,limit:1000})).map(async job=>profitFor?{...job,profit:await profitFor(job,actor)}:job)),
+  inspect_settlement_policy:async({job_id})=>{const job=await workflow.get(job_id,actor);if(!profitFor)throw Error('Settlement policy not configured');return {profit:await profitFor(job,actor),prompt:policyPromptFor?policyPromptFor(job,actor):null};},
+  reconcile_job:async({job_id})=>workflow.reconcile(job_id,actor),
   send_job_offer:async({id,worker_id,verifier_id,arbitrator_id,terms,metadata={}})=>{
    let job=await workflow.create({id,participants:{requester:actor,worker:worker_id,verifier:verifier_id,arbitrator:arbitrator_id},metadata},actor);
    if(terms)job=await workflow.act(job.id,'quote',{terms},{actor,idempotencyKey:'initial_quote'});return job;
   },
-  propose_quote:act('quote'),accept_quote:act('accept'),fund_escrow:act('fund'),submit_job:act('submit'),verify_job:act('verify'),release_escrow:act('release'),refund_escrow:act('refund'),dispute_job:act('dispute'),resolve_job:act('resolve'),timeout_job:act('timeout'),propose_settlement:act('propose_settlement'),counter_settlement:act('counter_settlement'),accept_settlement:act('accept_settlement'),request_cancellation:act('propose_settlement'),cancel_job:act('cancel'),
+  propose_quote:act('quote'),accept_quote:act('accept'),fund_escrow:act('fund'),submit_job:act('submit'),verify_job:act('verify'),release_escrow:act('release'),refund_escrow:act('refund'),dispute_job:act('dispute'),resolve_job:act('resolve'),timeout_job:act('timeout'),propose_settlement:act('propose_settlement'),counter_settlement:act('counter_settlement'),accept_settlement:act('accept_settlement'),accept_cancellation:async({job_id,input={},idempotency_key})=>workflow.acceptCancellation(job_id,input,{actor,idempotencyKey:idempotency_key}),execute_cancellation:act('execute_cancellation'),request_cancellation:act('propose_settlement'),cancel_job:act('cancel'),decline_job:act('decline'),reopen_job:act('reopen'),
   work_on_job:async(input)=>{const job=await act('start')(input);if(!job.pending&&job.state==='running')await enqueueRunningJobs({store,queue});return job;}
  };
 }
-function createApplicationHandler({workflow,store,queue,authenticate,revalidate,consentFor,settlementConsentFor,legacyState=async()=>({}),authorityHandler,basePath='/api/a423'}={}){
+function createApplicationHandler({workflow,store,queue,authenticate,revalidate,consentFor,settlementConsentFor,profitFor,legacyState=async()=>({}),authorityHandler,forwardCancellations=true,basePath='/api/a423'}={}){
  const {createEventStream,freshReceipts,renderReceiptPdf}=require('./index.cjs');
- const protocol=createWorkflowHandler({workflow,authenticate,basePath});const events=createEventStream({store,authenticate});
+ const protocol=createWorkflowHandler({workflow,authenticate,basePath,forwardCancellations,revalidateCancellationReceipt:async({job,receipt})=>{
+  const {validateCancellationReceipt}=require('../cancellation.cjs');validateCancellationReceipt(job,receipt);
+  try{const check=await revalidate(job,receipt.evidence);if(check.status!=='valid')throw Error('Evidence is not valid');}catch{const {A423Error}=require('../index.cjs');throw new A423Error('EVIDENCE_UNAVAILABLE','Cancellation receipt evidence is unavailable or changed',503);}
+ }});const events=createEventStream({store,authenticate});
  return async request=>{
   const path=new URL(request.url).pathname;
   if(path.startsWith('/api/a423-auth/')&&authorityHandler)return authorityHandler(request);
@@ -24,11 +30,13 @@ function createApplicationHandler({workflow,store,queue,authenticate,revalidate,
   const actor=await authenticate(request);if(!actor)return Response.json({error:'unauthenticated'},{status:401});
   try{
    if(path==='/api/state'){
-    const jobs=await Promise.all((await store.list({actor,limit:1000})).map(async job=>({...job,safety:await store.getSafety(job.id)})));const wallet_transactions=jobs.flatMap(j=>j.evidence.filter(e=>e.evidence.transaction_hash).map(e=>({job_id:j.id,action:e.action,...e.evidence})));
+    const jobs=await Promise.all((await store.list({actor,limit:1000})).map(async job=>({...job,profit:profitFor?await profitFor(job,actor):null,safety:await store.getSafety(job.id)})));const wallet_transactions=jobs.flatMap(j=>j.evidence.filter(e=>e.evidence.transaction_hash).map(e=>({job_id:j.id,action:e.action,...e.evidence})));
     return Response.json({...await legacyState(actor),a423:{jobs,wallet_transactions}},{headers:{'cache-control':'no-store'}});
    }
+   const profit=/^\/api\/a423-profit\/([A-Za-z0-9_-]{1,128})$/.exec(path);
+   if(profit){const job=await workflow.get(profit[1],actor);if(!profitFor)return Response.json({error:'POLICY_NOT_CONFIGURED'},{status:404});return Response.json(await profitFor(job,actor),{headers:{'cache-control':'no-store'}});}
    const receipt=/^\/api\/a423-receipts\/([A-Za-z0-9_-]{1,128})(\.pdf)?$/.exec(path);
-   if(receipt){const data=await freshReceipts({workflow,id:receipt[1],actor,revalidate});if(receipt[2])return new Response(Buffer.from(await renderReceiptPdf(data)),{headers:{'content-type':'application/pdf','cache-control':'no-store'}});return Response.json(data,{headers:{'cache-control':'no-store'}});}
+   if(receipt){const data=await freshReceipts({workflow,id:receipt[1],actor,revalidate});if(profitFor)data.profit=await profitFor(await workflow.get(receipt[1],actor),actor);if(receipt[2])return new Response(Buffer.from(await renderReceiptPdf(data)),{headers:{'content-type':'application/pdf','cache-control':'no-store'}});return Response.json(data,{headers:{'cache-control':'no-store'}});}
    const closing=/^\/api\/a423-settlement-consent\/([A-Za-z0-9_-]{1,128})$/.exec(path);
    if(closing){const job=await workflow.get(closing[1],actor);if(![job.participants.requester,job.participants.worker].includes(actor))return Response.json({error:'settlement party required'},{status:403});if(!settlementConsentFor)throw Error('Settlement consent not configured');const typed=await settlementConsentFor(job);return Response.json(JSON.parse(JSON.stringify(typed,(_,v)=>typeof v==='bigint'?v.toString():v)),{headers:{'cache-control':'no-store'}});}
    const consent=/^\/api\/a423-worker-consent\/([A-Za-z0-9_-]{1,128})$/.exec(path);

package/src/operations/factory.cjs

@@ -1,10 +1,11 @@
 'use strict';
 const {createWorkflow,hashAgreement}=require('../workflow.cjs');
 const {createCredentialAuthenticator,createAuthorityHandler}=require('../authority/index.cjs');
-function createEscrowApplication({storage,authority,escrows,signerFor,addressFor,limitsFor,approveSigning,validateArtifact,execute,keeperEnabled=false,allowAuthorityRequest=async()=>false,requireIndependentArbitrator=true}={}){
+function createEscrowApplication({storage,authority,escrows,signerFor,addressFor,limitsFor,approveSigning,validateArtifact,execute,settlementPolicy,keeperEnabled=false,forwardCancellations=true,allowAuthorityRequest=async()=>false,requireIndependentArbitrator=true}={}){
  const {createEscrowRegistry,createEvidenceRevalidator,escrowTerms,workerConsent,settlementConsent,escrowTransitions}=require('../escrow/index.cjs');
  const {validateTask,validateEscrowEvidence,createSpendingAuthorizer,createExpiryAdapter,createApplicationHandler,createChatTools}=require('./index.cjs');
  if(!storage||!authority||!Array.isArray(escrows)||!escrows.length||typeof approveSigning!=='function'||typeof limitsFor!=='function')throw new TypeError('Explicit storage, authority, escrow configurations and spending/signing approvals required');
+ const profit=settlementPolicy?require('../policy/index.cjs').createProfitSettlementService({...settlementPolicy,kv:storage.kv}):null;
  const registry=new Map(escrows.map(c=>[String(c.chainId)+':'+c.contractAddress.toLowerCase(),c]));
  const configFor=job=>{const e=job.agreement?.terms.escrow;const c=registry.get(e?.chain_id+':'+e?.contract?.toLowerCase());if(!c)throw Error('Unregistered escrow');return c;};
  const checkPolicy=async context=>{
@@ -17,17 +18,18 @@ function createEscrowApplication({storage,authority,escrows,signerFor,addressFor
  const authorizeTransaction=createSpendingAuthorizer({spending:storage.spending,limitsFor,authorize:checkPolicy});
  const adapters=createEscrowRegistry(escrows.map(c=>({...c,signerFor,addressFor,transactions:storage.transactions,authorizeTransaction,validateArtifact})));
  const workflow=createWorkflow({store:storage.jobs,adapters:{...adapters,expire:createExpiryAdapter()},transitions:escrowTransitions,
-  authorize:async({actor})=>authority.isActive(actor),
+  prepareInput:profit?async context=>{if(await authority.isActive(context.actor)!==true){const {A423Error}=require('../index.cjs');throw new A423Error('FORBIDDEN','Active identity required',403);}return profit.prepare(context);}:undefined,
+  authorize:async context=>await authority.isActive(context.actor)===true&&(context.phase==='reconcile'||!profit||await profit.authorize(context)),
   validateTerms:terms=>{validateTask(terms.task);const job={id:'terms_validation',agreement:{terms,hash:hashAgreement(terms)}};escrowTerms(job,configFor(job));},
   validateEvidence:({evidence})=>{if(evidence.transaction_hash)validateEscrowEvidence(evidence);}
  });
  const validators=new Map(escrows.map(c=>[String(c.chainId)+':'+c.contractAddress.toLowerCase(),createEvidenceRevalidator(c)]));
  const revalidate=(job,evidence)=>validators.get(String(configFor(job).chainId)+':'+configFor(job).contractAddress.toLowerCase())(job,evidence);
  const authenticate=createCredentialAuthenticator({authority});
- const applicationOptions={workflow,store:storage.jobs,queue:storage.queue,authenticate,revalidate,consentFor:async job=>workerConsent(job,configFor(job)),settlementConsentFor:async job=>settlementConsent(job,configFor(job)),authorityHandler:createAuthorityHandler({authority,allowRequest:allowAuthorityRequest})};
+ const applicationOptions={profitFor:profit?(job,actor)=>profit.project(job,actor,{revalidate}):undefined,forwardCancellations,workflow,store:storage.jobs,queue:storage.queue,authenticate,revalidate,consentFor:async job=>workerConsent(job,configFor(job)),settlementConsentFor:async job=>settlementConsent(job,configFor(job)),authorityHandler:createAuthorityHandler({authority,allowRequest:allowAuthorityRequest})};
  const workerOptions={authority,actorFor:async job=>job.pending?.actor||job.participants.requester,allowExecute:keeperEnabled,
   execute,beforeExecute:async job=>{await workflow.assertSafe(job.id,job.participants.worker);if(!await authority.isActive(job.participants.worker))return false;const result=await adapters.start.execute({job,input:{},operation:{actor:job.participants.worker}});return result.status==='confirmed';}
  };
- return {workflow,applicationOptions,workerOptions,handler:createApplicationHandler(applicationOptions),chatTools:actor=>createChatTools({workflow,store:storage.jobs,queue:storage.queue,actor})};
+ return {profit,workflow,applicationOptions,workerOptions,handler:createApplicationHandler(applicationOptions),chatTools:actor=>createChatTools({workflow,store:storage.jobs,queue:storage.queue,actor,profitFor:applicationOptions.profitFor,policyPromptFor:profit?(job,actor)=>profit.prompt({role:actor===job.participants.worker?'worker':'requester'}):undefined})};
 }
 module.exports={createEscrowApplication};

package/src/operations/index.cjs

@@ -39,6 +39,9 @@ async function runMaintenanceOnce({workflow,store,actorFor,allowExecute=false,no
    const actor=await actorFor(job);if(!actor)continue;
    let result=job;
    if(job.pending){result=await workflow.reconcile(job.id,actor);if(result.pending&&allowExecute)result=await workflow.resume(job.id,actor);}
+   else if((job.subflows||[]).some(s=>s.kind==='cancellation'&&s.status==='accepted')&&allowExecute){
+     const subflow=job.subflows.find(s=>s.kind==='cancellation');result=await workflow.act(job.id,'execute_cancellation',{instruction_id:subflow.instruction.id},{actor,idempotencyKey:'cancel_forward_'+hash(JSON.stringify(subflow.instruction.id))});
+   }
    else if(job.agreement){const e=job.agreement.terms.escrow;const seconds=Math.floor(now/1000);let action;
     if(e&&(['funded','running'].includes(job.state)||(['settlement_negotiation','disputed'].includes(job.state)&&!job.submission))&&seconds>e.work_deadline)action='timeout';
     if(e&&['submitted','verified','disputed','settlement_negotiation'].includes(job.state)&&seconds>e.resolution_deadline)action='timeout';
@@ -104,3 +107,10 @@ module.exports.migrateUnfundedLegacy=migrateUnfundedLegacy;
 Object.assign(module.exports,require('./application.cjs'));
 
 Object.assign(module.exports,require('./factory.cjs'));
+
+async function freshCancellationReceipt({workflow,id,actor,revalidate}){
+ const job=await workflow.get(id,actor),receipt=await workflow.cancellationReceipt(id,actor);
+ require('../cancellation.cjs').validateCancellationReceipt(job,receipt);
+ const check=await revalidate(job,receipt.evidence);assert(check.status==='valid','Cancellation receipt evidence is not currently valid');return receipt;
+}
+module.exports.freshCancellationReceipt=freshCancellationReceipt;

package/src/operations/index.d.ts

@@ -23,7 +23,9 @@ export function freshReceipts(options: {workflow: Workflow;id: string;actor: str
 export function renderReceiptPdf(receipt: object): Promise<Uint8Array>;
 export function planLegacyMigration(records: Array<{id: string;state: string}>): Array<{id: string;state: string;automatic: false;reason: string}>;
 export function migrateUnfundedLegacy(options: {records: Array<{id: string;state: string}>;workflow: Workflow;actor: string;map(source: any): Promise<Parameters<Workflow['create']>[0]>}): Promise<WorkflowJob[]>;
-export function createChatTools(options: {workflow: Workflow;store: SqliteJobStore;queue: DurableQueue;actor: string}): Record<string,(input: any) => Promise<WorkflowJob>>;
-export function createApplicationHandler(options: {workflow: Workflow;store: SqliteJobStore;queue: DurableQueue;authenticate(request: Request): Promise<string | null>;revalidate: Revalidator;consentFor?(job: WorkflowJob): Promise<object>;settlementConsentFor?(job: WorkflowJob): Promise<object>;legacyState?(actor: string): Promise<object>;authorityHandler?(request: Request): Promise<Response>;basePath?: string}): (request: Request) => Promise<Response>;
+export function createChatTools(options: {workflow: Workflow;store: SqliteJobStore;queue: DurableQueue;actor: string;profitFor?(job: WorkflowJob,actor: string): Promise<object | null>;policyPromptFor?(job: WorkflowJob,actor: string): string}): Record<string,(input: any) => Promise<any>>;
+export function createApplicationHandler(options: {workflow: Workflow;store: SqliteJobStore;queue: DurableQueue;authenticate(request: Request): Promise<string | null>;revalidate: Revalidator;consentFor?(job: WorkflowJob): Promise<object>;settlementConsentFor?(job: WorkflowJob): Promise<object>;profitFor?(job: WorkflowJob,actor: string): Promise<object | null>;legacyState?(actor: string): Promise<object>;authorityHandler?(request: Request): Promise<Response>;forwardCancellations?: boolean;basePath?: string}): (request: Request) => Promise<Response>;
 
-export function createEscrowApplication(options: {storage: import('../storage/index.js').SqliteStorage;authority: import('../authority/index.js').Authority;escrows: Array<any>;signerFor(actor: string): Promise<any>;addressFor(actor: string): Promise<string>;limitsFor(context: SigningContext): Promise<{perTransaction: string;daily: string;total: string}>;approveSigning(context: SigningContext): Promise<boolean>;validateArtifact(context: {job: WorkflowJob;resultHash: string}): Promise<boolean>;execute?(context: {job: WorkflowJob;idempotencyKey: string;signal: AbortSignal}): Promise<{result_hash: string;[key: string]: Json}>;keeperEnabled?: boolean;allowAuthorityRequest?(request: Request): Promise<boolean>;requireIndependentArbitrator?: boolean}): {workflow: Workflow;applicationOptions: Parameters<typeof createApplicationHandler>[0];workerOptions: any;handler: (request: Request) => Promise<Response>;chatTools(actor: string): ReturnType<typeof createChatTools>};
+export function createEscrowApplication(options: {storage: import('../storage/index.js').SqliteStorage;authority: import('../authority/index.js').Authority;escrows: Array<any>;signerFor(actor: string): Promise<any>;addressFor(actor: string): Promise<string>;limitsFor(context: SigningContext): Promise<{perTransaction: string;daily: string;total: string}>;approveSigning(context: SigningContext): Promise<boolean>;validateArtifact(context: {job: WorkflowJob;resultHash: string}): Promise<boolean>;execute?(context: {job: WorkflowJob;idempotencyKey: string;signal: AbortSignal}): Promise<{result_hash: string;[key: string]: Json}>;settlementPolicy?: Omit<import('../policy/index.js').ProfitServiceOptions, 'kv'>;keeperEnabled?: boolean;forwardCancellations?: boolean;allowAuthorityRequest?(request: Request): Promise<boolean>;requireIndependentArbitrator?: boolean}): {profit: ReturnType<typeof import('../policy/index.js').createProfitSettlementService> | null;workflow: Workflow;applicationOptions: Parameters<typeof createApplicationHandler>[0];workerOptions: any;handler: (request: Request) => Promise<Response>;chatTools(actor: string): ReturnType<typeof createChatTools>};
+
+export function freshCancellationReceipt(options: {workflow: Workflow;id: string;actor: string;revalidate: Revalidator}): Promise<import('../workflow.js').CancellationReceipt>;