create-evda 0.1.5 → 0.1.6

package/lib/gather-apply.mjs

@@ -0,0 +1,635 @@
+// `evda gather apply` and `evda gather revert`: the owner said yes to a gather proposal, so its
+// placements are written into a record, and every write can be taken back. Spec 07, "Gathering a
+// pile". The proposal and its questions are lib/gather.mjs.
+//
+// Apply:
+//   - Into a new record (a folder that does not exist or is empty): the record is made the way
+//     create-evda makes one, with the proposal's preset applied, and then filled.
+//   - Into an existing record: the pile is adopted, never re-sorted. An item whose bytes the record
+//     already holds, anywhere, is left where it is. A folder the proposal names is used when the
+//     record has it; else the record's own folder of the same type in the same role (a daily note
+//     goes to the record's journal folder, whatever it is called); else it is made, given its
+//     folder.evda.json, and declared under its role in evda.json. No file already in the record
+//     is moved, renamed or rewritten, except the manifests that say what a folder holds.
+//   - Copy is the default; the sources are not touched. With --move a placed file leaves its
+//     source; directories stay. Refused, unplaced and reference-only files never move.
+//   - References stay references: a Contacts card is a `contacts:` line on a person page, a
+//     bookmark is a new entry holding a `url:` reference, and the card or the bookmark is not
+//     copied. The answers on the proposal decide which person pages are made, which projects say
+//     `status: finished` (in their README's frontmatter, the project staying where it is), and
+//     whether a circle is proposed for sensitive notes: a proposal file under proposals/, never a
+//     circle. No share mark and no circle rule is ever written.
+//   - A chat export (HQ-1385) adds the owner's messages the record does not hold yet to its day
+//     files, each conversation one `## HH:MM` section at its date and time. A day file that exists is
+//     appended to, its old bytes kept for revert; one that does not is made.
+//   - Every file written, every manifest changed and every directory made is listed in a reversal
+//     manifest outside the record and the sources, with hashes, and doctor runs on the result.
+//
+// Revert restores the record and the sources to their bytes before the apply: moved files go back
+// with their mode and modification time, written files are removed, changed manifests get their
+// old bytes and times back, and directories the apply made are removed when empty. A written file
+// edited since the apply is named and the revert refused, unless --force.
+//
+// EVDA_GATHER_FALSIFY=<mode,...>, for the tests (APPLY_FALSIFY_MODES):
+//   apply-writes-share    the sensitive notes get a share: mark naming the proposed circle
+//   revert-not-exact      revert leaves the changed manifests as the apply wrote them
+//   reapply-resorts       nothing in the record counts as present, so a second gather places it all again
+//   move-without-flag     apply moves the sources when --move was not given
+//   revert-ignores-edits  revert removes a placed file the owner edited, without --force
+
+import { createHash } from "node:crypto";
+import { chmodSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve, sep } from "node:path";
+import { tmpdir } from "node:os";
+import { openEvda, readManifest, findRoot } from "./manifest.mjs";
+import { fourRoles, roleForPath, fourRoleOf } from "./roles.mjs";
+import { subRecords } from "./records.mjs";
+import { folderManifests, folderFor, FOLDER_MANIFEST } from "./folders.mjs";
+import { loadPreset, applyPreset, manifestFor } from "./presets.mjs";
+import { reference } from "./references.mjs";
+import { proposeCircle, onlyKeys, refuse } from "./tools.mjs";
+import { doctor } from "./doctor.mjs";
+import { gatherDir, loadProposal, checkOut, presentIndex, presentAt, GATHERED, chatPlan, dayDirOf } from "./gather.mjs";
+import { dayAppend } from "./chat-export.mjs";
+import { EvdaError } from "./errors.mjs";
+import { carries, NOTED, SEALED } from "./circles.mjs";
+import { parseArgs, scaffold } from "../create-evda.mjs";
+
+export const APPLY_VERSION = 1;
+export const APPLY_FALSIFY_MODES = ["apply-writes-share", "revert-not-exact", "reapply-resorts", "move-without-flag", "revert-ignores-edits"];
+const falsified = (mode) => (process.env.EVDA_GATHER_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+const posix = (p) => p.split(sep).join("/");
+const sha256 = (buf) => createHash("sha256").update(buf).digest("hex");
+const slug = (s) => s.toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-+|-+$/g, "") || "folder";
+const within = (abs, root) => abs === root || abs.startsWith(root + sep);
+
+// ---- writes, each one recorded ----
+
+// Every write the apply makes goes through here, so the reversal manifest is complete by
+// construction: a file made, a file changed (its old bytes and times kept), a directory made.
+function tracker(root) {
+  const t = { root, created: [], modified: [], dirs: [], moved: [], stash: new Map() };
+  const abs = (rel) => join(root, rel);
+  t.mkdirp = (rel) => {
+    if (!rel || rel === ".") return;
+    const segs = rel.split("/");
+    for (let i = 1; i <= segs.length; i++) {
+      const sub = segs.slice(0, i).join("/");
+      if (existsSync(abs(sub))) continue;
+      mkdirSync(abs(sub));
+      t.dirs.push(sub);
+    }
+  };
+  t.writeNew = (rel, buf, times = null) => {
+    t.mkdirp(posix(dirname(rel)));
+    writeFileSync(abs(rel), buf, { flag: "wx" });
+    if (times) utimesSync(abs(rel), times.atime, times.mtime);
+    t.created.push({ path: rel, sha256: sha256(buf), size: buf.length });
+  };
+  // Change a file that is already there (a manifest). Its bytes, mode and times are kept first.
+  t.modify = (rel, buf) => {
+    if (!t.stash.has(rel)) {
+      if (existsSync(abs(rel))) {
+        const st = statSync(abs(rel));
+        t.stash.set(rel, { path: rel, before: readFileSync(abs(rel)).toString("base64"), mode: st.mode & 0o7777, atimeMs: st.atimeMs, mtimeMs: st.mtimeMs });
+      } else t.stash.set(rel, { path: rel, before: null });
+    }
+    t.mkdirp(posix(dirname(rel)));
+    writeFileSync(abs(rel), buf);
+  };
+  // What the apply made or changed, with the hash each has now.
+  t.finish = () => {
+    t.modified = [...t.stash.values()].map((m) => ({ ...m, sha256: sha256(readFileSync(abs(m.path))) }));
+    return t;
+  };
+  return t;
+}
+
+// Every file and directory under `root`, relative, hidden ones included; symlinks are listed as files.
+function tree(root) {
+  const files = [];
+  const dirs = [];
+  const go = (d) => {
+    for (const n of readdirSync(d).sort()) {
+      const a = join(d, n);
+      const st = lstatSync(a);
+      const rel = posix(relative(root, a));
+      if (st.isDirectory()) { dirs.push(rel); go(a); } else files.push(rel);
+    }
+  };
+  if (existsSync(root)) go(root);
+  return { files, dirs };
+}
+
+// ---- frontmatter ----
+
+// Add keys to a markdown file's frontmatter, making one when it has none. A key it already has is
+// left as it is. `lines` are the YAML lines of each new key, keyed by name.
+function withFrontmatter(buf, add) {
+  const text = buf.toString("utf8");
+  const keys = Object.keys(add);
+  if (!keys.length) return buf;
+  if (text.startsWith("---\n")) {
+    const end = text.indexOf("\n---", 3);
+    if (end !== -1) {
+      const head = text.slice(4, end);
+      const missing = keys.filter((k) => !new RegExp(`^${k}\\s*:`, "m").test(head));
+      if (!missing.length) return buf;
+      return Buffer.from(`${text.slice(0, end)}\n${missing.map((k) => add[k]).join("\n")}${text.slice(end)}`, "utf8");
+    }
+  }
+  return Buffer.from(`---\n${keys.map((k) => add[k]).join("\n")}\n---\n${text}`, "utf8");
+}
+
+const q = (s) => JSON.stringify(s);
+const referencesYaml = (refs) => ["references:", ...refs.map((r) => { const v = reference(r); return `  - ref: ${q(v.ref)}\n    label: ${q(v.label)}`; })].join("\n");
+const refLabel = (ref, name) => (ref.startsWith("url:") ? ref.slice(4).replace(/^https?:\/\//, "") : name);
+
+// ---- the record ----
+
+// Where the apply writes: an existing record, or a new one made here with the proposal's preset.
+// Returns { evda, made } where `made` lists what making it wrote.
+function ensureRecord(target, p, { owner = "", dry = false } = {}) {
+  const exists = existsSync(target);
+  if (exists && !statSync(target).isDirectory()) throw refuse(`${target} is a file. Name a record, or a folder to make one in.`, "BAD_TARGET");
+  const empty = !exists || readdirSync(target).length === 0;
+  if (!empty) {
+    if (!existsSync(join(target, "evda.json"))) throw refuse(`${target} is not an EVDA and is not empty. Name a record to grow, or a new folder to make one in.`, "NOT_A_RECORD");
+    return { evda: openEvda(target), made: null, existed: true };
+  }
+  // A dry run makes the record in a temporary folder, plans against it, and removes it.
+  const dir = dry ? join(mkdtempSync(join(tmpdir(), "evda-gather-dry-")), basename(target)) : target;
+  const before = tree(dir);
+  const create = createRecord(dir, p.preset.id, owner);
+  const after = tree(dir);
+  const made = {
+    files: after.files.filter((f) => !before.files.includes(f)),
+    dirs: after.dirs.filter((d) => !before.dirs.includes(d)),
+    root: !exists,
+    preset: create.preset,
+  };
+  return { evda: openEvda(dir), made, existed: false, scratch: dry ? dirname(dir) : null };
+}
+
+function createRecord(dir, presetId, owner) {
+  const opts = parseArgs([dir, "--yes", "--no-pointer", ...(owner ? ["--owner", owner] : []), "--preset", presetId]);
+  scaffold(opts);
+  const plan = applyPreset(dir, presetId);
+  return { preset: plan.id };
+}
+
+// ---- the plan ----
+
+// The folder a proposal folder lands in, in this record.
+function folderResolver(evda, p) {
+  const preset = loadPreset(p.preset.id);
+  const subs = subRecords(evda.dir);
+  const four = fourRoles(evda, { subRecords: subs });
+  const inSub = (rel) => subs.some((s) => rel === s || rel.startsWith(`${s}/`));
+  const manifests = folderManifests(evda).filter((m) => m.type && !inSub(posix(relative(evda.dir, m.dir))));
+  const cache = new Map();
+  return (f) => {
+    if (cache.has(f.path)) return cache.get(f.path);
+    let r;
+    const abs = join(evda.dir, f.path);
+    if (existsSync(abs) && statSync(abs).isDirectory()) r = { path: f.path, how: "exists" };
+    else if (!falsified("reapply-resorts") && f.type) {
+      const same = manifests
+        .map((m) => ({ m, rel: posix(relative(evda.dir, m.dir)) }))
+        .filter(({ m, rel }) => rel !== "" && m.type === f.type && roleForPath(four, rel)?.role === f.role)
+        .sort((a, b) => a.rel.split("/").length - b.rel.split("/").length || a.rel.localeCompare(b.rel));
+      r = same.length ? { path: same[0].rel, how: "adopted" } : null;
+    }
+    if (!r) {
+      const pf = preset.folders.find((x) => x.path === f.path);
+      r = { path: f.path, how: "create", type: f.type ?? null, role: f.role ?? null, connectors: pf?.connectors ?? [] };
+    }
+    cache.set(f.path, r);
+    return r;
+  };
+}
+
+// The proposal folder a destination sits under: the longest one at or above it.
+const topOf = (p, to) => p.folders.filter((f) => to === f.path || to.startsWith(`${f.path}/`)).sort((a, b) => b.path.length - a.path.length)[0] ?? null;
+
+function sourceAbs(p, item) {
+  const s = p.sources.find((x) => x.id === item.source);
+  return existsSync(s.path) && statSync(s.path).isFile() ? s.path : join(s.path, item.path);
+}
+
+// The whole apply as a list of intended writes, before any is made. Pure over the record's state.
+function plan(evda, p, { mode }) {
+  const resolveFolder = folderResolver(evda, p);
+  const index = presentIndex(evda.dir);
+  const items = new Map(p.items.map((i) => [i.id, i]));
+  const out = { writes: [], present: [], changed: [], left: [], refused: [], referenceOnly: [], folders: new Map() };
+  const taken = new Set();
+  const claim = (to) => {
+    let t = to;
+    for (let n = 2; taken.has(t) || existsSync(join(evda.dir, t)); n++) t = to.replace(/(\.[^./]+)?$/, (e) => ` (${n})${e ?? ""}`);
+    taken.add(t);
+    return t;
+  };
+  const land = (to) => {
+    const f = topOf(p, to);
+    if (!f) return { to, folder: null };
+    const r = resolveFolder(f);
+    out.folders.set(f.path, { proposal: f, ...r });
+    return { to: r.path + to.slice(f.path.length), folder: f.path };
+  };
+  // The finished projects, and the placement that is each one's README.
+  const finished = new Map();
+  for (const pl of p.placements) {
+    if (!pl.fields?.status) continue;
+    const i = items.get(pl.item);
+    const key = `${i.source}:${i.project}`;
+    const proj = p.projects.find((x) => x.id === key);
+    const dir = pl.to.slice(0, pl.to.length - posix(relative(i.project, i.path)).replace(/\.txt$/i, ".md").length).replace(/\/$/, "");
+    const f = finished.get(key) ?? { name: proj?.name ?? basename(i.project), dir, readme: null, status: pl.fields.status };
+    if (/^readme\.(md|txt)$/i.test(basename(i.path)) && dirname(i.path) === i.project) f.readme = pl.item;
+    finished.set(key, f);
+  }
+  const statusFor = new Map([...finished.values()].filter((f) => f.readme).map((f) => [f.readme, f.status]));
+
+  for (const pl of p.placements) {
+    const i = items.get(pl.item);
+    if (pl.status === "refused") { out.refused.push({ item: pl.item, why: pl.why }); continue; }
+    if (pl.status === "unplaced") { out.left.push({ item: pl.item, why: pl.why }); continue; }
+    if (pl.status === "present") { out.present.push({ item: pl.item, at: pl.at }); continue; }
+    if (pl.status === "reference" && !pl.to) { out.referenceOnly.push({ item: pl.item, refs: (i.cards ?? []).map((c) => c.ref) }); continue; }
+    if (pl.status === "create") {
+      const { to, folder } = land(pl.to);
+      if (existsSync(join(evda.dir, to))) { out.present.push({ item: pl.item, at: to }); continue; }
+      const name = basename(pl.to, ".md");
+      const refs = (pl.refs ?? []).map((ref) => ({ ref, label: refLabel(ref, name) }));
+      const body = Buffer.from(`${refs.length ? `---\n${referencesYaml(refs)}\n---\n` : ""}# ${name}\n`, "utf8");
+      out.writes.push({ kind: "page", item: pl.item, to: claim(to), folder, bytes: body, schemes: refs.map((r) => r.ref.split(":")[0]) });
+      continue;
+    }
+    // Placed or a reference entry: the item's bytes are read again and must be what was gathered.
+    const at = presentAt(index, i.sha256);
+    if (at) { out.present.push({ item: pl.item, at }); continue; }
+    const src = sourceAbs(p, i);
+    let buf;
+    try { buf = readFileSync(src); } catch { out.changed.push({ item: pl.item, why: "is no longer at its source" }); continue; }
+    if (sha256(buf) !== i.sha256) { out.changed.push({ item: pl.item, why: "changed since the gather; gather again to place it" }); continue; }
+    const { to, folder } = land(pl.to);
+    if (pl.status === "reference") {
+      const name = basename(pl.to, ".md");
+      const refs = (pl.refs ?? []).map((ref) => ({ ref, label: refLabel(ref, name) }));
+      // A new entry made from a sealed or just-noted item carries its flag (HQ-1414).
+      const flags = [[SEALED, i.sealed], [NOTED, i.noted]].filter(([f, on]) => on && carries("gather-apply", f)).map(([f]) => `${f}: true\n`).join("");
+      out.writes.push({ kind: "reference", item: pl.item, source: src, sourceSha: i.sha256, to: claim(to), folder, bytes: Buffer.from(`---\n${flags}${referencesYaml(refs)}\n---\n# ${name}\n`, "utf8"), schemes: refs.map((r) => r.ref.split(":")[0]) });
+      continue;
+    }
+    const add = {};
+    const md = /\.md$/i.test(to);
+    if (md && pl.refs?.length) add.references = referencesYaml(pl.refs.map((ref) => ({ ref, label: refLabel(ref, i.heading ?? basename(to, ".md")) })));
+    if (md && statusFor.has(pl.item)) add.status = `status: ${statusFor.get(pl.item)}`;
+    if (md && pl.circle && falsified("apply-writes-share")) add.share = `share: [${pl.circle}]`;
+    // The item's own bytes, frontmatter included, so `noted: true` and `sealed: true` ride into the
+    // record with it (HQ-1414). EVDA_CARRY_FALSIFY=gather-apply:<flag> drops that line on the way in.
+    let bytes = withFrontmatter(buf, add);
+    for (const flag of [NOTED, SEALED]) if (md && !carries("gather-apply", flag)) bytes = Buffer.from(bytes.toString("utf8").replace(new RegExp(`^${flag}:[ \\t]*true[ \\t]*\\n`, "m"), ""), "utf8");
+    const st = statSync(src);
+    out.writes.push({
+      kind: mode === "move" ? "move" : "copy", item: pl.item, source: src, sourceSha: i.sha256, to: claim(to), folder, bytes, original: buf,
+      schemes: md && add.references ? pl.refs.map((r) => r.split(":")[0]) : [],
+      times: { atime: st.atimeMs / 1000, mtime: st.mtimeMs / 1000 }, mode: st.mode & 0o7777, atimeMs: st.atimeMs, mtimeMs: st.mtimeMs,
+    });
+  }
+  // A finished project with no README placed gets one, holding only its status and its name.
+  for (const f of finished.values()) {
+    if (f.readme) continue;
+    const { to, folder } = land(`${f.dir}/README.md`);
+    out.writes.push({ kind: "page", item: `status:${f.name}`, to: claim(to), folder, bytes: Buffer.from(`---\nstatus: ${f.status}\n---\n# ${f.name}\n`, "utf8"), schemes: [] });
+  }
+  // The folders the writes land in: made, with their manifest and role, or the record's own.
+  out.roles = [];
+  const mapping = evda.manifest.mapping;
+  const declared = new Set(Object.keys(mapping));
+  const four = fourRoles(evda, { subRecords: subRecords(evda.dir) });
+  for (const f of [...out.folders.values()].filter((x) => x.how === "create" && out.writes.some((w) => w.folder === x.proposal.path))) {
+    if (roleForPath(four, f.path)) continue;
+    // The proposal's own key for this folder, or for the nearest folder above it.
+    const candidates = Object.entries(p.mapping ?? {}).filter(([, v]) => f.path === v || f.path.startsWith(`${v}/`)).sort((a, b) => b[1].length - a[1].length);
+    const [key0, rel] = candidates[0] ?? [`${f.role ?? "collections"}/${slug(basename(f.path))}`, f.path];
+    if (out.roles.some((r) => r.rel === rel) || Object.values(mapping).includes(rel)) continue;
+    let key = key0;
+    if (declared.has(key)) {
+      const base = `${fourRoleOf(key0) ?? f.role}/${slug(basename(rel))}`;
+      key = base;
+      for (let n = 2; declared.has(key); n++) key = `${base}-${n}`;
+    }
+    declared.add(key);
+    out.roles.push({ key, rel });
+  }
+  return out;
+}
+
+// ---- apply ----
+
+export async function applyGather(p, into, { mode = "copy", dry = false, now = new Date(), owner = "", manifestOut = null, env = process.env, proposalPath = null } = {}) {
+  if (!["copy", "move"].includes(mode)) throw refuse(`mode is copy or move, not ${JSON.stringify(mode)}.`, "BAD_MODE");
+  if (falsified("move-without-flag")) mode = "move";
+  const open = (p.questions ?? []).filter((x) => x.answer === undefined);
+  if (open.length) throw refuse(`the proposal has ${open.length} open question(s), and the owner decides every placement before anything is written: ${open.map((x) => `[${x.id}] ${x.text}`).join(" ")} Answer them with evda gather answer, then apply.`, "OPEN_QUESTIONS");
+  const target = resolve(into);
+  for (const s of p.sources) {
+    if (within(target, s.path)) throw refuse(`${target} is inside the source ${s.path}. The record is written outside every source.`, "INTO_SOURCE");
+    if (within(s.path, target)) throw refuse(`the source ${s.path} is inside ${target}. Gather a pile from outside the record it grows.`, "SOURCE_IN_RECORD");
+  }
+  const outer = findRoot(dirname(target));
+  if (outer && !existsSync(join(target, "evda.json"))) throw refuse(`${target} is inside the EVDA at ${outer}. A new record is made outside every record; to grow ${outer}, name it.`, "INTO_RECORD");
+  const manifestAbs = dry ? null : checkOut(manifestOut ?? join(gatherDir(env), `${p.id}.apply-${now.toISOString().replace(/[-:]/g, "").replace(/\..*$/, "")}.json`), p);
+  if (manifestAbs && existsSync(manifestAbs)) throw refuse(`a reversal manifest is already at ${manifestAbs}. Name another with --manifest.`, "MANIFEST_EXISTS");
+
+  const rec = ensureRecord(target, p, { owner, dry });
+  const evda = rec.evda;
+  const pl = plan(evda, p, { mode });
+  pl.chats = chatWrites(evda, p);
+  const result = { dry, mode, target, made: rec.made, plan: pl, manifest: manifestAbs, proposal: p.id };
+  result.counts = counts(pl, p);
+  if (dry) {
+    if (rec.scratch) rmSync(rec.scratch, { recursive: true, force: true });
+    result.lines = applyLines(result, p);
+    return result;
+  }
+
+  const t = tracker(evda.dir);
+  // 1. Folders the writes need that the record does not have, each with its manifest.
+  const needSchemes = new Map();
+  for (const w of pl.writes) for (const s of w.schemes) {
+    const f = pl.folders.get(w.folder);
+    const key = f ? f.path : posix(dirname(w.to));
+    needSchemes.set(key, new Set([...(needSchemes.get(key) ?? []), s]));
+  }
+  for (const f of pl.folders.values()) {
+    if (f.how !== "create" || !pl.writes.some((w) => w.folder === f.proposal.path)) continue;
+    t.mkdirp(f.path);
+    if (f.type) {
+      const connectors = [...new Set([...(f.connectors ?? []), ...(needSchemes.get(f.path) ?? [])])];
+      t.writeNew(`${f.path}/${FOLDER_MANIFEST}`, Buffer.from(JSON.stringify(manifestFor({ type: f.type, connectors }), null, 2) + "\n"));
+    }
+  }
+  // 2. The roles those folders fill, in evda.json. Only added, never replaced.
+  if (pl.roles.length) {
+    const m = readManifest(evda.dir);
+    for (const r of pl.roles) m.mapping[r.key] ??= r.rel;
+    t.modify("evda.json", Buffer.from(JSON.stringify(m, null, 2) + "\n"));
+  }
+  // 3. The files.
+  const ledger = [];
+  for (const w of pl.writes) {
+    t.writeNew(w.to, w.bytes, w.times ?? null);
+    if (w.source) ledger.push({ source: w.sourceSha, to: w.to, proposal: p.id, at: now.toISOString() });
+    if (w.kind === "move") {
+      unlinkSync(w.source);
+      // A file the apply changed on the way in keeps its source bytes here, so revert can put them back.
+      t.moved.push({ source: w.source, to: w.to, sha256: w.sourceSha, mode: w.mode, atimeMs: w.atimeMs, mtimeMs: w.mtimeMs, ...(sha256(w.bytes) !== w.sourceSha ? { bytes: w.original.toString("base64") } : {}) });
+    }
+  }
+  // 3b. The owner's chat messages no agent filed (HQ-1385), appended to their days.
+  for (const [rel, adds] of pl.chats.byFile) {
+    const abs = join(evda.dir, rel);
+    const current = existsSync(abs) ? readFileSync(abs, "utf8") : null;
+    const bytes = Buffer.from((current ?? "") + dayAppend(current, adds), "utf8");
+    if (current === null) t.writeNew(rel, bytes);
+    else t.modify(rel, bytes);
+  }
+  // 4. A written reference resolves through a connector its folder declares; one it lacks is added.
+  const manifestsNow = folderManifests(openEvda(evda.dir));
+  for (const w of pl.writes) {
+    if (!w.schemes.length) continue;
+    const f = folderFor(join(evda.dir, w.to), manifestsNow);
+    if (!f) continue;
+    const m = JSON.parse(readFileSync(f.abs, "utf8"));
+    const has = Array.isArray(m.connectors) ? m.connectors : [];
+    const add = w.schemes.filter((s) => !has.includes(s));
+    if (!add.length) continue;
+    m.connectors = [...has, ...new Set(add)];
+    f.connectors = m.connectors;
+    t.modify(posix(relative(evda.dir, f.abs)), Buffer.from(JSON.stringify(m, null, 2) + "\n"));
+  }
+  // 5. The record's list of what it gathered, so a second gather knows a file it changed on the way in.
+  if (ledger.length) {
+    const g = join(evda.dir, GATHERED);
+    const before = existsSync(g) ? readFileSync(g, "utf8") : "";
+    t.modify(GATHERED, Buffer.from(before + ledger.map((l) => JSON.stringify(l)).join("\n") + "\n"));
+  }
+  // 6. A circle the answers asked for: a proposal file, never a circle.
+  result.proposed = [];
+  for (const c of p.circles ?? []) {
+    const f = [...pl.folders.values()].find((x) => c.covers === x.proposal.path || c.covers.startsWith(`${x.proposal.path}/`));
+    const covers = f ? f.path + c.covers.slice(f.proposal.path.length) : c.covers;
+    if (!pl.writes.some((w) => w.to.startsWith(`${covers}/`))) continue;
+    const before = tree(evda.dir);
+    const r = proposeCircle(evda, { name: c.name, who: "Only the people the owner grants it to, by name.", what: `${covers}/`, why: `The owner said yes to its own circle for these notes while gathering a pile (proposal ${p.id}).` }, { now });
+    const after = tree(evda.dir);
+    for (const d of after.dirs.filter((x) => !before.dirs.includes(x))) t.dirs.push(d);
+    t.created.push({ path: r.path, sha256: sha256(readFileSync(join(evda.dir, r.path))), size: statSync(join(evda.dir, r.path)).size });
+    result.proposed.push(r.path);
+  }
+  t.finish();
+
+  // The reversal manifest, written before doctor so a failing doctor still leaves a way back.
+  const manifest = {
+    evdaGatherApply: APPLY_VERSION,
+    proposal: p.id,
+    proposalPath,
+    target: evda.dir,
+    mode,
+    at: now.toISOString(),
+    made: rec.made ? { root: rec.made.root, preset: rec.made.preset, files: rec.made.files.map((f) => ({ path: f, sha256: sha256(readFileSync(join(evda.dir, f))) })), dirs: rec.made.dirs } : null,
+    created: t.created,
+    // A file the making of the record wrote and the apply then changed is simply made: revert removes it.
+    modified: t.modified.filter((m) => !rec.made?.files.includes(m.path)),
+    dirs: t.dirs,
+    moved: t.moved,
+    placed: pl.writes.map((w) => ({ item: w.item, kind: w.kind, from: w.source ?? null, to: w.to })),
+    chats: [...pl.chats.byFile.keys()],
+    counts: result.counts,
+  };
+  mkdirSync(dirname(manifestAbs), { recursive: true });
+  writeFileSync(manifestAbs, JSON.stringify(manifest, null, 2) + "\n", { flag: "wx" });
+
+  const lines = [];
+  const d = doctor(evda.dir, { out: (l) => lines.push(l), via: "gather apply" });
+  result.doctor = { exit: d.exit, lines, failures: d.failures, warnings: d.warnings.length };
+  result.lines = applyLines(result, p);
+  return result;
+}
+
+// The chat exports' additions, grouped by day file: { byFile: Map(rel -> adds), added, filed, secret,
+// changed: [why] }. The record is read as it is now, so what an agent filed since the gather counts.
+function chatWrites(evda, p) {
+  const out = { byFile: new Map(), added: 0, filed: 0, secret: 0, conversations: 0, changed: [] };
+  if (!(p.chats ?? []).length) return out;
+  const dayDir = dayDirOf(evda);
+  if (!dayDir) { out.changed.push("the record maps no day role, so the chat messages have no day to go to"); return out; }
+  for (const c of p.chats) {
+    let r;
+    try { r = chatPlan(evda, p.sources.find((x) => x.id === c.source), c); } catch (e) { out.changed.push(e.message.replace(/^REFUSED: /, "").replace(/ Nothing was written\.$/, "")); continue; }
+    out.filed += r.counts.filed;
+    out.secret += r.counts.secret;
+    for (const a of r.adds) {
+      const rel = posix(relative(evda.dir, join(dayDir, `${a.date}.md`)));
+      out.byFile.set(rel, [...(out.byFile.get(rel) ?? []), a]);
+      out.added += a.words.length;
+      out.conversations += 1;
+    }
+  }
+  for (const [rel, adds] of out.byFile) out.byFile.set(rel, adds.sort((a, b) => a.time.localeCompare(b.time)));
+  return out;
+}
+
+function counts(pl, p) {
+  const by = (k) => pl.writes.filter((w) => w.kind === k).length;
+  const placed = by("copy") + by("move") + by("reference") + by("page");
+  return {
+    placed, copied: by("copy"), moved: by("move"), references: by("reference"), pages: by("page"),
+    asked: (p.questions ?? []).length, left: pl.left.length, refused: pl.refused.length, present: pl.present.length,
+    changed: pl.changed.length, referenceOnly: pl.referenceOnly.length,
+    chatAdded: pl.chats?.added ?? 0, chatFiled: pl.chats?.filed ?? 0, chatSecret: pl.chats?.secret ?? 0, chatDays: pl.chats?.byFile.size ?? 0,
+  };
+}
+
+export function checkedLine(c) {
+  return `CHECKED ${c.placed} items placed, ${c.asked} asked, ${c.left} left for a person`;
+}
+
+function applyLines(r, p) {
+  const c = r.counts;
+  const out = [];
+  const verb = r.dry ? "would" : "did";
+  if (r.made) out.push(`${r.dry ? "Would make" : "Made"} a new EVDA at ${r.target} with the ${p.preset.title} preset (${r.made.files.length} file(s)).`);
+  else out.push(`${r.dry ? "Would grow" : "Grew"} the EVDA at ${r.target}; nothing already in it was moved.`);
+  for (const f of r.plan.folders.values()) {
+    if (f.how === "adopted") out.push(`  adopted  ${f.proposal.path}/ as the record's own ${f.path}/ (type ${f.proposal.type}, ${f.proposal.role})`);
+    else if (f.how === "create" && r.plan.writes.some((w) => w.folder === f.proposal.path)) out.push(`  ${verb === "did" ? "made    " : "make    "} ${f.path}/${f.type ? ` with ${FOLDER_MANIFEST} (type ${f.type})` : ""}`);
+  }
+  for (const x of r.plan.roles) out.push(`  ${verb === "did" ? "declared" : "declare "} ${x.key} -> ${x.rel}  in evda.json`);
+  out.push(`  ${verb === "did" ? (r.mode === "move" ? "moved   " : "copied  ") : (r.mode === "move" ? "move    " : "copy    ")} ${c.copied + c.moved} file(s)${r.mode === "move" ? ", each gone from its source" : "; the sources are untouched"}`);
+  if (c.references) out.push(`  ${verb === "did" ? "wrote   " : "write   "} ${c.references} entr${c.references === 1 ? "y" : "ies"} holding references; the bookmarks and link lists stay where they are`);
+  if (c.pages) out.push(`  ${verb === "did" ? "wrote   " : "write   "} ${c.pages} page(s) the answers asked for`);
+  if (c.referenceOnly) out.push(`  kept     ${c.referenceOnly} export(s) as references only, never copied`);
+  if (c.present) out.push(`  present  ${c.present} item(s) already in the record, left where they are`);
+  for (const x of r.plan.changed) out.push(`  changed  ${x.item} ${x.why}`);
+  if ((p.chats ?? []).length) {
+    out.push(`  ${verb === "did" ? "added   " : "add     "} ${c.chatAdded} message(s) of the owner's from ${p.chats.length} chat export(s) to ${c.chatDays} day file(s), each conversation under its date and time; ${c.chatFiled} already in the record${c.chatSecret ? `, ${c.chatSecret} left out for holding something shaped like a secret` : ""}`);
+    for (const why of r.plan.chats.changed) out.push(`  changed  ${why}`);
+  }
+  for (const x of r.plan.left) out.push(`  left     ${x.item}: ${x.why}`);
+  for (const x of r.plan.refused) out.push(`  refused  ${x.item}: left where it is`);
+  for (const x of r.proposed ?? []) out.push(`  proposed ${x}  (a proposal file; no circle was created, and no file was marked for sharing)`);
+  if (!r.dry) {
+    out.push(`Reversal manifest: ${r.manifest}  (evda gather revert ${r.manifest})`);
+    const last = r.doctor.lines[r.doctor.lines.length - 1] ?? "";
+    out.push(`doctor: ${last.trim()}`);
+    for (const f of r.doctor.failures) out.push(`  FAIL  ${f}`);
+  } else out.push("Nothing was written.");
+  out.push(checkedLine(c));
+  if ((p.chats ?? []).length) out.push(`CHECKED ${c.chatAdded + c.chatFiled + c.chatSecret} chat message(s) of the owner's  ${c.chatAdded} added, ${c.chatFiled} already filed, ${c.chatSecret} secret-shaped`);
+  out.push(`CHECKED ${c.copied + c.moved} file(s) ${r.mode === "move" ? "moved" : "copied"}, ${c.references} reference entr${c.references === 1 ? "y" : "ies"}, ${c.pages} page(s), ${c.present} already in the record, ${c.refused} refused, ${c.changed} changed since the gather`);
+  return out;
+}
+
+// ---- revert ----
+
+export function loadApplyManifest(path) {
+  const abs = resolve(path);
+  if (!existsSync(abs)) throw refuse(`no reversal manifest at ${abs}.`, "NO_MANIFEST");
+  let m;
+  try { m = JSON.parse(readFileSync(abs, "utf8")); } catch (e) { throw refuse(`${abs} is not valid JSON (${e.message}).`, "BAD_MANIFEST"); }
+  if (m?.evdaGatherApply !== APPLY_VERSION || !Array.isArray(m.created)) throw refuse(`${abs} is not a gather reversal manifest.`, "BAD_MANIFEST");
+  return { m, abs };
+}
+
+const hashOf = (abs) => (existsSync(abs) && lstatSync(abs).isFile() ? sha256(readFileSync(abs)) : null);
+
+export function revertGather(path, { force = false, now = new Date() } = {}) {
+  const { m, abs } = loadApplyManifest(path);
+  if (m.reverted) throw new EvdaError(`REFUSED: ${abs} was already reverted at ${m.reverted}. Nothing was changed.`, { code: "ALREADY_REVERTED", exit: 2 });
+  const root = m.target;
+  const files = [...(m.made?.files ?? []), ...m.created];
+  const edited = [];
+  const gone = [];
+  for (const f of files) {
+    const h = hashOf(join(root, f.path));
+    if (h === null) gone.push(f.path);
+    else if (h !== f.sha256) edited.push(f.path);
+  }
+  for (const f of m.modified) if (hashOf(join(root, f.path)) !== f.sha256) edited.push(f.path);
+  const blocked = m.moved.filter((x) => existsSync(x.source)).map((x) => x.source);
+  if ((edited.length || blocked.length) && !force && !falsified("revert-ignores-edits")) {
+    throw new EvdaError("REFUSED: " + [
+      edited.length ? `${edited.length} file(s) changed since the apply: ${edited.join(", ")}.` : "",
+      blocked.length ? `${blocked.length} source path(s) hold a file again: ${blocked.join(", ")}.` : "",
+      "Reverting would lose those changes. Pass --force to revert anyway. Nothing was changed.",
+    ].filter(Boolean).join(" "), { code: "EDITED_SINCE_APPLY", exit: 2 });
+  }
+  // Moved files first, back to their sources with their mode and times.
+  let restored = 0;
+  for (const x of m.moved) {
+    const placed = join(root, x.to);
+    const bytes = x.bytes ? Buffer.from(x.bytes, "base64") : existsSync(placed) ? readFileSync(placed) : null;
+    if (!bytes) continue;
+    mkdirSync(dirname(x.source), { recursive: true });
+    writeFileSync(x.source, bytes);
+    chmodSync(x.source, x.mode);
+    utimesSync(x.source, x.atimeMs / 1000, x.mtimeMs / 1000);
+    restored += 1;
+  }
+  let removed = 0;
+  for (const f of files) { const a = join(root, f.path); if (existsSync(a)) { unlinkSync(a); removed += 1; } }
+  let put = 0;
+  if (!falsified("revert-not-exact")) {
+    for (const f of m.modified) {
+      const a = join(root, f.path);
+      if (f.before === null) { if (existsSync(a)) unlinkSync(a); put += 1; continue; }
+      writeFileSync(a, Buffer.from(f.before, "base64"));
+      chmodSync(a, f.mode);
+      utimesSync(a, f.atimeMs / 1000, f.mtimeMs / 1000);
+      put += 1;
+    }
+  }
+  // Directories the apply made, deepest first, when nothing the owner added is in them.
+  const kept = [];
+  const dirs = [...(m.made?.dirs ?? []), ...m.dirs].sort((a, b) => b.split("/").length - a.split("/").length || b.localeCompare(a));
+  for (const d of dirs) {
+    const a = join(root, d);
+    if (!existsSync(a)) continue;
+    if (readdirSync(a).length) { kept.push(d); continue; }
+    rmdirSync(a);
+  }
+  if (m.made?.root && existsSync(root) && readdirSync(root).length === 0) rmdirSync(root);
+  m.reverted = now.toISOString();
+  writeFileSync(abs, JSON.stringify(m, null, 2) + "\n");
+  return { manifest: abs, target: root, restored, removed, put, kept, gone, edited, forced: force && edited.length > 0 };
+}
+
+export function revertLines(r) {
+  const out = [`Reverted the gather into ${r.target}.`];
+  if (r.restored) out.push(`  returned ${r.restored} file(s) to their sources, with their mode and modification time`);
+  out.push(`  removed  ${r.removed} file(s) the apply wrote`);
+  if (r.put) out.push(`  restored ${r.put} file(s) the apply changed (evda.json, a folder manifest, the gathered list) to their bytes before it`);
+  if (r.forced) out.push(`  forced   ${r.edited.length} file(s) edited since the apply were removed: ${r.edited.join(", ")}`);
+  for (const d of r.kept) out.push(`  kept     ${d}/, which holds files the apply did not write`);
+  if (r.gone.length) out.push(`  gone     ${r.gone.length} file(s) were already removed`);
+  out.push(`CHECKED ${r.removed + r.restored + r.put} file(s) reverted  ${r.kept.length} folder(s) kept`);
+  return out;
+}
+
+// ---- MCP ----
+
+export async function gatherApplyTool(evda, args = {}, { now = new Date(), env = process.env } = {}) {
+  onlyKeys("evda_gather_apply", args, ["proposal", "into", "move", "confirmed"], "It writes the proposal into a record after the owner's yes, and every write is listed in a reversal manifest.");
+  if (typeof args.proposal !== "string" || !args.proposal.trim()) throw refuse('evda_gather_apply needs "proposal", the id evda_gather returned.', "NO_PROPOSAL");
+  if (args.confirmed !== true) throw refuse('evda_gather_apply needs "confirmed": true, and that is true only when the owner said yes to applying this proposal in this conversation. Show them evda_gather\'s summary and the answers first, and wait.', "NOT_CONFIRMED");
+  if (args.move !== undefined && typeof args.move !== "boolean") throw refuse('evda_gather_apply "move" is true or false; copy is the default.', "BAD_MODE");
+  if (args.into !== undefined && (typeof args.into !== "string" || !args.into.trim())) throw refuse('evda_gather_apply "into" is a path: the record to grow, or a new folder to make one in.', "BAD_TARGET");
+  const { p, abs } = loadProposal(args.proposal, env);
+  const into = args.into ?? evda?.dir;
+  if (!into) throw refuse('evda_gather_apply needs "into": no record is open.', "BAD_TARGET");
+  return applyGather(p, into, { mode: args.move ? "move" : "copy", now, env, proposalPath: abs });
+}