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

package/dist/remote-tools/langchain.mjs

@@ -0,0 +1,62 @@
+import {DynamicStructuredTool} from '@langchain/core/tools';
+import * as z from 'zod';
+import {identifier,record,requireCondition} from '@ramex-labs/continuity/adapter';
+
+const decimalPattern=/^(0|[1-9][0-9]{0,77})$/;
+const decimalAmount=z.string().regex(decimalPattern,'Use whole units as decimal text, without signs, fractions, exponents or separators.')
+  .refine(value=>!decimalPattern.test(value)||BigInt(value)<(1n<<256n),
+    'Amount must be at most 2^256 - 1 whole units.')
+  .describe('Whole units as decimal text; no sign, fraction, exponent or separators.');
+const controlFree=/^[^\u0000-\u001f\u007f]+$/;
+const textField=z.string().min(1).max(1024).regex(controlFree,'Text cannot contain control characters.');
+const identifierField=z.string().min(1).max(128).regex(controlFree,'Identifiers cannot contain control characters.');
+const integerField=z.number().int().min(0).max(Number.MAX_SAFE_INTEGER)
+  .refine(value=>!Object.is(value,-0),'Use zero rather than negative zero.');
+
+/** One application-owned business operation, exposed as an ordinary LangChain tool. */
+export function createContinuityTool(options) {
+  const {registry,executor}=options;
+  const settings=record({tool:options.tool,operationId:options.operationId,businessKey:options.businessKey,
+    ...(Object.hasOwn(options,'name')?{name:options.name}:{})},['tool','operationId','businessKey'],['name']);
+  for(const name of ['tool','operationId','businessKey'])identifier(settings[name]);
+  const definition=registry.tools.find(x=>x.id===settings.tool);
+  requireCondition(definition,'UNKNOWN_TOOL');
+  requireCondition(typeof executor.run==='function','INVALID_CONFIGURATION');
+  const name=Object.hasOwn(settings,'name')?settings.name:definition.id.replaceAll('.','_');
+  requireCondition(typeof name==='string'&&/^[A-Za-z0-9_-]{1,64}$/.test(name),'INVALID_TOOL_NAME');
+  const fields={};
+  for(const [name,type] of Object.entries(definition.fields)) {
+    fields[name]=Array.isArray(type)?z.enum(type):type==='text'?textField:
+      type==='identifier'?identifierField:type==='integer'?integerField:
+      type==='boolean'?z.boolean():decimalAmount;
+  }
+  return new DynamicStructuredTool({
+    name,
+    description:`Request ${definition.id} for one application-assigned business operation. Refusal or uncertainty does not permit a new operation ID. Report the returned status; it is not proof of an outside outcome.`,
+    schema:z.object(fields).strict(),
+    async func(input) {
+      const args={...input};
+      // JSON tool calls carry exact decimal text. Conversion is explicit here;
+      // the core/destination API still accepts only a bounded bigint amount.
+      for(const [name,type] of Object.entries(definition.fields))if(type==='amount')args[name]=BigInt(args[name]);
+      const result=await executor.run({operationId:settings.operationId,businessKey:settings.businessKey,tool:settings.tool,arguments:args});
+      return JSON.stringify({operationId:settings.operationId,status:result.execution.status,
+        lastReportedServiceState:result.serviceReport?.result.state??'REPORT_UNAVAILABLE',
+        invocation:result.execution.invocation?.status??result.execution.result?.status??null,
+        externalOutcome:result.externalOutcome,revocationBoundary:result.revocationBoundary});
+    },
+  });
+}
+
+/** Build one host-selected tool list, refusing ambiguous framework names. */
+export function createContinuityTools(options) {
+  const {registry,executor}=options;
+  const {operations}=record({operations:options.operations},['operations']);
+  requireCondition(Array.isArray(operations)&&operations.length>0&&operations.length<=32,'INVALID_TOOL_OPERATIONS');
+  const tools=operations.map(value=>{
+    const operation=record(value,['tool','operationId','businessKey'],['name']);
+    return createContinuityTool({registry,executor,...operation});
+  });
+  requireCondition(new Set(tools.map(tool=>tool.name)).size===tools.length,'DUPLICATE_TOOL_NAME');
+  return Object.freeze(tools);
+}

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

@@ -0,0 +1 @@
+export * from '@ramex-labs/continuity/local';

package/dist/remote-tools/local.mjs

@@ -0,0 +1 @@
+export * from '@ramex-labs/continuity/local';

package/dist/remote-tools/recovery.mjs

@@ -0,0 +1,40 @@
+import {createHash} from 'node:crypto';
+import * as core from '@ramex-labs/continuity/adapter';
+import {PortableFileEventStore} from '@ramex-labs/continuity/adapter';
+import {stateOf} from '@ramex-labs/continuity/adapter';
+import {record,requireCondition} from '@ramex-labs/continuity/adapter';
+
+/** Application-owned recovery. Neither method dispatches or re-prepares work. */
+export function createCooperativeRecovery({local,client,registry}) {
+  const store=new PortableFileEventStore(local.historyFile);
+  const select=input=>{
+    const value=record(input,['operationId','businessKey','tool','arguments']);
+    const selected=registry.capture({intentId:value.operationId,businessKey:value.businessKey,
+      tool:value.tool,arguments:value.arguments,contractId:registry.contractId});
+    const state=stateOf(store.readAll());
+    requireCondition(core.canonicalEncode(state.genesis.domain)===core.canonicalEncode(local.domain),'DOMAIN_MISMATCH');
+    const admission=state.intentAdmissions.get(value.operationId),intent=state.intentDeclarations.get(value.operationId)?.data;
+    requireCondition(admission&&intent,'ADMISSION_REQUIRED');
+    requireCondition(intent.action===selected.action&&intent.resource===selected.resource&&intent.termsCommitment===selected.termsCommitment,'OPERATION_CONFLICT');
+    requireCondition(intent.amount===selected.quantities.amount&&intent.counterpartyId===selected.quantities.counterparty,'OPERATION_CONFLICT');
+    return {selected,identity:admission.adapterIdentity};
+  };
+  const bind=(reply,{selected,identity})=>{
+    let report=reply.result;
+    if(report.state==='TOO_LATE')report=report.report;
+    requireCondition(report.key===identity.idempotencyKey,'REPORT_MISMATCH');
+    if(['APPLIED','CANCELLED','PENDING'].includes(report.state)) {
+      requireCondition(report.fingerprint===identity.submissionFingerprint&&report.intentId===selected.wire.intentId&&
+        report.tool===selected.wire.tool&&report.businessKey===selected.wire.businessKey&&report.contractId===registry.contractId,'REPORT_MISMATCH');
+    } else requireCondition(report.state==='UNKNOWN','REPORT_UNAVAILABLE');
+    const observationAcknowledgment=report.state==='APPLIED'
+      ?core.createRemoteServiceReportAcknowledgment(identity,'0x'+createHash('sha256').update(core.canonicalEncode(report)).digest('hex')):null;
+    return Object.freeze({serviceReport:reply,observationAcknowledgment,externalOutcome:'NOT_PROVEN',
+      dispatchPerformed:false,retryPolicy:'NO_AUTOMATIC_REDELIVERY'});
+  };
+  return Object.freeze({
+    async lookup(input){const selected=select(input);return bind(await client.status(selected.identity.idempotencyKey),selected);},
+    // Coordinator privilege: expose this only to the application's operator.
+    async cancel(input){const selected=select(input);return bind(await client.cancel(selected.identity.idempotencyKey),selected);},
+  });
+}

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

@@ -0,0 +1 @@
+export * from '@ramex-labs/continuity/runtime';

package/dist/remote-tools/runtime.mjs

@@ -0,0 +1 @@
+export * from '@ramex-labs/continuity/runtime';

package/dist/remote-tools/strict-json.mjs

@@ -0,0 +1,136 @@
+// Validate raw JSON before the SDK parser can discard duplicate decoded keys.
+// The explicit stack also makes deeply nested, bounded input independent of the JS call stack.
+export class StrictJsonError extends Error {
+  constructor(code) {
+    super(code);
+    this.name = "StrictJsonError";
+    this.code = code;
+  }
+}
+
+export function parseStrictJson(
+  bytes,
+  { maxBytes = 2 * 1024 * 1024, maxDepth = 64, maxNodes = 100000 } = {},
+) {
+  if (bytes.byteLength > maxBytes)
+    throw new StrictJsonError("JSON_BYTES_EXCEEDED");
+  let source;
+  try {
+    source = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(
+      bytes,
+    );
+  } catch {
+    throw new StrictJsonError("INVALID_UTF8");
+  }
+  let at = 0;
+  const stack = [];
+  let nodes = 0;
+  const bad = () => {
+    throw new StrictJsonError("INVALID_JSON");
+  };
+  const space = () => {
+    while (/[\x20\t\r\n]/.test(source[at] ?? "\0")) at++;
+  };
+  const string = () => {
+    const start = at++;
+    while (at < source.length) {
+      const c = source.charCodeAt(at++);
+      if (c === 34) {
+        try {
+          return JSON.parse(source.slice(start, at));
+        } catch {
+          bad();
+        }
+      }
+      if (c < 32) bad();
+      if (c === 92) {
+        const escape = source[at++];
+        if (escape === "u") {
+          if (!/^[0-9a-fA-F]{4}$/.test(source.slice(at, at + 4))) bad();
+          at += 4;
+        } else if (!['"', "\\", "/", "b", "f", "n", "r", "t"].includes(escape))
+          bad();
+      }
+    }
+    bad();
+  };
+  const value = () => {
+    if (++nodes > maxNodes) throw new StrictJsonError("JSON_NODES_EXCEEDED");
+    space();
+    const c = source[at];
+    if (c === "{") {
+      at++;
+      stack.push({ kind: "object", state: "keyOrEnd", keys: new Set() });
+    } else if (c === "[") {
+      at++;
+      stack.push({ kind: "array", state: "valueOrEnd" });
+    } else if (c === '"') string();
+    else {
+      const token =
+        /^(?:true|false|null|-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?)/.exec(
+          source.slice(at),
+        );
+      if (!token) bad();
+      at += token[0].length;
+    }
+    if (stack.length > maxDepth)
+      throw new StrictJsonError("JSON_DEPTH_EXCEEDED");
+  };
+  value();
+  while (stack.length) {
+    space();
+    const frame = stack.at(-1),
+      c = source[at];
+    if (frame.kind === "object") {
+      if (frame.state === "keyOrEnd" && c === "}") {
+        at++;
+        stack.pop();
+      } else if (frame.state === "key" || frame.state === "keyOrEnd") {
+        if (c !== '"') bad();
+        const key = string();
+        if (frame.keys.has(key)) throw new StrictJsonError("DUPLICATE_KEY");
+        frame.keys.add(key);
+        frame.state = "colon";
+      } else if (frame.state === "colon") {
+        if (c !== ":") bad();
+        at++;
+        frame.state = "value";
+      } else if (frame.state === "value") {
+        frame.state = "commaOrEnd";
+        value();
+      } else if (c === "}") {
+        at++;
+        stack.pop();
+      } else if (c === ",") {
+        at++;
+        frame.state = "key";
+      } else bad();
+    } else {
+      if (frame.state === "valueOrEnd" && c === "]") {
+        at++;
+        stack.pop();
+      } else if (frame.state === "value" || frame.state === "valueOrEnd") {
+        frame.state = "commaOrEnd";
+        value();
+      } else if (c === "]") {
+        at++;
+        stack.pop();
+      } else if (c === ",") {
+        at++;
+        frame.state = "value";
+      } else bad();
+    }
+  }
+  space();
+  if (at !== source.length) bad();
+  try {
+    return JSON.parse(source, (_key, item) => {
+      if (typeof item === "number" && !Number.isFinite(item))
+        throw new StrictJsonError("INVALID_JSON_NUMBER");
+      return item;
+    });
+  } catch (error) {
+    if (error instanceof StrictJsonError) throw error;
+    bad();
+  }
+}

package/dist/remote-tools/validation.mjs

@@ -0,0 +1,96 @@
+import * as core from '@ramex-labs/continuity/adapter';
+import {stateOf} from '@ramex-labs/continuity/adapter';
+import {portableAdmissionControlIsCurrent} from '@ramex-labs/continuity/adapter';
+import {evaluatePortableReceiptPolicy} from '@ramex-labs/continuity/adapter';
+import {captureData,record,identifier,requireCondition} from '@ramex-labs/continuity/adapter';
+
+export const REFERENCE_TOOLS = Object.freeze([
+  {id:'ticket.create',action:'create-ticket',resource:'queue:security',fields:{title:'text'}},
+  {id:'document.access',action:'set-access',resource:'document:synthetic',fields:{level:['closed','reviewer']}},
+  {id:'document.read',action:'read-document',resource:'document:synthetic',fields:{}},
+  {id:'incident.note',action:'record-note',resource:'case:incident',fields:{note:'text'}},
+]);
+const equal=(a,b)=>core.canonicalEncode(a)===core.canonicalEncode(b);
+
+/** Application-selected contracts; no model-generated schema or resolver code. */
+export function createToolRegistry(input) {
+  const config=record(input,['serviceId','account','tools']);
+  const serviceId=identifier(config.serviceId),account=identifier(config.account);
+  requireCondition(Array.isArray(config.tools)&&config.tools.length>0&&config.tools.length<=32);
+  const definitions=config.tools.map(value=>{
+    const tool=record(value,['id','action','resource','fields'],['projection','compensates']);
+    const fields=captureData(tool.fields);
+    requireCondition(fields!==null&&typeof fields==='object'&&!Array.isArray(fields)&&Object.keys(fields).length<=16);
+    for(const [name,type] of Object.entries(fields)) {
+      identifier(name);
+      requireCondition(['text','integer','boolean','amount','identifier'].includes(type)||(Array.isArray(type)&&type.length>0&&type.length<=16&&type.every(x=>typeof x==='string'&&x.length<=128)));
+    }
+    let projection,compensates;
+    if(Object.hasOwn(tool,'projection')) {
+      projection=record(tool.projection,[],['amount','counterparty','unit']);
+      requireCondition(Object.hasOwn(projection,'amount')||Object.hasOwn(projection,'counterparty'));
+      if(Object.hasOwn(projection,'amount')) {
+        requireCondition(fields[identifier(projection.amount)]==='amount'&&Object.hasOwn(projection,'unit'));
+        identifier(projection.unit);
+      } else requireCondition(!Object.hasOwn(projection,'unit'));
+      if(Object.hasOwn(projection,'counterparty'))requireCondition(fields[identifier(projection.counterparty)]==='identifier');
+    }
+    if(Object.hasOwn(tool,'compensates')) {
+      compensates=record(tool.compensates,['tool','businessKeyField']);
+      identifier(compensates.tool);requireCondition(fields[identifier(compensates.businessKeyField)]==='identifier');
+    }
+    return {id:identifier(tool.id),action:identifier(tool.action),resource:identifier(tool.resource),fields,
+      ...(projection?{projection}:{}),...(compensates?{compensates}:{})};
+  });
+  requireCondition(new Set(definitions.map(x=>x.id)).size===definitions.length);
+  requireCondition(new Set(definitions.filter(x=>x.projection?.amount).map(x=>x.projection.unit)).size<=1,'MIXED_AMOUNT_UNITS');
+  for(const tool of definitions)if(tool.compensates)requireCondition(definitions.some(x=>x.id===tool.compensates.tool&&!x.compensates),'INVALID_COMPENSATION');
+  const contractId=core.hashCanonical({version:'continuity-tool-contract/1',serviceId,account,tools:definitions});
+  const capture=(input)=>{
+    const operation=record(input,['intentId','tool','arguments','businessKey','contractId']);
+    const intentId=identifier(operation.intentId),toolId=identifier(operation.tool),businessKey=identifier(operation.businessKey);
+    requireCondition(operation.contractId===contractId,'CONTRACT_MISMATCH');
+    const tool=definitions.find(x=>x.id===toolId);requireCondition(tool,'UNKNOWN_TOOL');
+    const args=record(operation.arguments,Object.keys(tool.fields));
+    for(const [field,type] of Object.entries(tool.fields)) {
+      const value=args[field];
+      if(Array.isArray(type))requireCondition(type.includes(value));
+      else if(type==='text')requireCondition(typeof value==='string'&&value.length>0&&value.length<=1024&&!/[\u0000-\u001f\u007f]/.test(value));
+      else if(type==='amount')requireCondition(typeof value==='bigint'&&value>=0n&&value<(1n<<256n));
+      else if(type==='identifier')identifier(value);
+      else if(type==='integer')requireCondition(Number.isSafeInteger(value)&&value>=0&&!Object.is(value,-0));
+      else requireCondition(typeof value==='boolean');
+    }
+    const wire=core.immutableProtocolValue({intentId,tool:toolId,arguments:args,businessKey,contractId});
+    const termsCommitment=core.hashCanonical({version:'continuity-tool-terms/1',serviceId,account,tool:toolId,arguments:args,businessKey,contractId});
+    const quantities={...(tool.projection?.amount?{amount:args[tool.projection.amount]}:{}),
+      ...(tool.projection?.counterparty?{counterparty:args[tool.projection.counterparty]}:{})};
+    return {wire,action:tool.action,resource:tool.resource,termsCommitment,quantities};
+  };
+  return Object.freeze({contractId,serviceId,account,tools:core.immutableProtocolValue(definitions),capture,
+    validateOperation(events,input,now,destinationState) {
+      requireCondition(Number.isSafeInteger(now)&&now>=0&&!Object.is(now,-0));
+      const selected=capture(input),state=stateOf(events);
+      requireCondition(now>=state.head.canonicalTime,'CLOCK_REGRESSION');
+      const admission=state.intentAdmissions.get(selected.wire.intentId),intent=state.intentDeclarations.get(selected.wire.intentId)?.data;
+      requireCondition(admission&&intent&&intent.adapterProfile.profileId===core.REMOTE_SERVICE_REPORT_ADAPTER_ID,'ADMISSION_REQUIRED');
+      requireCondition(portableAdmissionControlIsCurrent(state,intent.intentId,now),'RUNTIME_NOT_CURRENT');
+      requireCondition(!state.intentOutcomeStates.get(intent.intentId)?.terminal,'TERMINAL_INTENT');
+      requireCondition(intent.action===selected.action&&intent.resource===selected.resource&&intent.termsCommitment===selected.termsCommitment,'INTENT_MISMATCH');
+      requireCondition(Object.hasOwn(intent,'amount')===Object.hasOwn(selected.quantities,'amount')&&intent.amount===selected.quantities.amount&&
+        Object.hasOwn(intent,'counterpartyId')===Object.hasOwn(selected.quantities,'counterparty')&&intent.counterpartyId===selected.quantities.counterparty,'PROJECTION_MISMATCH');
+      const tool=definitions.find(x=>x.id===selected.wire.tool);
+      if(tool.compensates) {
+        requireCondition(destinationState?.serviceId===serviceId,'COMPENSATION_SOURCE_REQUIRED');
+        const original=destinationState.attempts.find(x=>x.operation.businessKey===selected.wire.arguments[tool.compensates.businessKeyField]);
+        requireCondition(original&&original.report.state==='APPLIED'&&original.operation.tool===tool.compensates.tool&&
+          original.operation.contractId===contractId,'COMPENSATION_SOURCE_REQUIRED');
+      }
+      const proof=state.events[admission.admissionEventPosition].data.authorizationProof;
+      requireCondition(proof.recognizedRoot.principalId===state.roles.get(intent.roleId).principalId,'WRONG_PRINCIPAL');
+      requireCondition(evaluatePortableReceiptPolicy(state,proof,now).live,'POLICY_NOT_LIVE');
+      return core.immutableProtocolValue({...selected.wire,idempotencyKey:admission.adapterIdentity.idempotencyKey,
+        submissionFingerprint:admission.adapterIdentity.submissionFingerprint});
+    },
+  });
+}

package/dist/remote-tools/wire.mjs

@@ -0,0 +1,150 @@
+import { createHash, createPublicKey, sign, verify } from 'node:crypto';
+import { captureData } from '@ramex-labs/continuity/adapter';
+import { canonicalEncode } from '@ramex-labs/continuity/adapter';
+import { parseStrictJson } from './strict-json.mjs';
+
+export const MAX_WIRE_BYTES = 16 * 1024 * 1024;
+const MAX_DATA_BYTES = 8 * 1024 * 1024;
+const fail = code => { throw Object.assign(new Error(code), {code}); };
+export const capture = value => captureData(value, MAX_DATA_BYTES, 300000, 96);
+export function exact(value, keys) {
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+      Object.keys(value).length !== keys.length || keys.some(key => !Object.hasOwn(value,key))) fail('INVALID_SHAPE');
+  return value;
+}
+export function textId(value) {
+  if (typeof value !== 'string' || !value || value.length > 256 || /[\u0000-\u001f\u007f]/.test(value)) fail('INVALID_IDENTIFIER');
+  return value;
+}
+export function hashId(value) {
+  if (typeof value !== 'string' || !/^0x[0-9a-f]{64}$/.test(value)) fail('INVALID_HASH');
+  return value;
+}
+export function integer(value) {
+  if (!Number.isSafeInteger(value) || value < 0 || Object.is(value,-0)) fail('INVALID_INTEGER');
+  return value;
+}
+export const canonicalDigest = value => '0x'+createHash('sha256').update(canonicalEncode(capture(value))).digest('hex');
+
+// Every node is tagged, so an ordinary object resembling a bigint marker
+// cannot become an integer during decoding. Object keys are sorted uniquely.
+export function encodeTransport(value) {
+  const stable = capture(value);
+  const encode = node => {
+    if (node === null) return ['null'];
+    if (typeof node === 'bigint') return ['bigint',node.toString()];
+    if (Array.isArray(node)) return ['array',node.map(encode)];
+    if (typeof node === 'object') return ['object',Object.keys(node).sort().map(key => [key,encode(node[key])])];
+    if (['string','number','boolean'].includes(typeof node)) return [typeof node,node];
+    fail('INVALID_TRANSPORT_VALUE');
+  };
+  const bytes = Buffer.from(JSON.stringify(encode(stable)));
+  if (bytes.length > MAX_WIRE_BYTES) fail('WIRE_LIMIT');
+  return bytes;
+}
+export function decodeTransport(bytes) {
+  if (!(bytes instanceof Uint8Array)) fail('INVALID_TRANSPORT');
+  const encoded = parseStrictJson(bytes,{maxBytes:MAX_WIRE_BYTES,maxDepth:256,maxNodes:1200000});
+  let nodes=0;
+  const decode = (node,depth=0) => {
+    if (++nodes>300000 || depth>96 || !Array.isArray(node)) fail('TRANSPORT_LIMIT');
+    if (node[0]==='null' && node.length===1) return null;
+    if (node.length!==2) fail('INVALID_TRANSPORT');
+    const [tag,value]=node;
+    if (tag==='string' && typeof value==='string') return value;
+    if (tag==='boolean' && typeof value==='boolean') return value;
+    if (tag==='number' && typeof value==='number' && Number.isSafeInteger(value) && !Object.is(value,-0)) return value;
+    if (tag==='bigint' && typeof value==='string' && /^(0|[1-9][0-9]{0,77})$/.test(value)) {
+      const number=BigInt(value); if(number >= (1n<<256n)) fail('INVALID_BIGINT'); return number;
+    }
+    if (tag==='array' && Array.isArray(value)) return value.map(item=>decode(item,depth+1));
+    if (tag==='object' && Array.isArray(value)) {
+      const result=Object.create(null); let previous;
+      for (const entry of value) {
+        if (!Array.isArray(entry)||entry.length!==2||typeof entry[0]!=='string'||
+            (previous!==undefined && previous>=entry[0])) fail('INVALID_TRANSPORT_OBJECT');
+        previous=entry[0]; Object.defineProperty(result,entry[0],{value:decode(entry[1],depth+1),enumerable:true});
+      }
+      return result;
+    }
+    fail('INVALID_TRANSPORT');
+  };
+  return capture(decode(encoded));
+}
+export function publicKeyIdentity(key) {
+  const publicKey=key?.type==='public'?key:createPublicKey(key);
+  if(publicKey.asymmetricKeyType!=='ed25519') fail('UNSUPPORTED_KEY');
+  return '0x'+createHash('sha256').update(publicKey.export({type:'spki',format:'der'})).digest('hex');
+}
+const assertKey = (key,privateRequired=false) => {
+  if(key?.asymmetricKeyType!=='ed25519'||(privateRequired&&key.type!=='private')) fail('UNSUPPORTED_KEY');
+};
+export function validateOperationShape(value) {
+  exact(value,['intentId','tool','arguments','businessKey','contractId']);
+  for(const key of ['intentId','tool','businessKey','contractId']) textId(value[key]);
+  if(!value.arguments||typeof value.arguments!=='object'||Array.isArray(value.arguments)) fail('INVALID_ARGUMENTS');
+  return value;
+}
+function requestBody(body) {
+  exact(body,['version','serviceId','nonce','operation','payload']);
+  if(body.version!=='continuity-cooperative-request/1'||typeof body.nonce!=='string'||! /^[0-9a-f]{64}$/.test(body.nonce)) fail('INVALID_REQUEST');
+  textId(body.serviceId);
+  switch(body.operation) {
+    case 'checkpoint': exact(body.payload,['events']); if(!Array.isArray(body.payload.events)||body.payload.events.length<1||body.payload.events.length>256)fail('INVALID_HISTORY'); break;
+    case 'prepare': exact(body.payload,['operation']); validateOperationShape(body.payload.operation); break;
+    case 'commit': case 'status': case 'cancel': exact(body.payload,['key']);hashId(body.payload.key);break;
+    default: fail('UNSUPPORTED_OPERATION');
+  }
+  return body;
+}
+export function validateReport(report) {
+  const fields=['state','key','fingerprint','intentId','tool','businessKey','contractId','checkpointHash'];
+  if(report?.state==='APPLIED') fields.push('effectId');
+  exact(report,fields);
+  if(!['PENDING','APPLIED','CANCELLED'].includes(report.state))fail('INVALID_REPORT');
+  for(const key of ['key','fingerprint','checkpointHash'])hashId(report[key]);
+  for(const key of ['intentId','tool','businessKey','contractId'])textId(report[key]);
+  if(report.state==='APPLIED')textId(report.effectId);
+  return report;
+}
+function responseBody(body) {
+  exact(body,['version','serviceId','requestDigest','sequence','result']);
+  if(body.version!=='continuity-cooperative-response/1') fail('INVALID_RESPONSE');
+  textId(body.serviceId);hashId(body.requestDigest);integer(body.sequence);
+  const result=body.result;
+  if(result?.state==='CHECKPOINTED') {
+    exact(result,['state','head']);exact(result.head,['hash','position','canonicalTime']);
+    hashId(result.head.hash);integer(result.head.position);integer(result.head.canonicalTime);
+  } else if(result?.state==='UNKNOWN') {exact(result,['state','key']);hashId(result.key);}
+  else if(result?.state==='TOO_LATE') {exact(result,['state','report']);validateReport(result.report);if(result.report.state!=='APPLIED')fail('INVALID_REPORT');}
+  else if(result?.state==='REFUSED') {
+    exact(result,['state','code']);
+    if(!['NO_CHECKPOINT','CHECKPOINT_CONFLICT','CHECKPOINT_CHANGED','OPERATION_CONFLICT','BUSINESS_KEY_CONFLICT',
+      'AUTHORIZATION_REFUSED','CLOCK_INVALID','CAPACITY_EXHAUSTED','INVALID_OPERATION','STORAGE_UNAVAILABLE'].includes(result.code))fail('INVALID_REFUSAL');
+  } else validateReport(result);
+  return body;
+}
+const signingBytes=(kind,body)=>Buffer.from(`continuity-cooperative-${kind}-signature/1\n${canonicalEncode(body)}`);
+function signed(kind,body,key,validate) {
+  assertKey(key,true);const stable=capture(body);validate(stable);
+  return capture({body:stable,signature:sign(null,signingBytes(kind,stable),key).toString('hex')});
+}
+function verified(kind,envelope,key,validate) {
+  assertKey(key);const stable=capture(envelope);exact(stable,['body','signature']);validate(stable.body);
+  if(typeof stable.signature!=='string'||! /^[0-9a-f]{128}$/.test(stable.signature)||
+      !verify(null,signingBytes(kind,stable.body),key,Buffer.from(stable.signature,'hex')))fail('INVALID_SIGNATURE');
+  return stable.body;
+}
+export const signRequest=(body,key)=>signed('request',body,key,requestBody);
+export const signResponse=(body,key)=>signed('response',body,key,responseBody);
+export function verifyRequest(envelope,key,{serviceId}={}) {
+  const body=verified('request',envelope,key,requestBody);
+  if(serviceId!==undefined&&body.serviceId!==serviceId)fail('SERVICE_MISMATCH');
+  return body;
+}
+export function verifyResponse(envelope,key,{serviceId,requestDigest}={}) {
+  const body=verified('response',envelope,key,responseBody);
+  if(serviceId!==undefined&&body.serviceId!==serviceId)fail('SERVICE_MISMATCH');
+  if(requestDigest!==undefined&&body.requestDigest!==requestDigest)fail('REQUEST_MISMATCH');
+  return body;
+}

package/examples/native-consumer.mjs

@@ -0,0 +1,44 @@
+import assert from 'node:assert/strict';
+import {mkdtempSync,mkdirSync,realpathSync,rmSync} from 'node:fs';
+import {tmpdir} from 'node:os';
+import {join} from 'node:path';
+import {generateKeyPairSync} from 'node:crypto';
+import {generatePrivateKey,privateKeyToAccount} from 'viem/accounts';
+import {createToolRegistry,createCooperativeDestination,createCooperativeClient,createCooperativeExecutor,createCooperativeRecovery} from '@ramex-labs/continuity-remote';
+import {createContinuityTools} from '@ramex-labs/continuity-remote/langchain';
+import {createLocalDomain,createLocalAttemptOwner} from '@ramex-labs/continuity-remote/local';
+
+const dir=realpathSync(mkdtempSync(join(tmpdir(),'continuity-native-')));
+let destination;
+try {
+  const amount=9007199254740993n,account=privateKeyToAccount(generatePrivateKey());
+  const local={historyFile:join(dir,'history.jsonl'),domain:createLocalDomain(),owner:'operations',controller:'app',now:()=>100,
+    session:'session:bea',signHash:hash=>account.signMessage({message:{raw:hash}})};
+  const owner=createLocalAttemptOwner(local);owner.createAgent({id:'bea'});owner.createRole({id:'operator'});
+  owner.appoint({agent:'bea',role:'operator',tenure:'shift:1',number:1});
+  owner.admitRuntime({agent:'bea',session:local.session,epoch:1,key:'key:bea',address:account.address,expiresAt:1000});
+  owner.grant({id:'budget',to:'bea',actions:['allocate'],resources:['credits:example'],expiresAt:500,
+    maxAmount:amount,maxCumulativeAmount:amount,maxTransactions:1});
+  const registry=createToolRegistry({serviceId:'native-example',account:'synthetic',tools:[{
+    id:'credits.allocate',action:'allocate',resource:'credits:example',fields:{units:'amount',recipient:'identifier'},
+    projection:{amount:'units',counterparty:'recipient',unit:'credits'},
+  }]});
+  const coordinator=generateKeyPairSync('ed25519'),provider=generateKeyPairSync('ed25519');
+  mkdirSync(join(dir,'destination'),{mode:0o700});
+  destination=await createCooperativeDestination({directory:join(dir,'destination'),domain:local.domain,serviceId:registry.serviceId,
+    coordinatorPublicKey:coordinator.publicKey,servicePrivateKey:provider.privateKey,now:()=>100,validateOperation:registry.validateOperation});
+  const client=createCooperativeClient({url:destination.url,serviceId:registry.serviceId,coordinatorPrivateKey:coordinator.privateKey,servicePublicKey:provider.publicKey});
+  let commits=0;
+  const simulatedLostReply={...client,async commit(key){commits++;await client.commit(key);throw Error('Example: reply lost after durable effect');}};
+  const executor=createCooperativeExecutor({local,client:simulatedLostReply,registry,role:'operator',tenure:'shift:1'});
+  const [tool]=createContinuityTools({registry,executor,operations:[{tool:'credits.allocate',operationId:'allocation:1',businessKey:'case:1:allocation'}]});
+  const args={units:amount.toString(),recipient:'team:blue'};
+  await assert.rejects(tool.invoke({...args,operationId:'model-selected'}));
+  const first=JSON.parse(await tool.invoke(args));assert.equal(first.invocation,'OUTCOME_UNKNOWN');
+  assert.equal(destination.inspect().effects.length,1);
+  const second=JSON.parse(await tool.invoke(args));assert.equal(second.lastReportedServiceState,'APPLIED');
+  assert.equal(commits,1);assert.equal(destination.inspect().effects[0].arguments.units,amount);
+  const recovered=await createCooperativeRecovery({local,client,registry}).lookup({operationId:'allocation:1',businessKey:'case:1:allocation',tool:'credits.allocate',arguments:{units:amount,recipient:'team:blue'}});
+  assert.equal(recovered.serviceReport.result.state,'APPLIED');assert.equal(recovered.dispatchPerformed,false);
+  console.log('Installed LangChain tool: exact decimal amount, denied identity injection, lost reply, status-only recovery and one effect passed.');
+} finally {try{await destination?.close();}finally{rmSync(dir,{recursive:true,force:true});}}