@awebai/oats 0.25.8 → 0.26.0

package/lib/captured-instance-index.mjs

@@ -1,277 +0,0 @@
-/** Bounded lifecycle custody in the existing deployment index. No source/config
- * discovery, user database, provider policy or automatic legacy backfill. */
-import { closeSync, constants, fsyncSync, lstatSync, openSync } from "node:fs";
-import { dirname } from "node:path";
-import { randomUUID } from "node:crypto";
-import { isAbsolute, join, resolve } from "node:path";
-import { readPortableBytes } from "./portable-files.mjs";
-import { compareUtf8, canonicalJson, parseStrictJson } from "./portable-values.mjs";
-import { jsonIntegrity } from "./portable-digest.mjs";
-import { portableScope, portableStateDirectory, withPortableStateWrite, writeGuardedPortableDocument } from "./portable-state.mjs";
-import { validateExecutionBinding } from "./schedule-capsule.mjs";
-import { validateIncarnationId, validateIntentRef } from "./captured-admission-shape.mjs";
-import { validateCapturedAction } from "./captured-action-shape.mjs";
-import { isMaterializedCapabilityId } from "./capability-provenance.mjs";
-import { objectAt, stringAt } from "./portable-shape.mjs";
-import { oatsError } from "./errors.mjs";
-
-const FILE = "instance-references.json";
-const STATUSES = new Set(["scaffolded-hooks-pending", "spawn-hooks-running", "spawned-launch-pending", "spawned-cleanup-required", "spawn-failed-cleanup-required", "retire-running", "retire-failed-cleanup-required", "start-running", "start-dispatched", "start-failed-cleanup-required"]);
-const INTENT_STATES = new Set(["admitted", "running", "completed", "unconfirmed", "blocked"]);
-const LIMITS = Object.freeze({ maxBytes: 4 * 1024 * 1024, maxDepth: 32, maxEntries: 40_000 });
-const RECEIPT_LIMITS = Object.freeze({ maxBytes: 128 * 1024, maxDepth: 24, maxEntries: 8192 });
-const same = (a,b) => canonicalJson(a) === canonicalJson(b);
-
-export function capturedDirectoryIdentity(path) {
-  const stat = lstatSync(path);
-  if (!stat.isDirectory()) throw oatsError("integrity-drift", "captured home/work must remain real directories");
-  return { dev: stat.dev, ino: stat.ino };
-}
-function directoryIdentity(value) {
-  objectAt(value,["dev","ino"],["dev","ino"]);
-  for (const key of ["dev","ino"]) if (!Number.isSafeInteger(value[key]) || value[key] < 0) throw oatsError("invalid-declaration","invalid directory identity witness");
-}
-function human(value) {
-  if (value === null) return;
-  objectAt(value,["provider","id"],["provider","id"]);stringAt(value.provider,"/human/provider");stringAt(value.id,"/human/id");
-}
-function intentRef(row,intent) { return {schemaVersion:1,executionId:intent.executionId,incarnationId:row.incarnationId,attempt:intent.attempt}; }
-function validateAdmittedAction(action,capability) {
-  if(action?.kind==='session'){
-    objectAt(action,['kind','name'],['kind','name']);
-    if(!['start','restart'].includes(action.name)||capability!==null)throw oatsError('invalid-declaration','invalid kernel session admission');
-  }else{
-    validateCapturedAction(action);
-    if(!isMaterializedCapabilityId(capability)||action.capability!==undefined&&action.capability!==capability)throw oatsError('invalid-declaration','invalid intent capability owner');
-  }
-}
-function validateIntent(intent) {
-  objectAt(intent,["executionId","capability","action","inputIntegrity","state","attempt","receipt","replayable"],["executionId","capability","action","inputIntegrity","state","attempt","receipt","replayable"]);
-  if(typeof intent.replayable!=="boolean")throw oatsError("invalid-declaration","invalid intent replay evidence");
-  validateAdmittedAction(intent.action,intent.capability);
-  stringAt(intent.executionId,"/executionId",{pattern:/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/});
-  if (!["command","operation","hook","session"].includes(intent.action.kind) || !INTENT_STATES.has(intent.state)) throw oatsError("invalid-declaration","invalid admitted action/state");
-  if (!Number.isSafeInteger(intent.attempt) || intent.attempt < 1) throw oatsError("invalid-declaration","invalid intent attempt");
-  objectAt(intent.inputIntegrity,["format","value"],["format","value"]);
-  if (intent.inputIntegrity.format !== "oats.json.v1" || !/^sha256-[a-f0-9]{64}$/.test(intent.inputIntegrity.value)) throw oatsError("invalid-declaration","invalid intent input integrity");
-  canonicalJson(intent.receipt,RECEIPT_LIMITS);
-}
-export function validateCapturedInstanceReference(row) {
-  objectAt(row,["home","instance","agent","kind","status","executionBinding","responsibleHuman","incarnationId","custody","intents","custodyFailure","nativeScaffold"],
-    ["home","instance","agent","kind","status","executionBinding","responsibleHuman","incarnationId","custody","intents"]);
-  for(const key of ["home","instance","agent"]) stringAt(row[key],`/${key}`);
-  if(!isAbsolute(row.home)||resolve(row.home)!==row.home) throw oatsError("invalid-declaration","captured home must be normalized absolute");
-  if(!['persistent','helper'].includes(row.kind)||!STATUSES.has(row.status)) throw oatsError("invalid-declaration","invalid captured instance kind/status");
-  validateIncarnationId(row.incarnationId);validateExecutionBinding(row.executionBinding);human(row.responsibleHuman);
-  if(row.nativeScaffold!==undefined){
-    objectAt(row.nativeScaffold,['schemaVersion','directories'],['schemaVersion','directories']);
-    if(row.nativeScaffold.schemaVersion!==1)throw oatsError('invalid-declaration','invalid native scaffold witness');
-    const names=['historyRoot','history','retirementRoot','baselines'];objectAt(row.nativeScaffold.directories,names,names);
-    for(const value of Object.values(row.nativeScaffold.directories))directoryIdentity(value);
-  }
-  if(row.custodyFailure!==undefined){
-    objectAt(row.custodyFailure,["code","message"],["code","message"]);
-    for(const key of ["code","message"]){stringAt(row.custodyFailure[key],`/custodyFailure/${key}`);if(row.custodyFailure[key].length>200)throw oatsError("resource-limit","custody diagnostic exceeds bound");}
-  }
-  objectAt(row.custody,["home","work"],["home","work"]);directoryIdentity(row.custody.home);directoryIdentity(row.custody.work);
-  if(!Array.isArray(row.intents)||row.intents.length>128) throw oatsError("resource-limit","captured instance intent retention limit reached");
-  const ids=new Set();let pending=0;
-  for(const intent of row.intents){validateIntent(intent);if(ids.has(intent.executionId))throw oatsError("invalid-declaration","duplicate intent ID");ids.add(intent.executionId);if(intent.state!=="completed")pending++;}
-  if(pending>1) throw oatsError("invalid-declaration","multiple unsettled captured intents");
-  return row;
-}
-function validateIndex(value) {
-  canonicalJson(value,LIMITS);objectAt(value,["schemaVersion","instances"],["schemaVersion","instances"]);
-  if(value.schemaVersion!==2) throw oatsError("migration-required","captured instance index lacks incarnation/admission evidence; no automatic backfill");
-  if(!Array.isArray(value.instances)) throw oatsError("invalid-declaration","invalid captured instance index");
-  const ids=new Set();let prior;
-  for(const row of value.instances){validateCapturedInstanceReference(row);if(ids.has(row.incarnationId)||(prior!==undefined&&compareUtf8(prior,row.home)>=0))throw oatsError("invalid-declaration","duplicate/unordered captured instance references");ids.add(row.incarnationId);prior=row.home;}
-  return value;
-}
-export function readCapturedInstanceIndex(deployment) {
-  const root=portableStateDirectory(deployment,false);
-  if(!root)return {schemaVersion:2,instances:[]};
-  const bytes=readPortableBytes(join(root,FILE),{allowMissing:true});
-  return bytes===null?{schemaVersion:2,instances:[]}:validateIndex(parseStrictJson(bytes,LIMITS));
-}
-
-/** Read and verify current owned metadata; old/unwitnessed homes are evidence,
- * never newly minted identities. Recheck roots after the descriptor read. */
-export function readCapturedInstanceMetadata(home) {
-  if(typeof home!=="string"||!isAbsolute(home))throw oatsError("invalid-declaration","captured home must be explicit and absolute");
-  const actual=portableScope(home),homeIdentity=capturedDirectoryIdentity(home),workIdentity=capturedDirectoryIdentity(join(home,"work"));
-  const metadata=parseStrictJson(readPortableBytes(join(actual,"instance.json")),LIMITS);
-  if(!metadata.incarnationId||!metadata.captured?.custody)throw oatsError("migration-required","captured home lacks incarnation custody; explicit reprovisioning required without deleting prior data");
-  validateIncarnationId(metadata.incarnationId);validateExecutionBinding(metadata.executionBinding);
-  if(typeof metadata.home!=="string"||portableScope(metadata.home)!==actual||metadata.work!=="directory"
-    ||!same(metadata.captured.custody,{home:homeIdentity,work:workIdentity})
-    ||!same(capturedDirectoryIdentity(home),homeIdentity)||!same(capturedDirectoryIdentity(join(home,"work")),workIdentity))throw oatsError("integrity-drift","captured home/work ownership changed");
-  return metadata;
-}
-function matchedRow(index,home) {
-  const metadata=readCapturedInstanceMetadata(home),actual=portableScope(home),row=index.instances.find(item=>item.home===actual);
-  if(!row)throw oatsError("invalid-resolution","captured incarnation is not indexed");
-  if(row.incarnationId!==metadata.incarnationId||row.instance!==metadata.instance||row.agent!==metadata.agent||row.kind!==metadata.kind
-    ||!same(row.custody,metadata.captured.custody)||!same(row.executionBinding,metadata.executionBinding)||!same(row.responsibleHuman,metadata.responsibleHuman))throw oatsError("invalid-resolution","captured index differs from current incarnation metadata");
-  return {row,metadata};
-}
-export function readCapturedInstanceAuthority(deployment,home) {
-  return matchedRow(readCapturedInstanceIndex(deployment),home);
-}
-const AUTHORITY_FIELDS = ["home","instance","agent","kind","executionBinding","responsibleHuman","incarnationId","custody"];
-function sameAuthority(a,b){return AUTHORITY_FIELDS.every(key=>same(a[key],b[key]))&&same(a.nativeScaffold??null,b.nativeScaffold??null);}
-export function assertCapturedInstanceCustody(original) {
-  for(const [key,path] of [["home",original.home],["work",join(original.home,"work")]]){
-    if(!same(capturedDirectoryIdentity(path),original.custody[key]))throw oatsError("integrity-drift","captured home/work changed after preflight");
-  }
-  const {row}=readCapturedInstanceAuthority(original.executionBinding.deployment,original.home);
-  if(!sameAuthority(original,row))throw oatsError("integrity-drift","captured instance authority changed after preflight");
-  return row;
-}
-
-/** Failure reporting deliberately does NOT read/resolve the home: it may now
- * belong to someone else. Match the original indexed authority and attempt,
- * preserve receipts there, and never use this path to certify success. */
-export function recordCapturedCustodyFailure(original,{meta={},intents={},code="integrity-drift",message="captured home/work custody changed"}={}) {
-  validateCapturedInstanceReference(original);objectAt(meta,null,[]);objectAt(intents,null,[]);
-  return withPortableStateWrite(original.executionBinding.deployment,context=>{
-    const index=readCapturedInstanceIndex(context.deployment),row=index.instances.find(item=>item.incarnationId===original.incarnationId);
-    if(!row||!sameAuthority(original,row))throw oatsError("selection-changed","original indexed custody no longer matches failure report");
-    // This reporter owns only the activation transition it acquired before
-    // hooks. Check it before changing ANY receipt/status, even on failure.
-    if(row.status!=="spawn-hooks-running")throw oatsError("selection-changed","activation no longer owns the indexed lifecycle state");
-    for(const [capability,ref] of Object.entries(intents)){
-      const intent=matchedIntent(row,ref);
-      if(intent.capability!==capability)throw oatsError("invalid-resolution","observed receipt owner differs from admitted capability");
-      if(Object.hasOwn(meta,capability)){canonicalJson(meta[capability],RECEIPT_LIMITS);intent.receipt=meta[capability];}
-      if(intent.state==="running"||intent.state==="admitted"){intent.state="unconfirmed";intent.replayable=false;}
-    }
-    for(const capability of Object.keys(meta))if(!Object.hasOwn(intents,capability))throw oatsError("invalid-resolution","observed receipt lacks its admitted intent");
-    row.status="spawn-failed-cleanup-required";
-    row.custodyFailure={code:String(code).slice(0,200)||"integrity-drift",message:String(message).slice(0,200)||"custody failure"};
-    save(context,index);return {home:row.home,incarnationId:row.incarnationId,executionBinding:row.executionBinding,custodyFailure:row.custodyFailure};
-  });
-}
-/** Sync only already-owned metadata paths. If synchronization fails after
- * publication, callers retain custody rather than claim admission completed. */
-export function syncCapturedMetadata(path) {
-  const stat=lstatSync(path);
-  if(!stat.isFile()&&!stat.isDirectory())throw oatsError("integrity-drift","captured metadata sync target changed");
-  const fd=openSync(path,constants.O_RDONLY|(constants.O_NOFOLLOW??0));
-  try{fsyncSync(fd);}finally{closeSync(fd);}
-}
-function save(context,index){
-  validateIndex(index);const file=join(context.root,FILE);
-  writeGuardedPortableDocument(context,file,index);
-  for(const path of [file,context.root,dirname(context.root),context.deployment])syncCapturedMetadata(path);
-}
-export function registerCapturedInstance(deployment,home) {
-  return withPortableStateWrite(deployment,context=>{
-    const index=readCapturedInstanceIndex(context.deployment),metadata=readCapturedInstanceMetadata(home),actual=portableScope(home);
-    if(index.instances.some(row=>row.home===actual))throw oatsError("selection-changed","captured home has retained lifecycle obligations; no replacement/backfill");
-    if(portableScope(metadata.executionBinding.deployment)!==context.deployment)throw oatsError("invalid-resolution","incarnation deployment mismatch");
-    const row={home:actual,instance:metadata.instance,agent:metadata.agent,kind:metadata.kind,status:"scaffolded-hooks-pending",executionBinding:metadata.executionBinding,
-      responsibleHuman:metadata.responsibleHuman,incarnationId:metadata.incarnationId,custody:metadata.captured.custody,intents:[]};
-    validateCapturedInstanceReference(row);index.instances.push(row);index.instances.sort((a,b)=>compareUtf8(a.home,b.home));save(context,index);return row;
-  });
-}
-export function markCapturedNativeScaffold(deployment,home,proof) {
-  return withPortableStateWrite(deployment,context=>{
-    const index=readCapturedInstanceIndex(context.deployment),{row,metadata}=matchedRow(index,home);
-    if(row.nativeScaffold||row.status!=='scaffolded-hooks-pending'||row.intents.length)throw oatsError('selection-changed','native scaffold cannot be backfilled after admission');
-    if(!same(metadata.captured.nativeScaffold,proof))throw oatsError('invalid-resolution','native scaffold proof differs from owned metadata');
-    row.nativeScaffold=proof;save(context,index);return row;
-  });
-}
-export function setCapturedInstanceStatus(deployment,home,status,{expectedStatus}={}) {
-  if(!STATUSES.has(status))throw oatsError("invalid-declaration","invalid captured lifecycle status");
-  return withPortableStateWrite(deployment,context=>{
-    const index=readCapturedInstanceIndex(context.deployment),{row}=matchedRow(index,home);
-    if(expectedStatus!==undefined&&row.status!==expectedStatus)throw oatsError("selection-changed","captured lifecycle status changed");
-    row.status=status;save(context,index);return row;
-  });
-}
-
-/** New intent or EXPLICIT retry; input commits only bounded nonsecret request
- * data, never runtime environment or credential values. */
-export function admitCapturedInstanceAction({deployment,home,executionBinding,capability,action,input={},retryExecutionId,expectedStatus}) {
-  validateExecutionBinding(executionBinding);
-  if(expectedStatus!==undefined&&!STATUSES.has(expectedStatus))throw oatsError('invalid-declaration','invalid admission source state');
-  validateAdmittedAction(action,capability);canonicalJson(input,{maxBytes:128*1024,maxDepth:24,maxEntries:8192});
-  const inputIntegrity=jsonIntegrity(input);
-  return withPortableStateWrite(deployment,context=>{
-    const index=readCapturedInstanceIndex(context.deployment),{row,metadata}=matchedRow(index,home);
-    if(!same(row.executionBinding,executionBinding))throw oatsError("invalid-resolution","admission selection differs from current indexed incarnation");
-    if(expectedStatus!==undefined&&(row.status!==expectedStatus||metadata.captured.lifecycle!==expectedStatus)){
-      const error=oatsError('selection-changed','native admission no longer owns matching source lifecycle');error.home=row.home;
-      error.capturedCustody={incarnationId:row.incarnationId,executionBinding:row.executionBinding,indexedStatus:row.status,metadataStatus:metadata.captured.lifecycle,expectedStatus,held:true};
-      throw error;
-    }
-    let intent;
-    if(retryExecutionId!==undefined){
-      intent=row.intents.find(item=>item.executionId===retryExecutionId);
-      if(!intent||intent.capability!==capability||!same(intent.action,action)||!same(intent.inputIntegrity,inputIntegrity))throw oatsError("invalid-resolution","retry does not match the admitted action/input");
-      if(intent.state==="completed")return {intent:intentRef(row,intent),replayed:true,replayable:intent.replayable,receipt:intent.receipt};
-      if(!["unconfirmed","blocked"].includes(intent.state))throw oatsError("selection-changed","intent is admitted/running; explicit reconciliation is required before retry");
-      intent.attempt++;intent.state="admitted";
-    }else{
-      if(row.intents.some(item=>item.state!=="completed"))throw oatsError("selection-changed","an unsettled captured intent must be reconciled/retried, not replaced");
-      if(row.intents.length>=128)throw oatsError("resource-limit","captured intent history is full; no automatic pruning");
-      const previous=row.intents.findLast(item=>item.capability===capability);
-      const receipt=previous?previous.receipt:capability!==null&&metadata.capabilityMeta&&Object.hasOwn(metadata.capabilityMeta,capability)?metadata.capabilityMeta[capability]:null;
-      canonicalJson(receipt,RECEIPT_LIMITS);
-      intent={executionId:randomUUID(),capability,action,inputIntegrity,state:"admitted",attempt:1,receipt,replayable:false};row.intents.push(intent);
-    }
-    save(context,index);return {intent:intentRef(row,intent),replayed:false,receipt:intent.receipt};
-  });
-}
-function matchedIntent(row,ref,action) {
-  validateIntentRef(ref);const intent=row.intents.find(item=>item.executionId===ref.executionId);
-  if(row.incarnationId!==ref.incarnationId||!intent||intent.attempt!==ref.attempt||(action&&!same(intent.action,action)))throw oatsError("invalid-resolution","intent reference differs from indexed incarnation/action/attempt");
-  return intent;
-}
-export function readCapturedIntent({deployment,home,intent:ref,action}) {
-  const {row}=matchedRow(readCapturedInstanceIndex(deployment),home),intent=matchedIntent(row,ref,action);
-  return {...intent,incarnationId:row.incarnationId};
-}
-export function failCapturedNativeIntent(original,ref,receipt) {
-  canonicalJson(receipt,RECEIPT_LIMITS);
-  return withPortableStateWrite(original.executionBinding.deployment,context=>{
-    const index=readCapturedInstanceIndex(context.deployment),row=index.instances.find(item=>item.incarnationId===original.incarnationId);
-    if(!row||!sameAuthority(original,row))throw oatsError('selection-changed','native failure lost original indexed authority');
-    if(row.status!=='start-running')throw oatsError('selection-changed','native failure no longer owns lifecycle state');
-    const intent=matchedIntent(row,ref);
-    if(intent.action.kind!=='session'||intent.capability!==null)throw oatsError('invalid-resolution','native failure is not its session intent');
-    if(intent.state!=='completed'){intent.state='unconfirmed';intent.receipt=receipt;intent.replayable=false;}
-    row.status='start-failed-cleanup-required';save(context,index);return intentRef(row,intent);
-  });
-}
-/** An allocated native target is retained under the running logical intent
- * BEFORE launch. It is an observation, not completion or a new identity. */
-export function observeCapturedNativeTarget(original,ref,receipt) {
-  validateCapturedInstanceReference(original);canonicalJson(receipt,RECEIPT_LIMITS);
-  return withPortableStateWrite(original.executionBinding.deployment,context=>{
-    const index=readCapturedInstanceIndex(context.deployment),{row}=matchedRow(index,original.home);
-    if(!sameAuthority(original,row)||row.status!=='start-running')throw oatsError('selection-changed','native target observation lost original lifecycle custody');
-    const intent=matchedIntent(row,ref);
-    if(intent.capability!==null||intent.action.kind!=='session'||intent.state!=='running')throw oatsError('selection-changed','native target observation needs the running admitted session');
-    intent.receipt=receipt;intent.replayable=false;save(context,index);return intentRef(row,intent);
-  });
-}
-export function beginCapturedIntent({deployment,home,intent:ref,action}) {
-  return withPortableStateWrite(deployment,context=>{
-    const index=readCapturedInstanceIndex(context.deployment),{row}=matchedRow(index,home),intent=matchedIntent(row,ref,action);
-    if(intent.state!=="admitted")throw oatsError("selection-changed","captured intent has already begun or settled");
-    intent.state="running";save(context,index);return intentRef(row,intent);
-  });
-}
-export function settleCapturedIntent({deployment,home,intent:ref,action,state,receipt,replayable=false}) {
-  if(typeof replayable!=="boolean")throw oatsError("invalid-declaration","invalid intent replay evidence");
-  if(!["completed","unconfirmed","blocked"].includes(state))throw oatsError("invalid-declaration","invalid captured intent outcome");
-  canonicalJson(receipt,RECEIPT_LIMITS);
-  return withPortableStateWrite(deployment,context=>{
-    const index=readCapturedInstanceIndex(context.deployment),{row}=matchedRow(index,home),intent=matchedIntent(row,ref,action);
-    if((state==="blocked"&&intent.state!=="admitted")||(state!=="blocked"&&intent.state!=="running"))throw oatsError("selection-changed","intent outcome does not match its admitted/running attempt");
-    intent.state=state;intent.receipt=receipt;intent.replayable=state==="completed"&&replayable;save(context,index);return intentRef(row,intent);
-  });
-}

package/lib/captured-invocation-context.mjs

@@ -1,130 +0,0 @@
-/** Provider-neutral captured action/lifecycle context. Provider bindings remain in
- * OATS_BINDING_FILE; this companion supplies record/target intent and prior
- * opaque provider receipt without provider-specific kernel fields. */
-import { lstatSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
-import { readCapturedInstanceAuthority, readCapturedIntent } from "./captured-instance-index.mjs";
-import { validateIncarnationId, validateIntentRef } from "./captured-admission-shape.mjs";
-import { isAbsolute, join, resolve } from "node:path";
-import { canonicalJson } from "./portable-values.mjs";
-import { objectAt, stringAt } from "./portable-shape.mjs";
-import { portableScope, portableStateDirectory } from "./portable-state.mjs";
-import { validateExecutionBinding } from "./schedule-capsule.mjs";
-import { validateCapturedSubject, validateCapturedContext, validateMessagingChoice } from "./resolution-shape.mjs";
-import { validateCapturedAction } from "./captured-action-shape.mjs";
-import { isMaterializedCapabilityId } from "./capability-provenance.mjs";
-import { oatsError } from "./errors.mjs";
-
-export const CAPTURED_INVOCATION_CONTEXT_LIMITS = Object.freeze({ maxBytes: 512 * 1024, maxDepth: 32, maxEntries: 16_384 });
-export const CAPTURED_PRIOR_RECEIPT_LIMITS = Object.freeze({ maxBytes: 128 * 1024, maxDepth: 24, maxEntries: 8192 });
-const FIELDS = ["schemaVersion", "executionBinding", "subject", "instance", "context", "responsibleHuman", "messagingChoice", "capability", "action", "priorReceipt", "intent"];
-
-function human(value, pointer) {
-  if (value === null) return;
-  objectAt(value, ["provider", "id"], ["provider", "id"], pointer);
-  stringAt(value.provider, `${pointer}/provider`); stringAt(value.id, `${pointer}/id`);
-}
-
-export function validateCapturedInvocationContext(value) {
-  canonicalJson(value, CAPTURED_INVOCATION_CONTEXT_LIMITS); objectAt(value, FIELDS, FIELDS);
-  if (value.schemaVersion !== 1) throw oatsError("unsupported-wire-version", "captured invocation context schemaVersion must be 1");
-  validateExecutionBinding(value.executionBinding);
-  validateCapturedSubject(value.subject);
-  const subjectName = value.subject.kind === "persistent" ? value.subject.soul.alias : value.subject.name;
-  if (value.instance !== null) {
-    objectAt(value.instance, ["home", "work", "name", "agent", "incarnationId"], ["home", "work", "name", "agent", "incarnationId"], "/instance");
-    validateIncarnationId(value.instance.incarnationId);
-    for (const key of ["home", "work"]) {
-      stringAt(value.instance[key], `/instance/${key}`);
-      if (!isAbsolute(value.instance[key]) || resolve(value.instance[key]) !== value.instance[key] || value.instance[key].includes("\0")) throw oatsError("invalid-declaration", `captured invocation ${key} must be normalized absolute`);
-    }
-    stringAt(value.instance.name, "/instance/name"); stringAt(value.instance.agent, "/instance/agent");
-    if (value.instance.agent !== subjectName || value.instance.work !== join(value.instance.home, "work")) throw oatsError("invalid-resolution", "captured invocation target differs from its subject/home");
-  }
-  validateCapturedContext(value.context);
-  human(value.responsibleHuman, "/responsibleHuman");
-  // Reuse the existing messaging-choice codec, not another privacy/policy model.
-  const messagingProvider = value.messagingChoice?.enabled === true ? value.messagingChoice.privateKey?.provider : undefined;
-  if (messagingProvider !== undefined && !isMaterializedCapabilityId(messagingProvider)) throw oatsError("invalid-declaration", "invalid invocation messaging provider");
-  validateMessagingChoice(value.messagingChoice, { context: value.context,
-    bindings: messagingProvider === undefined ? {} : { messaging: { capability: messagingProvider } } });
-  const expectedHuman = value.messagingChoice.enabled ? value.messagingChoice.privateKey.human : null;
-  if (canonicalJson(value.responsibleHuman) !== canonicalJson(expectedHuman)) throw oatsError("invalid-resolution", "invocation responsible human differs from captured messaging choice");
-  if (!isMaterializedCapabilityId(value.capability)) throw oatsError("invalid-declaration", "invalid invocation capability");
-  validateCapturedAction(value.action);
-  if (value.action.capability !== undefined && value.action.capability !== value.capability) throw oatsError("invalid-resolution", "invocation action capability differs from its owner");
-  if (value.action.kind === "hook" && value.instance === null) throw oatsError("invalid-resolution", "captured instance hook requires instance facts");
-  if (value.intent !== null) {
-    validateIntentRef(value.intent);
-    if (value.instance === null || value.intent.incarnationId !== value.instance.incarnationId) throw oatsError("invalid-resolution", "intent belongs to a different incarnation");
-  }
-  canonicalJson(value.priorReceipt, CAPTURED_PRIOR_RECEIPT_LIMITS);
-  return value;
-}
-
-export function buildCapturedInvocationContext(input) {
-  const { loaded, action, instance = null } = input;
-  if (!loaded?.record || !loaded?.resolution || !loaded?.capability) throw oatsError("invalid-resolution", "captured invocation context requires one verified action");
-  const { record } = loaded, subject = record.subject;
-  const subjectName = subject.kind === "persistent" ? subject.soul.alias : subject.name;
-  if (instance !== null && instance.agent !== subjectName) throw oatsError("invalid-resolution", "captured invocation target agent differs from retained subject");
-  const expectedHuman = record.messagingChoice.enabled ? record.messagingChoice.privateKey.human : null;
-  let priorReceipt = null, target = null;
-  const intent = input.intent ?? null;
-  if (instance !== null) {
-    canonicalJson(instance);
-    objectAt(instance, ["home", "work", "name", "agent"], ["home", "work", "name", "agent"]);
-    if (typeof instance.home !== "string" || !isAbsolute(instance.home) || instance.work !== join(instance.home, "work")) throw oatsError("invalid-resolution", "captured invocation needs an explicit home/work target");
-    const home = portableScope(instance.home);
-    if (!lstatSync(instance.home).isDirectory()) throw oatsError("invalid-resolution", "captured invocation home must not be a symlink");
-    const { metadata, row } = readCapturedInstanceAuthority(loaded.deployment, home);
-    target = { ...instance, incarnationId: metadata.incarnationId };
-    validateExecutionBinding(metadata.executionBinding);
-    if (typeof metadata.home !== "string" || portableScope(metadata.home) !== home || metadata.instance !== instance.name
-      || metadata.agent !== instance.agent || metadata.kind !== subject.kind
-      || portableScope(metadata.executionBinding.deployment) !== portableScope(loaded.deployment)
-      || canonicalJson(metadata.executionBinding.resolution) !== canonicalJson(loaded.resolution)
-      || canonicalJson(metadata.responsibleHuman) !== canonicalJson(expectedHuman)) throw oatsError("invalid-resolution", "invocation target differs from captured instance metadata/record");
-    if (metadata.capabilityMeta !== undefined) objectAt(metadata.capabilityMeta, null, []);
-    const previous = row.intents.findLast(entry => entry.capability === loaded.capability.id);
-    priorReceipt = previous ? previous.receipt : metadata.capabilityMeta && Object.hasOwn(metadata.capabilityMeta, loaded.capability.id) ? metadata.capabilityMeta[loaded.capability.id] : null;
-  }
-  if (intent !== null) {
-    if (!target) throw oatsError("invalid-resolution", "admitted action requires an owned instance");
-    const admitted = readCapturedIntent({ deployment: loaded.deployment, home: instance.home, intent, action });
-    if (admitted.capability !== loaded.capability.id || !["admitted", "running"].includes(admitted.state)) throw oatsError("invalid-resolution", "invocation does not match an active admitted capability action");
-    priorReceipt = admitted.receipt;
-  }
-  if (Object.hasOwn(input, "priorReceipt") && canonicalJson(input.priorReceipt) !== canonicalJson(priorReceipt)) throw oatsError("invalid-resolution", "invocation prior receipt differs from stored provider receipt");
-  const value = { schemaVersion: 1,
-    executionBinding: { schemaVersion: 1, deployment: portableScope(loaded.deployment), resolution: loaded.resolution },
-    subject, instance: target, intent, context: record.context, responsibleHuman: expectedHuman,
-    messagingChoice: record.messagingChoice, capability: loaded.capability.id, action, priorReceipt };
-  return validateCapturedInvocationContext(structuredClone(value));
-}
-
-export function withCapturedInvocationContextFile(invocation, run) {
-  validateCapturedInvocationContext(invocation);
-  if (typeof run !== "function") throw oatsError("invalid-declaration", "captured invocation context consumer must be a function");
-  const directory = mkdtempSync(join(portableStateDirectory(invocation.executionBinding.deployment, true), ".invocation-context-"));
-  const owned = lstatSync(directory), file = join(directory, "context.json"); let primary, result, completed = false;
-  try {
-    writeFileSync(file, canonicalJson(invocation, CAPTURED_INVOCATION_CONTEXT_LIMITS), { flag: "wx", mode: 0o600 });
-    result = run({ OATS_INVOCATION_CONTEXT_FILE: file }); completed = true; return result;
-  } catch (error) { primary = error; throw error; }
-  finally {
-    try {
-      const current = lstatSync(directory);
-      if (!current.isDirectory() || current.dev !== owned.dev || current.ino !== owned.ino) throw oatsError("integrity-drift", "invocation context directory ownership changed");
-      rmSync(directory, { recursive: true });
-    } catch (cleanup) {
-      if (!primary) {
-        const error = new AggregateError([cleanup], "captured invocation context cleanup failed after invocation", { cause: cleanup });
-        error.code = cleanup.code; error.invocationCompleted = completed; error.invocationResult = result; throw error;
-      }
-      const error = new AggregateError([primary, cleanup], "captured invocation context and cleanup failed", { cause: primary });
-      error.code = primary.code;
-      if (primary.invocationCompleted) { error.invocationCompleted = true; error.invocationResult = primary.invocationResult; }
-      throw error;
-    }
-  }
-}

package/lib/captured-launch-request.mjs

@@ -1,66 +0,0 @@
-/** Explicit portable launch input, not a current launch-config/model resolver.
- * OATS-managed entrypoints are retained; external host tools are explicitly
- * selected/preflighted, not forced into a new capability layer. */
-import { isAbsolute, resolve } from 'node:path';
-import { canonicalJson } from './portable-values.mjs';
-import { objectAt, stringAt } from './portable-shape.mjs';
-import { isMaterializedCapabilityId } from './capability-provenance.mjs';
-import { oatsError } from './errors.mjs';
-import { PI_SDK_HOST, validatePiHostRecipe } from './pi-sdk-host.mjs';
-
-export function validateCapturedLaunchRequest(value, validateConfig) {
-  canonicalJson(value,{maxBytes:128*1024,maxDepth:16,maxEntries:4096});
-  objectAt(value,['runtime','executable','args','env','model','yolo'],['runtime','executable','args','env','model','yolo']);
-  if(typeof value.executable==='string'){
-    stringAt(value.executable,'/launch/executable');
-    if(!isAbsolute(value.executable)||resolve(value.executable)!==value.executable||value.executable.includes('\0'))throw oatsError('invalid-declaration','host launch executable must be explicit normalized absolute text');
-  }else{
-    objectAt(value.executable,['capability','command'],['capability','command']);
-    if(!isMaterializedCapabilityId(value.executable.capability))throw oatsError('invalid-declaration','managed launch entrypoint must name a selected capability');
-    stringAt(value.executable.command,'/launch/executable/command');
-  }
-  stringAt(value.model,'/launch/model');
-  if(typeof value.yolo!=='boolean')throw oatsError('invalid-declaration','captured launch requires explicit yolo');
-  validateConfig('captured',{...value,executable:'captured-resource'},'explicit launch request');
-  if(value.executable===PI_SDK_HOST || value.args?.includes('--oats-pi-host'))validatePiHostRecipe(value);
-  // All kernel/provider invocation aliases remain kernel-owned on this new
-  // surface. The legacy launch-config validator has a narrower historical list.
-  for(const name of Object.keys(value.env))if(/^(OATS_|PI_AGENT_|OAS_)/.test(name)||name==='PI_AGENTS_ROOT')throw oatsError('invalid-declaration','launch environment cannot override captured authority');
-  return value;
-}
-
-export function compileCapturedLaunchRequest(request,{artifacts,manifests,settings,resources},kernel) {
-  if(request===undefined)return null;
-  validateCapturedLaunchRequest(request,kernel.validateLaunchConfig);
-  const providers=[...manifests].filter(([id])=>Object.hasOwn(artifacts.capabilities,id)).map(([id,manifest])=>({id,manifest,settings:settings[id]}));
-  // `ifInstalled: true` rows constrain a package that may legitimately be absent (a version floor
-  // for an ambient extension, if any). Captured preparation retains no ambient packages, so such a
-  // row is satisfied by absence — treating it as a hard requirement made a Pi launch with aweb
-  // `delivery: session` unpublishable (second-operator finding, 2026-09-21). Hard rows refuse
-  // through the preparation problem shape, naming the capability and package; the remedy text is
-  // the manifest's own `install` string — declared data, never free text.
-  // Resolve each applicable row back to its declaration, honouring the same `when` predicate the
-  // kernel's requirement selection uses, so two rows for one package (channel vs session) stay distinct.
-  const holds=(provider,row)=>!row.when || Object.entries(row.when).every(([k,v])=>String(provider.settings?.[k] ?? '')===String(v));
-  const declarationOf=(row)=>{const provider=providers.find(p=>p.id===row.capability);
-    return {provider,declared:provider?.manifest?.requires?.find(r=>r && typeof r==='object' && r.runtime===request.runtime && r.package===row.package && holds(provider,r))};};
-  const required=kernel.runtimeRequirements(request.runtime,providers).filter(row=>declarationOf(row).declared?.ifInstalled!==true);
-  if(required.length){
-    const error=oatsError('needs-configuration','runtime package requirements need retained runtime roots and a qualified loader; no ambient package discovery was used');
-    error.problems=required.map(row=>{
-      const {provider,declared}=declarationOf(row);
-      return {code:'needs-configuration',message:`${request.runtime} launch requires runtime package ${row.package}, which captured preparation has not retained`,capability:row.capability,
-        ...(provider?.manifest?.layer?{slot:provider.manifest.layer}:{}),runtime:request.runtime,package:row.package,...(typeof declared?.install==='string'?{install:declared.install}:{})};
-    });
-    throw error;
-  }
-  const base={version:1,runtime:request.runtime,args:request.args,env:request.env,model:request.model,yolo:request.yolo,
-    hooks:{launch:{},env:{},contributions:[],pending:true},prompt:{kind:'task-file',file:'TASK.md'}};
-  if(typeof request.executable==='string')return {...base,executable:request.executable,executableResolvedFrom:'explicit-host'};
-  const {capability:id,command}=request.executable,manifest=manifests.get(id);
-  if(!Object.hasOwn(artifacts.capabilities,id)||!manifest?.commands||!Object.hasOwn(manifest.commands,command))throw oatsError('capability-not-selected','launch entrypoint is not declared by a selected capability');
-  const key=`executable:${id}:command:${command}`;
-  if(!Object.hasOwn(resources,key)||resources[key].kind!=='file')throw oatsError('resolution-incomplete','launch entrypoint lacks a retained executable resource');
-  const [, ...declaredArgs]=manifest.commands[command].trim().split(/\s+/);
-  return {...base,executable:'captured-resource',executableResource:key,entrypoint:{capability:id,command},args:[...declaredArgs,...request.args]};
-}

package/lib/captured-operation-process.mjs

@@ -1,15 +0,0 @@
-/** Bounded runner for one already-verified captured provider operation. The
- * caller owns receipt interpretation and invocation-snapshot cleanup. */
-import { spawnSync } from "node:child_process";
-import { oatsError } from "./errors.mjs";
-
-export const CAPTURED_OPERATION_TIMEOUT_MS = 4 * 60 * 1000;
-
-export function runCapturedOperationProcess({ file, args = [], cwd, env, timeoutMs = CAPTURED_OPERATION_TIMEOUT_MS }) {
-  if (typeof file !== "string" || !file || !Array.isArray(args) || args.some((arg) => typeof arg !== "string")) throw oatsError("invalid-declaration", "captured operation executable and arguments must be text");
-  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1 || timeoutMs > CAPTURED_OPERATION_TIMEOUT_MS) throw oatsError("invalid-declaration", `captured operation timeout must be 1-${CAPTURED_OPERATION_TIMEOUT_MS}ms`);
-  return spawnSync(process.execPath, [file, ...args], {
-    cwd, env, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"],
-    maxBuffer: 16 * 1024 * 1024, timeout: timeoutMs, killSignal: "SIGKILL",
-  });
-}

package/lib/captured-pi-custody.mjs

@@ -1,29 +0,0 @@
-/** Kernel side of the Pi record-witness seam. Record support is deliberately
- * capability-checked before admission: older path-only readers cannot launch a
- * protected host. The record-library implementation is separately owned. */
-import { basename, dirname, join } from "node:path";
-import * as records from "../packages/record/lib/native-history.mjs";
-import { oatsError } from "./errors.mjs";
-
-export function capturedPiSessionDirectory(home) {
-  const history = records.nativeHistoryPath(home);
-  return join(dirname(history), `${basename(history)}.pi`);
-}
-
-export function requireCapturedPiRecordSupport() {
-  if (records.CAPTURED_PI_RECORD_VERSION !== 2
-    || ["inspectCapturedPiRoot", "prepareCapturedPiStart", "assertCapturedPiStart"].some(name => typeof records[name] !== "function")) {
-    throw oatsError("E_PI_HOST_RECORD_UNAVAILABLE", "captured Pi requires complete versioned native-root discovery/read/capture guards; path-only record support cannot launch it");
-  }
-  return records;
-}
-
-export function inspectCapturedPiRoot(home, authority) {
-  return requireCapturedPiRecordSupport().inspectCapturedPiRoot(home, authority);
-}
-export function prepareCapturedPiStart(home, authority) {
-  return requireCapturedPiRecordSupport().prepareCapturedPiStart(home, authority);
-}
-export function assertCapturedPiStart(home, nativeRecordId, authority) {
-  return requireCapturedPiRecordSupport().assertCapturedPiStart(home, nativeRecordId, authority);
-}