create-evda 0.1.5 → 0.1.6

package/lib/migrate-people.mjs

@@ -0,0 +1,231 @@
+// Migrate an untyped People doc to a person-profile entry (HQ-1189), by adding frontmatter only.
+//
+// The six rules, each implemented once below:
+//   1. The file is copied to <record root>/.backup/people-migration-<YYYY-MM-DD>/ first.
+//   2. Frontmatter is added and nothing below it changes: kind, id (filename slug), schemaVersion,
+//      name (the H1), observations. A file that already has frontmatter is skipped and reported.
+//   3. One observation per dated H2/H3 heading: text is the heading text, since is its date at the
+//      precision written (day or month). A range uses its start. A year-only heading stays prose.
+//   4. supersededBy only when a heading says it replaces an earlier one AND exactly one earlier
+//      observation fits. Otherwise it stays unlinked and is listed.
+//   5. A quote is attached only when its line names the speaker (`Name: "..."`, `"..." (Name, ...)`
+//      or `"..." -- Name`), only when the section has exactly one such line (an observation holds one
+//      quote), and only when the speaker is the profiled person or the owner, by first or full name.
+//      The owner is provenance owner; the person is provenance person with by naming them.
+//   6. Undated sections stay prose.
+// Before a file is reported done, the bytes after the frontmatter are hashed against the original.
+// A doc with no dated heading is left untouched and reported: a profile needs one observation.
+
+import { createHash } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative } from "node:path";
+import { findRoot, holderOf, readManifest } from "./manifest.mjs";
+import { readEntry } from "./kinds.mjs";
+import { parseYaml, toYaml } from "./yaml.mjs";
+import { carries, frontmatterOf, heldBy, sealedSections, NOTED, SEALED } from "./circles.mjs";
+
+// The lines of a body with every line of a sealed section blanked, so nothing in one becomes an
+// observation, a name or a quote in frontmatter every reader shows (HQ-1414). Line numbers are kept.
+// EVDA_CARRY_FALSIFY=migrate-people:sealed reads sealed sections like any other line.
+function openLines(text) {
+  const lines = text.split("\n");
+  if (!carries("migrate-people", SEALED)) return lines;
+  for (const s of sealedSections(text)) for (let i = s.start; i <= s.end; i++) lines[i] = "";
+  return lines;
+}
+
+const MONTHS = ["january", "february", "march", "april", "may", "june", "july", "august", "september", "october", "november", "december"];
+const MONTH_WORD = "(Jan(?:uary)?|Feb(?:ruary)?|Mar(?:ch)?|Apr(?:il)?|May|June?|July?|Aug(?:ust)?|Sept?(?:ember)?|Oct(?:ober)?|Nov(?:ember)?|Dec(?:ember)?)\\.?";
+const RANGE_SEP = "\\s*(?:-|\\u2013|\\u2014|to|through)\\s*";
+
+const monthNumber = (word) => MONTHS.findIndex((m) => m.startsWith(word.toLowerCase().replace(/\.$/, "").slice(0, 3))) + 1;
+const two = (n) => String(n).padStart(2, "0");
+const sha256 = (buf) => createHash("sha256").update(buf).digest("hex");
+
+function realDay(y, m, d) {
+  const t = new Date(Date.UTC(y, m - 1, d));
+  return t.getUTCFullYear() === y && t.getUTCMonth() === m - 1 && t.getUTCDate() === d;
+}
+
+// The date a heading carries, at the precision written, or null. Returns { since, at, length }.
+export function headingDate(text) {
+  const found = [];
+  const add = (re, make) => {
+    const m = re.exec(text);
+    if (m) { const since = make(m); if (since) found.push({ since, at: m.index, length: m[0].length }); }
+  };
+  add(/\b(\d{4})-(\d{2})-(\d{2})\b/, (m) => (realDay(+m[1], +m[2], +m[3]) ? `${m[1]}-${m[2]}-${m[3]}` : null));
+  add(/\b(\d{4})-(0[1-9]|1[0-2])\b(?!-\d)/, (m) => `${m[1]}-${m[2]}`);
+  add(new RegExp(`\\b${MONTH_WORD}\\s+(\\d{1,2})(?:st|nd|rd|th)?(?:${RANGE_SEP}\\d{1,2}(?:st|nd|rd|th)?)?,?\\s+(\\d{4})\\b`, "i"), (m) => {
+    const mo = monthNumber(m[1]);
+    return realDay(+m[3], mo, +m[2]) ? `${m[3]}-${two(mo)}-${two(+m[2])}` : null;
+  });
+  add(new RegExp(`\\b${MONTH_WORD}${RANGE_SEP}${MONTH_WORD}\\s+(\\d{4})\\b`, "i"), (m) => `${m[3]}-${two(monthNumber(m[1]))}`);
+  add(new RegExp(`\\b${MONTH_WORD}\\s+(\\d{4})\\b`, "i"), (m) => `${m[2]}-${two(monthNumber(m[1]))}`);
+  if (found.length === 0) return null;
+  // Earliest in the heading wins; at the same position the longest (most specific) match wins.
+  found.sort((a, b) => a.at - b.at || b.length - a.length);
+  return found[0];
+}
+
+// Every H2/H3 heading in a body that carries a date: the same definition planProfile uses for "a
+// dated section" (the rule in CLAUDE.md this migration implements). Shared with doctor.mjs's
+// heading-coverage check, so the two can never disagree about what counts as one.
+export function datedHeadings(text) {
+  const out = [];
+  for (const l of openLines(text)) {
+    const m = /^(#{1,3})\s+(.*?)\s*#*\s*$/.exec(l);
+    if (!m || m[1].length === 1) continue;
+    const date = headingDate(m[2]);
+    if (date) out.push({ text: m[2], since: date.since });
+  }
+  return out;
+}
+
+const REPLACES = /\b(?:no longer (?:holds?|true|applies|stands)|replaces|supersedes|superseded|revises|revised|corrects|corrected|correction to|overturns|instead of)\b/i;
+
+export const slug = (s) => s.normalize("NFKD").replace(/[\u0300-\u036f]/g, "").toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "");
+
+// A line that names its speaker and holds exactly one quoted span. Returns { speaker, words } or null.
+const QUOTED = /["\u201c]([^"\u201c\u201d]+)["\u201d]/g;
+export function speakerQuote(line) {
+  const spans = [...line.matchAll(QUOTED)];
+  if (spans.length !== 1) return null;
+  const words = spans[0][1].trim();
+  if (!words) return null;
+  const before = line.slice(0, spans[0].index);
+  const after = line.slice(spans[0].index + spans[0][0].length);
+  const NAME = "([A-Z][A-Za-z'.]*(?: [A-Z][A-Za-z'.]*)?)";
+  let m = new RegExp(`^\\s*(?:>\\s*)?(?:[-*]\\s+)?\\**${NAME}\\**\\s*:\\s*\\**_?\\*?$`).exec(before);
+  if (m) return { speaker: m[1], words };
+  m = new RegExp(`^\\s*\\*?_?\\s*\\(${NAME}(?:,[^)]*)?\\)`).exec(after);
+  if (m) return { speaker: m[1], words };
+  m = new RegExp(`^\\s*\\*?_?\\s*(?:\\u2014|\\u2013|--?)\\s*${NAME}\\b`).exec(after);
+  if (m) return { speaker: m[1], words };
+  return null;
+}
+
+// Plan the frontmatter for one doc. Pure: reads nothing from disk.
+export function planProfile({ fileName, text, owner }) {
+  const notes = [];
+  // A sealed or just-noted file always has frontmatter, so it is skipped here and never rewritten.
+  // EVDA_CARRY_FALSIFY=migrate-people:noted lets a noted one through, as a migration that read past
+  // its frontmatter would, to show this skip is what keeps it noted.
+  const falsifiedNoted = !carries("migrate-people", NOTED) && frontmatterOf(text)?.[NOTED] === true && !heldBy(frontmatterOf(text), "migrate-people");
+  if (/^---\r?\n/.test(text) && !falsifiedNoted) return { skip: "already has frontmatter" };
+  const lines = openLines(text);
+  const h1 = lines.find((l) => /^# \S/.test(l));
+  if (!h1) return { skip: "has no H1 to take the name from" };
+  const name = h1.slice(2).trim();
+  const first = name.split(/\s+/)[0];
+  const ownerFirst = String(owner).split(/\s+/)[0];
+
+  const headings = [];
+  lines.forEach((l, i) => { const m = /^(#{1,3})\s+(.*?)\s*#*\s*$/.exec(l); if (m) headings.push({ line: i, level: m[1].length, text: m[2] }); });
+
+  const observations = [];
+  const ids = new Set();
+  headings.forEach((h, k) => {
+    if (h.level === 1) return;
+    const date = headingDate(h.text);
+    if (!date) return;
+    let id = slug(h.text) || `o${observations.length + 1}`;
+    for (let n = 2; ids.has(id); n++) id = `${slug(h.text)}-${n}`;
+    ids.add(id);
+    const end = k + 1 < headings.length ? headings[k + 1].line : lines.length;
+    const quotes = [];
+    for (let i = h.line + 1; i < end; i++) { const q = speakerQuote(lines[i]); if (q) quotes.push({ ...q, line: i + 1 }); }
+    observations.push({ obs: { id, since: date.since, text: h.text }, heading: h, date, quotes, order: observations.length });
+  });
+
+  // Rule 5.
+  for (const o of observations) {
+    if (o.quotes.length === 0) continue;
+    if (o.quotes.length > 1) { notes.push(`quote not attached: "${o.heading.text}" has ${o.quotes.length} lines naming a speaker (lines ${o.quotes.map((q) => q.line).join(", ")}), and an observation holds one`); continue; }
+    const q = o.quotes[0];
+    const isOwner = q.speaker === owner || q.speaker === ownerFirst;
+    const isPerson = q.speaker === name || q.speaker === first;
+    if (!isOwner && !isPerson) { notes.push(`quote not attached: "${o.heading.text}" line ${q.line} names ${q.speaker}, who is neither ${name} nor the owner`); continue; }
+    const by = isOwner ? owner : name;
+    o.obs.quote = { words: q.words, provenance: isOwner ? "owner" : "person", by };
+  }
+
+  // Ordering: a month sorts as its first day, for ordering only.
+  const key = (s) => (s.length === 7 ? `${s}-01` : s);
+  // Rule 4.
+  for (const o of observations) {
+    const rest = o.heading.text.slice(0, o.date.at) + " " + o.heading.text.slice(o.date.at + o.date.length);
+    if (!REPLACES.test(rest)) continue;
+    const named = MONTHS.map((m, i) => (new RegExp(`\\b${m[0].toUpperCase()}${m.slice(1)}\\b`).test(rest) ? i + 1 : 0)).filter(Boolean);
+    const earlier = observations.filter((e) => e !== o && key(e.obs.since) < key(o.obs.since));
+    const fits = named.length ? earlier.filter((e) => named.includes(Number(e.obs.since.slice(5, 7)))) : earlier;
+    if (fits.length === 1) {
+      if (fits[0].obs.supersededBy) { notes.push(`unlinked: "${o.heading.text}" fits "${fits[0].heading.text}", which is already superseded`); continue; }
+      fits[0].obs.supersededBy = o.obs.id;
+    } else {
+      notes.push(`unlinked: "${o.heading.text}" says it replaces an earlier section, and ${fits.length} fit${fits.length ? `: ${fits.map((f) => `"${f.heading.text}"`).join(", ")}` : ""}`);
+    }
+  }
+
+  if (observations.length === 0) return { skip: "has no dated H2 or H3 heading, so there is no observation; left as prose" };
+
+  observations.sort((a, b) => (key(a.obs.since) < key(b.obs.since) ? -1 : key(a.obs.since) > key(b.obs.since) ? 1 : a.order - b.order));
+  const entry = {
+    kind: "person-profile",
+    id: slug(fileName.replace(/\.md$/i, "")),
+    schemaVersion: "0.1",
+    name,
+    observations: observations.map((o) => o.obs),
+  };
+  const frontmatter = `---\n${toYaml(entry)}---\n`;
+  const problems = readEntry("person-profile", parseYaml(frontmatter.slice(4, -4)), { owner }).problems;
+  return { entry, frontmatter, notes, problems };
+}
+
+// The body below a written frontmatter is the original, byte for byte.
+export function bodyMatches(original, written, frontmatter) {
+  const head = Buffer.from(frontmatter, "utf8");
+  if (!written.subarray(0, head.length).equals(head)) return false;
+  return sha256(written.subarray(head.length)) === sha256(original);
+}
+
+const today = () => { const d = new Date(); return `${d.getFullYear()}-${two(d.getMonth() + 1)}-${two(d.getDate())}`; };
+
+// Migrate files. Returns one result per file: { file, status: done|would|skipped|failed, ... }.
+export function migratePeople(files, { dry = false, date = today(), root = null } = {}) {
+  const results = [];
+  for (const file of files) {
+    const r = { file };
+    results.push(r);
+    if (basename(file) === "README.md") { Object.assign(r, { status: "skipped", why: "is a folder README, not a person profile" }); continue; }
+    const recordRoot = root ?? findRoot(dirname(file));
+    if (!recordRoot) { Object.assign(r, { status: "failed", why: "no evda.json above this file" }); continue; }
+    const owner = (() => { const h = holderOf(readManifest(recordRoot)); return h.id ?? h.name; })();
+    if (!owner) { Object.assign(r, { status: "failed", why: "evda.json names no owner" }); continue; }
+    const original = readFileSync(file);
+    const plan = planProfile({ fileName: basename(file), text: original.toString("utf8"), owner });
+    if (plan.skip) { Object.assign(r, { status: "skipped", why: plan.skip }); continue; }
+    Object.assign(r, { frontmatter: plan.frontmatter, notes: plan.notes, observations: plan.entry.observations.length });
+    if (plan.problems.length) { Object.assign(r, { status: "failed", why: `the frontmatter would not read as a person-profile: ${plan.problems.join("; ")}` }); continue; }
+    const backupDir = join(recordRoot, ".backup", `people-migration-${date}`);
+    r.backup = join(backupDir, basename(file));
+    if (dry) { r.status = "would"; continue; }
+    mkdirSync(backupDir, { recursive: true });
+    if (existsSync(r.backup) && sha256(readFileSync(r.backup)) !== sha256(original)) {
+      Object.assign(r, { status: "failed", why: `a different backup already exists at ${relative(recordRoot, r.backup)}; nothing written` });
+      continue;
+    }
+    copyFileSync(file, r.backup);
+    if (sha256(readFileSync(r.backup)) !== sha256(original)) { Object.assign(r, { status: "failed", why: "the backup does not match the original; nothing written" }); continue; }
+    writeFileSync(file, Buffer.concat([Buffer.from(plan.frontmatter, "utf8"), original]));
+    const written = readFileSync(file);
+    if (!bodyMatches(original, written, plan.frontmatter)) {
+      writeFileSync(file, original);
+      Object.assign(r, { status: "failed", why: "the body below the frontmatter did not hash to the original; restored the original" });
+      continue;
+    }
+    r.bodySha256 = sha256(original);
+    r.status = "done";
+  }
+  return results;
+}

package/lib/organize.mjs

@@ -3,7 +3,10 @@
 // The mechanical part is deterministic and done here:
 //   - each dated capture is copied, verbatim, into the daily file of its date, once. A marker comment
 //     in the daily file records the copy, so a second run files nothing twice and a rebuilt .evda/
-//     cannot make it forget.
+//     cannot make it forget. The copy carries the capture's flags (HQ-1414): a sealed capture is
+//     filed inside a sealed fence, and a just-noted one is not copied at all. Its day gets one
+//     pointer line naming the capture, so the words stay in one file under one flag that
+//     `evda_release_note` clears, and the first run after its owner releases it files the words.
 //   - the report lists what needs a person's judgment: people a recent note mentions whose file has
 //     nothing from that note, imports to check, undated notes, and notes that sit under no role.
 // The report is appended to reports/organize/<date>.md. Nothing is moved, renamed or deleted, and
@@ -16,6 +19,7 @@
 import { appendFileSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { basename, dirname, join, relative } from "node:path";
 import { spawnSync } from "node:child_process";
+import { tmpdir } from "node:os";
 import { resolveRole, resolveAll } from "./roles.mjs";
 import { mdFiles, fileDate } from "./record.mjs";
 import { secretShape } from "./references.mjs";
@@ -23,9 +27,13 @@ import { importsDir, localDate, localTime } from "./tools.mjs";
 import { serverCommand, SKILL_SOURCE } from "./connect.mjs";
 import { SERVER_NAME } from "./clients.mjs";
 import { EvdaError } from "./errors.mjs";
+import { frontmatterOf, heldBy, withoutSealed, SEALED, NOTED } from "./circles.mjs";
 
 export const REPORTS = "reports";
 const marker = (rel) => `<!-- evda:capture ${rel} -->`;
+// The pointer a just-noted capture leaves in its day in place of its words. A different marker, so
+// once the capture is released the next run still files its words.
+const notedMarker = (rel) => `<!-- evda:noted-capture ${rel} -->`;
 const posix = (p) => p.split("\\").join("/");
 
 function stripFrontmatter(text) {
@@ -74,11 +82,21 @@ export function plan(evda, { now = new Date(), window = 7 } = {}) {
       const text = readFileSync(abs, "utf8");
       const date = fileDate(abs, text);
       if (!date) { out.undated.push(rel(abs)); continue; }
+      const held = heldBy(frontmatterOf(text), "organize");
+      const target = join(daily.abs, `${date}.md`);
+      const dayText = existsSync(target) ? readFileSync(target, "utf8") : "";
+      // Just noted: its words are read for nothing, a secret included, and only a pointer is filed.
+      if (held === NOTED) {
+        if (!dayText.includes(marker(rel(abs))) && !dayText.includes(notedMarker(rel(abs)))) out.filings.push({ from: rel(abs), to: rel(target), date, noted: true });
+        continue;
+      }
       const secret = secretLine(text);
       if (secret) { out.refused.push({ path: rel(abs), why: `holds ${secret}; not copied` }); continue; }
-      const target = join(daily.abs, `${date}.md`);
-      if (existsSync(target) && readFileSync(target, "utf8").includes(marker(rel(abs)))) continue;
-      out.filings.push({ from: rel(abs), to: rel(target), date, body: stripFrontmatter(text).replace(/\n+$/, "") });
+      if (dayText.includes(marker(rel(abs)))) continue;
+      // A sealed capture (HQ-1220) is filed inside a sealed fence, heading and marker included, so the
+      // copy in the day is as sealed as the capture and names nothing outside the fence.
+      const sealed = held === SEALED;
+      out.filings.push({ from: rel(abs), to: rel(target), date, body: stripFrontmatter(text).replace(/\n+$/, ""), ...(sealed ? { sealed: true } : {}) });
     }
   }
   for (const abs of mdFiles(daily.abs)) {
@@ -90,7 +108,11 @@ export function plan(evda, { now = new Date(), window = 7 } = {}) {
   if (people.mapped && people.exists) {
     const recent = [...mdFiles(daily.abs), ...(captures.mapped && captures.exists ? mdFiles(captures.abs) : [])]
       .map((abs) => ({ abs, text: readFileSync(abs, "utf8") }))
-      .filter((f) => { const d = fileDate(f.abs, f.text); return d && d >= from; });
+      .filter((f) => { const d = fileDate(f.abs, f.text); return d && d >= from; })
+      // Who a sealed or just-noted note mentions is held back with it: it is not read for people, and
+      // a sealed section is cut before the rest is (HQ-1220, HQ-1414).
+      .filter((f) => !heldBy(frontmatterOf(f.text), "organize"))
+      .map((f) => ({ ...f, text: withoutSealed(f.text).text }));
     for (const p of mdFiles(people.abs)) {
       out.examined += 1;
       const ptext = readFileSync(p, "utf8");
@@ -138,7 +160,7 @@ export function reportText(p, { now = new Date(), window = 7 } = {}) {
   const lines = [`## Run ${localTime(now)}`, ""];
   lines.push(`Examined ${p.examined} note(s). Moved nothing.`, "");
   lines.push("### Filed");
-  if (p.filings.length) for (const f of p.filings) lines.push(`- ${f.from} copied verbatim into ${f.to}`);
+  if (p.filings.length) for (const f of p.filings) lines.push(f.sealed ? `- a sealed capture copied verbatim into ${f.to}, still sealed` : f.noted ? `- ${f.from} is just noted: ${f.to} points to it, and its words stay where they are until its owner releases it` : `- ${f.from} copied verbatim into ${f.to}`);
   else lines.push("- Nothing new to file.");
   lines.push("", `### People mentioned in the last ${window} days`);
   if (p.people.length) for (const x of p.people) lines.push(`- ${x.note} mentions ${x.name}; ${x.person} has nothing from it yet.`);
@@ -163,16 +185,24 @@ function appendReport(evda, kind, date, block) {
 }
 
 // Run the owner's claude -p with the skill and read-only EVDA tools. Returns { ok, text, why }.
+// With `evda` null (a gather, which has no record yet) it gets no EVDA tools and runs from the
+// system's temporary directory, so it reads nothing but the prompt.
 export function askOwnersAi(evda, prompt, { model = null, env = process.env, timeoutMs = 600_000 } = {}) {
   const bin = env.EVDA_CLAUDE || "claude";
-  const { command, args } = serverCommand(evda.dir);
-  const mcp = JSON.stringify({ mcpServers: { [SERVER_NAME]: { type: "stdio", command, args } } });
-  const allowed = ["evda_operating_layer", "evda_recent", "evda_search", "evda_circles"].map((t) => `mcp__${SERVER_NAME}__${t}`);
+  const argv = ["-p", prompt];
+  if (evda) {
+    const { command, args } = serverCommand(evda.dir);
+    const mcp = JSON.stringify({ mcpServers: { [SERVER_NAME]: { type: "stdio", command, args } } });
+    const allowed = ["evda_operating_layer", "evda_recent", "evda_search", "evda_circles"].map((t) => `mcp__${SERVER_NAME}__${t}`);
+    argv.push("--mcp-config", mcp, "--strict-mcp-config", "--allowedTools", allowed.join(","));
+  } else {
+    argv.push("--strict-mcp-config", "--mcp-config", JSON.stringify({ mcpServers: {} }), "--allowedTools", "");
+  }
+  argv.push("--output-format", "text");
   const skill = existsSync(SKILL_SOURCE) ? readFileSync(SKILL_SOURCE, "utf8") : "";
-  const argv = ["-p", prompt, "--mcp-config", mcp, "--strict-mcp-config", "--allowedTools", allowed.join(","), "--output-format", "text"];
   if (skill) argv.push("--append-system-prompt", skill);
   if (model) argv.push("--model", model);
-  const r = spawnSync(bin, argv, { cwd: evda.dir, env, encoding: "utf8", timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
+  const r = spawnSync(bin, argv, { cwd: evda ? evda.dir : tmpdir(), env, encoding: "utf8", timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
   if (r.error) return { ok: false, why: r.error.code === "ENOENT" ? `${bin} is not installed or not on PATH` : String(r.error.message) };
   if (r.status !== 0) return { ok: false, why: `${bin} -p exited ${r.status}: ${(r.stderr || r.stdout || "").trim().split("\n").slice(-3).join(" ")}` };
   const text = (r.stdout ?? "").trim();
@@ -190,7 +220,17 @@ export async function organize(evda, { now = new Date(), window = 7, withAi = fa
     const abs = join(evda.dir, f.to);
     const head = existsSync(abs) ? "" : `# ${f.date}\n`;
     const lead = existsSync(abs) && !readFileSync(abs, "utf8").endsWith("\n") ? "\n" : "";
-    appendFileSync(abs, `${lead}${head}\n## Capture: ${basename(f.from, ".md")}\n\n${marker(f.from)}\n\n${f.body}\n`);
+    if (f.noted) {
+      appendFileSync(abs, `${lead}${head}\n## Capture: ${basename(f.from, ".md")}\n\n${notedMarker(f.from)}\n\nJust noted, so its words stay in ${f.from}, read by no AI. Once its owner releases it, the next organize files them here.\n`);
+      continue;
+    }
+    const block = `## Capture: ${basename(f.from, ".md")}\n\n${marker(f.from)}\n\n${f.body}\n`;
+    if (f.sealed) {
+      // A fence longer than any backtick run at the start of a line in the block, so nothing in it closes it.
+      const longest = Math.max(2, ...block.split("\n").map((l) => /^ {0,3}(`+)/.exec(l)?.[1].length ?? 0));
+      const fence = "`".repeat(longest + 1);
+      appendFileSync(abs, `${lead}${head}\n${fence}sealed\n${block}${fence}\n`);
+    } else appendFileSync(abs, `${lead}${head}\n${block}`);
   }
   let exit = 0;
   if (withAi) {

package/lib/parity.mjs

@@ -0,0 +1,111 @@
+// Shadow parity (Spec 08, stage S1): the shadow a device folds received Changes into must equal the
+// record it shadows, byte for byte, for exactly the circles that device holds, and must hold nothing
+// of a circle it may never hold.
+//
+// The gate to S2 is this check holding every night for a week, so it is written to fail:
+//
+//   MISSING      a file of a held circle is in the record and not in the shadow
+//   EXTRA        a file is in the shadow and not in the record (a rename is one MISSING and one EXTRA)
+//   DIFFERS      the same path, different bytes (sha256)
+//   FORBIDDEN    the shadow holds a file of a circle this device must never hold
+//   UNCOVERED    the shadow holds a file no circle covers
+//   UNVERIFIABLE a file of a held circle is a symlink, an iCloud stub, or over the blob lane, so the
+//                record side has no bytes the shadow could be compared with
+//   CHECKED 0    nothing was compared, which is a broken discovery step and never a pass
+//
+// Two things are not differences, and each is counted rather than dropped:
+//
+//   a name stored in another Unicode form   paths are compared in NFC. iCloud delivered 23 of the
+//                                          vault's Greek and accented names to Hestia in the other
+//                                          form (measured 2026-09-22); the bytes are the same file,
+//                                          and APFS opens either spelling.
+//   a path iCloud never carries             a component ending in .tmp or .nosync. During S1 the
+//                                          record on the shadow device arrived by iCloud, so the
+//                                          laptop's .tmp/ (65 files, never on Hestia) reaches the
+//                                          shadow by the relay and could never match. NOT_CARRIED n.
+//
+// It reads both trees and writes nothing.
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { circleForPath } from "./filechanges.mjs";
+import { excluder, walk } from "./sync-rules.mjs";
+
+const nfc = (rel) => rel.normalize("NFC");
+// A path iCloud Drive does not sync, so it cannot be compared across devices while iCloud carries
+// the record. Exported for the test.
+export const notCarried = (rel) => rel.split("/").some((p) => p.endsWith(".tmp") || p.endsWith(".nosync"));
+
+const sha = (abs) => createHash("sha256").update(readFileSync(abs)).digest("hex");
+
+function circleOf(index, rel) {
+  try {
+    return circleForPath(index, rel);
+  } catch {
+    return undefined;
+  }
+}
+
+// `index` is circleIndex(evda). `holds` and `never` are circle names. `exclude` is the plan's
+// excluder, the same one the scan used.
+export function parity({ source, shadow, index, holds, never = [], exclude = excluder() }) {
+  const held = new Set(holds);
+  const forbidden = new Set(never);
+  const problems = [];
+  const perCircle = Object.fromEntries(holds.map((n) => [n, 0]));
+  const expected = new Map();
+  let notHeld = 0;
+  let excluded = 0;
+  let notCarriedCount = 0;
+
+  for (const e of walk(source, { exclude })) {
+    if (e.kind === "excluded") { excluded += 1; continue; }
+    if (notCarried(e.rel)) { notCarriedCount += 1; continue; }
+    const c = circleOf(index, e.rel);
+    if (!c || !held.has(c.name)) { notHeld += 1; continue; }
+    if (e.kind !== "file") {
+      problems.push({ code: "UNVERIFIABLE", rel: e.rel, circle: c.name, why: `a ${e.kind} on the record side` });
+      continue;
+    }
+    expected.set(nfc(e.rel), { rel: e.rel, circle: c.name, sha: sha(join(source, e.rel)) });
+  }
+
+  const seen = new Set();
+  let shadowFiles = 0;
+  for (const e of walk(shadow, { exclude: excluder() })) {
+    if (e.kind === "excluded") continue;
+    if (notCarried(e.rel)) { notCarriedCount += 1; continue; }
+    shadowFiles += 1;
+    const c = circleOf(index, e.rel);
+    if (c && forbidden.has(c.name)) { problems.push({ code: "FORBIDDEN", rel: e.rel, circle: c.name, why: `this device must never hold circle ${c.name}` }); continue; }
+    if (!c) { problems.push({ code: "UNCOVERED", rel: e.rel, why: "in the shadow and in no circle" }); continue; }
+    const want = expected.get(nfc(e.rel));
+    if (!want) { problems.push({ code: "EXTRA", rel: e.rel, circle: c.name, why: "in the shadow and not in the record" }); continue; }
+    seen.add(nfc(e.rel));
+    if (e.kind !== "file" || sha(join(shadow, e.rel)) !== want.sha) {
+      problems.push({ code: "DIFFERS", rel: e.rel, circle: c.name, why: "the shadow's bytes are not the record's" });
+      continue;
+    }
+    perCircle[want.circle] += 1;
+  }
+  for (const [key, want] of expected) {
+    if (!seen.has(key)) problems.push({ code: "MISSING", rel: want.rel, circle: want.circle, why: "in the record and not in the shadow" });
+  }
+
+  const checked = Object.values(perCircle).reduce((a, b) => a + b, 0);
+  if (checked === 0) problems.push({ code: "CHECKED_0", rel: "", why: "nothing was compared; zero is a broken discovery step, not a pass" });
+  return { ok: problems.length === 0, checked, perCircle, expected: expected.size, shadowFiles, notHeld, excluded, notCarried: notCarriedCount, problems };
+}
+
+// The lines a person or a log reads. The first line always says what was examined.
+export function formatParity(r, { limit = 20 } = {}) {
+  const lines = [`CHECKED ${r.checked} files: ${Object.entries(r.perCircle).map(([n, k]) => `${n} ${k}`).join(", ")}`];
+  lines.push(`  record side: ${r.expected} expected, ${r.notHeld} in circles this device does not hold, ${r.excluded} excluded${r.notCarried ? `, NOT_CARRIED ${r.notCarried} (paths iCloud does not sync, both sides)` : ""}; shadow side: ${r.shadowFiles} files`);
+  const byCode = {};
+  for (const p of r.problems) byCode[p.code] = (byCode[p.code] ?? 0) + 1;
+  for (const p of r.problems.slice(0, limit)) lines.push(`FAIL ${p.code} ${p.rel}${p.circle ? ` [${p.circle}]` : ""}: ${p.why}`);
+  if (r.problems.length > limit) lines.push(`... and ${r.problems.length - limit} more`);
+  lines.push(r.ok ? "PARITY OK" : `PARITY FAILED: ${Object.entries(byCode).map(([c, n]) => `${c} ${n}`).join(", ")}`);
+  return lines;
+}

package/lib/presets.mjs

@@ -7,9 +7,17 @@
 //     "for": "One sentence: who it suits.",
 //     "folders": [{ "path": "People", "type": "person", "connectors": ["contacts"], "note": "One file per person." }],
 //     "circles": [{ "name": "family", "public": false, "description": "...", "members": { "people": { "path": "People" } } }],
-//     "routines": ["weekly"]
+//     "routines": ["weekly"],
+//     "mapping": { "journal": "Journal", "collections": "People" }
 //   }
 //
+// `mapping` is what the preset declares for the four roles (Spec 07 section 2, HQ-1371): each key
+// a role or a `<role>/<facet>`, each value a folder the preset makes. Every folder the preset makes
+// fills a role, by lying at or under one of these paths; a folder that fills none is refused, so
+// no preset ships a folder an agent cannot say the purpose of. Applying writes the role paths the
+// record does not have into its evda.json and never replaces a key it has: when the key is taken,
+// the folder fills the same role under a facet key named for it (`collections/people`).
+//
 // `folders` are paths relative to the record root. A folder with a `type` gets folder.evda.json
 // (type, connectors, views), checked by the same validator doctor uses; a folder with no type is a
 // plain directory and nothing more. `circles` are starter circles, in the substrate's eco shape with
@@ -26,8 +34,8 @@
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
-import { openEvda } from "./manifest.mjs";
-import { resolveRole } from "./roles.mjs";
+import { openEvda, readManifest, writeManifest } from "./manifest.mjs";
+import { resolveRole, fourRoleOf, FOUR_ROLES, LEGACY_FACETS } from "./roles.mjs";
 import { validateFolderManifest, FOLDER_MANIFEST, FOLDER_TYPES } from "./folders.mjs";
 import { ROUTINE_KEYS } from "./routines.mjs";
 import { onlyKeys, proposeCircle, refuse, PROPOSALS } from "./tools.mjs";
@@ -35,7 +43,7 @@ import { EvdaError } from "./errors.mjs";
 
 export const PRESETS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "presets");
 export const PRESET_FILE = "preset.json";
-export const PRESET_KEYS = ["id", "title", "for", "folders", "circles", "routines"];
+export const PRESET_KEYS = ["id", "title", "for", "folders", "circles", "routines", "mapping"];
 export const PRESET_FOLDER_KEYS = ["path", "type", "connectors", "views", "note"];
 export const PRESET_CIRCLE_KEYS = ["name", "public", "description", "members"];
 export const NONE = "none";
@@ -98,6 +106,24 @@ export function validatePreset(p, dirName = null) {
       }
     });
   }
+  // The four roles. Required: a preset is a way to fill them.
+  if (!isObject(p.mapping) || Object.keys(p.mapping).length === 0) fail(`"mapping" must name the folders that fill the four roles (${FOUR_ROLES.join(", ")}).`);
+  else {
+    const rolePaths = [];
+    for (const [key, rel] of Object.entries(p.mapping)) {
+      const role = fourRoleOf(key);
+      if (!role || LEGACY_FACETS[key]) { fail(`mapping key "${key}" is not one of the four roles or a <role>/<facet> of one.`); continue; }
+      if (!nonEmpty(rel) || !paths.has(rel)) { fail(`mapping "${key}" is ${JSON.stringify(rel)}, which is not a folder this preset makes.`); continue; }
+      rolePaths.push({ role, rel });
+    }
+    const missing = FOUR_ROLES.filter((r) => !rolePaths.some((x) => x.role === r));
+    if (missing.length) fail(`fills no folder for ${missing.join(", ")}. Every record has the four roles.`);
+    for (const fp of paths) {
+      if (!rolePaths.some((x) => fp === x.rel || fp.startsWith(`${x.rel}/`))) fail(`folder ${fp} fills no role: it is not at or under any path in "mapping".`);
+    }
+    const seen = new Map();
+    for (const x of rolePaths) { if (seen.has(x.rel) && seen.get(x.rel) !== x.role) fail(`folder ${x.rel} fills two roles.`); seen.set(x.rel, x.role); }
+  }
   if (p.circles !== undefined) {
     if (!Array.isArray(p.circles)) fail(`"circles" must be a list.`);
     else {
@@ -205,7 +231,23 @@ const viewHeader = (v) => ["---", `view: ${v.view}`, `of: ${v.of}`, `in: ${v.in}
 export function applyPreset(root, id, { dry = false, now = new Date(), dir = PRESETS_DIR } = {}) {
   const evda = openEvda(resolve(root));
   const preset = loadPreset(id, { dir });
-  const plan = { id: preset.id, title: preset.title, root: evda.dir, dry, create: [], write: [], views: [], matched: [], conflicts: [], circles: [], proposed: [], routines: preset.routines ?? [], folders: preset.folders.length };
+  const plan = { id: preset.id, title: preset.title, root: evda.dir, dry, create: [], write: [], views: [], matched: [], conflicts: [], circles: [], proposed: [], routines: preset.routines ?? [], folders: preset.folders.length, roles: [] };
+  // The four roles the record does not declare yet. A key it has with another path is a conflict,
+  // left as it is; a path it already maps under a key of the same role is already there.
+  const has = evda.manifest.mapping;
+  for (const [key, rel] of Object.entries(preset.mapping ?? {})) {
+    if (has[key] === rel) continue;
+    if (Object.entries(has).some(([k, v]) => v === rel && fourRoleOf(k) === fourRoleOf(key))) continue;
+    // A key the record already uses for another path keeps it; the preset's folder fills the same
+    // role under a facet key named for the folder, so two presets compose and nothing is replaced.
+    let k = key;
+    if (has[k] !== undefined || plan.roles.some((r) => r.key === k)) {
+      const slug = rel.split("/").pop().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "folder";
+      k = `${fourRoleOf(key)}/${slug}`;
+      for (let n = 2; has[k] !== undefined || plan.roles.some((r) => r.key === k); n++) k = `${fourRoleOf(key)}/${slug}-${n}`;
+    }
+    plan.roles.push({ key: k, rel });
+  }
   const blocked = new Set();
   for (const f of preset.folders) {
     const abs = resolve(evda.dir, f.path);
@@ -234,6 +276,8 @@ export function applyPreset(root, id, { dry = false, now = new Date(), dir = PRE
       if (!existsSync(resolve(evda.dir, v.path))) plan.views.push({ path: v.path, view: v });
     }
   }
+  // A role is declared only over a folder this apply leaves in place; one a file blocks is not.
+  plan.roles = plan.roles.filter((r) => blockedBy(evda.dir, r.rel) === null);
   const circlesRole = resolveRole(evda, "circles");
   const proposals = join(evda.dir, PROPOSALS);
   const proposalNames = existsSync(proposals) ? readdirSync(proposals) : [];
@@ -244,6 +288,11 @@ export function applyPreset(root, id, { dry = false, now = new Date(), dir = PRE
   }
   if (dry) return plan;
 
+  if (plan.roles.length) {
+    const m = readManifest(evda.dir);
+    for (const r of plan.roles) m.mapping[r.key] ??= r.rel;
+    writeManifest(evda.dir, m);
+  }
   for (const rel of plan.create) mkdirSync(join(evda.dir, rel), { recursive: true });
   for (const w of plan.write) writeFileSync(join(evda.dir, w.path), JSON.stringify(w.manifest, null, 2) + "\n", { flag: "wx" });
   for (const v of plan.views) {
@@ -268,17 +317,18 @@ export function diffPreset(root, id, opts = {}) {
   return applyPreset(root, id, { ...opts, dry: true });
 }
 
-export const planIsEmpty = (plan) => !plan.create.length && !plan.write.length && !plan.views.length && !plan.circles.length && !plan.conflicts.length;
+export const planIsEmpty = (plan) => !plan.create.length && !plan.write.length && !plan.views.length && !plan.circles.length && !plan.conflicts.length && !(plan.roles ?? []).length;
 
 // The plan in plain words, for the owner to say yes or no to. Names each folder by its note.
 export function summary(plan, preset = loadPreset(plan.id)) {
   const lines = [];
   const adds = preset.folders.filter((f) => plan.create.includes(f.path) || plan.write.some((w) => w.folder.path === f.path));
-  if (!adds.length && !plan.circles.length && !plan.conflicts.length) {
+  if (!adds.length && !plan.circles.length && !plan.conflicts.length && !(plan.roles ?? []).length) {
     lines.push(`This record already has everything the ${plan.title} preset makes. Nothing would be written.`);
   } else {
     lines.push(`The ${plan.title} preset would add ${adds.length} folder(s) to this record:`);
     for (const f of adds) lines.push(`- ${f.path}/${f.type ? ` (${f.type})` : ""}${f.note ? `: ${f.note}` : ""}`);
+    if (plan.roles?.length) lines.push(`It would declare ${plan.roles.length} role path(s) in evda.json: ${plan.roles.map((r) => `${r.key} -> ${r.rel}`).join(", ")}.`);
     if (plan.circles.length) lines.push(`It would propose ${plan.circles.length} circle(s), as proposal files only: ${plan.circles.map((c) => c.name).join(", ")}.`);
     if (plan.matched.length) lines.push(`${plan.matched.length} folder(s) are already set up the same way and would be left alone.`);
     for (const c of plan.conflicts) lines.push(`Left as it is: ${c.path} ${c.why}.`);
@@ -294,6 +344,7 @@ export function planLines(plan, { diff = false } = {}) {
   const verb = plan.dry || diff ? "would" : "did";
   for (const p of plan.create) out.push(`  ${verb === "did" ? "created " : "create  "} ${p}/`);
   for (const w of plan.write) out.push(`  ${verb === "did" ? "wrote   " : "write   "} ${w.path}  type ${w.manifest.type}${w.manifest.connectors.length ? `, connectors ${w.manifest.connectors.join(", ")}` : ""}`);
+  for (const r of plan.roles ?? []) out.push(`  ${verb === "did" ? "declared" : "declare "} ${r.key} -> ${r.rel}  in evda.json`);
   for (const v of plan.views) out.push(`  ${verb === "did" ? "wrote   " : "write   "} ${v.path}  view ${v.view.view} (header only)`);
   if (!diff) for (const m of plan.matched) out.push(`  skipped  ${m.path}  already says the same`);
   for (const c of plan.conflicts) out.push(`  CONFLICT ${c.path}  ${c.why}. Left as it is.`);