strom-research 1.13.0-beta.6 → 1.13.0-beta.8

package/assets/lang/cs.json

@@ -769,6 +769,7 @@
   "ui.sync.do.title.user": "platí úprava z aplikace (verze výzkumu zůstane v historii)",
   "ui.sync.sex.changed": "{n}. {who}: pohlaví {text}",
   "ui.sync.note.new": "{n}. {who}: poznámka — „{text}“",
+  "ui.sync.note.changed": "{n}. {who}: poznámka — „{old}“ → „{new}“",
   "ui.sync.source.new": "{n}. pramen: „{text}“",
   "ui.sync.source.changed": "{n}. pramen z aplikace „{text}“: opravený přepis nebo stránka",
   "ui.sync.source.reading": "{n}. pramen výzkumu „{text}“: v aplikaci přečtený jinak",
@@ -809,6 +810,7 @@
   "ui.sync.place.located": "{n}. {place}: poloha na mapě {at}",
   "ui.sync.do.add": "přidá se jako vodítko",
   "ui.sync.do.correct": "opraví vodítko výzkumu",
+  "ui.sync.do.note.changed": "ten řádek poznámky výzkumu se opraví",
   "ui.sync.do.detail": "doplní se k údaji s odkazem na strom z aplikace",
   "ui.sync.do.refine": "doplní se k údaji s odkazem na strom z aplikace (záznamu nic neodporuje)",
   "ui.sync.do.conflict": "rozpor k rozhodnutí (výzkum to má ze záznamu)",
@@ -1283,6 +1285,7 @@
   "log.repository.retract": "Odvolaný archiv: {name}",
   "log.name.remove": "Odebrané jméno: {name} – {who}",
   "log.note.remove": "Odebraná poznámka: „{note}“ – {name}",
+  "log.note.edit": "Opravená poznámka: {name}",
   "log.event.status": "Změněná jistota údaje: {who} – {fact}",
   "log.event.restore": "Údaj znovu platí: {who} – {fact}",
   "log.input.sync.undo": "Vrácený rodokmen: {name}",

package/assets/lang/de.json

@@ -769,6 +769,7 @@
   "ui.sync.do.title.user": "Die eigene Änderung gilt (die der Forschung bleibt in ihrer Geschichte)",
   "ui.sync.sex.changed": "{n}. {who}: Geschlecht {text}",
   "ui.sync.note.new": "{n}. {who}: eine Notiz — „{text}“",
+  "ui.sync.note.changed": "{n}. {who}: eine Notiz — „{old}“ → „{new}“",
   "ui.sync.source.new": "{n}. eine Quelle: „{text}“",
   "ui.sync.source.changed": "{n}. eigene Quelle „{text}“: Abschrift oder Seite korrigiert",
   "ui.sync.source.reading": "{n}. die Quelle der Forschung „{text}“: anders gelesen",
@@ -809,6 +810,7 @@
   "ui.sync.place.located": "{n}. {place}: Lage auf der Karte {at}",
   "ui.sync.do.add": "als Hinweis übernommen",
   "ui.sync.do.correct": "berichtigt den Hinweis der Forschung",
+  "ui.sync.do.note.changed": "diese Zeile der Notiz der Forschung wird berichtigt",
   "ui.sync.do.detail": "wird der Angabe hinzugefügt, mit Verweis auf den eigenen Stammbaum",
   "ui.sync.do.refine": "wird der Angabe hinzugefügt, mit Verweis auf den eigenen Stammbaum (nichts widerspricht dem Eintrag)",
   "ui.sync.do.conflict": "ein Widerspruch zum Entscheiden (die Forschung hat es aus einem Eintrag)",
@@ -1283,6 +1285,7 @@
   "log.repository.retract": "Archiv zurückgezogen: {name}",
   "log.name.remove": "Name entfernt: {name} – {who}",
   "log.note.remove": "Notiz entfernt: „{note}“ – {name}",
+  "log.note.edit": "Notiz berichtigt: {name}",
   "log.event.status": "Sicherheit einer Angabe geändert: {who} – {fact}",
   "log.event.restore": "Angabe wieder gültig: {who} – {fact}",
   "log.input.sync.undo": "Stammbaum zurückgenommen: {name}",

package/dist/agents/global.js

@@ -93,36 +93,107 @@ function allowRules(agent) {
  */
 const TOML_BEGIN = "# strom: begin (strom agents install; removed by strom agents uninstall)";
 const TOML_END = "# strom: end";
-function grokWithout(text) {
-    const lines = text.split("\n");
-    const out = [];
-    let inside = false;
-    for (const l of lines) {
-        if (l.trim() === TOML_BEGIN)
-            inside = true;
-        else if (l.trim() === TOML_END)
-            inside = false;
-        else if (!inside)
-            out.push(l);
+const isTomlTable = (l) => /^\s*\[/.test(l);
+const isPermissionHeader = (l) => /^\s*\[permission\]\s*(#.*)?$/.test(l);
+const hasOwnAllow = (lines) => lines.some((l) => /^\s*allow\s*=/.test(l));
+/** A line of strom's own in config.toml: its [permission] header, or an allow list of nothing but strom's rules. */
+function isGrokStromLine(l) {
+    if (isPermissionHeader(l))
+        return true;
+    const m = /^\s*allow\s*=\s*\[(.*)\]\s*$/.exec(l);
+    const rules = m ? [...m[1].matchAll(/"([^"]*)"/g)].map((r) => r[1]) : [];
+    return rules.length > 0 && rules.every((r) => isStromRule("grok", r));
+}
+/** Strom's block among the lines of config.toml (split at \n): the lines of its begin and its end, or undefined. */
+function grokBlock(lines) {
+    const b = lines.findIndex((l) => l.trim() === TOML_BEGIN);
+    if (b < 0)
+        return undefined;
+    const e = lines.findIndex((l, i) => i > b && l.trim() === TOML_END);
+    if (e > b)
+        return [b, e];
+    // its end line lost: strom's own lines after its begin, never the person's that follow
+    let last = b;
+    while (last + 1 < lines.length && isGrokStromLine(lines[last + 1]))
+        last++;
+    return [b, last];
+}
+/**
+ * Strom's block taken out, the person's text before and after it kept as it is — only the blank line an install puts
+ * between the person's text and the block it appends goes with it. gap: whether the install that wrote the block put
+ * one there (recorded in agents-taught.json); false: no blank line around the block is strom's. Unknown (an
+ * installation that recorded nothing, a file strom created): the blank line before the block was strom's, or, the block
+ * first in the file, the one after it.
+ */
+function grokWithout(text, gap) {
+    let lines = text.split("\n");
+    const blank = (i) => i >= 0 && i < lines.length && lines[i].trim() === "";
+    for (let at = grokBlock(lines); at; at = grokBlock(lines)) {
+        const [b, e] = at;
+        let from = b;
+        let to = e + 1;
+        if (gap !== false) {
+            // a blank line before it, whatever follows (the end of the file, a blank line, the person's text right after its
+            // end): that one was strom's
+            if (blank(b - 1))
+                from = b - 1;
+            // first in the file, then a blank line and the person's text: that blank line was strom's
+            else if (b === 0 && blank(e + 1) && e + 1 < lines.length - 1)
+                to = e + 2;
+        }
+        // taken to the end of a file with no line break at its end: the CR of the break before it went with it
+        const tail = to >= lines.length && from > 0 ? [lines[from - 1].replace(/\r$/, "")] : lines.slice(from - 1, from);
+        lines = [...lines.slice(0, Math.max(0, from - 1)), ...tail, ...lines.slice(to)];
     }
-    return out.join("\n");
+    return lines.join("\n");
 }
-function grokWith(text) {
-    const rest = grokWithout(text);
+/** config.toml with strom's block; gap: whether a new block was put after a blank line (undefined: none put now). */
+function grokWith(text, rec) {
     const allow = `allow = [${allowRules("grok").map((r) => JSON.stringify(r)).join(", ")}]`;
-    const lines = rest.split("\n");
-    const header = lines.findIndex((l) => /^\s*\[permission\]\s*(#.*)?$/.test(l));
+    const nl = text.includes("\r\n") ? "\r\n" : "\n";
+    const cr = nl === "\r\n" ? "\r" : "";
+    const lines = text.split("\n");
+    const at = grokBlock(lines);
+    if (at) {
+        // strom's block there already: brought to this version where it is, the person's text around it untouched
+        const [b, e] = at;
+        const header = lines.findIndex((l, i) => (i < b || i > e) && isPermissionHeader(l));
+        let inner;
+        if (header < 0)
+            inner = ["[permission]", allow];
+        else if (header < b && !lines.slice(header + 1, b).some(isTomlTable)) {
+            // in the person's own table: up to the next table
+            let end = lines.findIndex((l, i) => i > e && isTomlTable(l));
+            if (end < 0)
+                end = lines.length;
+            if (hasOwnAllow([...lines.slice(header + 1, b), ...lines.slice(e + 1, end)]))
+                return undefined;
+            inner = [allow];
+        }
+        if (inner) {
+            const last = e === lines.length - 1; // the file ends with strom's end line: no line break after it
+            const block = [TOML_BEGIN, ...inner, TOML_END].map((l, i, all) => (last && i === all.length - 1 ? l : l + cr));
+            return { text: [...lines.slice(0, b), ...block, ...lines.slice(e + 1)].join("\n") };
+        }
+        // a table of strom's beside the person's own [permission] table (two would break the file): into theirs
+    }
+    const rest = at ? grokWithout(text, rec) : text;
+    const rl = rest.split("\n");
+    const header = rl.findIndex(isPermissionHeader);
     if (header < 0) {
-        const body = rest.replace(/\s+$/, "");
-        return `${body ? `${body}\n\n` : ""}${TOML_BEGIN}\n[permission]\n${allow}\n${TOML_END}\n`;
+        // appended after a blank line, the person's last line ending as it did (grokWithout takes exactly this away)
+        const block = [TOML_BEGIN, "[permission]", allow, TOML_END].join(nl);
+        if (!rest)
+            return { text: block + nl, gap: false };
+        return { text: rest.endsWith("\n") ? `${rest}${nl}${block}${nl}` : `${rest}${nl}${nl}${block}`, gap: true };
     }
     // the user's table: up to the next table
-    let end = lines.findIndex((l, i) => i > header && /^\s*\[/.test(l));
+    let end = rl.findIndex((l, i) => i > header && isTomlTable(l));
     if (end < 0)
-        end = lines.length;
-    if (lines.slice(header + 1, end).some((l) => /^\s*allow\s*=/.test(l)))
+        end = rl.length;
+    if (hasOwnAllow(rl.slice(header + 1, end)))
         return undefined;
-    return [...lines.slice(0, header + 1), TOML_BEGIN, allow, TOML_END, ...lines.slice(header + 1)].join("\n");
+    return { text: [...rl.slice(0, header + 1), ...[TOML_BEGIN, allow, TOML_END].map((l) => l + cr), ...rl.slice(header + 1)].join("\n"), gap: false };
 }
 /** A rule of strom's in Claude Code's or Antigravity's settings, whichever installation wrote it. */
 function isStromRule(agent, rule) {
@@ -223,30 +294,54 @@ function hasAllow(t, s) {
     const own = path.join(path.dirname(t.file), "strom.md");
     return isObject(bash) && bash[OPENCODE_STROM] === "allow" && Array.isArray(s.instructions) && s.instructions.includes(own);
 }
+/** Strom allowed in the settings; what it made there to do it. */
 function addAllow(t, s) {
+    const made = [];
+    const plain = [];
     if (t.agent !== "opencode") {
+        if (!isObject(s.permissions))
+            made.push("permissions");
+        const perms = isObject(s.permissions) ? s.permissions : {};
+        if (!Array.isArray(perms.allow))
+            made.push("permissions.allow");
         const have = allowList(s);
-        s.permissions = { ...(s.permissions ?? {}), allow: [...have, ...allowRules(t.agent).filter((r) => !have.includes(r))] };
-        return;
+        s.permissions = { ...perms, allow: [...have, ...allowRules(t.agent).filter((r) => !have.includes(r))] };
+        return { made };
     }
+    if (!isObject(s.permission))
+        (typeof s.permission === "string" ? plain : made).push("permission");
     const perm = isObject(s.permission) ? s.permission : typeof s.permission === "string" ? { "*": s.permission } : {};
     // A plain value for bash ("ask") becomes the general rule; strom's comes after it (the last match counts).
+    if (!isObject(perm.bash))
+        (typeof perm.bash === "string" ? plain : made).push("permission.bash");
     const bash = isObject(perm.bash) ? perm.bash : typeof perm.bash === "string" ? { "*": perm.bash } : {};
     s.permission = { ...perm, bash: { ...bash, [OPENCODE_STROM]: "allow" } };
     const own = path.join(path.dirname(t.file), "strom.md");
+    if (!Array.isArray(s.instructions))
+        made.push("instructions");
     const list = Array.isArray(s.instructions) ? s.instructions : [];
     if (!list.includes(own))
         s.instructions = [...list, own];
+    return { made, plain };
 }
-function removeAllow(t, s) {
+/**
+ * Strom's rules out of the settings. What strom made there (rec) goes when empty, and nothing else; a value it turned
+ * into an object becomes plain again. Nothing recorded (an installation before the record): every container left
+ * empty goes, as before.
+ */
+function removeAllow(t, s, rec) {
+    const goes = (p) => (rec ? (rec.made ?? []).includes(p) : true);
+    const wasPlain = (p, v) => (rec?.plain ?? []).includes(p) && Object.keys(v).length === 1 && "*" in v;
     if (t.agent !== "opencode") {
+        if (!isObject(s.permissions))
+            return;
         const rest = allowList(s).filter((r) => !isStromRule(t.agent, r));
         const perms = { ...s.permissions };
-        if (rest.length)
+        if (rest.length || !goes("permissions.allow"))
             perms.allow = rest;
         else
             delete perms.allow;
-        if (Object.keys(perms).length)
+        if (Object.keys(perms).length || !goes("permissions"))
             s.permissions = perms;
         else
             delete s.permissions;
@@ -255,7 +350,7 @@ function removeAllow(t, s) {
     const own = path.join(path.dirname(t.file), "strom.md");
     if (Array.isArray(s.instructions)) {
         const rest = s.instructions.filter((i) => i !== own);
-        if (rest.length)
+        if (rest.length || !goes("instructions"))
             s.instructions = rest;
         else
             delete s.instructions;
@@ -264,16 +359,137 @@ function removeAllow(t, s) {
         const bash = { ...s.permission.bash };
         delete bash[OPENCODE_STROM];
         const perm = { ...s.permission };
-        if (Object.keys(bash).length)
+        if (wasPlain("permission.bash", bash))
+            perm.bash = bash["*"];
+        else if (Object.keys(bash).length || !goes("permission.bash"))
             perm.bash = bash;
         else
             delete perm.bash;
-        if (Object.keys(perm).length)
+        if (wasPlain("permission", perm))
+            s.permission = perm["*"];
+        else if (Object.keys(perm).length || !goes("permission"))
             s.permission = perm;
         else
             delete s.permission;
     }
 }
+/** The spans of the JSON value at i of a text JSON.parse read (so nothing here needs to check it). */
+function jsonSpan(text, i) {
+    const ws = (k) => {
+        while (k < text.length && /\s/.test(text[k]))
+            k++;
+        return k;
+    };
+    const strEnd = (k) => {
+        for (k++; text[k] !== '"'; k++)
+            if (text[k] === "\\")
+                k++;
+        return k + 1;
+    };
+    const start = ws(i);
+    const c = text[start];
+    if (c === '"')
+        return { start, end: strEnd(start) };
+    if (c === "{" || c === "[") {
+        const keys = new Map();
+        const items = [];
+        let k = ws(start + 1);
+        while (text[k] !== (c === "{" ? "}" : "]")) {
+            if (c === "{") {
+                const keyEnd = strEnd(k);
+                const key = JSON.parse(text.slice(k, keyEnd));
+                const v = jsonSpan(text, ws(keyEnd) + 1); // after the colon
+                keys.set(key, v);
+                k = ws(v.end);
+            }
+            else {
+                const v = jsonSpan(text, k);
+                items.push(v);
+                k = ws(v.end);
+            }
+            if (text[k] === ",")
+                k = ws(k + 1);
+        }
+        return c === "{" ? { start, end: k + 1, keys } : { start, end: k + 1, items };
+    }
+    let end = start;
+    while (end < text.length && !/[\s,\]}]/.test(text[end]))
+        end++;
+    return { start, end };
+}
+/** How a JSON text on one line spaces it: what each place holds the first time it comes (outside strings), else nothing. */
+function oneLineSpacing(body) {
+    const seen = new Map();
+    const note = (k, v) => {
+        if (!seen.has(k))
+            seen.set(k, v);
+    };
+    const wsAfter = (i) => /^[ \t]*/.exec(body.slice(i + 1))[0];
+    const wsBefore = (i) => /[ \t]*$/.exec(body.slice(0, i))[0];
+    for (let i = 0; i < body.length; i++) {
+        const c = body[i];
+        if (c === '"') {
+            for (i++; i < body.length && body[i] !== '"'; i++)
+                if (body[i] === "\\")
+                    i++;
+            continue;
+        }
+        if (c === ":" || c === ",") {
+            note(`${c}<`, wsBefore(i));
+            note(`${c}>`, wsAfter(i));
+        }
+        else if (c === "{" || c === "[") {
+            const after = wsAfter(i);
+            if (body[i + 1 + after.length] !== (c === "{" ? "}" : "]"))
+                note(`${c}>`, after);
+        }
+        else if (c === "}" || c === "]") {
+            const before = wsBefore(i);
+            if (body[i - 1 - before.length] !== (c === "}" ? "{" : "["))
+                note(`${c}<`, before);
+        }
+    }
+    const at = (k, or = "") => seen.get(k) ?? or;
+    // no comma yet (one member): spaced after as its colon is
+    return { colon: `${at(":<")}:${at(":>")}`, comma: `${at(",<")},${at(",>", at(":>"))}`, obj: [at("{>"), at("}<")], arr: [at("[>"), at("]<")] };
+}
+/**
+ * The settings written as the person's file is: what did not change exactly as its text has it, what did in its
+ * indentation (or on one line as the file is, with its spaces), its line breaks, the whitespace around it. A blank file
+ * or none: strom's way, two spaces and a line break at the end.
+ */
+function formatJson(s, text) {
+    if (text === undefined || !text.trim())
+        return JSON.stringify(s, null, 2) + "\n";
+    const body = text.trim();
+    const nl = body.includes("\r\n") ? "\r\n" : "\n";
+    // the first indented line is one level in; all on one line: none, its own spaces below (an empty {} says nothing: strom's way)
+    const indent = /\n([ \t]+)\S/.exec(body)?.[1] ?? (body.includes("\n") || /^\{\s*\}$/.test(body) ? "  " : "");
+    // on one line: the person's spaces (none: compact)
+    const one = indent ? undefined : oneLineSpacing(body);
+    const same = (v, at) => JSON.stringify(v) === JSON.stringify(JSON.parse(text.slice(at.start, at.end)));
+    const write = (v, at, depth) => {
+        if (at && same(v, at))
+            return text.slice(at.start, at.end);
+        if (v === null || typeof v !== "object")
+            return JSON.stringify(v) ?? "null";
+        const entries = Array.isArray(v)
+            ? v.map((x, i) => [undefined, x, at?.items?.[i]])
+            : Object.entries(v).map(([k, x]) => [k, x, at?.keys?.get(k)]);
+        const [open, close] = Array.isArray(v) ? ["[", "]"] : ["{", "}"];
+        if (!entries.length)
+            return open + close;
+        const parts = entries.map(([k, x, sub]) => (k === undefined ? "" : JSON.stringify(k) + (one ? one.colon : ": ")) + write(x, sub, depth + 1));
+        if (one) {
+            const [inOpen, inClose] = Array.isArray(v) ? one.arr : one.obj;
+            return open + inOpen + parts.join(one.comma) + inClose + close;
+        }
+        const pad = (d) => indent.repeat(d);
+        return open + nl + parts.map((p) => pad(depth + 1) + p).join("," + nl) + nl + pad(depth) + close;
+    };
+    const lead = text.slice(0, text.length - text.trimStart().length);
+    return lead + write(s, jsonSpan(text, 0), 0) + text.slice(text.trimEnd().length);
+}
 function readMade(file) {
     try {
         const v = JSON.parse(fs.readFileSync(file, "utf8"));
@@ -287,10 +503,12 @@ function writeMade(file, m) {
     try {
         const files = m.files && Object.keys(m.files).length ? m.files : undefined;
         const dirs = m.dirs?.length ? [...new Set(m.dirs)].sort() : undefined;
-        if (!files && !dirs)
+        const json = m.json && Object.keys(m.json).length ? m.json : undefined;
+        const toml = m.toml && Object.keys(m.toml).length ? m.toml : undefined;
+        if (!files && !dirs && !json && !toml)
             fs.rmSync(file, { force: true });
         else
-            writeFileAtomic(file, JSON.stringify({ ...(files ? { files } : {}), ...(dirs ? { dirs } : {}) }, null, 2) + "\n");
+            writeFileAtomic(file, JSON.stringify({ ...(files ? { files } : {}), ...(dirs ? { dirs } : {}), ...(json ? { json } : {}), ...(toml ? { toml } : {}) }, null, 2) + "\n");
     }
     catch {
         // the user config not writable: the files stay as an uninstall without the record leaves them
@@ -312,31 +530,53 @@ function hasStrom(t, text) {
     const own = path.join(path.dirname(t.file), "strom.md");
     return (Array.isArray(s.instructions) && s.instructions.includes(own)) || (isObject(s.permission) && isObject(s.permission.bash) && OPENCODE_STROM in s.permission.bash);
 }
-/** Recorded after a write: the file created now, or the person's (one without strom's part); the folders made for it. */
-function noteWritten(t, before, firstDir) {
+/**
+ * Recorded after a write: the file created now, or the person's (one without strom's part); the folders made for it;
+ * in a settings file, what strom made in it (json); in config.toml, whether a new block went after a blank line (gap).
+ */
+function noteWritten(t, before, firstDir, json, gap) {
     const m = readMade(t.made);
     const files = { ...(m.files ?? {}) };
     const dirs = [...(m.dirs ?? [])];
+    const jsons = { ...(m.json ?? {}) };
+    const tomls = { ...(m.toml ?? {}) };
+    // a new block put now (one there already, brought to this version where it is, keeps what is recorded)
+    if (gap !== undefined)
+        tomls[t.file] = { gap };
+    const fresh = before === undefined || !hasStrom(t, before);
     if (before === undefined)
         files[t.file] = "created";
     // there without strom's part: the person's — also one recorded created, deleted since and made again by the person
-    else if (!hasStrom(t, before))
+    else if (fresh)
         files[t.file] = "existed";
     // strom's part already there: what is recorded stands; nothing recorded, an older installation's file — whose, nobody can tell
+    const prev = jsons[t.file];
+    const both = (a, b) => [...new Set([...(a ?? []), ...(b ?? [])])];
+    const kept = (j) => ({ ...(j.made?.length ? { made: j.made } : {}), ...(j.plain?.length ? { plain: j.plain } : {}), ...(j.blank !== undefined ? { blank: j.blank } : {}) });
+    if (json && fresh)
+        jsons[t.file] = kept(json);
+    else if (json && prev)
+        jsons[t.file] = kept({ ...prev, made: both(prev.made, json.made), plain: both(prev.plain, json.plain) });
+    // strom's part there and nothing recorded of it: an older installation's, taken away as it was before the record
     if (firstDir)
         for (let d = path.dirname(t.file);; d = path.dirname(d)) {
             dirs.push(d);
             if (d === firstDir || path.dirname(d) === d)
                 break;
         }
-    if (JSON.stringify(files) !== JSON.stringify(m.files ?? {}) || dirs.length !== (m.dirs ?? []).length)
-        writeMade(t.made, { files, dirs });
+    const changed = (a, b) => JSON.stringify(a) !== JSON.stringify(b ?? {});
+    if (changed(files, m.files) || dirs.length !== (m.dirs ?? []).length || changed(jsons, m.json) || changed(tomls, m.toml))
+        writeMade(t.made, { files, dirs, json: jsons, toml: tomls });
 }
 /** Its part taken away: the file is the person's again (or gone); the folders strom made for it go when empty. */
 function noteRemoved(t) {
     const m = readMade(t.made);
     const files = { ...(m.files ?? {}) };
     delete files[t.file];
+    const json = { ...(m.json ?? {}) };
+    delete json[t.file];
+    const toml = { ...(m.toml ?? {}) };
+    delete toml[t.file];
     const here = path.dirname(t.file);
     const within = (d) => here === d || here.startsWith(d.endsWith(path.sep) ? d : d + path.sep);
     // deepest first: a folder strom made in another it made
@@ -353,24 +593,37 @@ function noteRemoved(t) {
         }
         return false;
     });
-    writeMade(t.made, { files, dirs });
+    writeMade(t.made, { files, dirs, json, toml });
+}
+/**
+ * Whether strom put a blank line before its block in this config.toml, as recorded; unknown for an installation that
+ * recorded nothing, and for a file strom created (what the person adds to it after its block stands alone again).
+ */
+function tomlGap(t, m) {
+    return m.files?.[t.file] === "created" ? undefined : m.toml?.[t.file]?.gap;
 }
 /** Write it for one agent; false when it was already there as it is. */
 export function installGlobal(t) {
     const cur = read(t.file);
     let next;
+    let json;
+    let gap;
     if (t.kind === "allow" && t.agent === "grok") {
-        const with_ = grokWith(cur ?? "");
+        const with_ = grokWith(cur ?? "", tomlGap(t, readMade(t.made)));
         if (with_ === undefined)
             return false;
-        next = with_;
+        next = with_.text;
+        gap = with_.gap;
     }
     else if (t.kind === "allow") {
         const s = settingsOf(cur);
         if (!s || hasAllow(t, s))
             return false;
-        addAllow(t, s);
-        next = JSON.stringify(s, null, 2) + "\n";
+        json = addAllow(t, s);
+        if (cur !== undefined && !cur.trim())
+            json.blank = cur;
+        // written as the person's file is: its indentation, its line breaks, a line break at its end or none
+        next = formatJson(s, cur);
     }
     else if (t.kind === "own")
         next = t.agent === "claude" || t.agent === "grok" ? skill(t.app) : globalText(t.app);
@@ -382,12 +635,13 @@ export function installGlobal(t) {
         return false;
     const firstDir = fs.mkdirSync(path.dirname(t.file), { recursive: true });
     writeFileAtomic(t.file, next);
-    noteWritten(t, cur, firstDir);
+    noteWritten(t, cur, firstDir, json, gap);
     return true;
 }
 /** Take it away again; false when there was nothing of strom's. */
 export function uninstallGlobal(t) {
-    const removed = takeAway(t, readMade(t.made).files?.[t.file]);
+    const m = readMade(t.made);
+    const removed = takeAway(t, m.files?.[t.file], m.json?.[t.file], tomlGap(t, m));
     if (removed)
         noteRemoved(t);
     return removed;
@@ -397,18 +651,17 @@ export function uninstallGlobal(t) {
  * an installation that recorded nothing stays as it did before the record — a settings file kept as {}, a text file
  * with nothing but strom's part gone.
  */
-function takeAway(t, made) {
+function takeAway(t, made, rec, gap) {
     const cur = read(t.file);
     if (cur === undefined)
         return false;
     if (t.kind === "allow" && t.agent === "grok") {
-        if (!cur.includes(TOML_BEGIN))
+        if (!grokBlock(cur.split("\n")))
             return false;
-        const rest = grokWithout(cur);
-        if (rest.trim())
-            writeFileAtomic(t.file, rest.replace(/\n{3,}/g, "\n\n").replace(/\s*$/, "\n"));
-        else if (made === "existed")
-            writeFileAtomic(t.file, "");
+        // the person's text before and after strom's block as it was
+        const rest = grokWithout(cur, gap);
+        if (rest.trim() || made === "existed")
+            writeFileAtomic(t.file, rest);
         else
             fs.rmSync(t.file);
         return true;
@@ -419,11 +672,15 @@ function takeAway(t, made) {
         const any = t.agent === "opencode" ? s && hasAllow(t, s) : s && allowList(s).some((r) => isStromRule(t.agent, r));
         if (!s || !any)
             return false;
-        removeAllow(t, s);
+        removeAllow(t, s, rec);
         if (!Object.keys(s).length && made === "created")
             fs.rmSync(t.file);
+        // the person's blank file: blank again
+        else if (!Object.keys(s).length && rec?.blank !== undefined)
+            writeFileAtomic(t.file, rec.blank);
+        // written as the person's file is
         else
-            writeFileAtomic(t.file, JSON.stringify(s, null, 2) + "\n");
+            writeFileAtomic(t.file, formatJson(s, cur));
         return true;
     }
     if (t.kind === "own") {
@@ -455,8 +712,9 @@ export function isInstalled(t) {
     const cur = read(t.file);
     if (cur === undefined)
         return false;
+    // strom's block there, wherever the person's text puts it (an install brings it to this version where it is)
     if (t.kind === "allow" && t.agent === "grok")
-        return cur.includes(TOML_BEGIN) && grokWith(cur) === cur;
+        return grokBlock(cur.split("\n")) !== undefined;
     if (t.kind === "allow")
         return hasAllow(t, settingsOf(cur) ?? {});
     return t.kind === "own" || cur.includes(BEGIN);

package/dist/cli/ui.js

@@ -676,6 +676,7 @@ export const UI = {
     "ui.sync.do.title.user": "the edit wins (the research's in its history)",
     "ui.sync.sex.changed": "{n}. {who}: sex {text}",
     "ui.sync.note.new": "{n}. {who}: a note — “{text}”",
+    "ui.sync.note.changed": "{n}. {who}: a note — “{old}” → “{new}”",
     "ui.sync.source.new": "{n}. a source: “{text}”",
     "ui.sync.source.changed": "{n}. the file's source “{text}”: its transcript or page corrected",
     "ui.sync.source.reading": "{n}. the research's source “{text}”: read otherwise in the file",
@@ -725,6 +726,7 @@ export const UI = {
     "ui.sync.place.located": "{n}. {place}: on the map at {at}",
     "ui.sync.do.add": "added as a lead",
     "ui.sync.do.correct": "corrects the research's lead",
+    "ui.sync.do.note.changed": "that line of the research's note corrected",
     "ui.sync.do.detail": "added to the fact, citing the tree sent",
     "ui.sync.do.refine": "added to the fact, citing the tree sent (nothing in it disagrees with the record)",
     "ui.sync.do.conflict": "a conflict to decide (the research has it from a record)",

package/dist/commands/media.js

@@ -17,7 +17,7 @@ import { describeView, makeView, partRegion, viewRegion, VIEW_MAX } from "../cor
 import { listConnectors, missingConsents } from "../core/connector.js";
 import { now } from "../core/tree.js";
 import { originalMax, parseRegion, takeOriginal } from "../core/originals.js";
-import { batchFull, batchPath, noteBatch, openBatch } from "../core/batches.js";
+import { batchFull, batchPath, batchRoom, noteBatch, openBatch } from "../core/batches.js";
 import { readEntry, readZip } from "../core/zip.js";
 const IMAGE_EXT = new Set([".jpg", ".jpeg", ".png", ".tif", ".tiff", ".gif", ".webp", ".heic", ".jp2", ".bmp"]);
 /**
@@ -510,13 +510,13 @@ register({
             throw new UsageError(`no such file: ${args[0]}`);
         const sha = typeof opts.sha === "string" ? opts.sha.toLowerCase() : fileSha256(file);
         if (!/^[0-9a-f]{64}$/.test(sha) || fileSha256(file) !== sha)
-            throw new UsageError("the file is not the one named: its SHA-256 differs", { hint: "send it again" });
+            throw new UsageError("the file is not the one named: its SHA-256 differs", { hint: "send it again", code: "media.sha-differs", params: { sha: sha.slice(0, 64) } });
         const persons = (Array.isArray(opts.person) ? opts.person : opts.person ? [opts.person] : []).flatMap((p) => String(p).split(",")).map((p) => p.trim().toUpperCase()).filter(Boolean);
         const name = typeof opts.name === "string" ? opts.name : path.basename(file);
         const batch = typeof opts.batch === "string" ? opts.batch : undefined;
         const where = batchPath(typeof opts.path === "string" ? opts.path : undefined) ?? batchPath(name) ?? name;
         if (opts.zip && !batch)
-            throw new UsageError("a ZIP comes in a batch", { hint: "--batch <id>" });
+            throw new UsageError("a ZIP comes in a batch", { hint: "--batch <id>", code: "batch.zip-alone" });
         const got = tree.withTreeLock(() => {
             if (!batch)
                 return takeOriginal(tree, shared, file, sha, {
@@ -531,9 +531,9 @@ register({
                 b = { ...b, persons };
             if (!opts.zip) {
                 const size = fs.statSync(file).size;
-                const full = batchFull(b, size, ctx.env);
+                const full = batchRoom(b, size, ctx.env);
                 if (full)
-                    throw new UsageError(full);
+                    throw new UsageError(full.text, { code: full.code, params: full.params });
                 try {
                     const one = takeOriginal(tree, shared, file, sha, { name: path.basename(where), persons, batch, path: where, note: typeof opts.note === "string" ? opts.note : undefined });
                     noteBatch(tree.root, b, one.known ? { known: one.known } : { input: one.input, bytes: size });
@@ -559,7 +559,7 @@ function takeZip(ctx, tree, shared, file, zipPath, start, persons) {
     }
     catch (e) {
         fs.rmSync(file, { force: true });
-        throw new UsageError(`${path.basename(zipPath)}: ${e.message}`, { hint: "unpack it in the system and send the folder" });
+        throw new UsageError(`${path.basename(zipPath)}: ${e.message}`, { hint: "unpack it in the system and send the folder", code: "batch.zip-unreadable", params: { name: path.basename(zipPath) } });
     }
     const max = originalMax(ctx.env);
     let b = start;

package/dist/commands/sync.js

@@ -102,8 +102,8 @@ function changeLine(tree, c, incoming, lang) {
         now: c.kind === "fact.detail" ? detailText(c.fact, lang, short) : factText(c.fact, lang, short),
         when: [humanDate(c.fact?.date, lang), humanPlace(c.fact?.place, undefined, lang)].filter(Boolean).join(", "),
         text: truncate(c.text ?? "", 120),
-        old: c.title ? truncate(c.title.was, 80) || "—" : shownName(c.wasName),
-        new: c.title ? truncate(c.text ?? "", 80) || "—" : shownName(c.text),
+        old: c.note ? truncate(c.note.was, 80) : c.title ? truncate(c.title.was, 80) || "—" : shownName(c.wasName),
+        new: c.note ? truncate(c.text ?? "", 80) : c.title ? truncate(c.text ?? "", 80) || "—" : shownName(c.text),
         title: c.title ? ui(lang, c.title.part === "before" ? "ui.conflict.titleBefore" : "ui.conflict.titleAfter") : "",
         child: name(c.child),
         // a child's tie to each parent: one word for both, else each parent's
@@ -138,17 +138,19 @@ function changeLine(tree, c, incoming, lang) {
                         ? "ui.sync.do.name.user"
                         : c.kind === "name.title" && (c.action === "add" || c.action === "user")
                             ? `ui.sync.do.title${c.action === "user" ? ".user" : ""}`
-                            : c.kind === "family.union" && c.action !== "report"
-                                ? "ui.sync.do.family.union"
-                                : c.kind === "fact.detail" && c.action === "add"
-                                    ? "ui.sync.do.detail"
-                                    : c.kind === "fact.part" && (c.action === "add" || c.action === "user")
-                                        ? `ui.sync.do.part${c.action === "user" ? ".user" : ""}`
-                                        : c.kind.startsWith("source.") || c.kind === "fact.cite" || c.kind === "person.cite" || c.kind === "family.cite"
-                                            ? `ui.sync.do.${c.kind}${c.reads || (c.kind === "source.new" && newReads(c, incoming)) ? ".read" : ""}`
-                                            : c.kind === "fact.new" && c.reads
-                                                ? "ui.sync.do.reading"
-                                                : `ui.sync.do.${c.action}`;
+                            : c.kind === "note.changed" && c.action !== "pick"
+                                ? "ui.sync.do.note.changed"
+                                : c.kind === "family.union" && c.action !== "report"
+                                    ? "ui.sync.do.family.union"
+                                    : c.kind === "fact.detail" && c.action === "add"
+                                        ? "ui.sync.do.detail"
+                                        : c.kind === "fact.part" && (c.action === "add" || c.action === "user")
+                                            ? `ui.sync.do.part${c.action === "user" ? ".user" : ""}`
+                                            : c.kind.startsWith("source.") || c.kind === "fact.cite" || c.kind === "person.cite" || c.kind === "family.cite"
+                                                ? `ui.sync.do.${c.kind}${c.reads || (c.kind === "source.new" && newReads(c, incoming)) ? ".read" : ""}`
+                                                : c.kind === "fact.new" && c.reads
+                                                    ? "ui.sync.do.reading"
+                                                    : `ui.sync.do.${c.action}`;
     // an archive: nobody reads a record there, nor is an agent told — said without it
     const said = isArchive(tree) && `${does}.archive` in UI ? `${does}.archive` : does;
     return `${ui(lang, key, v)} → ${ui(lang, said)}`;

package/dist/core/batches.js

@@ -68,10 +68,10 @@ export function batchPath(raw) {
 /** A batch to add to: made at its first file; one closed takes nothing more. */
 export function openBatch(root, id) {
     if (!BATCH_ID.test(id))
-        throw new UsageError(`not a batch: "${id.slice(0, 64)}"`);
+        throw new UsageError(`not a batch: "${id.slice(0, 64)}"`, { code: "batch.bad-id", params: { batch: id.slice(0, 64) } });
     const b = readBatch(root, id);
     if (b?.done)
-        throw new UsageError(`the batch ${id} is closed already`, { hint: "send the rest as a new batch" });
+        throw new UsageError(`the batch ${id} is closed already`, { hint: "send the rest as a new batch", code: "batch.closed", params: { batch: id } });
     const t = new Date().toISOString();
     return b ?? { id, created: t, updated: t, inputs: [], known: [], bytes: 0, refused: [], nested: [] };
 }
@@ -91,11 +91,16 @@ export function noteBatch(root, b, add) {
 }
 /** Whether a batch has room for one more file of this size; why not, else undefined. */
 export function batchFull(b, bytes, env) {
+    return batchRoom(b, bytes, env)?.text;
+}
+/** Why a batch has no room for one more file of this size — the English words and, for the app, its code — else undefined. */
+export function batchRoom(b, bytes, env) {
     const lim = batchLimits(env);
     if (b.inputs.length + b.known.length >= lim.files)
-        return `the batch has ${lim.files} files already (the most one takes)`;
+        return { text: `the batch has ${lim.files} files already (the most one takes)`, code: "batch.full-files", params: { batch: b.id, files: String(lim.files) } };
+    const gb = String(Math.round(lim.bytes / 1024 ** 3));
     if (b.bytes + bytes > lim.bytes)
-        return `the batch would be larger than ${Math.round(lim.bytes / 1024 ** 3)} GB (the most one takes)`;
+        return { text: `the batch would be larger than ${gb} GB (the most one takes)`, code: "batch.full-bytes", params: { batch: b.id, gb } };
     return undefined;
 }
 /** The folder of a file in its batch that it is sorted with: its first one (a ZIP's: the ZIP and its first one), else none. */
@@ -114,7 +119,7 @@ const IMAGE = /^image\//;
 export function closeBatch(tree, id, opts) {
     const b = readBatch(tree.root, id);
     if (!b)
-        throw new UsageError(`no batch ${id} here`, { hint: "strom input batch" });
+        throw new UsageError(`no batch ${id} here`, { hint: "strom input batch", code: "batch.none", params: { batch: id } });
     if (b.done)
         return { ...b, tasks: b.tasks ?? [] };
     const lang = tree.lang;

package/dist/core/changelog.js

@@ -54,6 +54,7 @@ const SAID = {
     "story.approve": "log.story.approve",
     "story.discard": "log.story.discard",
     "note.add": "log.note.add",
+    "note.edit": "log.note.edit",
     "input.add": "log.input.add",
     "input.sync": "log.input.sync",
     "input.done": "log.input.done",

package/dist/core/live.js

@@ -78,7 +78,7 @@ import { EXIT, StromError } from "./errors.js";
 import { acquireLock } from "./lock.js";
 import { material } from "./material.js";
 import { checkOriginalMeta, freeBytes, knownOriginal, materialWaiting, originalMax, ORIGINAL_RESERVE, ORIGINAL_TYPES, parseRegion } from "./originals.js";
-import { BATCH_ID, batchEstimate, batchFull, batchLimits, batchPath, batchStatus, idleBatches, noteBatch, openBatch, readBatch } from "./batches.js";
+import { BATCH_ID, batchEstimate, batchLimits, batchRoom, batchPath, batchStatus, idleBatches, noteBatch, openBatch, readBatch } from "./batches.js";
 /** New images for the app, made for at most so long when the tree changed (the rest the next time). */
 const LIVE_IMAGES_MS = 20_000;
 import { liveWorkers } from "./workers.js";
@@ -122,6 +122,38 @@ const REFUSED = {
 function said(lang, key, params = {}) {
     return { error: ui(lang, key, params), code: CODES[key], text: ui("en", key, params), ...(Object.keys(params).length ? { params } : {}) };
 }
+/**
+ * An upload of the app refused (PUT /media/<sha256>, a batch's file, POST /batch/<id>/done, GET /media/<sha256>): the
+ * English sentence (`error`, `text`) and its stable `code` with `params` for the app to say it in the person's
+ * language (feature `media.codes`). Each code, its answer and its params:
+ * - `app.only` 403 — not from the Strom app's pages
+ * - `media.bad-sha` 400 — the address names no SHA-256
+ * - `media.bad-header` 400 {header} — a header that is not what it should be (X-Strom-Person, -Source, -Batch, -Zip,
+ *   -Path, -Name, -Note)
+ * - `media.bad-region` 400 {region} — X-Strom-Region is no part of an image
+ * - `media.no-person` 404 {person} — no such person in the research; `media.no-source` 404 {source} — no such source
+ * - `media.no-shared` 500 — the research has no shared folder for files (strom setup)
+ * - `media.large` 413 {mb} (and `max`) — larger than the research takes; `media.full` 507 (and `free`) — no room
+ *   (these two: `error` in the research's language, `text` English — said() above)
+ * - `media.sha-differs` 409 {sha} — the file is not the one its address names
+ * - `media.type` 415 {name} — not a kind of file the research takes
+ * - `media.cut-short` 422 {name, kind: JPEG|PNG|PDF}; `media.too-small` 422 {name, bytes} — the file is not whole
+ * - `media.refused` 400 — refused for another reason (the English sentence says why); `media.failed` 500 — went wrong
+ * - `media.gone` 410 {known} — GET …?file=1: the research knows it, its file is not on this computer
+ * - `research.busy` 503 (and Retry-After, `retry`) — another strom holds the research: send it again in a while
+ * - `batch.bad-id` 400 {batch}; `batch.zip-alone` 400 — a ZIP outside a batch; `batch.zip-unreadable` 400 {name}
+ * - `batch.closed` 409 {batch} — the batch is closed already: send the rest as a new batch
+ * - `batch.full-files` 413 {batch, files}; `batch.full-bytes` 413 {batch, gb} — the most a batch takes
+ * - `batch.none` 404 {batch} — POST /batch/<id>/done: no such batch here; `batch.bad-body` 400 — its body no JSON
+ */
+function refusal(error, code, params = {}) {
+    return { error, code, text: error, ...(Object.keys(params).length ? { params } : {}) };
+}
+/** What a strom of its own said as it failed (its --json: message, code, params): the code it gave, else `fallback`. */
+function refusalOf(why, data, fallback) {
+    const params = data.params && typeof data.params === "object" ? Object.fromEntries(Object.entries(data.params).map(([k, v]) => [k, String(v)])) : {};
+    return refusal(why, typeof data.code === "string" && data.code ? data.code : fallback, params);
+}
 /**
  * The environment of a strom the bridge runs for the Strom app (a send written, the app's tree taken in, an original, a
  * batch closed): what it writes is the person's in the app — never logged as an agent's or a session's, whatever the
@@ -484,7 +516,7 @@ function idsOf(applied, known) {
     return Object.keys(ids.persons).length || Object.keys(ids.sources).length ? { ids } : {};
 }
 /** What the bridge does that an app may ask about (each added once, never taken away). */
-export const BRIDGE_FEATURES = ["sync.again", "sync.undoneSince", "sync.takenBack", "sync.conflictEdit", "sync.since", "sync.ids", "family.noCouple", "family.alone", "adopt.transfer", "adopt.empty", "material.list", "person.titles"];
+export const BRIDGE_FEATURES = ["sync.again", "sync.undoneSince", "sync.takenBack", "sync.conflictEdit", "sync.since", "sync.ids", "family.noCouple", "family.alone", "adopt.transfer", "adopt.empty", "material.list", "person.titles", "media.codes"];
 export function history(root, tree, range = [`-n${LOG_MAX}`]) {
     const r = runGit(root, ["log", ...range, "--format=%x1e%H%x1f%cI%x1f%s%x1f%b%x1f", "--name-only"]);
     if (r.status !== 0)
@@ -1057,7 +1089,7 @@ export function serveLive(root, env) {
                 else if (!/[?&]file=1(?:&|$)/.test(req.url ?? ""))
                     json(200, { known: known.id, kind: known.kind, mime: known.mime, bytes: known.bytes, ...(known.name ? { name: known.name } : {}), here: !!known.file && fs.existsSync(known.file) });
                 else if (!known.file || !fs.existsSync(known.file))
-                    json(410, { known: known.id, error: "its file is not on this computer" });
+                    json(410, { known: known.id, ...refusal("its file is not on this computer", "media.gone", { known: known.id }) });
                 else {
                     const size = fs.statSync(known.file).size;
                     res.writeHead(200, { "Content-Type": known.mime, "Content-Length": String(size), "Cache-Control": "no-store", "Content-Disposition": `inline; filename*=UTF-8''${encodeURIComponent(known.name ?? path.basename(known.file))}` });
@@ -1493,10 +1525,10 @@ export function serveLive(root, env) {
             req.resume();
         };
         if (!origin)
-            return refuse(403, { error: "only the Strom app may send a file here" });
+            return refuse(403, refusal("only the Strom app may send a file here", "app.only"));
         const sha = rawSha.toLowerCase();
         if (!/^[0-9a-f]{64}$/.test(sha))
-            return refuse(400, { error: "the address names no SHA-256" });
+            return refuse(400, refusal("the address names no SHA-256", "media.bad-sha"));
         const header = (n) => {
             const v = req.headers[n];
             return typeof v === "string" ? v : undefined;
@@ -1509,33 +1541,45 @@ export function serveLive(root, env) {
         let where;
         const zip = header("x-strom-zip") === "1";
         const tree = Tree.open(root, env);
+        // the header read when it failed (its value not URI-encoded too): said by its name
+        let at = "X-Strom-Batch";
         try {
             batch = header("x-strom-batch")?.trim();
             if (batch !== undefined && !BATCH_ID.test(batch))
                 throw new Error("X-Strom-Batch: the batch's mark (letters, digits, -)");
+            at = "X-Strom-Zip";
             if (zip && !batch)
                 throw new Error("X-Strom-Zip: a ZIP comes in a batch (X-Strom-Batch)");
+            at = "X-Strom-Path";
             where = header("x-strom-path") ? batchPath(decodeURIComponent(header("x-strom-path"))) : undefined;
+            at = "X-Strom-Name";
             name = decodeURIComponent(header("x-strom-name") ?? "") || sha.slice(0, 12);
+            at = "X-Strom-Note";
             note = header("x-strom-note") ? decodeURIComponent(header("x-strom-note")).slice(0, 500) : undefined;
+            at = "X-Strom-Person";
             const persons = (header("x-strom-person") ?? "").split(",").map((p) => p.trim().toUpperCase()).filter(Boolean);
             if (persons.some((p) => !/^P\d{1,9}$/.test(p)))
                 throw new Error("X-Strom-Person: IDs of the research's people (P…), with commas");
+            at = "X-Strom-Source";
             const source = header("x-strom-source")?.trim().toUpperCase();
             if (source && !/^S\d{1,9}$/.test(source))
                 throw new Error("X-Strom-Source: the ID of a source of the research (S…)");
+            at = "X-Strom-Region";
             region = header("x-strom-region")?.trim();
             parseRegion(region);
             meta = checkOriginalMeta(tree, { persons, source });
         }
         catch (e) {
-            return refuse(/^no (person|source)/.test(e.message) ? 404 : 400, { error: e.message });
+            // a person or a source the research has not got: 404, its JSON body telling it from an address that is no bridge's
+            const m = e.message;
+            const coded = e instanceof StromError && e.code ? refusal(m, e.code, e.params ?? {}) : refusal(m, "media.bad-header", { header: at });
+            return refuse(/^no (person|source)/.test(m) ? 404 : 400, coded);
         }
         const settings = new Settings(env, {});
         const shared = settings.shared()?.value;
         // not set up (no shared folder): sending again does not help — /status says accepts.media null
         if (!shared)
-            return refuse(500, { error: "the research has no shared folder for files (strom setup)" });
+            return refuse(500, refusal("the research has no shared folder for files (strom setup)", "media.no-shared"));
         // a batch: open, with room for it
         let open;
         const length = Number(header("content-length") ?? NaN);
@@ -1544,11 +1588,11 @@ export function serveLive(root, env) {
                 open = openBatch(root, batch);
             }
             catch (e) {
-                return refuse(409, { error: e.message, batch });
+                return refuse(409, { ...refusalOf(e.message, e instanceof StromError ? e : {}, "batch.closed"), batch });
             }
-            const full = batchFull(open, Number.isFinite(length) ? length : 0, env);
+            const full = batchRoom(open, Number.isFinite(length) ? length : 0, env);
             if (full)
-                return refuse(413, { error: full, batch });
+                return refuse(413, { ...refusal(full.text, full.code, full.params), batch });
         }
         // the same content: only said (an image of another source given again is taken as one more of that source)
         const known = zip ? undefined : knownOriginal(tree, shared, sha);
@@ -1586,7 +1630,7 @@ export function serveLive(root, env) {
                 if (code !== 0)
                     noteLive(root, `what came again for ${known.id} was not added (exit ${code})`);
                 if (code === EXIT.locked)
-                    return reply(503, { error: "the research is busy — send it again in a while", retry: 30 });
+                    return reply(503, { ...refusal("the research is busy — send it again in a while", "research.busy"), retry: 30 });
                 reply(200, { known: known.id, kind: known.kind, ...(code === 0 && data.added ? { added: data.added } : {}), ...(code === 0 && data.task ? { task: data.task } : {}), ...(code === 0 ? { head: head(root) } : {}) });
             });
             return;
@@ -1647,7 +1691,7 @@ export function serveLive(root, env) {
             out.end(() => safely(req, res, () => {
                 if (hash.digest("hex") !== sha) {
                     drop();
-                    reply(409, { error: "the file is not the one its address names (its SHA-256 differs) — send it again" });
+                    reply(409, refusal("the file is not the one its address names (its SHA-256 differs) — send it again", "media.sha-differs", { sha }));
                     return;
                 }
                 // taken by a strom of its own: its lock, its log and its commit
@@ -1668,7 +1712,7 @@ export function serveLive(root, env) {
                 child.stderr.on("data", (d) => (stderr += d.toString("utf8")));
                 child.on("error", (e) => {
                     drop();
-                    reply(500, { error: errorText(e) });
+                    reply(500, refusal(errorText(e), "media.failed"));
                 });
                 child.on("close", (code) => {
                     let data = {};
@@ -1687,8 +1731,8 @@ export function serveLive(root, env) {
                     noteLive(root, `an original was not taken (exit ${code}): ${why}`);
                     // the research busy (another strom holding it longer than a writer waits): the app sends it again later
                     if (code === EXIT.locked)
-                        return reply(503, { error: why, retry: 30 });
-                    reply(/not a kind of file/.test(why) ? 415 : /cut short|too small/.test(why) ? 422 : /the most one takes/.test(why) ? 413 : /closed already/.test(why) ? 409 : 400, { error: why });
+                        return reply(503, { ...refusal(why, "research.busy"), retry: 30 });
+                    reply(/not a kind of file/.test(why) ? 415 : /cut short|too small/.test(why) ? 422 : /the most one takes/.test(why) ? 413 : /closed already/.test(why) ? 409 : 400, refusalOf(why, data, "media.refused"));
                 });
             }));
         });
@@ -1713,7 +1757,7 @@ export function serveLive(root, env) {
         child.stderr.on("data", (d) => (stderr += d.toString("utf8")));
         child.on("error", (e) => {
             closing.delete(id);
-            reply(500, { error: errorText(e) });
+            reply(500, { ...refusal(errorText(e), "media.failed"), batch: id });
         });
         child.on("close", (code) => {
             closing.delete(id);
@@ -1729,8 +1773,8 @@ export function serveLive(root, env) {
             const why = String(data.message ?? stderr.trim().split("\n").find((l) => l.startsWith("error:"))?.slice(6).trim() ?? "the batch was not closed");
             noteLive(root, `the batch ${id} was not closed (exit ${code}): ${why}`);
             if (code === EXIT.locked)
-                return reply(503, { error: why, retry: 30, batch: id });
-            reply(/no batch/.test(why) ? 404 : 400, { error: why, batch: id });
+                return reply(503, { ...refusal(why, "research.busy"), retry: 30, batch: id });
+            reply(/no batch/.test(why) ? 404 : 400, { ...refusalOf(why, data, /no batch/.test(why) ? "batch.none" : "media.refused"), batch: id });
         });
     };
     /** The app says a batch is whole: {name, files, person, note} — its files become sorting tasks (the note told in them). */
@@ -1740,10 +1784,10 @@ export function serveLive(root, env) {
                 res.writeHead(code, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store", ...(code === 503 ? { "Retry-After": "30" } : {}) }).end(JSON.stringify(body));
         };
         if (!origin)
-            return reply(403, { error: "only the Strom app may close a batch" });
+            return reply(403, refusal("only the Strom app may close a batch", "app.only"));
         if (!BATCH_ID.test(id) || !readBatch(root, id)) {
             req.resume();
-            return reply(404, { error: `no batch ${id.slice(0, 64)} here`, batch: id });
+            return reply(404, { ...refusal(`no batch ${id.slice(0, 64)} here`, "batch.none", { batch: id.slice(0, 64) }), batch: id });
         }
         let body = "";
         req.on("data", (c) => {
@@ -1756,7 +1800,7 @@ export function serveLive(root, env) {
                 said = body.trim() ? JSON.parse(body) : {};
             }
             catch {
-                return reply(400, { error: "the body: JSON {name, files, person}" });
+                return reply(400, { ...refusal("the body: JSON {name, files, person}", "batch.bad-body"), batch: id });
             }
             const persons = (Array.isArray(said.person) ? said.person : said.person ? [said.person] : []).map((p) => String(p).trim().toUpperCase()).filter((p) => /^P\d{1,9}$/.test(p));
             const extra = [

package/dist/core/originals.js

@@ -98,11 +98,14 @@ export function originalType(file, name) {
         return undefined;
     return named;
 }
-/** Why a file of that type is not whole (a JPEG or PNG cut short, a PDF without its end), or undefined. */
+/**
+ * Why a file of that type is not whole (a JPEG or PNG cut short, a PDF without its end), or undefined — the English
+ * words and, for the app to say it in its own language, its code (media.too-small {bytes}, media.cut-short {kind}).
+ */
 export function originalProblem(file, mime) {
     const size = fs.statSync(file).size;
     if (size < 16)
-        return `${size} bytes — too small`;
+        return { text: `${size} bytes — too small`, code: "media.too-small", params: { bytes: String(size) } };
     const tail = Buffer.alloc(Math.min(2048, size));
     const fd = fs.openSync(file, "r");
     try {
@@ -111,12 +114,13 @@ export function originalProblem(file, mime) {
     finally {
         fs.closeSync(fd);
     }
+    const short = (kind, text) => ({ text, code: "media.cut-short", params: { kind } });
     if (mime === "image/jpeg" && !tail.includes(Buffer.from([0xff, 0xd9])))
-        return "a JPEG cut short (no end marker)";
+        return short("JPEG", "a JPEG cut short (no end marker)");
     if (mime === "image/png" && !tail.includes(Buffer.from("IEND")))
-        return "a PNG cut short (no end)";
+        return short("PNG", "a PNG cut short (no end)");
     if (mime === "application/pdf" && !tail.includes(Buffer.from("%%EOF")))
-        return "a PDF cut short (no end)";
+        return short("PDF", "a PDF cut short (no end)");
     return undefined;
 }
 /** What the research has of this content: an input or an image (by SHA-256), with where its file is. */
@@ -137,7 +141,7 @@ export function parseRegion(text) {
     const n = text.split(",").map((x) => Number(x.trim()));
     const [x, y, w, h] = n;
     if (n.length !== 4 || n.some((v) => !Number.isFinite(v)) || x < 0 || y < 0 || w <= 0 || h <= 0 || x + w > 1.001 || y + h > 1.001)
-        throw new UsageError(`not a part of an image: "${text.slice(0, 60)}"`, { hint: "x,y,w,h as fractions of the image (0–1) from its top left corner" });
+        throw new UsageError(`not a part of an image: "${text.slice(0, 60)}"`, { hint: "x,y,w,h as fractions of the image (0–1) from its top left corner", code: "media.bad-region", params: { region: text.slice(0, 60) } });
     return { x: x, y: y, w: Math.min(w, 1 - x), h: Math.min(h, 1 - y) };
 }
 /** Where an original came from (an input's `from`). */
@@ -154,7 +158,7 @@ function personOf(tree, id) {
     for (let hops = 0; p?.mergedInto && hops < 10; hops++)
         p = tree.get(p.mergedInto);
     if (!p || p.type !== "person" || p.retracted)
-        throw new UsageError(`no person ${id} in this research`, { hint: "the person's REFN in the Strom app" });
+        throw new UsageError(`no person ${id} in this research`, { hint: "the person's REFN in the Strom app", code: "media.no-person", params: { person: id } });
     return p;
 }
 function sourceOf(tree, id) {
@@ -162,7 +166,7 @@ function sourceOf(tree, id) {
     for (let hops = 0; s?.mergedInto && hops < 10; hops++)
         s = tree.get(s.mergedInto);
     if (!s || s.type !== "source" || s.retracted)
-        throw new UsageError(`no source ${id} in this research`, { hint: "the source's REFN in the Strom app" });
+        throw new UsageError(`no source ${id} in this research`, { hint: "the source's REFN in the Strom app", code: "media.no-source", params: { source: id } });
     return s;
 }
 /** Check what an original is for before it comes: the people and the source the research has, the part of the image. */
@@ -182,10 +186,10 @@ export function takeOriginal(tree, shared, file, sha, metaIn) {
     const name = path.basename(metaIn.name.normalize("NFC").replace(/[\\/]+/g, "/")).replace(/[\u0000-\u001f]/g, "").slice(0, 200) || `${sha.slice(0, 12)}`;
     const type = originalType(file, name);
     if (!type)
-        throw new UsageError(`${name}: not a kind of file the research takes`, { hint: `images (JPEG, PNG, TIFF, HEIC, WebP), PDF, texts and documents, sound — ${ORIGINAL_TYPES.map((t) => t.ext[0]).join(" ")}` });
+        throw new UsageError(`${name}: not a kind of file the research takes`, { hint: `images (JPEG, PNG, TIFF, HEIC, WebP), PDF, texts and documents, sound — ${ORIGINAL_TYPES.map((t) => t.ext[0]).join(" ")}`, code: "media.type", params: { name } });
     const problem = originalProblem(file, type.mime);
     if (problem)
-        throw new UsageError(`${name}: ${problem} — not taken; send it again`);
+        throw new UsageError(`${name}: ${problem.text} — not taken; send it again`, { code: problem.code, params: { name, ...problem.params } });
     const lang = tree.lang;
     const known = knownOriginal(tree, shared, sha);
     const s = meta.source && !meta.batch ? tree.get(meta.source) : undefined;

package/dist/core/phrases.js

@@ -173,6 +173,7 @@ export const PHRASES = {
     "log.repository.retract": "Archive withdrawn: {name}",
     "log.name.remove": "Name taken off: {name} – {who}",
     "log.note.remove": "Note taken off: \"{note}\" – {name}",
+    "log.note.edit": "Note corrected: {name}",
     "log.event.status": "How sure a fact is, changed: {who} – {fact}",
     "log.event.restore": "A fact back again: {who} – {fact}",
     "log.input.sync.undo": "Family tree taken back: {name}",

package/dist/core/sync.js

@@ -386,6 +386,39 @@ function knownNote(text, said) {
     // a word or two of the app's own ("Birth:", "Address:") around what the research said — never a short note all new
     return unknown.length <= w.size * 0.2 || (unknown.length < 3 && unknown.length * 2 <= w.size);
 }
+/** A line of a note as compared: NFC, its spaces one (the app joins what GEDCOM splits). */
+const noteLine = (t) => t.normalize("NFC").replace(/\s+/g, " ").trim();
+/** The words of a line as the user wrote them (lower case, accents kept, a letter alone too): what an edit changes. */
+const lineWords = (t) => new Set(t.normalize("NFC").toLowerCase().match(/[\p{L}\p{M}\p{N}]+/gu) ?? []);
+/**
+ * Of the research's lines, the one this line is an edit of: at least `share` of the words of the longer of the two in
+ * both (a year changed, a name corrected, a word added or taken away), the most of them.
+ */
+function closest(ours, line, share) {
+    const w = lineWords(line);
+    let best;
+    let most = 0;
+    for (const x of ours) {
+        const v = lineWords(x.line);
+        const both = [...w].filter((y) => v.has(y)).length;
+        if (both && both >= share * Math.max(w.size, v.size) && both > most)
+            [best, most] = [x, both];
+    }
+    return best;
+}
+/** A note with one of its lines (as compared) another: the first such line, the others as they are. */
+function swapLine(text, was, now) {
+    const lines = text.split("\n");
+    const i = lines.findIndex((l) => noteLine(l) === was);
+    if (i >= 0)
+        lines[i] = now;
+    return lines.join("\n");
+}
+/** The line only adds words around the research's ("Address: čp. 35" of "čp. 35"): the app's own shape, no line of its own. */
+function onlyAdds(ours, line) {
+    const w = lineWords(line);
+    return [...lineWords(ours)].every((y) => w.has(y));
+}
 /**
  * A tree the Strom app sent the bridge, with the version the app said with it (X-Strom-App-Version, ?app=) as its HEAD's
  * 2 VERS under 1 SOUR STROM, where the file names no version of the app (the app writes "1.0" there): the file is read
@@ -1988,13 +2021,52 @@ export function planSync(tree, incoming, edits, opts = {}) {
         if (fresh.length)
             push({ kind: owner.family || owner.partners ? "family.cite" : "person.cite", action: "add", ...owner, cites: fresh, ...(fresh.some((c) => reads(c.source)) ? { reads: true } : {}) });
     };
-    /** A note coming back holds the research's too (the app joins them): only its lines the research has not said. */
-    const notesDiff = (owner, inc, said, facts) => {
+    /**
+     * A note coming back holds the research's too (the app joins them): only its lines the research has not said. A line
+     * of the research's own note the user edited in the app (a year, a name: hardly a word else — N38, found with the
+     * app's 3.10.0-beta.13: "nothing new taken", the edit lost) is no line the research has said: the user's own note
+     * (typed by the user, or the app's) corrected, a session's kept and the user's line beside it (sync.edits user, an
+     * archive: corrected too); a line like one the note still has, a line of its own. A line as the app was given it
+     * (the base) is no edit: the research's since stays.
+     */
+    const notesDiff = (owner, inc, said, facts, mine) => {
         const words = new Set(wordsOf([...said, ...facts.map((f) => [f.place, f.value, f.label].join(" "))].join("\n")));
+        // what the research says, and what the app was given (the base: a copy older than the research's edit is no edit)
+        const exactly = new Set(said.flatMap((t) => t.split(/\n+/)).map(noteLine).filter(Boolean));
+        const sent = new Set((inc ?? []).flatMap((t) => t.split(/\n+/)).map(noteLine).filter(Boolean));
+        const ours = (mine ?? []).flatMap((n) => n.text.split(/\n+/).map(noteLine).filter(Boolean).map((line) => ({ note: n, line })));
+        const used = new Set();
         for (const t of inc ?? []) {
-            const fresh = t.split(/\n+/).filter((line) => line.trim() && !knownNote(line, words));
-            if (fresh.length && !knownNote(fresh.join("\n"), words))
-                push({ kind: "note.new", action: "add", ...owner, text: fresh.join("\n") });
+            const lines = t.split(/\n+/).map((line) => line.trim()).filter(Boolean);
+            const own = new Set();
+            const fresh = lines.filter((line) => {
+                const l = noteLine(line);
+                if (exactly.has(l))
+                    return false;
+                // an edit of a line the note no longer has; a line beside one it still has, like it but for a word or two
+                const edit = closest(ours.filter((x) => !used.has(x) && !sent.has(x.line)), l, 0.5);
+                const like = !edit && closest(ours.filter((x) => sent.has(x.line) && !onlyAdds(x.line, l)), l, 0.6);
+                if (edit) {
+                    used.add(edit);
+                    // a file that names no commit it stands on (an older export, another program's): which is newer nobody can
+                    // tell — only shown, taken with --only (N39: an older copy set the user's correction back)
+                    if (!base) {
+                        push({ kind: "note.changed", action: "pick", ...owner, text: line.normalize("NFC"), note: { at: edit.note.at, was: edit.line } });
+                        return false;
+                    }
+                    if (edit.note.by === "user" || edits === "user") {
+                        push({ kind: "note.changed", action: "correct", ...owner, text: line.normalize("NFC"), note: { at: edit.note.at, was: edit.line } });
+                        return false;
+                    }
+                }
+                if (edit || like)
+                    own.add(line);
+                return !edit && !like && !knownNote(line, words);
+            });
+            const take = fresh.length > 0 && !knownNote(fresh.join("\n"), words);
+            const out = lines.filter((line) => own.has(line) || (take && fresh.includes(line)));
+            if (out.length)
+                push({ kind: "note.new", action: "add", ...owner, text: out.join("\n") });
         }
     };
     // people
@@ -2081,7 +2153,7 @@ export function planSync(tree, incoming, edits, opts = {}) {
             const overGuess = mySex === "U" && guessed !== undefined && !incoming.sexU;
             push({ kind: "sex.changed", action: b ? (edits === "user" ? "user" : backed || since || overGuess ? "conflict" : "correct") : "report", person: id, name, text: p.sex });
         }
-        notesDiff({ person: id, name }, p.notes, [o.said, b?.said ?? "", ...o.names], o.facts);
+        notesDiff({ person: id, name }, p.notes, [o.said, b?.said ?? "", ...o.names], o.facts, tree.get(id)?.notes);
     }
     if (base && !partial)
         for (const [key, b] of base.persons)
@@ -2264,7 +2336,7 @@ export function planSync(tree, incoming, edits, opts = {}) {
         const both = [...new Set([...o.partners, ...partners])];
         factsDiff({ family: fam.id, partners: both }, f.facts, o.facts, b?.facts, true);
         citesDiff({ family: fam.id, partners: both }, f.cites, fam, b?.cites);
-        notesDiff({ family: fam.id, partners: both }, f.notes, [o.said ?? "", b?.said ?? "", ...both.map((k) => ours.persons.get(k)?.names.join(" ") ?? "")], o.facts);
+        notesDiff({ family: fam.id, partners: both }, f.notes, [o.said ?? "", b?.said ?? "", ...both.map((k) => ours.persons.get(k)?.names.join(" ") ?? "")], o.facts, fam.notes);
         // how the couple is bound (no record proves it): the user's word where it changed since given, or where the research
         // has none; another word with nothing to stand on only said; none in the file takes nothing away (an older app)
         // (the one partner's married or divorced is the couple's facts' to say once the unknown one is named)
@@ -3410,6 +3482,23 @@ export function applySync(tree, plan, incoming, source, only) {
                     applied.push({ do: "note.add", id: owner, before: n.at });
                     break;
                 }
+                case "note.changed": {
+                    // the user's edit of a line of the research's note: that line of it corrected, the rest of the note as it was
+                    if (!owner || !c.text || !c.note)
+                        break;
+                    const { at, was } = c.note;
+                    const edited = noteLine(c.text);
+                    const rec = tree.get(owner);
+                    if (!rec?.notes.some((n) => n.at === at && n.text.split("\n").some((l) => noteLine(l) === was)))
+                        break;
+                    update(tree, owner, typeOfId(owner) === "family" ? "family" : "person", (o) => ({ ...o, notes: o.notes.map((n) => (n.at === at ? { ...n, text: swapLine(n.text, was, edited) } : n)) }), {
+                        op: "note.edit",
+                        summary: `${owner} note "${truncateText(was, 50)}" → "${truncateText(edited, 50)}": the user's edit (${reason})`,
+                        reason,
+                    });
+                    applied.push({ do: "note.edit", id: owner, before: JSON.stringify({ at, now: edited, was }) });
+                    break;
+                }
                 case "sex.changed": {
                     if (!owner || !c.text)
                         break;
@@ -3911,6 +4000,19 @@ export function undoSync(tree, input) {
                     : { op: "person.edit", summary: `${a.id} shown by its name before again: ${reason}`, reason });
                 break;
             }
+            case "note.edit": {
+                // the line as it was, back in its note (the note as it is now otherwise)
+                const b = JSON.parse(String(a.before ?? "{}"));
+                const rec = tree.get(a.id);
+                if (!b.at || !b.now || !b.was || !rec?.notes.some((n) => n.at === b.at && n.text.split("\n").some((l) => noteLine(l) === b.now)))
+                    break;
+                update(tree, a.id, typeOfId(a.id) === "family" ? "family" : "person", (o) => ({ ...o, notes: o.notes.map((n) => (n.at === b.at ? { ...n, text: swapLine(n.text, b.now, b.was) } : n)) }), {
+                    op: "note.edit",
+                    summary: `${a.id} note "${truncateText(b.now, 50)}" → "${truncateText(b.was, 50)}" again: ${reason}`,
+                    reason,
+                });
+                break;
+            }
             case "note.add":
                 update(tree, a.id, typeOfId(a.id) ?? "person", (o) => ({ ...o, notes: o.notes.filter((x) => x.at !== a.before) }), { op: "note.remove", summary: `${a.id} note "${noteText(tree, a.id, a.before)}" removed: ${reason}`, reason });
                 break;

package/dist/core/tree.js

@@ -27,7 +27,7 @@ import { lastBackup } from "./backup.js";
 export const TREE_FILE = "strom.json";
 // between releases the candidate being made (a bridge run from the sources says what it is: the Strom app goes by it);
 // at a release the release's own (package.json)
-export const VERSION = "1.13.0-beta.6";
+export const VERSION = "1.13.0-beta.8";
 const GITIGNORE = `# Strom Research — local state and large files are not versioned
 .strom/
 /media/

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "strom-research",
-  "version": "1.13.0-beta.6",
+  "version": "1.13.0-beta.8",
   "description": "Genealogical research toolkit for AI coding agents",
   "type": "module",
   "bin": {