create-evda 0.1.5 → 0.1.7

package/lib/organize.mjs

@@ -3,19 +3,25 @@
 // 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
 // nothing is written into circles/ or grants/.
 //
 // The judgment part runs through the owner's own AI (`--with-ai`): `claude -p` with the evda skill
-// and read-only EVDA tools, given the report. Its answer is appended to the same report. EVDA holds
+// and read-only EVDA tools, given the last two weeks of entries. It hands back one thread across
+// days, quoted and dated, which leads the report; an answer whose quotes are not in the entries is
+// dropped, and with nothing across two days the report says nothing (HQ-1246). EVDA holds
 // no key and calls no model; `claude` is the owner's install, signed in as the owner.
 
 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 +29,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 +84,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 +110,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 +162,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,21 +187,131 @@ 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 });
-  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();
-  if (!text) return { ok: false, why: `${bin} -p answered with nothing` };
-  return { ok: true, text };
+  const r = spawnSync(bin, argv, { cwd: evda ? evda.dir : tmpdir(), env, encoding: "utf8", timeout: timeoutMs, maxBuffer: 16 * 1024 * 1024 });
+  const text = r.error || r.status !== 0 ? "" : (r.stdout ?? "").trim();
+  if (text) return { ok: true, text };
+  return { ok: false, why: aiFailure(r, { bin, env }) };
+}
+
+// Why the owner's AI did not answer, in words the owner can act on (HQ-1246). The report is read by
+// a person, not a developer, so it never says "claude -p exited 1". Claude's own last line follows
+// the plain sentence when it is the only clue. EVDA_ROUTINES_FALSIFY=raw-why gives the old text.
+export function aiFailure(r, { bin = "claude", env = process.env } = {}) {
+  const said = `${r.stderr ?? ""}\n${r.stdout ?? ""}`.trim().split("\n").map((l) => l.trim()).filter(Boolean);
+  if ((env.EVDA_ROUTINES_FALSIFY ?? "").split(",").map((m) => m.trim()).includes("raw-why")) {
+    if (r.error) return r.error.code === "ENOENT" ? `${bin} is not installed or not on PATH` : String(r.error.message);
+    return r.status !== 0 ? `${bin} -p exited ${r.status}: ${said.slice(-3).join(" ")}` : `${bin} -p answered with nothing`;
+  }
+  if (r.error?.code === "ENOENT") return "Claude Code is not on this computer. Install it from https://claude.com/claude-code, open it once and sign in, and the next run includes your AI's read.";
+  if (r.error?.code === "ETIMEDOUT" || r.signal === "SIGTERM") return "Claude took too long and was stopped. The next run tries again.";
+  if (r.error) return `Claude could not be started on this computer. The next run tries again. What the computer said: ${r.error.message}`;
+  if (said.some((l) => /not logged in|please run \/login|invalid api key|oauth token (has )?expired|authentication[_ ]error|\b401\b/i.test(l))) return "Claude is not signed in on this computer: open Claude and sign in, and the next run includes your AI's read.";
+  if (r.status === 0) return "Claude answered with nothing. The next run tries again.";
+  return `Claude stopped with an error before answering. The next run tries again.${said.length ? ` What it said: ${said.at(-1)}` : ""}`;
+}
+
+// How far back the AI part reads for a thread.
+export const PATTERN_DAYS = 14;
+export const NO_PATTERN = "NOTHING";
+
+// The owner's own words, one per dated daily entry in the last `days` days, as the AI part reads
+// them: a sealed or just-noted day is left out, a sealed section is cut, and evda's markers and any
+// secret-shaped line are dropped. Oldest first.
+export function entriesFor(evda, { now = new Date(), days = PATTERN_DAYS } = {}) {
+  const daily = resolveRole(evda, "record/daily");
+  if (!daily.mapped || !daily.exists) return [];
+  const start = new Date(now);
+  start.setDate(start.getDate() - (days - 1));
+  const from = localDate(start);
+  const to = localDate(now);
+  const out = [];
+  for (const abs of mdFiles(daily.abs)) {
+    const raw = readFileSync(abs, "utf8");
+    const date = fileDate(abs, raw);
+    if (!date || date < from || date > to) continue;
+    if (heldBy(frontmatterOf(raw), "organize")) continue;
+    const text = stripFrontmatter(withoutSealed(raw).text)
+      .split("\n")
+      .filter((l) => !/^<!-- evda:/.test(l.trim()) && !/^#{1,6} /.test(l) && !secretShape(l))
+      .join("\n").replace(/\n{3,}/g, "\n\n").trim();
+    if (text) out.push({ date, text });
+  }
+  return out.sort((a, b) => a.date.localeCompare(b.date));
+}
+
+// The prompt for the AI part. It carries the mechanism the answer rests on, the exact shape the
+// answer must take, and the entries themselves.
+export function patternPrompt(entries) {
+  return [
+    "Below are the owner's own entries from the last two weeks, each under its date.",
+    "",
+    "Find one thing that comes back across different days: a person, a question, a worry, a want, a phrase they keep using.",
+    "Why it is worth their reading: a conclusion handed to someone from outside tends not to take, and one they recognize in their own words does. So hand back their words, not your reading of them.",
+    "",
+    "Answer in exactly this shape:",
+    "one or two plain sentences naming what comes back, in their vocabulary",
+    "- YYYY-MM-DD: \"words copied exactly from that day's entry\"",
+    "- YYYY-MM-DD: \"words copied exactly from another day's entry\"",
+    "",
+    "Quote at least two different days. Copy each quote character for character from the entry under that date; a quote that is not there is dropped, and so is the whole answer.",
+    "Say only what the entries say. No advice, no question back to them, no score, no count, no praise, and no words like journey, transformation or growth.",
+    "Do not mention filing, organizing, this report or yourself.",
+    `If nothing honestly comes back across two or more days, answer with the single word ${NO_PATTERN}.`,
+    "",
+    ...entries.flatMap((e) => [`=== ${e.date} ===`, e.text, ""]),
+  ].join("\n");
+}
+
+const squash = (t) => t.replace(/[\u2018\u2019]/g, "'").replace(/[\u201c\u201d]/g, '"').replace(/\s+/g, " ").trim().toLowerCase();
+
+// The answer, kept only when it has the shape: prose first, then two or more quotes from two or more
+// dates, each found in the entry of its date. Returns { prose, quotes } or null (say nothing).
+// EVDA_ROUTINES_FALSIFY=no-quote-check keeps whatever came back.
+export function patternFrom(text, entries, { env = process.env } = {}) {
+  const t = String(text ?? "").trim();
+  if ((env.EVDA_ROUTINES_FALSIFY ?? "").split(",").map((m) => m.trim()).includes("no-quote-check")) return t ? { prose: t, quotes: [] } : null;
+  if (!t || t.replace(/[.\s]/g, "").toUpperCase() === NO_PATTERN) return null;
+  const lines = t.split("\n").map((l) => l.trim()).filter(Boolean);
+  const quoteRe = /^[-*] (\d{4}-\d{2}-\d{2}): ["\u201c](.+)["\u201d]$/;
+  const first = lines.findIndex((l) => quoteRe.test(l));
+  if (first < 1) return null;
+  const prose = lines.slice(0, first);
+  const rest = lines.slice(first);
+  if (prose.length > 3 || rest.some((l) => !quoteRe.test(l))) return null;
+  const byDate = new Map(entries.map((e) => [e.date, squash(e.text)]));
+  const quotes = [];
+  for (const l of rest) {
+    const [, date, words] = quoteRe.exec(l);
+    const q = squash(words);
+    if (q.length < 3 || !byDate.has(date) || !byDate.get(date).includes(q)) return null;
+    quotes.push({ date, words });
+  }
+  if (new Set(quotes.map((q) => q.date)).size < 2) return null;
+  return { prose: prose.join(" "), quotes };
+}
+
+// The pattern leads the run's section, before the filing list.
+export function withPattern(report, { prose, quotes }) {
+  const block = ["### Across your entries", "", prose, "", ...quotes.map((q) => `- ${q.date}: "${q.words}"`), ""].join("\n");
+  const at = report.indexOf("\n", report.indexOf("## Run")) + 1;
+  return `${report.slice(0, at)}\n${block}${report.slice(at)}`;
 }
 
 export async function organize(evda, { now = new Date(), window = 7, withAi = false, dryRun = false, model = null, env = process.env } = {}) {
@@ -190,23 +324,33 @@ 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) {
-    const ai = askOwnersAi(evda, [
-      "Use the evda skill's Organizing section. Here is today's organize report for this record.",
-      "For each note that needs a place, answer in one line: the note's path, where it belongs, and the words from the note that say so, quoted.",
-      "Check against the record with the evda tools first. Write nothing. If nothing needs a place, say so in one line.",
-      "",
-      report,
-    ].join("\n"), { model, env });
-    if (ai.ok) {
-      const secret = secretLine(ai.text);
-      report += secret ? `\n### Your AI's read\n\nNot kept: the answer held ${secret}.\n` : `\n### Your AI's read (claude -p)\n\n${ai.text}\n`;
-    } else {
-      report += `\n### Your AI's read\n\nSKIPPED: ${ai.why}. Nothing else in this run depended on it.\n`;
-      exit = 1;
+    // The AI part hands back a thread across the owner's own entries, not a log of the filing above
+    // (HQ-1246). Its answer is kept only if every quote is in the entry of the date it names and the
+    // quotes span two days or more; otherwise the report says nothing about it.
+    const entries = entriesFor(evda, { now, days: PATTERN_DAYS });
+    if (entries.length) {
+      const ai = askOwnersAi(evda, patternPrompt(entries), { model, env });
+      if (ai.ok) {
+        const pattern = secretLine(ai.text) ? null : patternFrom(ai.text, entries, { env });
+        if (pattern) report = withPattern(report, pattern);
+      } else {
+        report += `\n### Your AI's read\n\nDid not run. ${ai.why}\n\nThe filing above ran without it.\n`;
+        exit = 1;
+      }
     }
   }
   const path = appendReport(evda, "organize", date, report);
@@ -218,7 +362,7 @@ export async function lookBack(evda, { now = new Date(), model = null, env = pro
   const date = localDate(now);
   const block = ai.ok
     ? (secretLine(ai.text) ? `## Run ${localTime(now)}\n\nNot kept: the answer held a secret-shaped line.\n` : `## Run ${localTime(now)}\n\n${ai.text}\n`)
-    : `## Run ${localTime(now)}\n\nSKIPPED: ${ai.why}.\n`;
+    : `## Run ${localTime(now)}\n\nDid not run. ${ai.why}\n`;
   const path = appendReport(evda, "look-back", date, block);
   return { path, exit: ai.ok ? 0 : 1, summary: `${block}\nAppended to ${path}.` };
 }

package/lib/parity.mjs

@@ -0,0 +1,184 @@
+// 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.
+//
+// And one thing is not yet a difference, while the source is being heard from:
+//
+//   LAG          the record's copy on this device changed after the newest Change this device has
+//                received from the source (`settled`). During S1 the shadow is fed only by the
+//                source (the laptop) and the record here arrives by iCloud, so bytes the shadow
+//                device's own passes write reach the shadow only after iCloud carries them to the
+//                source and its next scan mints them. The source cannot have sent what it had not
+//                seen. Applies to DIFFERS and MISSING, never to EXTRA or FORBIDDEN, and each LAG
+//                file is named. Measured 2026-09-25: the Hestia daily record and the journal,
+//                written on Hestia at 02:10 ET, differed at 03:35 because the laptop's last Change
+//                had arrived at 05:35Z and the laptop was off the network from 06:57Z.
+//   STALE        a LAG file when the source's newest Change is older than `staleAfterMs` (24 h)
+//                at the run. A source that has not been heard from is not lagging, it is absent,
+//                and a week of LAG must not pass the gate. A failure.
+//
+//   LAG, per path  `settled` is the newest Change from the source for ANY file. A short wake of the
+//                source (a 21 s DarkWake on battery, 2026-09-27) can scan before iCloud has
+//                delivered a file's final bytes to it, mint a Change for some other file, and so
+//                move `settled` past a file whose bytes the source never saw. So when the source
+//                has sent a Change for this path (`pathSettled`, keyed by NFC path), the line is
+//                that path's newest Change, not the global one: a file written after the source
+//                last sent THIS path is LAG. Measured 2026-09-27 on Hestia: the two DIFFERS files'
+//                newest Changes were 06:20:41Z, their record mtime 06:48:41Z, the global newest
+//                Change 06:53:08Z. A path the source never sent keeps the global line.
+//                The per-path excuse is bounded: once the source's newest Change is more than
+//                `staleAfterMs` past the file's mtime, the source has been scanning (the laptop's
+//                daily full pass reads every file) and still has not sent it, so it fails as what
+//                it is, DIFFERS or MISSING.
+//
+// Without `settled` (the `evda parity` command) nothing is LAG: parity is byte for byte.
+// A clock skew between the two machines moves the line by the skew; a stamp-preserving edit made
+// before `settled` stays DIFFERS, which is the strict direction.
+//
+// It reads both trees and writes nothing.
+
+import { createHash } from "node:crypto";
+import { readFileSync, statSync } 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 const STALE_AFTER_MS = 24 * 60 * 60 * 1000;
+
+const finite = (n) => typeof n === "number" && Number.isFinite(n);
+
+// The rule for one DIFFERS or MISSING record file, pure so it can be property-tested:
+//   "FAIL"   it is the difference it looks like
+//   "LAG"    the source had not seen these bytes when it last sent this path (or anything, when it
+//            never sent this path), and the source was heard from within `staleAfterMs`
+//   "STALE"  it would be LAG, but the source has been silent for longer than `staleAfterMs`
+//   "BOUND"  it would be LAG by its path's mark, but the source has sent other Changes for longer
+//            than `staleAfterMs` since the file was written, so it is a difference after all
+export function lateVerdict({ mtimeMs, settled, pathSettled, now, staleAfterMs = STALE_AFTER_MS }) {
+  if (!finite(settled)) return "FAIL";
+  const line = finite(pathSettled) ? pathSettled : settled;
+  if (!(mtimeMs > line)) return "FAIL";
+  if (now - settled > staleAfterMs) return "STALE";
+  if (settled - mtimeMs > staleAfterMs) return "BOUND";
+  return "LAG";
+}
+
+export function parity({ source, shadow, index, holds, never = [], exclude = excluder(), settled, pathSettled, staleAfterMs = STALE_AFTER_MS, now = Date.now() }) {
+  const marked = finite(settled);
+  const lag = [];
+  const hours = Math.round(staleAfterMs / 3600000);
+  // Keyed by NFC here, whatever form the caller's change_log holds the names in.
+  const marks = new Map([...(pathSettled ?? [])].map(([rel, t]) => [nfc(rel), t]));
+  // A DIFFERS or MISSING on a record file written after the source last sent it: LAG, or STALE.
+  const late = (want, code, why) => {
+    const mark = marked ? marks.get(nfc(want.rel)) : undefined;
+    const v = lateVerdict({ mtimeMs: want.mtimeMs, settled, pathSettled: mark, now, staleAfterMs });
+    if (v === "LAG") { lag.push({ rel: want.rel, circle: want.circle, was: code }); return; }
+    if (v === "STALE") { problems.push({ code: "STALE", rel: want.rel, circle: want.circle, why: `${why}, written after the source's newest Change of ${new Date(settled).toISOString()}, which is older than ${hours} h` }); return; }
+    if (v === "BOUND") { problems.push({ code, rel: want.rel, circle: want.circle, why: `${why}; written ${new Date(want.mtimeMs).toISOString()}, after the source last sent this path (${new Date(mark).toISOString()}), but the source has sent Changes for more than ${hours} h since without it` }); return; }
+    problems.push({ code, rel: want.rel, circle: want.circle, why });
+  };
+  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;
+    }
+    const abs = join(source, e.rel);
+    expected.set(nfc(e.rel), { rel: e.rel, circle: c.name, sha: sha(abs), mtimeMs: statSync(abs).mtimeMs });
+  }
+
+  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) {
+      late({ ...want, rel: e.rel }, "DIFFERS", "the shadow's bytes are not the record's");
+      continue;
+    }
+    perCircle[want.circle] += 1;
+  }
+  for (const [key, want] of expected) {
+    if (!seen.has(key)) late(want, "MISSING", "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, settled: marked ? settled : null, lag, 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${r.settled ? `; source's newest Change ${new Date(r.settled).toISOString()}` : ""}`);
+  const byCode = {};
+  for (const p of r.problems) byCode[p.code] = (byCode[p.code] ?? 0) + 1;
+  const lag = r.lag ?? [];
+  if (lag.length) {
+    lines.push(`  LAG ${lag.length} (written on this device after the source last sent that path, or after its newest Change, ${new Date(r.settled).toISOString()}, for a path it never sent; the source has not seen them yet)`);
+    for (const l of lag.slice(0, limit)) lines.push(`  LAG ${l.rel} [${l.circle}] (${l.was})`);
+  }
+  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.`);