@allorc/a423-sdk 0.3.0 → 0.4.0

package/src/operations/factory.cjs

@@ -0,0 +1,33 @@
+'use strict';
+const {createWorkflow,hashAgreement}=require('../workflow.cjs');
+const {createCredentialAuthenticator,createAuthorityHandler}=require('../authority/index.cjs');
+function createEscrowApplication({storage,authority,escrows,signerFor,addressFor,limitsFor,approveSigning,validateArtifact,execute,keeperEnabled=false,allowAuthorityRequest=async()=>false,requireIndependentArbitrator=true}={}){
+ const {createEscrowRegistry,createEvidenceRevalidator,escrowTerms,workerConsent,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 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=>{
+  if(typeof authority.isActive!=='function'||await authority.isActive(context.actor)!==true)return false;
+  if((await storage.jobs.getSafety(context.job.id))?.blocked)return false;
+  const e=context.job.agreement.terms.escrow;
+  if(requireIndependentArbitrator&&[e.payer,e.worker,e.verifier].map(a=>a.toLowerCase()).includes(e.arbitrator.toLowerCase()))return false;
+  return await approveSigning(context)===true;
+ };
+ 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),
+  validateTerms:terms=>{validateTask(terms.task);const job={id:'terms_validation',agreement:{terms,hash:hashAgreement(terms)}};escrowTerms(job,configFor(job));},
+  validateEvidence:({evidence})=>{if(evidence.transaction_hash)validateEscrowEvidence(evidence);}
+ });
+ const validators=new Map(escrows.map(c=>[String(c.chainId)+':'+c.contractAddress.toLowerCase(),createEvidenceRevalidator(c)]));
+ const revalidate=(job,evidence)=>validators.get(String(configFor(job).chainId)+':'+configFor(job).contractAddress.toLowerCase())(job,evidence);
+ const authenticate=createCredentialAuthenticator({authority});
+ const applicationOptions={workflow,store:storage.jobs,queue:storage.queue,authenticate,revalidate,consentFor:async job=>workerConsent(job,configFor(job)),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})};
+}
+module.exports={createEscrowApplication};

package/src/operations/index.cjs

@@ -0,0 +1,105 @@
+'use strict';
+const {createHash,createHmac,randomUUID}=require('node:crypto');
+const hash=x=>createHash('sha256').update(x).digest('hex');
+function assert(ok,message){if(!ok)throw new TypeError(message);}
+function validateTask(task){
+ assert(task&&typeof task==='object'&&!Array.isArray(task),'Task required');
+ for(const name of ['id','type','description'])assert(typeof task[name]==='string'&&task[name].trim()&&task[name].length<=16000,'Invalid task '+name);
+ assert(Array.isArray(task.deliverables)&&task.deliverables.length>0&&task.deliverables.length<=100,'Deliverables required');
+ const ids=new Set();for(const d of task.deliverables){assert(d&&typeof d.id==='string'&&!ids.has(d.id),'Unique deliverable IDs required');ids.add(d.id);assert(typeof d.media_type==='string'&&typeof d.description==='string','Deliverable media_type and description required');}
+ assert(task.acceptance&&typeof task.acceptance.validator==='string'&&typeof task.acceptance.version==='string'&&task.acceptance.criteria&&typeof task.acceptance.criteria==='object','Versioned acceptance criteria required');
+ JSON.stringify(task);return structuredClone(task);
+}
+function validateEscrowEvidence(e){
+ assert(e&&typeof e==='object','Escrow evidence required');
+ for(const key of ['chain_id','amount','worker_paid'])assert(typeof e[key]==='string'&&/^(0|[1-9][0-9]*)$/.test(e[key]),'Invalid evidence '+key);
+ for(const key of ['contract','token','payer','worker','verifier','arbitrator'])assert(/^0x[0-9a-fA-F]{40}$/.test(e[key]),'Invalid evidence '+key);
+ for(const key of ['job_id','agreement_hash','transaction_hash','block_hash','result_hash'])assert(/^0x[0-9a-fA-F]{64}$/.test(e[key]),'Invalid evidence '+key);
+ assert(Number.isSafeInteger(e.block_number)&&e.block_number>=0&&Number.isSafeInteger(e.confirmations)&&e.confirmations>0,'Invalid evidence block');
+ assert(['Funded','Submitted','Verified','Disputed','Settled'].includes(e.event),'Invalid evidence event');
+ assert(Number.isInteger(e.state)&&e.state>=1&&e.state<=7&&BigInt(e.worker_paid)<=BigInt(e.amount),'Invalid evidence allocation/state');
+ return structuredClone(e);
+}
+function createSpendingAuthorizer({spending,limitsFor,authorize}={}){
+ assert(spending&&typeof limitsFor==='function'&&typeof authorize==='function','Spending store, limitsFor and authorize required');
+ return async context=>{
+  if(await authorize(context)!==true)return false;
+  if(['fund','approve','approve_zero'].includes(context.step)){
+   const e=context.job.agreement.terms.escrow,limits=await limitsFor(context);
+   try {await spending.reserve({...limits,id:hash(JSON.stringify([e.chain_id,e.contract.toLowerCase(),context.job.id])),scope:JSON.stringify([e.chain_id,e.payer.toLowerCase(),e.token.toLowerCase()]),amount:e.amount});}catch(error){if(error.code==='SPENDING_LIMIT_EXCEEDED')return false;throw error;}
+  }
+  return true;
+ };
+}
+/** Resume is deliberately separate from observe-only reconcile; caller must authorize execution. */
+async function runMaintenanceOnce({workflow,store,actorFor,allowExecute=false,now=Date.now()}={}){
+ const results=[];let after='';
+ while(true){const jobs=await store.list({after,limit:100});if(!jobs.length)break;after=jobs.at(-1).id;
+  for(const job of jobs){try{
+   const actor=await actorFor(job);if(!actor)continue;
+   let result=job;
+   if(job.pending){result=await workflow.reconcile(job.id,actor);if(result.pending&&allowExecute)result=await workflow.resume(job.id,actor);}
+   else if(job.agreement){const e=job.agreement.terms.escrow;const seconds=Math.floor(now/1000);let action;
+    if(e&&['funded','running'].includes(job.state)&&seconds>e.work_deadline)action='timeout';
+    if(e&&['submitted','verified','disputed'].includes(job.state)&&seconds>e.resolution_deadline)action='timeout';
+    const expiry=job.agreement.terms.expires_at;
+    if(['quoted','accepted'].includes(job.state)&&Number.isSafeInteger(expiry)&&seconds>expiry)action='expire';
+    if(action&&allowExecute)result=await workflow.act(job.id,action,{}, {actor,idempotencyKey:'keeper_'+hash(job.id+':'+action)});
+   }
+   results.push({id:job.id,state:result.state,pending:!!result.pending});
+  }catch(error){results.push({id:job.id,error:error.message});}}
+ }
+ return results;
+}
+function createExpiryAdapter({now=()=>Date.now()}={}){const run=async({job})=>{
+ const expiry=job.agreement?.terms.expires_at;
+ if(!Number.isSafeInteger(expiry)||Math.floor(now()/1000)<=expiry)return {status:'rejected',reason:'Agreement has not expired'};
+ return {status:'confirmed',evidence:{expires_at:expiry,observed_at:new Date(now()).toISOString()}};
+};return {execute:run,reconcile:run};}
+async function runExecutionOnce({workflow,queue,execute,beforeExecute,leaseMs=30000}={}){
+ const item=await queue.claim({kind:'execution',leaseMs});if(!item)return null;
+ const heartbeat=setInterval(()=>{queue.heartbeat(item.id,item.lease,{leaseMs}).catch(()=>{});},Math.max(1,Math.floor(leaseMs/3)));
+ try{
+  let result=item.result;
+  if(!result){const job=await workflow.assertSafe(item.payload.job_id,item.payload.actor);assert(job.state==='running','Work requires running state');validateTask(job.agreement.terms.task);assert(typeof beforeExecute==='function'&&await beforeExecute(job)===true,'Execution eligibility check required');result=await execute({job,idempotencyKey:item.id});assert(await queue.checkpoint(item.id,item.lease,result),'Execution lease lost');}
+  assert(typeof result.result_hash==='string','Execution must return artifact commitment');
+  const job=await workflow.act(item.payload.job_id,'submit',result,{actor:item.payload.actor,idempotencyKey:'execution_'+hash(item.id)});
+  assert(await queue.complete(item.id,item.lease,{job_id:job.id,state:job.state}),'Execution lease lost');return job;
+ }catch(error){await queue.retry(item.id,item.lease,{delayMs:1000});throw error;}finally{clearInterval(heartbeat);}
+}
+async function enqueueRunningJobs({store,queue}){let after='',count=0;while(true){const jobs=await store.list({after,limit:100});if(!jobs.length)break;after=jobs.at(-1).id;for(const j of jobs)if(j.state==='running'&&!j.pending){const event=j.events.filter(e=>e.type==='start.confirmed').at(-1);if(event&&await queue.enqueue({id:'execution_'+hash(j.id+':'+event.sequence),kind:'execution',payload:{job_id:j.id,actor:j.participants.worker}}))count++;}}return count;}
+function createEventStream({store,authenticate,pollMs=1000,maxDurationMs=25000}={}){
+ return async request=>{
+  const actor=await authenticate(request);if(!actor)return Response.json({error:'unauthenticated'},{status:401});
+  let cursor=Number(request.headers.get('last-event-id')||new URL(request.url).searchParams.get('after')||0);if(!Number.isSafeInteger(cursor)||cursor<0)return Response.json({error:'invalid cursor'},{status:400});
+  let closed=false,timer;const encoder=new TextEncoder(),began=Date.now();
+  const stream=new ReadableStream({start(controller){const tick=async()=>{if(closed)return;try{const events=await store.events({actor,after:cursor,limit:100});for(const event of events){cursor=event.cursor;controller.enqueue(encoder.encode(`id: ${cursor}\nevent: a423\ndata: ${JSON.stringify(event)}\n\n`));}if(request.signal.aborted||Date.now()-began>=maxDurationMs){closed=true;controller.close();return;}controller.enqueue(encoder.encode(': heartbeat\n\n'));timer=setTimeout(tick,pollMs);}catch(e){closed=true;controller.error(e);}};void tick();},cancel(){closed=true;clearTimeout(timer);}});
+  return new Response(stream,{headers:{'content-type':'text/event-stream','cache-control':'no-store','x-accel-buffering':'no'}});
+ };
+}
+function createWebhookDispatcher({queue,kv,subscriptions,secretFor,fetch:fetchImpl=globalThis.fetch,timeoutMs=10000}={}){
+ assert(queue&&kv&&Array.isArray(subscriptions)&&typeof secretFor==='function','Webhook configuration required');
+ const targets=new Map();for(const s of subscriptions){const u=new URL(s.url);assert(u.protocol==='https:'&&!u.username&&!u.password&&!u.hash,'Use explicitly configured HTTPS webhook destinations');targets.set(s.id,{...s,url:u.href});}
+ return {
+  async project(store){for(const s of targets.values()){const events=await store.events({actor:s.actor,after:(await kv.get('webhook-cursors',s.id))?.cursor||s.after||0,limit:1000});for(const event of events){await queue.enqueue({id:'webhook_'+hash(s.id+':'+event.cursor),kind:'webhook',payload:{subscription:s.id,event}});await kv.put('webhook-cursors',s.id,{cursor:event.cursor});}}},
+  async deliverOne(){const item=await queue.claim({kind:'webhook',leaseMs:timeoutMs+5000});if(!item)return null;try{
+   const target=targets.get(item.payload.subscription);assert(target,'Subscription removed');const body=JSON.stringify(item.payload.event),timestamp=String(Math.floor(Date.now()/1000));const secret=await secretFor(target.id);assert(typeof secret==='string'&&secret.length>=32,'Webhook signing secret must have at least 32 characters');
+   const signature=createHmac('sha256',secret).update(timestamp+'.'+body).digest('hex');const response=await fetchImpl(target.url,{method:'POST',body,headers:{'content-type':'application/json','a423-delivery-id':item.id,'a423-timestamp':timestamp,'a423-signature':'v1='+signature},redirect:'error',signal:AbortSignal.timeout(timeoutMs)});
+   await response.body?.cancel();if(!response.ok)throw Error('Webhook HTTP '+response.status);await queue.complete(item.id,item.lease,{status:response.status});return {id:item.id,status:'delivered'};
+  }catch(error){await queue.retry(item.id,item.lease,{delayMs:Math.min(3600000,1000*2**Math.min(item.attempts,12))});return {id:item.id,status:'retry',error:error.message};}}
+ };
+}
+async function watchEvidenceOnce({store,revalidate}){const results=[];let after='';while(true){const jobs=await store.list({after,limit:100});if(!jobs.length)break;after=jobs.at(-1).id;for(const job of jobs){if(!job.evidence.length)continue;const checks=[];for(const item of job.evidence)if(item.evidence.transaction_hash){try{checks.push(await revalidate(job,item.evidence));}catch(error){checks.push({status:'unavailable',message:'Evidence provider unavailable'});}}
+ const blocked=checks.some(c=>c.status!=='valid');const safety={blocked,checks,checked_at:new Date().toISOString()};await store.setSafety(job.id,safety);results.push({id:job.id,...safety});}}return results;}
+async function freshReceipts({workflow,id,actor,revalidate}){const job=await workflow.get(id,actor);const checks=[];for(const item of job.evidence)if(item.evidence.transaction_hash){const result=await revalidate(job,item.evidence);assert(result.status==='valid','Receipt evidence is not currently valid: '+result.status);checks.push(result);}return {...await workflow.receipts(id,actor),revalidated_at:new Date().toISOString(),checks};}
+async function renderReceiptPdf(receipt){const {PDFDocument,StandardFonts}=require('pdf-lib');const pdf=await PDFDocument.create(),font=await pdf.embedFont(StandardFonts.Courier);let page,y;const newPage=()=>{page=pdf.addPage([595,842]);y=800;};newPage();const text=JSON.stringify(receipt,null,2).replace(/[^\x20-\x7e\n]/g,'?');for(const line of ['A423 Evidence Receipt',...text.split('\n')])for(let i=0;i<Math.max(1,line.length);i+=88){if(y<40)newPage();page.drawText(line.slice(i,i+88),{x:32,y,size:9,font});y-=12;}return pdf.save();}
+function planLegacyMigration(records){return records.map(record=>({id:record.id,state:record.state,automatic:false,reason:['funded','running','submitted','verified','paid','settlement_pending','completed'].includes(String(record.state).toLowerCase())?'Existing custody/evidence must stay with original contract; do not relabel':'Requires reviewed participant and accepted-terms mapping; create a new job with provenance'}));}
+module.exports={validateTask,validateEscrowEvidence,createSpendingAuthorizer,runMaintenanceOnce,createExpiryAdapter,runExecutionOnce,enqueueRunningJobs,createEventStream,createWebhookDispatcher,watchEvidenceOnce,freshReceipts,renderReceiptPdf,planLegacyMigration};
+
+async function migrateUnfundedLegacy({records,workflow,map,actor}){
+ const created=[];for(const source of records){assert(['offered','draft','quoted','accepted'].includes(String(source.state).toLowerCase()),'Funded/terminal legacy records cannot be automatically migrated');const target=await map(structuredClone(source));assert(target.id&&target.id!==source.id,'Use a new explicit job ID');const job=await workflow.create({...target,metadata:{...target.metadata,migration:{source_id:source.id,source_state:source.state,source_hash:hash(JSON.stringify(source)),accepted_terms_carried:false}}},actor);created.push(job);}return created;
+}
+module.exports.migrateUnfundedLegacy=migrateUnfundedLegacy;
+Object.assign(module.exports,require('./application.cjs'));
+
+Object.assign(module.exports,require('./factory.cjs'));

package/src/operations/index.d.ts

@@ -0,0 +1,29 @@
+import type { Workflow, WorkflowJob, Json } from '../workflow.js';
+import type { SqliteJobStore, DurableQueue, KeyValueStore, SpendingStore } from '../storage/index.js';
+export interface Task {
+ id: string; type: string; description: string;
+ deliverables: Array<{id: string;media_type: string;description: string}>;
+ acceptance: {validator: string;version: string;criteria: {[key: string]: Json}};
+ inputs?: Json;
+}
+export interface EvidenceCheck {status: 'valid' | 'invalid' | 'insufficient_confirmations' | 'unavailable';[key: string]: unknown}
+export type Revalidator = (job: WorkflowJob,evidence: any) => Promise<EvidenceCheck>;
+export interface SigningContext {job: WorkflowJob;operation: any;actor: string;step: string;to: string;data: string;phase: 'sign' | 'broadcast'}
+export function validateTask(task: unknown): Task;
+export function validateEscrowEvidence(evidence: unknown): {[key: string]: Json};
+export function createSpendingAuthorizer(options: {spending: SpendingStore;limitsFor(context: SigningContext): Promise<{perTransaction: string;daily: string;total: string}>;authorize(context: SigningContext): Promise<boolean>}): (context: SigningContext) => Promise<boolean>;
+export function runMaintenanceOnce(options: {workflow: Workflow;store: SqliteJobStore;actorFor(job: WorkflowJob): Promise<string | null>;allowExecute?: boolean;now?: number}): Promise<Array<{id: string;state?: string;pending?: boolean;error?: string}>>;
+export function createExpiryAdapter(options?: {now?(): number}): {execute(context: {job: WorkflowJob}): Promise<any>;reconcile(context: {job: WorkflowJob}): Promise<any>};
+export function enqueueRunningJobs(options: {store: SqliteJobStore;queue: DurableQueue}): Promise<number>;
+export function runExecutionOnce(options: {workflow: Workflow;queue: DurableQueue;execute(context: {job: WorkflowJob;idempotencyKey: string}): Promise<{result_hash: string;[key: string]: Json}>;beforeExecute(job: WorkflowJob): Promise<boolean>;leaseMs?: number}): Promise<WorkflowJob | null>;
+export function createEventStream(options: {store: SqliteJobStore;authenticate(request: Request): Promise<string | null>;pollMs?: number;maxDurationMs?: number}): (request: Request) => Promise<Response>;
+export function createWebhookDispatcher(options: {queue: DurableQueue;kv: KeyValueStore;subscriptions: Array<{id: string;actor: string;url: string;after?: number}>;secretFor(id: string): Promise<string>;fetch?: typeof fetch;timeoutMs?: number}): {project(store: SqliteJobStore): Promise<void>;deliverOne(): Promise<any>};
+export function watchEvidenceOnce(options: {store: SqliteJobStore;revalidate: Revalidator}): Promise<any[]>;
+export function freshReceipts(options: {workflow: Workflow;id: string;actor: string;revalidate: Revalidator}): Promise<object>;
+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>;legacyState?(actor: string): Promise<object>;authorityHandler?(request: Request): Promise<Response>;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}): Promise<{result_hash: string;[key: string]: Json}>;keeperEnabled?: boolean;allowAuthorityRequest?(request: Request): Promise<boolean>;requireIndependentArbitrator?: boolean}): {workflow: Workflow;applicationOptions: Parameters<typeof createApplicationHandler>[0];workerOptions: any;handler: (request: Request) => Promise<Response>;chatTools(actor: string): ReturnType<typeof createChatTools>};

package/src/operations/index.mjs

@@ -0,0 +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;

package/src/storage/index.cjs

@@ -0,0 +1,83 @@
+'use strict';
+const { DatabaseSync } = require('node:sqlite');
+const { randomUUID } = require('node:crypto');
+const { mkdirSync, chmodSync } = require('node:fs');
+const { dirname } = require('node:path');
+const json=JSON.stringify, parse=JSON.parse;
+/** Single-host durable SQLite drivers. All writers must use this file on local disk. */
+function createSqliteStorage({filename,busyTimeoutMs=5000}={}) {
+  if(typeof filename!=='string'||!filename||!Number.isSafeInteger(busyTimeoutMs)||busyTimeoutMs<0||busyTimeoutMs>60000)throw new TypeError('Supply filename and valid busy timeout');
+  if(filename!==':memory:')mkdirSync(dirname(filename),{recursive:true,mode:0o700});
+  const db=new DatabaseSync(filename);
+  if(filename!==':memory:')chmodSync(filename,0o600);
+  db.exec(`PRAGMA busy_timeout=${busyTimeoutMs}; PRAGMA journal_mode=WAL; PRAGMA synchronous=FULL;
+    CREATE TABLE IF NOT EXISTS a423_jobs(id TEXT PRIMARY KEY,version INTEGER NOT NULL,payload TEXT NOT NULL);
+    CREATE TABLE IF NOT EXISTS a423_events(cursor INTEGER PRIMARY KEY AUTOINCREMENT,job_id TEXT NOT NULL,sequence INTEGER NOT NULL,payload TEXT NOT NULL,UNIQUE(job_id,sequence));
+    CREATE TABLE IF NOT EXISTS a423_transactions(id TEXT PRIMARY KEY,payload TEXT NOT NULL);
+    CREATE TABLE IF NOT EXISTS a423_nonces(scope TEXT PRIMARY KEY,next_nonce INTEGER NOT NULL);
+    CREATE TABLE IF NOT EXISTS a423_nonce_reservations(scope TEXT NOT NULL,operation_id TEXT NOT NULL,nonce INTEGER NOT NULL,PRIMARY KEY(scope,operation_id),UNIQUE(scope,nonce));
+    CREATE TABLE IF NOT EXISTS a423_kv(namespace TEXT NOT NULL,id TEXT NOT NULL,payload TEXT NOT NULL,PRIMARY KEY(namespace,id));
+    CREATE TABLE IF NOT EXISTS a423_queue(id TEXT PRIMARY KEY,kind TEXT NOT NULL,payload TEXT NOT NULL,status TEXT NOT NULL,available_at INTEGER NOT NULL,lease TEXT,lease_until INTEGER NOT NULL DEFAULT 0,attempts INTEGER NOT NULL DEFAULT 0,result TEXT);
+    CREATE INDEX IF NOT EXISTS a423_queue_ready ON a423_queue(status,available_at,lease_until);
+    CREATE TABLE IF NOT EXISTS a423_spend(id TEXT PRIMARY KEY,scope TEXT NOT NULL,amount TEXT NOT NULL,day TEXT NOT NULL,at INTEGER NOT NULL);
+    CREATE INDEX IF NOT EXISTS a423_spend_scope ON a423_spend(scope,day);`);
+  const atomic=fn=>{db.exec('BEGIN IMMEDIATE');try{const out=fn();db.exec('COMMIT');return out;}catch(e){db.exec('ROLLBACK');throw e;}};
+  const kv={
+    async get(namespace,id){const row=db.prepare('SELECT payload FROM a423_kv WHERE namespace=? AND id=?').get(namespace,id);return row?parse(row.payload):null;},
+    async put(namespace,id,value){db.prepare('INSERT INTO a423_kv VALUES(?,?,?) ON CONFLICT(namespace,id) DO UPDATE SET payload=excluded.payload').run(namespace,id,json(value));},
+    async create(namespace,id,value){return !!db.prepare('INSERT OR IGNORE INTO a423_kv VALUES(?,?,?)').run(namespace,id,json(value)).changes;},
+    async take(namespace,id){return atomic(()=>{const row=db.prepare('SELECT payload FROM a423_kv WHERE namespace=? AND id=?').get(namespace,id);db.prepare('DELETE FROM a423_kv WHERE namespace=? AND id=?').run(namespace,id);return row?parse(row.payload):null;});},
+    async list(namespace){return db.prepare('SELECT id,payload FROM a423_kv WHERE namespace=? ORDER BY id').all(namespace).map(r=>({id:r.id,value:parse(r.payload)}));}
+  };
+  const project=job=>{
+    for(const event of job.events)db.prepare('INSERT OR IGNORE INTO a423_events(job_id,sequence,payload) VALUES(?,?,?)').run(job.id,event.sequence,json({...event,job_id:job.id}));
+  };
+  const jobs={
+    async get(id){const r=db.prepare('SELECT payload FROM a423_jobs WHERE id=?').get(id);return r?parse(r.payload):null;},
+    async create(job){return atomic(()=>{const r=db.prepare('INSERT OR IGNORE INTO a423_jobs VALUES(?,?,?)').run(job.id,job.version,json(job));if(r.changes)project(job);return !!r.changes;});},
+    async compareAndSet(id,version,job){if(job.id!==id||job.version!==version+1)throw new Error('Invalid CAS record');return atomic(()=>{const r=db.prepare('UPDATE a423_jobs SET version=?,payload=? WHERE id=? AND version=?').run(job.version,json(job),id,version);if(r.changes)project(job);return !!r.changes;});},
+    async list({actor,limit=100,after=''}={}){if(!Number.isInteger(limit)||limit<1||limit>1000)throw new TypeError('Invalid limit');const rows=db.prepare('SELECT payload FROM a423_jobs WHERE id>? ORDER BY id').all(after).map(r=>parse(r.payload));return rows.filter(j=>!actor||Object.values(j.participants).includes(actor)).slice(0,limit);},
+    async events({actor,after=0,limit=100}={}){if(!actor||!Number.isSafeInteger(after)||after<0||!Number.isSafeInteger(limit)||limit<1||limit>1000)throw new TypeError('Invalid event query');return db.prepare('SELECT cursor,job_id,payload FROM a423_events WHERE cursor>? ORDER BY cursor').all(after).filter(r=>{const j=db.prepare('SELECT payload FROM a423_jobs WHERE id=?').get(r.job_id);return j&&Object.values(parse(j.payload).participants).includes(actor);}).slice(0,limit).map(r=>({cursor:r.cursor,...parse(r.payload)}));},
+    async getSafety(id){return kv.get('safety',id);},
+    async setSafety(id,value){return kv.put('safety',id,value);}
+  };
+  const transactions={
+    async get(id){const r=db.prepare('SELECT payload FROM a423_transactions WHERE id=?').get(id);return r?parse(r.payload):null;},
+    async create(id,record){return !!db.prepare('INSERT OR IGNORE INTO a423_transactions VALUES(?,?)').run(id,json(record)).changes;},
+    async list(){return db.prepare('SELECT id,payload FROM a423_transactions ORDER BY id').all().map(r=>({id:r.id,...parse(r.payload)}));},
+    async appendReplacement(id,expectedHash,replacement){return atomic(()=>{const row=db.prepare('SELECT payload FROM a423_transactions WHERE id=?').get(id);if(!row)throw Error('Unknown transaction');const record=parse(row.payload);if((record.replacements?.at(-1)?.hash||record.hash)!==expectedHash)throw Error('Replacement conflict');record.replacements=[...(record.replacements||[]),replacement];db.prepare('UPDATE a423_transactions SET payload=? WHERE id=?').run(json(record),id);});},
+    async reserveNonce(scope,minimum,operationId){if(!Number.isSafeInteger(minimum)||minimum<0)throw new TypeError('Invalid nonce');return atomic(()=>{const old=db.prepare('SELECT nonce FROM a423_nonce_reservations WHERE scope=? AND operation_id=?').get(scope,operationId);if(old)return old.nonce;const row=db.prepare('SELECT next_nonce FROM a423_nonces WHERE scope=?').get(scope);const nonce=Math.max(minimum,row?.next_nonce||0);db.prepare('INSERT INTO a423_nonces VALUES(?,?) ON CONFLICT(scope) DO UPDATE SET next_nonce=excluded.next_nonce').run(scope,nonce+1);db.prepare('INSERT INTO a423_nonce_reservations VALUES(?,?,?)').run(scope,operationId,nonce);return nonce;});}
+  };
+  const queue={
+    async enqueue({id,kind,payload,availableAt=Date.now()}){if(!id||!kind||!Number.isSafeInteger(availableAt))throw new TypeError('Invalid queue item');return !!db.prepare("INSERT OR IGNORE INTO a423_queue(id,kind,payload,status,available_at) VALUES(?,?,?,'ready',?)").run(id,kind,json(payload),availableAt).changes;},
+    async claim({kind,leaseMs=30000,now=Date.now()}={}){if(!Number.isSafeInteger(leaseMs)||leaseMs<1||!Number.isSafeInteger(now))throw new TypeError('Invalid lease');return atomic(()=>{const row=db.prepare("SELECT * FROM a423_queue WHERE kind=? AND ((status='ready' AND available_at<=?) OR (status='leased' AND lease_until<=?)) ORDER BY available_at,id LIMIT 1").get(kind,now,now);if(!row)return null;const lease=randomUUID();db.prepare("UPDATE a423_queue SET status='leased',lease=?,lease_until=?,attempts=attempts+1 WHERE id=?").run(lease,now+leaseMs,row.id);return {id:row.id,kind:row.kind,payload:parse(row.payload),lease,attempts:row.attempts+1,result:row.result?parse(row.result):null};});},
+    async heartbeat(id,lease,{leaseMs=30000,now=Date.now()}={}){return !!db.prepare("UPDATE a423_queue SET lease_until=? WHERE id=? AND lease=? AND status='leased' AND lease_until>?").run(now+leaseMs,id,lease,now).changes;},
+    async checkpoint(id,lease,result,{now=Date.now()}={}){return !!db.prepare("UPDATE a423_queue SET result=? WHERE id=? AND lease=? AND status='leased' AND lease_until>?").run(json(result),id,lease,now).changes;},
+    async complete(id,lease,result,{now=Date.now()}={}){return !!db.prepare("UPDATE a423_queue SET status='done',result=? WHERE id=? AND lease=? AND status='leased' AND lease_until>?").run(json(result),id,lease,now).changes;},
+    async retry(id,lease,{delayMs=1000,now=Date.now(),maxAttempts=10}={}){return !!db.prepare("UPDATE a423_queue SET status=CASE WHEN attempts>=? THEN 'failed' ELSE 'ready' END, available_at=?,lease=NULL,lease_until=0 WHERE id=? AND lease=? AND status='leased' AND lease_until>?").run(maxAttempts,now+delayMs,id,lease,now).changes;},
+    async get(id){const r=db.prepare('SELECT * FROM a423_queue WHERE id=?').get(id);return r?{id:r.id,kind:r.kind,payload:parse(r.payload),status:r.status,attempts:r.attempts,result:r.result?parse(r.result):null}:null;}
+  };
+  const spending={
+    async reserve({id,scope,amount,perTransaction,daily,total,now=Date.now()}){
+      const value=x=>{if(typeof x!=='string'||!/^(0|[1-9][0-9]*)$/.test(x))throw new TypeError('Use raw decimal amount strings');return BigInt(x);};
+      const n=value(amount),day=new Date(now).toISOString().slice(0,10);if(!id||!scope)throw new TypeError('Spend identity/scope required');
+      return atomic(()=>{const old=db.prepare('SELECT * FROM a423_spend WHERE id=?').get(id);if(old){if(old.scope!==scope||old.amount!==amount)throw Error('Spending idempotency conflict');}
+        const rows=db.prepare('SELECT amount,day FROM a423_spend WHERE scope=? AND id<>?').all(scope,id);const all=rows.reduce((a,r)=>a+BigInt(r.amount),0n),today=rows.filter(r=>r.day===day).reduce((a,r)=>a+BigInt(r.amount),0n);
+        if(perTransaction===undefined||daily===undefined||total===undefined)throw Error('Explicit per-transaction, daily and total caps required');
+        if(n>value(perTransaction)||n+today>value(daily)||n+all>value(total)){const error=Error('Spending limit exceeded');error.code='SPENDING_LIMIT_EXCEEDED';throw error;}
+        db.prepare('INSERT INTO a423_spend VALUES(?,?,?,?,?) ON CONFLICT(id) DO UPDATE SET day=excluded.day,at=excluded.at').run(id,scope,amount,day,now);return true;});
+    },
+    // Conservative reservations persist after approvals and uncertain outcomes. Release only after external reconciliation.
+    async list(scope){return db.prepare('SELECT * FROM a423_spend WHERE scope=? ORDER BY at,id').all(scope);},
+    async release(id){db.prepare('DELETE FROM a423_spend WHERE id=?').run(id);}
+  };
+  return {jobs,transactions,queue,spending,kv,
+    async resetDevelopmentData({chainId,confirm,assertChainReset,includeAuthority=false,dryRun=true}={}){
+      if(![1337,31337].includes(chainId)||confirm!=='RESET_LOCAL_A423'||typeof assertChainReset!=='function'||await assertChainReset()!==true)throw Error('Reset requires confirmed local chain reset');
+      const tables=['a423_jobs','a423_events','a423_transactions','a423_nonces','a423_nonce_reservations','a423_queue','a423_spend'];
+      const counts=Object.fromEntries(tables.map(name=>[name,db.prepare('SELECT COUNT(*) AS n FROM '+name).get().n]));
+      if(!dryRun)atomic(()=>{for(const name of tables)db.exec('DELETE FROM '+name);if(includeAuthority)db.exec('DELETE FROM a423_kv');else db.exec("DELETE FROM a423_kv WHERE namespace NOT LIKE 'authority:%'");});
+      return {dryRun,counts,includeAuthority};
+    },close(){db.close();}};
+}
+module.exports={createSqliteStorage};

package/src/storage/index.d.ts

@@ -0,0 +1,37 @@
+import type { WorkflowStore, WorkflowJob, Json } from '../workflow.js';
+export interface TransactionRecord {hash: string;raw: string;to: string;data: string;from: string;created_at?: string;replacements?: TransactionRecord[]}
+export interface TransactionStore {get(id: string): Promise<TransactionRecord | null>;create(id: string,record: TransactionRecord): Promise<boolean>;reserveNonce(scope: string,minimum: number,operationId: string): Promise<number>;list(): Promise<Array<TransactionRecord & {id: string}>>;appendReplacement(id: string,expectedHash: string,replacement: TransactionRecord): Promise<void>}
+export interface Safety { blocked: boolean; checks: Array<{status: string; [key: string]: unknown}>; checked_at: string }
+export interface SqliteJobStore extends WorkflowStore {
+ list(options?: {actor?: string; after?: string; limit?: number}): Promise<WorkflowJob[]>;
+ events(options: {actor: string; after?: number; limit?: number}): Promise<Array<{cursor: number; job_id: string; sequence: number; type: string; actor_id: string; at: string; data: Json}>>;
+ getSafety(id: string): Promise<Safety | null>;
+ setSafety(id: string, value: Safety): Promise<void>;
+}
+export interface KeyValueStore {
+ get(namespace: string,id: string): Promise<any>;
+ put(namespace: string,id: string,value: unknown): Promise<void>;
+ create(namespace: string,id: string,value: unknown): Promise<boolean>;
+ take(namespace: string,id: string): Promise<any>;
+ list(namespace: string): Promise<Array<{id: string; value: any}>>;
+}
+export interface QueueItem {id: string; kind: string; payload: any; lease: string; attempts: number; result: any}
+export interface DurableQueue {
+ enqueue(input: {id: string; kind: string; payload: unknown; availableAt?: number}): Promise<boolean>;
+ claim(options: {kind: string; leaseMs?: number; now?: number}): Promise<QueueItem | null>;
+ heartbeat(id: string, lease: string, options?: {leaseMs?: number; now?: number}): Promise<boolean>;
+ checkpoint(id: string, lease: string, result: unknown, options?: {now?: number}): Promise<boolean>;
+ complete(id: string, lease: string, result: unknown, options?: {now?: number}): Promise<boolean>;
+ retry(id: string, lease: string, options?: {delayMs?: number; now?: number; maxAttempts?: number}): Promise<boolean>;
+ get(id: string): Promise<{id: string; kind: string; payload: unknown; status: string; attempts: number; result: unknown} | null>;
+}
+export interface SpendingStore {
+ reserve(input: {id: string;scope: string;amount: string;perTransaction: string;daily: string;total: string;now?: number}): Promise<boolean>;
+ release(id: string): Promise<void>;
+}
+export interface SqliteStorage {
+ jobs: SqliteJobStore; transactions: TransactionStore; kv: KeyValueStore; queue: DurableQueue; spending: SpendingStore;
+ resetDevelopmentData(options: {chainId: number;confirm: 'RESET_LOCAL_A423';assertChainReset(): Promise<boolean>;includeAuthority?: boolean;dryRun?: boolean}): Promise<{dryRun: boolean;counts: Record<string,number>;includeAuthority: boolean}>;
+ close(): void;
+}
+export function createSqliteStorage(options: {filename: string;busyTimeoutMs?: number}): SqliteStorage;

package/src/storage/index.mjs

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

package/src/workflow.cjs

@@ -31,7 +31,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, transitions = {} } = {}) {
+function createWorkflow({ store, adapters = {}, authorize, 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)) {
@@ -70,6 +70,7 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, transi
       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);
+    if(validateEvidence)await validateEvidence({job:copy(job),action:pending.action,evidence:copy(result.evidence)});
     const next = copy(job); next.pending = null; next.state = pending.target;
     next.operations[pending.key] = { request_hash: pending.request_hash, status: 'confirmed', result: copy(result) };
     next.evidence.push({ action: pending.action, operation_id: pending.id, evidence: copy(result.evidence) });
@@ -99,10 +100,13 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, transi
       return copy(job);
     },
     get,
+    async assertSafe(id,actor){const job=await get(id,actor);const safety=store.getSafety?await store.getSafety(id):null;if(safety?.blocked)error('SAFETY_HOLD','Evidence requires reconciliation',409);return job;},
     async act(id, action, input, { actor, idempotencyKey } = {}) {
       identifier(actor); identifier(idempotencyKey); identifier(action); canonical(input);
       let job = await get(id, actor);
-      const rule = rules[action];
+      const safety=store.getSafety ? await store.getSafety(id) : null;
+      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);
       await allowed(job, action, actor, input, rule);
       const key = digest([actor, idempotencyKey]);
@@ -136,6 +140,14 @@ function createWorkflow({ store, adapters = {}, authorize, validateTerms, transi
       next.operations[key] = { request_hash: requestHash, status: 'confirmed', result: { status: 'confirmed' } };
       return save(job, next, action, actor, input);
     },
+    async resume(id, actor) {
+      const job=await get(id,actor);
+      if(!job.pending)return job;
+      const safety=store.getSafety ? await store.getSafety(id) : null;
+      if(safety?.blocked)error('SAFETY_HOLD','Evidence requires reconciliation',409);
+      await allowed(job,job.pending.action,actor,job.pending.input,rules[job.pending.action]);
+      return execute(job);
+    },
     async reconcile(id, actor) {
       const job = await get(id, actor);
       if (!job.pending) return job;

package/src/workflow.d.ts

@@ -26,6 +26,7 @@ export interface WorkflowOptions {
   /** Return true to allow; authenticated actor ID must be supplied by your application. */
   authorize?(context: { job: WorkflowJob; action: string; actor: string; input: Json }): boolean | Promise<boolean>;
   /** Throw to reject application-specific terms. */
+  validateEvidence?(context: {job: WorkflowJob;action: string;evidence: {[key: string]: Json}}): void | Promise<void>;
   validateTerms?(terms: { [key: string]: Json }): void | Promise<void>;
   /** Explicit overrides replace the full rule; application is responsible for its invariants. */
   transitions?: Record<string, Transition>;
@@ -33,7 +34,9 @@ export interface WorkflowOptions {
 export interface Workflow {
   create(input: { id?: string; participants: WorkflowJob['participants']; metadata?: Json }, actor: string): Promise<WorkflowJob>;
   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>;
+  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'> & { job_id: string }>;
 }