naive-framework 0.1.0 → 0.3.0

package/schema/port-venture.mjs

@@ -1,161 +1,235 @@
 #!/usr/bin/env node
-// naive port: brings an existing project into a new venture by keeping its files as they are (EE-076).
-// Each file is placed, unchanged, in the package directory its name or folder points to; a code
-// repository or anything that should stay where it is becomes a pointer in knowledge/sources.json;
-// what fits nowhere is left behind, by name, so nothing disappears silently. Migrate (rewriting a
-// project into the Naive convention) is the other way in, and is not this command.
+// naive port: moves an existing folder into a venture, as it is (EE-076, revised by Torian on
+// 2026-10-29: port moves, it no longer copies files into packages). The folder is moved whole, with a
+// rename, so not one file in it is opened or changed; the venture names it in sources.json as a source
+// of truth (a read-only filesystem source) and logs the move in provenance.jsonl with the path it came
+// from. Migrate (rewriting a project into the Naive convention) is the other way in.
 //
-//   node schema/port-venture.mjs --from <project> --venture <new venture dir>
-//        writes the plan to <venture>/.release/port-plan.json and prints it; changes nothing else
-//   node schema/port-venture.mjs --venture <dir> --apply --confirm port
-//        carries out the plan as it now reads; the founder may first set any item's action to
-//        port, point or leave
+//   node schema/port-venture.mjs <folder> --venture <dir> [--to <path>] [--links <dir> ...]
+//        adds the move to the plan at <venture>/.release/port-plan.json and prints it; moves nothing.
+//        The folder goes to <venture>/repo/<its name> unless --to says where (relative to the venture
+//        or absolute). Run once per folder: each run adds or replaces that folder's item.
+//   node schema/port-venture.mjs --venture <dir> --apply --confirm port [--even-if-busy]
+//        carries out every planned move the founder left as move; any item can be set to leave first
 //
-// The project is only ever read. A port never overwrites a file in the venture, refuses a plan
-// whose source files changed since it was written, and records every copy in provenance.jsonl
-// with the source path it was derived from.
+// The plan says what a move would break: worktrees of a git repository (they point at its old path
+// until `git worktree repair` runs from the new one), symbolic links that point into the folder, and
+// processes working inside it, which refuse the apply unless --even-if-busy. A port never overwrites,
+// never copies (a move across disks is refused, not copied), and refuses an item whose folder changed
+// identity since the plan. Every run writes a trace to .release/port-trace.json, in the shape
+// platform/integrations/langsmith.mjs uploads.
 
+import { spawnSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
-import { basename, dirname, extname, join, relative, resolve, sep } from "node:path";
-import { record } from "../interface/provenance.mjs";
-import { SECRET } from "./migrate-venture.mjs";
+import { existsSync, lstatSync, mkdirSync, readdirSync, readFileSync, readlinkSync, realpathSync, renameSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { agentFromEnv, record } from "../interface/provenance.mjs";
+import { ventureFile } from "./venture-paths.mjs";
 
 export const PLAN = ".release/port-plan.json";
-const SKIP = new Set([".git", "node_modules", ".next", ".turbo", "dist", "build", ".venv", "__pycache__", ".DS_Store"]);
-const REPO_MARKERS = [".git", "package.json", "Cargo.toml", "go.mod", "pyproject.toml", "Gemfile", "pom.xml"];
-const CODE = new Set([".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx", ".py", ".rb", ".go", ".rs", ".java", ".kt", ".swift", ".c", ".h", ".cpp", ".cs", ".php", ".sh", ".sql", ".css", ".scss", ".html", ".lock", ".yml", ".yaml", ".toml"]);
-const MAX_BYTES = 5 * 1024 * 1024;
+export const TRACE = ".release/port-trace.json";
+const MAP = "knowledge/sources.json";
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^[^a-z]+|-$/g, "") || "folder";
+const inside = (a, b) => a === b || a.startsWith(b + sep);
+const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
 
-// The first rule whose pattern matches wins: the file name is tried before its folders, so a file
-// says more about itself than the folder it sits in. Patterns match words in lowercase paths.
-const RULES = [
-  [/\b(problem|pain[- ]?points?)\b/, "foundation", "states the problem"],
-  [/\b(icp|personas?|ideal[- ]customer|customer[- ]profile|segments?)\b/, "foundation", "describes the customer"],
-  [/\b(vision|mission|tagline|values|manifesto|one[- ]pager|strategy)\b/, "foundation", "states what the venture is for"],
-  [/\b(interviews?|surveys?|user[- ]research|customer[- ]research|discovery|experiments?|hypothes[ie]s|validation)\b/, "validation", "is evidence about the problem or the solution"],
-  [/\b(investors?|pitch|deck|fundrais\w*|safe|term[- ]sheet|cap[- ]table|data[- ]room)\b/, "investors", "is for or about investors"],
-  [/\b(pricing|prices?|revenue|budget|forecast|runway|financ\w*|p&l|burn|unit[- ]economics|model)\b/, "finance", "is about money the venture plans or earns"],
-  [/\b(brand\w*|marketing|copy|landing|seo|social|launch|blog|newsletter|campaigns?|content|go[- ]to[- ]market|gtm)\b/, "marketing", "is marketing or sales"],
-  [/\b(roadmap|specs?|prd|requirements|features?|product|designs?|ux|ui|wireframes?|mockups?|backlog)\b/, "product", "describes the product"],
-  [/\b(team|hiring|roles?|org[- ]chart|founders?|equity|vesting|people|onboarding|handbook|culture)\b/, "people", "is about the people"],
-  [/\b(customers?|clients?|accounts|crm|leads|pipeline)\b/, "customers", "is about customers"],
-  [/\b(decisions?|adrs?|decision[- ]log)\b/, "decisions", "records decisions"],
-  [/\b(legal|contracts?|agreements?|incorporation|bylaws|operating[- ]agreement|nda|terms|privacy|trademark|ip)\b/, "_private/legal", "is a legal document, kept private so it never reaches a model"],
-];
-const BANK = /\b(bank|transactions?|ledger|payroll|tax(es)?)\b/;
+// Files and bytes under a folder, without following links, to show the size of what moves, and a
+// manifest hash (each path with its size, never its contents) for the provenance entry.
+function measure(root) {
+  let files = 0, bytes = 0;
+  const lines = [];
+  const stack = [root];
+  while (stack.length) {
+    const d = stack.pop();
+    let list = [];
+    try { list = readdirSync(d, { withFileTypes: true }); } catch { continue; }
+    for (const e of list) {
+      const p = join(d, e.name);
+      if (e.isDirectory()) stack.push(p);
+      else { files++; let n = 0; try { n = lstatSync(p).size; } catch {} bytes += n; lines.push(`${relative(root, p)} ${n}`); }
+    }
+  }
+  return { files, bytes, manifest: createHash("sha256").update(lines.sort().join("\n")).digest("hex") };
+}
 
-const words = (s) => s.toLowerCase().replace(/[_.]+/g, " ");
-const sha = (f) => createHash("sha256").update(readFileSync(f)).digest("hex");
-const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "project";
+// Symbolic links under `roots` (to `depth` levels, skipping node_modules) whose target is inside `src`.
+// A link inside `src` that points inside it with a relative path keeps working, so only absolute ones count.
+export function linksInto(src, roots, depth = 4) {
+  const out = [];
+  const seen = new Set();
+  const visit = (d, n) => {
+    if (n > depth || seen.has(d)) return;
+    seen.add(d);
+    let list = [];
+    try { list = readdirSync(d, { withFileTypes: true }); } catch { return; }
+    for (const e of list) {
+      if (e.name === "node_modules" || e.name === ".git") continue;
+      const p = join(d, e.name);
+      if (e.isSymbolicLink()) {
+        const t = readlinkSync(p);
+        const target = resolve(dirname(p), t);
+        if (inside(target, src) && !(inside(p, src) && !isAbsolute(t))) out.push({ link: p, target: t });
+      } else if (e.isDirectory()) visit(p, n + 1);
+    }
+  };
+  for (const r of roots) visit(resolve(r), 0);
+  return out;
+}
 
-/** Where one file goes, or why it stays behind. `rel` is relative to the project root. */
-export function place(rel, bytes) {
-  const name = basename(rel, extname(rel));
-  const ext = extname(rel).toLowerCase();
-  if (bytes > MAX_BYTES) return { action: "leave", reason: `larger than ${MAX_BYTES / 1024 / 1024} MB; point to it instead` };
-  if (CODE.has(ext)) return { action: "leave", reason: "code or configuration: it stays in its repository" };
-  const folders = dirname(rel) === "." ? [] : dirname(rel).split(sep).reverse();
-  for (const [where, confidence] of [[name, "high"], ...folders.map((f) => [f, "low"])]) {
-    if (BANK.test(words(where))) return { action: "leave", reason: "bank and payroll data come from the bank connection, not from files" };
-    const hit = RULES.find(([re]) => re.test(words(where)));
-    if (hit) return { action: "port", to: `${hit[1]}/${basename(rel)}`, function: hit[1].split("/").at(-1), confidence, reason: `${confidence === "high" ? "its name" : `its folder ${where}`} ${hit[2]}` };
-  }
-  if (/^readme$/i.test(name)) return { action: "leave", reason: "the venture has its own AGENTS.md and profile.md; read this to write profile.md" };
-  return { action: "leave", reason: "nothing in its name or folders matches a package; place it by hand or migrate it" };
+// The git facts a move touches: whether the folder is a repository, its other worktrees, and how
+// many changes are uncommitted (the move keeps them; it is only said).
+function git(src) {
+  const g = join(src, ".git");
+  if (!existsSync(g)) return null;
+  if (statSync(g).isFile()) return { linked: true, worktrees: [], uncommitted: null };
+  const run = (...a) => spawnSync("git", ["-C", src, ...a], { encoding: "utf8" });
+  const wt = (run("worktree", "list", "--porcelain").stdout ?? "").split("\n").filter((l) => l.startsWith("worktree ")).map((l) => l.slice(9)).filter((p) => real(p) !== real(src));
+  const st = run("status", "--porcelain");
+  return { linked: false, worktrees: wt, uncommitted: st.status === 0 ? st.stdout.split("\n").filter(Boolean).length : null };
 }
 
-function walk(root, rel = "", out = { files: [], repos: [], secrets: [] }) {
-  for (const e of readdirSync(join(root, rel), { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
-    if (SKIP.has(e.name) || e.isSymbolicLink()) continue;
-    const r = rel ? join(rel, e.name) : e.name;
-    if (e.isDirectory()) {
-      if (REPO_MARKERS.some((m) => existsSync(join(root, r, m)))) out.repos.push(r);
-      else walk(root, r, out);
-    } else if (e.isFile() && SECRET.test(r)) out.secrets.push(r);
-    else if (e.isFile() && !e.name.startsWith(".")) out.files.push(r);
+// Processes whose working directory is inside the folder (macOS and Linux lsof).
+export function busy(src) {
+  const r = spawnSync("lsof", ["-d", "cwd", "-Fpcn"], { encoding: "utf8" });
+  if (r.error || !r.stdout) return [];
+  const out = [];
+  let p = null, c = null;
+  for (const l of r.stdout.split("\n")) {
+    if (l[0] === "p") p = l.slice(1);
+    else if (l[0] === "c") c = l.slice(1);
+    else if (l[0] === "n" && inside(l.slice(1), real(src)) && p !== String(process.pid)) out.push({ pid: Number(p), command: c, cwd: l.slice(1) });
   }
   return out;
 }
 
-/** The plan for porting `from` into the venture at `dir`. Reads both, writes neither. */
-export function plan(from, dir) {
-  const src = resolve(from);
-  if (!existsSync(src) || !statSync(src).isDirectory()) throw new Error(`${from} is not a directory`);
+const readPlan = (dir) => existsSync(ventureFile(dir, PLAN)) ? JSON.parse(readFileSync(ventureFile(dir, PLAN), "utf8")) : null;
+const readMap = (dir) => existsSync(ventureFile(dir, MAP)) ? JSON.parse(readFileSync(ventureFile(dir, MAP), "utf8")) : { sources: [], records: {} };
+
+/** The planned move of `folder` into the venture at `dir`. Reads both, writes neither. */
+export function planOne(folder, dir, { to, links = [] } = {}) {
+  if (!existsSync(folder) || !lstatSync(folder).isDirectory()) throw new Error(`${folder} is not a directory`);
   if (!existsSync(join(dir, "venture.json"))) throw new Error(`${dir} is not a venture: create one first with naive init`);
-  if (resolve(dir).startsWith(src + sep) || resolve(dir) === src) throw new Error("the venture cannot sit inside the project it ports from");
-  const { files, repos, secrets } = walk(src);
-  const items = secrets.map((f) => ({ from: f, action: "leave", reason: "looks like a secret, so it was never opened" }));
-  // The project itself is a repository when it carries a marker at its root: point to it, and still
-  // port its documents.
-  for (const r of REPO_MARKERS.some((m) => existsSync(join(src, m))) ? ["", ...repos] : repos)
-    items.push({ from: r || ".", action: "point", source: slug(r ? basename(r) : basename(src)), reason: "a code repository stays where it is; the venture points to it" });
-  const taken = new Set();
-  for (const f of files) {
-    const p = place(f, statSync(join(src, f)).size);
-    if (p.action === "port") {
-      // Two files with one name in one package: the second keeps its folder name in front.
-      if (taken.has(p.to)) p.to = `${dirname(p.to)}/${slug(basename(dirname(f)))}-${basename(f)}`;
-      if (taken.has(p.to) || existsSync(join(dir, p.to))) Object.assign(p, { action: "leave", reason: `${p.to} already exists in the venture; a port never overwrites` });
-      else taken.add(p.to);
-    }
-    items.push({ from: f, sha256: sha(join(src, f)), ...p });
-  }
-  const count = (a) => items.filter((i) => i.action === a).length;
-  return { from: src, venture: JSON.parse(readFileSync(join(dir, "venture.json"), "utf8")).id, at: new Date().toISOString(),
-    summary: { port: count("port"), point: count("point"), leave: count("leave") }, items };
+  const src = real(folder);
+  const v = real(dir);
+  if (inside(v, src)) throw new Error("the venture cannot sit inside the folder it ports");
+  const dest = resolve(v, to ?? join("repo", basename(src)));
+  const s = statSync(src);
+  const item = { action: "move", from: src, to: dest, source: slug(basename(src)), identity: { dev: s.dev, ino: s.ino }, ...measure(src) };
+  const warnings = [];
+  const leave = (why) => Object.assign(item, { action: "leave", reason: why });
+  if (existsSync(dest)) leave(`${dest} already exists; a port never overwrites`);
+  else if (inside(dest, src)) leave("the destination is inside the folder itself");
+  else if (!inside(dest, v)) warnings.push("the destination is outside the venture folder; sources.json will name it by absolute path");
+  // A rename only works on one disk: the nearest existing parent of the destination must share it.
+  let up = dirname(dest);
+  while (!existsSync(up)) up = dirname(up);
+  if (item.action === "move" && statSync(up).dev !== s.dev) leave("the destination is on another disk; a port moves, it never copies");
+  if (item.action === "move" && readMap(dir).sources.some((x) => x.id === item.source)) leave(`sources.json already has a source ${item.source}`);
+  const g = git(src);
+  item.git = g;
+  if (g?.linked) warnings.push("this folder is a linked git worktree; its main repository will point at the old path until `git worktree repair` runs there");
+  if (g?.worktrees.length) warnings.push(`${g.worktrees.length} worktree${g.worktrees.length === 1 ? "" : "s"} of this repository point at its old path until \`git -C ${dest} worktree repair\` runs: ${g.worktrees.join(", ")}`);
+  if (g?.uncommitted) warnings.push(`${g.uncommitted} uncommitted change${g.uncommitted === 1 ? "" : "s"} move with it, unchanged`);
+  item.links = linksInto(src, [dirname(src), src, ...links]);
+  if (item.links.length) warnings.push(`${item.links.length} symbolic link${item.links.length === 1 ? "" : "s"} point into it and will break: ${item.links.map((x) => x.link).join(", ")}`);
+  item.busy = busy(src);
+  if (item.busy.length) warnings.push(`${item.busy.length} process${item.busy.length === 1 ? " is" : "es are"} working inside it (${[...new Set(item.busy.map((x) => x.command))].join(", ")}); apply refuses unless --even-if-busy`);
+  item.warnings = warnings;
+  return item;
 }
 
-/** Carries out a plan as the founder left it. Returns what was done. */
-export function apply(dir, p, agent = { kind: "person", via: "cli" }) {
-  const src = p.from;
-  for (const i of p.items.filter((x) => x.action === "port")) {
-    if (!existsSync(join(src, i.from)) || sha(join(src, i.from)) !== i.sha256) throw new Error(`${i.from} changed since the plan was written; write the plan again`);
-    if (existsSync(join(dir, i.to))) throw new Error(`${i.to} already exists in the venture; a port never overwrites`);
+/** Adds (or replaces) one folder's item in the venture's plan and writes it. */
+export function plan(folder, dir, opts = {}) {
+  const item = planOne(folder, dir, opts);
+  const p = readPlan(dir) ?? { venture: JSON.parse(readFileSync(join(dir, "venture.json"), "utf8")).id, items: [] };
+  const others = p.items.filter((i) => i.from !== item.from && i.action === "move" && !i.done);
+  if (others.some((i) => i.source === item.source)) Object.assign(item, { action: "leave", reason: `another planned move already uses the source id ${item.source}` });
+  if (others.some((i) => i.to === item.to)) Object.assign(item, { action: "leave", reason: `another planned move already goes to ${item.to}` });
+  p.items = [...p.items.filter((i) => i.from !== item.from || i.done), item];
+  p.at = new Date().toISOString();
+  mkdirSync(dirname(ventureFile(dir, PLAN)), { recursive: true });
+  writeFileSync(ventureFile(dir, PLAN), JSON.stringify(p, null, 2) + "\n");
+  return { plan: p, item };
+}
+
+/** Carries out the plan as the founder left it. Checks every item before moving any. */
+export function apply(dir, p, { agent = agentFromEnv("person", "cli"), evenIfBusy = false } = {}) {
+  const moves = p.items.filter((i) => i.action === "move" && !i.done);
+  const ids = new Set(readMap(dir).sources.map((s) => s.id));
+  for (const i of moves) {
+    if (!existsSync(i.from)) throw new Error(`${i.from} is gone; write the plan again`);
+    const s = statSync(i.from);
+    if (s.dev !== i.identity.dev || s.ino !== i.identity.ino) throw new Error(`${i.from} is not the folder the plan was written for; write the plan again`);
+    if (existsSync(i.to)) throw new Error(`${i.to} already exists; a port never overwrites`);
+    if (ids.has(i.source)) throw new Error(`sources.json already has a source ${i.source}`);
+    const b = busy(i.from);
+    if (b.length && !evenIfBusy) throw new Error(`${b.length} process${b.length === 1 ? " is" : "es are"} working inside ${i.from} (${b.map((x) => `${x.command} ${x.pid}`).join(", ")}); stop them or add --even-if-busy`);
   }
-  const done = { ported: [], pointed: [] };
-  for (const i of p.items.filter((x) => x.action === "port")) {
-    mkdirSync(dirname(join(dir, i.to)), { recursive: true });
-    copyFileSync(join(src, i.from), join(dir, i.to));
-    record(dir, { entity: i.to, activity: "port", agent, derived_from: [`file://${join(src, i.from)}`], note: `ported unchanged: ${i.reason}` });
-    done.ported.push(i.to);
-  }
-  const points = p.items.filter((x) => x.action === "point");
-  if (points.length) {
-    const f = join(dir, "knowledge/sources.json");
-    const map = existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : { sources: [], records: {} };
-    for (const i of points) {
-      if (map.sources.some((s) => s.id === i.source)) continue;
-      map.sources.push({ id: i.source, connector: "filesystem", writes: "none", root: join(src, i.from === "." ? "" : i.from), note: `ported as a pointer: ${i.reason}` });
-      done.pointed.push(i.source);
-    }
-    mkdirSync(dirname(f), { recursive: true });
-    writeFileSync(f, JSON.stringify(map, null, 2) + "\n");
-    if (done.pointed.length) record(dir, { entity: "knowledge/sources.json", activity: "port", agent, note: `pointers to ${done.pointed.join(", ")}` });
+  const done = [];
+  for (const i of moves) {
+    mkdirSync(dirname(i.to), { recursive: true });
+    renameSync(i.from, i.to);
+    const map = readMap(dir);
+    const root = inside(i.to, real(dir)) ? relative(real(dir), i.to) : i.to;
+    map.sources.push({ id: i.source, connector: "filesystem", writes: "none", root, note: `source of truth, moved here unchanged from ${i.from} by naive port` });
+    mkdirSync(dirname(ventureFile(dir, MAP)), { recursive: true });
+    writeFileSync(ventureFile(dir, MAP), JSON.stringify(map, null, 2) + "\n");
+    record(dir, { entity: root, activity: "port", agent, derived_from: [`file://${i.from}`], sha256: measure(i.to).manifest, note: `moved unchanged (${i.files} files); named in sources.json as source ${i.source}` });
+    i.done = new Date().toISOString();
+    done.push(i);
+    writeFileSync(ventureFile(dir, PLAN), JSON.stringify(p, null, 2) + "\n");
   }
   return done;
 }
 
+// One run as a trace for platform/integrations/langsmith.mjs: the run, and a child per item.
+function trace(dir, name, inputs, start, items, error) {
+  const end = new Date().toISOString();
+  const t = { name, run_type: "chain", start, end, inputs, outputs: { items: items.map(({ from, to, action, done }) => ({ from, to, action, done })) }, ...(error ? { error } : {}),
+    tags: ["naive", "port"], children: items.map((i) => ({ name: `${i.action} ${basename(i.from)}`, run_type: "tool", start, end, inputs: { from: i.from, to: i.to },
+      outputs: { action: i.action, reason: i.reason, files: i.files, bytes: i.bytes, warnings: i.warnings, done: i.done } })) };
+  try { mkdirSync(dirname(ventureFile(dir, TRACE)), { recursive: true }); writeFileSync(ventureFile(dir, TRACE), JSON.stringify(t, null, 2) + "\n"); } catch { return; }
+  // The harness's way (interface/harness/run.mjs): with a key set, the platform exporter ships the trace.
+  if (process.env.LANGSMITH_API_KEY) {
+    const p = spawnSync("node", [join(dirname(new URL(import.meta.url).pathname), "../platform/integrations/langsmith.mjs"), ventureFile(dir, TRACE), "--project", process.env.LANGSMITH_PROJECT ?? "naive-port"], { encoding: "utf8" });
+    console.log(p.status === 0 ? `LangSmith: ${p.stdout.trim()}` : `LangSmith upload failed: ${(p.stderr || p.stdout).trim()}`);
+  }
+}
+
+const mb = (b) => `${(b / 1024 / 1024).toFixed(1)} MB`;
+
 if (import.meta.url === `file://${process.argv[1]}`) {
   const args = process.argv.slice(2);
   const opt = (k) => { const i = args.indexOf(`--${k}`); return i < 0 ? undefined : args[i + 1]; };
+  const all = (k) => args.flatMap((a, i) => a === `--${k}` ? [args[i + 1]] : []);
+  const VALUED = new Set(["--venture", "--to", "--links", "--confirm", "--from"]);
+  const folder = opt("from") ?? args.find((a, i) => !a.startsWith("--") && !VALUED.has(args[i - 1]));
   const dir = opt("venture");
-  if (!dir) { console.error("usage: node schema/port-venture.mjs --from <project> --venture <dir> | --venture <dir> --apply --confirm port"); process.exit(2); }
-  try {
-    if (args.includes("--apply")) {
-      if (opt("confirm") !== "port") { console.error("type --confirm port to carry out the plan"); process.exit(1); }
-      if (!existsSync(join(dir, PLAN))) { console.error(`no plan at ${join(dir, PLAN)}: run with --from first`); process.exit(1); }
-      const d = apply(dir, JSON.parse(readFileSync(join(dir, PLAN), "utf8")));
-      console.log(`ported ${d.ported.length} files unchanged; pointed to ${d.pointed.length} source${d.pointed.length === 1 ? "" : "s"}`);
-    } else {
-      const from = opt("from");
-      if (!from) { console.error("--from <project> is needed to write a plan"); process.exit(2); }
-      const p = plan(from, dir);
-      mkdirSync(join(dir, ".release"), { recursive: true });
-      writeFileSync(join(dir, PLAN), JSON.stringify(p, null, 2) + "\n");
-      for (const i of p.items) console.log(`${i.action.padEnd(5)}  ${i.from}${i.to ? `  ->  ${i.to}` : i.source ? `  ->  source ${i.source}` : ""}   (${i.reason})`);
-      console.log(`\n${p.summary.port} to port, ${p.summary.point} to point to, ${p.summary.leave} left behind. Nothing has changed yet.`);
-      console.log(`Read ${relative(process.cwd(), join(dir, PLAN))}, set any item's action to port, point or leave, then run with --apply --confirm port.`);
-    }
-  } catch (e) { console.error(e.message); process.exit(1); }
+  if (!dir) { console.error("usage: node schema/port-venture.mjs <folder> --venture <dir> [--to <path>] | --venture <dir> --apply --confirm port"); process.exit(2); }
+  const start = new Date().toISOString();
+  if (args.includes("--apply")) {
+    if (opt("confirm") !== "port") { console.error("type --confirm port to carry out the plan"); process.exit(1); }
+    const p = readPlan(dir);
+    if (!p) { console.error(`no plan at ${ventureFile(dir, PLAN)}: run naive port <folder> first`); process.exit(1); }
+    try {
+      const d = apply(dir, p, { evenIfBusy: args.includes("--even-if-busy") });
+      trace(dir, "naive port apply", { venture: dir }, start, d);
+      for (const i of d) console.log(`moved  ${i.from}  ->  ${i.to}   (${i.files} files, unchanged; source ${i.source})`);
+      for (const i of d.filter((x) => x.git?.worktrees.length)) console.log(`\nrepair its worktrees: git -C ${i.to} worktree repair`);
+      console.log(`\nmoved ${d.length} folder${d.length === 1 ? "" : "s"}. Trace: ${relative(process.cwd(), ventureFile(dir, TRACE))}`);
+    } catch (e) { trace(dir, "naive port apply", { venture: dir }, start, p.items, e.message); console.error(e.message); process.exit(1); }
+  } else {
+    if (!folder) { console.error("name the folder to port: naive port <folder>"); process.exit(2); }
+    try {
+      const { plan: p, item } = plan(folder, dir, { to: opt("to"), links: all("links") });
+      trace(dir, "naive port plan", { folder, venture: dir, to: opt("to") }, start, [item]);
+      for (const i of p.items) {
+        console.log(`${(i.done ? "moved" : i.action).padEnd(5)}  ${i.from}  ->  ${i.to}   (${i.files} files, ${mb(i.bytes)}${i.reason ? `; ${i.reason}` : ""})`);
+        if (!i.done) for (const w of i.warnings ?? []) console.log(`       ! ${w}`);
+      }
+      const n = p.items.filter((i) => i.action === "move" && !i.done).length;
+      console.log(`\n${n} folder${n === 1 ? "" : "s"} to move, unchanged. Nothing has moved yet.`);
+      console.log(`Read ${relative(process.cwd(), ventureFile(dir, PLAN))}, set any item's action to leave, then run with --apply --confirm port.`);
+    } catch (e) { trace(dir, "naive port plan", { folder, venture: dir }, start, [], e.message); console.error(e.message); process.exit(1); }
+  }
 }

package/schema/public-assets.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "public-assets.schema.json",
+  "title": "Public assets",
+  "description": "The register of what the venture ships as it is, at public/assets.json (I-23, J-2, J-3, J-4): each file in public/ with its source, license and credit, facts read by code from its bytes, and alt text with who wrote it; remote images as links with a note in raw/sources/<id>/; and remote_hosts, the hosts an agent may fetch from. Checked by schema/check-assets.mjs. Version 0.x, unevaluated.",
+  "type": "object",
+  "required": ["version", "assets"],
+  "additionalProperties": false,
+  "$defs": {
+    "alt": {
+      "type": "object",
+      "required": ["text", "by"],
+      "additionalProperties": false,
+      "properties": {
+        "text": { "type": "string", "minLength": 1 },
+        "by": { "enum": ["agent", "person"], "description": "Who wrote it. An agent's alt text stays pending until a person confirms it in provenance" }
+      }
+    },
+    "facts": {
+      "type": "object",
+      "required": ["type", "bytes", "sha256"],
+      "additionalProperties": false,
+      "description": "Read from the bytes by code (schema/assets.mjs), never written by hand",
+      "properties": {
+        "type": { "type": "string" },
+        "width": { "type": "integer" },
+        "height": { "type": "integer" },
+        "sizes": { "type": "array", "items": { "type": "string" } },
+        "bytes": { "type": "integer" },
+        "sha256": { "type": "string", "pattern": "^[0-9a-f]{64}$" },
+        "filled_at": { "type": "string" }
+      }
+    }
+  },
+  "properties": {
+    "version": { "type": "string" },
+    "remote_hosts": { "type": "array", "items": { "type": "string" }, "description": "Hosts an agent may fetch images from (exact, or *.example.com); the platform fetcher refuses any other" },
+    "assets": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["path", "source", "license"],
+        "additionalProperties": false,
+        "properties": {
+          "path": { "type": "string", "pattern": "^public/(?!.*\\.\\./).+" },
+          "source": { "type": "string", "description": "Where it came from: who made it, or a URL" },
+          "license": { "type": "string", "description": "An SPDX id (CC-BY-4.0, OFL-1.1), owned (made by or for the venture), licensed (bought), or the restriction (all-rights-reserved)" },
+          "credit": { "type": "string", "description": "Who to credit; a missing credit fails the check" },
+          "alt": { "$ref": "#/$defs/alt" },
+          "decorative": { "type": "boolean", "description": "An image that says nothing, so it needs no alt text" },
+          "origin_url": { "type": "string", "description": "The remote work this is a copy of" },
+          "design_system": { "type": "string", "description": "The design system (brand design_systems id) this came from" },
+          "facts": { "$ref": "#/$defs/facts" }
+        }
+      }
+    },
+    "remote": {
+      "type": "array",
+      "description": "Remote images the venture links to rather than ships",
+      "items": {
+        "type": "object",
+        "required": ["id", "url", "license"],
+        "additionalProperties": false,
+        "properties": {
+          "id": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$", "description": "The raw source holding the note: raw/sources/<id>/" },
+          "url": { "type": "string" },
+          "license": { "type": "string" },
+          "credit": { "type": "string" },
+          "alt": { "$ref": "#/$defs/alt" },
+          "fetched": { "$ref": "#/$defs/facts", "description": "Facts from a fetch by the platform; the original stays private in raw/sources/<id>/original.*" },
+          "copy": { "type": "string", "pattern": "^public/", "description": "Where a full copy was kept, only when the license allows it" }
+        }
+      }
+    }
+  }
+}

package/schema/release-read.mjs

@@ -0,0 +1,112 @@
+// Reading a release without the router (C-12, I-17). A release is the venture's static shell
+// (C-11): the confirmed records frozen in, and named holes for what stays live. Everything here
+// reads <venture>/.release/ and nothing else, so a release can be read after the venture's records
+// change, on a machine with no router, or handed to an investor as files. It never imports
+// interface/router.mjs; schema/releases-test.mjs checks that.
+//
+// The answer to a path is { status, type, body }:
+//   /                    the release index: venture, phase, release id, routes in the release, holes
+//   /release.json        the manifest;  /card.json  the release card's data (P-25, O-7)
+//   /records/<file>      one frozen record, as it was when it was confirmed
+//   /<route>             a route as the release holds it: a frozen record, a collection's frozen items,
+//                        a frozen command answer (H-4), or a hole that names where to read it live.
+//                        An item the release does not hold answers 404 with the items it does and the
+//                        command that adds it without rebuilding the rest (C-18, N-10).
+// Any method other than GET or HEAD answers 405: a release is read-only.
+
+import { existsSync, readFileSync } from "node:fs";
+import { join, normalize } from "node:path";
+import { ventureFile } from "./venture-paths.mjs";
+
+export const RELEASE_DIR = ".release";
+export const MANIFEST = ".release/release.json";
+export const CARD = ".release/card.json";
+export const RECORDS = ".release/records";
+
+/** The release manifest of a venture, or null when it has none. */
+export function readRelease(dir) {
+  const f = ventureFile(dir, MANIFEST);
+  return existsSync(f) ? JSON.parse(readFileSync(f, "utf8")) : null;
+}
+
+/** The frozen copy of one record in a release, as text, or null. */
+export function frozenText(dir, file) {
+  const rel = normalize(file);
+  if (rel.startsWith("..") || rel.startsWith("/")) return null;
+  const f = join(ventureFile(dir, RECORDS), rel);
+  return existsSync(f) ? readFileSync(f, "utf8") : null;
+}
+
+const parse = (file, text) => file.endsWith(".json") ? JSON.parse(text) : text;
+const json = (status, body) => ({ status, type: "application/json; charset=utf-8", body: JSON.stringify(body, null, 2) + "\n" });
+
+/** The index a reader starts from. */
+export function index(m) {
+  return { release: m.release, venture: m.venture, name: m.name, phase: m.phase, built_at: m.built_at, now: m.now,
+    routes: m.routes.filter((r) => r.in === "release").map((r) => r.route),
+    holes: m.holes.map((h) => ({ kind: h.kind, route: h.route, name: h.name, why: h.why })),
+    card: "/card.json", manifest: "/release.json",
+    note: "A release is read-only. Holes stay live: read them in the venture through the router." };
+}
+
+/** What a route holds in a release: { status, body }. Matches a concrete route (product/kettle) to its entry. */
+export function resolveRoute(dir, m, route) {
+  route = route.replace(/^\/+|\/+$/g, "");
+  const exact = m.routes.find((r) => r.route === route);
+  const entry = exact ?? m.routes.find((r) => r.route.endsWith("/[id]") && route.startsWith(r.route.slice(0, -4)) && !route.slice(r.route.length - 4).includes("/"));
+  if (!entry) return { status: 404, body: { error: `no route ${route} in release ${m.release}` } };
+  const id = exact ? null : route.slice(entry.route.length - 4);
+  const holes = m.holes.filter((h) => h.route === route || h.route_template === entry.route);
+  // A decision is also found by its id (decisions/founding-team), whatever its file is called.
+  const own = holes.find((h) => (h.route === route || (h.kind === "decision" && `decisions/${h.name}` === route)) && h.kind !== "attribute");
+  if (entry.in === "hole") return { status: 200, body: { route, hole: true, kind: own?.kind ?? entry.kind, why: own?.why ?? entry.why, live: own?.live ?? entry.live ?? null, ...(own ? {} : { holes }) } };
+  if (entry.in === "left out") return { status: 404, body: { route, left_out: true, why: entry.why } };
+  if (entry.kind === "command") {
+    const out = m.commands?.[entry.route];
+    return out === undefined ? { status: 404, body: { route, empty: true, why: entry.why ?? "not in this release" } } : { status: 200, body: { route, frozen: true, built_from: out.built_from, result: out.result } };
+  }
+  const recs = m.records.filter((r) => r.route_template === entry.route);
+  const fieldHoles = (r) => m.holes.filter((h) => h.kind === "attribute" && h.file === r.file).map((h) => h.field);
+  const one = (r) => ({ file: r.file, as_of: r.as_of, confirmed_by: r.confirmed_by, ...(fieldHoles(r).length ? { live_fields: fieldHoles(r) } : {}), record: parse(r.file, frozenText(dir, r.file)) });
+  if (entry.collection === "list") {
+    const items = m.records.filter((r) => r.route_template === `${entry.route}/[id]`);
+    return { status: 200, body: { route, items: Object.fromEntries(items.map((r) => [r.id, one(r)])), holes } };
+  }
+  if (entry.collection === "item") {
+    const hit = recs.find((r) => r.id === id);
+    if (own) return { status: 200, body: { route, hole: true, kind: own.kind, why: own.why, live: own.live ?? null } };
+    if (!hit) return { status: 404, body: { route, not_in_release: true, release: m.release, items: recs.map((r) => r.id), ...(holes.length ? { live_items: holes.filter((h) => h.kind !== "attribute").map((h) => h.name) } : {}),
+      note: `${route} was not known when release ${m.release} was built`, add: `node schema/build-release.mjs <venture dir> --add ${route}` } };
+    return { status: 200, body: { route, ...one(hit) } };
+  }
+  if (!recs.length) return { status: 404, body: { route, empty: true, why: entry.why ?? "no confirmed record when the release was built" } };
+  return { status: 200, body: { route, ...(recs.length === 1 ? one(recs[0]) : { records: recs.map(one) }) } };
+}
+
+/**
+ * Answers one request against a venture's release. draw, when given, turns the card's data into an
+ * image (the interface's job, O-7): draw(card) -> SVG text.
+ */
+export function answer(dir, method, path, { draw } = {}) {
+  if (method !== "GET" && method !== "HEAD") return { ...json(405, { error: "a release is read-only: only GET and HEAD" }), allow: "GET, HEAD" };
+  const m = readRelease(dir);
+  if (!m) return json(503, { error: `no release in ${dir}: run node schema/build-release.mjs ${dir} first` });
+  const p = decodeURIComponent(path.split("?")[0]);
+  if (p.split("/").includes("..")) return json(400, { error: "no .. in a release path" });
+  if (p === "/" || p === "") return json(200, index(m));
+  if (p === "/release.json") return json(200, m);
+  if (p === "/card.json") return existsSync(ventureFile(dir, CARD)) ? json(200, JSON.parse(readFileSync(ventureFile(dir, CARD), "utf8"))) : json(404, { error: "this release has no card" });
+  if (p === "/card.svg") {
+    if (!draw) return json(404, { error: "no card drawing here" });
+    return { status: 200, type: "image/svg+xml; charset=utf-8", body: draw(JSON.parse(readFileSync(ventureFile(dir, CARD), "utf8"))) };
+  }
+  if (p.startsWith("/records/")) {
+    const file = p.slice("/records/".length);
+    const r = m.records.find((x) => x.file === file);
+    const text = r ? frozenText(dir, file) : null;
+    if (text === null) return json(404, { error: `${file} is not in release ${m.release}` });
+    return { status: 200, type: file.endsWith(".json") ? "application/json; charset=utf-8" : "text/markdown; charset=utf-8", body: text };
+  }
+  const r = resolveRoute(dir, m, p);
+  return json(r.status, r.body);
+}