@awebai/oats 0.23.2 → 0.24.1

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

@@ -0,0 +1,111 @@
+// 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

@@ -0,0 +1,135 @@
+// 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

@@ -70,7 +70,7 @@ export function unlock(path, token) {
   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_AGENT','OATS_KIND','OATS_EVENT','OATS_CONTEXT','OATS_REPO','OATS_WORK','OATS_BRANCH','OATS_META','OATS_SETTINGS'];
+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_AGENT','OATS_KIND','OATS_EVENT','OATS_CONTEXT','OATS_REPO','OATS_WORK','OATS_BRANCH','OATS_META','OATS_SETTINGS','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)));
 }

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

@@ -0,0 +1,199 @@
+import { isAbsolute, resolve } from 'node:path';
+import { identifier, relPath, fail } from './io.mjs';
+import { resolveNodes, validateBindings, validateDeclaration } from './config.mjs';
+import { validateRepositoryLocator } from './source-contract.mjs';
+
+export const KNOWLEDGE_CONTRACT='oats.okf.locations';
+export const KNOWLEDGE_CONTRACT_VERSION=1;
+const candidateKinds=new Set(['workspace-default','import-adoption','operator']);
+const obj=value=>value && typeof value==='object' && !Array.isArray(value);
+const pointerKey=value=>String(value).replace(/~/g,'~0').replace(/\//g,'~1');
+const clone=value=>JSON.parse(JSON.stringify(value));
+const canonicalJson=value=>value===null || typeof value!=='object'?JSON.stringify(value):Array.isArray(value)?`[${value.map(canonicalJson).join(',')}]`:`{${Object.keys(value).sort().map(key=>`${JSON.stringify(key)}:${canonicalJson(value[key])}`).join(',')}}`;
+export const sameJson=(a,b)=>canonicalJson(a)===canonicalJson(b);
+function keys(value,allowed,required,label) {
+  if(!obj(value)) fail('E_CONFIG',`${label} must be an object`);
+  for(const key of Object.keys(value)) if(!allowed.includes(key)) fail('E_CONFIG',`unknown ${label} property: ${key}`);
+  for(const key of required) if(!Object.hasOwn(value,key)) fail('E_CONFIG',`${label} requires ${key}`);
+  return value;
+}
+function bindingKey(value) {
+  if(typeof value!=='string') fail('E_CONFIG','invalid knowledge binding key');
+  // Reserved stores.<alias> addresses ONE legal alias; dots inside that suffix
+  // are literal identity characters, never another hierarchy or fuzzy match.
+  const parts=value.startsWith('stores.')?[value.slice(7)]:value.split('.');
+  if(parts.some(part=>{try{identifier(part);return false;}catch{return true;}})) fail('E_CONFIG','invalid knowledge binding key');
+  return value;
+}
+export const bindingChoiceKey=value=>{
+  bindingKey(value);
+  return value.startsWith('stores.')?storeChoiceKey(value.slice(7)):`/bindings/knowledge/${value.split('.').map(pointerKey).join('/')}`;
+};
+export const storeChoiceKey=alias=>`/bindings/knowledge/stores/${pointerKey(identifier(alias))}`;
+function originAt({origins={},origin=null,pointer},suffix,kind) {
+  const at=`${pointer}${suffix}`,specific=origins[at],found=specific ?? origin;
+  if(!obj(found)) fail('E_CONFIG',`missing origin for ${at}`);
+  return clone({...found,kind});
+}
+
+/** Portable, non-secret store locator. Filesystem existence/custody and remote
+ * identity are checked later by bind/check; this function performs no I/O. */
+export function validateStoreLocator(value) {
+  if(!obj(value)) fail('E_CONFIG','knowledge store locator must be an object');
+  identifier(value.id);
+  if(value.kind==='directory') {
+    keys(value,['id','kind','path'],['id','kind','path'],'directory store locator');
+    if(typeof value.path!=='string' || !value.path.startsWith('path:') || !isAbsolute(value.path.slice(5)) || resolve(value.path.slice(5))!==value.path.slice(5)) fail('E_CONFIG','portable directory store requires a normalized absolute path: locator');
+    return {id:value.id,kind:value.kind,path:value.path};
+  } else if(value.kind==='git') {
+    keys(value,['id','kind','repository','root','acceptedBranch','pr'],['id','kind','repository','root','acceptedBranch','pr'],'git store locator');
+    validateRepositoryLocator(value.repository);
+    relPath(value.root,true);
+    if(typeof value.acceptedBranch!=='string' || !/^[a-zA-Z0-9][a-zA-Z0-9._/-]*$/.test(value.acceptedBranch) || value.acceptedBranch.includes('..') || value.acceptedBranch.endsWith('/') || value.acceptedBranch.endsWith('.lock')) fail('E_CONFIG','invalid acceptedBranch');
+    keys(value.pr,['repository'],['repository'],'git PR binding');if(typeof value.pr.repository!=='string' || !/^[\w.-]+\/[\w.-]+$/.test(value.pr.repository)) fail('E_CONFIG','git PR binding requires owner/repo');
+    return {id:value.id,kind:value.kind,repository:value.repository,root:value.root,acceptedBranch:value.acceptedBranch,pr:{repository:value.pr.repository}};
+  }
+  fail('E_CONFIG',`unsupported knowledge store kind: ${value.kind}`);
+}
+function validateEnvelope(value) {
+  keys(value,['contract','version','payload'],['contract','version','payload'],'knowledge declaration');
+  if(value.contract!==KNOWLEDGE_CONTRACT || value.version!==KNOWLEDGE_CONTRACT_VERSION) fail('E_CONFIG',`unsupported knowledge contract: ${value.contract}@${value.version}`);
+  return value.payload;
+}
+
+/** Validate the source-owned OKF payload and emit only field-level inputs for
+ * the kernel's one resolver. No winner is selected here. */
+export function normalizeKnowledgeDeclaration(envelope,{origins={},origin=null,pointer='/knowledge/payload'}={}) {
+  const payload=validateEnvelope(envelope);
+  keys(payload,['owner','stores','reads','owns'],['owner','stores','reads','owns'],'OKF knowledge payload');
+  const owner=identifier(payload.owner),stores={},requirements=[],candidates=[];
+  if(!obj(payload.stores)) fail('E_CONFIG','knowledge stores must be an object');
+  for(const [alias,spec] of Object.entries(payload.stores)) {
+    identifier(alias);keys(spec,['fixed','default','inherit'],[],`knowledge store ${alias}`);
+    const modes=['fixed','default','inherit'].filter(key=>Object.hasOwn(spec,key));
+    if(modes.length!==1) fail('E_CONFIG',`knowledge store ${alias} needs exactly one of fixed, default or inherit`);
+    const mode=modes[0],at=`/stores/${pointerKey(alias)}`,choiceKey=mode==='inherit'?bindingChoiceKey(bindingKey(spec.inherit)):storeChoiceKey(alias);
+    const selectedOrigin=originAt({origins,origin,pointer},`${at}/${mode}`,mode==='default'?'soul-default':'soul-requirement');
+    if(mode==='fixed') requirements.push({key:choiceKey,kind:'equals',value:validateStoreLocator(spec.fixed),origin:selectedOrigin});
+    else if(mode==='default') candidates.push({key:choiceKey,kind:'soul-default',value:validateStoreLocator(spec.default),origin:selectedOrigin});
+    else requirements.push({key:choiceKey,kind:'required',origin:selectedOrigin});
+    stores[alias]={mode,choiceKey,origin:selectedOrigin};
+  }
+  if(!Array.isArray(payload.reads) || !Array.isArray(payload.owns)) fail('E_CONFIG','knowledge reads/owns must be arrays');
+  const reads=[],owns=[],seenReads=new Set(),seenOwns=new Set();
+  payload.reads.forEach((entry,index)=>{
+    keys(entry,['store','node'],['store','node'],'knowledge read');
+    const store=identifier(entry.store),node=identifier(entry.node),key=`${store}/${node}`;
+    if(!Object.hasOwn(stores,store)) fail('E_CONFIG',`read references undeclared store: ${store}`);
+    if(seenReads.has(key)) fail('E_CONFIG',`duplicate knowledge read: ${key}`);seenReads.add(key);
+    reads.push({store,node,origin:originAt({origins,origin,pointer},`/reads/${index}`,'soul-requirement')});
+  });
+  payload.owns.forEach((entry,index)=>{
+    keys(entry,['node','destination'],['node'],'knowledge ownership');
+    const node=identifier(entry.node),destination=entry.destination===undefined?null:identifier(entry.destination);
+    if(destination!==null && !Object.hasOwn(stores,destination)) fail('E_CONFIG',`owned node references undeclared destination: ${destination}`);
+    const key=`${destination ?? '<write.default>'}/${node}`;
+    if(seenOwns.has(key)) fail('E_CONFIG',`duplicate knowledge ownership: ${key}`);seenOwns.add(key);
+    const itemOrigin=originAt({origins,origin,pointer},`/owns/${index}`,'soul-requirement');
+    if(destination===null) requirements.push({key:bindingChoiceKey('write.default'),kind:'required',origin:itemOrigin});
+    owns.push({node,destination,choiceKey:destination===null?bindingChoiceKey('write.default'):stores[destination].choiceKey,origin:itemOrigin});
+  });
+  return {contract:KNOWLEDGE_CONTRACT,version:KNOWLEDGE_CONTRACT_VERSION,owner,stores,reads,owns,requirements,candidates};
+}
+
+/** Convert already-parsed workspace/adoption/operator values to candidates.
+ * This intentionally performs no precedence or recursive merging. */
+export function normalizeKnowledgeBindingCandidates({bindings,kind,origins={},origin=null,pointer='/bindings'}={}) {
+  if(!candidateKinds.has(kind)) fail('E_CONFIG',`invalid knowledge candidate kind: ${kind}`);
+  if(!obj(bindings)) fail('E_CONFIG','knowledge bindings must be an object');
+  const candidates=[];
+  for(const [name,value] of Object.entries(bindings)) {
+    const key=bindingChoiceKey(name),at=`/${pointerKey(name)}`;
+    candidates.push({key,kind,value:validateStoreLocator(value),origin:originAt({origins,origin,pointer},at,kind)});
+  }
+  return candidates;
+}
+
+function selected(choices,key) {
+  if(!obj(choices) || !obj(choices[key]) || !Object.hasOwn(choices[key],'value') || choices[key].value===null) fail('E_CONFIG',`unresolved knowledge binding: ${key}`);
+  return validateStoreLocator(choices[key].value);
+}
+function runtimeStore(locator) {return locator.kind==='directory'?{...locator,path:locator.path.slice(5)}:locator;}
+
+/** Render provider-owned nonsecret data after the kernel's shared resolver has
+ * selected every field. Reads never imply a write destination. */
+export function bindKnowledgeDomain({model,choices}) {
+  if(!obj(model) || model.contract!==KNOWLEDGE_CONTRACT || model.version!==KNOWLEDGE_CONTRACT_VERSION) fail('E_CONFIG','invalid normalized OKF model');
+  const aliases={},stores={},provenance=[];
+  const add=(locator,choiceKey)=>{
+    const rendered=runtimeStore(locator);
+    if(Object.hasOwn(stores,locator.id) && !sameJson(stores[locator.id],rendered)) fail('E_CONFIG',`store identity ${locator.id} resolves to conflicting locations`);
+    stores[locator.id]=rendered;
+    const selectedBy=choices[choiceKey]?.selectedBy;if(obj(selectedBy)) provenance.push(clone(selectedBy));
+    return locator.id;
+  };
+  for(const [alias,plan] of Object.entries(model.stores)) aliases[alias]=add(selected(choices,plan.choiceKey),plan.choiceKey);
+  const reads=model.reads.map(entry=>({store:aliases[entry.store],node:entry.node}));
+  const readKeys=new Set();for(const entry of reads) {const key=`${entry.store}/${entry.node}`;if(readKeys.has(key)) fail('E_CONFIG',`duplicate resolved knowledge read: ${key}`);readKeys.add(key);}
+  const owns=model.owns.map(entry=>{
+    const locator=entry.destination===null?selected(choices,entry.choiceKey):selected(choices,model.stores[entry.destination].choiceKey);
+    const store=add(locator,entry.choiceKey);
+    return {store,node:entry.node,steward:model.owner};
+  });
+  const ownKeys=new Set();for(const entry of owns) {const key=`${entry.store}/${entry.node}`;if(ownKeys.has(key)) fail('E_OWNER',`duplicate resolved knowledge steward: ${key}`);ownKeys.add(key);}
+  for(const entry of [...model.reads,...model.owns]) provenance.push(clone(entry.origin));
+  const unique=[];for(const item of provenance) if(!unique.some(prior=>sameJson(prior,item))) unique.push(item);
+  return {contract:KNOWLEDGE_CONTRACT,version:KNOWLEDGE_CONTRACT_VERSION,payload:{owner:model.owner,stores,reads,owns},credentialRefs:{},provenance:unique};
+}
+
+function absolutePath(value,label) {
+  if(typeof value!=='string' || !isAbsolute(value) || resolve(value)!==value) fail('E_PATH',`${label} must be a normalized absolute path`);
+  return value;
+}
+function boundStore(value) {
+  if(!obj(value)) fail('E_CONFIG','bound knowledge store must be an object');
+  const portable=value.kind==='directory'?{...value,path:`path:${value.path}`} : value;
+  return runtimeStore(validateStoreLocator(portable));
+}
+
+/** Purely adapt a captured nonsecret provider domain to the existing OKF v1
+ * documents. The host supplies durable custody paths; neither is derived from
+ * a source home, and this function performs no filesystem access. */
+export function renderKnowledgeRuntime({domain,stateDir,descriptorFile}={}) {
+  keys(domain,['owner','stores','reads','owns'],['owner','stores','reads','owns'],'bound knowledge domain');
+  const owner=identifier(domain.owner),bases={};
+  if(!obj(domain.stores) || !Object.keys(domain.stores).length) fail('E_CONFIG','bound knowledge domain requires stores');
+  for(const [alias,value] of Object.entries(domain.stores)) {
+    identifier(alias);const store=boundStore(value);
+    if(store.id!==alias) fail('E_ID',`runtime alias must equal stable store identity: ${alias}`);
+    bases[alias]=store;
+  }
+  const references=(entries,label,owned=false)=>{
+    if(!Array.isArray(entries)) fail('E_CONFIG',`bound knowledge ${label} must be an array`);
+    return entries.map(entry=>{
+      keys(entry,owned?['store','node','steward']:['store','node'],owned?['store','node','steward']:['store','node'],`bound knowledge ${label}`);
+      const store=identifier(entry.store),node=identifier(entry.node);
+      if(!Object.hasOwn(bases,store)) fail('E_CONFIG',`${label} references unbound store: ${store}`);
+      if(owned && identifier(entry.steward)!==owner) fail('E_OWNER',`bound knowledge steward mismatch: ${store}/${node}`);
+      return `${store}/${node}`;
+    });
+  };
+  const declaration=validateDeclaration({version:1,owner,reads:references(domain.reads,'read'),owns:references(domain.owns,'ownership',true)});
+  return {descriptorFile:absolutePath(descriptorFile,'OKF descriptor file'),bindings:{version:1,stateDir:absolutePath(stateDir,'OKF stateDir'),bases},declaration};
+}
+
+/** Read-only custody/accepted-base check for an already rendered capture.
+ * `accepted` must come from the existing base validation path. */
+export function checkKnowledgeRuntime({rendered,accepted,sourceHome,sourceWork}={}) {
+  keys(rendered,['descriptorFile','bindings','declaration'],['descriptorFile','bindings','declaration'],'rendered OKF runtime');
+  keys(rendered.bindings,['version','stateDir','bases'],['version','stateDir','bases'],'rendered OKF bindings');
+  if(rendered.bindings.version!==1 || !obj(rendered.bindings.bases) || !Object.keys(rendered.bindings.bases).length) fail('E_CONFIG','invalid rendered OKF bindings');
+  absolutePath(rendered.bindings.stateDir,'OKF stateDir');
+  for(const [alias,value] of Object.entries(rendered.bindings.bases)) if(identifier(alias)!==boundStore(value).id) fail('E_ID',`runtime alias must equal stable store identity: ${alias}`);
+  if(!obj(accepted)) fail('E_CONFIG','accepted OKF base metadata is required');
+  const descriptorFile=absolutePath(rendered.descriptorFile,'OKF descriptor file');
+  const bindings=validateBindings(rendered.bindings,descriptorFile,{sourceHome,sourceWork});
+  const declaration=validateDeclaration(rendered.declaration);
+  resolveNodes(declaration,bindings,accepted);
+  return {descriptorFile,bindings,declaration};
+}

package/capabilities/oats-okf/lib/source-contract.mjs

@@ -0,0 +1,46 @@
+import { isAbsolute, resolve } from 'node:path';
+import { fail, relPath } from './io.mjs';
+const obj=value=>value!==null && typeof value==='object' && !Array.isArray(value);
+const invalid=()=>fail('E_SOURCE','invalid nonsecret qualified source identity');
+function exact(value,fields) {if(!obj(value) || Object.keys(value).some(key=>!fields.includes(key)) || fields.some(key=>!Object.hasOwn(value,key))) invalid();}
+
+/** Provider-owned nonsecret locator contract; no I/O, source resolver or secret
+ * lookup. Authentication remains in the native credential transport. */
+export function validateRepositoryLocator(value) {
+  const bad=()=>fail('E_CONFIG','Git repository must not contain credentials, query, fragment or malformed paths');
+  if(typeof value!=='string' || /[\s\\\x00-\x1f\x7f?#]/.test(value)) bad();
+  const scp=/^(git)@([^/:]+):(.+)$/.exec(value);
+  const spelling=scp?`ssh://${scp[1]}@${scp[2]}${scp[3].startsWith('/')?'':'/'}${scp[3]}`:value;
+  if(!/^(https|ssh):\/\//.test(spelling)) bad();
+  const pathStart=spelling.indexOf('/',spelling.indexOf('://')+3);
+  if(pathStart<0) bad();
+  for(const part of spelling.slice(pathStart+1).split('/')) {
+    let decoded;try{decoded=decodeURIComponent(part);}catch{bad();}
+    if(!part || decoded==='.' || decoded==='..' || /[/\\\x00-\x1f\x7f]/.test(decoded)) bad();
+  }
+  let url;try{url=new URL(spelling);}catch{bad();}
+  if(!url.hostname || url.password || url.search || url.hash || (url.protocol==='https:' && url.username)) bad();
+  if(scp) {if(value!==`${scp[1]}@${url.hostname}:${scp[3]}`) bad();}
+  else if(url.href!==value) bad();
+  return value;
+}
+export function qualifiedSoulIdentity(value) {
+  try {
+    if(value?.kind==='git-soul') {
+      exact(value,['kind','repository','exportPath']);const r=value.repository;
+      if(r?.kind==='provider-repository') {
+        exact(r,['kind','provider','host','id']);
+        if(typeof r.provider!=='string' || !/^[a-z][a-z0-9.-]*$/.test(r.provider) || typeof r.host!=='string' || !/^[a-z0-9](?:[a-z0-9.-]*[a-z0-9])?$/.test(r.host) || typeof r.id!=='string' || !r.id || /[\x00-\x1f\x7f]/.test(r.id)) invalid();
+      } else {
+        exact(r,['kind','remote']);if(r.kind!=='canonical-remote' || typeof r.remote!=='string' || !r.remote.startsWith('git:')) invalid();
+        validateRepositoryLocator(r.remote.slice(4));
+      }
+    } else if(value?.kind==='local-soul') {
+      exact(value,['kind','source','exportPath']);
+      if(typeof value.source!=='string' || !value.source.startsWith('path:') || /[\x00-\x1f\x7f]/.test(value.source)) invalid();
+      const p=value.source.slice(5);if(!isAbsolute(p) || resolve(p)!==p) invalid();
+    } else invalid();
+    relPath(value.exportPath,value.kind==='local-soul');
+    return JSON.parse(JSON.stringify(value));
+  } catch {invalid();}
+}