ultimate-brain 0.0.0-stage → 0.2.0

package/dist/lib/apply.js

@@ -0,0 +1,524 @@
+import { isDeepStrictEqual } from "node:util";
+import { posix } from "node:path";
+import { assertNoProblems, isRecord, unknownKeys } from "./input.js";
+import { compareCodePoints } from "./notes.js";
+import { stageNewItem } from "./proposals.js";
+import { loadSchemas } from "./schemas.js";
+import { formatDate } from "./time.js";
+const TIMESTAMP = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z$/;
+const ACTIONS = ["approve", "reject", "edit"];
+const EDITABLE = new Set(["update_fact", "contradiction", "add_to_note"]);
+/** Reference fields a merge leaves alone: the meeting side of a persisted pair (spec/schema.md §11.2). */
+const PAIR_FIELDS = new Set(["decisions", "questions", "decided_in", "raised_in"]);
+/** Corrections change knowledge notes only: sources are immutable and proposals are records. */
+const KNOWLEDGE_TYPES = new Set(["area", "goal", "project", "person", "org", "meeting", "decision", "question", "concept", "memory"]);
+const REFERENCE_FIELDS = [
+    "area", "areas", "goal", "client", "org", "projects", "people", "attendees", "deciders", "source", "sources",
+    "answer", "project", "generated_from", "facts",
+];
+/** Check the input shape (spec/cli.md §5.7); any problem fails the whole command. */
+export function parseApplyInput(input) {
+    if (!isRecord(input))
+        assertNoProblems([{ pointer: "", message: "must be an object" }]);
+    const record = input;
+    const problems = unknownKeys(record, ["corrections", "decisions"], "");
+    const corrections = record.corrections ?? [];
+    const decisions = record.decisions ?? [];
+    if (!Array.isArray(corrections))
+        problems.push({ pointer: "/corrections", message: "must be a list" });
+    if (!Array.isArray(decisions))
+        problems.push({ pointer: "/decisions", message: "must be a list" });
+    assertNoProblems(problems);
+    if (corrections.length === 0 && decisions.length === 0) {
+        assertNoProblems([{ pointer: "", message: "needs at least one correction or decision" }]);
+    }
+    corrections.forEach((item, index) => {
+        const pointer = `/corrections/${index}`;
+        if (!isRecord(item))
+            return problems.push({ pointer, message: "must be an object" });
+        problems.push(...unknownKeys(item, ["target", "field", "value", "observed_at"], pointer));
+        if (typeof item.target !== "string")
+            problems.push({ pointer: `${pointer}/target`, message: "must be a note id" });
+        if (typeof item.field !== "string")
+            problems.push({ pointer: `${pointer}/field`, message: "must be a string" });
+        if (!Object.hasOwn(item, "value"))
+            problems.push({ pointer: `${pointer}/value`, message: "is required (null removes a reference)" });
+        if (!isTimestamp(item.observed_at))
+            problems.push({ pointer: `${pointer}/observed_at`, message: "must be an ISO 8601 UTC timestamp" });
+    });
+    decisions.forEach((item, index) => {
+        const pointer = `/decisions/${index}`;
+        if (!isRecord(item))
+            return problems.push({ pointer, message: "must be an object" });
+        problems.push(...unknownKeys(item, ["proposal", "action", "value", "decided_at", "decided_by"], pointer));
+        if (typeof item.proposal !== "string")
+            problems.push({ pointer: `${pointer}/proposal`, message: "must be a proposal id" });
+        if (!ACTIONS.includes(item.action))
+            problems.push({ pointer: `${pointer}/action`, message: "must be approve, reject or edit" });
+        if (item.action === "edit" && (item.value === undefined || item.value === null))
+            problems.push({ pointer: `${pointer}/value`, message: "is required for edit" });
+        if (item.action !== "edit" && item.value !== undefined)
+            problems.push({ pointer: `${pointer}/value`, message: "is only allowed for edit" });
+        if (!isTimestamp(item.decided_at))
+            problems.push({ pointer: `${pointer}/decided_at`, message: "must be an ISO 8601 UTC timestamp" });
+        if (item.decided_by !== "notion" && item.decided_by !== "chat")
+            problems.push({ pointer: `${pointer}/decided_by`, message: "must be notion or chat" });
+    });
+    assertNoProblems(problems);
+    return { corrections: corrections, decisions: decisions };
+}
+/**
+ * Apply corrections, then decisions, each in input order (spec/cli.md §5.7, spec/schema.md
+ * §11.2). Each item is staged and validated on its own: a failed item leaves the workspace as it
+ * was, and later items see the results of earlier ones. Nothing is written; the caller commits.
+ */
+export function applyAll(workspace, input, options) {
+    const today = formatDate(options.now);
+    const result = {
+        corrections: [],
+        decisions: [],
+        summary: { applied: 0, closed: 0, recorded: 0, corrected: 0, skipped: 0, failed: 0 },
+        log: [],
+    };
+    for (const correction of input.corrections) {
+        const item = runItem(workspace, () => applyCorrection(workspace, correction, today));
+        result.corrections.push({ target: correction.target, field: correction.field, ...item.outcome });
+        if (item.outcome.result === "applied") {
+            result.summary.corrected += 1;
+            result.log.push({ op: "correct", id: correction.target, title: titleOf(workspace, correction.target), pairs: [["field", correction.field]] });
+        }
+        else {
+            result.summary[item.outcome.result] += 1;
+        }
+    }
+    const decisions = input.decisions ?? recordedDecisions(workspace);
+    for (const decision of decisions) {
+        const proposal = workspace.get(decision.proposal);
+        const kind = proposal?.type === "proposal" ? String(proposal.attributes.kind) : undefined;
+        const item = runItem(workspace, () => applyDecision(workspace, decision, today, options.recordOnly));
+        result.decisions.push({ proposal: decision.proposal, ...(kind === undefined ? {} : { kind }), action: item.action ?? decision.action, ...item.outcome });
+        result.summary[item.outcome.result] += 1;
+        if (item.outcome.result === "applied" || item.outcome.result === "closed") {
+            result.log.push({ op: "apply", id: decision.proposal, title: titleOf(workspace, decision.proposal), pairs: [["result", item.outcome.result]] });
+        }
+    }
+    return result;
+}
+class ItemFailure extends Error {
+    reason;
+    constructor(reason, message) {
+        super(message);
+        this.reason = reason;
+    }
+}
+/** Run one item atomically: on failure or a result that adds lint errors, restore the workspace. */
+function runItem(workspace, run) {
+    const start = workspace.checkpoint();
+    let outcome;
+    try {
+        outcome = run();
+    }
+    catch (error) {
+        workspace.restore(start);
+        if (error instanceof ItemFailure)
+            return { outcome: { result: "failed", reason: error.reason, message: error.message, changed: [] } };
+        // Anything else (a new_item whose note cannot be written, say) fails this item only (spec/cli.md §3.6.3).
+        const message = error instanceof Error ? error.message : String(error);
+        return { outcome: { result: "failed", reason: "INVALID_RESULT", message, changed: [] } };
+    }
+    const changed = workspace.changedSince(start);
+    const errors = workspace.newErrors();
+    if (errors.length > 0) {
+        workspace.restore(start);
+        const message = errors.map((issue) => `${issue.path}: ${issue.rule}: ${issue.message}`).join("; ");
+        return { outcome: { result: "failed", reason: "INVALID_RESULT", message, changed: [] } };
+    }
+    const { action, ...rest } = outcome;
+    return { outcome: { ...rest, changed }, action };
+}
+function applyCorrection(workspace, correction, today) {
+    const note = existing(workspace, correction.target);
+    const document = workspace.edit(note);
+    const attributes = document.attributes;
+    const factKey = /^facts\.([a-z][a-z0-9_]*)$/.exec(correction.field)?.[1];
+    const known = loadSchemas().knownKeys(note.type);
+    const correctable = KNOWLEDGE_TYPES.has(note.type) && factKey !== undefined
+        ? known?.has("facts") === true
+        : KNOWLEDGE_TYPES.has(note.type) && ["title", "summary", "why", "area", "goal", "client", "org", "people"].includes(correction.field) && known?.has(correction.field) === true;
+    if (!correctable)
+        throw new ItemFailure("FIELD_NOT_CORRECTABLE", `${correction.field} cannot be corrected on a ${note.type}`);
+    const current = factKey === undefined ? attributes[correction.field] : record(attributes.facts)[factKey];
+    if (isDeepStrictEqual(current ?? null, correction.value))
+        return { result: "skipped", reason: "NO_CHANGE" };
+    if (factKey !== undefined) {
+        const date = correction.observed_at.slice(0, 10);
+        setFact(attributes, factKey, correction.value, date, date, "notion-edit");
+    }
+    else if (correction.value === null) {
+        delete attributes[correction.field];
+    }
+    else {
+        attributes[correction.field] = correction.value;
+    }
+    attributes.updated = today;
+    workspace.save(note.path, document);
+    return { result: "applied" };
+}
+function applyDecision(workspace, input, today, recordOnly) {
+    const proposal = workspace.get(input.proposal);
+    if (proposal === undefined || proposal.type !== "proposal")
+        throw new ItemFailure("UNKNOWN_ID", `No proposal with id ${input.proposal}`);
+    const document = workspace.edit(proposal);
+    const p = document.attributes;
+    if (p.status === "applied" || p.status === "closed")
+        return { result: "skipped", reason: "ALREADY_TERMINAL" };
+    const incoming = { action: input.action, ...(input.value === undefined ? {} : { value: input.value }), decided_at: input.decided_at, decided_by: input.decided_by };
+    const recorded = isRecord(p.decision) ? p.decision : undefined;
+    let decision = incoming;
+    if (recorded !== undefined && (recorded.action !== incoming.action || !isDeepStrictEqual(recorded.value, incoming.value))) {
+        // You changed your mind in Notion before it was applied: the later decision wins.
+        if (Date.parse(recorded.decided_at) >= Date.parse(incoming.decided_at))
+            decision = recorded;
+    }
+    else if (recorded !== undefined) {
+        decision = recorded;
+    }
+    if (decision.action === "edit" && !EDITABLE.has(String(p.kind))) {
+        throw new ItemFailure("EDIT_NOT_ALLOWED", `edit is not allowed on a ${String(p.kind)} proposal (spec/schema.md §11.1)`);
+    }
+    const action = decision.action === incoming.action ? undefined : decision.action;
+    p.decision = decision;
+    p.status = decision.action === "approve" ? "approved" : decision.action === "edit" ? "edited" : "rejected";
+    p.updated = today;
+    if (recordOnly) {
+        workspace.save(proposal.path, document);
+        return { result: "recorded", action };
+    }
+    if (decision.action === "reject") {
+        p.status = "closed";
+        workspace.save(proposal.path, document);
+        return { result: "closed", action };
+    }
+    const D = decision.decided_at.slice(0, 10);
+    const V = decision.action === "edit" ? decision.value : undefined;
+    const stale = applyKind(workspace, p, proposal.path, V, D, today);
+    if (stale !== null) {
+        p.status = "closed";
+        p.closed_reason = "stale";
+        workspace.save(proposal.path, document);
+        return { result: "closed", reason: "STALE_PROPOSAL", message: stale, action };
+    }
+    p.status = "applied";
+    workspace.save(proposal.path, document);
+    return { result: "applied", action };
+}
+/** Apply a proposal's kind to its targets. Returns a message when the proposal is stale. */
+function applyKind(workspace, p, proposalPath, V, D, today) {
+    const kind = String(p.kind);
+    if (kind === "new_item") {
+        stageNewItem(workspace, p.note, proposalPath, new Date(`${today}T00:00:00Z`));
+        return null;
+    }
+    const target = existing(workspace, String(p.target));
+    const document = workspace.edit(target);
+    const a = document.attributes;
+    const field = String(p.field);
+    if (kind === "update_fact" || kind === "contradiction") {
+        const current = record(a.facts)[field];
+        if (!isDeepStrictEqual(current, p.before)) {
+            const shown = (value) => (value === undefined ? "absent" : JSON.stringify(value));
+            return `facts.${field} is ${shown(current)}, proposal expected ${shown(p.before)}`;
+        }
+    }
+    switch (kind) {
+        case "update_fact":
+            setFact(a, field, V ?? p.after, String(p.from), D, String(p.source));
+            break;
+        case "contradiction":
+            if (V === undefined)
+                contest(a, field, p.after, String(p.from), D, String(p.source));
+            else
+                resolveContradiction(a, field, V, String(p.from), D, String(p.source));
+            break;
+        case "add_to_note": {
+            const content = String(V ?? p.content).replace(/\n+$/, "");
+            const head = document.body.replace(/\n+$/, "");
+            document.body = `${head === "" ? "" : `${head}\n\n`}${content}\nSource: ${String(p.source)}\n`;
+            a.sources = union(list(a.sources), [p.source]);
+            break;
+        }
+        case "add_link":
+            if (!list(a[field]).some((value) => isDeepStrictEqual(value, p.after)))
+                a[field] = [...list(a[field]), p.after];
+            break;
+        case "supersede": {
+            const older = existing(workspace, String(p.supersedes));
+            const olderDocument = workspace.edit(older);
+            supersedePair(a, target.id, olderDocument.attributes, older.id);
+            olderDocument.attributes.updated = today;
+            workspace.save(older.path, olderDocument);
+            break;
+        }
+        case "merge":
+            merge(workspace, target, existing(workspace, String(p.merge_into)), today);
+            return null;
+        default:
+            throw new ItemFailure("INVALID_RESULT", `Unknown proposal kind ${kind}`);
+    }
+    a.updated = today;
+    workspace.save(target.path, document);
+    return null;
+}
+/** update_fact (and a facts.<key> correction): retire accepted entries, append the new value. */
+function setFact(a, field, value, from, learned, source) {
+    a.timeline = [
+        ...list(a.timeline).map((entry) => isRecord(entry) && entry.field === field && entry.assessment === "accepted" ? entryWith(entry, { until: from, assessment: "superseded" }) : entry),
+        timelineEntry(field, value, from, learned, source, "accepted"),
+    ];
+    a.facts = { ...record(a.facts), [field]: value };
+}
+/** contradiction approved: keep both claims as contested and drop the current fact. */
+function contest(a, field, value, from, learned, source) {
+    a.timeline = [
+        ...list(a.timeline).map((entry) => isRecord(entry) && entry.field === field && entry.assessment === "accepted" ? entryWith(entry, { assessment: "contested" }) : entry),
+        timelineEntry(field, value, from, learned, source, "contested"),
+    ];
+    const facts = { ...record(a.facts) };
+    delete facts[field];
+    if (Object.keys(facts).length === 0)
+        delete a.facts;
+    else
+        a.facts = facts;
+}
+/** contradiction edited: V is the accepted truth (spec/schema.md §11.2). */
+function resolveContradiction(a, field, value, from, learned, source) {
+    const timeline = list(a.timeline);
+    const live = timeline
+        .map((entry, index) => ({ entry, index }))
+        .filter(({ entry }) => isRecord(entry) && entry.field === field && (entry.assessment === "accepted" || entry.assessment === "contested"));
+    const matches = live.filter(({ entry }) => isDeepStrictEqual(record(entry).value, value));
+    const keep = matches.reduce((latest, candidate) => latest === undefined || String(record(candidate.entry).learned) >= String(record(latest.entry).learned) ? candidate : latest, undefined);
+    const next = [...timeline];
+    for (const { entry, index } of live) {
+        next[index] = index === keep?.index ? entryWith(record(entry), { assessment: "accepted" }) : entryWith(record(entry), { until: from, assessment: "superseded" });
+    }
+    if (keep === undefined)
+        next.push(timelineEntry(field, value, from, learned, source, "accepted"));
+    a.timeline = next;
+    a.facts = { ...record(a.facts), [field]: value };
+}
+/** Write both sides of a supersession; the older note is archived (spec/schema.md §11.2). */
+function supersedePair(newer, newerId, older, olderId) {
+    newer.relations = unionRelations(list(newer.relations), [{ type: "supersedes", target: olderId }]);
+    older.relations = unionRelations(list(older.relations), [{ type: "superseded_by", target: newerId }]);
+    older.lifecycle = "archived";
+    if (newer.type === "decision" && older.type === "decision") {
+        older.assessment = "superseded";
+        older.valid_until = newer.valid_from ?? newer.date;
+    }
+}
+/** merge X (the duplicate) into Y (spec/schema.md §11.2). */
+function merge(workspace, x, y, today) {
+    // 1. References, in every note except X, Y, sources and proposals.
+    for (const note of workspace.notes) {
+        if (note.id === x.id || note.id === y.id || note.type === "source" || note.type === "proposal")
+            continue;
+        const document = workspace.edit(note);
+        const before = JSON.stringify([document.attributes, document.body]);
+        rewriteReferences(document.attributes, x.id, y.id);
+        document.body = rewriteLinks(document.body, note.path, x.path, y.path);
+        if (JSON.stringify([document.attributes, document.body]) !== before) {
+            document.attributes.updated = today;
+            workspace.save(note.path, document);
+        }
+    }
+    // 2. Into Y.
+    const xDocument = workspace.edit(workspace.get(x.id));
+    const yDocument = workspace.edit(workspace.get(y.id));
+    const xa = xDocument.attributes;
+    const ya = yDocument.attributes;
+    const unionInto = (key, extra = []) => {
+        const merged = union(list(ya[key]), [...list(xa[key]), ...extra]);
+        if (merged.length > 0)
+            ya[key] = merged;
+    };
+    unionInto("aliases", [xa.title]);
+    unionInto("tags");
+    unionInto("sources");
+    unionInto("projects");
+    const carried = list(xa.relations).filter((relation) => {
+        const { type, target } = record(relation);
+        return type !== "supersedes" && type !== "superseded_by" && target !== x.id && target !== y.id;
+    });
+    if (carried.length > 0)
+        ya.relations = unionRelations(list(ya.relations), carried);
+    const yFacts = record(ya.facts);
+    const timeline = [...list(ya.timeline)];
+    for (const entry of list(xa.timeline)) {
+        if (timeline.some((other) => isDeepStrictEqual(other, entry)))
+            continue;
+        const { field, value, assessment } = record(entry);
+        const conflicting = Object.hasOwn(yFacts, String(field)) && assessment === "accepted" && !isDeepStrictEqual(value, yFacts[String(field)]);
+        timeline.push(conflicting ? entryWith(record(entry), { until: today, assessment: "superseded" }) : entry);
+    }
+    if (timeline.length > 0)
+        ya.timeline = timeline;
+    const facts = { ...yFacts };
+    for (const [key, value] of Object.entries(record(xa.facts)))
+        if (!Object.hasOwn(facts, key))
+            facts[key] = value;
+    if (Object.keys(facts).length > 0)
+        ya.facts = facts;
+    const yBody = yDocument.body.replace(/\n+$/, "");
+    const xBody = xDocument.body.replace(/^\n+|\n+$/g, "");
+    yDocument.body = `${yBody === "" ? "" : `${yBody}\n\n`}## Merged from ${String(xa.title)}\n${xBody === "" ? "" : `\n${xBody}\n`}`;
+    // 3. The pair: X archived and superseded by Y.
+    supersedePair(ya, y.id, xa, x.id);
+    xa.updated = today;
+    ya.updated = today;
+    workspace.save(x.path, xDocument);
+    workspace.save(y.path, yDocument);
+}
+function rewriteReferences(a, from, to) {
+    const swap = (value) => (value === from ? to : value);
+    for (const key of REFERENCE_FIELDS) {
+        if (PAIR_FIELDS.has(key) || a[key] === undefined)
+            continue;
+        const value = a[key];
+        if (Array.isArray(value))
+            a[key] = union([], value.map(swap));
+        else if (isRecord(value))
+            a[key] = Object.fromEntries(Object.entries(value).map(([k, v]) => [k, swap(v)]));
+        else
+            a[key] = swap(value);
+    }
+    if (Array.isArray(a.relations)) {
+        a.relations = unionRelations([], a.relations.map((relation) => {
+            const r = record(relation);
+            return r.type === "supersedes" || r.type === "superseded_by" ? relation : { ...r, target: swap(r.target) };
+        }));
+    }
+    if (Array.isArray(a.timeline)) {
+        a.timeline = a.timeline.map((entry) => {
+            const e = record(entry);
+            return e.value === from || e.source === from ? { ...e, value: swap(e.value), source: swap(e.source) } : entry;
+        });
+    }
+}
+/** Point relative Markdown links to X's file at Y's file instead, outside fenced code blocks. */
+function rewriteLinks(body, notePath, xPath, yPath) {
+    const dir = posix.dirname(notePath);
+    const rewriteTarget = (raw) => {
+        const target = raw.startsWith("<") ? raw.slice(1, -1) : raw;
+        if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("#"))
+            return raw;
+        const suffixAt = target.search(/[?#]/);
+        const path = suffixAt === -1 ? target : target.slice(0, suffixAt);
+        const suffix = suffixAt === -1 ? "" : target.slice(suffixAt);
+        let decoded = path;
+        try {
+            decoded = decodeURIComponent(path);
+        }
+        catch {
+            // keep as written
+        }
+        if (posix.normalize(posix.join(dir, decoded)) !== xPath)
+            return raw;
+        const replaced = `${posix.relative(dir, yPath)}${suffix}`;
+        return raw.startsWith("<") ? `<${replaced}>` : replaced;
+    };
+    const rewriteProse = (prose) => {
+        const spans = [];
+        const masked = prose.replace(/(`+)((?:(?!\r?\n[ \t]*\r?\n)[\s\S])*?)\1/g, (span) => {
+            const marker = `\u0000${spans.length}\u0000`;
+            spans.push(span);
+            return marker;
+        });
+        return masked
+            .replace(/\]\(\s*(<[^>]*>|[^)\s]+)/g, (match, raw) => match.replace(raw, () => rewriteTarget(raw)))
+            .replace(/^(\s{0,3}\[(?!\^)[^\]\n]+\]:\s*)(<[^>]*>|[^\s]+)/gm, (match, prefix, raw) => `${prefix}${rewriteTarget(raw)}`)
+            .replace(/<([^<>\n]+)>/g, (match, target) => rewriteTarget(`<${target}>`))
+            .replace(/\u0000(\d+)\u0000/g, (_marker, index) => spans[Number(index)]);
+    };
+    const lines = body.split(/(?<=\n)/);
+    const output = [];
+    let prose = [];
+    let fence;
+    const flush = () => {
+        if (prose.length > 0)
+            output.push(rewriteProse(prose.join("")));
+        prose = [];
+    };
+    for (const line of lines) {
+        if (fence === undefined) {
+            const open = /^\s{0,3}(`{3,}|~{3,})/.exec(line)?.[1];
+            if (open !== undefined) {
+                flush();
+                fence = { character: open[0], length: open.length };
+                output.push(line);
+            }
+            else
+                prose.push(line);
+        }
+        else {
+            output.push(line);
+            const close = new RegExp(`^\\s{0,3}${fence.character}{${fence.length},}\\s*(?:\\n)?$`);
+            if (close.test(line))
+                fence = undefined;
+        }
+    }
+    flush();
+    return output.join("");
+}
+/** Proposals holding a recorded decision that is not applied yet, oldest first. */
+function recordedDecisions(workspace) {
+    return workspace.notes
+        .filter((note) => note.type === "proposal" && ["approved", "edited", "rejected"].includes(String(note.attributes.status)) && isRecord(note.attributes.decision))
+        .sort((a, b) => compareCodePoints(String(a.attributes.created), String(b.attributes.created)) || compareCodePoints(a.id, b.id))
+        .map((note) => ({ proposal: note.id, ...note.attributes.decision }));
+}
+function existing(workspace, id) {
+    const note = workspace.get(id);
+    if (note === undefined)
+        throw new ItemFailure("UNKNOWN_ID", `No note with id ${id}`);
+    return note;
+}
+function titleOf(workspace, id) {
+    const title = workspace.get(id)?.attributes.title;
+    return typeof title === "string" ? title : "";
+}
+/** A timeline entry with its keys in the spec/schema.md §5 order. */
+function timelineEntry(field, value, from, learned, source, assessment) {
+    return { field, value, from, learned, source, assessment };
+}
+const ENTRY_ORDER = ["field", "value", "from", "until", "learned", "source", "assessment", "note"];
+function entryWith(entry, changes) {
+    const merged = { ...entry, ...changes };
+    const rank = (key) => (ENTRY_ORDER.includes(key) ? ENTRY_ORDER.indexOf(key) : ENTRY_ORDER.length);
+    return Object.fromEntries(Object.entries(merged).sort(([a], [b]) => rank(a) - rank(b)));
+}
+function union(base, extra) {
+    const out = [];
+    for (const value of [...base, ...extra])
+        if (!out.some((other) => isDeepStrictEqual(other, value)))
+            out.push(value);
+    return out;
+}
+function unionRelations(base, extra) {
+    const out = [];
+    for (const relation of [...base, ...extra]) {
+        const { type, target } = record(relation);
+        if (!out.some((other) => record(other).type === type && record(other).target === target))
+            out.push(relation);
+    }
+    return out;
+}
+function list(value) {
+    return Array.isArray(value) ? value : [];
+}
+function record(value) {
+    return isRecord(value) ? value : {};
+}
+function isTimestamp(value) {
+    return typeof value === "string" && TIMESTAMP.test(value) && !Number.isNaN(Date.parse(value));
+}

package/dist/lib/args.js

@@ -0,0 +1,63 @@
+import { BrainError } from "./errors.js";
+/** Global options accepted by every command (spec/cli.md §3.1). */
+export const GLOBAL_OPTIONS = {
+    brain: "string",
+    json: "boolean",
+    now: "string",
+    help: "boolean",
+};
+/**
+ * Parse `--name value`, `--name=value`, boolean flags and `-h` anywhere in argv.
+ * Unknown options are a usage error; a repeated string option keeps the last value.
+ */
+export function parseArgs(argv, spec) {
+    const all = { ...GLOBAL_OPTIONS, ...spec };
+    const options = {};
+    const positionals = [];
+    for (let index = 0; index < argv.length; index += 1) {
+        const arg = argv[index];
+        if (arg === "-h") {
+            options.help = true;
+            continue;
+        }
+        if (arg === "--") {
+            positionals.push(...argv.slice(index + 1));
+            break;
+        }
+        if (arg === "-" || !arg.startsWith("-")) {
+            positionals.push(arg);
+            continue;
+        }
+        if (!arg.startsWith("--"))
+            throw new BrainError("USAGE", `Unknown option: ${arg}`);
+        const equals = arg.indexOf("=");
+        const name = arg.slice(2, equals === -1 ? undefined : equals);
+        const kind = all[name];
+        if (kind === undefined)
+            throw new BrainError("USAGE", `Unknown option: --${name}`);
+        if (kind === "boolean") {
+            if (equals !== -1)
+                throw new BrainError("USAGE", `Option --${name} takes no value`);
+            options[name] = true;
+            continue;
+        }
+        let value;
+        if (equals !== -1) {
+            value = arg.slice(equals + 1);
+        }
+        else {
+            value = argv[index + 1];
+            index += 1;
+        }
+        if (value === undefined || value === "")
+            throw new BrainError("USAGE", `Option --${name} needs a value`);
+        if (kind === "list") {
+            const existing = options[name];
+            options[name] = [...(Array.isArray(existing) ? existing : []), value];
+        }
+        else {
+            options[name] = value;
+        }
+    }
+    return { options, positionals };
+}

package/dist/lib/brain-path.js

@@ -0,0 +1,91 @@
+import { constants } from "node:fs";
+import { access, readFile, realpath, stat } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { BrainError } from "./errors.js";
+/** Resolve and validate the brain directory using the documented precedence. */
+export async function resolveBrainDirectory(options = {}) {
+    const env = options.env ?? process.env;
+    const homeDirectory = options.homeDirectory ?? homedir();
+    const higherPriority = firstNonEmpty(options.brainFlag, env.BRAIN_DIR);
+    const configured = higherPriority === undefined ? await readConfiguredBrain(homeDirectory) : undefined;
+    const candidate = higherPriority ?? configured?.brain;
+    if (candidate === undefined) {
+        throw new BrainError("BRAIN_NOT_CONFIGURED", "Brain directory is not configured. Pass --brain, set BRAIN_DIR, or set brain in ~/.config/ultimate-brain/config.json.");
+    }
+    const expanded = expandHome(candidate, homeDirectory);
+    // A relative path in the config file is relative to that file's folder (spec/cli.md §4).
+    const absolute = configured === undefined ? resolve(expanded) : resolve(configured.folder, expanded);
+    let directory;
+    try {
+        const metadata = await stat(absolute);
+        if (!metadata.isDirectory()) {
+            throw new BrainError("BRAIN_NOT_FOUND", `Brain path is not a directory: ${absolute}`);
+        }
+        directory = await realpath(absolute);
+    }
+    catch (error) {
+        if (error instanceof BrainError)
+            throw error;
+        throw new BrainError("BRAIN_NOT_FOUND", `Brain directory does not exist or cannot be read: ${absolute}`);
+    }
+    if (await isProductRepository(directory)) {
+        throw new BrainError("BRAIN_IS_PRODUCT_REPO", `Refusing to use the Ultimate Brain product repository as a brain: ${directory}`);
+    }
+    return directory;
+}
+async function readConfiguredBrain(homeDirectory) {
+    const configPath = join(homeDirectory, ".config", "ultimate-brain", "config.json");
+    try {
+        const raw = await readFile(configPath, "utf8");
+        const parsed = JSON.parse(raw);
+        if (!isRecord(parsed)) {
+            throw new Error("configuration must be a JSON object");
+        }
+        const config = parsed;
+        const extra = Object.keys(parsed).filter((key) => key !== "brain");
+        if (extra.length > 0) {
+            throw new Error(`unknown key "${extra[0]}"; the only key is "brain"`);
+        }
+        if (typeof config.brain !== "string" || config.brain.trim() === "") {
+            throw new Error('the "brain" value must be a non-empty string');
+        }
+        return { brain: config.brain, folder: dirname(configPath) };
+    }
+    catch (error) {
+        if (isNodeError(error) && error.code === "ENOENT") {
+            return undefined;
+        }
+        const detail = error instanceof Error ? error.message : String(error);
+        throw new BrainError("BRAIN_CONFIG_INVALID", `Cannot read brain configuration at ${configPath}: ${detail}`);
+    }
+}
+export async function isProductRepository(directory) {
+    const markers = [join(directory, "spec", "cli.md"), join(directory, "src", "cli.ts")];
+    const found = await Promise.all(markers.map(async (marker) => {
+        try {
+            await access(marker, constants.F_OK);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }));
+    return found.every(Boolean);
+}
+function firstNonEmpty(...values) {
+    return values.find((value) => value !== undefined && value.trim() !== "")?.trim();
+}
+function expandHome(path, homeDirectory) {
+    if (path === "~")
+        return homeDirectory;
+    if (path.startsWith("~/"))
+        return join(homeDirectory, path.slice(2));
+    return path;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}