naive-framework 0.1.0 → 0.2.0

package/schema/setup.mjs

@@ -0,0 +1,164 @@
+// Setup (EE-083): the questions that establish a venture's structure, in order: its people and their
+// hats, where each function keeps its truth, the strategic foundation and the first decisions (the decision
+// docket), and a goal for the discovery phase. It holds no view. The naive-setup skill
+// (interface/skills/naive-setup) renders it in the model's harness, as a Claude artifact where there is one;
+// interface/dev/setup.mjs serves the same state to a browser.
+//
+//   node schema/setup.mjs <venture dir> state                     the state, as JSON
+//   node schema/setup.mjs <venture dir> artifact                  the state rendered into the skill's artifact template
+//   node schema/setup.mjs <venture dir> answer <decision id> <the founder's words> [--via mcp]
+//   node schema/setup.mjs <venture dir> point <function> <system> [address] [--via mcp]
+//   node schema/setup.mjs <venture dir> confirm [--yes]          confirm the answers the model relayed, as the founder
+
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+
+const repo = new URL("..", import.meta.url).pathname;
+const load = (p) => JSON.parse(readFileSync(p, "utf8"));
+export const TEMPLATE = "interface/skills/naive-setup/artifact.html";
+
+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 catalog = load(join(repo, "schema/systems-catalog.json"));
+  const types = load(join(repo, "schema/venture-types.json")).types;
+  const all = decisions(dir).decisions;
+  // The roots (venture, foundation) structure the docket; they are not questions to answer here.
+  const docket = all.filter((d) => d.id !== GOAL && d.status !== "deferred" && !["venture", "foundation"].includes(d.id));
+  const now = docket.filter((d) => d.render === "now" || d.status === "decided");
+  const goal = all.find((d) => d.id === GOAL) ?? null;
+  const settled = now.filter((d) => d.status === "decided").length;
+  const pointed = Object.values(sources.functions ?? {}).filter((f) => f.systems.length).length;
+  const steps = { venture: true, people: !!people, truth: pointed > 0, docket: now.length > 0 && settled === now.length, goal: goal?.status === "decided" };
+  return {
+    venture: { id: v.id, name: v.name, phase: v.phase, type: types.find((t) => t.id === v.type) ?? null },
+    people, functions: sources.functions ?? {}, truth: sources.truth ?? "local",
+    catalog, docket: now.map((d) => ({ id: d.id, question: d.question, source: d.source, status: d.status, options: d.options ?? [], answer: d.answer ?? null, why: d.why ?? [], statement: d.statement ?? null, relayed: relayed(d) })),
+    // Answers the model wrote down from the founder's words; they wait for the founder to confirm them.
+    waiting: [...now, ...(goal ? [goal] : [])].filter(relayed).map((d) => ({ id: d.id, question: d.question, answer: d.answer })),
+    later: docket.filter((d) => d.render !== "now" && d.status !== "decided").length,
+    goal: goal ? { status: goal.status, answer: goal.answer ?? null, relayed: relayed(goal) } : null,
+    steps, done: Object.values(steps).every(Boolean), counts: { settled, of: now.length },
+    rho: existsSync(join(repo, "platform/integrations/rho.mjs")),
+  };
+}
+
+// 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";
+
+// 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" }) {
+  const { approve, decisions, propose } = await import("./decisions.mjs");
+  if (!answer || !String(answer).trim()) return { ok: false, error: "write an answer first" };
+  const by = founderName(dir);
+  const d = decisions(dir).decisions.find((x) => x.id === id);
+  if (id === GOAL && !d) {
+    const p = propose(dir, { id: GOAL, question: "What must be true for the venture to leave discovery? Name the goal this phase works toward.", decides: { record: "telos", path: "foundation/telos.json" }, layer: "purpose", needed_in: "discovery", boundary: "fail-open" }, { via });
+    if (!p.ok) return p;
+    return approve(dir, GOAL, { by, answer: String(answer).trim(), via, note: `set at ${where}` });
+  }
+  if (!d) return { ok: false, error: `no decision ${id}` };
+  if (d.source === "foundation") {
+    const sid = id.replace(/^foundation-/, "");
+    const did = `statement-${sid}`;
+    const p = propose(dir, { id: did, question: d.question, statement: sid, decides: d.decides, layer: d.layer === "system" ? "purpose" : d.layer, needed_in: d.needed_in }, { via });
+    if (!p.ok) return p;
+    return approve(dir, did, { by, answer: String(answer).trim(), via, note: `the founder's words at ${where}` });
+  }
+  return approve(dir, id, { by, answer: String(answer).trim(), via, note: `decided at ${where}` });
+}
+
+// One pointer: where a function keeps its truth, merged into knowledge/sources.json through the router.
+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 map = existsSync(file) ? load(file) : { sources: [], records: {}, truth: "local" };
+  const f = (map.functions ??= {})[fn] ??= { systems: [] };
+  const entry = { system, ...(address ? { address } : {}), status: "pointed" };
+  if (system === "rho" && existsSync(join(repo, "platform/integrations/rho.mjs"))) {
+    const live = Boolean(process.env.RHO_API_TOKEN);
+    const r = spawnSync("node", [join(repo, "platform/integrations/rho.mjs"), "sync", "--venture", dir, ...(live ? ["--live"] : [])], { encoding: "utf8", env: process.env });
+    if (r.status === 0) Object.assign(entry, { status: "connected", synced: new Date().toISOString().replace(/\.\d+Z$/, "Z"), address: address || (live ? "live" : "sandbox") });
+  }
+  f.systems = [...f.systems.filter((s) => s.system !== system), entry];
+  const { call } = await import("../interface/router.mjs");
+  const r = await call({ workspace: dirname(dir), venture: basename(dir), route: "knowledge/knowledge-sources", action: "write", input: map, actor, ...(agentId ? { actor_id: agentId } : {}), via, provenance: { note: `${fn}: ${system}${address ? ` at ${address}` : ""} (${entry.status})` } });
+  return r.ok ? { ok: true, result: entry } : r;
+}
+
+/** The model relays the founder's answer: proposed with the founder's words as its wording, by an agent,
+ *  so it stays open until the founder confirms it (an agent never decides, EE-058). */
+export async function relay(dir, { id, answer, agentId, harness, model }) {
+  const { decisions, propose } = await import("./decisions.mjs");
+  if (!answer || !String(answer).trim()) return { ok: false, error: "pass the founder's answer, in their words" };
+  const words = String(answer).trim();
+  const note = `the founder's words, relayed from ${harness ?? "the model's harness"} during setup`;
+  const opts = { agentId, via: "mcp", harness, model };
+  const d = decisions(dir).decisions.find((x) => x.id === id);
+  if (id === GOAL) return propose(dir, { ...(d ? {} : { decides: { record: "telos", path: "foundation/telos.json" }, layer: "purpose", needed_in: "discovery", boundary: "fail-open" }), id: GOAL, question: d?.question ?? "What must be true for the venture to leave discovery? Name the goal this phase works toward.", answer: words, note }, opts);
+  if (!d) return { ok: false, error: `no decision ${id}` };
+  if (d.status === "decided") return { ok: false, error: `${id} is decided; only the founder can change it` };
+  if (d.source === "foundation") {
+    const sid = id.replace(/^foundation-/, "");
+    return propose(dir, { id: `statement-${sid}`, question: d.question, statement: sid, decides: d.decides, layer: d.layer === "system" ? "purpose" : d.layer, needed_in: d.needed_in, answer: words, note }, opts);
+  }
+  return propose(dir, { id, question: d.question, answer: words, note }, opts);
+}
+
+/** The founder confirms the answers the model relayed, at the keyboard: each becomes a decision they made. */
+export async function confirm(dir, { by = founderName(dir) } = {}) {
+  const { approve } = await import("./decisions.mjs");
+  const out = [];
+  for (const w of (await state(dir)).waiting) {
+    const r = approve(dir, w.id, { by, via: "cli", note: `confirmed at setup: ${by}'s words, relayed by the model` });
+    if (!r.ok) return { ...r, confirmed: out };
+    out.push(w.id);
+  }
+  return { ok: true, result: { confirmed: out, by } };
+}
+
+/** The state rendered into the skill's artifact template: one self-contained page, no network. */
+export async function artifact(dir) {
+  const s = await state(dir);
+  const data = JSON.stringify(s).replace(/</g, "\\u003c");
+  return readFileSync(join(repo, TEMPLATE), "utf8").replace("__NAIVE_SETUP_STATE__", () => data);
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === new URL(import.meta.url).pathname) {
+  const [dirArg, cmd, ...rest] = process.argv.slice(2);
+  const flag = (n) => { const i = rest.indexOf(`--${n}`); if (i < 0) return undefined; const v = rest[i + 1]; rest.splice(i, 2); return v; };
+  const via = flag("via") ?? "cli";
+  if (!["cli", "mcp", "api"].includes(via)) { console.error(`--via is cli, mcp or api, not ${via}`); process.exit(2); }
+  if (!dirArg || !existsSync(join(dirArg, "venture.json"))) { console.error("usage: node schema/setup.mjs <venture dir> state|artifact|answer|point|confirm ..."); process.exit(2); }
+  const dir = resolve(dirArg);
+  let r;
+  if (cmd === "state") r = { ok: true, result: await state(dir) };
+  else if (cmd === "artifact") { process.stdout.write(await artifact(dir)); process.exit(0); }
+  else if (cmd === "answer") r = await decide(dir, { id: rest[0], answer: rest.slice(1).join(" "), via, where: via === "mcp" ? "setup in the model's harness" : "setup" });
+  else if (cmd === "confirm") {
+    const waiting = (await state(dir)).waiting;
+    if (!waiting.length) { console.log("Nothing waits for you to confirm."); process.exit(0); }
+    for (const w of waiting) console.log(`\n  ${w.question}\n  > ${w.answer}`);
+    let yes = rest.includes("--yes");
+    if (!yes) {
+      const { createInterface } = await import("node:readline/promises");
+      const rl = createInterface({ input: process.stdin, output: process.stdout });
+      yes = (await rl.question(`\nAre these ${waiting.length} answers yours, as written? Type yes to confirm them: `)).trim().toLowerCase() === "yes";
+      rl.close();
+    }
+    if (!yes) { console.log("Nothing confirmed. Change an answer in the chat, or run this again."); process.exit(1); }
+    r = await confirm(dir);
+  }
+  else if (cmd === "point") r = await point(dir, { fn: rest[0], system: rest[1], address: rest[2], via });
+  else { console.error(`unknown command ${cmd}: state, artifact, answer, point or confirm`); process.exit(2); }
+  console.log(JSON.stringify(r.ok && cmd === "state" ? r.result : r, null, 2));
+  process.exit(r.ok ? 0 : 1);
+}

package/schema/stale.mjs

@@ -0,0 +1,111 @@
+#!/usr/bin/env node
+// Stale summaries (V-9). In Next.js, content from a CMS is cached for a long time, and the CMS calls a
+// webhook that revalidates its tag when the content changes. In Naive a system of record (a CRM, a bank
+// such as Rho) notifies the venture that something it holds changed, and every summary that reads it is
+// marked stale until it is written again. What reads what is already recorded:
+//
+//   - provenance: a record whose latest write was derived from the changed item (derived_from names its
+//     path or its <source>://<path> address, or a folder that holds it) reads it;
+//   - the where-used list (knowledge/where-used.json, V-4): every child of a fact whose parent route is
+//     the changed record repeats it.
+//
+// Receiving the notification over the network is the platform's (platform/webhooks/server.mjs); this is
+// the framework part, offline: notify() marks, staleOf() answers for one file (the router adds it to a
+// read), and a summary is fresh again once it is written after the mark. Marks live in
+// <venture>/.naive/stale.json, never in the records.
+//
+//   node schema/stale.mjs <venture dir> [--json]                                   what is stale now
+//   node schema/stale.mjs <venture dir> --notify --source <id> --path <p> [--path <q>] [--version <v>]
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+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";
+
+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: [] });
+
+// The latest write of each file in the log.
+function lastWrites(dir) {
+  const last = new Map();
+  for (const e of entries(dir)) if (WRITES.has(e.activity) && !e.source) last.set(e.entity, e);
+  return last;
+}
+
+const covers = (d, item) => d === item || (d.endsWith("/") ? item.startsWith(d) : item.startsWith(`${d}/`));
+
+/**
+ * A system of record says items changed. Marks every summary that reads them stale and returns what it
+ * marked. source: a source id from knowledge/sources.json (venture for the venture's own folder);
+ * paths: the changed items, as paths inside that source.
+ */
+export function notify(dir, { source, paths, version, at = now(), via = "framework" }) {
+  const map = sourcesOf(dir);
+  if (!source || !map.sources.some((s) => s.id === source)) throw new Error(`no source ${source} in ${dir}'s knowledge/sources.json: one of ${map.sources.map((s) => s.id).join(", ")}`);
+  paths = [paths].flat().filter(Boolean);
+  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 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");
+  if (existsSync(wu)) {
+    for (const fact of load(wu).facts ?? []) {
+      const { r, params } = resolveRoute(fact.parent.route);
+      if (!r || r.kind !== "record") continue;
+      const files = (r.collection === "item" ? r.files.map((f) => f.replace("*", params.id)) : r.files).filter((f) => !f.includes("*"));
+      if (!files.some((f) => items.includes(f) || items.includes(address(source, f)))) continue;
+      for (const c of fact.children) readers.set(c.source === LOCAL ? c.path : address(c.source, c.path), { via: "where-used", reads: fact.parent.route, fact: fact.id });
+    }
+  }
+  const state = readMarks(dir);
+  const because = { source, paths, ...(version ? { version } : {}), at, via };
+  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");
+  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;
+  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;
+}
+
+/** Every stale file in the venture now. */
+export function stale(dir) {
+  const files = [...new Set(readMarks(dir).marks.map((m) => m.file))];
+  return files.map((f) => ({ file: f, ...staleOf(dir, f) })).filter((x) => x.since).sort((a, b) => a.file.localeCompare(b.file));
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const a = process.argv.slice(2);
+  const dir = a[0];
+  const all = (n) => a.flatMap((x, i) => (x === `--${n}` ? [a[i + 1]] : []));
+  if (!dir || !existsSync(join(dir, "venture.json"))) { console.error("usage: node schema/stale.mjs <venture dir> [--json] | --notify --source <id> --path <p> [--version <v>]"); process.exit(2); }
+  try {
+    if (a.includes("--notify")) {
+      const r = notify(dir, { source: all("source")[0], paths: all("path"), version: all("version")[0], via: "cli" });
+      if (a.includes("--json")) console.log(JSON.stringify(r, null, 2));
+      else console.log(r.stale.length ? `${r.stale.length} stale: ${r.stale.join(", ")}` : "nothing reads what changed, so nothing is stale");
+    } else {
+      const s = stale(dir);
+      if (a.includes("--json")) console.log(JSON.stringify(s, null, 2));
+      else console.log(s.length ? s.map((x) => `stale  ${x.file}  since ${x.since}: ${x.because.map((b) => `${b.source} changed ${b.paths.join(", ")}`).join("; ")}`).join("\n") : "nothing is stale");
+    }
+  } catch (e) { console.error(e.message); process.exit(1); }
+}

package/schema/start-release.mjs

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+// naive start (I-17, C-12): serves a venture's release read-only over local HTTP. No router: it reads
+// <venture>/.release/ and nothing else (schema/release-read.mjs), as a CDN serves a static shell. It
+// reads the manifest on each request, so an item added with build-release --add shows at once (C-18).
+// It listens on 127.0.0.1 only. The paths are listed in schema/release-read.mjs; /card.svg is the
+// release card drawn by the interface (interface/release-card.mjs).
+//
+//   node schema/start-release.mjs <venture dir> [--port n]     serve; --port 0 picks a free port (default 4330)
+//   node schema/start-release.mjs <venture dir> --get <path>   answer one path and exit, without a server
+
+import { existsSync } from "node:fs";
+import { createServer } from "node:http";
+import { join } from "node:path";
+import { svg } from "../interface/release-card.mjs";
+import { answer, readRelease } from "./release-read.mjs";
+
+const args = process.argv.slice(2);
+const opt = (n) => { const i = args.indexOf(`--${n}`); return i >= 0 ? args[i + 1] : undefined; };
+const values = new Set(["port", "get", "now"].flatMap((n) => (opt(n) !== undefined ? [opt(n)] : [])));
+const dir = args.find((a) => !a.startsWith("--") && !values.has(a));
+if (!dir || !existsSync(join(dir, "venture.json"))) { console.error("usage: node schema/start-release.mjs <venture dir> [--port n] | --get <path>"); process.exit(2); }
+if (!readRelease(dir)) { console.error(`no release in ${dir}: run node schema/build-release.mjs ${dir} first`); process.exit(1); }
+
+if (opt("get") !== undefined) {
+  const a = answer(dir, "GET", opt("get"), { draw: svg });
+  process.stdout.write(a.body);
+  process.exit(a.status < 400 ? 0 : 1);
+}
+
+const port = opt("port") === undefined ? 4330 : Number(opt("port"));
+if (!Number.isInteger(port) || port < 0 || port > 65535) { console.error(`--port ${opt("port")} is not a port`); process.exit(2); }
+const server = createServer((req, res) => {
+  const a = answer(dir, req.method, req.url ?? "/", { draw: svg });
+  res.writeHead(a.status, { "content-type": a.type, "cache-control": "no-cache", ...(a.allow ? { allow: a.allow } : {}) });
+  res.end(req.method === "HEAD" ? undefined : a.body);
+});
+server.listen(port, "127.0.0.1", () => {
+  const m = readRelease(dir);
+  console.log(`serving release ${m.release} of ${m.venture} read-only at http://127.0.0.1:${server.address().port}/`);
+});
+for (const s of ["SIGINT", "SIGTERM"]) process.on(s, () => server.close(() => process.exit(0)));

package/schema/structure.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+// The venture folder's structure (Next.js translation P-3, P-22, P-32): what venture.json declares,
+// which folders are private, and which names Naive reserves.
+//
+//   node schema/structure.mjs <venture dir> [--json]      check the structure; exit 1 on an error
+//   node schema/structure.mjs manifest <venture dir>      print the manifest venture.json declares
+//
+// P-3 venture.json is Naive's package.json: identity, phase, governance, the function owners, and the
+//      packages and kits the venture uses (EE-071). packages and kits are declared the way
+//      package.json lists dependencies; when venture.json does not list packages, the manifest
+//      derives them (the core packages that fit the phase now, plus any package that holds records).
+// P-22 A folder whose name starts with _ is private: no route reaches a file under it unless the
+//      data model names that folder in a record's path (customers/_streams/*/stream.json). _drafts/
+//      holds writes waiting for a person, _private/ never reaches a model, _notes/ holds notes,
+//      _streams/ holds a data package's append-only activity.
+// P-32 Names reserved for Naive's own conventions, now and later. A venture that uses one for
+//      something else gets an error (the name already means something) or a warning (it will).
+//
+// Never calls a model. Reads the venture folder only.
+
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+const repo = new URL("..", import.meta.url).pathname;
+const load = (f) => JSON.parse(readFileSync(f, "utf8"));
+
+/** The private folders Naive knows, and what each holds (P-22). Any other _folder is private too. */
+export const PRIVATE = {
+  _drafts: "writes held for a person to accept; Naive writes it, at the venture root only",
+  _private: "never sent to a model and never released",
+  _notes: "the founder's working notes beside a package; never routed",
+  _streams: "a data package's append-only activity (customers, investors, money)",
+};
+
+/** Names reserved for Naive conventions (P-32). in_use: Naive gives them a meaning today; future: kept free for a convention to come. */
+export const RESERVED = {
+  in_use: {
+    "AGENTS.md": "a layout: instructions for agents in this folder and below",
+    "venture.json": "a venture's manifest; a folder holding one is a nested venture",
+    "naive.config.json": "the venture's overrides, at the venture root",
+    "provenance.jsonl": "the venture's provenance log, at the venture root",
+    _drafts: PRIVATE._drafts,
+    _streams: PRIVATE._streams,
+    ".release": "release plans and output",
+  },
+  future: {
+    "layout.md": "a folder's own layout file (L-5)",
+    "template.md": "context recomputed on every action (P-12)",
+    "error.md": "a package's own error answer (P-15)",
+    "loading.md": "a package's own pending state (P-37)",
+    "not-found.md": "a package's own missing-record answer (P-14)",
+    "default.md": "what a slot shows for a package with nothing in it (P-17)",
+    "page.md": "a record's people-facing page (P-10)",
+    ".naive": "generated framework files",
+  },
+  // Folder shapes that mean something to the router: (group) shares a layout (P-36); @slot and [param] are kept for later.
+  shapes: [
+    { re: /^\(.+\)$/, name: "(group)", rule: "a route group: it holds only its AGENTS.md, the layout its packages share (P-36)" },
+    { re: /^@.+/, name: "@slot", rule: "reserved for named slots (P-21)" },
+    { re: /^\[.+\]$/, name: "[param]", rule: "reserved for dynamic segments (P-19); collections are declared by the data model, not by folder names" },
+  ],
+};
+
+const DATA_PACKAGES = ["customers", "investors", "money"];
+
+/** Whether a segment is private (P-22). */
+export const isPrivate = (segment) => segment.startsWith("_");
+
+/** Whether a route's file pattern may reach a venture file: every private segment of the file is named, as it is, in the pattern (P-22). */
+export function routable(file, pattern) {
+  const ps = pattern.split("/");
+  return file.split("/").every((s, i) => !isPrivate(s) || ps[i] === s);
+}
+
+// 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);
+  return readdirSync(d, { withFileTypes: true }).flatMap((e) => {
+    const rel = sub ? `${sub}/${e.name}` : e.name;
+    if (e.isDirectory()) {
+      if (e.name === ".git" || e.name === "node_modules") return [];
+      if (existsSync(join(d, e.name, "venture.json"))) return [{ path: rel, dir: true, venture: true }];
+      return [{ path: rel, dir: true }, ...walk(dir, rel)];
+    }
+    return [{ path: rel, dir: false }];
+  });
+}
+
+/** Checks a venture folder's private folders and reserved names. { errors, warnings, private } */
+export function structure(dir) {
+  const errors = [], warnings = [], privateFolders = [];
+  if (!existsSync(join(dir, "venture.json"))) return { errors: [`${dir} has no venture.json`], warnings, private: privateFolders };
+  for (const e of walk(dir)) {
+    const segs = e.path.split("/");
+    const name = segs.at(-1), parent = segs.slice(0, -1).join("/");
+    if (e.venture) continue;
+    if (e.dir && isPrivate(name)) privateFolders.push({ folder: `${e.path}/`, holds: PRIVATE[name] ?? "private: never routed, never released (P-22)" });
+    if (e.dir && name === "_drafts" && parent) errors.push(`${e.path}/: _drafts/ is reserved for the venture root, where Naive writes held drafts (P-32)`);
+    if (!e.dir && segs[0] === "_drafts" && segs.length === 2 && !name.endsWith(".draft") && name !== ".gitkeep") errors.push(`${e.path}: only Naive's .draft files belong in _drafts/ (P-32)`);
+    if (e.dir && name === "_streams" && !DATA_PACKAGES.includes(parent)) errors.push(`${e.path}/: _streams/ belongs directly under a data package (${DATA_PACKAGES.join(", ")}) (P-32)`);
+    if (!e.dir && ["naive.config.json", "provenance.jsonl"].includes(name) && parent) errors.push(`${e.path}: ${name} is read only at the venture root; move it or rename it (P-32)`);
+    if (e.dir && name === ".release" && parent) errors.push(`${e.path}/: .release/ is reserved for the venture root (P-32)`);
+    if (RESERVED.future[name] && !segs.some(isPrivate)) warnings.push(`${e.path}: ${name} is reserved for ${RESERVED.future[name]}; rename it so a later Naive does not read it as that (P-32)`);
+    if (e.dir) for (const s of RESERVED.shapes) {
+      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");
+        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)`);
+    }
+  }
+  return { errors, warnings, private: privateFolders };
+}
+
+const PACKAGE_NAMES = () => existsSync(join(repo, "packages")) ? readdirSync(join(repo, "packages")).filter((n) => existsSync(join(repo, "packages", n, "package.json"))) : [];
+const pkgOf = (n) => load(join(repo, "packages", n, "package.json"));
+const FUNCTIONS = () => load(join(repo, "operations/departments.json")).departments.map((d) => d.id);
+
+/**
+ * The manifest venture.json declares (P-3), with what is derived when it does not declare it:
+ * identity, phase, governance, function owners, and the packages and kits in use.
+ */
+export async function manifest(dir) {
+  const v = load(join(dir, "venture.json"));
+  const names = PACKAGE_NAMES();
+  let derived = null;
+  if (!v.packages) {
+    // 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)); });
+    derived = [...new Set([...p.core.filter((x) => x.in === "now").map((x) => x.id), ...holding])];
+  }
+  const used = v.packages ?? derived;
+  const owners = v.functions ?? {};
+  const fnOf = (n) => { const k = names.includes(n) ? pkgOf(n) : {}; return k.function ?? k.department ?? null; };
+  const solo = !(v.members?.length);
+  const functions = [...new Set(used.map(fnOf).filter(Boolean))].map((f) => ({ function: f, owner: owners[f]?.owner ?? (solo ? "the founder" : null), declared: !!owners[f], packages: used.filter((n) => fnOf(n) === f) }));
+  for (const [f, o] of Object.entries(owners)) if (!functions.some((x) => x.function === f)) functions.push({ function: f, owner: o.owner, declared: true, packages: [] });
+  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" },
+    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" })),
+  };
+}
+
+/** Errors in what venture.json declares (P-3): unknown packages and functions, kits extending a package not in use, an owner missing. */
+export function checkManifest(dir) {
+  const v = load(join(dir, "venture.json"));
+  const names = PACKAGE_NAMES(), fns = FUNCTIONS();
+  const errors = [];
+  for (const n of v.packages ?? []) if (!names.includes(n)) errors.push(`venture.json packages: ${n} is not a Naive package (one of ${names.join(", ")})`);
+  for (const [f, o] of Object.entries(v.functions ?? {})) {
+    if (!fns.includes(f)) errors.push(`venture.json functions: ${f} is not a function (one of ${fns.join(", ")})`);
+    if (!o?.owner) errors.push(`venture.json functions: ${f} has no owner; every function has one accountable owner`);
+  }
+  for (const k of v.kits ?? []) {
+    if (!names.includes(k.extends)) errors.push(`venture.json kits: ${k.id} extends ${k.extends}, which is not a Naive package`);
+    else if (v.packages && !v.packages.includes(k.extends)) errors.push(`venture.json kits: ${k.id} extends ${k.extends}, which the venture does not list in packages`);
+  }
+  return errors;
+}
+
+if (import.meta.url === `file://${process.argv[1]}`) {
+  const args = process.argv.slice(2);
+  if (args[0] === "manifest") {
+    if (!args[1] || !existsSync(join(args[1], "venture.json"))) { console.error("usage: node schema/structure.mjs manifest <venture dir>"); process.exit(2); }
+    console.log(JSON.stringify(await manifest(args[1]), null, 2));
+    process.exit(0);
+  }
+  const dir = args.find((a) => !a.startsWith("--"));
+  if (!dir || !existsSync(dir) || !statSync(dir).isDirectory()) { console.error("usage: node schema/structure.mjs <venture dir> [--json] | manifest <venture dir>"); process.exit(2); }
+  const s = structure(dir);
+  if (existsSync(join(dir, "venture.json"))) s.errors.push(...checkManifest(dir));
+  if (args.includes("--json")) console.log(JSON.stringify(s, null, 2));
+  else {
+    for (const w of s.warnings) console.warn(`warning: ${w}`);
+    if (s.errors.length) console.error(s.errors.join("\n"));
+    else console.log(`structure holds: ${s.private.length} private folders, no reserved name misused`);
+  }
+  process.exit(s.errors.length ? 1 : 0);
+}

package/schema/systems-catalog.json

@@ -0,0 +1,126 @@
+{
+  "version": "0.1.0",
+  "note": "Systems a venture's functions keep their truth in (EE-083), offered at create-venture and recorded in knowledge/sources.json `functions`. connect names the code that reaches a system; a system without it is recorded as a pointer until a connector exists.",
+  "systems": {
+    "local-repo": {
+      "label": "A local code repository",
+      "kind": "code",
+      "address": "a folder path",
+      "connect": null
+    },
+    "github": {
+      "label": "GitHub",
+      "kind": "code",
+      "address": "owner/name",
+      "connect": "knowledge/connectors: the github connector reads records from it (knowledge/sources.json)"
+    },
+    "vercel": {
+      "label": "Vercel",
+      "kind": "hosting and analytics",
+      "address": "team/project",
+      "connect": null
+    },
+    "cloudflare": {
+      "label": "Cloudflare",
+      "kind": "hosting and analytics",
+      "address": "account/zone or Pages project",
+      "connect": null
+    },
+    "stripe": {
+      "label": "Stripe",
+      "kind": "payments and sales",
+      "address": "account id (acct_...)",
+      "connect": null
+    },
+    "square": {
+      "label": "Square",
+      "kind": "payments and sales",
+      "address": "location or merchant id",
+      "connect": null
+    },
+    "shopify": {
+      "label": "Shopify",
+      "kind": "store and sales",
+      "address": "store domain (name.myshopify.com)",
+      "connect": null
+    },
+    "rho": {
+      "label": "Rho",
+      "kind": "bank and spend",
+      "address": "sandbox, or live with RHO_API_TOKEN",
+      "connect": "platform/integrations/rho.mjs sync: accounts, transactions and a summary, as pointers in money/"
+    },
+    "google-drive": {
+      "label": "Google Drive",
+      "kind": "documents",
+      "address": "folder URL",
+      "connect": null
+    },
+    "docusign": {
+      "label": "DocuSign",
+      "kind": "signatures",
+      "address": "account",
+      "connect": null
+    },
+    "local-folder": {
+      "label": "A local folder",
+      "kind": "documents",
+      "address": "a folder path",
+      "connect": null
+    }
+  },
+  "functions": {
+    "products": [
+      "local-repo",
+      "github",
+      "vercel",
+      "cloudflare"
+    ],
+    "marketing-and-sales": [
+      "vercel",
+      "cloudflare",
+      "stripe",
+      "square",
+      "shopify"
+    ],
+    "customer-service": [
+      "stripe",
+      "shopify",
+      "square"
+    ],
+    "finance": [
+      "rho",
+      "stripe",
+      "square",
+      "shopify"
+    ],
+    "risk-and-compliance": [
+      "google-drive",
+      "docusign",
+      "local-folder"
+    ],
+    "legal": [
+      "google-drive",
+      "docusign",
+      "local-folder"
+    ],
+    "it": [
+      "github",
+      "vercel",
+      "cloudflare"
+    ],
+    "external-relationships": [
+      "google-drive",
+      "local-folder"
+    ],
+    "service-delivery": [
+      "local-folder",
+      "google-drive"
+    ],
+    "supply-chain": [
+      "shopify",
+      "square",
+      "local-folder"
+    ]
+  }
+}