@ramex-labs/continuity-remote 0.3.0-preview.1

package/dist/remote-tools/destination.mjs

@@ -0,0 +1,180 @@
+import http from 'node:http';
+import { openDestinationStore } from './durable-store.mjs';
+import { stateOf } from '@ramex-labs/continuity/adapter';
+import { captureHistory } from '@ramex-labs/continuity/adapter';
+import { capture, exact, textId, hashId, integer, canonicalDigest, encodeTransport, decodeTransport,
+  publicKeyIdentity, verifyRequest, signResponse, validateOperationShape, validateReport, MAX_WIRE_BYTES } from './wire.mjs';
+
+const refuse=code=>{throw Object.assign(new Error(code),{code});};
+const same=(a,b)=>canonicalDigest(a)===canonicalDigest(b);
+const response=(state,code)=>({state,code});
+const refusals=['NO_CHECKPOINT','CHECKPOINT_CONFLICT','CHECKPOINT_CHANGED','OPERATION_CONFLICT','BUSINESS_KEY_CONFLICT',
+  'AUTHORIZATION_REFUSED','CLOCK_INVALID','CAPACITY_EXHAUSTED','INVALID_OPERATION'];
+const requestBytes=request=>new Promise((resolve,reject)=>{
+  const parts=[];let size=0,settled=false;
+  const timer=setTimeout(()=>{if(!settled){settled=true;reject(Error('REQUEST_TIMEOUT'));request.destroy();}},5000);
+  const end=()=>clearTimeout(timer);
+  request.on('data',chunk=>{if(settled)return;size+=chunk.length;if(size>MAX_WIRE_BYTES){settled=true;end();reject(Error('REQUEST_LIMIT'));request.destroy();}else parts.push(chunk);});
+  request.on('end',()=>{if(settled)return;settled=true;end();resolve(Buffer.concat(parts));});
+  request.on('error',error=>{if(settled)return;settled=true;end();reject(error);});
+  request.on('aborted',()=>{if(settled)return;settled=true;end();reject(Error('REQUEST_ABORTED'));});
+});
+
+/** Synthetic effects only: effect and deduplication record share one commit. */
+export async function createCooperativeDestination({directory,domain,serviceId,coordinatorPublicKey,servicePrivateKey,now,validateOperation}) {
+  domain=capture(domain);textId(serviceId);
+  if(typeof now!=='function'||typeof validateOperation!=='function'||servicePrivateKey.type!=='private'||coordinatorPublicKey.type!=='public')throw Error('INVALID_CONFIGURATION');
+  const coordinatorKey=publicKeyIdentity(coordinatorPublicKey),serviceKey=publicKeyIdentity(servicePrivateKey);
+  const store=openDestinationStore({directory,initial:{version:'continuity-cooperative-destination/1',domain,serviceId,
+    coordinatorKey,serviceKey,sequence:0,lastTime:0,checkpoint:null,attempts:[],businessKeys:[],effects:[]}});
+  const clock=state=>{
+    let at;try{at=integer(now());}catch{refuse('CLOCK_INVALID');}
+    if(at<state.lastTime||(state.checkpoint&&at<state.checkpoint.head.canonicalTime))refuse('CLOCK_INVALID');
+    state.lastTime=at;
+    return at;
+  };
+  const normalized=(events,operation,at,state)=>{
+    let result;
+    try{result=capture(validateOperation(events,operation,at,capture(state)));}
+    catch{refuse('AUTHORIZATION_REFUSED');}
+    exact(result,['intentId','idempotencyKey','submissionFingerprint','tool','arguments','businessKey','contractId']);
+    hashId(result.idempotencyKey);hashId(result.submissionFingerprint);
+    for(const name of ['intentId','tool','businessKey','contractId'])textId(result[name]);
+    if(result.intentId!==operation.intentId||result.tool!==operation.tool||result.businessKey!==operation.businessKey||
+        result.contractId!==operation.contractId||!same(result.arguments,operation.arguments))refuse('INVALID_OPERATION');
+    return result;
+  };
+  const validateSaved=state=>{
+    const heads=new Map();
+    if(state.checkpoint!==null){
+      exact(state.checkpoint,['head','events']);const events=captureHistory(state.checkpoint.events),replayed=stateOf(events);
+      if(!same(replayed.genesis.domain,domain)||!same(replayed.head,state.checkpoint.head))throw Error('STORAGE_UNAVAILABLE');
+      heads.set(replayed.head.position,replayed.head);
+    }
+    const keys=new Set(),business=new Set(),effects=new Set();
+    for(const item of state.attempts){
+      exact(item,['key','fingerprint','intentId','operation','normalized','checkpointHead','preparedAt','report']);
+      hashId(item.key);hashId(item.fingerprint);integer(item.preparedAt);validateOperationShape(item.operation);validateReport(item.report);
+      exact(item.normalized,['intentId','idempotencyKey','submissionFingerprint','tool','arguments','businessKey','contractId']);
+      exact(item.checkpointHead,['hash','position','canonicalTime']);hashId(item.checkpointHead.hash);
+      integer(item.checkpointHead.position);integer(item.checkpointHead.canonicalTime);
+      if(!state.checkpoint||item.checkpointHead.position>state.checkpoint.head.position||
+        item.preparedAt<item.checkpointHead.canonicalTime)throw Error('STORAGE_UNAVAILABLE');
+      if(!heads.has(item.checkpointHead.position))heads.set(item.checkpointHead.position,
+        stateOf(state.checkpoint.events.slice(0,item.checkpointHead.position+1)).head);
+      if(!same(heads.get(item.checkpointHead.position),item.checkpointHead))throw Error('STORAGE_UNAVAILABLE');
+      if(keys.has(item.key)||item.normalized.idempotencyKey!==item.key||item.normalized.submissionFingerprint!==item.fingerprint||
+          !same(item.normalized,{...item.operation,idempotencyKey:item.key,submissionFingerprint:item.fingerprint})||
+          item.intentId!==item.operation.intentId||item.report.key!==item.key||item.report.fingerprint!==item.fingerprint||
+          item.report.intentId!==item.intentId||item.report.tool!==item.operation.tool||item.report.businessKey!==item.operation.businessKey||
+          item.report.contractId!==item.operation.contractId||item.report.checkpointHash!==item.checkpointHead.hash)throw Error('STORAGE_UNAVAILABLE');
+      keys.add(item.key);
+    }
+    for(const binding of state.businessKeys){exact(binding,['businessKey','key','intentId']);if(business.has(binding.businessKey)||
+      !state.attempts.some(item=>item.key===binding.key&&item.intentId===binding.intentId&&item.operation.businessKey===binding.businessKey))throw Error('STORAGE_UNAVAILABLE');business.add(binding.businessKey);}
+    if(business.size!==state.attempts.length)throw Error('STORAGE_UNAVAILABLE');
+    for(const effect of state.effects){
+      exact(effect,['effectId','key','fingerprint','tool','arguments','businessKey','contractId']);
+      const attempt=state.attempts.find(item=>item.key===effect.key);
+      if(effects.has(effect.key)||!attempt||attempt.report.state!=='APPLIED'||attempt.report.effectId!==effect.effectId||
+          effect.fingerprint!==attempt.fingerprint||effect.tool!==attempt.normalized.tool||
+          !same(effect.arguments,attempt.normalized.arguments)||effect.businessKey!==attempt.normalized.businessKey||effect.contractId!==attempt.normalized.contractId)throw Error('STORAGE_UNAVAILABLE');
+      effects.add(effect.key);
+    }
+    if(state.attempts.some(item=>(item.report.state==='APPLIED')!==effects.has(item.key)))throw Error('STORAGE_UNAVAILABLE');
+    return state;
+  };
+  try{validateSaved(store.read());}catch(error){store.close();throw error;}
+  const handle=body=>{
+    try{
+      const committed=store.transact(state=>{
+        validateSaved(state);
+        const before=capture(state);
+        try {
+        const {operation,payload}=body;
+        let result;
+        if(operation==='checkpoint'){
+          const at=clock(state);let events,replayed;
+          try{events=captureHistory(payload.events);replayed=stateOf(events);}catch{refuse('CHECKPOINT_CONFLICT');}
+          if(!same(replayed.genesis.domain,domain)||at<replayed.head.canonicalTime)refuse('CHECKPOINT_CONFLICT');
+          if(state.checkpoint){
+            const prior=state.checkpoint.events;
+            if(events.length<prior.length||!same(events.slice(0,prior.length),prior))refuse('CHECKPOINT_CONFLICT');
+            if(events.length===prior.length)return{state,result:{state:'CHECKPOINTED',head:state.checkpoint.head}};
+          }
+          state.checkpoint={events,head:replayed.head};state.lastTime=at;
+          result={state:'CHECKPOINTED',head:replayed.head};
+        }else if(operation==='prepare'){
+          if(!state.checkpoint)refuse('NO_CHECKPOINT');
+          const at=clock(state),op=payload.operation,norm=normalized(state.checkpoint.events,op,at,state);
+          const prior=state.attempts.find(item=>item.key===norm.idempotencyKey);
+          if(prior){
+            if(!same(prior.operation,op)||!same(prior.normalized,norm))refuse('OPERATION_CONFLICT');
+            if(!same(prior.checkpointHead,state.checkpoint.head))refuse('CHECKPOINT_CHANGED');
+            return{state,result:prior.report};
+          }
+          if(state.businessKeys.some(item=>item.businessKey===norm.businessKey))refuse('BUSINESS_KEY_CONFLICT');
+          if(state.attempts.length>=256)refuse('CAPACITY_EXHAUSTED');
+          const report={state:'PENDING',key:norm.idempotencyKey,fingerprint:norm.submissionFingerprint,
+            intentId:norm.intentId,tool:norm.tool,businessKey:norm.businessKey,contractId:norm.contractId,checkpointHash:state.checkpoint.head.hash};
+          state.attempts.push({key:norm.idempotencyKey,fingerprint:norm.submissionFingerprint,intentId:norm.intentId,
+            operation:op,normalized:norm,checkpointHead:state.checkpoint.head,preparedAt:at,report});
+          state.businessKeys.push({businessKey:norm.businessKey,key:norm.idempotencyKey,intentId:norm.intentId});
+          state.lastTime=at;result=report;
+        }else{
+          const prior=state.attempts.find(item=>item.key===payload.key);
+          if(!prior)return{state,result:{state:'UNKNOWN',key:payload.key}};
+          if(operation==='status')return{state,result:prior.report};
+          if(operation==='cancel'){
+            if(prior.report.state==='APPLIED')return{state,result:{state:'TOO_LATE',report:prior.report}};
+            if(prior.report.state==='CANCELLED')return{state,result:prior.report};
+            // Cancellation reduces authority. A faulty clock cannot block it
+            // or lower the floor used to admit future work.
+            try{state.lastTime=Math.max(state.lastTime,integer(now()));}catch{}
+            prior.report={...prior.report,state:'CANCELLED'};result=prior.report;
+          }else if(operation==='commit'){
+            if(prior.report.state!=='PENDING')return{state,result:prior.report};
+            if(!state.checkpoint||!same(prior.checkpointHead,state.checkpoint.head))refuse('CHECKPOINT_CHANGED');
+            const at=clock(state),norm=normalized(state.checkpoint.events,prior.operation,at,state);
+            if(!same(norm,prior.normalized))refuse('OPERATION_CONFLICT');
+            const effectId='effect:'+prior.key.slice(2);
+            state.effects.push({effectId,key:prior.key,fingerprint:prior.fingerprint,tool:norm.tool,
+              arguments:norm.arguments,businessKey:norm.businessKey,contractId:norm.contractId});
+            prior.report={...prior.report,state:'APPLIED',effectId};state.lastTime=at;result=prior.report;
+          }else refuse('INVALID_OPERATION');
+        }
+        validateSaved(state);return{state,result};
+        }catch(error){
+          if(!refusals.includes(error.code))throw error;
+          // An observed later trusted time survives a refusal. Otherwise a
+          // subsequent backward clock could revive an expired permission.
+          return{state:{...before,lastTime:Math.max(before.lastTime,state.lastTime)},result:response('REFUSED',error.code)};
+        }
+      });
+      return{sequence:committed.state.sequence,result:committed.result};
+    }catch(error){
+      const code=refusals.includes(error.code)?error.code:'STORAGE_UNAVAILABLE';
+      return{sequence:store.read().sequence,result:response('REFUSED',code)};
+    }
+  };
+  const sockets=new Set();let closing=false;
+  const server=http.createServer(async(request,res)=>{
+    if(request.method!=='POST'||request.url!=='/cooperative'){res.writeHead(404);res.end();return;}
+    try{
+      const envelope=decodeTransport(await requestBytes(request));
+      const body=verifyRequest(envelope,coordinatorPublicKey,{serviceId});
+      const result=handle(body);
+      const receipt=signResponse({version:'continuity-cooperative-response/1',serviceId,requestDigest:canonicalDigest(body),...result},servicePrivateKey);
+      res.writeHead(200,{'content-type':'application/json'});res.end(encodeTransport(receipt));
+    }catch{if(!res.destroyed){res.writeHead(400);res.end();}}
+  });
+  server.on('connection',socket=>{sockets.add(socket);socket.on('close',()=>sockets.delete(socket));});
+  server.requestTimeout=5000;server.headersTimeout=5000;
+  try{await new Promise((resolve,reject)=>{server.once('error',reject);server.listen(0,'127.0.0.1',()=>{server.off('error',reject);resolve();});});}
+  catch(error){store.close();throw error;}
+  return Object.freeze({
+    url:`http://127.0.0.1:${server.address().port}`,
+    inspect(){return capture(validateSaved(store.read()));},
+    async close(){if(closing)return;closing=true;for(const socket of sockets)socket.destroy();await new Promise(resolve=>server.close(resolve));store.close();},
+  });
+}

package/dist/remote-tools/durable-store.mjs

@@ -0,0 +1,232 @@
+/** Single-host cooperative destination store; checksums are not rollback authentication. */
+import {
+  constants, openSync, closeSync, writeFileSync, readSync, fsyncSync, fstatSync,
+  lstatSync, realpathSync, readdirSync, renameSync, unlinkSync, existsSync,
+} from 'node:fs';
+import {join,resolve} from 'node:path';
+import {hostname} from 'node:os';
+import {randomUUID} from 'node:crypto';
+import {types} from 'node:util';
+import {encodeTransport,decodeTransport,canonicalDigest} from './wire.mjs';
+
+const FILE_LIMIT=16*1024*1024, RECORD_LIMIT=1024;
+const STATE_VERSION='continuity-cooperative-destination/1';
+const SNAPSHOT_VERSION='continuity-destination-snapshot/1';
+const IDENTITY_VERSION='continuity-destination-identity/1';
+const LOCK_VERSION='continuity-destination-lock/1';
+const STATE_KEYS=['version','domain','serviceId','coordinatorKey','serviceKey','sequence','lastTime','checkpoint','attempts','businessKeys','effects'];
+const IDENTITY_KEYS=['version','domain','serviceId','coordinatorKey','serviceKey'];
+const HASH=/^0x[0-9a-f]{64}$/;
+const fail=code=>{throw Object.assign(new Error(code),{code})};
+const check=(condition,code='DESTINATION_STATE_INVALID')=>{if(!condition)fail(code)};
+const equal=(a,b)=>canonicalDigest(a)===canonicalDigest(b);
+const exact=(value,keys)=>value!==null&&typeof value==='object'&&!Array.isArray(value)&&
+  Object.keys(value).length===keys.length&&keys.every(key=>Object.hasOwn(value,key));
+const integer=value=>Number.isSafeInteger(value)&&value>=0&&!Object.is(value,-0);
+const identifier=value=>typeof value==='string'&&value.length>0&&value.length<=256&&!/[\u0000-\u001f\u007f]/u.test(value);
+const capture=value=>decodeTransport(encodeTransport(value));
+const identityOf=state=>capture(Object.fromEntries(IDENTITY_KEYS.map(key=>[key,state[key]])));
+
+function checkedDirectory(value) {
+  check(typeof value==='string'&&value.length>0,'DIRECTORY_INVALID');
+  const path=resolve(value);
+  check(realpathSync(path)===path&&lstatSync(path).isDirectory(),'DIRECTORY_INVALID');
+  return path;
+}
+function syncDirectory(path) {
+  const fd=openSync(path,constants.O_RDONLY|constants.O_DIRECTORY|constants.O_NOFOLLOW);
+  try {fsyncSync(fd)} finally {closeSync(fd)}
+}
+function readFile(path,maximum=FILE_LIMIT) {
+  const before=lstatSync(path);
+  check(before.isFile()&&!before.isSymbolicLink()&&before.nlink===1&&before.size<=maximum,'DESTINATION_FILE_INVALID');
+  const fd=openSync(path,constants.O_RDONLY|constants.O_NOFOLLOW|constants.O_NONBLOCK);
+  try {
+    const opened=fstatSync(fd);
+    check(opened.isFile()&&opened.nlink===1&&opened.dev===before.dev&&opened.ino===before.ino&&opened.size<=maximum,'DESTINATION_FILE_INVALID');
+    const buffer=Buffer.alloc(opened.size+1);let offset=0;
+    while(offset<buffer.length){const count=readSync(fd,buffer,offset,buffer.length-offset,null);if(!count)break;offset+=count}
+    const after=fstatSync(fd),named=lstatSync(path);
+    check(offset===opened.size&&after.size===opened.size&&after.mtimeMs===opened.mtimeMs&&after.ctimeMs===opened.ctimeMs&&
+      after.nlink===1&&!named.isSymbolicLink()&&named.dev===opened.dev&&named.ino===opened.ino,'DESTINATION_FILE_CHANGED');
+    const bytes=buffer.subarray(0,offset),value=decodeTransport(bytes);
+    // Only the writer's exact serialization is a valid stored record.
+    check(bytes.equals(encodeTransport(value)),'DESTINATION_ENCODING_INVALID');
+    return value;
+  } finally {closeSync(fd)}
+}
+function createFile(path,value,maximum=FILE_LIMIT) {
+  const bytes=encodeTransport(value);check(bytes.length<=maximum,'DESTINATION_FILE_LIMIT');
+  const fd=openSync(path,constants.O_WRONLY|constants.O_CREAT|constants.O_EXCL|constants.O_NOFOLLOW,0o600);
+  try {writeFileSync(fd,bytes);fsyncSync(fd)} finally {closeSync(fd)}
+}
+function identityEnvelope(identity) {
+  const body={version:IDENTITY_VERSION,identity};
+  return {...body,checksum:canonicalDigest(body)};
+}
+function readIdentity(path) {
+  const value=readFile(path,65536);
+  check(exact(value,['version','identity','checksum'])&&value.version===IDENTITY_VERSION&&
+    exact(value.identity,IDENTITY_KEYS)&&value.checksum===canonicalDigest({version:value.version,identity:value.identity}),'DESTINATION_IDENTITY_INVALID');
+  return value.identity;
+}
+function validateState(input,identity) {
+  const state=capture(input);
+  check(exact(state,STATE_KEYS)&&state.version===STATE_VERSION&&integer(state.sequence)&&integer(state.lastTime));
+  check(exact(state.domain,['protocol','version','deploymentId','chainId','verifyingContract'])&&
+    state.domain.protocol==='continuity'&&state.domain.version==='0.2'&&identifier(state.domain.deploymentId)&&
+    typeof state.domain.chainId==='string'&&/^[1-9][0-9]*$/.test(state.domain.chainId)&&state.domain.chainId.length<=78&&
+    typeof state.domain.verifyingContract==='string'&&/^0x[0-9a-fA-F]{40}$/.test(state.domain.verifyingContract));
+  check(identifier(state.serviceId)&&typeof state.coordinatorKey==='string'&&HASH.test(state.coordinatorKey)&&
+    typeof state.serviceKey==='string'&&HASH.test(state.serviceKey));
+  if(identity)check(equal(identityOf(state),identity),'DESTINATION_IDENTITY_MISMATCH');
+  for(const key of ['attempts','businessKeys','effects'])check(Array.isArray(state[key])&&state[key].length<=RECORD_LIMIT,'DESTINATION_RECORD_LIMIT');
+  if(state.checkpoint!==null){
+    check(exact(state.checkpoint,['head','events'])&&Array.isArray(state.checkpoint.events)&&state.checkpoint.events.length>0&&state.checkpoint.events.length<=256);
+    const head=state.checkpoint.head;
+    check(exact(head,['hash','position','canonicalTime'])&&typeof head.hash==='string'&&HASH.test(head.hash)&&integer(head.position)&&integer(head.canonicalTime)&&
+      head.position===state.checkpoint.events.length-1&&head.canonicalTime<=state.lastTime);
+  }
+  const attemptKeys=new Set(),businessKeys=new Set(),effectKeys=new Set();
+  for(const attempt of state.attempts){
+    check(exact(attempt,['key','fingerprint','intentId','operation','normalized','checkpointHead','preparedAt','report']));
+    check(typeof attempt.key==='string'&&HASH.test(attempt.key)&&typeof attempt.fingerprint==='string'&&HASH.test(attempt.fingerprint)&&
+      identifier(attempt.intentId)&&integer(attempt.preparedAt)&&attempt.preparedAt<=state.lastTime&&!attemptKeys.has(attempt.key));
+    attemptKeys.add(attempt.key);
+  }
+  for(const record of state.businessKeys){
+    check(exact(record,['businessKey','key','intentId'])&&identifier(record.businessKey)&&typeof record.key==='string'&&HASH.test(record.key)&&
+      identifier(record.intentId)&&!businessKeys.has(record.businessKey)&&attemptKeys.has(record.key));
+    businessKeys.add(record.businessKey);
+  }
+  for(const effect of state.effects){
+    check(exact(effect,['effectId','key','fingerprint','tool','arguments','businessKey','contractId'])&&identifier(effect.effectId)&&
+      typeof effect.key==='string'&&HASH.test(effect.key)&&typeof effect.fingerprint==='string'&&HASH.test(effect.fingerprint)&&
+      identifier(effect.tool)&&identifier(effect.businessKey)&&identifier(effect.contractId)&&!effectKeys.has(effect.key)&&attemptKeys.has(effect.key));
+    effectKeys.add(effect.key);
+  }
+  return state;
+}
+function monotonic(previous,next) {
+  check(next.sequence===previous.sequence,'DESTINATION_SEQUENCE_OWNED_BY_STORE');
+  check(next.lastTime>=previous.lastTime,'DESTINATION_TIME_ROLLBACK');
+  for(const key of ['attempts','businessKeys','effects'])check(next[key].length>=previous[key].length,'DESTINATION_PRUNING_FORBIDDEN');
+  for(let index=0;index<previous.attempts.length;index++){
+    const {report:oldReport,...oldIdentity}=previous.attempts[index];
+    const {report:newReport,...newIdentity}=next.attempts[index];
+    check(equal(oldIdentity,newIdentity),'DESTINATION_ATTEMPT_IDENTITY_CHANGED');
+    if(oldReport?.state==='APPLIED'||oldReport?.state==='CANCELLED')check(equal(oldReport,newReport),'DESTINATION_TERMINAL_CHANGED');
+  }
+  for(const key of ['businessKeys','effects'])for(let index=0;index<previous[key].length;index++)check(equal(previous[key][index],next[key][index]),'DESTINATION_RETAINED_RECORD_CHANGED');
+  if(previous.checkpoint!==null){
+    check(next.checkpoint!==null&&next.checkpoint.events.length>=previous.checkpoint.events.length,'DESTINATION_CHECKPOINT_ROLLBACK');
+    for(let index=0;index<previous.checkpoint.events.length;index++)check(equal(previous.checkpoint.events[index],next.checkpoint.events[index]),'DESTINATION_CHECKPOINT_FORK');
+  }
+}
+function snapshotEnvelope(state,identityHash) {
+  const body={version:SNAPSHOT_VERSION,identityHash,state};
+  return {...body,checksum:canonicalDigest(body)};
+}
+function loadSnapshot(path,identity) {
+  const value=readFile(path);
+  check(exact(value,['version','identityHash','state','checksum'])&&value.version===SNAPSHOT_VERSION&&
+    value.identityHash===canonicalDigest(identity)&&value.checksum===canonicalDigest({version:value.version,identityHash:value.identityHash,state:value.state}),'DESTINATION_INTEGRITY_INVALID');
+  return validateState(value.state,identity);
+}
+function lockRecord() {return {version:LOCK_VERSION,hostname:hostname(),pid:process.pid,instance:randomUUID()}}
+function validateLock(value) {
+  check(exact(value,['version','hostname','pid','instance'])&&value.version===LOCK_VERSION&&identifier(value.hostname)&&
+    Number.isSafeInteger(value.pid)&&value.pid>0&&typeof value.instance==='string'&&/^[0-9a-f-]{36}$/.test(value.instance),'DESTINATION_LOCK_INVALID');
+  return value;
+}
+function assertOwnLock(path,lock) {check(equal(validateLock(readFile(path,65536)),lock),'DESTINATION_LOCK_CHANGED')}
+
+/** Read-only evidence for a separate, explicit operator recovery step. */
+export function inspectDestinationLock({directory}) {
+  return validateLock(readFile(join(checkedDirectory(directory),'destination.lock'),65536));
+}
+
+/** Exact lock token + same host + OS-confirmed absent PID. Never age-based. */
+export function recoverDestinationLock({directory,expectedLock}) {
+  const root=checkedDirectory(directory),expected=validateLock(capture(expectedLock));
+  check(expected.hostname===hostname(),'DESTINATION_FOREIGN_LOCK');
+  const lockPath=join(root,'destination.lock'),recoveryPath=join(root,'recovery.lock'),recovery=lockRecord();
+  try{createFile(recoveryPath,recovery,65536);syncDirectory(root)}catch(error){if(error.code==='EEXIST')fail('DESTINATION_RECOVERY_LOCKED');throw error}
+  try{
+    assertOwnLock(lockPath,expected);
+    let absent=false;
+    try{process.kill(expected.pid,0)}catch(error){if(error.code==='ESRCH')absent=true;else fail('DESTINATION_LOCK_OWNER_UNVERIFIED')}
+    check(absent,'DESTINATION_LOCK_OWNER_ALIVE');
+    assertOwnLock(lockPath,expected);
+    const retained=join(root,`recovered-${expected.instance}.lock`);
+    check(!existsSync(retained),'DESTINATION_RECOVERY_EVIDENCE_EXISTS');
+    renameSync(lockPath,retained);syncDirectory(root);
+    return Object.freeze({recovered:true,retainedLock:retained,lock:expected});
+  } finally {
+    assertOwnLock(recoveryPath,recovery);unlinkSync(recoveryPath);syncDirectory(root);
+  }
+}
+
+/** One lifetime lock, no pruning or implicit unlock/reinitialization. */
+export function openDestinationStore({directory,initial}) {
+  const root=checkedDirectory(directory),initialState=validateState(initial);
+  check(initialState.sequence===0&&initialState.lastTime===0&&initialState.checkpoint===null&&
+    initialState.attempts.length===0&&initialState.businessKeys.length===0&&initialState.effects.length===0,'DESTINATION_INITIAL_INVALID');
+  const identity=identityOf(initialState),lock=lockRecord();
+  const lockPath=join(root,'destination.lock'),identityPath=join(root,'identity.bin'),snapshotPath=join(root,'snapshot.bin');
+  check(!existsSync(join(root,'recovery.lock')),'DESTINATION_RECOVERY_LOCKED');
+  const before=readdirSync(root);
+  try {createFile(lockPath,lock,65536);syncDirectory(root)}catch(error){if(error.code==='EEXIST')fail('DESTINATION_LOCKED');throw error}
+  let closed=false,busy=false,poisoned=false,current;
+  const release=()=>{assertOwnLock(lockPath,lock);unlinkSync(lockPath);syncDirectory(root)};
+  const writeSnapshot=state=>{
+    const temporary=join(root,`snapshot-${randomUUID()}.tmp`);
+    createFile(temporary,snapshotEnvelope(state,canonicalDigest(identity)));
+    renameSync(temporary,snapshotPath);syncDirectory(root);
+  };
+  try{
+    check(!existsSync(join(root,'recovery.lock')),'DESTINATION_RECOVERY_LOCKED');
+    const hasIdentity=existsSync(identityPath),hasSnapshot=existsSync(snapshotPath);
+    if(!hasIdentity&&!hasSnapshot){
+      check(before.length===0,'DESTINATION_INITIALIZATION_REFUSED');
+      // Persist the identity first: interruption may block availability, never silently reset history.
+      poisoned=true;createFile(identityPath,identityEnvelope(identity),65536);syncDirectory(root);
+      writeSnapshot(initialState);poisoned=false;
+    } else check(hasIdentity&&hasSnapshot,'DESTINATION_STATE_MISSING');
+    check(equal(readIdentity(identityPath),identity),'DESTINATION_IDENTITY_MISMATCH');
+    current=loadSnapshot(snapshotPath,identity);
+  }catch(error){if(!poisoned)release();throw error}
+  const active=()=>{check(!closed,'DESTINATION_STORE_CLOSED');check(!poisoned,'DESTINATION_STORE_UNCERTAIN');check(!busy,'DESTINATION_STORE_BUSY')};
+  const verify=()=>{
+    try{
+      assertOwnLock(lockPath,lock);check(equal(readIdentity(identityPath),identity),'DESTINATION_IDENTITY_MISMATCH');
+      const stored=loadSnapshot(snapshotPath,identity);
+      check(equal(stored,current),'DESTINATION_EXTERNAL_STATE_CHANGE');return stored;
+    }catch(error){poisoned=true;throw error}
+  };
+  return Object.freeze({
+    read(){active();return verify()},
+    transact(fn){
+      active();check(typeof fn==='function','DESTINATION_TRANSACTION_INVALID');
+      const previous=verify();busy=true;
+      try{
+        const answer=fn(structuredClone(previous));
+        check(!types.isPromise(answer),'DESTINATION_ASYNC_TRANSACTION');
+        const captured=capture(answer);
+        check(exact(captured,['state','result']),'DESTINATION_TRANSACTION_INVALID');
+        let next=validateState(captured.state,identity);monotonic(previous,next);
+        if(equal(previous,next))return Object.freeze({state:previous,result:captured.result});
+        check(previous.sequence<Number.MAX_SAFE_INTEGER,'DESTINATION_SEQUENCE_LIMIT');
+        next=validateState({...next,sequence:previous.sequence+1},identity);
+        try{writeSnapshot(next);current=next}catch(error){poisoned=true;throw Object.assign(new Error('DESTINATION_COMMIT_UNCERTAIN'),{code:'DESTINATION_COMMIT_UNCERTAIN',cause:error})}
+        return Object.freeze({state:current,result:captured.result});
+      }finally{busy=false}
+    },
+    close(){
+      if(closed)return;
+      check(!busy,'DESTINATION_STORE_BUSY');closed=true;
+      // An uncertain write requires explicit recovery after the owning process is gone.
+      if(!poisoned)release();
+    },
+  });
+}

package/dist/remote-tools/executor.mjs

@@ -0,0 +1,67 @@
+import {createHash} from 'node:crypto';
+import * as core from '@ramex-labs/continuity/adapter';
+import {PortableFileEventStore} from '@ramex-labs/continuity/adapter';
+import {openLocalExecution} from '@ramex-labs/continuity/adapter';
+import {record,identifier,requireCondition} from '@ramex-labs/continuity/adapter';
+
+/** Trusted application factory. Model arguments cannot select identity or client. */
+export function createCooperativeExecutor({local,client,registry,role,tenure}) {
+  requireCondition(local.additionalPolicy === undefined, "UNSUPPORTED_ADDITIONAL_POLICY");
+  const store=new PortableFileEventStore(local.historyFile);
+  const profile=core.approvedPortableAdapterProfileForPolicy(core.PORTABLE_ADAPTER_POLICY_E5_HASH,core.REMOTE_SERVICE_REPORT_ADAPTER_ID);
+  role=identifier(role);tenure=identifier(tenure);
+  const select=input=>{
+    const value=record(input,['operationId','businessKey','tool','arguments']);
+    const selected=registry.capture({intentId:identifier(value.operationId),businessKey:value.businessKey,
+      tool:value.tool,arguments:value.arguments,contractId:registry.contractId});
+    return {...selected,op:{id:selected.wire.intentId,action:selected.action,resource:selected.resource,role,tenure,termsCommitment:selected.termsCommitment,...selected.quantities}};
+  };
+  const retained=new Map();
+  const adapterFor=selected=>{
+    const unknown=i=>({status:'OUTCOME_UNKNOWN',idempotencyKey:i.idempotencyKey,submissionFingerprint:i.submissionFingerprint});
+    const convert=(reply,i,status)=>{
+      const report=reply.result;
+      if(report.state!=='APPLIED') {
+        requireCondition(report.key === undefined || report.key === i.idempotencyKey, "REPORT_MISMATCH");
+        retained.set(i.intentId,reply);
+        return unknown(i);
+      }
+      requireCondition(report.key===i.idempotencyKey&&report.fingerprint===i.submissionFingerprint&&report.intentId===i.intentId&&
+        report.tool===selected.wire.tool&&report.businessKey===selected.wire.businessKey&&report.contractId===registry.contractId,'REPORT_MISMATCH');
+      retained.set(i.intentId,reply);
+      const digest='0x'+createHash('sha256').update(core.canonicalEncode(report)).digest('hex');
+      const acknowledgment=core.createRemoteServiceReportAcknowledgment(i,digest);
+      const evidence=core.portableAdapterAcknowledgmentEvidence(i,acknowledgment);
+      return {status,idempotencyKey:i.idempotencyKey,submissionFingerprint:i.submissionFingerprint,
+        acknowledgment,...(status==='RETRY'?{retainedEvidence:evidence}:{evidence})};
+    };
+    return {adapterProfile:profile,
+      async submit(submission) {
+        const i=core.derivePortableAdapterIdentity(submission);
+        try {
+          const checkpoint=await client.checkpoint(store.readAll());
+          if(checkpoint.result.state!=='CHECKPOINTED')return unknown(i);
+          const prepared=await client.prepare(selected.wire);
+          if(prepared.result.state==='APPLIED')return convert(prepared,i,'RETRY');
+          if(prepared.result.state!=='PENDING')return convert(prepared,i,'RETRY');
+          return convert(await client.commit(i.idempotencyKey),i,'SUBMITTED');
+        } catch {return unknown(i);}
+      },
+      async reconcile(submission) {
+        const i=core.derivePortableAdapterIdentity(submission);
+        try {return convert(await client.status(i.idempotencyKey),i,'RETRY');}
+        catch {return unknown(i);}
+      },
+    };
+  };
+  return Object.freeze({
+    async run(input) {
+      const selected=select(input);
+      const execution=await openLocalExecution(local,adapterFor(selected),'REMOTE_REPORT').run(selected.op);
+      return Object.freeze({execution,serviceReport:retained.get(selected.wire.intentId)??null,
+        externalOutcome:'NOT_PROVEN',revocationBoundary:'DESTINATION_ACKNOWLEDGED_CHECKPOINT'});
+    },
+    // Publishing a checkpoint is an owner/application action, not an agent tool.
+    checkpoint(){return client.checkpoint(store.readAll());},
+  });
+}

package/dist/remote-tools/index.d.mts

@@ -0,0 +1,106 @@
+import type {KeyObject} from 'node:crypto';
+import type {PortableAuthorizationDomain, PortableCanonicalEvent, PortableHistoryHead, RemoteServiceReportAcknowledgment} from '@ramex-labs/continuity/adapter';
+import type {LocalExecutionOptions, openLocalExecution} from '@ramex-labs/continuity/adapter';
+
+export type Hash = `0x${string}`;
+export type Data = null | boolean | number | string | bigint | readonly Data[] | {readonly [key: string]: Data};
+export type Arguments = Readonly<Record<string, Data>>;
+export type Field = 'text' | 'integer' | 'boolean' | 'amount' | 'identifier' | readonly string[];
+export type ToolDefinition = Readonly<{id: string; action: string; resource: string; fields: Readonly<Record<string, Field>>;
+  projection?: Readonly<{amount?: string; counterparty?: string; unit?: string}>;
+  compensates?: Readonly<{tool: string; businessKeyField: string}>}>;
+export type Operation = Readonly<{intentId: string; tool: string; arguments: Arguments; businessKey: string; contractId: string}>;
+export type NormalizedOperation = Operation & Readonly<{idempotencyKey: Hash; submissionFingerprint: Hash}>;
+export type ReportIdentity = Readonly<{key: Hash; fingerprint: Hash; intentId: string; tool: string; businessKey: string; contractId: string; checkpointHash: Hash}>;
+export type PendingReport = ReportIdentity & Readonly<{state: 'PENDING'}>;
+export type CancelledReport = ReportIdentity & Readonly<{state: 'CANCELLED'}>;
+export type AppliedReport = ReportIdentity & Readonly<{state: 'APPLIED'; effectId: string}>;
+export type AttemptReport = PendingReport | CancelledReport | AppliedReport;
+export type RefusalCode = 'NO_CHECKPOINT' | 'CHECKPOINT_CONFLICT' | 'CHECKPOINT_CHANGED' | 'OPERATION_CONFLICT' |
+  'BUSINESS_KEY_CONFLICT' | 'AUTHORIZATION_REFUSED' | 'CLOCK_INVALID' | 'CAPACITY_EXHAUSTED' | 'INVALID_OPERATION' | 'STORAGE_UNAVAILABLE';
+export type Refusal = Readonly<{state: 'REFUSED'; code: RefusalCode}>;
+export type UnknownReport = Readonly<{state: 'UNKNOWN'; key: Hash}>;
+export type CheckpointReport = Readonly<{state: 'CHECKPOINTED'; head: PortableHistoryHead}>;
+export type TooLateReport = Readonly<{state: 'TOO_LATE'; report: AppliedReport}>;
+export type ServiceResult = AttemptReport | Refusal | UnknownReport | CheckpointReport | TooLateReport;
+export type SignedResponse<R extends ServiceResult = ServiceResult> = Readonly<{
+  body: Readonly<{version: 'continuity-cooperative-response/1'; serviceId: string; requestDigest: Hash; sequence: number; result: R}>;
+  signature: string;
+}>;
+export type CooperativeReply<R extends ServiceResult = ServiceResult> = Readonly<{sequence: number; result: R; receipt: SignedResponse<R>}>;
+
+export interface ToolRegistry {
+  readonly contractId: Hash;
+  readonly serviceId: string;
+  readonly account: string;
+  readonly tools: readonly ToolDefinition[];
+  capture(operation: Operation): Readonly<{wire: Operation; action: string; resource: string; termsCommitment: Hash; quantities: Readonly<{amount?: bigint; counterparty?: string}>}>;
+  validateOperation(events: readonly PortableCanonicalEvent[], operation: Operation, now: number, destinationState?: DestinationState): NormalizedOperation;
+}
+export declare const REFERENCE_TOOLS: readonly ToolDefinition[];
+export declare function createToolRegistry(options: Readonly<{serviceId: string; account: string; tools: readonly ToolDefinition[]}>): ToolRegistry;
+
+export interface CooperativeClient {
+  checkpoint(events: readonly PortableCanonicalEvent[]): Promise<CooperativeReply<CheckpointReport | Refusal>>;
+  prepare(operation: Operation): Promise<CooperativeReply<AttemptReport | Refusal>>;
+  commit(key: Hash): Promise<CooperativeReply<AttemptReport | UnknownReport | Refusal>>;
+  status(key: Hash): Promise<CooperativeReply<AttemptReport | UnknownReport | Refusal>>;
+  cancel(key: Hash): Promise<CooperativeReply<AttemptReport | UnknownReport | TooLateReport | Refusal>>;
+  inspectResponse(envelope: unknown, expectedRequestDigest: Hash): CooperativeReply;
+}
+/** Trusted application keys and pinned destination; never expose this whole handle to an agent. */
+export declare function createCooperativeClient(options: Readonly<{
+  url: string; serviceId: string; coordinatorPrivateKey: KeyObject; servicePublicKey: KeyObject; timeoutMs?: number;
+}>): CooperativeClient;
+
+export type StoredAttempt = Readonly<{
+  key: Hash; fingerprint: Hash; intentId: string; operation: Operation; normalized: NormalizedOperation;
+  checkpointHead: PortableHistoryHead; preparedAt: number; report: AttemptReport;
+}>;
+export type DestinationState = Readonly<{
+  version: 'continuity-cooperative-destination/1'; domain: PortableAuthorizationDomain; serviceId: string;
+  coordinatorKey: Hash; serviceKey: Hash; sequence: number; lastTime: number;
+  checkpoint: null | Readonly<{head: PortableHistoryHead; events: readonly PortableCanonicalEvent[]}>;
+  attempts: readonly StoredAttempt[];
+  businessKeys: readonly Readonly<{businessKey: string; key: Hash; intentId: string}>[];
+  effects: readonly Readonly<{effectId: string; key: Hash; fingerprint: Hash; tool: string; arguments: Arguments; businessKey: string; contractId: string}>[];
+}>;
+export interface CooperativeDestination {
+  readonly url: string;
+  inspect(): DestinationState;
+  close(): Promise<void>;
+}
+/** Local synthetic destination: no real external effect or arbitrary execution callback. */
+export declare function createCooperativeDestination(options: Readonly<{
+  directory: string; domain: PortableAuthorizationDomain; serviceId: string;
+  coordinatorPublicKey: KeyObject; servicePrivateKey: KeyObject; now: () => number;
+  validateOperation: (events: readonly PortableCanonicalEvent[], operation: Operation, now: number, destinationState?: DestinationState) => NormalizedOperation;
+}>): Promise<CooperativeDestination>;
+
+export type ToolRequest = Readonly<{operationId: string; businessKey: string; tool: string; arguments: Arguments}>;
+export type ExecutionResult = Awaited<ReturnType<ReturnType<typeof openLocalExecution>['run']>>;
+export type CooperativeExecutionResult = Readonly<{
+  execution: ExecutionResult;
+  serviceReport: CooperativeReply | null;
+  externalOutcome: 'NOT_PROVEN';
+  revocationBoundary: 'DESTINATION_ACKNOWLEDGED_CHECKPOINT';
+}>;
+export interface CooperativeExecutor {
+  run(request: ToolRequest): Promise<CooperativeExecutionResult>;
+  checkpoint(): Promise<CooperativeReply<CheckpointReport | Refusal>>;
+}
+/** Root-selected local identity and policy; request data cannot choose them. */
+export declare function createCooperativeExecutor(options: Readonly<{
+  local: Omit<LocalExecutionOptions, 'additionalPolicy'> & Readonly<{additionalPolicy?: never}>;
+  client: CooperativeClient; registry: ToolRegistry; role: string; tenure: string;
+}>): CooperativeExecutor;
+
+export type RecoveryResult = Readonly<{serviceReport: CooperativeReply; observationAcknowledgment: RemoteServiceReportAcknowledgment | null; externalOutcome: 'NOT_PROVEN';
+  dispatchPerformed: false; retryPolicy: 'NO_AUTOMATIC_REDELIVERY'}>;
+export interface CooperativeRecovery {lookup(request: ToolRequest): Promise<RecoveryResult>; cancel(request: ToolRequest): Promise<RecoveryResult>}
+export declare function createCooperativeRecovery(options: Readonly<{local: Pick<LocalExecutionOptions,'historyFile'|'domain'>;
+  client: CooperativeClient; registry: ToolRegistry}>): CooperativeRecovery;
+export type DestinationLock = Readonly<{version: 'continuity-destination-lock/1'; hostname: string; pid: number; instance: string}>;
+export declare function inspectDestinationLock(options: Readonly<{directory: string}>): DestinationLock;
+export declare function recoverDestinationLock(options: Readonly<{directory: string; expectedLock: DestinationLock}>):
+  Readonly<{recovered: true; retainedLock: string; lock: DestinationLock}>;

package/dist/remote-tools/index.mjs

@@ -0,0 +1,7 @@
+export {createToolRegistry, REFERENCE_TOOLS} from './validation.mjs';
+export {createCooperativeClient} from './client.mjs';
+export {createCooperativeDestination} from './destination.mjs';
+export {createCooperativeExecutor} from './executor.mjs';
+
+export {createCooperativeRecovery} from './recovery.mjs';
+export {inspectDestinationLock,recoverDestinationLock} from './durable-store.mjs';

package/dist/remote-tools/langchain.d.mts

@@ -0,0 +1,7 @@
+import type {DynamicStructuredTool} from '@langchain/core/tools';
+import type {ToolRegistry,CooperativeExecutor} from './index.mjs';
+/** The application fixes identity. Only the configured arguments become model input. */
+export declare function createContinuityTool(options: Readonly<{registry: ToolRegistry; executor: CooperativeExecutor;
+  tool: string; operationId: string; businessKey: string; name?: string}>): DynamicStructuredTool;
+export declare function createContinuityTools(options: Readonly<{registry: ToolRegistry; executor: CooperativeExecutor;
+  operations: readonly Readonly<{tool: string; operationId: string; businessKey: string; name?: string}>[]}>): readonly DynamicStructuredTool[];