@awebai/oats 0.30.0 → 0.30.2

package/capabilities/oats-okf/lib/binding-wire.mjs

@@ -1,380 +0,0 @@
-import { TextDecoder } from 'node:util';
-import { tmpdir } from 'node:os';
-import { isAbsolute, join, resolve } from 'node:path';
-import { fs, safePath } from './io.mjs';
-import {
-  KNOWLEDGE_CONTRACT,
-  KNOWLEDGE_CONTRACT_VERSION,
-  bindKnowledgeDomain,
-  bindingChoiceKey,
-  checkKnowledgeRuntime,
-  normalizeKnowledgeBindingCandidates,
-  normalizeKnowledgeDeclaration,
-  renderKnowledgeRuntime,
-  sameJson,
-} from './portable-binding.mjs';
-import { declaration as soulDeclaration, loadBindings, validateBindings } from './config.mjs';
-import { stageBase, validateBase } from './stores.mjs';
-
-export const BINDING_WIRE_LIMITS=Object.freeze({bytes:1024*1024,depth:32,entries:16384});
-const CAPABILITY='oats.okf',SLOT='knowledge';
-const phases=new Set(['normalize','bind','check']);
-const unsupportedCapturedCommands=new Set(['setup','init','migrate','unlock']);
-const declarationKinds=new Set(['soul','workspace','adoption','operator']);
-const errorCodes=new Set(['needs-configuration','requirement-conflict','invalid-binding','authorization-required','host-requirement-missing','provider-unavailable','provider-not-qualified']);
-const obj=value=>value!==null && typeof value==='object' && !Array.isArray(value);
-const wireError=code=>{throw Object.assign(new Error(code),{wireCode:code});};
-// Private diagnostic marker and closed literal vocabulary. Never serialize a
-// caught exception's message, supplied value, path, alias or unknown key.
-const settingDiagnostic=Symbol('runtime-setting-diagnostic');
-const settingMessages=Object.freeze({
-  'bindings-file:missing':'setting bindings-file is required (absolute host path)',
-  'bindings-file:invalid':'setting bindings-file must be a normalized absolute host path',
-  'state-dir:missing':'setting state-dir is required (absolute host path)',
-  'state-dir:invalid':'setting state-dir must be a normalized absolute host path',
-  'harvest-runtime:missing':'setting harvest-runtime is required (pi, claude or codex)',
-  'harvest-runtime:invalid':'setting harvest-runtime must be pi, claude or codex',
-  'harvest-model:invalid':'setting harvest-model must be null or a non-empty string',
-});
-function settingError(reason) {
-  if(!Object.hasOwn(settingMessages,reason)) wireError('invalid-binding');
-  throw Object.assign(new Error('needs-configuration'),{wireCode:'needs-configuration',[settingDiagnostic]:settingMessages[reason]});
-}
-function keys(value,allowed,required,label) {
-  if(!obj(value)) wireError('invalid-binding');
-  for(const key of Object.keys(value)) if(!allowed.includes(key)) wireError('invalid-binding');
-  for(const key of required) if(!Object.hasOwn(value,key)) wireError('invalid-binding');
-  return value;
-}
-function absolute(value) {return typeof value==='string' && isAbsolute(value) && resolve(value)===value;}
-
-class StrictJsonParser {
-  constructor(text,{depth,entries}) {this.text=text;this.maxDepth=depth;this.maxEntries=entries;this.at=0;this.entries=0;}
-  whitespace() {while(/[\u0009\u000a\u000d\u0020]/.test(this.text[this.at] || '')) this.at++;}
-  count() {if(++this.entries>this.maxEntries) wireError('invalid-binding');}
-  string() {
-    if(this.text[this.at]!=='"') wireError('invalid-binding');
-    const start=this.at++;
-    while(this.at<this.text.length) {
-      const code=this.text.charCodeAt(this.at++);
-      if(code===0x22) {try{return JSON.parse(this.text.slice(start,this.at));}catch{wireError('invalid-binding');}}
-      if(code<0x20) wireError('invalid-binding');
-      if(code===0x5c) {
-        const escaped=this.text[this.at++];
-        if(escaped==='u') {if(!/^[0-9a-fA-F]{4}$/.test(this.text.slice(this.at,this.at+4))) wireError('invalid-binding');this.at+=4;}
-        else if(!'"\\/bfnrt'.includes(escaped || '')) wireError('invalid-binding');
-      }
-    }
-    wireError('invalid-binding');
-  }
-  value(depth=1) {
-    this.whitespace();const char=this.text[this.at];
-    if(char==='"') return this.string();
-    if(char==='{') {
-      if(depth>this.maxDepth) wireError('invalid-binding');this.at++;this.whitespace();
-      const result=Object.create(null),seen=new Set();if(this.text[this.at]==='}') {this.at++;return result;}
-      while(true) {
-        this.whitespace();const key=this.string();if(seen.has(key)) wireError('invalid-binding');seen.add(key);this.count();
-        this.whitespace();if(this.text[this.at++]!==':') wireError('invalid-binding');result[key]=this.value(depth+1);this.whitespace();
-        const next=this.text[this.at++];if(next==='}') return result;if(next!==',') wireError('invalid-binding');
-      }
-    }
-    if(char==='[') {
-      if(depth>this.maxDepth) wireError('invalid-binding');this.at++;this.whitespace();
-      const result=[];if(this.text[this.at]===']') {this.at++;return result;}
-      while(true) {this.count();result.push(this.value(depth+1));this.whitespace();const next=this.text[this.at++];if(next===']') return result;if(next!==',') wireError('invalid-binding');}
-    }
-    for(const [token,value] of [['true',true],['false',false],['null',null]]) if(this.text.startsWith(token,this.at)) {this.at+=token.length;return value;}
-    const match=/^-?(?:0|[1-9][0-9]*)(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?/.exec(this.text.slice(this.at));
-    if(!match) wireError('invalid-binding');this.at+=match[0].length;const number=Number(match[0]);if(!Number.isFinite(number)) wireError('invalid-binding');return number;
-  }
-  parse() {this.whitespace();const value=this.value();this.whitespace();if(this.at!==this.text.length) wireError('invalid-binding');return value;}
-}
-
-export function parseBindingJson(bytes,limits=BINDING_WIRE_LIMITS) {
-  if(!Buffer.isBuffer(bytes)) bytes=Buffer.from(bytes);
-  if(bytes.length>limits.bytes) wireError('invalid-binding');
-  let text;try{text=new TextDecoder('utf-8',{fatal:true}).decode(bytes);}catch{wireError('invalid-binding');}
-  return new StrictJsonParser(text,limits).parse();
-}
-
-function request(value,phase) {
-  keys(value,['schemaVersion','phase','slot','capability','settings','input'],['schemaVersion','phase','slot','capability','settings','input'],'binding request');
-  if(value.schemaVersion!==1 || value.phase!==phase || value.slot!==SLOT || value.capability!==CAPABILITY || !obj(value.settings)) wireError('invalid-binding');
-  return value;
-}
-function declaration(value) {
-  keys(value,['kind','value','origin','origins'],['kind','value','origin','origins'],'provider declaration');
-  if(!declarationKinds.has(value.kind) || !obj(value.value) || !obj(value.origin) || !obj(value.origins)) wireError('invalid-binding');
-  return value;
-}
-function contract(value,{required=false}={}) {
-  if(value===undefined) {if(required) wireError('needs-configuration');return null;}
-  if(!obj(value) || value.contract!==KNOWLEDGE_CONTRACT || value.version!==KNOWLEDGE_CONTRACT_VERSION) wireError('invalid-binding');
-  return value;
-}
-function runtimeSettings(settings) {
-  // `harvest` (on|off) is read by the lifecycle hooks, not bound: accept it here
-  // so a deployment can set it, and refuse any other value.
-  keys(settings,['bindings-file','state-dir','harvest-runtime','harvest-model','harvest'],[], 'OKF settings');
-  if(settings.harvest!==undefined && !['on','off'].includes(settings.harvest)) wireError('invalid-binding');
-  const descriptorFile=settings['bindings-file'],stateDir=settings['state-dir'],runtime=settings['harvest-runtime'],model=settings['harvest-model'] ?? null;
-  for(const name of ['bindings-file','state-dir']) {
-    if(settings[name]===undefined) settingError(`${name}:missing`);
-    if(!absolute(settings[name])) settingError(`${name}:invalid`);
-  }
-  if(runtime===undefined) settingError('harvest-runtime:missing');
-  if(!['pi','claude','codex'].includes(runtime)) settingError('harvest-runtime:invalid');
-  if(model!==null && (typeof model!=='string' || !model.trim())) settingError('harvest-model:invalid');
-  return {descriptorFile,stateDir,execution:{runtime,model}};
-}
-// Shared maps contain other providers' opaque values. Ownership comes from
-// this source's declared/default/required knowledge addresses, not from a value
-// looking like a locator or a blanket stores.* prefix. Validate OWN values later.
-function ownedBindings(bindings,ownedKeys) {
-  return Object.fromEntries(Object.entries(bindings).filter(([name])=>{
-    let key;try{key=bindingChoiceKey(name);}catch{return false;}
-    return ownedKeys.has(key);
-  }));
-}
-function normalizePhase(req) {
-  keys(req.input,['declarations','context'],['declarations','context'],'normalize input');
-  if(!Array.isArray(req.input.declarations) || !obj(req.input.context)) wireError('invalid-binding');
-  const requirements=[],candidates=[],bindingInputs=[];let domain=null;
-  const collect=input=>{if(!obj(input.bindings)) wireError('invalid-binding');bindingInputs.push(input);};
-  for(const raw of req.input.declarations) {
-    const item=declaration(raw);
-    if(item.kind==='soul') {
-      const envelope=contract(item.value.knowledge,{required:true});
-      if(domain) wireError('requirement-conflict');
-      domain=normalizeKnowledgeDeclaration(envelope,{origin:item.origin,origins:item.origins,pointer:'/knowledge/payload'});
-      continue;
-    }
-    if(item.kind==='workspace') {
-      const stores=item.value.knowledge?.stores;
-      if(stores===undefined) continue;
-      if(!Array.isArray(stores)) wireError('invalid-binding');
-      stores.forEach((rawStore,index)=>{
-        if(!obj(rawStore)) wireError('invalid-binding');
-        if(rawStore.contract!==KNOWLEDGE_CONTRACT) return;
-        const store=contract(rawStore);
-        keys(store.payload,['bindings'],['bindings'],'workspace OKF payload');
-        collect({bindings:store.payload.bindings,kind:'workspace-default',origin:item.origin,origins:item.origins,pointer:`/knowledge/stores/${index}/payload/bindings`});
-      });
-      continue;
-    }
-    if(item.value.bindings===undefined) continue;
-    collect({bindings:item.value.bindings,kind:item.kind==='adoption'?'import-adoption':'operator',origin:item.origin,origins:item.origins,pointer:'/bindings'});
-  }
-  if(!domain) wireError('needs-configuration');
-  // Collect first so declaration order cannot change who owns a binding. Keep
-  // all declared addresses, including dotted aliases and explicit/implicit
-  // write.default or custom inheritance; the kernel still resolves precedence.
-  const ownedKeys=new Set([...domain.requirements,...domain.candidates].map(item=>item.key));
-  for(const input of bindingInputs) candidates.push(...normalizeKnowledgeBindingCandidates({...input,bindings:ownedBindings(input.bindings,ownedKeys)}));
-  requirements.push(...domain.requirements);candidates.unshift(...domain.candidates);
-  return {requirements,candidates,model:{domain,runtime:runtimeSettings(req.settings)}};
-}
-function choiceMap(value) {
-  if(!obj(value)) wireError('invalid-binding');
-  for(const [key,choice] of Object.entries(value)) {
-    if(!key.startsWith('/bindings/knowledge/') || key.includes('//') || /~(?![01])/.test(key)) wireError('invalid-binding');
-    keys(choice,['value','selectedBy','constraints','considered'],['value','selectedBy','constraints','considered'],'knowledge choice');
-    if(!Array.isArray(choice.constraints) || !Array.isArray(choice.considered) || (choice.selectedBy!==null && !obj(choice.selectedBy))) wireError('invalid-binding');
-  }
-  return value;
-}
-function bindPhase(req) {
-  keys(req.input,['model','choices','context'],['model','choices','context'],'bind input');if(!obj(req.input.context)) wireError('invalid-binding');
-  keys(req.input.model,['domain','runtime'],['domain','runtime'],'OKF binding model');
-  keys(req.input.model.runtime,['stateDir','descriptorFile','execution'],['stateDir','descriptorFile','execution'],'OKF runtime model');
-  let bound;try{bound=bindKnowledgeDomain({model:req.input.model.domain,choices:choiceMap(req.input.choices)});}catch(error){if(/unresolved knowledge binding/.test(error.message)) wireError('needs-configuration');throw error;}
-  const runtime=renderKnowledgeRuntime({domain:bound.payload,...req.input.model.runtime});
-  return {payloadContract:bound.contract,payloadVersion:bound.version,payload:{...bound.payload,runtime,execution:req.input.model.runtime.execution},credentialRefs:bound.credentialRefs,provenance:bound.provenance};
-}
-function bindingPayload(binding,{diagnoseSettings=false}={}) {
-  keys(binding,['schemaVersion','capability','payloadContract','payloadVersion','payload','credentialRefs','provenance'],['schemaVersion','capability','payloadContract','payloadVersion','payload','credentialRefs','provenance'],'provider binding');
-  if(binding.schemaVersion!==1 || binding.capability!==CAPABILITY || binding.payloadContract!==KNOWLEDGE_CONTRACT || binding.payloadVersion!==KNOWLEDGE_CONTRACT_VERSION || !Array.isArray(binding.provenance)) wireError('invalid-binding');
-  if(!obj(binding.credentialRefs) || Object.keys(binding.credentialRefs).length) wireError('invalid-binding');
-  keys(binding.payload,['owner','stores','reads','owns','runtime','execution'],['owner','stores','reads','owns','runtime','execution'],'OKF binding payload');
-  const domain={owner:binding.payload.owner,stores:binding.payload.stores,reads:binding.payload.reads,owns:binding.payload.owns};
-  if(diagnoseSettings) {
-    const bound=binding.payload;
-    if(!obj(bound.runtime) || !obj(bound.runtime.bindings) || !obj(bound.execution)) wireError('invalid-binding');
-    // Check the retained values, not mutable request settings. Existing full
-    // envelope/canonical-runtime/execution guards still run below on success.
-    runtimeSettings({'bindings-file':bound.runtime.descriptorFile,'state-dir':bound.runtime.bindings.stateDir,
-      'harvest-runtime':bound.execution.runtime,'harvest-model':bound.execution.model});
-  }
-  const runtime=renderKnowledgeRuntime({domain,stateDir:binding.payload.runtime?.bindings?.stateDir,descriptorFile:binding.payload.runtime?.descriptorFile});
-  if(!sameJson(runtime,binding.payload.runtime)) wireError('invalid-binding');
-  keys(binding.payload.execution,['runtime','model'],['runtime','model'],'OKF worker execution');
-  if(!['pi','claude','codex'].includes(binding.payload.execution.runtime) || (binding.payload.execution.model!==null && (typeof binding.payload.execution.model!=='string' || !binding.payload.execution.model.trim()))) wireError('invalid-binding');
-  return {domain,runtime,execution:binding.payload.execution};
-}
-
-/** Pure projection for durable source registration and later source-free work. */
-export function sourceRuntimeFromKnowledgeBinding(binding) {
-  const {domain,runtime,execution}=bindingPayload(binding);
-  return {owner:domain.owner,bindings:{file:runtime.descriptorFile,...runtime.bindings},decl:runtime.declaration,execution:{...execution}};
-}
-
-const invocationError=()=>{throw Object.assign(new Error('invalid captured provider binding snapshot'),{code:'E_BINDING'});};
-export function readPrivateInvocationJson(file) {
-  if(!absolute(file)) invocationError();
-  let fd;
-  try {
-    if(safePath(file)!==file) invocationError();
-    const before=fs.lstatSync(file),uid=typeof process.getuid==='function'?process.getuid():null;
-    if(!before.isFile() || before.nlink!==1 || before.size>BINDING_WIRE_LIMITS.bytes || (before.mode&0o077)!==0 || (uid!==null && before.uid!==uid)) invocationError();
-    fd=fs.openSync(file,fs.constants.O_RDONLY|fs.constants.O_NOFOLLOW|fs.constants.O_NONBLOCK);
-    const opened=fs.fstatSync(fd);
-    if(!opened.isFile() || opened.nlink!==1 || opened.dev!==before.dev || opened.ino!==before.ino || opened.size>BINDING_WIRE_LIMITS.bytes || (opened.mode&0o077)!==0 || (uid!==null && opened.uid!==uid)) invocationError();
-    const bytes=Buffer.alloc(Math.min(BINDING_WIRE_LIMITS.bytes+1,opened.size+1));let length=0;
-    while(length<bytes.length) {const count=fs.readSync(fd,bytes,length,bytes.length-length,null);if(!count) break;length+=count;}
-    const after=fs.fstatSync(fd);
-    if(length>BINDING_WIRE_LIMITS.bytes || after.size!==opened.size || after.mtimeMs!==opened.mtimeMs) invocationError();
-    return parseBindingJson(bytes.subarray(0,length));
-  } catch(error) {if(error?.code==='E_BINDING') throw error;invocationError();}
-  finally {if(fd!==undefined) fs.closeSync(fd);}
-}
-
-/** Load only the parent-owned transient ProviderBinding1 snapshot when present.
- * Absence is an explicit legacy mode; every present-file defect fails closed. */
-export function loadInvocationKnowledgeBinding(env=process.env) {
-  if(!Object.hasOwn(env,'OATS_BINDING_FILE')) return {kind:'legacy'};
-  const file=env.OATS_BINDING_FILE,binding=readPrivateInvocationJson(file);
-  let runtime;try{runtime=sourceRuntimeFromKnowledgeBinding(binding);}catch{invocationError();}
-  return {kind:'captured',file,binding,runtime};
-}
-// Closed vocabulary of check-phase reasons: one fixed literal per cause, so the
-// operator learns WHICH qualification failed without any value, path, alias or
-// caught message reaching the wire. Every literal is also in oats.json
-// binding.reasons (byte-exact) — the manifest test pins that.
-const checkReasons=Object.freeze({
-  'action:not-admitted':'check action is not an admitted knowledge operation',
-  'settings:missing':'OKF settings missing bindings-file: set settings.oats.okf bindings-file, or deactivate oats.okf',
-  'soul:missing':'OKF soul declaration missing: create okf.json for this soul, or deactivate oats.okf',
-  'harvest-runtime:missing':settingMessages['harvest-runtime:missing'],
-  'harvest-runtime:invalid':settingMessages['harvest-runtime:invalid'],
-  'harvest-model:invalid':settingMessages['harvest-model:invalid'],
-  'binding:not-configured':'OKF binding missing or invalid: provision soul OKF declaration and bindings file, or deactivate oats.okf',
-  'bindings:invalid':'OKF bindings file missing or invalid: repair configured bindings file, or deactivate oats.okf',
-  'bases:too-many':'more than 64 git knowledge bases declared',
-  'base:stage-failed':'declared knowledge base could not be staged from its git source',
-  'base:not-validated':'declared knowledge base is not a validated knowledge tree',
-  'base:owner-unmet':'knowledge base owner or remote custody requirement not met',
-  'base:source-mismatch':'staged git source does not match the declared knowledge base',
-  'runtime:command-missing':'harvest runtime command is not installed on this host',
-  'runtime:not-qualified':'harvest runtime is not qualified: install/configure the selected harvest runtime or set harvest off',
-});
-function problem(code,reason) {
-  if(reason===undefined) return {code};
-  if(!Object.hasOwn(checkReasons,reason)) wireError('invalid-binding');
-  return {code,message:checkReasons[reason]};
-}
-export const CHECK_REASONS=Object.values(checkReasons);
-function providerActionName(action) {
-  if(action.kind==='operation' && action.slot===SLOT) return action.name;
-  if(action.kind!=='command') return null;
-  if(action.namespace==='okf' || action.capability===CAPABILITY) return action.name;
-  if(typeof action.name==='string' && action.name.startsWith('okf:')) return action.name.slice(4);
-  return null;
-}
-function readinessRuntime(settings,env=process.env) {
-  if(Object.hasOwn(settings,'bindings-file')) {
-    try {
-      if(typeof settings['bindings-file']!=='string' || !absolute(settings['bindings-file'])) return {problem:problem('needs-configuration','settings:missing')};
-      if(settings.harvest!==undefined && !['on','off'].includes(settings.harvest)) return {problem:problem('needs-configuration','runtime:not-qualified')};
-      if(settings.harvest!=='off') {
-        if(settings['harvest-runtime']===undefined) return {problem:problem('needs-configuration','harvest-runtime:missing')};
-        if(!['pi','claude','codex'].includes(settings['harvest-runtime'])) return {problem:problem('needs-configuration','harvest-runtime:invalid')};
-        if(settings['harvest-model']!==undefined && (typeof settings['harvest-model']!=='string' || !settings['harvest-model'].trim())) return {problem:problem('needs-configuration','harvest-model:invalid')};
-      }
-      const bindings=loadBindings(settings['bindings-file']);
-      if(!env.OATS_SOUL) return {problem:problem('needs-configuration','soul:missing')};
-      const decl=soulDeclaration(env.OATS_SOUL);
-      return {runtime:{descriptorFile:bindings.file,bindings:{version:1,stateDir:bindings.stateDir,bases:bindings.bases},declaration:decl}};
-    } catch(error) {
-      const message=String(error?.message || '');
-      if(error?.code==='E_CONFIG' && /okf\.json|soul has no/.test(message)) return {problem:problem('needs-configuration','soul:missing')};
-      return {problem:problem('needs-configuration','bindings:invalid')};
-    }
-  }
-  if(settings.schemaVersion!==undefined) {
-    try { return {runtime:bindingPayload(settings,{diagnoseSettings:true}).runtime}; }
-    catch(error) {if(['invalid-binding','needs-configuration'].includes(error?.wireCode)) return {problem:problem('needs-configuration','binding:not-configured')};throw error;}
-  }
-  return {problem:problem('needs-configuration','settings:missing')};
-}
-function checkPhase(req) {
-  keys(req.input,['context','action'],['context','action'],'check input');
-  if(!obj(req.input.context) || !obj(req.input.action)) wireError('invalid-binding');
-  const action=req.input.action,name=providerActionName(action);
-  const prepared=readinessRuntime(req.settings);
-  if(prepared.problem) return {status:'needs-configuration',problems:[prepared.problem]};
-  const runtime=prepared.runtime;
-  if(name && (unsupportedCapturedCommands.has(name) || name==='run-source' || name==='harvest')) return {status:'needs-configuration',problems:[problem('provider-not-qualified','action:not-admitted')]};
-  if(action.kind==='hook' && action.name==='soul-scaffold') return {status:'ready',problems:[]};
-  let bindings;try{bindings=validateBindings(runtime.bindings,runtime.descriptorFile);}catch{return {status:'needs-configuration',problems:[problem('needs-configuration','bindings:invalid')]};}
-  const accepted={},gitBases=Object.entries(bindings.bases).filter(([,base])=>base.kind==='git');
-  if(gitBases.length>64) return {status:'unavailable',problems:[problem('provider-not-qualified','bases:too-many')]};
-  let scratch=null,stage='base';
-  try {
-    if(gitBases.length) scratch=fs.mkdtempSync(join(fs.realpathSync(tmpdir()),'oats-okf-binding-check-'));
-    for(const [alias,base] of Object.entries(bindings.bases)) {
-      stage=base.kind==='directory'?'validate':'stage';
-      accepted[alias]=(base.kind==='directory'?validateBase(base.path,base):stageBase(base,join(scratch,alias),{alias})).meta;
-    }
-    if(req.settings.harvest!=='off') {
-      stage='runtime';
-      checkKnowledgeRuntime({rendered:runtime,accepted});
-    }
-  } catch(error) {
-    if(error.code==='E_COMMAND') return {status:'needs-configuration',problems:[problem('needs-configuration','runtime:command-missing')]};
-    if(error.code==='E_OWNER') return {status:'needs-configuration',problems:[problem('provider-not-qualified','base:owner-unmet')]};
-    if(error.code==='E_CONFIRM') return {status:'needs-configuration',problems:[problem('provider-not-qualified','base:source-mismatch')]};
-    if(['E_BASE','E_VALIDATION','E_DIRECTORY_GIT'].includes(error.code)) return {status:'needs-configuration',problems:[problem('provider-not-qualified',stage==='stage'?'base:stage-failed':'base:not-validated')]};
-    if(stage==='runtime') return {status:'needs-configuration',problems:[problem('needs-configuration','runtime:not-qualified')]};
-    return {status:'unavailable',problems:[problem('provider-unavailable')]};
-  } finally {
-    if(scratch) fs.rmSync(scratch,{recursive:true,force:true});
-  }
-  return {status:'ready',problems:[]};
-}
-
-export function handleBindingRequest(phase,value) {
-  if(!phases.has(phase)) wireError('invalid-binding');
-  const req=request(value,phase);
-  if(phase==='normalize') return normalizePhase(req);
-  if(phase==='bind') return bindPhase(req);
-  return checkPhase(req);
-}
-function response(phase,body) {return {schemaVersion:1,phase,slot:SLOT,capability:CAPABILITY,...body};}
-function errorCode(error) {if(errorCodes.has(error?.wireCode)) return error.wireCode;if(error?.code==='E_OWNER') return 'requirement-conflict';return 'invalid-binding';}
-function errorProblem(error) {
-  const code=errorCode(error),message=error?.[settingDiagnostic];
-  return {code,...(code==='needs-configuration' && Object.values(settingMessages).includes(message)?{message}:{})};
-}
-function enforceOutputLimits(value,depth=1,state={entries:0}) {
-  if(depth>BINDING_WIRE_LIMITS.depth) wireError('provider-not-qualified');
-  if(value===null || typeof value!=='object') return;
-  for(const child of Array.isArray(value)?value:Object.values(value)) {
-    if(++state.entries>BINDING_WIRE_LIMITS.entries) wireError('provider-not-qualified');
-    enforceOutputLimits(child,depth+1,state);
-  }
-}
-export async function runBindingWire(phase,input=process.stdin,output=process.stdout) {
-  let answer;
-  try {
-    const chunks=[];let length=0;
-    for await(const chunk of input) {const bytes=Buffer.from(chunk);length+=bytes.length;if(length>BINDING_WIRE_LIMITS.bytes) wireError('invalid-binding');chunks.push(bytes);}
-    const result=handleBindingRequest(phase,parseBindingJson(Buffer.concat(chunks,length)));
-    answer=response(phase,{ok:true,result});
-  } catch(error) {answer=response(phases.has(phase)?phase:'check',{ok:false,error:errorProblem(error)});}
-  let bytes;
-  try {enforceOutputLimits(answer);bytes=Buffer.from(JSON.stringify(answer)+'\n');if(bytes.length>BINDING_WIRE_LIMITS.bytes) wireError('provider-not-qualified');}
-  catch {bytes=Buffer.from(JSON.stringify(response(phases.has(phase)?phase:'check',{ok:false,error:{code:'provider-not-qualified'}}))+'\n');}
-  output.write(bytes);
-  return answer.ok;
-}

package/capabilities/oats-okf/lib/captured-worker.mjs

@@ -1,109 +0,0 @@
-// Captured worker PUBLIC consumer. No kernel imports/index reads, legacy source
-// discovery, fake admission, auth handling, backend defaults or history repair.
-import {fs,join,resolve,safePath,exec,cliPath,hash,fail} from './io.mjs';
-import {isAbsolute} from 'node:path';
-import {parseBindingJson,BINDING_WIRE_LIMITS} from './binding-wire.mjs';
-import {assertOkfSourceContext,requireOkfAdmittedAction} from './invocation-context.mjs';
-import {sameInvocationJson as same} from './invocation-shape.mjs';
-export const CAPTURED_WORKER_KEY='oats.okf:memory-harvest';
-const obj=v=>v!==null&&typeof v==='object'&&!Array.isArray(v);
-const abs=v=>typeof v==='string'&&isAbsolute(v)&&resolve(v)===v&&!v.includes('\0');
-const uuid=v=>typeof v==='string'&&/^[a-f0-9]{8}-[a-f0-9]{4}-4[a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/.test(v);
-export const capturedSource=s=>['providerBinding','executionBinding','registration'].some(k=>Object.hasOwn(s,k));
-function binding(v){if(!obj(v)||v.schemaVersion!==1||!abs(v.deployment)||v.resolution?.schemaVersion!==1||!/^sha256-[a-f0-9]{64}$/.test(v.resolution.id))fail('E_CAPTURED_HELPER','invalid public execution binding');return v;}
-export function workerCallEnvironment(inherited){
-  // Preserve native HOME/profile/auth/Git helpers and the active OATS data
-  // scope, not invoking instance selectors (including legacy PI_AGENT aliases).
-  const env={...inherited};for(const key of Object.keys(env))if(/^(OATS_(?!HOME_DIR$)|OAS_|PI_AGENT_)/.test(key)||key==='PI_AGENTS_ROOT')delete env[key];
-  return env;
-}
-export function publicWorkerCall(source,args){
-  let text,status=0;
-  const env=workerCallEnvironment(process.env);
-  try{text=exec(cliPath(),args,{cwd:source.context,env,timeout:90000});}
-  catch(error){text=error.stdout;status=error.status??null;}
-  let envelope;try{envelope=parseBindingJson(Buffer.from(text||''),BINDING_WIRE_LIMITS);}catch{fail('E_CAPTURED_HELPER_UNKNOWN','public helper outcome is unknown; retain run/home, never re-scaffold');}
-  if(envelope.schemaVersion!==1||typeof envelope.ok!=='boolean')fail('E_CAPTURED_HELPER_UNKNOWN','invalid public helper response');
-  if(status!==0||!envelope.ok){const error=Object.assign(new Error('public captured helper action refused or is uncertain; retain custody'),{code:'E_CAPTURED_HELPER_UNKNOWN',publicObservation:{status,envelope}});throw error;}
-  if(!obj(envelope.result))fail('E_CAPTURED_HELPER_UNKNOWN','public helper result missing');return envelope.result;
-}
-export function readWorkerEndpoint(file){
-  if(!abs(file))fail('E_CAPTURED_HELPER','captured harvest needs an explicit absolute native-request');safePath(file);let fd;
-  try{
-    fd=fs.openSync(file,fs.constants.O_RDONLY|fs.constants.O_NOFOLLOW|fs.constants.O_NONBLOCK);
-    const before=fs.fstatSync(fd);if(!before.isFile()||before.size>BINDING_WIRE_LIMITS.bytes)fail('E_CAPTURED_HELPER','invalid bounded native request');
-    const buffer=Buffer.alloc(before.size+1);let n=0,k;while(n<buffer.length&&(k=fs.readSync(fd,buffer,n,buffer.length-n,null)))n+=k;
-    const after=fs.fstatSync(fd);if(n!==before.size||before.size!==after.size||before.mtimeMs!==after.mtimeMs||before.ctimeMs!==after.ctimeMs)fail('E_CAPTURED_HELPER','native request changed');
-    const value=parseBindingJson(buffer.subarray(0,n),BINDING_WIRE_LIMITS);
-    if(!obj(value)||value.schemaVersion!==1||!obj(value.backend)||Object.keys(value).some(k=>!['schemaVersion','backend','stopGraceMs'].includes(k)))fail('E_CAPTURED_HELPER','worker native-request allows backend/stopGraceMs only; provider owns task');
-    const b=value.backend,allowed=b.backend==='tmux'?['backend','binary','socket','session']:b.backend==='herdr'?['backend','binary','socket','protocol']:[];
-    if(!allowed.length||Object.keys(b).length!==allowed.length||!allowed.every(k=>Object.hasOwn(b,k))||!abs(b.binary)||!abs(b.socket))fail('E_CAPTURED_HELPER','unsupported exact backend request');
-    if(b.backend==='tmux'&&(typeof b.session!=='string'||!b.session||/[\r\n\0]/.test(b.session)))fail('E_CAPTURED_HELPER','invalid tmux endpoint');
-    if(b.backend==='herdr'&&![20,22].includes(b.protocol))fail('E_CAPTURED_HELPER','unknown Herdr protocol');
-    if(value.stopGraceMs!==undefined&&(!Number.isSafeInteger(value.stopGraceMs)||value.stopGraceMs<1||value.stopGraceMs>300000))fail('E_CAPTURED_HELPER','invalid stop grace');
-    return JSON.parse(JSON.stringify(value));
-  }finally{if(fd!==undefined)fs.closeSync(fd);}
-}
-export function qualifyCapturedWorker(source,{context,nativeRequest}={},call=publicWorkerCall){
-  if(!context||source.registration?.schemaVersion!==1||source.registration.kind!=='captured')fail('E_CAPTURED_HELPER','captured worker needs registered SOURCE and current admitted operation');
-  requireOkfAdmittedAction(context);assertOkfSourceContext(source,context,source.providerBinding);
-  if(context.action.kind!=='operation'||context.action.slot!=='knowledge'||context.action.name!=='harvest'||context.subject.kind!=='persistent')fail('E_CAPTURED_HELPER','only admitted SOURCE knowledge:harvest may create a captured worker');
-  const manifest=JSON.parse(fs.readFileSync(new URL('../oats.json',import.meta.url),'utf8'));
-  if((manifest.requires||[]).some(r=>obj(r)&&r.runtime==='pi')||manifest.hooks?.launch)fail('E_CAPTURED_HELPER','required Pi plugin/launch behavior is not qualified by this captured slice');
-  const request=readWorkerEndpoint(nativeRequest),sourceBinding=binding(source.executionBinding);
-  const inspected=call(source,['inspect','--deployment',sourceBinding.deployment,'--resolution',sourceBinding.resolution.id,'--helper',CAPTURED_WORKER_KEY,'--json']);
-  return validateWorkerSelection(source,context,request,inspected);
-}
-export function validateWorkerSelection(source,context,request,inspected){
-  const selected=inspected?.helperSelection;
-  if(selected?.schemaVersion!==1||!same(selected.sourceExecutionBinding,source.executionBinding)||selected.workMode!=='directory'||!same(selected.context,context.context)||!same(selected.responsibleHuman,source.responsibleHuman))fail('E_CAPTURED_HELPER','helper SOURCE/context/human/work correspondence is unqualified');
-  const h=selected.helper,subject=h?.subject;
-  if(h?.key!==CAPTURED_WORKER_KEY||h.name!=='memory-harvest'||subject?.kind!=='helper'||subject.name!==h.name||subject.provider?.kind!=='capability'||subject.provider.capability!=='oats.okf'||!same(subject.provider,subject.definition?.owner))fail('E_CAPTURED_HELPER','wrong qualified helper identity');
-  const api={schemaVersion:1,api:{contract:'oats.captured-session',version:2,available:true,backends:['tmux','herdr']},readiness:{status:'not-checked'}};
-  if(!same(selected.launch,api)||!same(inspected.nativeSession,api))fail('E_CAPTURED_HELPER','unknown captured native public API');
-  // Preserve the exact retained selection. Ordinary Claude/Codex may select
-  // null to use their own native model configuration; Pi's strict SDK slice
-  // still needs an explicit model and its previously qualified sole-OKF profile.
-  // API availability/approval is NOT native readiness. The unchanged public
-  // scaffold/start path enforces the entire retained resource/hook closure.
-  const launch=selected.launchSelection;
-  if(!obj(launch)||launch.runtime!==source.execution.runtime||!['pi','claude','codex'].includes(launch.runtime)
-    || !(launch.model===null?launch.runtime!=='pi':typeof launch.model==='string'&&!!launch.model.trim())
-    || (source.execution.model!==null&&launch.model!==source.execution.model))fail('E_CAPTURED_HELPER','retained helper launch runtime/model missing or mismatched');
-  const capabilities=inspected.capabilities;
-  if(!Array.isArray(capabilities)||!capabilities.length||capabilities.some(c=>!obj(c)||typeof c.id!=='string'||!/^(?:@?[a-z0-9][a-z0-9._-]*[./])[a-z0-9][a-z0-9._/-]*$/.test(c.id)||!['approved','not-required'].includes(c.approval))
-    || new Set(capabilities.map(c=>c.id)).size!==capabilities.length||!capabilities.some(c=>c.id==='oats.okf'&&c.approval==='approved'))fail('E_CAPTURED_HELPER','complete selected helper capability closure requires current approval');
-  if(launch.runtime==='pi'&&capabilities.length!==1)fail('E_CAPTURED_HELPER','enriched strict-Pi helper profile is not qualified; required capabilities were not removed');
-  if(binding(selected.executionBinding).deployment!==source.executionBinding.deployment||!same(inspected.resolution,selected.executionBinding.resolution))fail('E_CAPTURED_HELPER','helper inspection resolution/deployment differs');
-  return {schemaVersion:1,sourceBinding:JSON.parse(JSON.stringify(source.executionBinding)),helperBinding:JSON.parse(JSON.stringify(selected.executionBinding)),helper:JSON.parse(JSON.stringify(h)),request,requestHash:hash(request),sourceIntent:JSON.parse(JSON.stringify(context.intent)),sourceIncarnationId:context.instance.incarnationId,launchSelection:JSON.parse(JSON.stringify(launch))};
-}
-export function assertCapturedRun(source,run,plan){
-  const prior=run.capturedWorker;
-  if(!prior||prior.schemaVersion!==1||!same(prior.sourceBinding,source.executionBinding)||!same(prior.helperBinding,plan.helperBinding)||!same(prior.helper,plan.helper)||prior.sourceIncarnationId!==plan.sourceIncarnationId||prior.requestHash!==plan.requestHash||hash(prior.request)!==prior.requestHash||!same(prior.request,plan.request)||!same(prior.launchSelection,plan.launchSelection))fail('E_CAPTURED_HELPER','existing run authority/endpoint changed; no replacement worker');
-  if(['spawn-intent','scaffold-unknown','scaffolded','launch-intent','launch-unknown'].includes(run.status))fail('E_CAPTURED_HELPER_UNKNOWN','existing worker outcome requires explicit custody recovery; no duplicate dispatch');
-}
-export function capturedScaffold(source,run,home,call=publicWorkerCall){
-  const p=run.capturedWorker,b=p.helperBinding;
-  const result=call(source,['spawn',p.helper.name,'--deployment',b.deployment,'--resolution',b.resolution.id,'--home',home,'--no-launch','--json']);
-  if(result.home!==home||!uuid(result.incarnationId)||!same(result.executionBinding,b)||result.launchPending!==true||result.hooksPending!==false||result.cleanupRequired!==false||result.agent!==p.helper.name||result.work!=='directory'||typeof result.instance!=='string')fail('E_CAPTURED_HELPER_UNKNOWN','scaffold receipt lacks exact completed helper custody');
-  return result;
-}
-function directoryCustody(home){
-  const result={};for(const [key,path] of [['home',home],['work',join(home,'work')]]){safePath(path);const s=fs.lstatSync(path);if(!s.isDirectory()||!Number.isSafeInteger(s.dev)||!Number.isSafeInteger(s.ino))fail('E_WORKER','original worker directories unavailable');result[key]={dev:s.dev,ino:s.ino};}return result;
-}
-export function retainCapturedWorkerCustody(run,meta){
-  // Observe the EXISTING kernel home/work proof after the real public scaffold;
-  // do not mint a new incarnation or read/modify its private kernel index.
-  const actual=directoryCustody(run.worker.home);
-  if(!same(meta.captured?.custody,actual)||meta.incarnationId!==run.worker.incarnationId||!same(meta.executionBinding,run.capturedWorker.helperBinding))fail('E_WORKER','scaffold metadata/directory proof mismatch');
-  return JSON.parse(JSON.stringify(meta.captured.custody));
-}
-export function assertCapturedWorkerHome(source,run,meta,home){
-  const p=run.capturedWorker;if(!p||home!==run.worker.home||!same(p.sourceBinding,source.executionBinding)||!same(meta.executionBinding,p.helperBinding)||meta.incarnationId!==run.worker.incarnationId||meta.kind!=='helper'||meta.agent!==p.helper.name||!same(meta.captured?.custody,p.workerDirectoryCustody)||!same(directoryCustody(home),p.workerDirectoryCustody))fail('E_WORKER','captured worker incarnation/binding/subject/directory mismatch');
-}
-export function capturedStart(source,run,requestFile,call=publicWorkerCall){
-  const p=run.capturedWorker,b=p.sourceBinding;
-  const result=call(source,['session','start','--deployment',b.deployment,'--resolution',b.resolution.id,'--helper',p.helper.key,'--home',run.worker.home,'--request',requestFile,'--json']);
-  if(result.home!==run.worker.home||result.incarnationId!==run.worker.incarnationId||!same(result.executionBinding,p.helperBinding)||!same(result.sourceExecutionBinding,b)||!same(result.helper,p.helper)||result.dispatchAccepted!==true||result.intent?.incarnationId!==run.worker.incarnationId||typeof result.intent?.executionId!=='string'||result.runtime!==p.launchSelection.runtime||result.model!==p.launchSelection.model)fail('E_CAPTURED_HELPER_UNKNOWN','native result lacks exact helper dispatch custody');
-  return result;
-}

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

@@ -1,124 +0,0 @@
-import { isAbsolute } from 'node:path';
-import { fs, join, resolve, dirname, fail, readJSON, safePath, relPath, identifier, overlaps, hash, embedsCredential } from './io.mjs';
-const obj = v => v && typeof v === 'object' && !Array.isArray(v);
-function keys(value, allowed, label, code='E_CONFIG') {
-  if(!obj(value)) fail(code, `${label} must be an object`);
-  for(const key of Object.keys(value)) if(!allowed.includes(key)) fail(code, `unknown ${label} property: ${key}`);
-}
-export function settings() {
-  const s = JSON.parse(process.env.OATS_SETTINGS || '{}');
-  keys(s,['bindings-file','state-dir','harvest-runtime','harvest-model','git-timeout','consult-max-age','harvest'],'OATS_SETTINGS');
-  if(s.harvest!==undefined && !['on','off'].includes(s.harvest)) fail('E_CONFIG','harvest must be on or off');
-  if(s['git-timeout']!==undefined && (!Number.isInteger(s['git-timeout']) || s['git-timeout']<1)) fail('E_CONFIG','git-timeout must be a positive integer number of seconds');
-  if(s['consult-max-age']!==undefined && (!Number.isInteger(s['consult-max-age']) || s['consult-max-age']<0)) fail('E_CONFIG','consult-max-age must be a non-negative integer number of seconds');
-  if(s['state-dir']!==undefined && (typeof s['state-dir']!=='string' || !isAbsolute(s['state-dir']) || resolve(s['state-dir'])!==s['state-dir'])) fail('E_CONFIG','state-dir must be a normalized absolute path');
-  if(s['harvest-runtime']!==undefined && !['pi','claude','codex'].includes(s['harvest-runtime'])) fail('E_CONFIG','invalid harvest-runtime');
-  if(s['harvest-model']!==undefined && (typeof s['harvest-model']!=='string' || !s['harvest-model'].trim())) fail('E_CONFIG','harvest-model must be a nonempty string');
-  return s;
-}
-/** Time budget for Git operations that talk to a remote (clone, fetch, push,
- *  ls-remote). Local object reads keep the short exec default. */
-export function gitTimeoutMs() { return (settings()['git-timeout'] ?? 600)*1000; }
-/** How old (seconds) the host cache's accepted commit may be before a consult
- *  read refetches the accepted branch; 0 fetches on every read. */
-export function consultMaxAgeMs() { return (settings()['consult-max-age'] ?? 300)*1000; }
-export function noGit(path) {
-  for (let p = safePath(path); ; p = dirname(p)) {
-    if (fs.existsSync(join(p, '.git')) || (fs.existsSync(join(p, 'HEAD')) && fs.existsSync(join(p, 'objects')) && fs.existsSync(join(p, 'refs')))) fail('E_DIRECTORY_GIT', `directory store is in Git custody: ${p}; use kind git`);
-    if (dirname(p) === p) break;
-  }
-}
-export function validateBindings(doc, file, { sourceHome, sourceWork } = {}) {
-  keys(doc,['version','stateDir','bases','cron','tz'],'bindings');
-  if (!obj(doc) || doc.version !== 1 || !obj(doc.bases) || !Object.keys(doc.bases).length || (typeof doc.stateDir !== 'string' || !doc.stateDir)) fail('E_CONFIG', 'bindings require {version:1,stateDir,bases}');
-  for(const key of ['cron','tz']) if(doc[key]!==undefined && (typeof doc[key]!=='string' || !doc[key].trim())) fail('E_CONFIG', `${key} must be a nonempty string`);
-  const stateDir = safePath(resolve(dirname(file), doc.stateDir));
-  const bases = {}; const ids = new Set(); const paths = [];
-  for (const [alias, raw] of Object.entries(doc.bases)) {
-    identifier(alias); if (!obj(raw)) fail('E_CONFIG', 'invalid base');
-    const id = identifier(raw.id); if(ids.has(id)) fail('E_ID', `duplicate base identity ${id}`); ids.add(id);
-    if (raw.kind === 'directory') {
-      keys(raw,['id','kind','path'],'directory base');
-      if(typeof raw.path !== 'string' || !raw.path || ['repository','root','acceptedBranch','pr'].some(k=>k in raw)) fail('E_CONFIG', 'directory base requires only path custody');
-      const path = safePath(resolve(dirname(file), raw.path)); noGit(path);
-      bases[alias] = { id, kind: 'directory', path }; paths.push(path);
-      for(const artifact of [`${path}.okf-lock`,`${path}.okf-publication.json`]) if(overlaps(artifact,stateDir) || [sourceHome,sourceWork,file].filter(Boolean).some(p=>overlaps(artifact,p))) fail('E_PATH','coordination artifacts overlap state/source/bindings');
-      if ([sourceHome, sourceWork].filter(Boolean).some(p=>overlaps(path,p))) fail('E_PATH', 'directory base overlaps source home/work');
-    } else if (raw.kind === 'git') {
-      keys(raw,['id','kind','repository','root','acceptedBranch','pr'],'git base');
-      keys(raw.pr,['repository'],'git pr');
-      if(typeof raw.repository !== 'string' || !raw.repository || raw.repository.startsWith('-') || /[\r\n\0]/.test(raw.repository) || 'path' in raw) fail('E_CONFIG', 'git base requires repository');
-      if(embedsCredential(raw.repository)) fail('E_CONFIG', `git base "${alias}": the repository locator embeds a credential (user:token@); bind the plain URL and let a Git credential helper or SSH key supply access`);
-      const root = relPath(raw.root, true);
-      if (typeof raw.acceptedBranch !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/.test(raw.acceptedBranch) || raw.acceptedBranch.includes('..') || raw.acceptedBranch.endsWith('/') || raw.acceptedBranch.endsWith('.lock')) fail('E_CONFIG','invalid acceptedBranch');
-      if (!obj(raw.pr) || typeof raw.pr.repository !== 'string' || !/^[\w.-]+\/[\w.-]+$/.test(raw.pr.repository)) fail('E_CONFIG','git pr requires repository: owner/repo (same-repository PRs)');
-      let repository = raw.repository;
-      if(!/^(https:\/\/|ssh:\/\/|git@)/.test(repository)) {
-        repository = safePath(resolve(dirname(file), repository));
-        if(sourceHome && overlaps(repository,sourceHome) && repository.startsWith(sourceHome)) fail('E_PATH','Git locator is disposable source custody');
-        if(fs.existsSync(join(repository,'.git')) && fs.lstatSync(join(repository,'.git')).isFile()) fail('E_PATH','Git repository locator is a linked worktree; bind the durable canonical repository/remote');
-        paths.push(safePath(resolve(repository,root)));
-      }
-      bases[alias] = { id, kind:'git', repository, root, acceptedBranch:raw.acceptedBranch, pr:{repository:raw.pr.repository} };
-    } else fail('E_CONFIG', `unsupported base kind ${raw.kind}`);
-  }
-  for (const p of paths) if (overlaps(p,stateDir)) fail('E_PATH', 'state overlaps accepted base');
-  for (let i=0;i<paths.length;i++) for(let j=0;j<i;j++) if(overlaps(paths[i],paths[j])) fail('E_PATH','overlapping bases');
-  const gitBases=Object.values(bases).filter(b=>b.kind==='git');
-  for(let i=0;i<gitBases.length;i++) for(let j=0;j<i;j++) if(gitBases[i].repository===gitBases[j].repository && overlaps(resolve('/',gitBases[i].root),resolve('/',gitBases[j].root))) fail('E_PATH','overlapping Git base namespaces');
-  for (const p of [sourceHome,sourceWork].filter(Boolean)) if(overlaps(stateDir,p)) fail('E_PATH','state overlaps source home/work');
-  if(overlaps(stateDir,file) || paths.some(p=>overlaps(p,file))) fail('E_PATH','bindings document must be outside state and bases');
-  return { version:1, stateDir, bases, cron:doc.cron?.trim() ?? '*/15 * * * *', tz:doc.tz?.trim() ?? 'UTC' };
-}
-export function loadBindings(file = settings()['bindings-file'], opts = {}) {
-  if(typeof file !== 'string' || !isAbsolute(file)) fail('E_CONFIG','set one absolute bindings-file; explicit provisioning/migration is required');
-  safePath(file); return { file, ...validateBindings(readJSON(file),file,opts) };
-}
-export function declaration(soul) {
-  if(fs.existsSync(join(soul,'.okf-cutover.json'))) fail('E_MIGRATION','incomplete explicit migration cutover: rerun its recorded migrate --cutover command');
-  if(fs.existsSync(join(soul,'knowledge'))) fail('E_MIGRATION','legacy soul/knowledge exists: use oats okf migrate to preserve and stage it, then explicit cutover; no automatic loss');
-  if(!fs.existsSync(join(soul,'okf.json'))) fail('E_CONFIG',`soul has no okf.json: this soul reads/owns no knowledge yet. Provision it explicitly (oats okf init, or oats okf migrate for a legacy soul), or deactivate oats.okf for this soul; nothing was created`);
-  return validateDeclaration(readJSON(join(soul,'okf.json')));
-}
-export function validateDeclaration(d) {
-  keys(d,['version','owner','owns','reads'],'soul declaration');
-  if(!obj(d) || d.version!==1) fail('E_CONFIG','soul/okf.json requires version:1');
-  identifier(d.owner);
-  for(const key of ['owns','reads']) {
-    if(!Array.isArray(d[key]) || new Set(d[key]).size !== d[key].length) fail('E_CONFIG', `${key} must be a unique array`);
-    for(const ref of d[key]) splitRef(ref);
-  }
-  return { version:1, owner:d.owner, owns:d.owns, reads:d.reads };
-}
-export function splitRef(ref) {
-  if(typeof ref !== 'string' || ref.split('/').length !== 2) fail('E_CONFIG', `node reference must be base/node: ${ref}`);
-  return ref.split('/').map(identifier);
-}
-export function metadata(files, base) {
-  let m; try { m=JSON.parse(Buffer.from(files['okf-base.json'],'base64').toString()); } catch { fail('E_BASE','missing/invalid accepted okf-base.json; run explicit init, never bootstrap on read'); }
-  keys(m,['version','id','nodes'],'base metadata','E_BASE');
-  if(!base || typeof base.id!=='string') fail('E_BASE','invalid bound base identity');
-  if(!obj(m) || m.version !==1 || m.id!==base.id || !obj(m.nodes) || !Object.keys(m.nodes).length) fail('E_BASE','base identity/nodes mismatch');
-  const paths=[];
-  for(const [node, spec] of Object.entries(m.nodes)) {
-    identifier(node); keys(spec,['path','owner'],'node','E_BASE'); identifier(spec.owner); relPath(spec.path);
-    if(spec.path.split('/').some(p=>p.startsWith('.'))) fail('E_BASE','hidden node paths are not valid knowledge');
-    if(paths.some(p=>overlaps(resolve('/',p),resolve('/',spec.path)))) fail('E_BASE','overlapping nodes'); paths.push(spec.path);
-    if(!Object.hasOwn(files,`${spec.path}/index.md`) || !Object.hasOwn(files,`${spec.path}/log.md`)) fail('E_BASE',`missing node index/log ${node}`);
-  }
-  if(!files['index.md'] || !files['log.md']) fail('E_BASE','base index.md and log.md required');
-  for(const p of Object.keys(files)) {
-    if(p.split('/').some(part=>part.startsWith('.'))) fail('E_BASE','hidden knowledge files would evade the OKF validator');
-    if(['okf-base.json','index.md','log.md'].includes(p)) continue;
-    if(!p.endsWith('.md') || !paths.some(n=>p.startsWith(n+'/'))) fail('E_BASE',`file outside node knowledge: ${p}`);
-  }
-  return m;
-}
-export function resolveNodes(d, bindings, accepted) {
-  for(const ref of [...d.owns,...d.reads]) {
-    const [alias,node]=splitRef(ref);
-    if(!Object.hasOwn(bindings.bases,alias) || !accepted[alias] || !Object.hasOwn(accepted[alias].nodes,node)) fail('E_CONFIG', `unresolved node: ${ref}`);
-    if(d.owns.includes(ref) && accepted[alias].nodes[node].owner!==d.owner) fail('E_OWNER',`owner mismatch: ${ref}`);
-  }
-}
-export const bindingFingerprint = b => hash({stateDir:b.stateDir,bases:b.bases});