@awebai/oats 0.23.0 → 0.23.2

package/capabilities/oats-okf/injects/okf.md

@@ -1,69 +1,34 @@
 ## Knowledge: OKF
 
-Your knowledge layer is **OKF** (Open Knowledge Format). Long-term knowledge
-lives in your soul's OKF bundle (`./soul/knowledge/`, index-first); episodic
-state lives in `STATE.md`/`log.md`/`notes/`.
-
-**Before working — every session, no exceptions:**
-
-1. **Load the okf skill.** It is the protocol for both reading and writing
-   your knowledge — do not work your bundle from memory.
-2. Read `./STATE.md` and recent `./log.md` — if STATE.md has a plan/progress
-   you are resuming, continue from its `# Next`.
-3. **Check your knowledge for the task at hand**: open
-   `./soul/knowledge/index.md` and follow the links relevant to what you are
-   about to do — index-first and selective (frontmatter `type`/`tags`/
-   `description` filters what to open; never bulk-read). Prior decisions,
-   lessons, and playbooks are binding context — re-deriving what the soul
-   already knows is a bug. Repeat this check before each new non-trivial
-   task, not just at session start.
-
-Keep STATE.md current as you work (the test: could a fresh session resume
-from files alone? its `# Next` names the single next action). Append dated
-milestones to `./log.md` (newest first).
-
-**Write down what you learn.** Anything you figured out that was not obvious
-— a gotcha, a decision and its why, a procedure that worked — goes in
-`./notes/`, one OKF concept per insight, as you go. Do not judge whether it
-is "important enough"; that is someone else's job. Just capture it
-faithfully.
-
-**Before every commit, bring memory up to date**: STATE.md current, log.md
-milestone appended, fresh insights in `./notes/`.
-
-**After committing with pending notes, launch the harvester yourself**: run
-
-```bash
-oats okf harvest
-```
-
-from your instance home. It spawns the memory-harvest agent attached to your
-work tree to promote your notes into the soul (it skips cleanly when there
-are no notes or a harvester is already running — calling it "too often" is
-safe; not calling it means your insights never reach the soul, and unwritten
-or unharvested notes are lost when your home is retired).
-
-**If you write few notes** (a coordinating or reviewing role, a standing
-session): still run `oats okf harvest` at task boundaries, and at least once
-a day. With no notes pending it harvests your own captured session turns
-since the last harvest instead; the harvester judges them under the same
-bar. It skips when nothing is new. `oats okf harvest --from-record` asks for
-the record even when notes are pending.
-
-**Workspace-mode instances**: your soul lives in its own home repo, and your
-`./work` (the workspace) is not where it commits. `oats okf harvest` handles
-this — it promotes your notes in a worktree of the soul's home repo and
-delivers the update **as a PR to that repo**, never a direct push and never
-a commit into member repos. Your job is unchanged: write notes, commit
-nothing yourself, call the harvester.
-
-**Local-soul instances**: your soul is uncommitted by design (it lives in
-`local-agents/`, gitignored). The harvester edits your soul directly — no
-commit, no PR. Your job is still unchanged: write notes, commit your WORK
-normally, call the harvester.
-
-The okf skill you loaded at session start also governs writing: notes,
-concepts, index.md, and log.md follow its format craft (concepts,
-frontmatter, index/log discipline, validation). Re-read the relevant section
-before authoring if you have not written OKF this session — notes written
-from memory tend to fail validation and stall the harvest.
+Your knowledge is external to the soul. Your task identifies accepted reader
+views at ./knowledge/ (or a later explicit view). Read view.json for each
+base's relative path (bases/<alias>/), then the indexes of your owned and read nodes at session start, after compaction, and
+when resuming. Follow only links relevant to the task: do not bulk-load bases.
+Each base is one link namespace: `/node/concept.md` resolves from that base's
+root, not the filesystem root. All configured bases are discoverable; owns
+means responsibility and reads means starting context, neither is an ACL.
+
+Consult prior decisions before re-deriving them. Cite base/node/concept paths.
+Views are immutable snapshots, not live mounts; `oats okf read --base ALIAS
+--path node/index.md` retrieves current accepted text. `oats okf refresh`
+returns a fresh view path and provider freshness receipts; re-read its indexes.
+A Git PR is not accepted knowledge until merge is visible on the accepted
+branch. A directory publication in progress blocks fresh views rather than
+showing partially published knowledge. Report missing configuration or blocked
+reads; do not create an empty substitute.
+
+**Never write accepted knowledge or soul knowledge.** This is an instruction
+boundary, not a filesystem sandbox. Read through the provided views, not by
+editing the base behind them. Skills remain curated soul artifacts.
+
+Keep your task-local memory in instance home, not ./work:
+- STATE.md: rewrite the current task and progress; # Next names one next step.
+- log.md: append dated significant events; never rewrite history.
+- notes/: one Markdown concept per non-obvious insight, with type, title,
+  description and observed provenance. Capture without judging importance.
+  Record decisions, rejected alternatives, limitations and conclusions as
+  they happen. Never include credentials or third-party messages verbatim.
+
+After compaction re-read STATE.md and the relevant knowledge indexes before
+continuing. Update memory before task boundaries. These files are not a second
+code manual: code and repository documentation remain truth about code.

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

@@ -0,0 +1,112 @@
+import { isAbsolute } from 'node:path';
+import { fs, join, resolve, dirname, fail, readJSON, safePath, relPath, identifier, overlaps, hash } 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','harvest-runtime','harvest-model'],'OATS_SETTINGS');
+  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;
+}
+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');
+      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');
+  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});

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

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

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

@@ -0,0 +1,103 @@
+import * as fs from 'node:fs';
+import { dirname, resolve, relative, isAbsolute, join, sep, basename } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { hostname } from 'node:os';
+import { spawnSync } from 'node:child_process';
+export { fs, join, resolve, dirname };
+export const fail = (code, message) => { throw Object.assign(new Error(message), { code }); };
+export const hash = value => createHash('sha256').update(typeof value === 'string' || Buffer.isBuffer(value) ? value : JSON.stringify(value)).digest('hex');
+export const readJSON = path => JSON.parse(fs.readFileSync(path, 'utf8'));
+export const within = (root, path) => { const r = relative(root, path); return r === '' || (!r.startsWith('..' + sep) && r !== '..' && !isAbsolute(r)); };
+export const overlaps = (a, b) => within(a, b) || within(b, a);
+export function safePath(path) {
+  path = resolve(path);
+  let part = path;
+  while (true) {
+    try { if (fs.lstatSync(part).isSymbolicLink()) fail('E_PATH', `symlink not allowed: ${part}`); }
+    catch (e) { if (e.code !== 'ENOENT') throw e; }
+    if (dirname(part) === part) break;
+    part = dirname(part);
+  }
+  return path;
+}
+export function relPath(p, dot = false) {
+  if (typeof p !== 'string' || (!dot && p === '.') || !p || p.includes('\\') || p.includes('\0') || isAbsolute(p) || p.split('/').some(x => !x || x === '..' || (x === '.' && p !== '.')) || p.split('/').some(x => x === '.git')) fail('E_PATH', `noncanonical relative path: ${p}`);
+  return p;
+}
+export function identifier(value) {
+  if (typeof value !== 'string' || !/^[a-zA-Z0-9][a-zA-Z0-9._-]{0,95}$/.test(value) || ['constructor','__proto__','prototype','toString','valueOf'].includes(value)) fail('E_ID', `invalid identity: ${value}`);
+  return value;
+}
+export function syncDir(dir) { const fd = fs.openSync(dir, 'r'); try { fs.fsyncSync(fd); } finally { fs.closeSync(fd); } }
+export function atomic(path, bytes, { tempDir = dirname(path) } = {}) {
+  safePath(path); fs.mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  // Publication may stage in its owned lock directory, outside accepted data.
+  safePath(tempDir);
+  const temp = join(tempDir, `${basename(path)}.tmp-${randomUUID()}`);
+  const fd = fs.openSync(temp, 'wx', 0o600);
+  try { fs.writeFileSync(fd, bytes); fs.fsyncSync(fd); } finally { fs.closeSync(fd); }
+  fs.renameSync(temp, path); syncDir(dirname(path));
+}
+export const save = (path, obj) => atomic(path, JSON.stringify(obj, null, 2) + '\n');
+export function tree(root, { git = false } = {}) {
+  safePath(root); const files = {};
+  function walk(dir) {
+    for (const d of fs.readdirSync(dir, { withFileTypes: true }).sort((a,b) => a.name.localeCompare(b.name))) {
+      if (git && dir === root && d.name === '.git') continue;
+      const path = join(dir, d.name); safePath(path);
+      if (d.isDirectory()) walk(path);
+      else if (d.isFile()) { if (fs.statSync(path).nlink !== 1) fail('E_PATH', `hardlink not allowed: ${path}`); files[relative(root, path).split(sep).join('/')] = fs.readFileSync(path).toString('base64'); }
+      else fail('E_PATH', `unsupported entry: ${path}`);
+    }
+  }
+  walk(root); return files;
+}
+export const digest = files => hash(Object.fromEntries(Object.entries(files).sort(([a],[b])=>a.localeCompare(b))));
+export function materialize(root, files) {
+  safePath(root); fs.mkdirSync(root, { recursive: true });
+  for (const [p, content] of Object.entries(files)) atomic(join(root, relPath(p)), Buffer.from(content, 'base64'));
+}
+export function withLock(path, fn) {
+  safePath(path); fs.mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+  try { fs.mkdirSync(path, { mode: 0o700 }); } catch(e) { if(e.code === 'EEXIST') fail('E_LOCKED', `busy or abandoned lock: ${path}; inspect owner.json, never reclaim by age`); throw e; }
+  const owner = { token: randomUUID(), pid: process.pid, host: hostname() };
+  save(join(path, 'owner.json'), owner);
+  try { return fn(); } finally { if (readJSON(join(path, 'owner.json')).token === owner.token) { fs.rmSync(path, { recursive: true }); syncDir(dirname(path)); } }
+}
+export function unlock(path, token) {
+  safePath(path); const o = readJSON(join(path, 'owner.json'));
+  if (!token || o.token !== token || o.host !== hostname()) fail('E_LOCKED', 'explicit matching local lock token required');
+  try { process.kill(o.pid, 0); fail('E_LOCKED', 'lock owner is still alive'); } catch (e) { if(e.code !== 'ESRCH') throw e; }
+  fs.rmSync(path, { recursive: true }); syncDir(dirname(path)); return { unlocked: path };
+}
+export const identityKeys = ['OATS_INSTANCE','OATS_INSTANCE_HOME','OATS_HOME','PI_AGENT_HOME','PI_AGENT_NAME','PI_AGENT_INSTANCE','PI_AGENTS_ROOT','OATS_ROOT','OATS_SOUL','OATS_AGENT','OATS_KIND','OATS_EVENT','OATS_CONTEXT','OATS_REPO','OATS_WORK','OATS_BRANCH','OATS_META','OATS_SETTINGS'];
+export function cleanEnv(env = process.env) {
+  return Object.fromEntries(Object.entries(env).filter(([k]) => !/^(OATS_(?!HOME_DIR$|PACKAGE_CATALOG$)|PI_AGENT|GIT_)/.test(k)));
+}
+export function exec(bin, args, { cwd, env = cleanEnv(), timeout = 30000, maxBuffer = 16*1024*1024, acceptedStatus = [0] } = {}) {
+  const r = spawnSync(bin, args, { cwd, env, encoding: 'utf8', timeout, maxBuffer });
+  if(r.error || !acceptedStatus.includes(r.status)) throw Object.assign(new Error(`${bin} ${args[0]} failed: ${r.error?.message || r.stderr || `exit ${r.status}`}`),{code:'E_COMMAND',stdout:r.stdout,status:r.status});
+  return r.stdout.trim();
+}
+export function cliPath() {
+  const p = process.env.OATS_CLI_BIN;
+  if (!p || !isAbsolute(p)) fail('E_RUNTIME', 'absolute OATS_CLI_BIN required; never resolve oats on PATH');
+  return p;
+}
+export function oats(args, cwd, { native = false, ...opts } = {}) {
+  let text;
+  try {text = exec(cliPath(), args, { cwd, ...opts });}
+  catch(e) {
+    let response;try {response=JSON.parse(e.stdout);} catch { /* unknown side effect, preserve command failure */ }
+    if(response?.schemaVersion===1 && response.ok===false) fail(response.error?.code || 'E_RUNTIME',response.error?.message || 'CLI failed');
+    throw e;
+  }
+  let o; try { o = JSON.parse(text); } catch { fail('E_RUNTIME', 'unsupported CLI JSON response'); }
+  if(native) return o;
+  if(o.schemaVersion !== 1 || o.ok !== true) fail(o.error?.code || 'E_RUNTIME', o.error?.message || 'unsupported CLI envelope');
+  return o.result;
+}
+export const quote = v => `'${String(v).replaceAll("'", "'\\''")}'`;
+export function command(cwd, argv) {
+  return `cd ${quote(cwd)} && env ${identityKeys.map(k => `-u ${quote(k)}`).join(' ')} ${[cliPath(), ...argv].map(quote).join(' ')}`;
+}

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

@@ -0,0 +1,116 @@
+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);
+  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 stage=stageBase(base,output); 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(join(dir,'migration.json'),record);
+  return {status:'staged',migration:join(dir,'migration.json'),originalPreserved:true,stage:stage.root};
+}
+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));
+      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.'};
+}