strom-research 1.0.0

package/dist/core/people.js

@@ -0,0 +1,283 @@
+// Person helpers: names, life spans, relatives, and resolving a reference
+// ("P0039", "Antonín Víšek", "visek antonin") to exactly one person.
+import { AmbiguousError, UsageError } from "./errors.js";
+import { dateYears, yearLabel } from "./gdate.js";
+import { foldText, tokens } from "./text.js";
+/**
+ * Parse "Jan /Novák/", "Jan Novák" (last word = surname) or "/Novák/". The
+ * surname runs from the first slash to the last: "/⟨K/Č⟩emenská/" keeps its
+ * inner slash for the caller to refuse (actions) or replace (import).
+ */
+export function parseName(input) {
+    const s = input.trim().replace(/\s+/g, " ");
+    const m = /^([^/]*?)\s*\/(.*)\/\s*([^/]*)$/.exec(s);
+    if (m) {
+        const given = [m[1], m[3]].filter(Boolean).join(" ").trim();
+        return { given, surname: (m[2] ?? "").trim() };
+    }
+    const parts = s.split(" ");
+    if (parts.length === 1)
+        return { given: s, surname: "" };
+    return { given: parts.slice(0, -1).join(" "), surname: parts[parts.length - 1] };
+}
+/** Words that describe a person instead of naming them (folded): stillborn, unbaptised, N.N. */
+const DESCRIPTIONS = new Set([
+    "nn", "n n", "nomen nescio", "unnamed", "unknown", "stillborn", "still born", "infant", "child", "son", "daughter",
+    "mrtve narozeny", "mrtve narozena", "mrtve narozene", "mrtvy narozen", "mrtva narozena", "mrtvorozeny", "mrtvorozena", "mrtvorozene",
+    "nepokrteny", "nepokrtena", "nepokrtene", "nekrtenec", "bez jmena", "neznamy", "neznama", "dite", "syn", "dcera",
+    "totgeboren", "totgeborenes kind", "ungetauft", "namenlos", "kind", "sohn", "tochter",
+    "martwo urodzony", "martwo urodzona", "martwo urodzone", "nieochrzczony", "nieochrzczona", "dziecko",
+    "sans nom", "mort ne", "mort nee", "inconnu", "inconnue", "enfant", "proles", "infans", "filius", "filia",
+]);
+/**
+ * Why a given name is not a name, or undefined: a description in brackets or
+ * a word like "stillborn" is what the record says ABOUT the person — it goes
+ * to a fact or a note, the name stays empty ("/Novák/").
+ */
+export function notAName(given) {
+    const g = given.trim();
+    if (!g)
+        return undefined;
+    if (/^[(\[{].*[)\]}]$/su.test(g))
+        return `"${g}" is a description in brackets, not a name`;
+    const words = foldText(g).replace(/[^\p{L}\p{N}]+/gu, " ").trim();
+    if (DESCRIPTIONS.has(words))
+        return `"${g}" describes the person, it is not a name`;
+    return undefined;
+}
+/**
+ * The same name: letter for letter (case aside), whatever its kind. "Višek"
+ * and "Víšek" are two spellings — a variant worth keeping, not one name.
+ */
+export function sameName(a, b) {
+    const key = (n) => formatName(n).normalize("NFC").toLowerCase();
+    return key(a) === key(b);
+}
+export function formatName(n) {
+    return [n.given, n.surname].filter(Boolean).join(" ") || "?";
+}
+/** GEDCOM keeps the surname between two slashes: a slash inside a name part is written as "|". */
+export function gedcomName(n) {
+    const part = (s) => s.replace(/\//g, "|");
+    return `${part(n.given)} /${part(n.surname)}/`.trim();
+}
+/** Why a name cannot be kept as it is, or undefined: a slash inside it ("/⟨K/Č⟩emenská/", "Jan /Novák"). */
+export function slashInName(n) {
+    const bad = [n.given, n.surname].find((s) => s.includes("/"));
+    return bad === undefined ? undefined : `"${bad}": a slash inside a name — only the surname goes between two slashes ("Jan /Novák/")`;
+}
+export function primaryName(p) {
+    return p.names.find((n) => !n.kind || n.kind === "birth") ?? p.names[0] ?? { given: "", surname: "" };
+}
+export function displayName(p) {
+    return formatName(primaryName(p));
+}
+const STATUS_RANK = { proven: 0, probable: 1, possible: 2, lead: 3 };
+/** Best-supported first: status, then the number of citations, then the order they were added. */
+export function byPreference(a, b) {
+    return (STATUS_RANK[a.status] ?? 9) - (STATUS_RANK[b.status] ?? 9) || b.citations.length - a.citations.length;
+}
+/** The fact of a kind that counts: the best-supported one that is not retracted or disproven. */
+export function preferred(events, kind) {
+    return events.filter((e) => e.kind === kind && !e.retracted && e.status !== "disproven").sort(byPreference)[0];
+}
+/**
+ * Events in the order a GEDCOM reader should see them: for each kind the
+ * preferred one first (readers take the first BIRT as the birth), kinds in
+ * the order they first appear.
+ */
+export function preferredOrder(events) {
+    const kinds = [...new Set(events.map((e) => e.kind))];
+    return kinds.flatMap((k) => events.filter((e) => e.kind === k).sort(byPreference));
+}
+function firstEvent(p, kinds) {
+    for (const k of kinds) {
+        const e = preferred(p.events, k);
+        if (e)
+            return e;
+    }
+    return undefined;
+}
+export function birthEvent(p) {
+    return firstEvent(p, ["BIRT", "CHR", "BAPM"]);
+}
+export function deathEvent(p) {
+    return firstEvent(p, ["DEAT", "BURI", "CREM"]);
+}
+/** "1811–1892", "*1811", "†1892" or "". */
+export function lifespan(p) {
+    const b = birthEvent(p)?.date;
+    const d = deathEvent(p)?.date;
+    if (b && d)
+        return `${yearLabel(b)}–${yearLabel(d)}`;
+    if (b)
+        return `*${yearLabel(b)}`;
+    if (d)
+        return `†${yearLabel(d)}`;
+    return "";
+}
+export function label(p) {
+    const span = lifespan(p);
+    return `${p.id} ${displayName(p)}${span ? ` (${span})` : ""}`;
+}
+const relCache = new WeakMap();
+function relIndex(tree) {
+    const cached = relCache.get(tree);
+    if (cached && cached.version === tree.version)
+        return cached;
+    const idx = { version: tree.version, asChild: new Map(), asPartner: new Map() };
+    for (const f of tree.list("family")) {
+        if (f.retracted)
+            continue;
+        for (const c of f.children)
+            idx.asChild.set(c.person, [...(idx.asChild.get(c.person) ?? []), f]);
+        for (const p of f.partners)
+            idx.asPartner.set(p, [...(idx.asPartner.get(p) ?? []), f]);
+    }
+    relCache.set(tree, idx);
+    return idx;
+}
+/** How a child is related to one partner of its family: its own relation to them, else the family's. */
+export function relationTo(link, partner) {
+    return link.relations?.[partner] ?? link.relation;
+}
+/** The family a child was born into: born to every partner of it. */
+export function isBirthFamily(f, child) {
+    const link = f.children.find((c) => c.person === child);
+    if (!link)
+        return false;
+    return f.partners.length ? f.partners.every((p) => relationTo(link, p) === "birth") : link.relation === "birth";
+}
+export function familiesAsChild(tree, id) {
+    return relIndex(tree).asChild.get(id) ?? [];
+}
+export function familiesAsPartner(tree, id) {
+    return relIndex(tree).asPartner.get(id) ?? [];
+}
+export function parentsOf(tree, id) {
+    const out = [];
+    for (const f of familiesAsChild(tree, id)) {
+        const link = f.children.find((c) => c.person === id);
+        for (const pid of f.partners) {
+            const rel = relationTo(link, pid);
+            if (rel !== "birth" && rel !== "unknown")
+                continue;
+            const p = tree.get(pid);
+            if (p && !p.retracted && !out.includes(p))
+                out.push(p);
+        }
+    }
+    return out;
+}
+/** Generation numbers of ancestors: focus = 1, parents = 2, ... */
+export function ancestorGenerations(tree, focus, max = 50) {
+    const gen = new Map([[focus, 1]]);
+    let frontier = [focus];
+    for (let g = 2; g <= max && frontier.length > 0; g++) {
+        const next = [];
+        for (const id of frontier)
+            for (const parent of parentsOf(tree, id))
+                if (!gen.has(parent.id)) {
+                    gen.set(parent.id, g);
+                    next.push(parent.id);
+                }
+        frontier = next;
+    }
+    return gen;
+}
+// ── resolving references ───────────────────────────────────────────────────
+function candidateLabel(tree, p) {
+    const parents = parentsOf(tree, p.id).map(displayName);
+    const place = birthEvent(p)?.place;
+    return [label(p), place ? `born ${place}` : "", parents.length ? `child of ${parents.join(" & ")}` : ""].filter(Boolean).join(", ");
+}
+export function findPersons(tree, query) {
+    const q = tokens(query);
+    if (q.length === 0)
+        return [];
+    return tree
+        .list("person")
+        .filter((p) => !p.retracted)
+        .filter((p) => {
+        const hay = p.names.flatMap((n) => tokens(`${n.given} ${n.surname}`));
+        return q.every((t) => hay.some((h) => h === t || h.startsWith(t)));
+    });
+}
+export function resolvePerson(tree, ref) {
+    const id = ref.trim().toUpperCase();
+    if (/^P\d+$/.test(id)) {
+        const p = tree.get(id.length < 5 ? "P" + id.slice(1).padStart(4, "0") : id);
+        if (!p)
+            throw new UsageError(`no person ${ref}`, { hint: "strom person list" });
+        if (p.mergedInto)
+            throw new UsageError(`${p.id} was merged into ${p.mergedInto}`, { hint: `strom person show ${p.mergedInto}` });
+        return p;
+    }
+    const hits = findPersons(tree, ref);
+    if (hits.length === 1)
+        return hits[0];
+    if (hits.length === 0)
+        throw new UsageError(`no person matches "${ref}"`, { hint: `strom person list ${foldText(ref).split(" ").pop() ?? ""}`.trim() });
+    // Exact full-name match wins over prefix matches.
+    const exact = hits.filter((p) => p.names.some((n) => foldText(formatName(n)) === foldText(ref)));
+    if (exact.length === 1)
+        return exact[0];
+    throw new AmbiguousError(ref, hits.map((p) => ({ id: p.id, label: candidateLabel(tree, p) })));
+}
+/** Surnames that may be one family name: "Víšek"/"Víšková", "Nowak"/"Nowakowa", "Novotný"/"Novotná"; an unknown one fits any. */
+export function sameSurname(a, b) {
+    const fa = foldText(a);
+    const fb = foldText(b);
+    if (!fa || !fb || fa === fb)
+        return true;
+    const stem = (x) => x.replace(/(ova|owa|ovna|owna|ina)$/, "").replace(/([a-z])(a|y|i)$/, "$1");
+    return stem(fa) === stem(fb);
+}
+/**
+ * People of `ids` (an imported tree) who are probably people already in the
+ * tree: the same first given name, a fitting surname in any of their names,
+ * the same sex and birth years at most three apart. A hint to check — never
+ * merged without a look.
+ */
+export function likelyDuplicates(tree, ids) {
+    const out = [];
+    const inSet = new Set(ids);
+    const others = tree.list("person").filter((p) => !p.retracted && !inSet.has(p.id));
+    const first = (n) => foldText(n.given).split(" ")[0] ?? "";
+    const year = (p) => dateYears(birthEvent(p)?.date ?? "")[0];
+    for (const id of ids) {
+        const p = tree.get(id);
+        if (!p || p.retracted)
+            continue;
+        for (const o of others) {
+            if (p.sex !== "U" && o.sex !== "U" && p.sex !== o.sex)
+                continue;
+            const names = p.names.some((n) => o.names.some((m) => first(n) && first(n) === first(m) && sameSurname(n.surname, m.surname)));
+            if (!names)
+                continue;
+            const [a, b] = [year(p), year(o)];
+            if (a !== undefined && b !== undefined && Math.abs(a - b) > 3)
+                continue;
+            out.push({ person: p, same: o });
+        }
+    }
+    // A wife under her married name is found through her husband: the partner of a
+    // likely duplicate, with the same first given name, is likely the same too.
+    const found = new Set(out.map((d) => d.person.id));
+    for (const d of [...out])
+        for (const f of familiesAsPartner(tree, d.person.id))
+            for (const pid of f.partners.filter((x) => x !== d.person.id && inSet.has(x) && !found.has(x))) {
+                const p = tree.get(pid);
+                for (const g of familiesAsPartner(tree, d.same.id))
+                    for (const oid of g.partners.filter((x) => x !== d.same.id)) {
+                        const o = tree.get(oid);
+                        if (!o || o.retracted || (p.sex !== "U" && o.sex !== "U" && p.sex !== o.sex))
+                            continue;
+                        if (!p.names.some((n) => o.names.some((m) => first(n) && first(n) === first(m))))
+                            continue;
+                        out.push({ person: p, same: o });
+                        found.add(pid);
+                    }
+            }
+    return out;
+}

package/dist/core/phrases.js

@@ -0,0 +1,85 @@
+// Texts strom itself writes into a research (the tasks it proposes: frontier,
+// intake) are in the research language, like everything the agent writes.
+// English is built in; a language adds assets/lang/<code>.json with the same
+// keys (any it leaves out stay English). {name} marks a value filled in.
+import { readAsset } from "./assets.js";
+export const PHRASES = {
+    "estimate.marriage": "their marriage {year}",
+    "estimate.child": "the eldest child known, {year}",
+    "reason.unknown": "parents unknown",
+    "reason.unproven": "parents not proven by a record",
+    "born.about": " (born ~{year}, estimated from {from})",
+    "the.birthplace": "the birthplace",
+    "whole.book": "the whole book",
+    "link.what": "Baptism of {name}{place}{about}",
+    "link.place": ", {place}",
+    "link.why": "{reason}; the baptism entry names both parents (generation {generation} of {research})",
+    "link.done": "entry found and recorded with its parents — or {years} searched without it",
+    "locate.what": "Where are the baptisms of {place}{around}? (for {name}{about})",
+    "locate.around": " around {year}",
+    "locate.where": "jurisdiction of {place}",
+    "locate.where.unknown": "birthplace unknown — find it first",
+    "locate.years": ", years {from}–{to}",
+    "locate.why": "{reason}; no record set is known for the place and time",
+    "locate.done": "a record set with access (URL or call number) is recorded and a link task points at it",
+    "request.what": "Ask for the records of {name}: {tasks} found nothing",
+    "request.where": "the archive or parish holding the records of {place}, or the family",
+    "request.why": "{reason}; the record sets and archives known so far are exhausted",
+    "request.done": "a request is sent (strom task wait … --on \"<reply>\") or the user decides the line ends here",
+    "story.what": "Write the story of {name}",
+    "story.more.what": "Add to the story of {name}: {count} new facts",
+    "story.where": "the facts recorded (strom person show {id})",
+    "story.why": "{count} facts from records tell the life (generation {generation} of {research}); the family reads it in the Strom app's family book",
+    "story.done": "strom story set {id} with every fact it rests on (--fact) — a draft until the user approves it",
+    "session.user": "stopped by the user",
+    "session.run": "the run stopped before the session ended (interrupted, or the computer went down)",
+    "session.chat": "the conversation ended before the session was closed",
+    "session.agent": "the agent stopped ({outcome}) without closing the session",
+    "intake.files": "Analyse {count} files from {folder} ({first}–{last})",
+    "intake.the.material": "the material",
+    "intake.tree.imported": "Review imported tree {id} ({name})",
+    "intake.tree.read": "Read the family tree {id} ({name}), not imported",
+    "intake.text": "Process text {id}",
+    "intake.text.file": "Process text {id} ({name})",
+    "intake.other": "Analyse {id} ({name})",
+    "intake.why.imported": "{persons} persons came in as leads{matched}: they guide the research, they prove nothing.",
+    "intake.why.matched": ", {matched} matched existing persons",
+    "intake.why.read": "Registered without importing it: nothing of it is in the tree; what it says can guide the research, it proves nothing.",
+    "intake.why": "Material from the user: find out who and what it is about, and what it can prove.",
+    "intake.done.imported": "the leads are checked for obvious mistakes (duplicates, impossible dates) and the first locate/link tasks exist",
+    "intake.done.read": "what it adds to the tree is entered as leads citing it (strom source add … --kind family-tree --form authored --input {id}) — or the input is skipped with a reason (strom input skip {id} --reason …)",
+    "intake.done": "every person and fact in it is recorded (a source if it is an original document, leads otherwise) and cited — or the input is skipped with a reason (strom input skip I… --reason …)",
+};
+const catalogs = new Map();
+/**
+ * The catalog of a language (assets/lang/<code>.json); empty when there is none.
+ * It holds these phrases and the texts a person reads in the guided menu (ui.*, src/cli/ui.ts).
+ */
+export function catalog(lang) {
+    if (!/^[a-z]{2,3}$/.test(lang) || lang === "en")
+        return {};
+    if (!catalogs.has(lang)) {
+        let parsed = {};
+        try {
+            parsed = JSON.parse(readAsset("lang", `${lang}.json`) ?? "{}");
+        }
+        catch {
+            // a broken catalog must not stop the research: English it is
+        }
+        catalogs.set(lang, parsed);
+    }
+    return catalogs.get(lang);
+}
+/** A template with its {values} filled in (an unknown {name} stays as it is). */
+export function fill(template, values) {
+    return template.replace(/\{(\w+)\}/g, (m, name) => (name in values ? String(values[name]) : m));
+}
+/** A text of a language's catalog, or the English one where the catalog has none. */
+export function localized(lang, key, english, values = {}) {
+    const own = catalog(lang)[key];
+    return fill(typeof own === "string" && own ? own : english, values);
+}
+/** A text in the research language, its {values} filled in. */
+export function phrase(lang, key, values = {}) {
+    return localized(lang, key, PHRASES[key], values);
+}

package/dist/core/queue.js

@@ -0,0 +1,113 @@
+// The order of the task queue. A research spreads out: the nearest ancestors
+// first, but no line takes every session — a line that just had sessions waits
+// while the others get theirs, a task tried again and again sinks instead of
+// being taken forever, and work that needs a download comes after what can be
+// done now. Strategies (setting queue.strategy): balanced (the default), depth
+// (stay on the line of the last sessions), priority (strict priority).
+import { parentsOf } from "./people.js";
+import { taskRecordsets } from "./frontier.js";
+import { now } from "./tree.js";
+import { subjectPeople } from "./records.js";
+export const LEVEL_ORDER = { intake: 0, locate: 1, link: 2, verify: 3, enrich: 4, request: 5, narrate: 6 };
+/** Levels that read records: without images of their record sets they can only ask the user for them. */
+const NEEDS_IMAGES = new Set(["link", "verify"]);
+/** How many of the last sessions count as "recent" when spreading the work over the lines. */
+const RECENT = 4;
+/** A generation for work about no ancestor (a sibling, a side line, a book): after the close ancestors. */
+const OFF_LINE_GENERATION = 4;
+/** A task that needs images none of its record sets has yet. */
+export function lacksImages(tree, t, withImages = new Set(tree.list("media").map((m) => m.recordset))) {
+    return NEEDS_IMAGES.has(t.level) && !taskRecordsets(tree, t).sets.some((b) => withImages.has(b.id));
+}
+export function effectiveState(t, today) {
+    if (t.state === "parked" && t.parkedUntil && t.parkedUntil <= today)
+        return "open";
+    return t.state;
+}
+/**
+ * Every ancestor of the focus with its generation and its line: the focus, each
+ * parent and each grandparent are lines of their own; everyone further back
+ * belongs to the line of the grandparent they descend through.
+ */
+export function ancestorLines(tree, focus, max = 50) {
+    const out = new Map([[focus, { gen: 1, line: focus }]]);
+    let current = [focus];
+    for (let g = 2; g <= max && current.length; g++) {
+        const next = [];
+        for (const id of current)
+            for (const p of parentsOf(tree, id))
+                if (!out.has(p.id)) {
+                    out.set(p.id, { gen: g, line: g <= 3 ? p.id : out.get(id).line });
+                    next.push(p.id);
+                }
+        current = next;
+    }
+    return out;
+}
+/** The open tasks in the order to work on them, each with the reason. */
+export function rankTasks(tree, tasks, strategy = "balanced") {
+    const today = now().slice(0, 10);
+    const open = tasks.filter((t) => ["open", "doing"].includes(effectiveState(t, today)));
+    const withImages = new Set(tree.list("media").map((m) => m.recordset));
+    const researches = tree.list("research");
+    const lines = new Map();
+    const linesOf = (researchId) => {
+        const r = researches.find((x) => x.id === researchId) ?? (researches.length === 1 ? researches[0] : undefined);
+        if (!r || r.direction !== "ancestors")
+            return undefined;
+        if (!lines.has(r.id))
+            lines.set(r.id, ancestorLines(tree, r.focus));
+        return lines.get(r.id);
+    };
+    /** The nearest ancestor a task is about: its generation and line. */
+    const place = (t) => {
+        const map = linesOf(t.research);
+        const found = [...t.subject, ...subjectPeople(tree, t.subject)].map((s) => map?.get(s)).filter((x) => !!x);
+        return found.sort((a, b) => a.gen - b.gen)[0];
+    };
+    const tasksById = new Map(tree.list("task").map((t) => [t.id, t]));
+    const ended = tree
+        .list("session")
+        .filter((s) => s.state !== "open" && s.task)
+        .sort((a, b) => (b.ended ?? b.updated).localeCompare(a.ended ?? a.updated));
+    const recentLines = ended.slice(0, RECENT).map((s) => {
+        const t = tasksById.get(s.task);
+        return t ? (place(t)?.line ?? `task:${t.id}`) : undefined;
+    });
+    const tries = new Map();
+    for (const s of ended)
+        tries.set(s.task, (tries.get(s.task) ?? 0) + 1);
+    const rows = open.map((t) => {
+        const at = place(t);
+        const gen = at?.gen ?? OFF_LINE_GENERATION;
+        const line = at?.line ?? `task:${t.id}`;
+        const recent = recentLines.filter((l) => l === line).length;
+        const tried = tries.get(t.id) ?? 0;
+        const intake = t.level === "intake" ? 3 : 0;
+        const score = strategy === "depth"
+            ? 2 * t.priority + intake + 2 * recent - 0.5 * (gen - 1) - 1.5 * tried
+            : strategy === "priority"
+                ? 0
+                : 2 * t.priority + intake - (gen - 1) - 2 * recent - 1.5 * tried;
+        const blocked = lacksImages(tree, t, withImages);
+        const why = [
+            t.state === "doing" ? "in progress" : undefined,
+            blocked ? "needs images the user has to download" : undefined,
+            `p${t.priority}`,
+            t.level === "intake" ? "the user's material" : at ? `generation ${gen}` : "not about an ancestor",
+            recent ? `its line had ${recent} of the last ${RECENT} sessions` : undefined,
+            tried ? `tried ${tried}×` : undefined,
+        ]
+            .filter(Boolean)
+            .join(" · ");
+        return { task: t, why, doing: t.state === "doing" ? 0 : 1, blocked: blocked ? 1 : 0, score, gen };
+    });
+    return rows
+        .sort((a, b) => a.doing - b.doing ||
+        // work that can be done now comes before work that waits for the user's download
+        a.blocked - b.blocked ||
+        (strategy === "priority" ? b.task.priority - a.task.priority || a.gen - b.gen : b.score - a.score) ||
+        (LEVEL_ORDER[a.task.level] ?? 9) - (LEVEL_ORDER[b.task.level] ?? 9) ||
+        a.task.created.localeCompare(b.task.created))
+        .map(({ task, why }) => ({ task, why }));
+}

package/dist/core/reader.js

@@ -0,0 +1,76 @@
+// Readers: an agent with a clean context that looks at a batch of images and
+// writes down what is on them — and nothing else. The main researcher gets
+// back a short report instead of a context full of images.
+//
+// From measurements in earlier research: an image stays in the context of whoever
+// opened it and is paid for on every later turn, so the cost of a reader grows
+// with the square of its batch; ten images per reader cost a third per image
+// of fifty. Readers never write to the research; the researcher records what
+// they found (and what they did not: a search "by reader").
+export const BATCH = 10;
+export const BATCH_MAX = 12;
+/** Split into batches of at most `size` images (never more than BATCH_MAX). */
+export function batches(items, size = BATCH) {
+    const n = Math.max(1, Math.min(BATCH_MAX, size));
+    const out = [];
+    for (let i = 0; i < items.length; i += n)
+        out.push(items.slice(i, i + n));
+    return out;
+}
+export function readerPrompt(o) {
+    return `You are a READER for a genealogical research. You are not the researcher: you do not decide
+anything and you do not write anywhere except your report file. Do not run any commands.
+
+THE QUESTION
+${o.question}
+${o.context ? `\nWhat the researcher knows (to recognise the family — never to fill in what you cannot read):\n${o.context}\n` : ""}${o.blind ? "\nThis is a BLIND reading: transcribe what is written, exactly; do not interpret or complete names from expectations.\n" : ""}
+THE IMAGES (open each file with your image reader, one at a time, in this order)
+${o.images
+        .map((i) => {
+        const head = `- ${i.id}${i.image !== undefined ? ` · image ${i.image}` : ""}${i.page ? ` · page ${i.page}` : ""}`;
+        return i.parts?.length
+            ? `${head} — ${i.parts.length} overlapping parts at full resolution, read them together:\n${i.parts.map((p) => `    ${p.label}: ${p.view}`).join("\n")}`
+            : `${head}: ${i.view}`;
+    })
+        .join("\n")}
+
+THE REPORT
+Write your report to ${o.report} AS YOU GO — after every image, not at the end.
+For every image, this block (in ${o.lang === "en" ? "English" : `the research language (${o.lang})`}; transcriptions in the language of the record;
+the words "Image", "result", "found", "nothing", "unclear" and "done" stay in English — strom reads them):
+
+## Image <image number> · <M… id>
+result: found | nothing | unclear
+entries: every entry that answers the question — word for word as written (the original
+  language and spelling), with the column it stands in: date, house, names, parents,
+  godparents/witnesses, remarks; one entry per line
+illegible: what you could not read, and where
+hand: the writing (ink, script, language, abbreviations)
+certainty: for each name in an entry, how sure you are (%)
+
+"nothing" is a valid and valuable result: say what you checked. "Illegible" beats a guess.
+When all images are done, finish with one line: "done: <n> images, found on <image numbers or none>".`;
+}
+/** The result of each image in a report ("## Image 114 · M0012" … "result: found"). */
+export function parseReport(text) {
+    const out = [];
+    const blocks = text.split(/^##\s+/m).slice(1);
+    for (const b of blocks) {
+        const head = b.split("\n")[0] ?? "";
+        const id = /\b(M\d{4,})\b/.exec(head)?.[1] ?? /Image\s+(\d+)/i.exec(head)?.[1];
+        if (!id)
+            continue;
+        const r = /^result:\s*(\p{L}+)/imu.exec(b)?.[1]?.toLowerCase();
+        out.push({ image: id, result: r === "found" ? "found" : r === "nothing" ? "nothing" : "unclear" });
+    }
+    return out;
+}
+/** Claude Code settings for a reader: it may read these views and write its report — nothing else. */
+export function readerSettings(views, report, toPermission) {
+    return {
+        permissions: {
+            allow: [...views.map((v) => `Read(${toPermission(v)})`), `Write(${toPermission(report)})`, `Edit(${toPermission(report)})`],
+            deny: ["Bash", "WebFetch", "WebSearch"],
+        },
+    };
+}

package/dist/core/records.js

@@ -0,0 +1,105 @@
+// Generic create / update for every record type, so commands stay small.
+// All writes still go through Tree.put (validation + seal).
+import { UsageError } from "./errors.js";
+import { RECORD_TYPES } from "./model.js";
+import { now, typeOfId } from "./tree.js";
+import { makeNote } from "./actions.js";
+/** Create a record of `type` with a fresh ID. */
+export function create(tree, type, fields, summary, targets = []) {
+    return tree.withTreeLock(() => {
+        const t = now();
+        const { note, ...rest } = fields;
+        const rec = {
+            id: tree.allocate(RECORD_TYPES[type].prefix),
+            type,
+            ...stripUndefined(rest),
+            notes: note ? [makeNote(tree, note)] : [],
+            created: t,
+            updated: t,
+        };
+        tree.put(rec, { op: `${type}.add`, targets: [rec.id, ...targets], summary: summary(rec.id) });
+        return rec;
+    });
+}
+/** Load, change and write a record. `reason` is required when facts change meaning. */
+export function update(tree, id, expect, change, op) {
+    if (typeOfId(id) !== expect)
+        throw new UsageError(`${id} is not a ${expect}`);
+    return tree.withTreeLock(() => {
+        const cur = tree.get(id);
+        if (!cur)
+            throw new UsageError(`no ${expect} ${id}`, { hint: `strom ${expect === "repository" ? "repo" : expect} list` });
+        const next = { ...change(structuredClone(cur)), updated: now() };
+        tree.put(next, {
+            op: op.op,
+            targets: [id, ...(op.targets ?? [])],
+            summary: op.summary,
+            ...(op.reason ? { reason: op.reason } : {}),
+        });
+        return next;
+    });
+}
+export function stripUndefined(o) {
+    const out = {};
+    for (const [k, v] of Object.entries(o)) {
+        if (v === undefined)
+            continue;
+        if (Array.isArray(v) || v === null || typeof v !== "object")
+            out[k] = v;
+        else
+            out[k] = stripUndefined(v);
+    }
+    return out;
+}
+/** Normalize an ID the user typed: "s12" -> "S0012". */
+export function normId(ref, type) {
+    const m = /^([A-Za-z])(\d+)$/.exec(ref.trim());
+    if (!m)
+        return ref.trim();
+    const id = m[1].toUpperCase() + m[2].padStart(4, "0");
+    if (type && typeOfId(id) !== type)
+        throw new UsageError(`${ref} is not a ${type} ID (${RECORD_TYPES[type].prefix}0001)`);
+    return id;
+}
+export function requireRecord(tree, ref, type) {
+    const id = normId(ref, type);
+    const rec = tree.get(id);
+    if (!rec)
+        throw new UsageError(`no ${type} ${id}`, { hint: `strom ${type === "repository" ? "repo" : type} list` });
+    if (rec.mergedInto)
+        throw new UsageError(`${id} was merged into ${rec.mergedInto}`, { hint: `strom ${type === "repository" ? "repo" : type} show ${rec.mergedInto}` });
+    return rec;
+}
+/** Repeatable option → array. Values are kept whole: free text may contain commas. */
+export function listOpt(v) {
+    if (v === undefined || v === false)
+        return [];
+    const arr = Array.isArray(v) ? v : [v];
+    return arr.map((x) => String(x).trim()).filter(Boolean);
+}
+/** Repeatable option whose values may also be comma separated: IDs, kinds, place lists. */
+export function csvOpt(v) {
+    return listOpt(v).flatMap((x) => x.split(",")).map((x) => x.trim()).filter(Boolean);
+}
+/** Read "@file" as the file's text, otherwise the value itself. */
+export function textOpt(v, readFile) {
+    if (typeof v !== "string")
+        return undefined;
+    if (v.startsWith("@"))
+        return readFile(v.slice(1));
+    return v;
+}
+/** The people a list of subjects names: the persons in it, and the people of the conflicts and hypotheses in it. */
+export function subjectPeople(tree, ids) {
+    const out = new Set();
+    for (const id of ids) {
+        const type = typeOfId(id);
+        if (type === "person")
+            out.add(id);
+        else if (type === "conflict" || type === "hypothesis")
+            for (const s of tree.get(id)?.subject ?? [])
+                if (typeOfId(s) === "person")
+                    out.add(s);
+    }
+    return [...out];
+}