@allorc/a423-sdk 0.5.0 → 0.8.1

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/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;
@@ -62,11 +64,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 +87,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 +108,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 +120,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 +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 = { 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);
@@ -132,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]);
@@ -143,12 +155,35 @@ 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);
+      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');
@@ -157,6 +192,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);
       }
@@ -164,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;
@@ -175,16 +225,28 @@ 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));},
+    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 { 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;
 }
-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 +254,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 +270,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 +312,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,25 @@ 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 PreFundingCancellation {id: string;epoch: number;action: 'cancel'|'decline';actor_id: string;prior_state: string;accepted_by: string[];agreement: Agreement | null;reason: string | null;at: string;reopen_approvals: string[];reopened_at: string | null}
 export interface WorkflowJob {
+  epoch?: number;agreement_revision?: number;pre_funding_cancellations?: PreFundingCancellation[];
+  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 };
@@ -27,9 +43,10 @@ export type Effect = (context: AdapterContext) => Promise<AdapterResult>;
 export interface Transition { from: string[]; roles: string[]; to: string; effect?: boolean }
 export interface WorkflowOptions {
   store: WorkflowStore;
-  adapters?: Record<string, Effect | { execute: Effect; reconcile?: Effect }>;
+  adapters?: Record<string, Effect | { execute: Effect; reconcile?: Effect; rejectPending?: Effect }>;
   /** Return true to allow; authenticated actor ID must be supplied by your application. */
-  authorize?(context: { job: WorkflowJob; action: string; actor: string; input: Json }): boolean | Promise<boolean>;
+  authorize?(context: { job: WorkflowJob; action: string; actor: string; input: Json;phase?: 'execute'|'reconcile' }): boolean | Promise<boolean>;
+  prepareInput?(context: {job: WorkflowJob;action: string;actor: string;input: Json}): Promise<Json>;
   /** Throw to reject application-specific terms. */
   validateEvidence?(context: {job: WorkflowJob;action: string;evidence: {[key: string]: Json}}): void | Promise<void>;
   validateTerms?(terms: { [key: string]: Json }): void | Promise<void>;
@@ -41,15 +58,20 @@ export interface Workflow {
   get(id: string, actor: string): Promise<WorkflowJob>;
   assertSafe(id: string, actor: string): Promise<WorkflowJob>;
   act(id: string, action: string, input: Json, options: { actor: string; idempotencyKey: string }): Promise<WorkflowJob>;
+  rejectPendingOperation(id: string,input: {operation_id: string;reason: string},options: {actor: 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, 'epoch' | 'pre_funding_cancellations' | '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 +79,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;