@awebai/oats 0.29.4 → 0.30.1

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

@@ -1,137 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { fs, join, dirname, resolve, safePath, readJSON, save, atomic, tree, materialize, digest, hash, overlaps, withLock, fail, identifier } from './io.mjs';
-import { metadata, noGit, validateDeclaration, loadBindings, resolveNodes, splitRef } from './config.mjs';
-import { stageBase, validateBase, baseLock, journalPath, gitPublish, directoryPublish } from './stores.mjs';
-const b64=s=>Buffer.from(s).toString('base64');
-export function initBase(bindings,alias,nodesFile,output,{confirm=false}={}) {
-  const base=Object.hasOwn(bindings.bases,alias)?bindings.bases[alias]:null;if(!base) fail('E_CONFIG','unknown base');
-  const nodes=readJSON(nodesFile);const files={'okf-base.json':b64(JSON.stringify({version:1,id:base.id,nodes},null,2)+'\n'),'index.md':b64('---\nokf_version: "0.1"\n---\n\n# Knowledge base\n\n'+Object.entries(nodes).map(([n,s])=>`* [${n}](${s.path}/index.md) - owned by ${s.owner}.`).join('\n')+'\n'),'log.md':b64('# Knowledge log\n')};
-  for(const [n,s] of Object.entries(nodes)) {identifier(n);files[`${s.path}/index.md`]=b64(`# ${n}\n`);files[`${s.path}/log.md`]=b64(`# ${n} log\n`);}
-  metadata(files,base);
-  const dest=safePath(output || (base.kind==='directory' && confirm ? base.path : fail('E_USAGE','init requires --output for a staged Git/operator proposal, or --confirm for a new directory base')));
-  if(fs.existsSync(dest)) fail('E_BASE','init destination exists; never overwrite knowledge');
-  for(const b of Object.values(bindings.bases)) {
-    const path=b.kind==='directory'?b.path:(b.repository.startsWith('/')?resolve(b.repository,b.root):null);
-    if(path && overlaps(path,dest) && !(b===base && b.kind==='directory' && dest===path && confirm)) fail('E_PATH','init stage overlaps accepted base');
-  }
-  if(overlaps(dest,bindings.stateDir)) fail('E_PATH','init cannot overlap durable state');
-  const write=()=>{materialize(dest,files);validateBase(dest,base);};
-  if(base.kind==='directory' && dest===base.path) {if(!confirm) fail('E_USAGE','directory provisioning needs --confirm');noGit(dest);withLock(baseLock(base),write);}
-  else write();
-  return {status:base.kind==='directory' && dest===base.path?'accepted':'staged',path:dest,next:base.kind==='git'?'Commit this initialized bundle in an operator-owned checkout and deliver through a reviewed PR before activating sources.':null};
-}
-export function migrate(bindings,{legacy,alias,node,output}) {
-  const base=Object.hasOwn(bindings.bases,alias)?bindings.bases[alias]:null;if(!base) fail('E_CONFIG','unknown base');identifier(node);legacy=safePath(legacy);output=safePath(output);
-  if(overlaps(legacy,output) || overlaps(legacy,bindings.stateDir) || overlaps(output,bindings.stateDir)) fail('E_PATH','migration source, stage and state must be disjoint');
-  // Check ALL configured custody, before even creating preservation/staging
-  // state. A destination alias does not grant writes to another accepted base.
-  for(const b of Object.values(bindings.bases)) {
-    const paths=b.kind==='directory'?[b.path,baseLock(b),journalPath(b)]:(b.repository.startsWith('/')?[resolve(b.repository,b.root)]:[]);
-    if(paths.some(path=>overlaps(path,output))) fail('E_PATH','migration stage overlaps configured accepted base or coordination artifacts');
-  }
-  const original=tree(legacy);
-  // Stage the accepted base before any record exists: a base that cannot be
-  // read leaves nothing behind. From the record on, a failure is recorded in
-  // it rather than left as an unexplained directory.
-  const stage=stageBase(base,output,{alias});
-  fs.mkdirSync(bindings.stateDir,{recursive:true,mode:0o700});
-  const id=randomUUID();const dir=join(bindings.stateDir,'migrations',id);fs.mkdirSync(dir,{recursive:true,mode:0o700});
-  save(join(dir,'legacy.json'),original); // byte-preserving backup BEFORE any delivery
-  const recordFile=join(dir,'migration.json');
-  try {
-  const spec=stage.meta.nodes[node];if(!spec) fail('E_OWNER','migration node must be explicitly provisioned first');
-  const prefix=spec.path+'/';
-  if(Object.keys(stage.files).some(p=>p.startsWith(prefix) && ![prefix+'index.md',prefix+'log.md'].includes(p))) fail('E_MIGRATION','target node is not empty; merge migration requires human judgment');
-  const after={...stage.files};for(const p of Object.keys(after)) if(p.startsWith(prefix)) delete after[p];
-  for(const [p,content] of Object.entries(original)) {
-    if(!p.endsWith('.md')) fail('E_MIGRATION',`legacy non-Markdown artifact requires manual migration: ${p}`);
-    let text=Buffer.from(content,'base64').toString('utf8');
-    text=text.replace(/\]\(\/(?!\/)([^)]+)\)/g,`](/${spec.path}/$1)`);
-    if(p==='index.md') text=text.replace(/^---\r?\n[\s\S]*?\r?\n---\r?\n/,'');
-    after[prefix+p]=b64(text);
-  }
-  after[prefix+'log.md'] ||= b64(`# ${node} log\n`);
-  // Replace only the empty pre-provisioned node, not unrelated accepted bytes.
-  fs.rmSync(join(stage.root,spec.path),{recursive:true});materialize(stage.root,after);validateBase(stage.root,base);
-  const proposalFile=join(dir,'proposal.json');const proposal={version:1,run:id,created:new Date().toISOString(),file:proposalFile,before:stage.files,after};save(proposalFile,proposal);
-  const record={version:1,id,alias,node,base,owner:spec.owner,legacy,originalDigest:digest(original),stage:{root:stage.root,checkout:stage.checkout,head:stage.head},proposal:proposalFile,proposalHash:hash(proposal),receipt:{status:'staged'}};save(recordFile,record);
-  return {status:'staged',migration:recordFile,originalPreserved:true,stage:stage.root};
-  } catch(e) {
-    save(recordFile,{version:1,id,alias,node,base,legacy,originalDigest:digest(original),receipt:{status:'failed',error:e.message,code:e.code||'E_MIGRATION',at:new Date().toISOString()}});
-    throw e;
-  }
-}
-/** Remove a migration record that never delivered anything (staged or failed).
- *  The backup it holds is the legacy bundle, which still exists at its source;
- *  a delivered record is custody and stays. */
-export function forgetMigration(bindings,id) {
-  identifier(id);const dir=join(bindings.stateDir,'migrations',id);const file=join(dir,'migration.json');
-  if(!fs.existsSync(dir)) fail('E_MIGRATION',`unknown migration ${id}`);
-  const status=fs.existsSync(file)?readJSON(file).receipt?.status:'incomplete';
-  if(!['failed','staged','incomplete'].includes(status)) fail('E_MIGRATION',`migration ${id} is ${status}: a delivered migration is custody and cannot be forgotten`);
-  fs.rmSync(dir,{recursive:true,force:true});
-  return {status:'forgotten',id,was:status};
-}
-export function deliverMigration(file) {
-  safePath(file);const m=readJSON(file);const proposal=readJSON(m.proposal);if(hash(proposal)!==m.proposalHash) fail('E_MIGRATION','migration proposal changed');
-  const persist=()=>save(file,m);
-  if(m.receipt.status==='accepted' && m.base.kind==='directory' && !fs.existsSync(`${m.base.path}.okf-publication.json`)) return m.receipt;
-  if(m.base.kind==='git') gitPublish(m.base,m.stage,proposal,m.receipt,persist);
-  else directoryPublish(m.base,proposal,m.receipt,persist);
-  return m.receipt;
-}
-export function cutoverMigration(file,soul) {
-  safePath(file);soul=safePath(soul);const m=readJSON(file);
-  if(m.receipt.status!=='accepted') fail('E_MIGRATION','cutover requires provider-confirmed acceptance; deliver/inspect merged PR first');
-  if(resolve(m.legacy)!==join(soul,'knowledge')) fail('E_MIGRATION','legacy path must be this soul/knowledge');
-  if(m.cutover?.status==='complete') return {status:'complete',backup:join(dirname(file),'original')};
-  const savedOriginal=join(dirname(file),'original');
-  const live=fs.existsSync(m.legacy)?m.legacy:(m.cutover?.status==='intent' && fs.existsSync(savedOriginal)?savedOriginal:m.legacy);
-  if(digest(tree(live))!==m.originalDigest) fail('E_MIGRATION','legacy bundle changed since staging; preserve and migrate the new version');
-  const original=readJSON(join(dirname(file),'legacy.json'));if(digest(original)!==m.originalDigest) fail('E_MIGRATION','backup differs');
-  const declarationFile=join(soul,'okf.json');const ref=`${m.alias}/${m.node}`;
-  let decl=fs.existsSync(declarationFile)?validateDeclaration(readJSON(declarationFile)):{version:1,owner:m.owner,owns:[],reads:[]};
-  if(decl.owner!==m.owner) fail('E_OWNER','existing soul declaration owner differs');
-  decl={...decl,owns:[...new Set([...decl.owns,ref])],reads:[...new Set([...decl.reads,ref])]};
-  // The declaration resolves through TODAY's bindings, not the frozen delivery
-  // locator. Validate it before any cutover intent, archive or soul edit.
-  const bindings=loadBindings();
-  if(!Object.hasOwn(bindings.bases,m.alias) || hash(bindings.bases[m.alias])!==hash(m.base)) fail('E_MIGRATION','current migration alias differs from frozen delivered base');
-  const proposal=readJSON(m.proposal);
-  if(hash(proposal)!==m.proposalHash) fail('E_MIGRATION','migration proposal changed');
-  const frozen=metadata(proposal.after,m.base).nodes[m.node];
-  if(!frozen || frozen.owner!==m.owner) fail('E_OWNER','migration proposal owner differs');
-  const accepted={};
-  const scratch=fs.mkdtempSync(join(bindings.stateDir,'cutover-check-'));
-  try {
-    for(const alias of new Set([...decl.owns,...decl.reads].map(r=>splitRef(r)[0]))) {
-      if(!Object.hasOwn(bindings.bases,alias)) fail('E_CONFIG',`unresolved base: ${alias}`);
-      const staged=stageBase(bindings.bases[alias],join(scratch,alias),{alias});
-      accepted[alias]=staged.meta;
-      if(alias===m.alias) {
-        if(hash(staged.meta.nodes[m.node] || null)!==hash(frozen)) fail('E_OWNER','accepted migration ownership/path differs from delivered node');
-        const nodeFiles=files=>Object.fromEntries(Object.entries(files).filter(([p])=>p.startsWith(frozen.path+'/')));
-        if(digest(nodeFiles(staged.files))!==digest(nodeFiles(proposal.after))) fail('E_MIGRATION','accepted migration node no longer matches delivered content; inspect and reconcile before cutover');
-      }
-    }
-    resolveNodes(decl,bindings,accepted);
-  } finally {fs.rmSync(scratch,{recursive:true,force:true});}
-  m.cutover={status:'intent',soul};save(file,m);save(join(soul,'.okf-cutover.json'),{migration:file});
-  // Atomic rename, not deletion. Cross-device moves deliberately fail closed;
-  // the operator can keep the preserved bundle and arrange explicit cutover.
-  if(live===m.legacy) fs.renameSync(m.legacy,savedOriginal);
-  save(declarationFile,decl);fs.rmSync(join(soul,'.okf-cutover.json'));m.cutover.status='complete';save(file,m);
-  return {status:'complete',backup:join(dirname(file),'original'),next:'Update old soul/knowledge references in soul instructions to knowledge/bases/<alias>/<node>. Skills are unchanged.'};
-}
-
-export function migrateSource(bindings, home) {
-  home=safePath(home);
-  if(overlaps(home,bindings.stateDir)) fail('E_PATH','legacy source overlaps durable state');
-  const files={};
-  for(const name of ['STATE.md','log.md','.okf-harvest-record.json','.okf-harvest-record.next.json']) if(fs.existsSync(join(home,name))) {safePath(join(home,name));files[name]=fs.readFileSync(join(home,name)).toString('base64');}
-  if(fs.existsSync(join(home,'notes'))) for(const [p,b] of Object.entries(tree(join(home,'notes')))) files['notes/'+p]=b;
-  const id=randomUUID(),file=join(bindings.stateDir,'migrations',id,'legacy-source.json');
-  save(file,{version:1,home,files,digest:digest(files)});
-  save(join(home,'.okf-v1-migration.json'),{version:1,backup:file,digest:digest(files)});
-  return {status:'preserved',backup:file,next:'Migrate any soul/knowledge bundle first; harvest re-registers this source and captures all visible evidence. Old v1 cursors are preserved, NOT accepted as v2 processing proof.'};
-}

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

@@ -1,123 +0,0 @@
-#!/usr/bin/env node
-/**
- * okf-validate.mjs — OKF v0.1 bundle validator (no dependencies).
- *
- * Usage: node okf-validate.mjs <bundle-dir> [--strict] [--json]
- *
- * Conformance (errors): frontmatter parses; non-empty `type` on concepts;
- * reserved files (index.md, log.md) carry no `type`.
- * Producer lints (--strict, warnings): broken intra-bundle links (log.md exempt),
- * links missing .md, concepts unreachable from any index.md, missing title/description.
- * Exit: 0 conformant, 1 errors (or warnings with --strict), 2 usage.
- */
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { join, relative, resolve, dirname, posix } from "node:path";
-
-const args = process.argv.slice(2);
-const strict = args.includes("--strict");
-const asJson = args.includes("--json");
-const dir = args.find((a) => !a.startsWith("--"));
-if (!dir || !existsSync(dir)) { console.error("usage: okf-validate.mjs <bundle-dir> [--strict] [--json]"); process.exit(2); }
-const root = resolve(dir);
-
-const files = [];
-(function walk(d) {
-  for (const e of readdirSync(d, { withFileTypes: true })) {
-    if (e.name.startsWith(".")) continue;
-    const p = join(d, e.name);
-    if (e.isDirectory()) walk(p);
-    else if (e.name.endsWith(".md")) files.push(p);
-  }
-})(root);
-
-const errors = [], warnings = [];
-const rel = (p) => relative(root, p).split("\\").join("/");
-const isReserved = (p) => ["index.md", "log.md"].includes(posix.basename(rel(p)));
-
-function parseFrontmatter(text) {
-  if (!text.startsWith("---")) return { present: false };
-  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---(\r?\n|$)/);
-  if (!m) return { present: true, parsed: false };
-  const meta = {};
-  for (const line of m[1].split("\n")) {
-    if (/^\s*#/.test(line) || !line.trim()) continue;
-    const kv = line.match(/^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/);
-    if (kv) meta[kv[1]] = kv[2].replace(/\s+#.*$/, "").replace(/^["']|["']$/g, "").trim();
-    else if (!/^\s+/.test(line)) return { present: true, parsed: false };
-  }
-  return { present: true, parsed: true, meta, body: text.slice(m[0].length) };
-}
-
-const concepts = new Map(); // rel path -> { meta, body }
-for (const f of files) {
-  const r = rel(f);
-  const text = readFileSync(f, "utf8");
-  const fm = parseFrontmatter(text);
-  if (isReserved(f)) {
-    if (fm.present && fm.parsed && fm.meta.type) errors.push(`${r}: reserved file must not carry a 'type'`);
-    if (fm.present && fm.parsed && posix.basename(r) === "index.md" && r !== "index.md") {
-      const keys = Object.keys(fm.meta);
-      if (keys.some((k) => k !== "okf_version")) warnings.push(`${r}: only the bundle-root index.md may carry frontmatter`);
-    }
-    concepts.set(r, { reserved: true, body: fm.parsed ? fm.body : text });
-    continue;
-  }
-  if (!fm.present) { errors.push(`${r}: missing YAML frontmatter`); continue; }
-  if (!fm.parsed) { errors.push(`${r}: unparseable YAML frontmatter`); continue; }
-  if (!fm.meta.type) errors.push(`${r}: missing or empty required field 'type'`);
-  if (strict) {
-    if (!fm.meta.title) warnings.push(`${r}: missing recommended field 'title'`);
-    if (!fm.meta.description) warnings.push(`${r}: missing recommended field 'description'`);
-  }
-  concepts.set(r, { meta: fm.meta, body: fm.body });
-}
-
-if (strict) {
-  // Link checks (log.md bodies exempt) + reachability from index files.
-  const reachable = new Set();
-  const linkRe = /\[[^\]]*\]\(([^)\s]+)\)/g;
-  const resolveLink = (fromRel, target) => {
-    if (/^[a-z]+:\/\//i.test(target) || target.startsWith("mailto:")) return null; // external
-    const clean = target.split("#")[0];
-    if (!clean) return null;
-    const abs = clean.startsWith("/")
-      ? posix.normalize(clean.slice(1))
-      : posix.normalize(posix.join(posix.dirname(fromRel), clean));
-    return abs;
-  };
-  for (const [r, c] of concepts) {
-    const body = c.body ?? "";
-    const fromLog = posix.basename(r) === "log.md";
-    for (const m of body.matchAll(linkRe)) {
-      const t = resolveLink(r, m[1]);
-      if (t === null) continue;
-      const isDir = t.endsWith("/") || concepts.has(posix.join(t, "index.md")) || existsSync(join(root, t)) && statSync(join(root, t)).isDirectory?.();
-      if (posix.basename(r) === "index.md" || !fromLog) {
-        if (!t.endsWith(".md") && !isDir) { if (!fromLog) warnings.push(`${r}: link missing .md extension: ${m[1]}`); continue; }
-      }
-      if (fromLog) continue; // history exempt from broken-link lint
-      if (t.endsWith(".md") && !concepts.has(t)) warnings.push(`${r}: broken link: ${m[1]}`);
-      if (posix.basename(r) === "index.md" && t.endsWith(".md") && concepts.has(t)) reachable.add(t);
-      if (posix.basename(r) === "index.md" && isDir) reachable.add(posix.join(t.replace(/\/$/, ""), "index.md"));
-    }
-  }
-  // Reachability: walk index closure (an index that lists a subdir makes that subdir's index reachable).
-  for (const [r, c] of concepts) {
-    if (c.reserved || reachable.has(r)) continue;
-    // root-level concepts listed in root index handled above; report the rest
-    const anyIndex = [...concepts.keys()].some((k) => posix.basename(k) === "index.md");
-    if (anyIndex) warnings.push(`${r}: unreachable from any index.md`);
-  }
-}
-
-const conceptCount = [...concepts.values()].filter((c) => !c.reserved).length;
-if (asJson) {
-  console.log(JSON.stringify({ bundle: root, concepts: conceptCount, errors, warnings, conformant: errors.length === 0 }, null, 2));
-} else {
-  console.log(`OKF validate — ${root}`);
-  console.log(`  ${conceptCount} concept(s), ${errors.length} error(s), ${warnings.length} warning(s)`);
-  for (const e of errors) console.log(`  ERROR ${e}`);
-  for (const w of warnings) console.log(`  warn  ${w}`);
-  console.log(errors.length === 0 ? (strict && warnings.length ? "PASS (with lints)" : "PASS — conformant") : "FAIL — nonconformant");
-}
-process.exit(errors.length > 0 ? 1 : strict && warnings.length > 0 && process.env.OKF_STRICT_EXIT ? 1 : 0);

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

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

@@ -1,46 +0,0 @@
-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();}
-}