strom-research 1.4.1 → 1.6.0

package/dist/core/live.js

@@ -10,6 +10,9 @@
 //   GET <token>/tree.ged   the tree for the Strom app, as it is now, each entry with its image (the settings excerpts.*)
 //   GET <token>/images.ged the same (the address an older strom gave)
 //   GET <token>/events     server-sent events: hello, change, working
+//   POST <token>/sync      the Strom app sends the user's edited tree back (?send=): kept to be shown
+//                          and written on the user's word (strom sync) — nothing of the research changes
+//   POST <token>/cancel    …or says it sends nothing ({"reason": "unchanged" | "cancelled" | "no-tree"})
 //
 // Only pages of the Strom app may read it (CORS: https://stromapp.info, its beta, and a
 // local copy on localhost for its development), and a browser asks first
@@ -22,12 +25,19 @@ import { spawn, spawnSync } from "node:child_process";
 import { Tree, VERSION } from "./tree.js";
 import { exportGedcom } from "../gedcom/export.js";
 import { excerptSettings, planExcerpts } from "./excerpt.js";
+import { noteAdoptFailed, noteNothingSent, pendingAdoption, receiveAdopted, receiveTree, SYNC_MAX_BYTES } from "./sync.js";
+import { ui } from "../cli/ui.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";
-import { openSessions } from "./session.js";
+import { monthSpend, openSessions } from "./session.js";
+import { rankTasks } from "./queue.js";
+import { humanTask } from "../cli/human.js";
+import { knownNewerVersion } from "./update.js";
 import { gitProgram } from "./git.js";
-import { isStromAppOrigin } from "./stromapp.js";
+import { appOpensLinks, isStromAppOrigin } from "./stromapp.js";
+import { Settings } from "./config.js";
+import { linkActions, linkHandlerState } from "./links.js";
 import { stromLauncher } from "./self.js";
 /** Where a running bridge of a tree is noted. */
 export function liveFile(root) {
@@ -120,10 +130,43 @@ function working(root, tree) {
         return { who: w.label, since: w.since, ...(s ? { session: s.id, ...(s.task ? { task: task ? `${task.id} ${task.what}` : s.task } : {}) } : {}) };
     });
 }
+/** How long what the system says of the links is taken as true (asking it costs a program started). */
+const LINKS_FRESH_MS = 60_000;
+let linksSeen;
+/** The strom-research:// links this computer takes: said to the app only while the scheme leads to this strom. */
+function links(env) {
+    if (!linksSeen || Date.now() - linksSeen.at > LINKS_FRESH_MS)
+        linksSeen = { at: Date.now(), actions: linkActions(linkHandlerState(env)) };
+    return linksSeen.actions;
+}
+/** At most so many tasks of the queue the app is told (the rest counted): what comes next, then what was put aside. */
+const QUEUE_NEXT = 14;
+const QUEUE_PARKED = 6;
+/** The agent's queue in its order, for the user (records by their names), and how many more there are. */
+function queue(tree, settings) {
+    const lang = tree.lang;
+    const next = rankTasks(tree, tree.list("task"), settings.strategy(tree.config)).map((r) => r.task);
+    const parked = tree.list("task").filter((t) => t.state === "parked");
+    const item = (state) => (t) => ({ id: t.id, text: humanTask(tree, t.what, lang), state });
+    const shown = [...next.slice(0, QUEUE_NEXT).map(item("next")), ...parked.slice(0, QUEUE_PARKED).map(item("parked"))];
+    return { queue: shown, queueMore: next.length + parked.length - shown.length };
+}
+/** The last tree the Strom app sent (through the bridge) that the research took and has not taken back. */
+function lastIntake(tree) {
+    const last = tree
+        .list("input")
+        .filter((i) => i.sync && !i.sync.undone && i.sync.applied.length && i.name.startsWith("strom-app-"))
+        .sort((a, b) => a.created.localeCompare(b.created))
+        .pop();
+    return last ? { id: last.id, at: last.created } : undefined;
+}
 /** What the app shows beside the tree. */
 function status(root, env) {
     const tree = Tree.open(root, env);
+    const settings = new Settings(env, {});
     const waiting = tree.list("task").filter((t) => t.state === "waiting");
+    const newer = knownNewerVersion(settings, env);
+    const intake = lastIntake(tree);
     return {
         strom: VERSION,
         tree: { id: tree.config.id, name: tree.config.name, lang: tree.lang },
@@ -133,7 +176,13 @@ function status(root, env) {
         researches: tree.list("research").map((r) => ({ id: r.id, name: r.name, state: r.state })),
         working: working(root, tree),
         open: openSessions(tree).map((s) => ({ id: s.id, task: s.task, started: s.started })),
-        waiting: waiting.map((t) => ({ id: t.id, what: t.what, on: t.waitingOn ?? "" })),
+        // since when it waits: its last change is the one that made it wait
+        waiting: waiting.map((t) => ({ id: t.id, what: t.what, on: t.waitingOn ?? "", at: t.updated })),
+        links: links(env),
+        ...queue(tree, settings),
+        ...(newer ? { update: { version: newer } } : {}),
+        spend: { ...monthSpend(tree, new Date().toISOString().slice(0, 7)), currency: "USD" },
+        ...(intake ? { lastIntake: intake } : {}),
     };
 }
 /** Run the bridge of the tree here, until idle or stopped. */
@@ -153,7 +202,7 @@ export function serveLive(root, env) {
         }
         if (req.method === "OPTIONS") {
             if (origin) {
-                res.setHeader("Access-Control-Allow-Methods", "GET");
+                res.setHeader("Access-Control-Allow-Methods", "GET, POST");
                 res.setHeader("Access-Control-Allow-Headers", String(req.headers["access-control-request-headers"] ?? ""));
                 if (req.headers["access-control-request-private-network"])
                     res.setHeader("Access-Control-Allow-Private-Network", "true");
@@ -162,22 +211,48 @@ export function serveLive(root, env) {
             return;
         }
         const [, t, what] = (req.url ?? "").split("?")[0].split("/");
+        if (req.method === "POST" && t === token && what === "sync") {
+            receive(req, res, origin);
+            return;
+        }
+        if (req.method === "POST" && t === token && what === "cancel") {
+            nothing(req, res, origin);
+            return;
+        }
+        if (req.method === "POST" && t === token && what === "adopt") {
+            receive(req, res, origin, "adopt");
+            return;
+        }
         if (req.method !== "GET" || t !== token) {
             res.writeHead(404).end();
             return;
         }
         try {
-            if (what === "status") {
+            if (what === "adopt") {
+                // the new research started from the app's link: which tree of the app it waits for (its mark), its name
+                const mark = pendingAdoption(root);
+                const tree = Tree.open(root, env);
+                const body = mark ? { token: mark, name: tree.config.name, tree: tree.config.id } : { error: "this research waits for no tree" };
+                res.writeHead(mark ? 200 : 404, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" }).end(JSON.stringify(body));
+            }
+            else if (what === "status") {
                 res.writeHead(200, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" }).end(JSON.stringify(status(root, env)));
             }
             else if (what === "tree.ged" || what === "images.ged") {
                 const h = head(root);
-                if (!ged || ged.head !== h) {
+                if (!ged || ged.head !== h || ged.links !== (appOpensLinks(new Settings(env, {})) ? links(env).join(" ") : "")) {
                     const tree = Tree.open(root, env);
                     // the images from the cache; new ones made for a while at most (the rest the next time the tree changes)
                     const set = excerptSettings(tree);
                     const images = set ? planExcerpts(tree, set.shared, { quality: set.quality, for: set.for, maxBytes: set.mb * 1024 * 1024, budgetMs: LIVE_IMAGES_MS }) : undefined;
-                    ged = { head: h, text: exportGedcom(tree, { for: "strom", ...(images ? { excerpts: images.of } : {}) }).text };
+                    // an app that opens strom-research:// links: each excerpt's mark, and the links this computer takes
+                    const opens = appOpensLinks(new Settings(env, {}));
+                    const offered = opens ? links(env) : [];
+                    ged = {
+                        head: h,
+                        links: offered.join(" "),
+                        text: exportGedcom(tree, { for: "strom", ...(h ? { head: h } : {}), ...(images ? { excerpts: images.of } : {}), ...(opens ? { clips: true, research: true } : {}), ...(offered.length ? { links: offered } : {}) }).text,
+                    };
                 }
                 res.writeHead(200, { "Content-Type": "text/plain; charset=utf-8", "Cache-Control": "no-store", "X-Strom-Head": h }).end(ged.text);
             }
@@ -194,6 +269,80 @@ export function serveLive(root, env) {
             res.writeHead(500, { "Content-Type": "text/plain; charset=utf-8" }).end(e.message);
         }
     });
+    /** The user's tree from the app: only from its pages, only so large; the answer in the research's language. */
+    const receive = (req, res, origin, as = "sync") => {
+        const reply = (code, body) => res.writeHead(code, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" }).end(JSON.stringify(body));
+        const lang = () => {
+            try {
+                return Tree.open(root, env).lang;
+            }
+            catch {
+                return "en";
+            }
+        };
+        if (!origin) {
+            reply(403, { error: "only the Strom app may send a tree here" });
+            return;
+        }
+        const chunks = [];
+        let size = 0;
+        let over = false;
+        req.on("data", (c) => {
+            size += c.length;
+            if (size > SYNC_MAX_BYTES)
+                over = true;
+            else
+                chunks.push(c);
+        });
+        req.on("end", () => {
+            if (over) {
+                reply(413, { error: ui(lang(), "ui.sync.bridge.large") });
+                return;
+            }
+            try {
+                const text = Buffer.concat(chunks).toString("utf8");
+                if (as === "adopt") {
+                    // kept for the research in the terminal to take in; the app links its tree to this research
+                    receiveAdopted(root, text);
+                    reply(200, { tree: Tree.open(root, env).config.id, head: head(root) ?? "" });
+                    return;
+                }
+                const got = receiveTree(root, env, text);
+                reply(200, { ok: true, changes: got.changes, file: path.basename(got.file) });
+            }
+            catch (e) {
+                const m = e.message;
+                // the new research in the terminal waits for it: told, it stops waiting
+                if (as === "adopt" && pendingAdoption(root))
+                    noteAdoptFailed(root, /empty|no people/.test(m) ? "empty" : "other");
+                const key = /another research/.test(m) ? "ui.sync.bridge.other" : /does not look like/.test(m) ? "ui.sync.bridge.foreign" : /empty|no people|not a GEDCOM/.test(m) ? "ui.sync.bridge.empty" : undefined;
+                reply(400, { error: key ? ui(lang(), key) : m });
+            }
+        });
+    };
+    /** The app sends nothing (unchanged, the user said no, no tree of this research): strom sync --app stops waiting. */
+    const nothing = (req, res, origin) => {
+        const reply = (code, body) => res.writeHead(code, { "Content-Type": "application/json; charset=utf-8", "Cache-Control": "no-store" }).end(JSON.stringify(body));
+        if (!origin) {
+            reply(403, { error: "only the Strom app may say so" });
+            return;
+        }
+        let body = "";
+        req.on("data", (c) => {
+            if (body.length < 4096)
+                body += c.toString("utf8");
+        });
+        req.on("end", () => {
+            let reason = "cancelled";
+            try {
+                reason = String(JSON.parse(body).reason ?? reason);
+            }
+            catch {
+                reason = body.trim() || reason;
+            }
+            reply(200, { ok: true, reason: noteNothingSent(root, reason) });
+        });
+    };
     return new Promise((resolve) => {
         server.listen(0, "127.0.0.1", () => {
             const port = server.address().port;

package/dist/core/phrases.js

@@ -32,6 +32,7 @@ export const PHRASES = {
     "story.why": "{count} facts from records tell the life (generation {generation} of {research}); the family reads it in the Strom app's family book",
     "story.done": "strom story set {id} with every fact it rests on (--fact) — a draft until the user approves it",
     "review.research": "Review of {name}",
+    "review.unproven.research": "People without a record of their own",
     "review.more": " (and {count} more after these)",
     "review.mentions.what": "What the tree already says of {name} outside their data: {list}{more}",
     "review.mentions.why": "records, notes or the diary name {name}, yet their data do not show it — the cheapest finds of a review ({research})",

package/dist/core/review.js

@@ -7,7 +7,7 @@
 // Each kind is at most one task per person at a time, and what a task of that
 // kind took up is never proposed again.
 import { dateYears } from "./gdate.js";
-import { RECORD_KINDS, recordsetsCovering, researchPeople } from "./frontier.js";
+import { birthEstimate, RECORD_KINDS, recordsetsCovering, researchPeople } from "./frontier.js";
 import { birthEvent, displayName, familiesAsPartner, lifespan } from "./people.js";
 import { phrase } from "./phrases.js";
 import { foldText } from "./text.js";
@@ -55,6 +55,11 @@ function citedFor(tree, p) {
     for (const n of p.names)
         for (const c of n.citations ?? [])
             out.add(c.source);
+    // the record naming a family — a child's baptism names its parents — also without a fact of the family
+    for (const f of tree.list("family"))
+        if (!f.retracted && (f.partners.includes(p.id) || f.children.some((c) => c.person === p.id)))
+            for (const c of f.citations ?? [])
+                out.add(c.source);
     for (const other of tree.list("person"))
         for (const e of other.events)
             if (e.participants?.some((x) => x.person === p.id))
@@ -67,6 +72,36 @@ function citedFor(tree, p) {
                     out.add(c.source);
     return out;
 }
+/**
+ * The people no record of their own proves: not one fact of theirs proven or
+ * probable — the living among them marked. Each with how they stand — a record names them elsewhere, their
+ * facts are only leads, or nothing but a note says where they come from.
+ */
+export function unprovenPeople(tree) {
+    const out = [];
+    for (const p of tree.list("person")) {
+        if (p.retracted)
+            continue;
+        const facts = p.events.filter((e) => !e.retracted && e.status !== "retracted" && e.status !== "disproven");
+        if (facts.some((e) => e.status === "proven" || e.status === "probable"))
+            continue;
+        const sources = [...citedFor(tree, p)];
+        const kind = facts.some((e) => e.citations.length) ? "leads" : sources.length ? "named" : "none";
+        out.push({ person: p, kind, sources, living: livingBorn(tree, p) !== undefined });
+    }
+    return out;
+}
+/**
+ * Most likely alive: born (or, by their marriage or eldest child, about) less than DEATH_AFTER_YEARS ago, and no
+ * death recorded — the year, else undefined. Their records are the family's; the registers of those years are
+ * mostly closed.
+ */
+export function livingBorn(tree, p) {
+    if (p.events.some((e) => !e.retracted && e.status !== "disproven" && DEATHS.has(e.kind)))
+        return undefined;
+    const born = birthEstimate(tree, p, tree.lang).year;
+    return born !== undefined && born > new Date().getFullYear() - DEATH_AFTER_YEARS ? born : undefined;
+}
 /** The models that read each source: the sessions that recorded or corrected it (the user's hand counts as "user"). */
 export function readersOf(tree) {
     const model = new Map(tree.list("session").map((s) => [s.id, s.model ?? "unknown"]));
@@ -207,10 +242,13 @@ export function reviewProposals(tree, research) {
         };
         propose("mentions", "enrich", mentionsOf(tree, p, citedFor(tree, p)));
         propose("entries", "enrich", entriesOf(tree, p));
-        const single = singleReadings(tree, p);
-        propose("verify", "verify", single);
-        if (reread && readers)
-            propose("reread", "verify", rereads(tree, p, reread, readers).filter((e) => !single.includes(e)), { model: reread });
+        // the people without a record want one of their own first: checking what their family's facts rest on can wait
+        if (!research.review?.unproven) {
+            const single = singleReadings(tree, p);
+            propose("verify", "verify", single);
+            if (reread && readers)
+                propose("reread", "verify", rereads(tree, p, reread, readers).filter((e) => !single.includes(e)), { model: reread });
+        }
         propose("conflicts", "verify", openConflicts(tree, p));
         out.push(...gaps(tree, research, p, name, tasks));
     }

package/dist/core/schema.js

@@ -98,6 +98,7 @@ export const SCHEMAS = {
     },
     conflict: {
         title: S({ req: true, max: 200 }),
+        fact: S({ max: 8 }),
         subject: RS(ANY_SUBJECT, 1),
         claims: { t: "array", req: true, min: 2, of: { source: R("source"), value: S({ req: true, max: 500 }), note: S({ max: 500 }) } },
         state: S({ req: true, enum: ["open", "resolved"] }),

package/dist/core/self.js

@@ -33,6 +33,23 @@ export function installation() {
     }
     return (cached = { kind: "npm" });
 }
+/**
+ * Another strom on disk than the one running (strom update replaced its code or its Node): this process goes on
+ * with what it loaded, so a person is told to start strom again. `version`: the running one's.
+ */
+export function replacedOnDisk(version) {
+    const inst = installation();
+    if (inst.kind !== "installed" || !inst.root)
+        return false;
+    try {
+        const app = JSON.parse(fs.readFileSync(path.join(inst.root, "app", "package.json"), "utf8"));
+        const info = JSON.parse(fs.readFileSync(path.join(inst.root, "install.json"), "utf8"));
+        return app.version !== version || info.node !== inst.node;
+    }
+    catch {
+        return false;
+    }
+}
 /** The program and arguments that run strom: this Node and its entry script (cli.ts from sources, cli.js built). */
 export function stromLauncher() {
     const cli = path.resolve(path.dirname(here), "..", here.endsWith(".ts") ? "cli.ts" : "cli.js");

package/dist/core/session.js

@@ -157,3 +157,9 @@ export function recentSessions(tree, research, n = 2) {
         .sort((a, b) => (b.ended ?? b.updated).localeCompare(a.ended ?? a.updated))
         .slice(0, n);
 }
+/** What the agent's sessions of a month ("2026-09", by when they started) cost: how many, the dollars known (a session stopped before it said: its known part). */
+export function monthSpend(tree, month) {
+    const of = tree.list("session").filter((s) => s.started.slice(0, 7) === month);
+    const amount = of.reduce((sum, s) => sum + (s.metrics?.costUsd ?? 0), 0);
+    return { month, sessions: of.length, amount: Math.round(amount * 100) / 100 };
+}

package/dist/core/stromapp.js

@@ -30,6 +30,44 @@ export const APP_OPENS_RESEARCH = true;
 export function appOpensResearch(settings) {
     return APP_OPENS_RESEARCH || stromAppUrl(settings) !== STROM_APP_URL;
 }
+/**
+ * The Strom app sends the user's edits back (?send=<the bridge>, POST <bridge>/sync — the app's spec
+ * docs/ZADANI_SYNC_Z_APLIKACE.md): the first version of stromapp.info that does (3.3.0, 2026-09-27).
+ * Another copy of the app (its beta, its development: strom.app.url) is taken as current.
+ */
+export const APP_SENDS_CHANGES = "3.3.0";
+export function appSendsChanges(settings) {
+    return APP_SENDS_CHANGES !== undefined || stromAppUrl(settings) !== STROM_APP_URL;
+}
+/**
+ * The Strom app opens strom-research:// links (the app's spec docs/ZADANI_VYZKUM_ODKAZY_Z_APLIKACE.md): it reads
+ * each excerpt's mark (_STROM_CLIP) and the links a research offers (_STROM_LINKS in the GEDCOM the bridge serves).
+ * The first version of stromapp.info that does (3.4.0, 2026-09-27); another copy of the app (its beta, its
+ * development: strom.app.url) is taken as current. An app of a known version (strom.version) goes by it.
+ */
+export const APP_OPENS_LINKS = "3.4.0";
+export function appOpensLinks(settings, version) {
+    if (stromAppUrl(settings) !== STROM_APP_URL)
+        return true;
+    if (!APP_OPENS_LINKS)
+        return false;
+    if (!version)
+        return true;
+    const n = (v) => v.split(".").map((x) => Number.parseInt(x, 10) || 0);
+    const [a, b] = [n(version), n(APP_OPENS_LINKS)];
+    for (let i = 0; i < 3; i++)
+        if ((a[i] ?? 0) !== (b[i] ?? 0))
+            return (a[i] ?? 0) > (b[i] ?? 0);
+    return true;
+}
+/** The address that opens the Strom app to send the user's edited tree to the bridge. */
+export function sendAppUrl(bridge, settings) {
+    return `${stromAppUrl(settings)}?send=${encodeURIComponent(bridge)}`;
+}
+/** The address that opens the Strom app to hand one of its trees to a new research (strom-research://new). */
+export function adoptAppUrl(bridge, settings) {
+    return `${stromAppUrl(settings)}?adopt=${encodeURIComponent(bridge)}`;
+}
 /** The address that opens the Strom app following a research through its bridge. */
 export function liveAppUrl(bridge, settings) {
     return `${stromAppUrl(settings)}?live=${encodeURIComponent(bridge)}`;