@awebai/oats 0.29.4 → 0.30.1

package/capabilities/oats-okf/lib/harvest-switch.mjs

@@ -1,94 +0,0 @@
-// The harvest switch (okf 4.0.0; plan §2.4). `harvest: on|off` is a host
-// fact, default off. A soul may only opt OUT (`knowledge: { harvest: off }` in
-// soul.yaml), and that opt-out is absolute. The kernel merges soul ⊕ host ⊕
-// spawn with later-wins, so a host `on` would hide a soul `off` in the merged
-// settings. The soul's own value is therefore read from its soul.yaml
-// ($OATS_SOUL), with a deliberately small reader. Anything it cannot read with
-// certainty counts as off (fail closed): a private transcript is never kept
-// because a file was ambiguous.
-import { fs, join } from './io.mjs';
-
-const VALUES = ['on', 'off'];
-const scalar = (raw) => {
-  const v = raw.replace(/\s+#.*$/, '').trim();
-  const q = /^(['"])(.*)\1$/.exec(v);
-  return q ? q[2] : v;
-};
-/** The soul's own `knowledge.harvest` → { value: 'on'|'off'|null, readable, why }. */
-export function soulHarvest(soulDir) {
-  if (!soulDir) return { value: null, readable: false, why: 'the soul directory is not known to this command (OATS_SOUL unset)' };
-  let text;
-  try { text = fs.readFileSync(join(soulDir, 'soul.yaml'), 'utf8'); } catch (e) { return { value: null, readable: false, why: `soul.yaml unreadable (${e.code || e.message})` }; }
-  const lines = text.split(/\r?\n/);
-  const at = lines.findIndex((l) => /^knowledge\s*:/.test(l));
-  if (at < 0) return { value: null, readable: true, why: 'no knowledge: payload' };
-  const rest = lines[at].replace(/^knowledge\s*:/, '').replace(/\s+#.*$/, '').trim();
-  if (rest === 'none' || rest === "'none'" || rest === '"none"') return { value: null, readable: true, why: 'knowledge: none' };
-  if (rest.startsWith('{')) {
-    if (!rest.endsWith('}') || /[{}]/.test(rest.slice(1, -1))) return { value: null, readable: false, why: 'knowledge: flow mapping is not a single flat line' };
-    const pairs = rest.slice(1, -1).split(',').map((p) => p.trim()).filter(Boolean);
-    let value = null;
-    for (const pair of pairs) {
-      const m = /^(['"]?)([A-Za-z0-9._-]+)\1\s*:\s*(.*)$/.exec(pair);
-      if (!m) return { value: null, readable: false, why: 'knowledge: flow mapping entry is not key: value' };
-      if (m[2] === 'harvest') value = scalar(m[3]);
-    }
-    return shaped(value);
-  }
-  if (rest !== '') return { value: null, readable: false, why: 'knowledge: is neither none, a flow mapping nor a block mapping' };
-  let value = null, indent = null;
-  for (const line of lines.slice(at + 1)) {
-    if (/^\s*(#.*)?$/.test(line)) continue;
-    const lead = /^(\s*)/.exec(line)[1].length;
-    if (lead === 0) break;
-    if (/\t/.test(line.slice(0, lead))) return { value: null, readable: false, why: 'tab indentation under knowledge:' };
-    if (indent === null) indent = lead;
-    if (lead < indent) return { value: null, readable: false, why: 'inconsistent indentation under knowledge:' };
-    if (lead > indent) continue; // a nested value of another key
-    const m = /^\s*(['"]?)([A-Za-z0-9._-]+)\1\s*:(.*)$/.exec(line);
-    if (!m) return { value: null, readable: false, why: 'a knowledge: entry is not key: value' };
-    if (m[2] === 'harvest') value = scalar(m[3]);
-  }
-  return shaped(value);
-}
-function shaped(value) {
-  if (value === null) return { value: null, readable: true, why: 'the soul does not set harvest' };
-  if (!VALUES.includes(value)) return { value: null, readable: false, why: `the soul's harvest is ${JSON.stringify(value)}, not on or off` };
-  return { value, readable: true, why: `soul.yaml knowledge.harvest: ${value}` };
-}
-/** Effective = on only if the deployment says on AND the soul does not say off.
- *  A soul `on` is ignored and reported: a soul cannot switch a host on. It also
- *  hides the host's value (the kernel's merged `harvest` is then the soul's),
- *  so with a soul `on` the switch stays off until the soul drops the line. */
-/** OATS_SETTINGS_ORIGINS (kernel 0.29.0): JSON pointer → { kind, at } of the LAST
- *  layer that set each leaf. {} when absent or unreadable. */
-export function parseOrigins(text = process.env.OATS_SETTINGS_ORIGINS) {
-  try { const o = JSON.parse(text || '{}'); return o && typeof o === 'object' && !Array.isArray(o) ? o : {}; } catch { return {}; }
-}
-/** okf 4.0.1: origins name the last layer only, and the host's settings merge
- *  AFTER the soul's slot, so a host `harvest: on` hides a soul's `off` there.
- *  soul.yaml therefore stays the authority for the absolute opt-out; origins
- *  are an extra signal: a merged value whose origin is the soul is never the
- *  deployment switching harvest on (a soul `on` is ignored, a soul `off` is off). */
-export function harvestSwitch({ settings = {}, soulDir = process.env.OATS_SOUL, origins = parseOrigins() } = {}) {
-  const origin = origins?.['/harvest'] && typeof origins['/harvest'] === 'object' ? origins['/harvest'] : null;
-  const fromSoul = origin?.kind === 'soul';
-  const deployment = !fromSoul && VALUES.includes(settings.harvest) ? settings.harvest : 'off';
-  const soul = soulHarvest(soulDir);
-  if (fromSoul && VALUES.includes(settings.harvest) && soul.value === null) Object.assign(soul, { value: settings.harvest, readable: true, why: `OATS_SETTINGS_ORIGINS: harvest: ${settings.harvest} came from the soul (${String(origin.at || 'soul.yaml')})` });
-  const rows = [
-    { layer: 'deployment', value: deployment, ...(origin ? { origin: origin.kind } : {}), why: fromSoul ? 'the merged harvest value came from the soul, so the deployment does not switch harvest on' : settings.harvest === undefined ? 'harvest is not set (default off)' : `settings.oats.okf.harvest: ${settings.harvest}` },
-    { layer: 'soul', value: soul.value, readable: soul.readable, why: soul.why },
-  ];
-  const warnings = [];
-  if (soul.value === 'on') warnings.push('the soul says harvest: on, which is ignored: only the deployment can switch harvest on; a soul may only opt out with harvest: off');
-  let effective = 'off', reason;
-  if (soul.value === 'on') reason = "the soul's harvest: on is ignored and hides the deployment's own value; remove it from soul.yaml (a soul may only opt out)";
-  else if (deployment !== 'on') reason = 'the deployment does not switch harvest on (oats-local.yaml settings.oats.okf.harvest)';
-  else if (!soul.readable) reason = `the soul's opt-out could not be read (${soul.why}); unreadable counts as off`;
-  else if (soul.value === 'off') reason = 'the soul opts out (knowledge: { harvest: off }), which the deployment cannot override';
-  else { effective = 'on'; reason = 'the deployment switches harvest on and the soul does not opt out'; }
-  return { effective, reason, rows, warnings };
-}
-/** The home's record that it was spawned with harvest off (no source registered). */
-export const instanceRecordPath = (home) => join(home, '.okf-instance.json');

package/capabilities/oats-okf/lib/inspection.mjs

@@ -1,119 +0,0 @@
-import { fs, join, dirname, safePath, fail, oats } from './io.mjs';
-import { markerPath, loadStatus } from './sources.mjs';
-import { qualifiedSoulIdentity } from './source-contract.mjs';
-
-// Keep the v1 labeled-document contract, including its explicit per-document
-// preview cap. The JSON envelope itself must drain in full through stdout.
-const DOCUMENT_BYTES = 256 * 1024;
-const missing = e => e.code === 'ENOENT' || e.code === 'ENOTDIR';
-function regular(file, limit) {
-  safePath(file);
-  let stat;try { stat=fs.lstatSync(file); } catch(e) { if(missing(e)) return null;throw e; }
-  if(!stat.isFile() || stat.nlink!==1) fail('E_PATH',`inspection requires a single-link regular file: ${file}`);
-  const fd=fs.openSync(file,fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK);
-  try {
-    const opened=fs.fstatSync(fd);
-    if(!opened.isFile() || opened.nlink!==1 || opened.dev!==stat.dev || opened.ino!==stat.ino) fail('E_PATH',`inspection file changed: ${file}`);
-    if(limit===undefined) return {text:fs.readFileSync(fd,'utf8')};
-    const bytes=Buffer.alloc(Math.min(opened.size,limit));let length=0;
-    while(length<bytes.length) { const n=fs.readSync(fd,bytes,length,bytes.length-length,null);if(!n) break;length+=n; }
-    const truncated=opened.size>limit;
-    let text=bytes.subarray(0,length).toString('utf8');
-    if(truncated && text.endsWith('\uFFFD')) text=text.slice(0,-1);
-    return {text,...(truncated?{truncated:true,bytes:opened.size}:{})};
-  } finally {fs.closeSync(fd);}
-}
-function identityJSON(text,label) {
-  // JSON.parse diagnostics may include raw input from a replacement home.
-  // Report the failed verification, never those untrusted bytes.
-  try {return JSON.parse(text);} catch {fail('E_SOURCE',`invalid ${label} JSON in source home`);}
-}
-function liveHome(source,status) {
-  if(status.retired) return {available:false,reason:'retired'};
-  try {
-    safePath(source.home);
-    const stat=fs.lstatSync(source.home);
-    if(!stat.isDirectory()) return {available:false,reason:'identity-mismatch'};
-    const marker=regular(markerPath(source.home));
-    if(!marker) return {available:false,reason:'missing-marker'};
-    const m=identityJSON(marker.text,'source marker');
-    // Never load a replacement descriptor or trust the invoking home/env when
-    // inspecting an explicitly selected durable source.
-    if(m?.version!==1 || m.id!==source.id || m.source!==source.file) return {available:false,reason:'identity-mismatch'};
-    const metadata=regular(join(source.home,'instance.json'));
-    if(metadata) {
-      const meta=identityJSON(metadata.text,'instance metadata');
-      if(meta?.instance!==source.instance || meta.agent!==source.agent) return {available:false,reason:'identity-mismatch'};
-    }
-    return {available:true,reason:'live',dev:stat.dev,ino:stat.ino};
-  } catch(e) {
-    if(missing(e)) return {available:false,reason:'missing-home'};
-    // Unsafe/unreadable identity is not proof of a live source. Durable state
-    // remains inspectable, but no document from that home may be returned.
-    return {available:false,reason:'unverified-home',error:{code:e.code || 'E_SOURCE',message:e.message}};
-  }
-}
-export function workingDocuments(source,status=loadStatus(source)) {
-  const before=liveHome(source,status),observedAt=new Date().toISOString();
-  const unavailable=state=>({liveMemory:{available:false,reason:state.reason,observedAt,...(state.error?{error:state.error}:{})},documents:[]});
-  if(!before.available) return unavailable(before);
-  const documents=[];
-  const doc=(label,file)=>{
-    const content=regular(file,DOCUMENT_BYTES);
-    if(content) documents.push({label,kind:'markdown',path:file,...content});
-  };
-  let error;
-  try {
-    doc('Working state (STATE.md)',join(source.home,'STATE.md'));
-    doc('Log (log.md)',join(source.home,'log.md'));
-    const notes=safePath(join(source.home,'notes'));
-    function walk(dir,prefix='') {
-      let entries;try {entries=fs.readdirSync(dir,{withFileTypes:true});} catch(e) {if(e.code==='ENOENT') return;throw e;}
-      for(const entry of entries.sort((a,b)=>a.name<b.name?-1:a.name>b.name?1:0)) {
-        const name=prefix+entry.name,file=join(dir,entry.name);
-        // No symlink traversal, including directories or non-Markdown aliases.
-        safePath(file);
-        if(entry.isDirectory()) walk(file,name+'/');
-        else if(entry.name.endsWith('.md')) doc(`Pending note: ${name}`,file);
-      }
-    }
-    walk(notes);
-  } catch(e) {error=e;}
-  const after=liveHome(source,loadStatus(source));
-  if(!after.available) return unavailable(after);
-  if(before.dev!==after.dev || before.ino!==after.ino) return unavailable({reason:'home-changed'});
-  if(error) fail(error.code==='E_PATH'?'E_PATH':'E_INSPECT_FAILED',error.message);
-  return {liveMemory:{available:true,reason:'live',observedAt},documents};
-}
-export function capturedAuthority(source) {
-  const fields=['registration','providerBinding','sourceIdentity','executionBinding','responsibleHuman'],present=fields.filter(key=>Object.hasOwn(source,key));
-  const base={schemaVersion:1};
-  if(!present.length) return {...base,registration:'legacy',capture:'unknown',migrationRequired:true,responsibleHuman:{status:'unknown'}};
-  const binding=source.executionBinding,identity=source.sourceIdentity,complete=source.registration?.schemaVersion===1 && source.registration.kind==='captured'
-    && source.providerBinding && typeof source.providerBinding==='object' && identity && typeof identity==='object' && !Array.isArray(identity)
-    && binding?.schemaVersion===1 && typeof binding.deployment==='string' && binding.resolution?.schemaVersion===1 && typeof binding.resolution.id==='string'
-    && Object.hasOwn(source,'responsibleHuman');
-  const invalid={...base,registration:'invalid',capture:'invalid',migrationRequired:true,responsibleHuman:{status:'unknown'}};
-  if(!complete) return invalid;
-  try {if(Buffer.byteLength(JSON.stringify({identity,binding}))>64*1024) return invalid;qualifiedSoulIdentity(identity);} catch {return invalid;}
-  return {...base,registration:'captured',capture:'recorded',migrationRequired:false,sourceIdentity:JSON.parse(JSON.stringify(identity)),executionBinding:JSON.parse(JSON.stringify(binding)),
-    responsibleHuman:{status:source.responsibleHuman===null?'disabled':'specified'}};
-}
-/** A ./knowledge/ snapshot written by okf 2.x. okf 3.0.0 never reads it
- *  (knowledge is consulted remotely) and never deletes it. */
-export function legacyLocalView(source,status=loadStatus(source)) {
-  if(!liveHome(source,status).available) return null;
-  const path=join(safePath(source.home),'knowledge');let stat;
-  try {stat=fs.lstatSync(path);} catch(e) {if(missing(e)) return null;throw e;} // never follow it
-  return {status:'legacy-local-view',path,ignored:true,...(stat.isSymbolicLink()?{symlink:true}:{}),note:'okf 3.0.0 ignores this okf 2.x snapshot and reads knowledge remotely; it is safe to delete by hand'};
-}
-export function inspect(source) {
-  const status=loadStatus(source),working=workingDocuments(source,status),legacy=legacyLocalView(source,status);
-  let health;try {health=oats(['schedule','list','--dir',source.context,'--json'],source.context).scheduler;} catch(e) {health={active:false,error:e.message};}
-  const documents=[...working.documents,{label:'Durable processing receipts',kind:'text',path:join(dirname(source.file),'status.json'),text:JSON.stringify(status,null,2)}];
-  return {
-    summary:`OKF ${source.id}: ${status.captured.inputs.length-status.processed.length} unprocessed inputs; ${status.retired?'source retired':'source not retired'}; ${working.liveMemory.available?`${working.documents.length} working-memory documents`:`live memory unavailable (${working.liveMemory.reason})`}${legacy?'; legacy-local-view ./knowledge/ (ignored, safe to delete)':''}`,
-    source:source.file,owns:source.decl.owns,reads:source.decl.reads,bases:source.bindings.bases,authority:capturedAuthority(source),
-    acceptedView:source.acceptedView,legacyLocalView:legacy,status,scheduler:health,liveMemory:working.liveMemory,documents
-  };
-}

package/capabilities/oats-okf/lib/invocation-context.mjs

@@ -1,111 +0,0 @@
-// Execution-only consumer of the kernel-owned generic snapshot. This module
-// never reads a kernel index, mints identity, discovers source/config, or grants
-// native authority from structural validation alone. Check remains stdin-only.
-import fs from 'node:fs';
-import { dirname, isAbsolute, resolve } from 'node:path';
-import { BINDING_WIRE_LIMITS, parseBindingJson, sourceRuntimeFromKnowledgeBinding } from './binding-wire.mjs';
-import { INVOCATION_LIMITS, validateInvocationShape, sameInvocationJson } from './invocation-shape.mjs';
-import { validateCapturedReceipt } from './sources.mjs';
-
-const CAPABILITY='oats.okf';
-export const INVOCATION_CONTEXT_LIMITS=INVOCATION_LIMITS;
-const SOURCE_RECEIPT_LIMITS=Object.freeze({bytes:256*1024,depth:32,entries:16384});
-const invalid=()=>{throw Object.assign(new Error('invalid captured OKF invocation context'),{code:'E_INVOCATION'});};
-function absolute(value) {return typeof value==='string' && !value.includes('\0') && isAbsolute(value) && resolve(value)===value;}
-function noLinks(file) {
-  for(let path=file;;path=dirname(path)) {
-    const stat=fs.lstatSync(path);
-    if(stat.isSymbolicLink() || (path!==file && !stat.isDirectory())) invalid();
-    if(dirname(path)===path) return;
-  }
-}
-function readPrivateJson(file,limits) {
-  if(!absolute(file)) invalid();let fd;
-  try {
-    noLinks(file);
-    const uid=typeof process.getuid==='function'?process.getuid():null;
-    const privateFile=stat=>stat.isFile() && stat.nlink===1n && stat.size<=BigInt(limits.bytes) && (stat.mode&0o7777n)===0o600n && (uid===null || stat.uid===BigInt(uid));
-    const before=fs.lstatSync(file,{bigint:true});
-    const same=stat=>privateFile(stat) && ['dev','ino','size','mtimeNs','ctimeNs'].every(key=>stat[key]===before[key]);
-    if(!privateFile(before) || typeof fs.constants.O_NOFOLLOW!=='number' || typeof fs.constants.O_NONBLOCK!=='number') invalid();
-    fd=fs.openSync(file,fs.constants.O_RDONLY|fs.constants.O_NOFOLLOW|fs.constants.O_NONBLOCK);
-    noLinks(file);
-    if(!same(fs.fstatSync(fd,{bigint:true})) || !same(fs.lstatSync(file,{bigint:true}))) invalid();
-    const bytes=Buffer.alloc(Number(before.size));
-    for(let offset=0;offset<bytes.length;) {
-      const count=fs.readSync(fd,bytes,offset,bytes.length-offset,offset);
-      if(!count) invalid();offset+=count;
-    }
-    noLinks(file);
-    if(!same(fs.fstatSync(fd,{bigint:true})) || !same(fs.lstatSync(file,{bigint:true}))) invalid();
-    return parseBindingJson(bytes,limits);
-  } catch {invalid();}
-  finally {if(fd!==undefined) fs.closeSync(fd);}
-}
-export function validateOkfInvocationContext(value,binding) {
-  try {
-    sourceRuntimeFromKnowledgeBinding(binding);
-    return validateInvocationShape(value,{capability:CAPABILITY});
-  } catch {invalid();}
-}
-export function loadCapturedOkfInvocation(env=process.env) {
-  const hasContext=Object.hasOwn(env,'OATS_INVOCATION_CONTEXT_FILE'),hasBinding=Object.hasOwn(env,'OATS_BINDING_FILE');
-  if(!hasContext && !hasBinding && !Object.hasOwn(env,'OATS_SOURCE_RECEIPT_FILE')) return {kind:'legacy'};
-  if(!hasContext || !hasBinding || env.OATS_INVOCATION_CONTEXT_FILE===env.OATS_BINDING_FILE) invalid();
-  if(Object.hasOwn(env,'OATS_SOURCE_RECEIPT_FILE') && [env.OATS_INVOCATION_CONTEXT_FILE,env.OATS_BINDING_FILE].includes(env.OATS_SOURCE_RECEIPT_FILE)) invalid();
-  const binding=readPrivateJson(env.OATS_BINDING_FILE,BINDING_WIRE_LIMITS);
-  const context=validateOkfInvocationContext(readPrivateJson(env.OATS_INVOCATION_CONTEXT_FILE,INVOCATION_CONTEXT_LIMITS),binding);
-  return {kind:'captured',file:env.OATS_INVOCATION_CONTEXT_FILE,bindingFile:env.OATS_BINDING_FILE,binding,context};
-}
-export function loadOkfSourceReceiptInput(loaded,env=process.env) {
-  if(!Object.hasOwn(env,'OATS_SOURCE_RECEIPT_FILE')) return {mode:'absent'};
-  if([loaded.file,loaded.bindingFile].includes(env.OATS_SOURCE_RECEIPT_FILE)) invalid();
-  const receipt=readPrivateJson(env.OATS_SOURCE_RECEIPT_FILE,SOURCE_RECEIPT_LIMITS);
-  assertOkfSourceReceiptContext(receipt,loaded.context,loaded.binding);
-  return {mode:'captured',receipt};
-}
-// Explicit compatibility for a source already validated/loaded from durable
-// storage. This cannot construct a source or supply generic admission authority.
-export function assertOkfRegisteredSourceReplay(source,binding) {
-  try {sourceRuntimeFromKnowledgeBinding(binding);} catch {invalid();}
-  if(!source?.file || source.registration?.schemaVersion!==1 || source.registration.kind!=='captured' || !sameInvocationJson(source.providerBinding,binding)) invalid();
-}
-export function assertOkfInvocationAction(context,event,manifest) {
-  try {validateInvocationShape(context,{capability:CAPABILITY});} catch {invalid();}
-  const action=context.action;
-  if(manifest?.capability!==CAPABILITY) invalid();
-  if(action.kind==='hook') {
-    if(action.capability!==CAPABILITY || action.name!==event || !Object.hasOwn(manifest.hooks||{},event)) invalid();
-  } else if(action.kind==='command') {
-    if(action.name!==event || !Object.hasOwn(manifest.commands||{},event) || (action.capability!==CAPABILITY && action.namespace!==manifest.command)) invalid();
-  } else if(action.kind==='operation') {
-    if(action.slot!==manifest.layer || !Object.hasOwn(manifest.operations||{},action.name) || manifest.operations[action.name].command!==event) invalid();
-  } else invalid();
-}
-export function requireOkfAdmittedAction(context) {
-  try {validateInvocationShape(context,{capability:CAPABILITY});} catch {invalid();}
-  if(!context.instance || !context.intent) throw Object.assign(new Error('captured action requires an admitted instance intent'),{code:'E_ADMISSION'});
-  // The shared shape enforces incarnation equality; the kernel, not this
-  // provider, proves that the supplied attempt is currently admitted/running.
-}
-export function assertOkfSourceReceiptContext(receipt,context,binding) {
-  validateOkfInvocationContext(context,binding);
-  try {validateCapturedReceipt(context.instance?.home,receipt);} catch {invalid();}
-  const instance=context.instance;
-  if(!instance || context.action.kind!=='hook' || !['spawn','retire'].includes(context.action.name)
-    || receipt.kind!==context.subject.kind || receipt.home!==instance.home || receipt.work!==instance.work
-    || receipt.agent!==instance.agent || receipt.instance!==instance.name || receipt.context!==context.executionBinding.deployment
-    || !sameInvocationJson(receipt.executionBinding,context.executionBinding) || !sameInvocationJson(receipt.responsibleHuman,context.responsibleHuman)
-    || !sameInvocationJson(receipt.binding,binding)) invalid();
-  const identity=context.subject.kind==='persistent'?context.subject.soul.identity:null;
-  if(!sameInvocationJson(receipt.sourceIdentity,identity)) invalid();
-}
-export function assertOkfSourceContext(source,context,binding) {
-  validateOkfInvocationContext(context,binding);
-  if(!source) invalid();
-  if(context.subject.kind!=='persistent' || source.agent!==context.subject.soul.alias
-    || !sameInvocationJson(source.sourceIdentity,context.subject.soul.identity) || !sameInvocationJson(source.providerBinding,binding)
-    || !sameInvocationJson(source.executionBinding,context.executionBinding) || source.context!==context.executionBinding.deployment
-    || !sameInvocationJson(source.responsibleHuman,context.responsibleHuman)) invalid();
-  if(context.instance && (source.home!==context.instance.home || source.work!==context.instance.work || source.instance!==context.instance.name || source.agent!==context.instance.agent)) invalid();
-}

package/capabilities/oats-okf/lib/invocation-shape.mjs

@@ -1,135 +0,0 @@
-// Provider-side consumption checks for the kernel-owned CapturedInvocationContext1.
-// Decoded JSON only: no source/config parsing, artifact lookup or authorization.
-// The kernel must verify retained authority before invoking provider code.
-import { isAbsolute, join, resolve } from 'node:path';
-export const INVOCATION_LIMITS=Object.freeze({bytes:512*1024,depth:32,entries:16384});
-export const PRIOR_RECEIPT_LIMITS=Object.freeze({bytes:128*1024,depth:24,entries:8192});
-const fail=()=>{throw Object.assign(new Error('invalid captured invocation'),{code:'invalid-binding'});};
-const obj=value=>value!==null && typeof value==='object' && !Array.isArray(value);
-const canonical=value=>value===null || typeof value!=='object'?JSON.stringify(value):Array.isArray(value)?`[${value.map(canonical).join(',')}]`:`{${Object.keys(value).sort().map(key=>`${JSON.stringify(key)}:${canonical(value[key])}`).join(',')}}`;
-export const sameInvocationJson=(a,b)=>canonical(a)===canonical(b);
-const same=sameInvocationJson;
-function keys(value,allowed,required=allowed) {if(!obj(value)) fail();for(const key of Object.keys(value)) if(!allowed.includes(key)) fail();for(const key of required) if(!Object.hasOwn(value,key)) fail();}
-function text(value,empty=false) {if(typeof value!=='string' || (!empty && !value.length) || value.includes('\0')) fail();}
-function list(value) {if(!Array.isArray(value)) fail();return value;}
-function absolute(value) {text(value);if(!isAbsolute(value) || resolve(value)!==value) fail();}
-function path(value,root=false) {text(value);if(root && value==='.') return;if(value.startsWith('/') || value.includes('\\') || value.split('/').some(part=>!part || part==='.' || part==='..')) fail();}
-function hash(value) {if(typeof value!=='string' || !/^sha256-[a-f0-9]{64}$/.test(value)) fail();}
-function integrity(value,format) {keys(value,['format','value']);if(value.format!==format) fail();hash(value.value);}
-function capability(value) {text(value);if(!/^(?:@?[a-z0-9][a-z0-9._-]*[./])[a-z0-9][a-z0-9._/-]*$/.test(value)) fail();}
-function repository(value) {
-  if(value?.kind==='canonical-remote') {keys(value,['kind','remote']);text(value.remote);}
-  else if(value?.kind==='provider-repository') {keys(value,['kind','provider','host','id']);text(value.provider);text(value.host);text(value.id);}
-  else fail();
-}
-function soulIdentity(value) {
-  if(value?.kind==='git-soul') {keys(value,['kind','repository','exportPath']);repository(value.repository);path(value.exportPath);}
-  else if(value?.kind==='local-soul') {keys(value,['kind','source','exportPath']);text(value.source);if(!value.source.startsWith('path:')) fail();path(value.exportPath,true);}
-  else fail();
-}
-function artifact(value) {
-  if(value?.kind==='soul') {keys(value,['kind','identity','integrity']);soulIdentity(value.identity);}
-  else if(value?.kind==='capability') {keys(value,['kind','capability','integrity']);capability(value.capability);}
-  else if(value?.kind==='resource') keys(value,['kind','integrity']);
-  else fail();
-  integrity(value.integrity,'oats.tree-exec.v1');
-}
-function resolution(value) {keys(value,['schemaVersion','id']);if(value.schemaVersion!==1) fail();hash(value.id);}
-function incarnation(value) {if(typeof value!=='string' || !/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(value)) fail();}
-function intent(value,instance) {
-  if(value===null) return;
-  keys(value,['schemaVersion','executionId','incarnationId','attempt']);incarnation(value.incarnationId);
-  if(value.schemaVersion!==1 || typeof value.executionId!=='string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(value.executionId) || !Number.isSafeInteger(value.attempt) || value.attempt<1) fail();
-  if(instance===null || value.incarnationId!==instance.incarnationId) fail();
-}
-function origin(value) {
-  keys(value,['kind','document','pointer','span'],['kind','document','pointer']);
-  if(!['soul-requirement','soul-default','workspace-default','import-adoption','operator','package-dependency','work-target','migration-evidence','provider-binding','workspace-admission','member-backlink','source-export','manifest-default'].includes(value.kind)) fail();
-  text(value.pointer,true);if(!/^(?:\/(?:[^~]|~[01])*)*$/.test(value.pointer)) fail();
-  const doc=value.document;
-  if(doc?.kind==='source') {keys(doc,['kind','source','revision','path','integrity']);text(doc.source);text(doc.revision);path(doc.path);integrity(doc.integrity,'oats.bytes.v1');}
-  else if(doc?.kind==='deployment') {keys(doc,['kind','path','integrity']);path(doc.path);integrity(doc.integrity,'oats.bytes.v1');}
-  else if(doc?.kind==='operator') {keys(doc,['kind','id']);text(doc.id);}
-  else if(doc?.kind==='record') {keys(doc,['kind','ref']);resolution(doc.ref);}
-  else if(doc?.kind==='artifact') {keys(doc,['kind','owner','path','integrity']);artifact(doc.owner);path(doc.path);integrity(doc.integrity,'oats.bytes.v1');}
-  else fail();
-  if(Object.hasOwn(value,'span')) {keys(value.span,['start','end']);if(!Number.isSafeInteger(value.span.start) || !Number.isSafeInteger(value.span.end) || value.span.start<0 || value.span.end<value.span.start) fail();}
-}
-function origins(value) {list(value).forEach(origin);}
-function subject(value) {
-  if(value?.kind==='helper') {
-    keys(value,['kind','provider','definition','name']);artifact(value.provider);
-    keys(value.definition,['owner','path','kind']);artifact(value.definition.owner);path(value.definition.path,true);
-    if(value.provider.kind!=='capability' || !same(value.provider,value.definition.owner) || !['file','directory','manifest','skill','runtime-package'].includes(value.definition.kind)) fail();
-    if(typeof value.name!=='string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(value.name)) fail();return value.name;
-  }
-  if(value?.kind!=='persistent') fail();keys(value,['kind','soul']);const s=value.soul;
-  keys(s,['identity','revision','alias','sourceArtifact','definition','projection']);soulIdentity(s.identity);artifact(s.sourceArtifact);
-  if(s.sourceArtifact.kind!=='soul' || !same(s.identity,s.sourceArtifact.identity)) fail();
-  if(typeof s.alias!=='string' || !/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(s.alias)) fail();path(s.definition);
-  keys(s.projection,['roots']);list(s.projection.roots).forEach(value=>path(value,true));
-  if(!s.projection.roots.length || !s.projection.roots.some(root=>root==='.' || s.definition===root || s.definition.startsWith(`${root}/`))) fail();
-  for(let i=1;i<s.projection.roots.length;i++) if(Buffer.compare(Buffer.from(s.projection.roots[i-1]),Buffer.from(s.projection.roots[i]))>=0) fail();
-  if(s.identity.exportPath!=='.' && !s.definition.startsWith(`${s.identity.exportPath}/`)) fail();
-  const r=s.revision;
-  if(r?.kind==='local') {
-    keys(r,['kind','source','integrity','provenance','repository'],['kind','source','integrity','provenance']);text(r.source);if(!r.source.startsWith('path:')) fail();integrity(r.integrity,'oats.tree-exec.v1');
-    if(!same(r.integrity,s.sourceArtifact.integrity)) fail();
-    if(s.identity.kind==='local-soul') {if(r.source!==s.identity.source || Object.hasOwn(r,'repository')) fail();}
-    else {repository(r.repository);if(!same(r.repository,s.identity.repository)) fail();}
-  } else {
-    keys(r,['identity','remote','selector','commit','provenance']);repository(r.identity);text(r.remote);text(r.selector);
-    if(s.identity.kind!=='git-soul' || !same(r.identity,s.identity.repository) || !/^[a-f0-9]{40}$/.test(r.commit)) fail();
-    if(r.identity.kind==='canonical-remote' && r.identity.remote!==r.remote) fail();
-  }
-  origins(r.provenance);if(!r.provenance.length) fail();return s.alias;
-}
-function context(value) {
-  if(value?.kind==='workspace') {keys(value,['kind','identity','observation']);keys(value.identity,['repository','path']);repository(value.identity.repository);if(value.identity.path!=='oats-workspace.yaml') fail();origin(value.observation);return {kind:'workspace',identity:value.identity};}
-  if(value?.kind==='standalone') {keys(value,['kind','key']);if(value.key!==null) text(value.key);return value;}
-  fail();
-}
-function human(value) {if(value===null) return;keys(value,['provider','id']);text(value.provider);text(value.id);}
-function messaging(value,selectedContext,responsibleHuman) {
-  if(value?.enabled===false) {keys(value,['schemaVersion','enabled']);if(responsibleHuman!==null) fail();}
-  else {
-    keys(value,['schemaVersion','enabled','privateKey','wider','provenance']);if(value.enabled!==true) fail();
-    keys(value.privateKey,['provider','human','context']);capability(value.privateKey.provider);human(value.privateKey.human);
-    if(value.privateKey.human===null || !same(value.privateKey.human,responsibleHuman) || !same(value.privateKey.context,selectedContext) || (selectedContext.kind==='standalone' && selectedContext.key===null)) fail();
-    list(value.wider).forEach(row=>{keys(row,['provider','id']);text(row.id);if(row.provider!==value.privateKey.provider) fail();});
-    for(let i=1;i<value.wider.length;i++) if(Buffer.compare(Buffer.from(canonical(value.wider[i-1])),Buffer.from(canonical(value.wider[i])))>=0) fail();
-    origins(value.provenance);
-  }
-  if(value.schemaVersion!==1) fail();
-}
-function action(value) {
-  if(!obj(value)) fail();
-  if(value.kind==='command') {keys(value,['kind','capability','namespace','name'],['kind','name']);if(Object.hasOwn(value,'capability')===Object.hasOwn(value,'namespace')) fail();if(value.capability!==undefined) capability(value.capability);else text(value.namespace);text(value.name);}
-  else if(value.kind==='hook') {keys(value,['kind','capability','name']);capability(value.capability);text(value.name);}
-  else if(value.kind==='operation') {keys(value,['kind','slot','name']);if(!['knowledge','messaging','tasks'].includes(value.slot)) fail();text(value.name);}
-  else if(['inspect','compose'].includes(value.kind)) keys(value,['kind']);
-  else fail();
-}
-export function assertInvocationBounds(value,limits=INVOCATION_LIMITS) {
-  let entries=0;const active=new Set();
-  const visit=(v,depth)=>{
-    if(v===null || typeof v==='string' || typeof v==='boolean') return;
-    if(typeof v==='number') {if(!Number.isFinite(v)) fail();return;}
-    if(typeof v!=='object' || depth>limits.depth || active.has(v)) fail();
-    if(!Array.isArray(v) && Object.getPrototypeOf(v)!==Object.prototype && Object.getPrototypeOf(v)!==null) fail();
-    active.add(v);for(const child of Object.values(v)) {if(++entries>limits.entries) fail();visit(child,depth+1);}active.delete(v);
-  };
-  visit(value,1);if(Buffer.byteLength(JSON.stringify(value),'utf8')>limits.bytes) fail();
-}
-export function validateInvocationShape(value,expected={}) {
-  assertInvocationBounds(value);keys(value,['schemaVersion','executionBinding','subject','instance','intent','context','responsibleHuman','messagingChoice','capability','action','priorReceipt']);
-  if(value.schemaVersion!==1) fail();keys(value.executionBinding,['schemaVersion','deployment','resolution']);if(value.executionBinding.schemaVersion!==1) fail();absolute(value.executionBinding.deployment);resolution(value.executionBinding.resolution);
-  const alias=subject(value.subject);
-  if(value.instance!==null) {keys(value.instance,['home','work','name','agent','incarnationId']);incarnation(value.instance.incarnationId);absolute(value.instance.home);absolute(value.instance.work);text(value.instance.name);text(value.instance.agent);if(value.instance.agent!==alias || value.instance.work!==join(value.instance.home,'work')) fail();}
-  intent(value.intent,value.instance);
-  const selectedContext=context(value.context);human(value.responsibleHuman);messaging(value.messagingChoice,selectedContext,value.responsibleHuman);capability(value.capability);action(value.action);assertInvocationBounds(value.priorReceipt,PRIOR_RECEIPT_LIMITS);
-  if(value.action.capability!==undefined && value.action.capability!==value.capability) fail();
-  if(value.action.kind==='hook' && value.instance===null) fail();
-  for(const field of ['capability','context','action']) if(Object.hasOwn(expected,field) && !same(value[field],expected[field])) fail();
-  return value;
-}

package/capabilities/oats-okf/lib/io.mjs

@@ -1,118 +0,0 @@
-import * as fs from 'node:fs';
-import { dirname, resolve, relative, isAbsolute, join, sep, basename } from 'node:path';
-import { createHash, randomUUID } from 'node:crypto';
-import { hostname } from 'node:os';
-import { spawnSync } from 'node:child_process';
-export { fs, join, resolve, dirname };
-export const fail = (code, message) => { throw Object.assign(new Error(message), { code }); };
-export const hash = value => createHash('sha256').update(typeof value === 'string' || Buffer.isBuffer(value) ? value : JSON.stringify(value)).digest('hex');
-export const readJSON = path => JSON.parse(fs.readFileSync(path, 'utf8'));
-export const within = (root, path) => { const r = relative(root, path); return r === '' || (!r.startsWith('..' + sep) && r !== '..' && !isAbsolute(r)); };
-// okf 4.0.1 #2: a URL's userinfo is a credential (https://user:token@host).
-// Strip it from anything shown to agents or users; an SSH user alone
-// (ssh://git@host) is not a secret and stays.
-const USERINFO = /\b([a-z][a-z0-9+.-]*:\/\/)([^\s/@'"]+)@/gi;
-export const redactUrls = text => String(text).replace(USERINFO, (m, scheme, info) => /^ssh:/i.test(scheme) && !info.includes(':') ? m : scheme);
-export const displayRepo = repository => typeof repository === 'string' ? redactUrls(repository) : repository;
-/** Whether a repository locator embeds a credential (any userinfo except a bare SSH user). */
-export const embedsCredential = repository => { USERINFO.lastIndex = 0; return typeof repository === 'string' && redactUrls(repository) !== repository; };
-export const overlaps = (a, b) => within(a, b) || within(b, a);
-export function safePath(path) {
-  path = resolve(path);
-  let part = path;
-  while (true) {
-    try { if (fs.lstatSync(part).isSymbolicLink()) fail('E_PATH', `symlink not allowed: ${part}`); }
-    catch (e) { if (e.code !== 'ENOENT') throw e; }
-    if (dirname(part) === part) break;
-    part = dirname(part);
-  }
-  return path;
-}
-export function relPath(p, dot = false) {
-  if (typeof p !== 'string' || (!dot && p === '.') || !p || p.includes('\\') || p.includes('\0') || isAbsolute(p) || p.split('/').some(x => !x || x === '..' || (x === '.' && p !== '.')) || p.split('/').some(x => x === '.git')) fail('E_PATH', `noncanonical relative path: ${p}`);
-  return p;
-}
-export function identifier(value) {
-  if (typeof value !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$/.test(value) || ['constructor','__proto__','prototype','toString','valueOf'].includes(value)) fail('E_ID', `invalid identity: ${value}`);
-  return value;
-}
-export function syncDir(dir) { const fd = fs.openSync(dir, 'r'); try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); } }
-export function atomic(path, bytes, { tempDir = dirname(path) } = {}) {
-  safePath(path); fs.mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  // Publication may stage in its owned lock directory, outside accepted data.
-  safePath(tempDir);
-  const temp = join(tempDir, `${basename(path)}.tmp-${randomUUID()}`);
-  const fd = fs.openSync(temp, 'wx', 0o600);
-  try { fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
-  fs.renameSync(temp, path); syncDir(dirname(path));
-}
-export const save = (path, obj) => atomic(path, JSON.stringify(obj, null, 2) + '\n');
-export function tree(root, { git = false } = {}) {
-  safePath(root); const files = {};
-  function walk(dir) {
-    for (const d of fs.readdirSync(dir, { withFileTypes: true }).sort((a,b) => a.name.localeCompare(b.name))) {
-      if (git && dir === root && d.name === '.git') continue;
-      const path = join(dir, d.name); safePath(path);
-      if (d.isDirectory()) walk(path);
-      else if (d.isFile()) { if (fs.statSync(path).nlink !== 1) fail('E_PATH', `hardlink not allowed: ${path}`); files[relative(root, path).split(sep).join('/')] = fs.readFileSync(path).toString('base64'); }
-      else fail('E_PATH', `unsupported entry: ${path}`);
-    }
-  }
-  walk(root); return files;
-}
-export const digest = files => hash(Object.fromEntries(Object.entries(files).sort(([a],[b])=>a.localeCompare(b))));
-export function materialize(root, files) {
-  safePath(root); fs.mkdirSync(root, { recursive: true });
-  for (const [p, content] of Object.entries(files)) atomic(join(root, relPath(p)), Buffer.from(content, 'base64'));
-}
-const pause = ms => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
-/** Cooperative directory lock. `waitMs` lets a reader queue behind a live
- *  holder for a bounded time; an abandoned lock is still never reclaimed. */
-export function withLock(path, fn, { waitMs = 0 } = {}) {
-  safePath(path); fs.mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  const deadline = Date.now() + waitMs;
-  for (let delay = 20;; delay = Math.min(delay * 2, 250)) {
-    try { fs.mkdirSync(path, { mode: 0o700 }); break; }
-    catch(e) { if(e.code !== 'EEXIST') throw e; if(Date.now() >= deadline) fail('E_LOCKED', `busy or abandoned lock: ${path}; inspect owner.json, never reclaim by age`); pause(delay); }
-  }
-  const owner = { token: randomUUID(), pid: process.pid, host: hostname() };
-  save(join(path, 'owner.json'), owner);
-  try { return fn(); } finally { if (readJSON(join(path, 'owner.json')).token === owner.token) { fs.rmSync(path, { recursive: true }); syncDir(dirname(path)); } }
-}
-export function unlock(path, token) {
-  safePath(path); const o = readJSON(join(path, 'owner.json'));
-  if (!token || o.token !== token || o.host !== hostname()) fail('E_LOCKED', 'explicit matching local lock token required');
-  try { process.kill(o.pid, 0); fail('E_LOCKED', 'lock owner is still alive'); } catch (e) { if(e.code !== 'ESRCH') throw e; }
-  fs.rmSync(path, { recursive: true }); syncDir(dirname(path)); return { unlocked: path };
-}
-export const identityKeys = ['OATS_INSTANCE','OATS_INSTANCE_HOME','OATS_HOME','PI_AGENT_HOME','PI_AGENT_NAME','PI_AGENT_INSTANCE','PI_AGENTS_ROOT','OATS_ROOT','OATS_SOUL','OATS_SOUL_ID','OATS_AGENT','OATS_KIND','OATS_EVENT','OATS_CONTEXT','OATS_REPO','OATS_WORK','OATS_BRANCH','OATS_META','OATS_SETTINGS','OATS_SETTINGS_ORIGINS','OATS_BINDING_FILE','OATS_SOURCE_RECEIPT_FILE','OATS_INVOCATION_CONTEXT_FILE','OATS_DEPLOYMENT','OATS_RESOLUTION'];
-export function cleanEnv(env = process.env) {
-  return Object.fromEntries(Object.entries(env).filter(([k]) => !/^(OATS_(?!HOME_DIR$|PACKAGE_CATALOG$)|PI_AGENT|GIT_)/.test(k)));
-}
-export function exec(bin, args, { cwd, env = cleanEnv(), timeout = 30000, maxBuffer = 16*1024*1024, acceptedStatus = [0] } = {}) {
-  const r = spawnSync(bin, args, { cwd, env, encoding: 'utf8', timeout, maxBuffer });
-  if(r.error || !acceptedStatus.includes(r.status)) throw Object.assign(new Error(`${bin} ${args[0]} failed: ${r.error?.message || r.stderr || `exit ${r.status}`}`),{code:'E_COMMAND',stdout:r.stdout,status:r.status});
-  return r.stdout.trim();
-}
-export function cliPath() {
-  const p = process.env.OATS_CLI_BIN;
-  if (!p || !isAbsolute(p)) fail('E_RUNTIME', 'absolute OATS_CLI_BIN required; never resolve oats on PATH');
-  return p;
-}
-export function oats(args, cwd, { native = false, ...opts } = {}) {
-  let text;
-  try {text = exec(cliPath(), args, { cwd, ...opts });}
-  catch(e) {
-    let response;try {response=JSON.parse(e.stdout);} catch { /* unknown side effect, preserve command failure */ }
-    if(response?.schemaVersion===1 && response.ok===false) fail(response.error?.code || 'E_RUNTIME',response.error?.message || 'CLI failed');
-    throw e;
-  }
-  let o; try { o = JSON.parse(text); } catch { fail('E_RUNTIME', 'unsupported CLI JSON response'); }
-  if(native) return o;
-  if(o.schemaVersion !== 1 || o.ok !== true) fail(o.error?.code || 'E_RUNTIME', o.error?.message || 'unsupported CLI envelope');
-  return o.result;
-}
-export const quote = v => `'${String(v).replaceAll("'", "'\\''")}'`;
-export function command(cwd, argv) {
-  return `cd ${quote(cwd)} && env ${identityKeys.map(k => `-u ${quote(k)}`).join(' ')} ${[cliPath(), ...argv].map(quote).join(' ')}`;
-}