create-evda 0.1.9 → 0.1.10

package/lib/presets.mjs

@@ -28,7 +28,10 @@
 // that are missing, and reports the rest: a manifest that already says the same thing is skipped,
 // one that says something else is a conflict and is left exactly as it is, and a preset path that
 // already exists as a file is a conflict. Nothing is moved, renamed or deleted, so applying twice
-// writes nothing the second time. A shipped preset that does not validate fails
+// writes nothing the second time. A folder typed person also brings its layout (HQ-2024): a sibling
+// Processing/ for processing docs, and a README inside the folder stating the one-file-per-person
+// rule doctor checks, each only when missing and only when the folder's manifest is the preset's.
+// A shipped preset that does not validate fails
 // test/presets.test.mjs, so the person running it never meets one.
 
 import { existsSync, lstatSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
@@ -40,6 +43,7 @@ import { validateFolderManifest, FOLDER_MANIFEST, FOLDER_TYPES } from "./folders
 import { ROUTINE_KEYS } from "./routines.mjs";
 import { onlyKeys, proposeCircle, refuse, PROPOSALS } from "./tools.mjs";
 import { EvdaError } from "./errors.mjs";
+import { PERSON_FOLDER_README, PROCESSING_DIR, README_NAME } from "./person-folders.mjs";
 
 export const PRESETS_DIR = resolve(dirname(fileURLToPath(import.meta.url)), "..", "presets");
 export const PRESET_FILE = "preset.json";
@@ -223,6 +227,7 @@ const viewHeader = (v) => ["---", `view: ${v.view}`, `of: ${v.of}`, `in: ${v.in}
 //   create     directories that do not exist yet
 //   write      manifests that do not exist yet ({ path, folder, manifest })
 //   views      view files a manifest declares that do not exist yet
+//   files      files a person folder brings that do not exist yet ({ path, text }): its README
 //   matched    manifests that exist and already say what the preset says (skipped)
 //   conflicts  manifests that exist and say something else, and preset paths that are files
 //              ({ path, why }); reported, never overwritten
@@ -231,7 +236,7 @@ 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, roles: [] };
+  const plan = { id: preset.id, title: preset.title, root: evda.dir, dry, create: [], write: [], files: [], 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;
@@ -263,15 +268,29 @@ export function applyPreset(root, id, { dry = false, now = new Date(), dir = PRE
     const want = manifestFor(f);
     const mpath = `${f.path}/${FOLDER_MANIFEST}`;
     const mabs = join(abs, FOLDER_MANIFEST);
+    let ours = true;
     if (!existsSync(mabs)) plan.write.push({ path: mpath, folder: f, manifest: want });
-    else if (!lstatSync(mabs).isFile()) plan.conflicts.push({ path: mpath, why: "exists and is not a file" });
+    else if (!lstatSync(mabs).isFile()) { plan.conflicts.push({ path: mpath, why: "exists and is not a file" }); ours = false; }
     else {
       let existing;
       try { existing = JSON.parse(readFileSync(mabs, "utf8")); } catch { plan.conflicts.push({ path: mpath, why: "exists and is not valid JSON" }); continue; }
       const diff = differences(existing, want);
-      if (diff.length) plan.conflicts.push({ path: mpath, why: `exists and differs: ${diff.join("; ")}` });
+      if (diff.length) { plan.conflicts.push({ path: mpath, why: `exists and differs: ${diff.join("; ")}` }); ours = false; }
       else plan.matched.push({ path: mpath });
     }
+    if (f.type === "person" && ours) {
+      const readme = `${f.path}/${README_NAME}`;
+      const rabs = join(abs, README_NAME);
+      if (!existsSync(rabs)) plan.files.push({ path: readme, text: PERSON_FOLDER_README });
+      else if (!lstatSync(rabs).isFile()) plan.conflicts.push({ path: readme, why: "exists and is not a file" });
+      const parent = f.path.includes("/") ? f.path.slice(0, f.path.lastIndexOf("/")) : "";
+      const processing = parent ? `${parent}/${PROCESSING_DIR}` : PROCESSING_DIR;
+      const pfile = blockedBy(evda.dir, processing);
+      if (pfile) {
+        if (!blocked.has(pfile)) plan.conflicts.push({ path: pfile, why: `exists as a file, so ${processing}/ for processing docs beside ${f.path} cannot be made there` });
+        blocked.add(pfile);
+      } else if (!existsSync(join(evda.dir, processing)) && !plan.create.includes(processing)) plan.create.push(processing);
+    }
     for (const v of want.views) {
       if (!existsSync(resolve(evda.dir, v.path))) plan.views.push({ path: v.path, view: v });
     }
@@ -295,6 +314,7 @@ export function applyPreset(root, id, { dry = false, now = new Date(), dir = PRE
   }
   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 w of plan.files) writeFileSync(join(evda.dir, w.path), w.text, { flag: "wx" });
   for (const v of plan.views) {
     mkdirSync(dirname(resolve(evda.dir, v.path)), { recursive: true });
     writeFileSync(resolve(evda.dir, v.path), viewHeader(v.view), { flag: "wx" });
@@ -317,7 +337,7 @@ 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 && !(plan.roles ?? []).length;
+export const planIsEmpty = (plan) => !plan.create.length && !plan.write.length && !(plan.files ?? []).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)) {
@@ -344,6 +364,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 w of plan.files ?? []) out.push(`  ${verb === "did" ? "wrote   " : "write   "} ${w.path}  the person folder's rule`);
   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`);

package/lib/publish.mjs

@@ -29,7 +29,9 @@
 //      written, and a hit refuses. A label is its opaque id, its namespace, its own directory, a
 //      member path, or its name between slashes. The exported files' own paths are the released
 //      set (doctor prints them every run) and are left out of that search, since a marked file
-//      necessarily lives under a keyed circle's member path.
+//      necessarily lives under a keyed circle's member path. A markdown file's `sources:`
+//      frontmatter field is cut from its exported bytes before this search (HQ-2698): it is
+//      provenance, the record's own paths, and is never published.
 //
 // The fourth check in the spec (the site holds no credential to anything else) is a property of
 // where the export is served, not of this code.
@@ -70,6 +72,41 @@ function filesUnder(abs) {
 const posix = (rel) => rel.split(sep).join("/");
 const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
 
+// Provenance (HQ-2698). A top-level `sources:` field in a markdown file's frontmatter lists the
+// record paths the file was written from: a blog Companion names the private draft and the journal
+// days behind it. That is the record's own bookkeeping, never part of what a stranger reads, so it
+// is cut from every exported markdown file, whatever folder or rule released it, the way a sealed
+// section is. Only the frontmatter field is cut: a private path anywhere in the body still reaches
+// the stranger check and refuses. The value runs to the next top-level key, so a block list,
+// indented or not, a flow list on one or more lines and a bare string all go with the key.
+const PROVENANCE_KEY = /^(["']?)sources\1[ \t]*:/;
+const isFence = (line) => line.replace(/\r$/, "") === "---";
+const continues = (line) => /^[ \t]/.test(line) || /^-([ \t]|\r?$)/.test(line);
+const blank = (line) => line.replace(/\r$/, "").trim() === "";
+export function withoutProvenance(text) {
+  const lines = String(text).split("\n");
+  if (!isFence(lines[0])) return { text, cut: 0 };
+  let end = 1;
+  while (end < lines.length && !isFence(lines[end])) end++;
+  if (end >= lines.length) return { text, cut: 0 };
+  const kept = [lines[0]];
+  let cut = 0;
+  for (let i = 1; i < end; i++) {
+    if (!PROVENANCE_KEY.test(lines[i])) { kept.push(lines[i]); continue; }
+    cut++;
+    let j = i + 1;
+    for (;;) {
+      let k = j;
+      while (k < end && blank(lines[k])) k++;
+      if (k < end && continues(lines[k])) j = k + 1;
+      else break;
+    }
+    i = j - 1;
+  }
+  if (!cut) return { text, cut: 0 };
+  return { text: [...kept, ...lines.slice(end)].join("\n"), cut };
+}
+
 // Build the export in memory and run the checks. Writes nothing.
 export function buildPublicExport(evda, { circleName = null, publishedAt = new Date() } = {}) {
   const circle = publicCircle(evda, circleName);
@@ -114,14 +151,21 @@ export function buildPublicExport(evda, { circleName = null, publishedAt = new D
   // A sealed section (HQ-1220) is cut out of every markdown file on the way out; the rest of the
   // file is exported, and nothing marks where the section was. A sealed FILE never gets here:
   // released() refuses it, and a refusal refuses the publish above.
+  // A file's `sources:` provenance is cut the same way (withoutProvenance above, HQ-2698).
   let sealedCut = 0;
+  let provenanceCut = 0;
   const exportBytes = (abs) => {
     const bytes = readFileSync(abs);
-    if (!/\.md$/i.test(abs) || !carries("publish", "sealed")) return bytes;
-    const cut = withoutSealed(bytes.toString("utf8"));
-    if (!cut.sections) return bytes;
-    sealedCut += cut.sections;
-    return Buffer.from(cut.text, "utf8");
+    if (!/\.md$/i.test(abs)) return bytes;
+    let text = bytes.toString("utf8");
+    let changed = false;
+    if (carries("publish", "sealed")) {
+      const cut = withoutSealed(text);
+      if (cut.sections) { sealedCut += cut.sections; text = cut.text; changed = true; }
+    }
+    const prov = withoutProvenance(text);
+    if (prov.cut) { provenanceCut += 1; text = prov.text; changed = true; }
+    return changed ? Buffer.from(text, "utf8") : bytes;
   };
   const loaded = files.filter((f) => !consumed.has(f.path)).map((f) => ({ path: f.path, bytes: exportBytes(f.abs), by: f.by }));
   for (const v of rendered.views) loaded.push({ path: v.path, bytes: v.bytes, by: "view", view: v.view, sources: v.entries.map((e) => ({ path: e.path, sha256: e.sha256 })) });
@@ -157,9 +201,9 @@ export function buildPublicExport(evda, { circleName = null, publishedAt = new D
       // What identifies a private circle to a stranger is a LABEL: a path segment, the circle's own
       // directory, or the opaque id that travels on a Change and in an export manifest. A name
       // matched as a word anywhere in the bytes is not that test, and on a real record it refuses
-      // every publish there is: his private circles are core, health, money, people, school,
-      // therapy, wellness and workshop, and his public fact sheet says "10 core mechanics" and
-      // "help other people understand me" (2026-09-21, HQ-1199). So the name is matched only
+      // every publish there is: private circles are named with ordinary words (a circle called
+      // "core" or "people"), and a public fact sheet uses those words in plain prose ("10 core
+      // mechanics", "help other people understand me") (2026-09-21, HQ-1199). So the name is matched only
       // between slashes, and the id and namespace, which the word match never looked at, are
       // matched literally. The gap this leaves, stated so the next reader does not rediscover it:
       // a distinctive circle name written as bare prose passes.
@@ -188,7 +232,7 @@ export function buildPublicExport(evda, { circleName = null, publishedAt = new D
     }
   }
 
-  return { manifest, files: loaded, sealedCut };
+  return { manifest, files: loaded, sealedCut, provenanceCut };
 }
 
 export function canonicalManifest(manifest) {
@@ -259,6 +303,7 @@ export async function publishCommand(dir, circleName, { out, key }) {
   console.log(`published ${built.files.length} file(s) from the public circle to ${at} (${built.files.length - marked - views.length} by path, ${marked} by mark${views.length ? `, ${views.length} rendered from ${drawn} entries` : ""})`);
   for (const f of views) console.log(`  view  ${f.path}  rendered from ${f.sources.length} entries (${f.view})`);
   if (built.sealedCut) console.log(`  ${built.sealedCut} sealed section(s) left out of the files they sit in`);
+  if (built.provenanceCut) console.log(`  ${built.provenanceCut} file(s) exported without their sources: provenance`);
   console.log(`CHECKED ${built.files.length} public members, signed by ${signed.publicKey}`);
   return 0;
 }

package/lib/record.mjs

@@ -98,3 +98,57 @@ export function moment(evda, { from, to = from } = {}) {
   out.entries.sort((a, b) => (a.date === b.date ? a.path.localeCompare(b.path) : a.date.localeCompare(b.date)));
   return out;
 }
+
+// What a reader needs from each section of a file to know what it was about without opening it
+// (HQ-2324): its heading, its context line (the one line the filing agent wrote above the owner's
+// words, `Context, not their words:` or `*Context (Iris, ...): ...*`), and the opening of the
+// owner's words, cut at a word. A day file's headings are mostly times (`## 20:13`), so a heading
+// alone told a chat app nothing about his last days. Text before the first heading is a section
+// with no heading. Frontmatter, fences and the one-line marker a sealed part leaves are skipped.
+export const OPENING_MAX = 280;
+const CONTEXT_MAX = 240;
+const CONTEXT_LINE = /^\*{0,2}_?\s*Context\b[^:]*:/i;
+
+function cutAt(text, max) {
+  if (text.length <= max) return text;
+  const cut = text.slice(0, max);
+  const at = cut.lastIndexOf(" ");
+  return `${at > max / 2 ? cut.slice(0, at) : cut}...`;
+}
+
+export function sectionDigest(text, { openingMax = OPENING_MAX } = {}) {
+  let body = text;
+  if (body.startsWith("---")) {
+    const end = body.indexOf("\n---", 3);
+    if (end !== -1) body = body.slice(end + 4);
+  }
+  const out = [];
+  let cur = { heading: null, lines: [] };
+  let fence = false;
+  const flush = () => {
+    const lines = cur.lines.map((l) => l.trim()).filter((l) => l && !/^\[sealed[:\]]/i.test(l));
+    const ctxAt = lines.findIndex((l) => CONTEXT_LINE.test(l));
+    const context = ctxAt === -1 ? null : cutAt(lines[ctxAt].replace(/^[*_\s]+|[*_\s]+$/g, ""), CONTEXT_MAX);
+    const words = lines.filter((_, i) => i !== ctxAt)
+      .map((l) => l.replace(/^>\s?/, "").replace(/^>\s?/, "").trim())
+      .filter(Boolean)
+      .join(" ")
+      .replace(/\s+/g, " ")
+      .trim();
+    if (cur.heading !== null || context || words) out.push({ heading: cur.heading, context, opening: words ? cutAt(words, openingMax) : null });
+  };
+  for (const line of body.split("\n")) {
+    if (/^\s*(`{3,}|~{3,})/.test(line)) { fence = !fence; continue; }
+    if (fence) continue;
+    const h = /^#{1,6} (.*)$/.exec(line);
+    if (h) { flush(); cur = { heading: h[1].trim(), lines: [] }; continue; }
+    cur.lines.push(line);
+  }
+  flush();
+  return out;
+}
+
+// The date a heading names (`## 2026-10-02, morning: ...`, `## October 4 (added 2026-10-04)`), or null.
+export function headingDate(heading) {
+  return /\b(\d{4}-\d{2}-\d{2})\b/.exec(heading ?? "")?.[1] ?? null;
+}

package/lib/routines.mjs

@@ -243,7 +243,17 @@ export function uninstallLaunchd(key, dir, { env = process.env, home = env.HOME
 // What setup does with the routines it was given (HQ-1246). On a Mac each is installed as a launchd
 // job; elsewhere nothing can be scheduled from here, so it prints the Claude desktop steps and says
 // so. Returns the lines to print.
-export function installAtSetup(keys, dir, { env = process.env, platform = process.platform } = {}) {
+//
+// `say` prints a line at once, before anything is installed (HQ-1368): a run with --yes asks nothing,
+// so the line that a launchd job is about to be loaded into this Mac is said before launchctl runs,
+// not only in the summary after it. `launchctl` is the tests' stand-in, handed through to
+// installLaunchd with loading on, so a test can watch the order without the real launchctl.
+export function setupNotice(key, dir) {
+  const r = ROUTINES[key];
+  return `Installing a launchd job on this Mac: ${r.title}, ${r.when.toLowerCase()}, runs ${r.command.join(" ")} on ${resolve(dir)} with your own Claude. Not wanted: create-evda --no-routines, or afterwards evda routine ${key} ${resolve(dir)} --uninstall`;
+}
+
+export function installAtSetup(keys, dir, { env = process.env, platform = process.platform, say = null, launchctl = null } = {}) {
   const lines = [];
   for (const key of keys) {
     const r = ROUTINES[key];
@@ -251,7 +261,8 @@ export function installAtSetup(keys, dir, { env = process.env, platform = proces
     if (platform === "darwin") {
       let done;
       try {
-        done = installLaunchd(key, dir, { env });
+        if (say && !falsified(env, "silent-install")) say(setupNotice(key, dir));
+        done = installLaunchd(key, dir, launchctl ? { env, launchctl, load: true } : { env });
       } catch (e) {
         if (e.code !== "TEMP_RECORD") throw e;
         lines.push(e.message);

package/lib/takeout.mjs

@@ -0,0 +1,169 @@
+// Google Takeout's sidecars (HQ-1368). Takeout writes a `.json` file beside each photo and each Keep
+// note, holding what the app knew about it: when a photo was taken, its caption, when a note was made
+// and last edited. Gathered as files of their own they became captures while their photo or note went
+// somewhere else (the 2026-09-27 trial). So a gather pairs each sidecar with the file it describes,
+// folds the sidecar's date and caption into that file's entry, and never places the sidecar itself.
+//
+// The names Takeout gives them, all paired here:
+//   IMG_1.jpg.json                                  the older name
+//   IMG_1.jpg.supplemental-metadata.json            the newer one
+//   IMG_1.jpg.supplemental-metad.json, .supp.json   cut short: Takeout caps a name near 51 characters
+//   <the first 40-odd characters of a long name>.json   the photo's own name cut short
+//   IMG_1.jpg(1).json, IMG_1.jpg.supplemental-metadata(1).json   the sidecar of IMG_1(1).jpg
+//   Note.json                                       a Keep note's, beside Note.html
+// A photo's `-edited` copy has no sidecar of its own and shares its original's.
+//
+// What is folded, and what is not: a photo's date taken (`photoTakenTime.timestamp`, UTC epoch seconds,
+// kept to the second) and whether it has a caption; a Keep note's created and edited times. Its place
+// (`geoData`) and the people Google tagged in it are never read into the proposal or the record. The
+// caption is the owner's words, so the proposal only says there is one; apply reads it again from the
+// sidecar, unchanged since the gather, and keeps it on the record's gathered list beside the photo.
+//
+//   pairSidecars(files, read)   { folded: Map<rel, facts>, sidecars: [{ rel, why, of }] }
+//   captionOf(buf)              the caption a photo sidecar holds, or null
+//
+// EVDA_GATHER_FALSIFY=sidecars-as-entries turns the pairing off, so the tests can show their checks fail
+// without it (TAKEOUT_FALSIFY_MODES).
+
+import { createHash } from "node:crypto";
+import { basename, dirname, extname } from "node:path";
+import { secretShape } from "./references.mjs";
+
+export const TAKEOUT_FALSIFY_MODES = ["sidecars-as-entries"];
+const falsified = (mode) => (process.env.EVDA_GATHER_FALSIFY ?? "").split(",").map((s) => s.trim()).includes(mode);
+const sha256 = (buf) => createHash("sha256").update(buf).digest("hex");
+
+// The files a sidecar describes: what Takeout exports from Photos, and Keep's notes.
+const MEDIA_EXT = new Set([".jpg", ".jpeg", ".png", ".gif", ".heic", ".heif", ".webp", ".tif", ".tiff", ".bmp", ".dng", ".raw", ".cr2", ".nef", ".arw", ".mp4", ".mov", ".m4v", ".avi", ".3gp", ".mkv", ".mpg", ".webm", ".mp"]);
+const NOTE_EXT = new Set([".html", ".htm", ".txt", ".md"]);
+const SUPPLEMENTAL = "supplemental-metadata";
+// Takeout's sidecar names run to about 51 characters; a photo's own name is cut from about 46.
+const CUT_AT = 30;
+const SIDECAR_MAX = 1024 * 1024;
+
+// The name a sidecar describes, from the sidecar's own name: { target, n, marked }, or null for a name
+// that is not `.json`. `n` is Takeout's "(1)" copy number; `marked` says the name carries the
+// supplemental-metadata marker, whole or cut short.
+export function sidecarTarget(name) {
+  if (!/\.json$/i.test(name)) return null;
+  let stem = name.slice(0, -5);
+  let n = null;
+  const copy = /\((\d+)\)$/.exec(stem);
+  if (copy) { n = copy[1]; stem = stem.slice(0, copy.index); }
+  let marked = false;
+  const tail = /\.([a-z-]*)$/i.exec(stem);
+  if (tail && SUPPLEMENTAL.startsWith(tail[1].toLowerCase())) {
+    const before = stem.slice(0, tail.index);
+    if (/\.[a-z0-9]{2,5}$/i.test(before) || tail[1].length >= 4) { stem = before; marked = true; }
+  }
+  return { target: stem, n, marked };
+}
+
+// What kind of Takeout file a parsed JSON value is: "photo", "keep", "album", or null.
+export function takeoutShape(v) {
+  if (!v || typeof v !== "object" || Array.isArray(v)) return null;
+  if (v.photoTakenTime || (v.creationTime && (v.title !== undefined || v.imageViews !== undefined))) return "photo";
+  if (v.createdTimestampUsec !== undefined || v.userEditedTimestampUsec !== undefined) return "keep";
+  if (v.albumData || (v.title !== undefined && v.date?.timestamp !== undefined && v.access !== undefined)) return "album";
+  return null;
+}
+
+// Seconds or microseconds since the epoch, as Takeout writes them, to an ISO time in UTC.
+const iso = (ms) => new Date(ms).toISOString().replace(/\.000Z$/, "Z");
+const seconds = (x) => (/^\d{1,12}$/.test(String(x ?? "").trim()) ? Number(String(x).trim()) : null);
+const usec = (x) => (/^\d{1,18}$/.test(String(x ?? "").trim()) ? Math.floor(Number(String(x).trim()) / 1000) : null);
+
+// The facts a sidecar folds into its file's entry. Nothing from geoData or people is read.
+function factsOf(v, shape) {
+  const out = {};
+  if (shape === "photo") {
+    const e = seconds(v.photoTakenTime?.timestamp);
+    if (e !== null) { out.takenEpoch = e; out.taken = iso(e * 1000); }
+    if (captionText(v)) out.caption = true;
+  } else if (shape === "keep") {
+    const c = usec(v.createdTimestampUsec);
+    const e = usec(v.userEditedTimestampUsec);
+    if (c !== null && c > 0) out.created = iso(c);
+    if (e !== null && e > 0) out.edited = iso(e);
+  }
+  return out;
+}
+
+// A caption, unless it is empty or shaped like a secret (then it is folded nowhere).
+function captionText(v) {
+  const t = typeof v?.description === "string" ? v.description.trim() : "";
+  if (!t || t.split("\n").some(secretShape)) return null;
+  return t;
+}
+
+export function captionOf(buf) {
+  try { return captionText(JSON.parse(buf.toString("utf8"))); } catch { return null; }
+}
+
+const withN = (name, n) => {
+  const ext = extname(name);
+  return ext ? `${name.slice(0, -ext.length)}(${n})${ext}` : `${name}(${n})`;
+};
+
+// Pair every sidecar in a walked source with the file it describes. `files` are the walk's
+// { rel, abs, size }, `read(abs)` their bytes. Returns { folded, sidecars }: `folded` maps a file's rel
+// to the facts its sidecar gave it, `sidecars` lists every sidecar with why it was not placed and, when
+// it has one, the file it describes (`of`).
+export function pairSidecars(files, read) {
+  const folded = new Map();
+  const sidecars = [];
+  if (falsified("sidecars-as-entries")) return { folded, sidecars };
+  const byDir = new Map();
+  for (const f of files) {
+    const d = dirname(f.rel);
+    byDir.set(d, [...(byDir.get(d) ?? []), f]);
+  }
+  for (const [dir, here] of byDir) {
+    const others = here.filter((f) => !/\.json$/i.test(f.rel));
+    const names = new Map(others.map((f) => [basename(f.rel), f]));
+    for (const f of here) {
+      const name = basename(f.rel);
+      const t = sidecarTarget(name);
+      if (!t) continue;
+      let v = null;
+      let bad = null;
+      if (f.size > SIDECAR_MAX) bad = "too large to be a sidecar";
+      else {
+        const text = read(f.abs).toString("utf8");
+        try { v = JSON.parse(text); } catch { bad = "not valid JSON"; }
+      }
+      const shape = v ? takeoutShape(v) : null;
+      const named = t.marked || MEDIA_EXT.has(extname(t.target).toLowerCase()) || NOTE_EXT.has(extname(t.target).toLowerCase());
+      // A .json that is neither shaped nor named like a sidecar is an ordinary file of the pile.
+      if (!shape && !named) continue;
+      if (shape === "album") { sidecars.push({ rel: f.rel, why: "Google Photos' details of the album this folder holds; not an entry of its own", sidecar: true }); continue; }
+      // The file it describes, in this folder.
+      let match = null;
+      if (t.n) match = names.get(withN(t.target, t.n)) ?? null;
+      else match = names.get(t.target) ?? null;
+      if (!match && !t.n) {
+        const same = others.filter((o) => basename(o.rel, extname(o.rel)) === t.target);
+        const notes = same.filter((o) => NOTE_EXT.has(extname(o.rel).toLowerCase()));
+        match = (notes.length === 1 ? notes[0] : same.length === 1 ? same[0] : null);
+      }
+      if (!match && !t.n && t.target.length >= CUT_AT) {
+        const cut = others.filter((o) => basename(o.rel).startsWith(t.target));
+        if (cut.length === 1) match = cut[0];
+      }
+      if (!match) {
+        sidecars.push({ rel: f.rel, why: bad ? `a Takeout sidecar that is ${bad}, and no file it describes is beside it; nothing read from it` : `a Takeout sidecar for ${t.n ? withN(t.target, t.n) : t.target}, which is not in the pile; placed nowhere`, sidecar: true, unmatched: true });
+        continue;
+      }
+      const facts = bad ? {} : factsOf(v, shape ?? "photo");
+      sidecars.push({ rel: f.rel, of: match.rel, why: bad ? `a Takeout sidecar for ${basename(match.rel)} that is ${bad}; nothing read from it, and ${basename(match.rel)} is placed without it` : `Google Takeout's details of ${basename(match.rel)}, folded into its entry`, sidecar: true, ...(bad ? { malformed: true } : {}) });
+      if (bad) continue;
+      const fold = { sidecar: f.rel, sha256: sha256(read(f.abs)), ...facts };
+      folded.set(match.rel, fold);
+      // A photo's edited copy has no sidecar of its own: it is the same moment.
+      const ext = extname(match.rel);
+      const edited = names.get(`${basename(match.rel, ext)}-edited${ext}`);
+      if (edited && !folded.has(edited.rel)) folded.set(edited.rel, { ...fold, sharedWith: match.rel });
+    }
+  }
+  return { folded, sidecars };
+}