@allorc/a423-sdk 0.6.0 → 0.8.1

package/SECURITY.md

@@ -17,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,7 @@
 # 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.**

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,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);}};
+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='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');}
+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.6.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": [
@@ -75,7 +80,11 @@
     "src/closing.cjs",
     "SETTLEMENT.md",
     "src/cancellation.cjs",
-    "CANCELLATION.md"
+    "CANCELLATION.md",
+    "src/policy",
+    "PROFIT-POLICY.md",
+    "examples/quickstart.mjs",
+    "examples/README.md"
   ],
   "engines": {
     "node": ">=22.13"

package/src/escrow/index.cjs

@@ -201,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);}),

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. */

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. */

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','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;
+ 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,18 +1,21 @@
 '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'),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'),
+  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,forwardCancellations=true,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,forwardCancellations,revalidateCancellationReceipt:async({job,receipt})=>{
   const {validateCancellationReceipt}=require('../cancellation.cjs');validateCancellationReceipt(job,receipt);
@@ -27,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,forwardCancellations=true,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={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 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.d.ts

@@ -23,9 +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>;forwardCancellations?: boolean;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;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 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>;

package/src/policy/index.cjs

@@ -0,0 +1,94 @@
+'use strict';
+const {hashAgreement}=require('../workflow.cjs');
+const BPS=10000n,MAX=(1n<<256n)-1n;
+function check(ok,message){if(!ok)throw new TypeError(message);}
+function raw(value,name){check(typeof value==='string'&&/^(0|[1-9][0-9]*)$/.test(value),name+' must be an unsigned raw-unit integer string');const n=BigInt(value);check(n<=MAX,name+' exceeds uint256');return n;}
+const min=(a,b)=>a<b?a:b,ceil=(a,b)=>(a+b-1n)/b;
+const floor=(a,b)=>a>=0n?a/b:-ceil(-a,b);
+function margin(cost,payout){return payout===0n?null:(floor((payout-cost)*BPS,payout)).toString();}
+function createSettlementPolicy(options={}){
+ check(options&&Object.getPrototypeOf(options)===Object.prototype,'Policy thresholds must be a plain object');
+ const keys=['target_margin_bps','min_margin_bps','max_margin_bps','require_counter'];
+ check(Object.keys(options).every(key=>keys.includes(key)),'Unknown policy threshold; use target_margin_bps, min_margin_bps, max_margin_bps or require_counter');
+ const {target_margin_bps=5000,min_margin_bps=1000,max_margin_bps=5000,require_counter=true}=options;
+ for(const v of [target_margin_bps,min_margin_bps,max_margin_bps])check(Number.isSafeInteger(v)&&v>=0&&v<10000,'Margins must be integer basis points between 0 and 9999');
+ check(min_margin_bps<=target_margin_bps&&target_margin_bps<=max_margin_bps,'Require minimum <= target <= maximum');check(typeof require_counter==='boolean','require_counter must be boolean');
+ const configuration={target_margin_bps,min_margin_bps,max_margin_bps,require_counter};
+ function evaluate({cost_basis_raw,budget_raw,escrow_raw,offer_raw,negotiation_round=0}){
+  const cost=raw(cost_basis_raw,'cost_basis_raw'),budget=raw(budget_raw,'budget_raw'),escrow=raw(escrow_raw,'escrow_raw'),affordable=min(budget,escrow);
+  check(Number.isSafeInteger(negotiation_round)&&negotiation_round>=0,'negotiation_round must be nonnegative');
+  const target=ceil(cost*BPS,BPS-BigInt(target_margin_bps)),minimum=ceil(cost*BPS,BPS-BigInt(min_margin_bps)),maximum=ceil(cost*BPS,BPS-BigInt(max_margin_bps));
+  const recommended=min(target,affordable),offer=offer_raw===undefined?null:raw(offer_raw,'offer_raw');
+  const viability=cost===0n?'no_cost':affordable<cost?'below_cost':affordable<minimum?'below_minimum':affordable<target?'below_target':'target_affordable';
+  const offerIssue=offer===null?null:offer>affordable?'above_budget_or_escrow':offer>maximum?'above_maximum':offer<cost?'below_cost':offer<minimum?'below_minimum':null;
+  const requires=cost>0n&&(affordable<minimum||['below_cost','below_minimum'].includes(offerIssue));
+  let decision=cost===0n?'refund':requires?'owner_approval_required':offer===null?'propose':offerIssue?'counter':require_counter&&negotiation_round===0?'counter':'accept';
+  if(cost===0n&&offer!==null&&offer!==0n)decision='counter';
+  return {version:'a423.profit_policy.v1',...configuration,cost_basis_raw,budget_raw,escrow_raw,affordable:affordable.toString(),target_payout:target.toString(),min_payout:minimum.toString(),max_payout:maximum.toString(),recommended_payout:recommended.toString(),expected_profit:(recommended-cost).toString(),expected_margin_bps:margin(cost,recommended),viability,decision,requires_owner_approval:requires,offer_issue:offerIssue,offer_raw:offer?.toString()??null,offer_profit_raw:offer===null?null:(offer-cost).toString(),offer_margin_bps:offer===null?null:margin(cost,offer),negotiation_round};
+ }
+ return Object.freeze({configuration:Object.freeze(configuration),evaluate});
+}
+function profitProjection({evaluation,payout_raw,confirmed=false}){
+ check(typeof confirmed==='boolean','confirmed must be boolean');const payout=raw(payout_raw,'payout_raw'),cost=raw(evaluation.cost_basis_raw,'cost_basis_raw');
+ const projected={projected_payout_raw:payout_raw,projected_profit_raw:(payout-cost).toString(),projected_margin_bps:margin(cost,payout),target_status:payout>=BigInt(evaluation.target_payout)?'target_met':'below_target'};
+ return {...evaluation,...projected,advisory:true,receipt_confirmed:confirmed,realized_payout_raw:confirmed?payout_raw:null,realized_profit_raw:confirmed?projected.projected_profit_raw:null,realized_margin_bps:confirmed?projected.projected_margin_bps:null};
+}
+function settlementPolicyPrompt({role='worker',policy=createSettlementPolicy(),override}={}){
+ check(['worker','requester'].includes(role),'Unknown policy role');if(override!==undefined){check(typeof override==='string','Prompt override must be text');return override;}
+ const c=policy.configuration;
+ const shared='Use list_jobs to discover unknown IDs; never invent IDs. Reconcile OPERATION_PENDING before another action. Both parties approve the exact revision/hash. Acceptance is not payment; require a freshly confirmed receipt. The runner submits artifacts. Simulated costs are estimates, not invoices.';
+ return (role==='worker'?`Profit is the primary objective. Inspect cost basis before quoting or proposing a closing split. Target ${c.target_margin_bps} basis points gross margin on revenue, minimum ${c.min_margin_bps}, maximum ${c.max_margin_bps}. Use the policy recommendation within budget and escrow caps. Never silently accept below cost or minimum; obtain explicit owner approval. ${c.require_counter?'Counter before accepting the first buyer offer. ':''}No cost means a full refund. Publicly share progress, work claims and proposed amounts only; never disclose internal cost, token counts or margin calculations.`:'Evaluate proposals against completed work and the original budget. Do not demand zero solely because work is incomplete; use progress and claims. Never exceed the original budget. Internal worker cost/margins are private.')+' '+shared;
+}
+function createProfitSettlementService({kv,costBasisFor,budgetFor,policy,thresholds,approveException,canViewPrivate=async()=>false}={}){
+ check(policy===undefined||thresholds===undefined,'Supply either thresholds or policy, not both');
+ policy=policy===undefined?createSettlementPolicy(thresholds):policy;
+ check(policy&&typeof policy.evaluate==='function'&&policy.configuration,'A valid SettlementPolicy is required');
+ // Capture and validate configuration at initialization, before any job or cost lookup.
+ const configuration=createSettlementPolicy(policy.configuration).configuration;
+ check(kv&&typeof kv.create==='function'&&typeof costBasisFor==='function'&&typeof budgetFor==='function','Durable private KV, costBasisFor and budgetFor required');
+ const key=job=>hashAgreement([job.id,job.agreement?.hash,job.epoch||0]);
+ async function basis(job,freeze=false){
+  check(job.agreement?.terms.escrow,'Escrow agreement required');const id=key(job),stored=await kv.get('a423_profit_basis',id);if(stored)return stored;
+  const [cost,budget]=await Promise.all([costBasisFor(structuredClone(job)),budgetFor(structuredClone(job))]);
+  const snapshot={cost_basis_raw:cost,budget_raw:budget,escrow_raw:job.agreement.terms.escrow.amount,configuration:{...configuration},frozen_at:new Date().toISOString()};
+  policy.evaluate(snapshot);
+  if(!freeze)return snapshot;await kv.create('a423_profit_basis',id,snapshot);return await kv.get('a423_profit_basis',id);
+ }
+ async function evaluate(job,{freeze=false,offer_raw}={}){const snapshot=await basis(job,freeze);const history=job.negotiation?.history||[],firstBuyer=history.findIndex(p=>p.proposer_id===job.participants.requester);const round=firstBuyer<0?0:history.filter((p,i)=>i>firstBuyer&&p.proposer_id===job.participants.worker).length;return createSettlementPolicy(snapshot.configuration).evaluate({...snapshot,offer_raw,negotiation_round:round});}
+ async function prepare({job,actor,action,input}){
+  if(!['propose_settlement','counter_settlement'].includes(action))return input;
+  const e=await evaluate(job,{freeze:true});return {...input,worker_amount:input.worker_amount===undefined?(actor===job.participants.worker?e.recommended_payout:'0'):input.worker_amount};
+ }
+ async function authorize({job,actor,action,input}){
+  const workerProposal=['propose_settlement','counter_settlement'].includes(action)&&actor===job.participants.worker;
+  const acceptance=['accept_settlement','approve_cancellation','execute_cancellation'].includes(action);
+  if(!workerProposal&&!acceptance)return true;
+  // Adopting already executed chain evidence is observation, not authorization to spend.
+  if(['accept_settlement','execute_cancellation'].includes(action)&&/^0x[0-9a-fA-F]{64}$/.test(input.transaction_hash||''))return true;
+  const payout=workerProposal?input.worker_amount:job.negotiation?.current?.worker_amount;
+  if(payout===undefined)return true; // The protocol adapter rejects malformed or absent proposals.
+  const e=await evaluate(job,{freeze:true,offer_raw:payout});
+  if(['above_budget_or_escrow','above_maximum'].includes(e.offer_issue))return false;
+  if(e.requires_owner_approval){
+   if(typeof approveException!=='function')return false;
+   const approval=await approveException({job:structuredClone(job),actor,action,payout_raw:payout,evaluation:structuredClone(e),proposal_hash:job.negotiation?.current?.proposal_hash||null});
+   if(approval?.approved!==true||typeof approval.approval_id!=='string'||!approval.approval_id.trim())return false;
+   await kv.create('a423_profit_approvals',hashAgreement([key(job),action,payout,job.negotiation?.current?.proposal_hash||null,approval.approval_id]),{job_id:job.id,agreement_hash:job.agreement.hash,action,actor,proposal_hash:job.negotiation?.current?.proposal_hash||null,approval_id:approval.approval_id,payout_raw:payout,at:new Date().toISOString()});
+  }
+  if(acceptance&&job.negotiation?.current?.proposer_id!==job.participants.worker&&e.require_counter&&e.cost_basis_raw!=='0'&&e.negotiation_round===0)return false;
+  return true;
+ }
+ async function project(job,actor,{revalidate}={}){
+  if(!job.agreement?.terms.escrow)return null;
+  const proof=[...job.evidence].reverse().find(item=>item.evidence.event==='Settled')?.evidence;
+  let confirmed=false,evidence_status=proof?'unavailable':'not_settled';
+  if(proof&&revalidate){try{const result=await revalidate(job,proof);confirmed=result.status==='valid';evidence_status=result.status;}catch{evidence_status='unavailable';}}
+  const payout=confirmed?proof.worker_paid:job.negotiation?.current?.worker_amount||'0';
+  // Never call the cost provider or disclose its output to the requester.
+  if(actor!==job.participants.worker&&await canViewPrivate({job:structuredClone(job),actor})!==true)return {advisory:true,proposed_payout_raw:job.negotiation?.current?.worker_amount||null,realized_payout_raw:confirmed?payout:null,receipt_confirmed:confirmed,evidence_status};
+  const e=await evaluate(job);const frozen=!!await kv.get('a423_profit_basis',key(job));
+  return {...profitProjection({evaluation:e,payout_raw:payout,confirmed}),basis_frozen:frozen,evidence_status};
+ }
+ return {configuration,evaluate,prepare,authorize,project,prompt:options=>settlementPolicyPrompt({...options,policy:createSettlementPolicy(configuration)})};
+}
+module.exports={createSettlementPolicy,profitProjection,settlementPolicyPrompt,createProfitSettlementService};

package/src/policy/index.d.ts

@@ -0,0 +1,23 @@
+import type {WorkflowJob,Json} from '../workflow.js';
+import type {KeyValueStore} from '../storage/index.js';
+export interface PolicyConfiguration {target_margin_bps?: number;min_margin_bps?: number;max_margin_bps?: number;require_counter?: boolean}
+export interface PolicyInput {cost_basis_raw: string;budget_raw: string;escrow_raw: string;offer_raw?: string;negotiation_round?: number}
+export interface PolicyEvaluation extends Required<PolicyConfiguration> {
+ version: 'a423.profit_policy.v1';cost_basis_raw: string;budget_raw: string;escrow_raw: string;affordable: string;target_payout: string;min_payout: string;max_payout: string;recommended_payout: string;expected_profit: string;expected_margin_bps: string | null;viability: 'no_cost'|'below_cost'|'below_minimum'|'below_target'|'target_affordable';decision: 'refund'|'propose'|'counter'|'accept'|'owner_approval_required';requires_owner_approval: boolean;offer_issue: string | null;offer_raw: string | null;offer_profit_raw: string | null;offer_margin_bps: string | null;negotiation_round: number;
+}
+export interface SettlementPolicy {readonly configuration: Readonly<Required<PolicyConfiguration>>;evaluate(input: PolicyInput): PolicyEvaluation}
+export type CostBasisProvider=(job: WorkflowJob)=>Promise<string>;
+export interface ProfitProjection extends PolicyEvaluation {advisory: true;receipt_confirmed: boolean;projected_payout_raw: string;projected_profit_raw: string;projected_margin_bps: string | null;target_status: 'target_met'|'below_target';realized_payout_raw: string | null;realized_profit_raw: string | null;realized_margin_bps: string | null}
+export interface PolicyContext {job: WorkflowJob;actor: string;action: string;input: any}
+export interface ProfitServiceOptions {kv: KeyValueStore;costBasisFor: CostBasisProvider;budgetFor(job: WorkflowJob): Promise<string>;policy?: SettlementPolicy;thresholds?: PolicyConfiguration;approveException?(context: {job: WorkflowJob;actor: string;action: string;payout_raw: string;evaluation: PolicyEvaluation;proposal_hash: string | null}): Promise<{approved: boolean;approval_id?: string} | null>;canViewPrivate?(context: {job: WorkflowJob;actor: string}): Promise<boolean>}
+export function createSettlementPolicy(options?: PolicyConfiguration): SettlementPolicy;
+export function profitProjection(input: {evaluation: PolicyEvaluation;payout_raw: string;confirmed?: boolean}): ProfitProjection;
+export function settlementPolicyPrompt(options?: {role?: 'worker'|'requester';policy?: SettlementPolicy;override?: string}): string;
+export function createProfitSettlementService(options: ProfitServiceOptions): {
+ readonly configuration: Readonly<Required<PolicyConfiguration>>;
+ evaluate(job: WorkflowJob,options?: {freeze?: boolean;offer_raw?: string}): Promise<PolicyEvaluation>;
+ prepare(context: PolicyContext): Promise<Json>;
+ authorize(context: PolicyContext): Promise<boolean>;
+ project(job: WorkflowJob,actor: string,options?: {revalidate?(job: WorkflowJob,evidence: any): Promise<{status: string}>}): Promise<(ProfitProjection & {basis_frozen: boolean;evidence_status: string}) | {advisory: true;proposed_payout_raw: string | null;realized_payout_raw: string | null;receipt_confirmed: boolean;evidence_status: string} | null>;
+ prompt(options?: {role?: 'worker'|'requester';override?: string}): string;
+};

package/src/policy/index.mjs

@@ -0,0 +1,2 @@
+import api from './index.cjs';
+export const {createSettlementPolicy,profitProjection,settlementPolicyPrompt,createProfitSettlementService}=api;

package/src/workflow.cjs

@@ -24,6 +24,8 @@ const RULES = {
   verify: { from: ['submitted'], roles: ['verifier'], to: 'verified', effect: true },
   release: { from: ['verified'], roles: ['verifier'], to: 'paid', effect: true },
   refund: { from: ['funded', 'running'], roles: ['requester'], to: 'refunded', effect: true },
+  decline: { from: ['draft', 'quoted', 'accepted'], roles: ['worker'], to: 'cancelled' },
+  reopen: { from: ['cancelled'], roles: ['requester', 'worker'], to: 'draft' },
   cancel: { from: ['draft', 'quoted', 'accepted'], roles: ['requester'], to: 'cancelled' },
   expire: { from: ['draft', 'quoted', 'accepted'], roles: ['requester', 'worker'], to: 'expired', effect: true },
   dispute: { from: ['submitted', 'verified'], roles: ['requester', 'worker', 'verifier'], to: 'disputed' },
@@ -31,7 +33,7 @@ const RULES = {
 };
 /** Pure canonical JSON SHA-256. This is an integrity commitment, not authentication. */
 function hashAgreement(terms) { return digest(terms); }
-function createWorkflow({ store, adapters = {}, authorize, validateTerms, validateEvidence, transitions = {} } = {}) {
+function createWorkflow({ store, adapters = {}, authorize, prepareInput, validateTerms, validateEvidence, transitions = {} } = {}) {
   if (!store || ['get', 'create', 'compareAndSet'].some(k => typeof store[k] !== 'function')) throw new TypeError('Supply an atomic workflow store');
   const rules = copy(RULES);
   for (const [action, rule] of Object.entries(transitions)) {
@@ -52,9 +54,9 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, valida
     if (!job || !Object.values(job.participants).includes(actor)) error('NOT_FOUND', 'Job not found', 404);
     return copy(job);
   }
-  async function allowed(job, action, actor, input, rule) {
+  async function allowed(job, action, actor, input, rule, phase='execute') {
     if (!rule.roles.some(role => job.participants[role] === actor)) error('FORBIDDEN', 'Actor cannot perform this action', 403);
-    if (authorize && await authorize({ job: copy(job), action, actor, input: copy(input) }) !== true) error('FORBIDDEN', 'Application policy rejected action', 403);
+    if (authorize && await authorize({ job: copy(job), action, actor, input: copy(input), phase }) !== true) error('FORBIDDEN', 'Application policy rejected action', 403);
   }
   async function complete(job, result) {
     const pending = job.pending;
@@ -126,7 +128,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 = { 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 };
+      const job = { epoch:0,agreement_revision:0,pre_funding_cancellations:[],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);
@@ -140,6 +142,8 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, valida
       if(safety?.blocked) error('SAFETY_HOLD','Evidence requires reconciliation before further actions',409);
       const rule = Object.hasOwn(rules,action) ? rules[action] : null;
       if (!rule) error('UNKNOWN_ACTION', 'Unknown workflow action', 400);
+      if(!rule.roles.some(role=>job.participants[role]===actor))error('FORBIDDEN','Actor cannot perform this action',403);
+      if(prepareInput){input=await prepareInput({job:copy(job),action,actor,input:copy(input)});canonical(input);}
       await allowed(job, action, actor, input, rule);
       const key = digest([actor, idempotencyKey]);
       const requestHash = digest([action, input]);
@@ -156,10 +160,30 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, valida
       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);
+      const fundingStarted=Object.values(job.operations).some(op=>op.result?.evidence?.event==='Funded') || job.evidence.some(e=>e.action==='fund') || job.events.some(e=>e.type==='fund.requested') || !!job.escrow_ledger;
+      if(['cancel','decline','reopen'].includes(action)&&fundingStarted)error('FUNDING_STARTED','Funding activity must be reconciled and closed; this job cannot be reopened',409);
+      if((job.epoch||0)>0&&['quote','accept','fund','cancel','decline'].includes(action)&&input?.expected_epoch!==job.epoch)error('STALE_EPOCH','Reload the job and supply its current expected_epoch',409);
+      if(['cancel','decline'].includes(action)){
+        if(input?.reason!==undefined&&(typeof input.reason!=='string'||!input.reason.trim()||input.reason.length>4000))error('INVALID_INPUT','Cancellation reason must be nonempty text, at most 4000 characters',400);
+        const record={id:randomUUID(),epoch:job.epoch||0,action,actor_id:actor,prior_state:job.state,accepted_by:copy(job.agreement?.accepted_by||[]),agreement:copy(job.agreement),reason:input?.reason||null,at:stamp(),reopen_approvals:[],reopened_at:null};
+        next.pre_funding_cancellations=[...(job.pre_funding_cancellations||[]),record];next.work_status='stopped';
+      }
+      if(action==='reopen'){
+        const history=copy(job.pre_funding_cancellations||[]),record=history.at(-1);
+        if(!record||record.reopened_at||input?.cancellation_id!==record.id)error('CANCELLATION_MISMATCH','Supply the current pre-funding cancellation_id',409);
+        const required=[...new Set([job.participants.requester,record.actor_id,...([job.participants.requester,job.participants.worker].every(id=>record.accepted_by.includes(id))?[job.participants.worker]:[])])];
+        if(!required.includes(actor))error('FORBIDDEN','This actor is not a required reopening approver',403);
+        record.reopen_approvals=[...new Set([...record.reopen_approvals,actor])];next.pre_funding_cancellations=history;
+        if(!required.every(id=>record.reopen_approvals.includes(id))){next.operations[key]={request_hash:requestHash,status:'confirmed',result:{status:'confirmed'}};return save(job,next,'reopen.approved',actor,{cancellation_id:record.id,required_approvers:required});}
+        record.reopened_at=stamp();next.epoch=(job.epoch||0)+1;next.agreement_revision=Math.max(job.agreement_revision||0,job.agreement?.revision||0);next.agreement=null;next.work_status='not_started';
+      }
       if (action === 'quote') {
         if (!input || !input.terms || typeof input.terms !== 'object' || Array.isArray(input.terms)) error('INVALID_INPUT', 'Supply a terms object', 400);
         if (validateTerms) await validateTerms(copy(input.terms));
-        next.agreement = { revision: (job.agreement?.revision || 0) + 1, terms: copy(input.terms), hash: hashAgreement(input.terms), accepted_by: [] };
+        const terms=copy(input.terms);
+        if((job.epoch||0)>0)terms._a423_reopen={job_id:job.id,epoch:job.epoch};
+        next.agreement_revision=Math.max(job.agreement_revision||0,job.agreement?.revision||0)+1;
+        next.agreement = { revision: next.agreement_revision, terms, hash: hashAgreement(terms), accepted_by: [] };
       }
       if (action === 'accept') {
         if (!input || input.agreement_hash !== job.agreement.hash || input.revision !== job.agreement.revision) error('AGREEMENT_MISMATCH', 'Accept the current agreement hash and revision');
@@ -176,6 +200,20 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, valida
       next.operations[key] = { request_hash: requestHash, status: 'confirmed', result: { status: 'confirmed' } };
       return save(job, next, action, actor, input);
     },
+    async rejectPendingOperation(id,{operation_id,reason},{actor}={}) {
+      const job=await get(id,actor),pending=job.pending;
+      if((store.getSafety?await store.getSafety(id):null)?.blocked)error('SAFETY_HOLD','Evidence requires reconciliation before recovery',409);
+      if(!pending||pending.id!==operation_id)error('PENDING_MISMATCH','Supply the current pending operation ID',409);
+      if(typeof reason!=='string'||!reason.trim()||reason.length>4000)error('INVALID_INPUT','Recovery reason required',400);
+      const rule=rules[pending.action];if(!rule)error('RECOVERY_UNSUPPORTED','Unknown pending action',409);
+      await allowed(job,pending.action,actor,pending.input,rule);
+      if(pending.request_hash!==digest([pending.action,pending.input]))error('RECOVERY_UNSAFE','Pending input integrity mismatch; manual investigation required',409);
+      const inspect=adapters[pending.action]?.rejectPending;
+      if(typeof inspect!=='function')error('RECOVERY_UNSUPPORTED','Adapter does not prove this operation is never executable',409);
+      const proof=await inspect({job:copy(job),input:copy(pending.input),operation:copy(pending)});
+      if(proof?.status!=='rejected'||proof.never_executable!==true)error('RECOVERY_UNSAFE','Operation might execute; reconcile instead',409);
+      return complete(job,{status:'rejected',reason,recovery:{operation_id,proof:copy(proof)}});
+    },
     async resume(id, actor) {
       const job=await get(id,actor);
       if(!job.pending)return job;
@@ -187,7 +225,7 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, valida
     async reconcile(id, actor) {
       const job = await get(id, actor);
       if (!job.pending) return job;
-      await allowed(job, job.pending.action, actor, job.pending.input, rules[job.pending.action]);
+      await allowed(job, job.pending.action, actor, job.pending.input, rules[job.pending.action],'reconcile');
       return execute(job, true);
     },
     async cancellation(id,actor){return require('./cancellation.cjs').getCancellationSubflow(await get(id,actor));},
@@ -202,7 +240,7 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, valida
     },
     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, 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 { epoch:job.epoch||0,pre_funding_cancellations:job.pre_funding_cancellations||[],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;