@awebai/oats 0.27.2 → 0.29.0

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

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

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

@@ -99,13 +99,21 @@ export function capturedAuthority(source) {
   return {...base,registration:'captured',capture:'recorded',migrationRequired:false,sourceIdentity:JSON.parse(JSON.stringify(identity)),executionBinding:JSON.parse(JSON.stringify(binding)),
     responsibleHuman:{status:source.responsibleHuman===null?'disabled':'specified'}};
 }
+/** A ./knowledge/ snapshot written by okf 2.x. okf 3.0.0 never reads it
+ *  (knowledge is consulted remotely) and never deletes it. */
+export function legacyLocalView(source,status=loadStatus(source)) {
+  if(!liveHome(source,status).available) return null;
+  const path=join(safePath(source.home),'knowledge');let stat;
+  try {stat=fs.lstatSync(path);} catch(e) {if(missing(e)) return null;throw e;} // never follow it
+  return {status:'legacy-local-view',path,ignored:true,...(stat.isSymbolicLink()?{symlink:true}:{}),note:'okf 3.0.0 ignores this okf 2.x snapshot and reads knowledge remotely; it is safe to delete by hand'};
+}
 export function inspect(source) {
-  const status=loadStatus(source),working=workingDocuments(source,status);
+  const status=loadStatus(source),working=workingDocuments(source,status),legacy=legacyLocalView(source,status);
   let health;try {health=oats(['schedule','list','--dir',source.context,'--json'],source.context).scheduler;} catch(e) {health={active:false,error:e.message};}
   const documents=[...working.documents,{label:'Durable processing receipts',kind:'text',path:join(dirname(source.file),'status.json'),text:JSON.stringify(status,null,2)}];
   return {
-    summary:`OKF ${source.id}: ${status.captured.inputs.length-status.processed.length} unprocessed inputs; ${status.retired?'source retired':'source not retired'}; ${working.liveMemory.available?`${working.documents.length} working-memory documents`:`live memory unavailable (${working.liveMemory.reason})`}`,
+    summary:`OKF ${source.id}: ${status.captured.inputs.length-status.processed.length} unprocessed inputs; ${status.retired?'source retired':'source not retired'}; ${working.liveMemory.available?`${working.documents.length} working-memory documents`:`live memory unavailable (${working.liveMemory.reason})`}${legacy?'; legacy-local-view ./knowledge/ (ignored, safe to delete)':''}`,
     source:source.file,owns:source.decl.owns,reads:source.decl.reads,bases:source.bindings.bases,authority:capturedAuthority(source),
-    acceptedView:source.acceptedView,status,scheduler:health,liveMemory:working.liveMemory,documents
+    acceptedView:source.acceptedView,legacyLocalView:legacy,status,scheduler:health,liveMemory:working.liveMemory,documents
   };
 }

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

@@ -57,9 +57,16 @@ 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) {
+const pause = ms => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+/** Cooperative directory lock. `waitMs` lets a reader queue behind a live
+ *  holder for a bounded time; an abandoned lock is still never reclaimed. */
+export function withLock(path, fn, { waitMs = 0 } = {}) {
   safePath(path); fs.mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
-  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 deadline = Date.now() + waitMs;
+  for (let delay = 20;; delay = Math.min(delay * 2, 250)) {
+    try { fs.mkdirSync(path, { mode: 0o700 }); break; }
+    catch(e) { if(e.code !== 'EEXIST') throw e; if(Date.now() >= deadline) fail('E_LOCKED', `busy or abandoned lock: ${path}; inspect owner.json, never reclaim by age`); pause(delay); }
+  }
   const owner = { token: randomUUID(), pid: process.pid, host: hostname() };
   save(join(path, 'owner.json'), owner);
   try { return fn(); } finally { if (readJSON(join(path, 'owner.json')).token === owner.token) { fs.rmSync(path, { recursive: true }); syncDir(dirname(path)); } }

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

@@ -0,0 +1,123 @@
+#!/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/sources.mjs

@@ -1,10 +1,11 @@
 import { randomUUID } from 'node:crypto';
-import { fs, join, dirname, resolve, safePath, readJSON, save, atomic, materialize, hash, withLock, oats, fail, tree, overlaps, syncDir, identifier, relPath } from './io.mjs';
-import { loadBindings, declaration, metadata, resolveNodes, bindingFingerprint, settings, validateBindings } from './config.mjs';
-import { stageBase } from './stores.mjs';
+import { fs, join, dirname, resolve, safePath, readJSON, save, atomic, hash, withLock, oats, fail, tree, overlaps, identifier } from './io.mjs';
+import { loadBindings, declaration, bindingFingerprint, settings, validateBindings } from './config.mjs';
+import { acceptedResolution } from './consult.mjs';
 import { loadInvocationKnowledgeBinding, readPrivateInvocationJson, sourceRuntimeFromKnowledgeBinding } from './binding-wire.mjs';
 import { sameJson } from './portable-binding.mjs';
 import { qualifiedSoulIdentity } from './source-contract.mjs';
+import { harvestSwitch, instanceRecordPath } from './harvest-switch.mjs';
 
 const obj=value=>value!==null && typeof value==='object' && !Array.isArray(value);
 function exact(value,allowed,required,label) {
@@ -89,48 +90,37 @@ export function service(home) {
   if(fs.existsSync(join(home,'instance.json'))) return readJSON(join(home,'instance.json')).kind==='capability';
   return process.env.OATS_KIND==='capability';
 }
-// Control files live at the view root; arbitrary legal aliases live ONLY in
-// bases/. Receipts use paths relative to the view so moving a prepared view
-// into its final location cannot invalidate its navigation.
-export function views(bindings, decl, target) {
-  target=safePath(target); if(fs.existsSync(target)) fail('E_VIEW','view exists; use a new immutable view destination');
-  const all={}; const receipts={};
-  fs.mkdirSync(dirname(target),{recursive:true});
-  const pending=fs.mkdtempSync(join(dirname(target),'.okf-view-'));
-  try {
-    for(const [alias,base] of Object.entries(bindings.bases)) {
-      const scratch=fs.mkdtempSync(join(bindings.stateDir,'read-'));
-      try {
-        const staged=stageBase(base,join(scratch,'base'),{alias});
-        all[alias]=staged.meta;
-        const path=`bases/${alias}`;
-        materialize(join(pending,path),staged.files);
-        receipts[alias]={path,id:base.id,digest:staged.digest,head:staged.head || null,nodes:staged.meta.nodes};
-      } finally { fs.rmSync(scratch,{recursive:true,force:true}); }
-    }
-    resolveNodes(decl,bindings,all);
-    save(join(pending,'view.json'),{version:1,at:new Date().toISOString(),bases:receipts,owns:decl.owns,reads:decl.reads});
-    // Never expose a partial view or remove/replace a caller's existing view.
-    if(fs.existsSync(target)) fail('E_VIEW','view exists; use a new immutable view destination');
-    fs.renameSync(pending,target);syncDir(dirname(target));
-    return receipts;
-  } finally { fs.rmSync(pending,{recursive:true,force:true}); }
+// okf 3.0.0 materializes no instance copy of any base: registration records
+// the accepted resolution (per base: commit or digest, and its nodes) and the
+// instance consults the bases remotely through `oats okf`. A ./knowledge/ left
+// by okf 2.x is not touched; inspect reports it as a legacy local view.
+const acceptedNodes = view => Object.fromEntries(Object.entries(view).map(([alias,row])=>[alias,row.nodes]));
+/** Instance knowledge (STATE.md, log.md, notes/) exists whether or not this
+ *  instance is harvested: it is the instance's own working memory. */
+export function ensureInstanceKnowledge(home) {
+  for(const [p,text] of [['STATE.md','# Working state\n\n# Task\n\n# Next\n'],['log.md','# Instance log\n']]) if(!fs.existsSync(join(home,p))) atomic(join(home,p),text);
+  fs.mkdirSync(join(home,'notes'),{recursive:true});
 }
-const registrationView = source => join(source.home,`.okf-view-${source.id}`);
 function finishRegistration(source) {
-  const pending=safePath(registrationView(source)),target=safePath(join(source.home,'knowledge'));
-  if(fs.existsSync(pending)) {
-    if(fs.existsSync(target)) fail('E_VIEW','knowledge already exists; refusing to replace it with the registered view');
-    fs.renameSync(pending,target);syncDir(source.home);
-  }
   // A durable home pointer precedes publication. Failures after it was saved
-  // resume this same source/view; they never reset captured evidence or IDs.
-  const receipt=readJSON(join(target,'view.json'));
-  if(source.acceptedView && JSON.stringify(receipt.bases)!==JSON.stringify(source.acceptedView)) fail('E_VIEW','registered accepted view receipt differs; preserve it and inspect');
-  for(const [p,text] of [['STATE.md','# Working state\n\n# Task\n\n# Next\n'],['log.md','# Instance log\n']]) if(!fs.existsSync(join(source.home,p))) atomic(join(source.home,p),text);
-  fs.mkdirSync(join(source.home,'notes'),{recursive:true});
+  // resume this same source; they never reset captured evidence or IDs.
+  ensureInstanceKnowledge(source.home);
   scheduleSource(source);return source;
 }
+/** Harvest off (okf 4.0.0): no source, no custody, no schedule. The home keeps
+ *  a small record so retire knows there is nothing to capture. */
+function harvestOff(home,sw,extra={}) {
+  const record={version:1,harvest:'off',reason:sw.reason,rows:sw.rows,warnings:sw.warnings,at:new Date().toISOString()};
+  atomic(instanceRecordPath(home),JSON.stringify(record,null,2)+'\n');
+  ensureInstanceKnowledge(home);
+  return {harvestOff:true,switch:sw,home,...extra};
+}
+export const harvestOffRecord = home => fs.existsSync(instanceRecordPath(home))?readJSON(instanceRecordPath(home)):null;
+/** The source's tasks provider (its instance.json tasks-layer capability), or null. */
+function tasksProvider(meta) {
+  const row=Array.isArray(meta?.capabilities)?meta.capabilities.find(c=>c && c.layer==='tasks' && typeof c.id==='string'):null;
+  return row?row.id:null;
+}
 function capturedOwner(bindings,owner,identity) {
   const file=join(bindings.stateDir,'owners.json'),row={schemaVersion:1,kind:'captured-qualified-soul',identity};
   withLock(join(bindings.stateDir,'owners.lock'),()=>{
@@ -155,9 +145,10 @@ export function registerCaptured(home,receipt) {
     const source=homeSource(home);if(!sameCapturedReceipt(source,receipt,captured)) fail('E_SOURCE','captured registration receipt differs from durable source');
     return finishRegistration(source);
   }
-  safePath(join(home,'knowledge'));
-  if(fs.existsSync(join(home,'knowledge'))) fail('E_VIEW','unregistered knowledge view exists; preserve it and inspect before registering');
   if(['.okf-harvest-record.json','.okf-harvest-record.next.json'].some(path=>fs.existsSync(join(home,path)))) fail('E_MIGRATION','legacy source watermarks require explicit migration before captured registration');
+  // The captured path takes its authority from the frozen binding and never
+  // reads live settings or the soul, so the 4.0.0 harvest switch (a live host
+  // setting) does not apply here. No released kernel drives this path.
   if(overlaps(home,captured.context) && captured.context.startsWith(home)) fail('E_PATH','captured deployment context cannot be in disposable home');
   const {file:bindingsFile,...bindingsDoc}=captured.binding.bindings;
   const bindings={file:bindingsFile,...validateBindings(bindingsDoc,bindingsFile,{sourceHome:home,sourceWork:captured.work})};
@@ -167,13 +158,13 @@ export function registerCaptured(home,receipt) {
     bindingFingerprint:bindingFingerprint(bindings),execution:captured.binding.execution,providerBinding:JSON.parse(JSON.stringify(receipt.binding)),
     registration:{schemaVersion:1,kind:'captured'},sourceIdentity:captured.sourceIdentity,executionBinding:captured.execution,
     responsibleHuman:captured.responsibleHuman,created:new Date().toISOString()};
-  const file=join(dir,'source.json'),pending=registrationView(source);fs.mkdirSync(dir,{recursive:true,mode:0o700});
+  const file=join(dir,'source.json');fs.mkdirSync(dir,{recursive:true,mode:0o700});
   try {
-    source.acceptedView=views(bindings,source.decl,pending);source.acceptedNodes=Object.fromEntries(Object.entries(source.acceptedView).map(([alias,row])=>[alias,row.nodes]));
+    source.acceptedView=acceptedResolution(bindings,source.decl);source.acceptedNodes=acceptedNodes(source.acceptedView);
     save(file,source);save(join(dir,'status.json'),{version:1,captured:{notes:[],threads:{},inputs:[]},processed:[],delivered:{},accepted:{},retired:false,auto:true,activeRun:null});
     save(markerPath(home),{version:1,id,source:file});
   } catch(error) {
-    if(!fs.existsSync(markerPath(home))) {fs.rmSync(pending,{recursive:true,force:true});fs.rmSync(dir,{recursive:true,force:true});}
+    if(!fs.existsSync(markerPath(home))) fs.rmSync(dir,{recursive:true,force:true});
     throw error;
   }
   return finishRegistration({...source,file});
@@ -188,8 +179,6 @@ export function register(home) {
   }
   if(service(home)) return {skipped:'service'};
   if(fs.existsSync(markerPath(home))) return finishRegistration(homeSource(home));
-  safePath(join(home,'knowledge'));
-  if(fs.existsSync(join(home,'knowledge'))) fail('E_VIEW','unregistered knowledge view exists; preserve it and inspect before registering');
   if(['.okf-harvest-record.json','.okf-harvest-record.next.json'].some(p=>fs.existsSync(join(home,p))) && !fs.existsSync(join(home,'.okf-v1-migration.json'))) fail('E_MIGRATION','legacy source watermarks require explicit oats okf migrate --source-home PATH before v2 registration; no cursor is silently trusted');
   const meta=fs.existsSync(join(home,'instance.json'))?readJSON(join(home,'instance.json')):{};
   if(!process.env.OATS_SOUL) fail('E_OATS_SOUL_MISSING','OATS_SOUL is not set; oats.okf hooks and commands run only under the OATS kernel');
@@ -203,6 +192,8 @@ export function register(home) {
   const agent=process.env.OATS_AGENT || meta.agent;
   const instance=process.env.OATS_INSTANCE || meta.instance;
   if(!agent || !instance) fail('E_SOURCE','source instance/agent required');
+  const sw=harvestSwitch({settings:settings(),soulDir:soul});
+  if(sw.effective!=='on') {acceptedResolution(bindings,decl);return harvestOff(home,sw,{decl});}
   fs.mkdirSync(bindings.stateDir,{recursive:true,mode:0o700});
   const ownersFile=join(bindings.stateDir,'owners.json');
   const id=randomUUID(); const dir=join(bindings.stateDir,'sources',id);
@@ -211,24 +202,20 @@ export function register(home) {
   const roleFile=safePath(join(soul,'AGENTS.md'));
   const role=fs.existsSync(roleFile)?fs.readFileSync(roleFile,'utf8'):'';
   if(Buffer.byteLength(role)>128*1024) fail('E_SOURCE','role document exceeds 128KiB; provide a concise role before registering');
-  const source={version:1,id,home,work,context,agent,instance,owner:decl.owner,decl,role,bindings,bindingFingerprint:bindingFingerprint(bindings),execution:{runtime:settings()['harvest-runtime']||'pi',model:settings()['harvest-model']||null},created:new Date().toISOString()};
+  const source={version:1,id,home,work,context,agent,instance,owner:decl.owner,decl,role,bindings,bindingFingerprint:bindingFingerprint(bindings),execution:{runtime:settings()['harvest-runtime']||'pi',model:settings()['harvest-model']||null},soulId,tasksProvider:tasksProvider(meta),created:new Date().toISOString()};
   const file=join(dir,'source.json');
-  const pending=registrationView(source);
   fs.mkdirSync(dir,{recursive:true,mode:0o700});
   try {
-    source.acceptedView=views(bindings,decl,pending);
+    source.acceptedView=acceptedResolution(bindings,decl);
     pinOwner(ownersFile,decl.owner,{id:soulId,soulName:agent,path:soul});
-    source.acceptedNodes=Object.fromEntries(Object.entries(source.acceptedView).map(([alias,r])=>[alias,r.nodes]));
+    source.acceptedNodes=acceptedNodes(source.acceptedView);
     save(file,source);
     save(join(dir,'status.json'),{version:1,captured:{notes:[],threads:{},inputs:[]},processed:[],delivered:{},accepted:{},retired:false,auto:true,activeRun:null});
     save(markerPath(home),{version:1,id,source:file});
   } catch(e) {
     // Until the pointer is durable no capture or schedule can reference these
     // files. Leave an installed pointer's state intact even if fsync failed.
-    if(!fs.existsSync(markerPath(home))) {
-      fs.rmSync(pending,{recursive:true,force:true});
-      fs.rmSync(dir,{recursive:true,force:true});
-    }
+    if(!fs.existsSync(markerPath(home))) fs.rmSync(dir,{recursive:true,force:true});
     throw e;
   }
   return finishRegistration({...source,file});

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

@@ -4,10 +4,10 @@ import { tmpdir } from 'node:os';
 import { fileURLToPath } from 'node:url';
 import { fs, join, dirname, safePath, readJSON, save, atomic, tree, materialize, digest, hash, withLock, exec, cleanEnv, fail, relPath, overlaps, resolve } from './io.mjs';
 import { metadata, noGit, gitTimeoutMs } from './config.mjs';
-const validator = fileURLToPath(new URL('../skills/okf/scripts/okf-validate.mjs', import.meta.url));
+const validator = fileURLToPath(new URL('./okf-validate.mjs', import.meta.url));
 // Never let local replace refs reinterpret frozen OIDs, including inside Git's
 // transport subprocesses. Override even an explicitly supplied command env.
-const gitEnv = (env = cleanEnv()) => ({...env,GIT_NO_REPLACE_OBJECTS:'1'});
+export const gitEnv = (env = cleanEnv()) => ({...env,GIT_NO_REPLACE_OBJECTS:'1'});
 export const git = (cwd,args,opts={}) => exec('git',['--no-replace-objects','-c','core.hooksPath=/dev/null','-c','protocol.ext.allow=never','-C',cwd,...args],{cwd,...opts,env:gitEnv(opts.env)});
 function baseError(code,message,base,alias,step,reason) {throw Object.assign(new Error(message),{code,base:alias,repository:base.repository,step,reason});}
 function baseRemedy(alias) {return `fix the binding for base alias "${alias}" in the bindings file, or remove the base from the bindings`;}
@@ -19,22 +19,25 @@ function classifyGitFailure(error) {
   if(/could not resolve host|failed to connect|connection refused|network is unreachable|no route to host|proxy/i.test(text)) return 'network';
   return 'unknown';
 }
-function unavailable(base,alias,step,error) {
+export function unavailable(base,alias,step,error) {
   const reason=classifyGitFailure(error),detail=reason==='unknown'?`; original Git failure: ${String(error?.message || 'unknown failure')}`:'';
   const message=`Git base "${alias}" repository "${base.repository}" is required by the deployment's bindings, but ${step} failed (reason: ${reason}${detail}); ${baseRemedy(alias)}`;
   baseError('E_BASE_UNAVAILABLE',message,base,alias,step,reason);
 }
-function requireNotShallow(base,alias,cwd) {
+export function requireNotShallow(base,alias,cwd) {
   const shallow=git(cwd,['rev-parse','--is-shallow-repository']);
   if(shallow==='true') baseError('E_BASE_SHALLOW',`Git base "${alias}" repository "${base.repository}" is required by the deployment's bindings, but the repository is shallow; oats.okf requires full accepted history before staging; ${baseRemedy(alias)}`,base,alias,'clone','shallow');
 }
-function preflightLocalRepository(base,alias) {
+export function preflightLocalRepository(base,alias) {
   if(!base.repository.startsWith('/')) return;
   if(!fs.existsSync(base.repository)) unavailable(base,alias,'clone',Object.assign(new Error('repository not found'),{code:'ENOENT'}));
   try { requireNotShallow(base,alias,base.repository); }
   catch(e) { if(e.code==='E_BASE_SHALLOW') throw e; unavailable(base,alias,'clone',e); }
 }
 export const baseLock = b => `${b.path}.okf-lock`;
+// okf consult readers hold a directory base's lock briefly; staging and
+// publication queue behind them for a bounded time instead of failing.
+const CONSULT_READER_WAIT_MS = 10000;
 export const journalPath = b => `${b.path}.okf-publication.json`;
 export function validateBase(root, base) {
   const files=tree(root,{git:base.kind==='git' && base.root==='.'}); const meta=metadata(files,base);
@@ -123,7 +126,7 @@ export function stageBase(base, dest, { alias = base.id } = {}) {
     if(fs.existsSync(journalPath(base))) fail('E_RECOVERY',`publication pending: ${journalPath(base)}; retry its recorded run before reading`);
     const result=validateBase(base.path,base); materialize(dest,result.files);
     return {...result,root:dest};
-  });
+  },{waitMs:CONSULT_READER_WAIT_MS});
 }
 export function allowedChanges(before, after, meta, owned) {
   const changed=[...new Set([...Object.keys(before),...Object.keys(after)])].filter(p=>before[p]!==after[p]);
@@ -287,7 +290,7 @@ export function directoryPublish(base, proposal, receipt, persist, { afterWrite
     receipt.status='accepted'; receipt.acceptedDigest=final.digest; receipt.acceptedAt=new Date().toISOString(); persist();
     fs.rmSync(jp); syncParent(jp);
     return receipt;
-  });
+  },{waitMs:CONSULT_READER_WAIT_MS});
 }
 function syncParent(p) { const fd=fs.openSync(dirname(p),'r'); try {fs.fsyncSync(fd);} finally {fs.closeSync(fd);} }
 function prRows(base,branch,cwd,{identity,allBases=false}={}) {
@@ -303,7 +306,7 @@ function prRows(base,branch,cwd,{identity,allBases=false}={}) {
   const raw=exec('gh',['pr','list','--repo',base.pr.repository,'--head',branch,...(allBases?[]:['--base',base.acceptedBranch]),'--state','all','--json',fields],{cwd,env:gitEnv()});
   const rows=JSON.parse(raw); if(!Array.isArray(rows)) fail('E_PR','invalid gh PR list'); return rows;
 }
-function verifyRemote(base,cwd) {
+export function verifyRemote(base,cwd) {
   for(const mode of [[],['--push']]) {
     const urls=git(cwd,['remote','get-url',...mode,'--all','origin']).split('\n');
     if(!urls.length || urls.some(url=>url!==base.repository)) fail('E_OWNER','worker changed frozen Git publication remote or effective push destination');
@@ -350,7 +353,7 @@ function immutableCommit(cwd,oid) {
   const header=git(cwd,['cat-file','commit',oid]).split('\n\n')[0].split('\n');
   return {tree:header.find(l=>l.startsWith('tree '))?.slice(5),parents:header.filter(l=>l.startsWith('parent ')).map(l=>l.slice(7))};
 }
-export function gitPublish(base, stage, proposal, receipt, persist, {beforePublish=()=>{},prIdentity=receipt.pr}={}) {
+export function gitPublish(base, stage, proposal, receipt, persist, {beforePublish=()=>{},prIdentity=receipt.pr,pr:presentation}={}) {
   const cwd=stage.checkout, branch=`okf/${proposal.attempt || proposal.run}-${base.id}`;
   verifyRemote(base,cwd);
   const baseline=immutableCommit(cwd,stage.head);
@@ -397,7 +400,7 @@ export function gitPublish(base, stage, proposal, receipt, persist, {beforePubli
     // real Git write and receipt persistence; no guessed commit or fake repository.
     const stamp=proposal.created;
     const env={...cleanEnv(),GIT_AUTHOR_NAME:'OKF harvest',GIT_AUTHOR_EMAIL:'okf@localhost',GIT_COMMITTER_NAME:'OKF harvest',GIT_COMMITTER_EMAIL:'okf@localhost',GIT_AUTHOR_DATE:stamp,GIT_COMMITTER_DATE:stamp};
-    receipt.commit=git(cwd,['commit-tree',treeId,'-p',stage.head,'-m',`memory-harvest: ${proposal.run}`],{env});
+    receipt.commit=git(cwd,['commit-tree',treeId,'-p',stage.head,'-m',`okf-harvest: ${proposal.run}`],{env});
     receipt.status='committed'; persist();
   }
   const publication=immutableCommit(cwd,receipt.commit);
@@ -419,7 +422,12 @@ export function gitPublish(base, stage, proposal, receipt, persist, {beforePubli
   if(!rows.length) {
     beforePublish();
     receipt.status='pr-intent'; persist();
-    try { exec('gh',['pr','create','--repo',base.pr.repository,'--head',branch,'--base',base.acceptedBranch,'--title',`memory-harvest: ${proposal.run}`,'--body',`Knowledge-only proposal from durable OKF input ${proposal.run}. Review provenance and promotion judgment.`],{cwd,env:gitEnv()}); }
+    const title=presentation?.title || `okf-harvest: ${proposal.run}`,body=presentation?.body || `Knowledge-only proposal from durable OKF run ${proposal.run}. Review provenance and promotion judgment.`;
+    const label=presentation?.label;
+    // The label is what the harvest-review trigger watches: make sure the
+    // repository has it (idempotent), then open the PR carrying it.
+    if(label) try {exec('gh',['label','create',label,'--repo',base.pr.repository,'--force','--color','0E8A16','--description','OKF harvest PR (oats.okf)'],{cwd,env:gitEnv()});} catch { /* may exist already or be unmanageable; pr create reports a real problem */ }
+    try { exec('gh',['pr','create','--repo',base.pr.repository,'--head',branch,'--base',base.acceptedBranch,'--title',title,'--body',body,...(label?['--label',label]:[])],{cwd,env:gitEnv()}); }
     catch(e) {receipt.status='pr-unknown';receipt.error=e.message;persist();throw e;}
     rows=prRows(base,branch,cwd);
   }