@allorc/a423-sdk 0.5.0 → 0.6.0

package/CANCELLATION.md

@@ -0,0 +1,70 @@
+# Cancellation subflow — 0.6.0
+
+A job has one parent lifecycle and an optional cancellation subflow. Cancellation can negotiate compensation for completed work and agreed expenses, then close the job. It does not permit continuing work after a partial release.
+
+The flow is:
+
+1. Publish `propose_settlement`, or alternate `counter_settlement`, with the worker's proposed amount, reason, claims, original deadline and expected revision. The payer receives the remainder. Funds remain in the escrow contract, never the worker's wallet. Work pauses.
+2. Both parties review the exact current proposal and sign the `ClosingSettlement` typed data returned by `settlementConsent`. Signature authorization is bound to chain, contract, agreement, job, revision, amounts, proposal hash and expiry.
+3. Accept using `workflow.acceptCancellation`. The adapter verifies both EOA/ERC-1271 signatures and current on-chain terms/proposal. The workflow atomically saves an immutable JSON instruction and marks the child flow `accepted` before any closing transaction is signed or broadcast. The instruction says `funds_status: "not_executed"`.
+4. Forward the saved instruction. The adapter validates the JSON against the job, encodes `settleByConsent`, applies the signing/broadcast policy and journals the transaction. The contract verifies signatures and distributes the exact split atomically. It does not parse or trust JSON.
+5. After the configured confirmations and matching settlement evidence, save the final cancellation receipt. It records actual worker/payer allocations, zero remaining locked amount, transaction/block evidence and the accepted instruction ID.
+
+An acceptance record is an authorization receipt, not proof of payment. Pending, rejected, expired or unavailable execution must not display a completed payment receipt.
+
+## Server API
+
+```js
+const proposed = await workflow.act(id, 'propose_settlement', {
+  worker_amount: '30', // raw token units; payer gets total minus 30
+  expected_revision: 0,
+  expires_at: proposalExpiry, // no later than original resolution deadline
+  reason: 'Research completed; remaining work cancelled',
+  claims: [{ kind: 'work', description: 'Checked source list', evidence: ['artifact:sources'] }]
+}, { actor: workerId, idempotencyKey: 'cancel-proposal-1' });
+
+const job = await workflow.acceptCancellation(id, {
+  expected_revision: proposed.negotiation.current.escrow_version,
+  proposal_hash: proposed.negotiation.current.proposal_hash,
+  payer_signature: payerSignature,
+  worker_signature: workerSignature
+}, { actor: payerId, idempotencyKey: 'cancel-accept-1' });
+```
+
+The default forwards immediately AFTER saving acceptance. To separate acceptance and execution, pass `forward: false`, then:
+
+```js
+const instruction = await workflow.cancellationInstruction(id, payerId);
+await workflow.act(id, 'execute_cancellation', {
+  instruction_id: instruction.id
+}, { actor: payerId, idempotencyKey: 'cancel-execute-1' });
+```
+
+`createEscrowApplication({forwardCancellations:false,...})` stages HTTP acceptance. An explicitly enabled keeper (`allowExecute:true` / factory `keeperEnabled:true`) forwards accepted instructions. Observe-only reconciliation never creates a new payment transaction.
+
+| Route, relative to `/api/a423/jobs/:id` | Meaning |
+|---|---|
+| `GET /subflows` | Child records and active child ID |
+| `GET /cancellation` | Cancellation child or null |
+| `POST /cancellation/accept` | Body: revision/hash and both signatures; save then optionally forward |
+| `POST /cancellation/execute` | Body: `instruction_id`, optionally external `transaction_hash` |
+| `GET /cancellation/instruction` | Accepted instruction; unavailable until acceptance |
+| `GET /cancellation/receipt` | Final receipt; HTTP 409 before confirmation |
+
+POST requests require the usual credential and `idempotency-key`. The typed workflow client exposes the corresponding methods. The application handler freshly revalidates final receipt evidence; unavailable/changed evidence returns 503. The lower-level workflow getter validates record integrity only; use `freshCancellationReceipt` with an evidence revalidator for current chain proof.
+
+## State and recovery
+
+Child statuses are `proposal_pending`, `negotiating`, `acceptance_pending`, `accepted`, `execution_pending`, `execution_failed`, `disputed`, `proposal_rejected`, and `completed`. Its ID and `parent_job_id` link it to the parent job; events retain proposal revisions and receipt/instruction IDs. The job remains `settlement_negotiation` while acceptance/execution is pending. The separate escrow ledger changes only with confirmed chain evidence.
+
+Keep the same actor, request and idempotency key on retries. Accepted JSON survives storage restarts. Recovery observes the durable transaction journal; it must not send a duplicate payout. If approval is saved but execution was never started, call acceptance again or use an authorized keeper. A rejected execution preserves the accepted instruction and locked ledger; retry deliberately using a new execution key after resolving its cause. Pending execution must be reconciled/resumed first.
+
+The SDK blocks counters after instruction acceptance. External transactions can still change the chain state; forwarding checks fresh state and the contract rejects stale signatures. Original expiry refunds, arbitration and timeout allocations remain available under their original conditions. Those exits create a final receipt with their actual outcome and `instruction_id:null`; `prior_instruction_id` preserves the unexecuted acceptance reference. A failed acceptance or proposal produces no payment receipt.
+
+## Compatibility and limits
+
+0.6 reuses the 0.5 `A423Escrow` contract. No new deployment is needed for a verified 0.5 deployment. Existing 0.4/older contracts do not support these methods; retain their original adapter until custody is closed. Existing records without subflows remain readable; a cancellation child is added when negotiation starts.
+
+The legacy `accept_settlement` action remains available for a direct counterparty transaction or dual-signature relay. It can produce a final receipt without a separately saved accepted instruction. Use the new staged flow when the UI needs acceptance before execution.
+
+Amounts use raw integer token units, never floating point. Signatures and claims are public authorization material, not private keys. Persist records securely and avoid exposing participant-specific endpoints without authentication. Pure JSON constructors validate structure/binding; they do not independently prove cryptographic consent or chain finality. The reference adapters perform those checks. No live-chain deployment, external app migration or independent security audit is implied.

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## 0.6.0
+
+- Add a persisted cancellation child flow with proposal, acceptance, escrow execution and confirmed receipt stages.
+- Verify both wallet signatures before saving the immutable JSON instruction; encode it into the existing `settleByConsent` call.
+- Add typed client/HTTP/chat actions, accepted-instruction and fresh final-receipt routes, keeper forwarding and dashboard controls.
+- Preserve locked balances through rejected/expired execution; retain arbitration and original deadline exits.
+- Reuse the 0.5 contract without Solidity changes. Earlier contracts still require the 0.5 deployment upgrade.
+
 ## 0.5.0
 
 - Add reference-contract closing proposals, counterproposals, exact counterpart acceptance and dual-signature permissionless settlement.

package/INTEGRATION.md

@@ -1,3 +1,7 @@
+# Cancellation subflows in 0.6
+
+Use `workflow.acceptCancellation` or `POST /api/a423/jobs/:id/cancellation/accept` with both wallet signatures. Acceptance is persisted before forwarding; show the subflow status and issue the final receipt only after confirmation. See [CANCELLATION.md](./CANCELLATION.md) for routes, retry behavior and migration. The actual remote application is not modified by installing this package.
+
 # Closing settlements in 0.5
 
 Read SETTLEMENT.md. Use a new local/testnet reference deployment, preserve older funded contracts with their original adapters, wire proposal/counter/accept actions and the settlement-consent endpoint, and display work status/escrow ledger/negotiation separately. Test partial compensation, stale and expired approvals, arbitration, original deadlines and crash recovery. No real-chain deployment is implicit.
@@ -13,7 +17,7 @@ The remote MVP was not available in the SDK workspace; these utilities do not im
 Install after the maintainer publishes:
 
 ```sh
-npm install @allorc/a423-sdk@0.5.0
+npm install @allorc/a423-sdk@0.6.0
 ```
 
 For testing before publication, install the maintainer's `npm pack` tarball instead. Do not silently install 0.1 and assume the workflow entry point exists.

package/OPERATIONS.md

@@ -1,5 +1,7 @@
 # A423 operational integration
 
+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.
+
 Version 0.5 adds closing negotiation, a paused-work state, a separate escrow ledger and proposal history. See SETTLEMENT.md before deploying the new contract. Execution callbacks receive an AbortSignal and must honor it for cooperative cancellation.
 
 This guide covers concrete SDK modules and their deployment boundaries. The remote MVP's source was unavailable during this SDK change, so its chat tools, dashboard, environment, reset route and testnet deployment have not been modified. Use the supplied bridge in that repository, then run the actual app's integration tests. Existing contract-level constraints remain explicit.

package/README.md

@@ -1,11 +1,13 @@
-# A423 SDK — 0.5.0
+# A423 SDK — 0.6.0
+
+Version 0.6 adds a durable **cancellation subflow**: accepted signed JSON → escrow execution → confirmed cancellation receipt. See [CANCELLATION.md](./CANCELLATION.md). Acceptance records never claim funds have moved. It reuses the 0.5 reference contract.
 
 Version 0.5 adds **negotiated closing settlements**: partial-work/expense claims, counterproposals, exact acceptance, on-chain release blocking during negotiation, arbitration and unchanged deadline fallbacks. See [SETTLEMENT.md](./SETTLEMENT.md) for the complete flow, signatures, ledger and upgrade requirements. It closes the job; it does not add milestone payments.
 
 Experimental Node.js/Next.js middleware for agent tasks, agreements and escrow. Version 0.4 adds working persistence, authority credentials and operational services around the configurable workflow and reference contract. Installing the SDK never publishes endpoints or deploys a contract automatically.
 
 ```sh
-npm install @allorc/a423-sdk@0.5.0 ethers@^6.15.0 pdf-lib@^1.17.1
+npm install @allorc/a423-sdk@0.6.0 ethers@^6.15.0 pdf-lib@^1.17.1
 ```
 
 Node.js 22.13+ is required for the SQLite module. Node 24 is the tested runtime. `ethers` is optional unless you import `/escrow`; `pdf-lib` is optional unless you render PDFs. Core/workflow remain framework-independent.

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.

package/SETTLEMENT.md

@@ -1,5 +1,7 @@
 # Negotiated closing settlements — 0.5.0
 
+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/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);const info=document.createElement('pre');info.textContent=JSON.stringify({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','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(['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'?JSON.parse(input.value):{action:action.value,input: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=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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@allorc/a423-sdk",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Experimental Next.js-friendly agent job SDK with typed HTTP client and pluggable storage, authentication and settlement",
   "license": "MIT",
   "type": "commonjs",
@@ -73,7 +73,9 @@
     "LEGACY.md",
     "scripts/operations-worker.mjs",
     "src/closing.cjs",
-    "SETTLEMENT.md"
+    "SETTLEMENT.md",
+    "src/cancellation.cjs",
+    "CANCELLATION.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)=>{
@@ -180,4 +212,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

@@ -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

@@ -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'])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;
 }
 /** 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

@@ -8,13 +8,16 @@ function createChatTools({workflow,store,queue,actor}={}){
    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'),
   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,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);

package/src/operations/factory.cjs

@@ -1,7 +1,7 @@
 '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,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');
@@ -24,7 +24,7 @@ function createEscrowApplication({storage,authority,escrows,signerFor,addressFor
  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={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';}
  };

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

@@ -24,6 +24,8 @@ 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 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>;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}>;keeperEnabled?: boolean;forwardCancellations?: 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 freshCancellationReceipt(options: {workflow: Workflow;id: string;actor: string;revalidate: Revalidator}): Promise<import('../workflow.js').CancellationReceipt>;

package/src/operations/index.mjs

@@ -1,2 +1,2 @@
 import api from './index.cjs';
-export const { validateTask, validateEscrowEvidence, createSpendingAuthorizer, runMaintenanceOnce, createExpiryAdapter, runExecutionOnce, enqueueRunningJobs, createEventStream, createWebhookDispatcher, watchEvidenceOnce, freshReceipts, renderReceiptPdf, planLegacyMigration, migrateUnfundedLegacy, createChatTools, createApplicationHandler, createEscrowApplication } = api;
+export const { validateTask, validateEscrowEvidence, createSpendingAuthorizer, runMaintenanceOnce, createExpiryAdapter, runExecutionOnce, enqueueRunningJobs, createEventStream, createWebhookDispatcher, watchEvidenceOnce, freshReceipts, renderReceiptPdf, planLegacyMigration, migrateUnfundedLegacy, createChatTools, createApplicationHandler, createEscrowApplication, freshCancellationReceipt } = api;

package/src/workflow.cjs

@@ -62,11 +62,13 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, valida
     canonical(result);
     if (result.status === 'pending') {
       const next = copy(job); next.pending.observation = copy(result);
+      require('./cancellation.cjs').updateCancellationSubflow(job,next,{action:pending.action,actor:pending.actor,phase:'pending',evidence:result,at:stamp()});
       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) };
+      require('./cancellation.cjs').updateCancellationSubflow(job,next,{action:pending.action,actor:pending.actor,phase:'rejected',error:result.reason,at:stamp()});
       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);
@@ -83,7 +85,12 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, valida
       next.negotiation={status:'open',origin_state:job.negotiation?.origin_state||job.state,current:record,history:[...(job.negotiation?.history||[]),record]};
       next.work_status='paused';eventData={...eventData,proposal:record};
     }
-    if(pending.action==='accept_settlement'){
+    if(pending.action==='approve_cancellation'){
+      const instruction=require('./cancellation.cjs').validateCancellationInstruction(job,result.evidence.instruction);
+      next.negotiation={...copy(job.negotiation),status:'accepted',acceptance_basis:'dual_wallet_signatures'};next.work_status='paused';
+      eventData={...eventData,instruction_id:instruction.id};
+    }
+    if(['accept_settlement','execute_cancellation'].includes(pending.action)){
       const p=job.negotiation?.current;
       if(!p || result.evidence.settlement_reason!==4 || result.evidence.worker_paid!==p.worker_amount || result.evidence.proposal_hash!==p.proposal_hash || result.evidence.escrow_version!==p.escrow_version)error('INVALID_ADAPTER_RESULT','Closing settlement evidence mismatch',502);
       next.negotiation={...copy(job.negotiation),status:'settled',accepted_by:pending.actor,settled_at:stamp()};next.work_status='stopped';
@@ -99,6 +106,7 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, valida
       const closed=[5,6,7].includes(e.state);
       next.escrow_ledger={funded_amount:e.amount,worker_paid:e.worker_paid,payer_refunded:closed?(BigInt(e.amount)-BigInt(e.worker_paid)).toString():'0',locked_amount:closed?'0':e.amount,escrow_version:e.escrow_version??0};
     }
+    require('./cancellation.cjs').updateCancellationSubflow(job,next,{action:pending.action,actor:pending.actor,phase:'confirmed',evidence:result.evidence,instruction:result.evidence.instruction,at:stamp()});
     return save(job, next, pending.action + '.confirmed', pending.actor, eventData);
   }
   async function execute(job, reconcile = false) {
@@ -110,7 +118,7 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, valida
     const result = await fn({ job: copy(job), input: copy(pending.input), operation: copy(pending) });
     return complete(job, result);
   }
-  return {
+  const workflow={
     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');
@@ -118,7 +126,7 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, valida
       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 = { work_status:'not_started',negotiation:null,escrow_ledger:null,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 };
+      const job = { subflows:[],active_subflow_id:null,work_status:'not_started',negotiation:null,escrow_ledger:null,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);
@@ -143,6 +151,9 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, valida
         if (job.pending.key !== key || job.pending.request_hash !== requestHash) error('OPERATION_PENDING', 'Reconcile or retry the pending operation first');
         return execute(job);
       }
+      const cancellation=require('./cancellation.cjs').getCancellationSubflow(job);
+      if(['propose_settlement','counter_settlement'].includes(action)&&cancellation?.instruction)error('CANCELLATION_ACCEPTED','An accepted instruction must be executed or resolved before renegotiating',409);
+      if(action==='approve_cancellation'&&cancellation?.instruction){const candidate=require('./cancellation.cjs').createCancellationInstruction(job,input);if(input.expected_revision!==job.negotiation.current.escrow_version||input.proposal_hash!==job.negotiation.current.proposal_hash||hashAgreement(candidate)!==hashAgreement(cancellation.instruction))error('CANCELLATION_CONFLICT','Another instruction is already accepted',409);return job;}
       if (!rule.from.includes(job.state)) error('INVALID_STATE', `Cannot ${action} from ${job.state}`);
       let next = copy(job);
       if (action === 'quote') {
@@ -157,6 +168,7 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, valida
       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 };
+        require('./cancellation.cjs').updateCancellationSubflow(job,next,{action,actor,phase:'requested',input,at:stamp()});
         job = await save(job, next, action + '.requested', actor);
         return execute(job);
       }
@@ -178,13 +190,25 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, valida
       await allowed(job, job.pending.action, actor, job.pending.input, rules[job.pending.action]);
       return execute(job, true);
     },
+    async cancellation(id,actor){return require('./cancellation.cjs').getCancellationSubflow(await get(id,actor));},
+    async cancellationInstruction(id,actor){const job=await get(id,actor),subflow=require('./cancellation.cjs').getCancellationSubflow(job);if(!subflow?.instruction)error('INSTRUCTION_UNAVAILABLE','No accepted cancellation instruction',409);return require('./cancellation.cjs').validateCancellationInstruction(job,subflow.instruction);},
+    async cancellationReceipt(id,actor){const job=await get(id,actor),subflow=require('./cancellation.cjs').getCancellationSubflow(job);if(subflow?.status!=='completed'||!subflow.receipt)error('RECEIPT_UNAVAILABLE','Cancellation payment is not confirmed',409);return require('./cancellation.cjs').validateCancellationReceipt(job,subflow.receipt);},
+    async acceptCancellation(id,input,{actor,idempotencyKey,forward=true}={}){
+      if(typeof forward!=='boolean')throw new TypeError('forward must be a boolean');
+      let job=await workflow.act(id,'approve_cancellation',input,{actor,idempotencyKey});
+      const subflow=require('./cancellation.cjs').getCancellationSubflow(job);
+      if(!forward||job.pending||!subflow?.instruction||subflow.status!=='accepted')return job;
+      return workflow.act(id,'execute_cancellation',{instruction_id:subflow.instruction.id},{actor,idempotencyKey:'cancel_forward_'+digest(subflow.instruction.id)});
+    },
     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, work_status:job.work_status,negotiation:job.negotiation,escrow_ledger:job.escrow_ledger,evidence: job.evidence, events: job.events, pending: job.pending };
+      return { protocol: job.protocol, job_id: id, state: job.state, agreement: job.agreement, submission: job.submission, subflows:job.subflows||[],active_subflow_id:job.active_subflow_id||null,work_status:job.work_status,negotiation:job.negotiation,escrow_ledger:job.escrow_ledger,evidence: job.evidence, events: job.events, pending: job.pending };
     }
   };
+  return workflow;
 }
-function createWorkflowHandler({ workflow, authenticate, basePath = '/api/a423', maxBodyBytes = 65536, onError } = {}) {
+function createWorkflowHandler({ workflow, authenticate, basePath = '/api/a423', maxBodyBytes = 65536, onError, forwardCancellations = true, revalidateCancellationReceipt } = {}) {
+  if(typeof forwardCancellations!=='boolean')throw new TypeError('forwardCancellations must be a boolean');
   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' } });
@@ -192,10 +216,10 @@ function createWorkflowHandler({ workflow, authenticate, basePath = '/api/a423',
     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));
+      const match = /^\/jobs(?:\/([A-Za-z0-9_-]{1,128})(?:\/(actions|reconcile|receipts|subflows|cancellation(?:\/(?:accept|execute|instruction|receipt))?))?)?$/.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';
+      const method = !id || ['actions','reconcile','cancellation/accept','cancellation/execute'].includes(action) ? '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);
@@ -208,6 +232,16 @@ function createWorkflowHandler({ workflow, authenticate, basePath = '/api/a423',
         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==='subflows'){const job=await workflow.get(id,actor);return respond({job_id:id,subflows:job.subflows||[],active_subflow_id:job.active_subflow_id||null});}
+      if(action==='cancellation')return respond({job_id:id,subflow:await workflow.cancellation(id,actor)});
+      if(action==='cancellation/instruction')return respond({instruction:await workflow.cancellationInstruction(id,actor)});
+      if(action==='cancellation/receipt'){
+        const receipt=await workflow.cancellationReceipt(id,actor);
+        if(revalidateCancellationReceipt)await revalidateCancellationReceipt({job:await workflow.get(id,actor),receipt,actor});
+        return respond({receipt});
+      }
+      if(action==='cancellation/accept')return respond({job:await workflow.acceptCancellation(id,body,{actor,idempotencyKey:request.headers.get('idempotency-key'),forward:forwardCancellations})});
+      if(action==='cancellation/execute')return respond({job:await workflow.act(id,'execute_cancellation',body,{actor,idempotencyKey:request.headers.get('idempotency-key')})});
       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));
@@ -240,12 +274,24 @@ function createWorkflowClient({ baseUrl, headers, fetch: fetchImpl = globalThis.
     return data;
   }
   const path = id => '/jobs/' + identifier(id);
-  return {
+  const workflow={
     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 cancellation(id){return (await request(path(id)+'/cancellation')).subflow;},
+    async cancellationInstruction(id){return (await request(path(id)+'/cancellation/instruction')).instruction;},
+    async cancellationReceipt(id){return (await request(path(id)+'/cancellation/receipt')).receipt;},
+    async subflows(id){return (await request(path(id)+'/subflows')).subflows;},
+    async acceptCancellation(id,input,{idempotencyKey}={}){identifier(idempotencyKey);return (await request(path(id)+'/cancellation/accept',input,idempotencyKey)).job;},
+    async executeCancellation(id,input,{idempotencyKey}={}){identifier(idempotencyKey);return (await request(path(id)+'/cancellation/execute',input,idempotencyKey)).job;},
     async receipts(id) { return request(path(id)+'/receipts'); }
   };
+  return workflow;
 }
 module.exports.createWorkflowClient = createWorkflowClient;
+
+module.exports.getCancellationSubflow=(job)=>require('./cancellation.cjs').getCancellationSubflow(job);
+module.exports.createCancellationInstruction=(job,proofs)=>require('./cancellation.cjs').createCancellationInstruction(job,proofs);
+module.exports.validateCancellationInstruction=(job,instruction)=>require('./cancellation.cjs').validateCancellationInstruction(job,instruction);
+module.exports.validateCancellationReceipt=(job,receipt)=>require('./cancellation.cjs').validateCancellationReceipt(job,receipt);

package/src/workflow.d.ts

@@ -4,9 +4,23 @@ export interface Operation { id: string; key: string; action: string; actor: str
 export interface AdapterResult { status: 'pending' | 'confirmed' | 'rejected'; evidence?: { [key: string]: Json }; [key: string]: Json | undefined }
 export interface SettlementClaim {kind: 'work' | 'expense' | 'other';description: string;amount?: string;evidence?: string[]}
 export interface SettlementProposal {version: 'a423.closing.v1';job_id: string;agreement_hash: string;escrow_version: number;worker_amount: string;payer_amount: string;expires_at: number;reason: string;claims: SettlementClaim[];closes_job: true;proposal_hash: string;proposer_id?: string;at?: string}
-export interface Negotiation {status: 'open' | 'disputed' | 'settled';origin_state: string;current: SettlementProposal;history: SettlementProposal[];accepted_by?: string;settled_at?: string}
+export interface Negotiation {status: 'open' | 'accepted' | 'disputed' | 'settled';acceptance_basis?: 'dual_wallet_signatures';origin_state: string;current: SettlementProposal;history: SettlementProposal[];accepted_by?: string;settled_at?: string}
 export interface EscrowLedger {funded_amount: string;worker_paid: string;payer_refunded: string;locked_amount: string;escrow_version: number}
+export interface CancellationInstruction {
+ id: string;version: 'a423.cancellation_instruction.v1';purpose: 'close_job';funds_status: 'not_executed';job_id: string;subflow_id: string;agreement_hash: string;chain_id: string;escrow_contract: string;token: string;onchain_job_id: string;escrow_version: number;proposal_hash: string;expires_at: number;
+ payer: {agent_id: string;address: string;amount: string};worker: {agent_id: string;address: string;amount: string};proposal: SettlementProposal;
+ authorization: {scheme: 'eip712_closing_settlement_v1';payer_signature: string;worker_signature: string};
+}
+export interface CancellationReceipt {
+ id: string;version: 'a423.cancellation_receipt.v1';status: 'confirmed';job_id: string;subflow_id: string;agreement_hash: string;outcome: string;instruction_id: string | null;prior_instruction_id: string | null;
+ allocations: {worker: {address: string;amount: string};payer: {address: string;amount: string}};remaining_locked: '0';evidence: {[key: string]: Json};
+}
+export interface CancellationSubflow {
+ id: string;kind: 'cancellation';parent_job_id: string;status: 'proposal_pending'|'proposal_rejected'|'negotiating'|'acceptance_pending'|'accepted'|'execution_pending'|'execution_failed'|'completed'|'disputed';started_at: string;updated_at: string;proposal_revision: number;instruction: CancellationInstruction | null;receipt: CancellationReceipt | null;events: Array<{sequence: number;type: string;actor_id: string;at: string;data: Json}>;accepted_at?: string;approved_by?: string[];completed_at?: string;execution_reference?: string | null;closing_action?: string;last_error?: string | null;
+}
+export interface CancellationApproval {expected_revision: number;proposal_hash: string;payer_signature: string;worker_signature: string}
 export interface WorkflowJob {
+  subflows?: CancellationSubflow[];active_subflow_id?: string | null;
   work_status?: string;negotiation?: Negotiation | null;escrow_ledger?: EscrowLedger | null;
   id: string; protocol: 'a423.workflow.v1'; version: number; state: string;
   participants: { requester: string; worker: string; verifier: string; [role: string]: string };
@@ -43,13 +57,17 @@ export interface Workflow {
   act(id: string, action: string, input: Json, options: { actor: string; idempotencyKey: string }): Promise<WorkflowJob>;
   resume(id: string, actor: 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' | 'work_status' | 'negotiation' | 'escrow_ledger'> & { job_id: string }>;
+  cancellation(id: string, actor: string): Promise<CancellationSubflow | null>;
+  cancellationInstruction(id: string, actor: string): Promise<CancellationInstruction>;
+  cancellationReceipt(id: string, actor: string): Promise<CancellationReceipt>;
+  acceptCancellation(id: string,input: CancellationApproval,options: {actor: string;idempotencyKey: string;forward?: boolean}): Promise<WorkflowJob>;
+  receipts(id: string, actor: string): Promise<Pick<WorkflowJob, 'protocol' | 'state' | 'agreement' | 'submission' | 'evidence' | 'events' | 'pending' | 'work_status' | 'negotiation' | 'escrow_ledger' | 'subflows' | 'active_subflow_id'> & { 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>;
+  basePath?: string; maxBodyBytes?: number; forwardCancellations?: boolean; revalidateCancellationReceipt?(context: {job: WorkflowJob;receipt: CancellationReceipt;actor: string}): Promise<void>; 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). */
@@ -57,9 +75,20 @@ export interface WorkflowClient {
   get(id: string): Promise<WorkflowJob>;
   act(id: string, action: string, input: Json, options: { idempotencyKey: string }): Promise<WorkflowJob>;
   reconcile(id: string): Promise<WorkflowJob>;
+  cancellation(id: string): Promise<CancellationSubflow | null>;
+  cancellationInstruction(id: string): Promise<CancellationInstruction>;
+  cancellationReceipt(id: string): Promise<CancellationReceipt>;
+  subflows(id: string): Promise<CancellationSubflow[]>;
+  acceptCancellation(id: string,input: CancellationApproval,options: {idempotencyKey: string}): Promise<WorkflowJob>;
+  executeCancellation(id: string,input: {instruction_id: string;transaction_hash?: string},options: {idempotencyKey: 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;
+
+export function getCancellationSubflow(job: WorkflowJob): CancellationSubflow | null;
+export function createCancellationInstruction(job: WorkflowJob,proofs: {payer_signature: string;worker_signature: string}): CancellationInstruction;
+export function validateCancellationInstruction(job: WorkflowJob,instruction: CancellationInstruction): CancellationInstruction;
+export function validateCancellationReceipt(job: WorkflowJob,receipt: CancellationReceipt): CancellationReceipt;

package/src/workflow.mjs

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