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

package/dist/agents/global.js

@@ -120,28 +120,35 @@ function grokBlock(lines) {
 }
 /**
  * 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.
+ * 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) {
+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;
-        // a blank line before it, and the end of the file or another blank line after it: the one before was strom's
-        if (blank(b - 1) && (e + 1 >= lines.length || blank(e + 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;
+        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 lines.join("\n");
 }
-function grokWith(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 nl = text.includes("\r\n") ? "\r\n" : "\n";
     const cr = nl === "\r\n" ? "\r" : "";
@@ -166,19 +173,19 @@ function grokWith(text) {
         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 [...lines.slice(0, b), ...block, ...lines.slice(e + 1)].join("\n");
+            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) : text;
+    const rest = at ? grokWithout(text, rec) : text;
     const rl = rest.split("\n");
     const header = rl.findIndex(isPermissionHeader);
     if (header < 0) {
         // 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 block + nl;
-        return rest.endsWith("\n") ? `${rest}${nl}${block}${nl}` : `${rest}${nl}${nl}${block}`;
+            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 = rl.findIndex((l, i) => i > header && isTomlTable(l));
@@ -186,7 +193,7 @@ function grokWith(text) {
         end = rl.length;
     if (hasOwnAllow(rl.slice(header + 1, end)))
         return undefined;
-    return [...rl.slice(0, header + 1), ...[TOML_BEGIN, allow, TOML_END].map((l) => l + cr), ...rl.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) {
@@ -410,18 +417,56 @@ function jsonSpan(text, i) {
         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 compact, as the file is), its line breaks, the whitespace around it. A blank file or none: strom's
- * way, two spaces and a line break at the end.
+ * 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: compact (an empty {} says nothing: strom's way)
+    // 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))
@@ -434,9 +479,11 @@ function formatJson(s, text) {
         const [open, close] = Array.isArray(v) ? ["[", "]"] : ["{", "}"];
         if (!entries.length)
             return open + close;
-        const parts = entries.map(([k, x, sub]) => (k === undefined ? "" : JSON.stringify(k) + (indent ? ": " : ":")) + write(x, sub, depth + 1));
-        if (!indent)
-            return open + parts.join(",") + 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;
     };
@@ -457,10 +504,11 @@ function writeMade(file, m) {
         const files = m.files && Object.keys(m.files).length ? m.files : undefined;
         const dirs = m.dirs?.length ? [...new Set(m.dirs)].sort() : undefined;
         const json = m.json && Object.keys(m.json).length ? m.json : undefined;
-        if (!files && !dirs && !json)
+        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 } : {}), ...(json ? { json } : {}) }, 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
@@ -484,13 +532,17 @@ function hasStrom(t, text) {
 }
 /**
  * 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 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) {
+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";
@@ -512,8 +564,9 @@ function noteWritten(t, before, firstDir, json) {
             if (d === firstDir || path.dirname(d) === d)
                 break;
         }
-    if (JSON.stringify(files) !== JSON.stringify(m.files ?? {}) || dirs.length !== (m.dirs ?? []).length || JSON.stringify(jsons) !== JSON.stringify(m.json ?? {}))
-        writeMade(t.made, { files, dirs, json: jsons });
+    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) {
@@ -522,6 +575,8 @@ function noteRemoved(t) {
     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
@@ -538,18 +593,27 @@ function noteRemoved(t) {
         }
         return false;
     });
-    writeMade(t.made, { files, dirs, json });
+    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);
@@ -571,13 +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, json);
+    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 m = readMade(t.made);
-    const removed = takeAway(t, m.files?.[t.file], m.json?.[t.file]);
+    const removed = takeAway(t, m.files?.[t.file], m.json?.[t.file], tomlGap(t, m));
     if (removed)
         noteRemoved(t);
     return removed;
@@ -587,7 +651,7 @@ 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, rec) {
+function takeAway(t, made, rec, gap) {
     const cur = read(t.file);
     if (cur === undefined)
         return false;
@@ -595,7 +659,7 @@ function takeAway(t, made, rec) {
         if (!grokBlock(cur.split("\n")))
             return false;
         // the person's text before and after strom's block as it was
-        const rest = grokWithout(cur);
+        const rest = grokWithout(cur, gap);
         if (rest.trim() || made === "existed")
             writeFileAtomic(t.file, rest);
         else

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/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/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/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.7";
+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.7",
+  "version": "1.13.0-beta.8",
   "description": "Genealogical research toolkit for AI coding agents",
   "type": "module",
   "bin": {