naive-framework 0.2.0 → 0.4.0

package/schema/setup.mjs

@@ -13,6 +13,7 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, readFileSync } from "node:fs";
 import { basename, dirname, join, resolve } from "node:path";
+import { ventureFile } from "./venture-paths.mjs";
 
 const repo = new URL("..", import.meta.url).pathname;
 const load = (p) => JSON.parse(readFileSync(p, "utf8"));
@@ -23,8 +24,8 @@ const GOAL = "discovery-goal";
 export async function state(dir) {
   const { decisions } = await import("./decisions.mjs");
   const v = load(join(dir, "venture.json"));
-  const people = existsSync(join(dir, "people/people.json")) ? load(join(dir, "people/people.json")) : null;
-  const sources = existsSync(join(dir, "knowledge/sources.json")) ? load(join(dir, "knowledge/sources.json")) : { sources: [], records: {} };
+  const people = existsSync(join(ventureFile(dir, "people/people.json"))) ? load(join(ventureFile(dir, "people/people.json"))) : null;
+  const sources = existsSync(join(ventureFile(dir, "knowledge/sources.json"))) ? load(join(ventureFile(dir, "knowledge/sources.json"))) : { sources: [], records: {} };
   const catalog = load(join(repo, "schema/systems-catalog.json"));
   const types = load(join(repo, "schema/venture-types.json")).types;
   const all = decisions(dir).decisions;
@@ -51,7 +52,7 @@ export async function state(dir) {
 // An open decision whose wording an agent wrote: in setup, the founder's words the model relayed.
 const relayed = (d) => d.status !== "decided" && !!d.answer && d.provenance?.drafted_by?.kind === "agent";
 
-const founderName = (dir) => existsSync(join(dir, "people/people.json")) ? load(join(dir, "people/people.json")).people[0]?.name ?? "Founder" : "Founder";
+const founderName = (dir) => existsSync(join(ventureFile(dir, "people/people.json"))) ? load(join(ventureFile(dir, "people/people.json"))).people[0]?.name ?? "Founder" : "Founder";
 
 // One answer: a decision on file is approved; a foundation statement (or the goal) becomes a decision a person approves.
 export async function decide(dir, { id, answer, via = "api", where = "/setup" }) {
@@ -79,7 +80,7 @@ export async function decide(dir, { id, answer, via = "api", where = "/setup" })
 export async function point(dir, { fn, system, address, via = "api", actor = "person", agentId }) {
   const catalog = load(join(repo, "schema/systems-catalog.json"));
   if (!catalog.functions[fn]?.includes(system)) return { ok: false, error: `${system} is not offered for ${fn}` };
-  const file = join(dir, "knowledge/sources.json");
+  const file = join(ventureFile(dir, "knowledge/sources.json"));
   const map = existsSync(file) ? load(file) : { sources: [], records: {}, truth: "local" };
   const f = (map.functions ??= {})[fn] ??= { systems: [] };
   const entry = { system, ...(address ? { address } : {}), status: "pointed" };

package/schema/stale.mjs

@@ -23,13 +23,14 @@ import { entries } from "../interface/provenance.mjs";
 import { resolve as resolveRoute } from "../interface/router.mjs";
 import { address } from "../knowledge/connectors/contract.mjs";
 import { LOCAL, sourcesOf } from "../knowledge/connectors/index.mjs";
+import { ventureFile } from "./venture-paths.mjs";
 
 export const MARKS = ".naive/stale.json";
 const load = (p) => JSON.parse(readFileSync(p, "utf8"));
 const now = () => new Date().toISOString();
 const WRITES = new Set(["write", "accept", "baseline"]);
 
-const readMarks = (dir) => (existsSync(join(dir, MARKS)) ? load(join(dir, MARKS)) : { marks: [] });
+const readMarks = (dir) => (existsSync(ventureFile(dir, MARKS)) ? load(ventureFile(dir, MARKS)) : { marks: [] });
 
 // The latest write of each file in the log.
 function lastWrites(dir) {
@@ -52,14 +53,14 @@ export function notify(dir, { source, paths, version, at = now(), via = "framewo
   if (!paths.length) throw new Error("a notification names at least one changed path");
   // The changed items as the venture refers to them: the address always, and the bare path for its own folder
   // or for a source whose records the venture keeps a local copy of at the same path.
-  const items = paths.flatMap((p) => [address(source, p), ...(source === LOCAL || existsSync(join(dir, p)) ? [p] : [])]);
+  const items = paths.flatMap((p) => [address(source, p), ...(source === LOCAL || existsSync(ventureFile(dir, p)) ? [p] : [])]);
   const readers = new Map();
   for (const [file, e] of lastWrites(dir)) {
     if (items.includes(file)) continue;
     const hit = (e.derived_from ?? []).find((d) => items.some((i) => covers(d, i)));
     if (hit) readers.set(file, { via: "provenance", reads: hit });
   }
-  const wu = join(dir, "knowledge/where-used.json");
+  const wu = join(ventureFile(dir, "knowledge/where-used.json"));
   if (existsSync(wu)) {
     for (const fact of load(wu).facts ?? []) {
       const { r, params } = resolveRoute(fact.parent.route);
@@ -74,13 +75,13 @@ export function notify(dir, { source, paths, version, at = now(), via = "framewo
   for (const [file, how] of readers) state.marks.push({ file, ...how, because, marked_at: now() });
   state.notifications = [...(state.notifications ?? []), { ...because, marked: readers.size, received_at: now() }].slice(-100);
   mkdirSync(join(dir, ".naive"), { recursive: true });
-  writeFileSync(join(dir, MARKS), JSON.stringify(state, null, 2) + "\n");
+  writeFileSync(ventureFile(dir, MARKS), JSON.stringify(state, null, 2) + "\n");
   return { source, paths, stale: [...readers.keys()].sort() };
 }
 
 /** Whether one file is stale: the marks made after its latest write, or null when it is fresh. */
 export function staleOf(dir, file) {
-  if (!existsSync(join(dir, MARKS))) return null;
+  if (!existsSync(ventureFile(dir, MARKS))) return null;
   const written = lastWrites(dir).get(file)?.at ?? "";
   const live = readMarks(dir).marks.filter((m) => m.file === file && m.marked_at > written);
   return live.length ? { since: live[0].marked_at, because: live.map((m) => ({ ...m.because, reads: m.reads, via: m.via })), fix: `write ${file} again from the changed source; it is fresh once written` } : null;

package/schema/structure.mjs

@@ -20,6 +20,7 @@
 
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join } from "node:path";
+import { ventureFile } from "./venture-paths.mjs";
 
 const repo = new URL("..", import.meta.url).pathname;
 const load = (f) => JSON.parse(readFileSync(f, "utf8"));
@@ -74,7 +75,7 @@ export function routable(file, pattern) {
 
 // Every entry under a folder, as venture-relative paths, stopping at nested ventures and dot folders other than reserved ones.
 function walk(dir, sub = "") {
-  const d = join(dir, sub);
+  const d = ventureFile(dir, sub);
   return readdirSync(d, { withFileTypes: true }).flatMap((e) => {
     const rel = sub ? `${sub}/${e.name}` : e.name;
     if (e.isDirectory()) {
@@ -105,7 +106,7 @@ export function structure(dir) {
       if (!s.re.test(name)) continue;
       if (s.name === "(group)") {
         if (parent) errors.push(`${e.path}/: a route group folder sits at the venture root (P-36)`);
-        const inside = readdirSync(join(dir, e.path)).filter((f) => f !== "AGENTS.md" && f !== ".gitkeep");
+        const inside = readdirSync(ventureFile(dir, e.path)).filter((f) => f !== "AGENTS.md" && f !== ".gitkeep");
         if (inside.length) errors.push(`${e.path}/: ${s.rule}; move ${inside.join(", ")} into its package`);
       } else warnings.push(`${e.path}/: ${s.name} is ${s.rule} (P-32)`);
     }
@@ -129,7 +130,7 @@ export async function manifest(dir) {
     // The packages that fit the phase now, plus every package that already holds a record.
     const { packages } = await import("./packages.mjs");
     const p = packages(dir);
-    const holding = names.filter((n) => { const k = pkgOf(n); return (k.records ?? []).length && existsSync(join(dir, n)) && readdirSync(join(dir, n)).some((f) => /\.(json|md|mdx)$/.test(f)); });
+    const holding = names.filter((n) => { const k = pkgOf(n); return (k.records ?? []).length && existsSync(ventureFile(dir, n)) && readdirSync(ventureFile(dir, n)).some((f) => /\.(json|md|mdx)$/.test(f)); });
     derived = [...new Set([...p.core.filter((x) => x.in === "now").map((x) => x.id), ...holding])];
   }
   const used = v.packages ?? derived;
@@ -141,7 +142,7 @@ export async function manifest(dir) {
   return {
     identity: { id: v.id, name: v.name, kind: v.kind ?? "venture", parent: v.parent, owner: v.owner, status: v.status },
     phase: v.phase,
-    governance: { governed_by: v.governed_by ?? null, legal_form: v.form?.legal_form ?? "none", members: v.members ?? [], decision_rights: existsSync(join(dir, "governance/decision-rights.json")) ? "governance/decision-rights.json" : "the framework's template" },
+    governance: { governed_by: v.governed_by ?? null, legal_form: v.form?.legal_form ?? "none", members: v.members ?? [], decision_rights: existsSync(join(ventureFile(dir, "governance/decision-rights.json"))) ? "governance/decision-rights.json" : "the framework's template" },
     functions,
     packages: { declared: !!v.packages, list: used.map((n) => ({ name: n, kind: names.includes(n) ? pkgOf(n).kind : null, known: names.includes(n) })) },
     kits: (v.kits ?? []).map((k) => ({ ...k, note: "a kit is Mentura's; the framework checks only that it names a package the venture uses" })),

package/schema/time-to-ready.mjs

@@ -15,6 +15,7 @@ import { execFileSync } from "node:child_process";
 import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
 import { join, dirname } from "node:path";
 import { needNow } from "./need-now.mjs";
+import { ventureFile } from "./venture-paths.mjs";
 
 const load = (p) => JSON.parse(readFileSync(p, "utf8"));
 const day = (d) => d ? d.slice(0, 10) : null;
@@ -43,19 +44,19 @@ export function timeToReady(dir) {
     const rels = (model.records.find((r) => r.id === type)?.paths ?? []).filter((p) => p.startsWith("instance/**/")).map((p) => p.slice("instance/**/".length));
     return here.filter((x) => rels.some((g) => glob(g).test(x)));
   };
-  const seen = (type) => { const fs = where(type); return fs.length ? fs.map((f) => firstSeen(join(dir, f))).sort()[0] : null; };
+  const seen = (type) => { const fs = where(type); return fs.length ? fs.map((f) => firstSeen(ventureFile(dir, f))).sort()[0] : null; };
 
   // Running.
   const nn = needNow(dir);
-  const products = where("product").map((f) => ({ f, p: load(join(dir, f)) }));
+  const products = where("product").map((f) => ({ f, p: load(ventureFile(dir, f)) }));
   const offered = products.filter(({ p }) => p.status === "live");
   const telosFile = where("telos")[0];
-  const telos = telosFile ? load(join(dir, telosFile)) : null;
+  const telos = telosFile ? load(ventureFile(dir, telosFile)) : null;
   const conditions = {
     promise: v.core?.promise ? firstSeen(join(dir, "venture.json")) : null,
-    product_offered: offered.length ? offered.map(({ f }) => firstSeen(join(dir, f))).sort()[0] : null,
+    product_offered: offered.length ? offered.map(({ f }) => firstSeen(ventureFile(dir, f))).sort()[0] : null,
     first_account: seen("account"),
-    next_exit_criteria: nn.next && telos?.phases?.some((p) => p.phase === nn.next) ? firstSeen(join(dir, telosFile)) : null,
+    next_exit_criteria: nn.next && telos?.phases?.some((p) => p.phase === nn.next) ? firstSeen(ventureFile(dir, telosFile)) : null,
   };
   const missing = Object.entries(conditions).filter(([, d]) => !d).map(([k]) => k);
   const runningOn = missing.length ? null : Object.values(conditions).sort().at(-1);
@@ -75,7 +76,7 @@ export function timeToReady(dir) {
 
   // MAD tiers.
   const opsFile = where("validation-operations-readiness")[0];
-  const tiers = opsFile ? load(join(dir, opsFile)).tiers.map((t) => ({ tier: t.tier, ready_on: t.ready_on ?? null, days: days(start, t.ready_on) })) : [];
+  const tiers = opsFile ? load(ventureFile(dir, opsFile)).tiers.map((t) => ({ tier: t.tier, ready_on: t.ready_on ?? null, days: days(start, t.ready_on) })) : [];
 
   return { venture: v.id, phase: nn.phase, started: start, running: { on: runningOn, days: days(start, runningOn), missing, conditions }, layers: layerRows, tiers };
 }

package/schema/triggers.mjs

@@ -26,6 +26,7 @@ import { decisions, propose } from "./decisions.mjs";
 import { kit } from "./kits.mjs";
 import { CONFIG, readConfig, writeConfig } from "./naive-config.mjs";
 import { packages } from "./packages.mjs";
+import { ventureFile } from "./venture-paths.mjs";
 
 export const STATE = ".naive/triggers.json";
 export const ERRORS = ".naive/trigger-errors.jsonl";
@@ -63,19 +64,19 @@ export function matches(t, e) {
 }
 
 function readState(dir) {
-  const f = join(dir, STATE);
+  const f = ventureFile(dir, STATE);
   if (existsSync(f)) {
     try { const s = load(f); if (Array.isArray(s.runs) && Array.isArray(s.waiting)) return s; } catch {}
     // A state file that cannot be read is kept beside it, and the failure is raised; runs start again from now.
     const kept = `.naive/triggers.unreadable-${Date.now()}.json`;
-    renameSync(f, join(dir, kept));
+    renameSync(f, ventureFile(dir, kept));
     return { since: now(), cursor: null, runs: [], waiting: [], unreadable: kept };
   }
   // Triggers start with the events after they were configured, not the venture's whole history.
-  const cfg = join(dir, CONFIG);
+  const cfg = ventureFile(dir, CONFIG);
   return { since: existsSync(cfg) ? statSync(cfg).mtime.toISOString() : now(), cursor: null, runs: [], waiting: [] };
 }
-const saveState = (dir, s) => { mkdirSync(join(dir, ".naive"), { recursive: true }); writeFileSync(join(dir, STATE), JSON.stringify(s, null, 2) + "\n"); };
+const saveState = (dir, s) => { mkdirSync(join(dir, ".naive"), { recursive: true }); writeFileSync(ventureFile(dir, STATE), JSON.stringify(s, null, 2) + "\n"); };
 
 const complete = (dir, name) => { try { return packages(dir).complete.includes(name); } catch { return false; } };
 const brief = (x) => (x == null ? null : typeof x === "string" ? x.slice(0, 300) : JSON.stringify(x).slice(0, 300));
@@ -155,7 +156,7 @@ export async function fire(dir, { rounds = 20 } = {}) {
       delete state.unreadable; state.runs.push(run); made.push(run); saveState(dir, state);
     }
     // A crash the provenance hook kept is a failure too.
-    const ef = join(dir, ERRORS);
+    const ef = ventureFile(dir, ERRORS);
     if (existsSync(ef)) {
       for (const l of readFileSync(ef, "utf8").split("\n").filter(Boolean)) {
         const x = JSON.parse(l);
@@ -211,7 +212,7 @@ export async function fire(dir, { rounds = 20 } = {}) {
 export function report(dir) {
   const { triggers, problems } = triggersOf(dir);
   // Read only: a listing never moves an unreadable state file aside (the next run does, and raises it).
-  const s = (() => { try { return load(join(dir, STATE)); } catch { return { runs: [], waiting: [] }; } })();
+  const s = (() => { try { return load(ventureFile(dir, STATE)); } catch { return { runs: [], waiting: [] }; } })();
   return { triggers: triggers.map((t) => ({ id: t.id, from: t.from, on: t.on, run: t.run.propose ? { propose: t.run.propose.id } : { route: t.run.route, action: t.run.action }, needs: t.needs ?? null, needs_complete: t.needs ? complete(dir, t.needs) : null, enabled: t.enabled, once: !!t.once })),
     problems, runs: s.runs.slice(-10), waiting: s.waiting, open: s.runs.filter((r) => r.status === "raised").map((r) => ({ run: r.n, trigger: r.trigger, error: r.error, decision: r.decision, decide: `mentura decide ${r.decision} --venture ${load(join(dir, "venture.json")).id} --by <your name> --answer "Retry" (or "Skip this event", "Turn the trigger off")` })) };
 }

package/schema/upgrades.mjs

@@ -25,6 +25,7 @@ import { agentFromEnv, record } from "../interface/provenance.mjs";
 import { routes, glob } from "../interface/router.mjs";
 import { CONFIG, pins, readConfig, writeConfig } from "./naive-config.mjs";
 import { packages as packageFit } from "./packages.mjs";
+import { ventureFile } from "./venture-paths.mjs";
 
 export const repo = new URL("..", import.meta.url).pathname;
 export const STAGE = ".naive/upgrade";
@@ -106,26 +107,26 @@ function context(dir, { dry, git, cfg, at, onConfig }) {
   return {
     at, config: cfg, moved, writes, escalated, notes, kept,
     mv(a, b) {
-      if (!existsSync(join(dir, a))) return;
-      if (existsSync(join(dir, b)) && !moved.some(([, t]) => t === b)) throw new Error(`${b} already exists, so ${a} cannot move there; move one of them yourself and upgrade again`);
+      if (!existsSync(ventureFile(dir, a))) return;
+      if (existsSync(ventureFile(dir, b)) && !moved.some(([, t]) => t === b)) throw new Error(`${b} already exists, so ${a} cannot move there; move one of them yourself and upgrade again`);
       if (!dry) {
-        mkdirSync(dirname(join(dir, b)), { recursive: true });
+        mkdirSync(dirname(ventureFile(dir, b)), { recursive: true });
         if (tracked(a)) execFileSync("git", ["mv", a, b], { cwd: dir, stdio: "pipe" });
-        else renameSync(join(dir, a), join(dir, b));
+        else renameSync(ventureFile(dir, a), ventureFile(dir, b));
       }
       moved.push([a, b]);
     },
     write(rel, text, { activity = "write", note, derived_from, log = true } = {}) {
-      if (!dry) { mkdirSync(dirname(join(dir, rel)), { recursive: true }); writeFileSync(join(dir, rel), text); }
+      if (!dry) { mkdirSync(dirname(ventureFile(dir, rel)), { recursive: true }); writeFileSync(ventureFile(dir, rel), text); }
       writes.push({ path: rel, activity, note, derived_from, log });
     },
     escalate: (msg) => escalated.push(msg),
     note: (msg) => notes.push(msg),
     configChanged: () => onConfig(),
-    removeEmpty: (rel) => { if (!dry) removeEmpty(join(dir, rel)); },
+    removeEmpty: (rel) => { if (!dry) removeEmpty(ventureFile(dir, rel)); },
     keep(sub) {
-      if (existsSync(join(dir, sub))) return;
-      if (!dry) { mkdirSync(join(dir, sub), { recursive: true }); writeFileSync(join(dir, sub, ".gitkeep"), ""); }
+      if (existsSync(ventureFile(dir, sub))) return;
+      if (!dry) { mkdirSync(ventureFile(dir, sub), { recursive: true }); writeFileSync(join(ventureFile(dir, sub), ".gitkeep"), ""); }
       kept.push(sub);
     },
   };
@@ -177,8 +178,8 @@ export async function upgrade(dir, { reg = registry(), dry = false, git = true }
     if (!dry && (p.pending || configChanged)) {
       if (configChanged) { writeConfig(dir, cfg); record(dir, { entity: CONFIG, activity: "write", agent, note: `pinned Naive ${p.to} and ${Object.keys(cfg.packages).length} packages (U-1)` }); }
       const rel = `.release/upgrade-${p.to}.json`;
-      mkdirSync(join(dir, ".release"), { recursive: true });
-      writeFileSync(join(dir, rel), JSON.stringify(release, null, 2) + "\n");
+      mkdirSync(join(ventureFile(dir, ".release")), { recursive: true });
+      writeFileSync(ventureFile(dir, rel), JSON.stringify(release, null, 2) + "\n");
       record(dir, { entity: rel, activity: "release", agent, derived_from: [...new Set([...ran.flatMap((r) => [...r.moves.map((m) => m.to), ...r.rewrote]), ...(configChanged ? [CONFIG] : [])])], note: `upgraded from Naive ${p.from} to ${p.to}` });
       // Adapters installed in the venture (Z-4) are refreshed, so their copies of package skills follow the upgrade.
       release.adapters = await refreshAdapters(dir);
@@ -264,18 +265,18 @@ export function updateFramework(root = repo) {
 export function snapshot(dir, { skipPrivate = true } = {}) {
   const out = {};
   const walk = (rel) => {
-    for (const e of readdirSync(join(dir, rel), { withFileTypes: true })) {
+    for (const e of readdirSync(ventureFile(dir, rel), { withFileTypes: true })) {
       const r = rel ? `${rel}/${e.name}` : e.name;
       if (!rel && (r === ".naive" || r === ".git" || (skipPrivate && r === "_private"))) continue;
       if (e.isDirectory()) { if (!existsSync(join(dir, r, "venture.json"))) walk(r); }
-      else if (e.isFile()) out[r] = sha(readFileSync(join(dir, r)));
+      else if (e.isFile()) out[r] = sha(readFileSync(ventureFile(dir, r)));
     }
   };
   walk("");
   return out;
 }
 
-const writeDraft = (dir, d) => { mkdirSync(join(dir, STAGE), { recursive: true }); writeFileSync(join(dir, DRAFT), JSON.stringify(d, null, 2) + "\n"); return d; };
+const writeDraft = (dir, d) => { mkdirSync(ventureFile(dir, STAGE), { recursive: true }); writeFileSync(ventureFile(dir, DRAFT), JSON.stringify(d, null, 2) + "\n"); return d; };
 /** Adds to the staged upgrade's draft record (what an agent did, say). */
 export function annotate(dir, extra) {
   const d = draft(dir);
@@ -283,16 +284,16 @@ export function annotate(dir, extra) {
   return writeDraft(dir, { ...d, ...extra });
 }
 /** The staged upgrade's draft record, or null. */
-export const draft = (dir) => (existsSync(join(dir, DRAFT)) ? load(join(dir, DRAFT)) : null);
+export const draft = (dir) => (existsSync(ventureFile(dir, DRAFT)) ? load(ventureFile(dir, DRAFT)) : null);
 
 /** Copies the venture to .naive/upgrade/venture and upgrades the copy. Nothing in the venture changes. */
 export async function stage(dir, { reg = registry(), by = "naive" } = {}) {
-  if (existsSync(join(dir, STAGE))) throw new Error(`an upgrade is already staged in ${STAGE}: accept it (--accept --confirm ${CONFIRM}) or reject it (--reject)`);
+  if (existsSync(ventureFile(dir, STAGE))) throw new Error(`an upgrade is already staged in ${STAGE}: accept it (--accept --confirm ${CONFIRM}) or reject it (--reject)`);
   const p = plan(dir, { reg });
   if (!p.pending) throw new Error(`${p.venture} is already on Naive ${p.to} with every package pinned: nothing to stage`);
   const base = snapshot(dir);
-  const out = join(dir, STAGED);
-  for (const f of Object.keys(base)) { mkdirSync(dirname(join(out, f)), { recursive: true }); copyFileSync(join(dir, f), join(out, f)); }
+  const out = ventureFile(dir, STAGED);
+  for (const f of Object.keys(base)) { mkdirSync(dirname(join(out, f)), { recursive: true }); copyFileSync(ventureFile(dir, f), join(out, f)); }
   const result = await upgrade(out, { reg, git: false });
   return writeDraft(dir, { status: "staged", from: p.from, to: p.to, staged_at: now(), by, base, migrations: result.release.migrations.map((m) => ({ id: m.id, moves: m.moves.length, rewrote: m.rewrote.length })), escalated: result.release.escalated, guides: result.release.guides });
 }
@@ -310,7 +311,7 @@ export function runChecks(vdir, { reg = registry() } = {}) {
   for (const r of routes().filter((x) => x.kind === "record" && x.schema && (x.form ?? "json") === "json")) {
     for (const f of files.filter((f) => r.files.some((g) => glob(g).test(f)))) {
       n++;
-      const v = spawnSync("python3", [join(repo, "schema/validate.py"), "--schema", r.schema.replace(/^schema\//, ""), "--file", join(vdir, f)], { encoding: "utf8" });
+      const v = spawnSync("python3", [join(repo, "schema/validate.py"), "--schema", r.schema.replace(/^schema\//, ""), "--file", ventureFile(vdir, f)], { encoding: "utf8" });
       if (v.status !== 0) bad.push(`${f} does not match ${r.schema}: ${(v.stdout + v.stderr).trim().split("\n")[0]}`);
     }
   }
@@ -323,10 +324,10 @@ export function runChecks(vdir, { reg = registry() } = {}) {
 
 /** What the staged copy changes: files added, changed and removed (the venture's _private/ is never removed). */
 export function changes(dir) {
-  const live = snapshot(dir), staged = snapshot(join(dir, STAGED), { skipPrivate: false });
+  const live = snapshot(dir), staged = snapshot(ventureFile(dir, STAGED), { skipPrivate: false });
   return {
-    added: Object.keys(staged).filter((f) => !(f in live) && !existsSync(join(dir, f))).sort(),
-    changed: Object.keys(staged).filter((f) => (f in live && live[f] !== staged[f]) || (!(f in live) && existsSync(join(dir, f)) && sha(readFileSync(join(dir, f))) !== staged[f])).sort(),
+    added: Object.keys(staged).filter((f) => !(f in live) && !existsSync(ventureFile(dir, f))).sort(),
+    changed: Object.keys(staged).filter((f) => (f in live && live[f] !== staged[f]) || (!(f in live) && existsSync(ventureFile(dir, f)) && sha(readFileSync(ventureFile(dir, f))) !== staged[f])).sort(),
     removed: Object.keys(live).filter((f) => !(f in staged)).sort(),
   };
 }
@@ -335,7 +336,7 @@ export function changes(dir) {
 export function check(dir, { reg = registry() } = {}) {
   const d = draft(dir);
   if (!d) throw new Error("no upgrade is staged: stage one with --stage or --agent");
-  const checks = runChecks(join(dir, STAGED), { reg });
+  const checks = runChecks(ventureFile(dir, STAGED), { reg });
   const ok = checks.every((c) => c.passed);
   return writeDraft(dir, { ...d, status: ok ? "ready" : "checks-failed", checked_at: now(), checks, changes: changes(dir) });
 }
@@ -357,13 +358,13 @@ export async function accept(dir, { confirm, by, reg = registry() } = {}) {
   const ch = checked.changes;
   const clash = ch.changed.filter((f) => f.startsWith("_private/"));
   if (clash.length) throw new Error(`not accepted: the upgrade would overwrite private files that differ (${clash.join(", ")}); move them aside, reject and stage again`);
-  const src = join(dir, STAGED);
-  for (const f of [...ch.added, ...ch.changed]) { mkdirSync(dirname(join(dir, f)), { recursive: true }); copyFileSync(join(src, f), join(dir, f)); }
-  for (const f of ch.removed) rmSync(join(dir, f));
+  const src = ventureFile(dir, STAGED);
+  for (const f of [...ch.added, ...ch.changed]) { mkdirSync(dirname(ventureFile(dir, f)), { recursive: true }); copyFileSync(join(src, f), ventureFile(dir, f)); }
+  for (const f of ch.removed) rmSync(ventureFile(dir, f));
   // Folders the upgrade emptied go too, unless the copy still has them.
   const dirs = [...new Set(ch.removed.flatMap((f) => f.split("/").slice(0, -1).map((_, i, a) => a.slice(0, i + 1).join("/"))))].sort((a, b) => b.length - a.length);
-  for (const x of dirs) if (existsSync(join(dir, x)) && !existsSync(join(src, x)) && readdirSync(join(dir, x)).length === 0) rmSync(join(dir, x), { recursive: true });
-  rmSync(join(dir, STAGE), { recursive: true, force: true });
+  for (const x of dirs) if (existsSync(ventureFile(dir, x)) && !existsSync(join(src, x)) && readdirSync(ventureFile(dir, x)).length === 0) rmSync(ventureFile(dir, x), { recursive: true });
+  rmSync(ventureFile(dir, STAGE), { recursive: true, force: true });
   return landed(dir, d, ch, by);
 }
 
@@ -373,13 +374,13 @@ async function refreshAdapters(dir) {
 
 async function landed(dir, d, ch, by) {
   const rel = `.release/upgrade-${d.to}.json`;
-  const e = existsSync(join(dir, rel)) ? record(dir, { entity: rel, activity: "accept", agent: agentFromEnv("person", "cli", by ? { id: by } : {}), note: `accepted the staged upgrade to Naive ${d.to}${d.by && d.by !== "naive" ? ` (worked by ${d.by})` : ""}` }) : null;
+  const e = existsSync(ventureFile(dir, rel)) ? record(dir, { entity: rel, activity: "accept", agent: agentFromEnv("person", "cli", by ? { id: by } : {}), note: `accepted the staged upgrade to Naive ${d.to}${d.by && d.by !== "naive" ? ` (worked by ${d.by})` : ""}` }) : null;
   return { accepted: d.to, from: d.from, added: ch.added.length, changed: ch.changed.length, removed: ch.removed.length, provenance: e?.hash ?? null, adapters: await refreshAdapters(dir) };
 }
 
 /** Discards a staged upgrade. The venture never changed, so nothing is logged. */
 export function reject(dir) {
-  if (!existsSync(join(dir, STAGE))) throw new Error("no upgrade is staged");
-  rmSync(join(dir, STAGE), { recursive: true, force: true });
+  if (!existsSync(ventureFile(dir, STAGE))) throw new Error("no upgrade is staged");
+  rmSync(ventureFile(dir, STAGE), { recursive: true, force: true });
   return { rejected: true };
 }

package/schema/venture-paths.mjs

@@ -0,0 +1,97 @@
+// Where a venture's files physically are (EE-086). Code names a file by its logical path, the path a
+// record has always had (foundation/problem.json, provenance.jsonl, knowledge/sources.json), and `at`
+// says where it sits on disk under the venture's layout:
+//
+//   flat (no layout in venture.json, every venture made before EE-086): the logical path, unchanged
+//   structured (venture.json layout: "structured"):
+//     venture.json, AGENTS.md, README.md, package.json   at the top (profile.md is README.md)
+//     provenance.jsonl, sources.json, naive.config.json   in meta/; .release/ is meta/releases/
+//     every package (foundation/, people/, _drafts/ ...)  in k-base/, or in k-base/(group)/ when the
+//                                                         founder mirrors a function as a folder
+//     code the venture keeps (a marketing site, a ported repository)  in codebase/
+//   A structured venture made by 0.3.0 has knowledge/ where k-base/ now is; it is read where it is
+//   until naive upgrade renames it.
+//
+// `logical` goes the other way, for code that walks the disk and matches files against the data model.
+
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, sep } from "node:path";
+
+const TOP = new Set(["venture.json", "AGENTS.md", "README.md", "package.json", "package-lock.json", ".gitignore"]);
+const META = { "provenance.jsonl": "meta/provenance.jsonl", "knowledge/sources.json": "meta/sources.json", "sources.json": "meta/sources.json", "naive.config.json": "meta/naive.config.json" };
+const cache = new Map();
+export const KBASE = "k-base";
+export const CODEBASE = "codebase";
+
+/** The venture's knowledge-base folder: k-base/, or knowledge/ in a structured venture made before it was renamed. */
+export function kbaseOf(dir) {
+  return !existsSync(join(dir, KBASE)) && existsSync(join(dir, "knowledge", "foundation")) ? "knowledge" : KBASE;
+}
+
+/** The venture's layout: "structured" (EE-086) or "flat". Read once per venture.json change. */
+export function layoutOf(dir) {
+  const f = join(dir, "venture.json");
+  let m = 0;
+  try { m = statSync(f).mtimeMs; } catch { return "flat"; }
+  const hit = cache.get(dir);
+  if (hit && hit.m === m) return hit.layout;
+  let layout = "flat";
+  try { layout = JSON.parse(readFileSync(f, "utf8")).layout === "structured" ? "structured" : "flat"; } catch {}
+  cache.set(dir, { m, layout });
+  return layout;
+}
+
+// The (group)/ folder a package sits in, when the founder mirrors functions on disk.
+function groupOf(dir, pkg) {
+  const kb = join(dir, kbaseOf(dir));
+  if (!pkg || existsSync(join(kb, pkg)) || !existsSync(kb)) return null;
+  for (const g of readdirSync(kb)) if (/^\(.+\)$/.test(g) && existsSync(join(kb, g, pkg))) return g;
+  return null;
+}
+
+/** The venture-relative physical path of a logical path. */
+export function physical(dir, rel) {
+  const r = String(rel).split(sep).join("/").replace(/^\.\//, "");
+  if (layoutOf(dir) !== "structured") return r;
+  if (TOP.has(r)) return r;
+  if (r === "profile.md") return "README.md";
+  if (META[r]) return META[r];
+  if (r === ".release" || r.startsWith(".release/")) return "meta/releases" + r.slice(".release".length);
+  if (r.startsWith(".naive/") || r === ".naive" || r.startsWith("node_modules") || r.startsWith(".git")) return r;
+  const kb = kbaseOf(dir);
+  if (r.startsWith(`${kb}/`) || r === kb || r.startsWith("meta/") || r.startsWith(`${CODEBASE}/`) || r.startsWith("repo/")) return r;
+  const pkg = r.split("/")[0];
+  const g = groupOf(dir, pkg);
+  return `${kb}/${g ? `${g}/` : ""}${r}`;
+}
+
+/** The absolute path of a logical path in a venture. */
+export const ventureFile = (dir, rel) => join(dir, physical(dir, rel));
+
+/** The logical path of a venture-relative physical path: the inverse of `physical`. */
+export function logical(dir, rel) {
+  const r = String(rel).split(sep).join("/");
+  if (layoutOf(dir) !== "structured") return r;
+  if (r === "README.md") return "profile.md";
+  for (const [l, p] of Object.entries(META)) if (r === p) return l === "sources.json" ? "knowledge/sources.json" : l;
+  if (r === "meta/releases" || r.startsWith("meta/releases/")) return ".release" + r.slice("meta/releases".length);
+  const kb = kbaseOf(dir);
+  if (r.startsWith(`${kb}/`)) return r.slice(kb.length + 1).replace(/^\([^/]+\)\//, "");
+  return r;
+}
+
+/** Every file of a venture by its logical path, skipping what is never a record. */
+export function logicalFiles(dir) {
+  const out = [];
+  const walk = (d) => {
+    if (!existsSync(d)) return;
+    for (const e of readdirSync(d, { withFileTypes: true })) {
+      if (e.name === "node_modules" || e.name === ".git") continue;
+      const p = join(d, e.name);
+      if (e.isDirectory()) { if (!existsSync(join(p, "venture.json"))) walk(p); }
+      else out.push(logical(dir, relative(dir, p)));
+    }
+  };
+  walk(dir);
+  return out;
+}

package/schema/venture.schema.json

@@ -34,6 +34,31 @@
       "pattern": "^[a-z0-9-]+$",
       "description": "The venture type, an id from schema/venture-types.json: what kind of venture this is (a software startup, a VC fund), which decides its starting packages, first decisions, functions and roles (EE-082)"
     },
+    "layout": {
+      "enum": [
+        "flat",
+        "structured"
+      ],
+      "default": "flat",
+      "description": "Where the venture's files sit (EE-086). structured: venture.json, README.md and AGENTS.md at the top, the knowledge base in knowledge/, sources.json, naive.config.json, the provenance log and releases in meta/, and code in an optional repo/. flat: every venture made before EE-086, with packages at the top."
+    },
+    "functions": {
+      "type": "object",
+      "description": "The venture's functions and their one accountable owner each (EE-071), keyed by function id from operations/departments.json. A solo founder owns them all, which is what the manifest assumes when this is left out.",
+      "additionalProperties": {
+        "type": "object",
+        "required": [
+          "owner"
+        ],
+        "properties": {
+          "owner": {
+            "type": "string",
+            "description": "A role or a person's name; no personal details"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
     "parent": {
       "type": [
         "string",
@@ -181,23 +206,6 @@
         "additionalProperties": false
       }
     },
-    "functions": {
-      "type": "object",
-      "description": "The venture's functions and their one accountable owner each (EE-071), keyed by function id from operations/departments.json. A solo founder owns them all, which is what the manifest assumes when this is left out.",
-      "additionalProperties": {
-        "type": "object",
-        "required": [
-          "owner"
-        ],
-        "properties": {
-          "owner": {
-            "type": "string",
-            "description": "A role or a person's name; no personal details"
-          }
-        },
-        "additionalProperties": false
-      }
-    },
     "brand": {
       "type": "object",
       "description": "The venture's verbal brand elements, owned by the brand pillar. Visual identity (tokens, logos) is a separate record.",

package/schema/workspace.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "workspace.schema.json",
   "title": "Workspace",
-  "description": "A builder's workspace: one instance of the system. A workspace.json at its top says which schema version it follows, where its vault is and where its repositories are (EE-002, EE-011, EE-020). A workspace always has a vault; it has a code folder of repositories once any venture builds software.",
+  "description": "A builder's workspace: one instance of the system. A naive-workspace.json (earlier workspace.json) at its top says which schema version it follows, where its vault is and where its repositories are (EE-002, EE-011, EE-020). A workspace always has a vault; it has a code folder of repositories once any venture builds software.",
   "type": "object",
   "required": [
     "schema",
@@ -18,6 +18,10 @@
       "pattern": "^\\d+\\.\\d+\\.\\d+$",
       "description": "The version in schema/VERSION that this workspace follows"
     },
+    "name": {
+      "type": "string",
+      "description": "The workspace's name, shown to the founder. create-venture names a new workspace \"Naive workspace\"; the founder can rename it"
+    },
     "ventures": {
       "type": "array",
       "items": {