ultimate-brain 0.0.0-stage → 0.1.1

package/dist/lib/index-builder.js

@@ -0,0 +1,216 @@
+import { compareCodePoints } from "./notes.js";
+export const INDEX_HEADER = "<!-- GENERATED by brain index. Do not edit. -->";
+/** index.md sections, in order (spec/schema.md §13). */
+const SECTIONS = [
+    ["area", "Areas"],
+    ["goal", "Goals"],
+    ["project", "Projects"],
+    ["person", "People"],
+    ["org", "Orgs"],
+    ["decision", "Decisions"],
+    ["question", "Questions"],
+    ["meeting", "Meetings"],
+    ["concept", "Concepts"],
+];
+const NON_KNOWLEDGE = new Set(["source", "view", "proposal"]);
+/** Computed inverses exposed as backlinks (spec/schema.md §6). */
+const RELATION_INVERSES = {
+    about: "mentioned_in",
+    depends_on: "needed_by",
+    contradicts: "contradicts",
+    derived_from: "used_by",
+    related_to: "related_to",
+};
+const FIELD_INVERSES = [
+    ["projects", "project_of"],
+    ["area", "area_of"],
+    ["goal", "goal_of"],
+    ["client", "client_of"],
+    ["org", "member"],
+    ["attendees", "attended"],
+    ["decided_in", "decisions"],
+    ["raised_in", "questions"],
+];
+/** Build index.md and the agent-facing index from notes sorted by path. */
+export function buildIndex(allNotes) {
+    const byId = new Map();
+    const duplicates = [];
+    const notes = [];
+    for (const note of allNotes) {
+        const kept = byId.get(note.id);
+        if (kept !== undefined) {
+            duplicates.push({ id: note.id, path: note.path, kept: kept.path });
+            continue;
+        }
+        byId.set(note.id, note);
+        notes.push(note);
+    }
+    const counts = {};
+    for (const note of notes)
+        counts[note.type] = (counts[note.type] ?? 0) + 1;
+    return {
+        markdown: renderMarkdown(notes, byId),
+        entries: notes.map(toEntry),
+        backlinks: computeBacklinks(notes, byId),
+        counts,
+        duplicates,
+    };
+}
+function renderMarkdown(notes, byId) {
+    const lines = [INDEX_HEADER, "", "# Index"];
+    for (const [type, heading] of SECTIONS) {
+        const section = notes
+            .filter((note) => note.type === type)
+            .sort((a, b) => compareCodePoints(sortKey(a), sortKey(b)) || compareCodePoints(a.id, b.id));
+        if (section.length === 0)
+            continue;
+        lines.push("", `## ${heading}`, ...section.map((note) => renderLine(note, byId)));
+    }
+    return `${lines.join("\n")}\n`;
+}
+function sortKey(note) {
+    return text(note.attributes.title).normalize("NFC").toLowerCase();
+}
+function renderLine(note, byId) {
+    const a = note.attributes;
+    const title = oneLine(text(a.title)).replaceAll("\\", "\\\\").replaceAll("[", "\\[").replaceAll("]", "\\]");
+    const segments = [`- [${title}](${note.path}) — ${note.id}`];
+    for (const [label, value] of typeFields(note, byId)) {
+        if (value !== undefined && value !== "")
+            segments.push(`${label}: ${oneLine(value)}`);
+    }
+    if (typeof a.summary === "string")
+        segments.push(oneLine(a.summary));
+    const aliases = list(a.aliases).filter(isScalar).map((alias) => oneLine(String(alias)));
+    if (aliases.length > 0)
+        segments.push(`aliases: ${aliases.join(", ")}`);
+    if (a.lifecycle === "disputed" || a.lifecycle === "archived")
+        segments.push(String(a.lifecycle));
+    return segments.join(" · ");
+}
+/** Per-type index fields, rendered (references as titles). */
+function typeFields(note, byId) {
+    const a = note.attributes;
+    const ref = (value) => (typeof value === "string" ? titleOf(value, byId) : undefined);
+    const refs = (value) => {
+        const items = list(value).filter((item) => typeof item === "string").map((item) => titleOf(item, byId));
+        return items.length === 0 ? undefined : items.join(", ");
+    };
+    const scalar = (value) => (isScalar(value) ? String(value) : undefined);
+    const notionField = (key) => scalar(record(a.notion_fields)[key]);
+    const fact = (key) => scalar(record(a.facts)[key]);
+    switch (note.type) {
+        case "goal":
+            return [["area", ref(a.area)], ["status", notionField("status")], ["deadline", fact("deadline")]];
+        case "project":
+            return [["area", ref(a.area)], ["status", notionField("status")], ["client", ref(a.client)]];
+        case "person":
+            return [["org", ref(a.org)], ["role", fact("role")]];
+        case "org":
+            return [["relationship", notionField("relationship")]];
+        case "decision":
+            return [["date", scalar(a.date)], ["assessment", scalar(a.assessment)], ["project", refs(a.projects)]];
+        case "question":
+            return [["kind", scalar(a.kind)], ["status", notionField("status")]];
+        case "meeting":
+            return [["date", scalar(a.date)], ["project", refs(a.projects)]];
+        default:
+            return [];
+    }
+}
+function toEntry(note) {
+    const a = note.attributes;
+    const nullable = (value) => (value === undefined ? null : value);
+    return {
+        id: note.id,
+        type: note.type,
+        title: nullable(a.title),
+        path: note.path,
+        summary: nullable(a.summary),
+        lifecycle: NON_KNOWLEDGE.has(note.type) ? null : nullable(a.lifecycle),
+        aliases: list(a.aliases),
+        tags: list(a.tags),
+        area: nullable(a.area),
+        projects: list(a.projects),
+        updated: nullable(a.updated),
+        notion: nullable(a.notion),
+        fields: entryFields(note),
+    };
+}
+/** Raw (unrendered) per-type fields for the JSON index (spec/cli.md §5.8). */
+function entryFields(note) {
+    const a = note.attributes;
+    const notionFields = record(a.notion_fields);
+    const facts = record(a.facts);
+    const picks = {
+        goal: [["status", notionFields.status], ["deadline", facts.deadline]],
+        project: [["status", notionFields.status], ["client", a.client], ["goal", a.goal]],
+        person: [["org", a.org], ["role", facts.role]],
+        org: [["relationship", notionFields.relationship]],
+        decision: [["date", a.date], ["assessment", a.assessment]],
+        question: [["kind", a.kind], ["status", notionFields.status]],
+        meeting: [["date", a.date]],
+        source: [["source_key", a.source_key]],
+        view: [["view_kind", a.view_kind], ["project", a.project]],
+        proposal: [["kind", a.kind], ["status", a.status], ["target", a.target]],
+        memory: [["scope", a.scope]],
+    };
+    const fields = {};
+    for (const [key, value] of picks[note.type] ?? []) {
+        if (value !== undefined && value !== null)
+            fields[key] = value;
+    }
+    return fields;
+}
+function computeBacklinks(notes, byId) {
+    const collected = new Map();
+    const add = (target, type, source) => {
+        if (typeof target !== "string" || !byId.has(target))
+            return;
+        const bucket = collected.get(target) ?? new Map();
+        bucket.set(`${type}\u0000${source}`, { type, source });
+        collected.set(target, bucket);
+    };
+    for (const note of notes) {
+        const a = note.attributes;
+        for (const relation of list(a.relations)) {
+            const { type, target } = record(relation);
+            const inverse = typeof type === "string" ? RELATION_INVERSES[type] : undefined;
+            if (inverse !== undefined)
+                add(target, inverse, note.id);
+        }
+        for (const [field, inverse] of FIELD_INVERSES) {
+            const value = a[field];
+            for (const target of Array.isArray(value) ? value : [value])
+                add(target, inverse, note.id);
+        }
+    }
+    const result = {};
+    for (const target of [...collected.keys()].sort(compareCodePoints)) {
+        result[target] = [...collected.get(target).values()].sort((x, y) => compareCodePoints(x.type, y.type) || compareCodePoints(x.source, y.source));
+    }
+    return result;
+}
+function titleOf(value, byId) {
+    const id = String(value);
+    const title = byId.get(id)?.attributes.title;
+    return typeof title === "string" ? title : id;
+}
+/** Collapse every line break (and the spaces around it) into one space, then trim. */
+function oneLine(value) {
+    return value.replace(/[ \t]*(?:\r\n|\r|\n)[ \t]*/g, " ").trim();
+}
+function isScalar(value) {
+    return typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+}
+function text(value) {
+    return value === undefined || value === null ? "" : String(value);
+}
+function list(value) {
+    return Array.isArray(value) ? value : [];
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}

package/dist/lib/input.js

@@ -0,0 +1,45 @@
+import { readFile } from "node:fs/promises";
+import { BrainError } from "./errors.js";
+/** Read the JSON input of `--input <path|->` (spec/cli.md §3.2). */
+export async function readJsonInput(path, command) {
+    if (path === undefined)
+        throw new BrainError("USAGE", `brain ${command} needs --input <file|->`);
+    let text;
+    try {
+        text = path === "-" ? await readStdin() : await readFile(path, "utf8");
+    }
+    catch (error) {
+        throw new BrainError("INPUT_UNREADABLE", `Cannot read input ${path}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    try {
+        return JSON.parse(text.startsWith("\uFEFF") ? text.slice(1) : text);
+    }
+    catch (error) {
+        throw new BrainError("INPUT_UNREADABLE", `Input is not JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+/** Throw INPUT_INVALID listing every problem, when there are any. */
+export function assertNoProblems(problems) {
+    if (problems.length === 0)
+        return;
+    const count = problems.length === 1 ? "1 problem" : `${problems.length} problems`;
+    throw new BrainError("INPUT_INVALID", `${count} in input: ${problems[0].pointer} ${problems[0].message}`, problems);
+}
+/** Problems for keys of `value` outside `allowed` (unknown keys are errors, §3.2). */
+export function unknownKeys(value, allowed, pointer) {
+    return Object.keys(value)
+        .filter((key) => !allowed.includes(key))
+        .map((key) => ({ pointer: `${pointer}/${escapePointer(key)}`, message: "unknown key" }));
+}
+export function escapePointer(key) {
+    return key.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(Buffer.from(chunk));
+    return Buffer.concat(chunks).toString("utf8");
+}

package/dist/lib/lint.js

@@ -0,0 +1,336 @@
+import { createHash } from "node:crypto";
+import { readdirSync } from "node:fs";
+import { posix } from "node:path";
+import { buildIndex } from "./index-builder.js";
+import { compareCodePoints } from "./notes.js";
+import { describeErrors, loadSchemas } from "./schemas.js";
+import { deriveView, generatedBlockRange } from "./views.js";
+const ID = /^(area|gol|prj|per|org|mtg|dec|que|con|src|mem|prp|vw)-[0-9abcdefghjkmnpqrstvwxyz]{8}$/;
+/** Frontmatter keys whose values are references (spec/schema.md §3–§11); `relations` and `timeline` are handled by shape. */
+const REFERENCE_KEYS = new Set([
+    "area", "goal", "client", "org", "projects", "people", "attendees", "decided_in", "raised_in", "deciders",
+    "source", "sources", "decisions", "questions", "answer", "target", "supersedes", "merge_into", "project",
+    "generated_from", "facts",
+]);
+/** Where each type must live (spec/schema.md §2). */
+const FOLDERS = {
+    area: /^areas\/[^/]+\.md$/,
+    goal: /^(archive\/)?goals\/[^/]+\.md$/,
+    project: /^(archive\/)?projects\/[^/]+\/project\.md$/,
+    view: /^(archive\/)?projects\/[^/]+\/[^/]+\.md$/,
+    person: /^knowledge\/people\/[^/]+\.md$/,
+    org: /^knowledge\/orgs\/[^/]+\.md$/,
+    meeting: /^knowledge\/meetings\/\d{4}-\d{2}-\d{2}-[^/]+\.md$/,
+    decision: /^knowledge\/decisions\/\d{4}-\d{2}-\d{2}-[^/]+\.md$/,
+    question: /^knowledge\/questions\/[^/]+\.md$/,
+    concept: /^knowledge\/concepts\/[^/]+\.md$/,
+    source: /^sources\/notion\/\d{4}-\d{2}-\d{2}-[^/]+\.md$/,
+    memory: /^memories\/\d{4}\/\d{2}\/\d{4}-\d{2}-\d{2}-[^/]+\.md$/,
+    proposal: /^_proposals\/[^/]+\.md$/,
+};
+const KNOWLEDGE = new Set(["area", "goal", "project", "person", "org", "meeting", "decision", "question", "concept", "memory"]);
+const UNDATED = new Set(["area", "goal", "project", "person", "org", "question", "concept"]);
+const FRESHNESS_WORDS = /\b(currently|now|at the moment|this week|latest|recently|soon)\b/i;
+const HAS_DATE = /\b\d{4}-\d{2}(-\d{2})?\b/;
+const MEMORY_REACH = { general: null, area: "areas", project: "projects", stack: "stacks" };
+/** Run every lint rule of spec/cli.md §5.10 over the brain. Issues are sorted by path, line, rule, message. */
+export function lintBrain(input) {
+    const schemas = loadSchemas();
+    const issues = [];
+    const add = (severity, rule, path, line, id, message) => issues.push({ severity, rule, path, line, id, message });
+    for (const problem of input.problems) {
+        if (problem.code === "NOT_A_NOTE")
+            add("error", "not-a-note", problem.path, 1, null, problem.message);
+        if (problem.code === "UNPARSEABLE" || problem.code === "UNREADABLE")
+            add("error", "unparseable", problem.path, 1, null, problem.message);
+    }
+    if (!schemas.brain(input.brainConfig)) {
+        add("error", "brain-config", "brain.json", 1, null, describeErrors(schemas.brain.errors).join("; "));
+    }
+    const byId = new Map();
+    const pathsById = new Map();
+    for (const note of input.notes) {
+        if (!byId.has(note.id))
+            byId.set(note.id, note);
+        pathsById.set(note.id, [...(pathsById.get(note.id) ?? []), note.path]);
+    }
+    for (const note of input.notes) {
+        const others = pathsById.get(note.id).filter((path) => path !== note.path);
+        if (others.length > 0)
+            add("error", "id-duplicate", note.path, lineOfKey(note, "id"), note.id, `${note.id} is also used by ${others.join(", ")}`);
+    }
+    const onDisk = caseSensitiveExists(input.root);
+    const exists = (path) => input.pendingPaths?.has(path) === true || onDisk(path);
+    for (const note of input.notes) {
+        const a = note.attributes;
+        const err = (rule, line, message) => add("error", rule, note.path, line, note.id, message);
+        const warn = (rule, line, message) => add("warning", rule, note.path, line, note.id, message);
+        // Shape
+        const validate = note.type === "proposal" ? schemas.proposal : schemas.note;
+        if (!validate(a)) {
+            const firstKey = validate.errors?.find((error) => error.instancePath !== "")?.instancePath.split("/")[1];
+            err("schema", firstKey === undefined ? 1 : lineOfKey(note, firstKey), describeErrors(validate.errors).join("; "));
+        }
+        if (!ID.test(note.id))
+            err("id-format", lineOfKey(note, "id"), `"${note.id}" is not <prefix>-<8 chars> with a schema prefix`);
+        const folder = FOLDERS[note.type];
+        if (folder !== undefined && !folder.test(note.path))
+            err("wrong-folder", 1, `a ${note.type} must live in its folder (spec/schema.md §2)`);
+        const known = schemas.knownKeys(note.type);
+        if (known !== undefined) {
+            for (const key of Object.keys(a))
+                if (!known.has(key))
+                    warn("unknown-key", lineOfKey(note, key), `${note.type} does not declare "${key}"`);
+        }
+        // References and links
+        const references = Object.entries(a).filter(([key]) => REFERENCE_KEYS.has(key));
+        for (const relation of list(a.relations))
+            references.push(["relations", record(relation).target]);
+        for (const entry of list(a.timeline))
+            references.push(["timeline", record(entry).source]);
+        for (const [key, value] of references) {
+            for (const ref of collectIds(value)) {
+                if (!byId.has(ref))
+                    err("missing-ref", lineOfKey(note, key), `${key} references ${ref}, which does not exist`);
+            }
+        }
+        const bodyStart = bodyLineOffset(note);
+        for (const [index, raw] of proseLines(note.body)) {
+            const line = bodyStart + index;
+            if (raw.includes("[["))
+                err("wikilink", line, "use a relative Markdown link, not [[wikilinks]] (0002)");
+            for (const match of raw.matchAll(/\^\[([^\]]*)\]/g)) {
+                if (match[1] !== "inferred" && match[1] !== "ambiguous")
+                    err("unknown-marker", line, `^[${match[1]}] is not a provenance marker (0004)`);
+            }
+            for (const target of linkTargets(raw)) {
+                if (/^[a-z][a-z0-9+.-]*:/i.test(target) || target.startsWith("#"))
+                    continue;
+                const resolved = posix.normalize(posix.join(posix.dirname(note.path), decodePath(target.split(/[?#]/)[0])));
+                if (resolved.startsWith("../") || !exists(resolved))
+                    err("broken-link", line, `link target ${target} does not exist`);
+            }
+            const prose = raw.replace(/\]\([^)]*\)/g, "]");
+            if (UNDATED.has(note.type) && FRESHNESS_WORDS.test(prose) && !HAS_DATE.test(prose)) {
+                warn("freshness", line, `"${prose.match(FRESHNESS_WORDS)[0]}" in an undated note without a date; write (as of YYYY-MM-DD) (0011)`);
+            }
+        }
+        // Type rules
+        if (note.type === "source") {
+            const hash = `sha256:${createHash("sha256").update(note.body, "utf8").digest("hex")}`;
+            if (a.content_hash !== hash)
+                err("source-hash", lineOfKey(note, "content_hash"), "the body no longer matches content_hash; sources are immutable");
+        }
+        for (const source of list(a.sources)) {
+            if (typeof source === "string" && byId.get(source)?.type === "view")
+                err("view-cited", lineOfKey(note, "sources"), `${source} is a derived view and can't be evidence`);
+        }
+        if (note.type === "view" && (a.view_kind === "brief" || a.view_kind === "decision_log")) {
+            const project = byId.get(String(a.project));
+            const range = generatedBlockRange(note.body);
+            if (project?.type === "project" && range !== undefined) {
+                const derived = deriveView(project, a.view_kind, input.notes);
+                const generatedFrom = Array.isArray(a.generated_from) ? a.generated_from : [];
+                if (note.body.slice(range.start, range.end) !== derived.generatedBlock || !sameStringList(generatedFrom, derived.generatedFrom)) {
+                    warn("view-stale", 1, "generated block is out of date; run brain views");
+                }
+            }
+        }
+        const facts = record(a.facts);
+        for (const [key, value] of Object.entries(facts)) {
+            const entries = list(a.timeline).map(record).filter((entry) => entry.field === key);
+            const accepted = entries.some((entry) => entry.assessment === "accepted" && entry.value === value);
+            // Unless contested (schema §5): when the latest entry is contested, facts may keep the earlier value.
+            const contested = entries.at(-1)?.assessment === "contested" && entries.some((entry) => entry.value === value);
+            if (!accepted && !contested)
+                err("fact-timeline", lineOfKey(note, "facts"), `facts.${key} has no accepted timeline entry with value ${JSON.stringify(value)}`);
+        }
+        for (const relation of list(a.relations)) {
+            const { type, target } = record(relation);
+            const inverse = type === "supersedes" ? "superseded_by" : type === "superseded_by" ? "supersedes" : undefined;
+            if (inverse === undefined || typeof target !== "string" || !byId.has(target))
+                continue;
+            const paired = list(byId.get(target).attributes.relations).some((other) => record(other).type === inverse && record(other).target === note.id);
+            if (!paired)
+                err("supersession-pair", lineOfKey(note, "relations"), `${type} ${target}, but ${target} has no ${inverse} ${note.id}`);
+        }
+        for (const [field, list_, label] of [["decided_in", "decisions", "decision"], ["raised_in", "questions", "question"]]) {
+            const meeting = typeof a[field] === "string" ? byId.get(a[field]) : undefined;
+            if (meeting !== undefined && !list(meeting.attributes[list_]).includes(note.id)) {
+                err("meeting-backref", lineOfKey(note, field), `${field} ${meeting.id}, but that meeting's ${list_} does not list this ${label}`);
+            }
+        }
+        if (note.type === "meeting") {
+            for (const [list_, field] of [["decisions", "decided_in"], ["questions", "raised_in"]]) {
+                for (const ref of list(a[list_])) {
+                    const other = typeof ref === "string" ? byId.get(ref) : undefined;
+                    if (other !== undefined && other.attributes[field] !== note.id) {
+                        err("meeting-backref", lineOfKey(note, list_), `${list_} lists ${ref}, whose ${field} is not this meeting`);
+                    }
+                }
+            }
+        }
+        if (note.type === "decision") {
+            if (a.assessment === "superseded" && a.valid_until === undefined)
+                err("superseded-valid-until", lineOfKey(note, "assessment"), "a superseded decision needs valid_until");
+            if (a.assessment === "superseded" && !list(a.relations).some((relation) => record(relation).type === "superseded_by")) {
+                err("superseded-unlinked", lineOfKey(note, "assessment"), "a superseded decision needs a superseded_by relation (0005)");
+            }
+            if (list(a.sources).length === 0)
+                err("decision-sources", lineOfKey(note, "sources"), "a decision needs sources (0005)");
+        }
+        if (note.type === "memory") {
+            const reach = MEMORY_REACH[String(a.scope)];
+            const present = ["areas", "projects", "stacks"].filter((key) => a[key] !== undefined);
+            if (reach === undefined) {
+                err("memory-scope", lineOfKey(note, "scope"), `scope ${String(a.scope)} is not general, area, project or stack (0009)`);
+            }
+            else if (reach === null ? present.length > 0 : present.length !== 1 || present[0] !== reach || list(a[reach]).length === 0) {
+                err("memory-scope", lineOfKey(note, "scope"), `scope ${String(a.scope)} must have ${reach === null ? "no reach lists" : `only a non-empty ${reach}`} (0009)`);
+            }
+        }
+        if (note.type === "proposal") {
+            const problem = proposalStatusProblem(a);
+            if (problem !== null)
+                err("proposal-status", lineOfKey(note, "status"), problem);
+        }
+        // Quality warnings
+        if (KNOWLEDGE.has(note.type)) {
+            if (typeof a.summary === "string" && a.summary.length > 200)
+                warn("summary-length", lineOfKey(note, "summary"), `summary is ${a.summary.length} characters; aim for 200`);
+            if (!["area", "goal", "project", "decision"].includes(note.type) && list(a.sources).length === 0) {
+                warn("no-sources", 1, "knowledge without sources can't be traced");
+            }
+        }
+    }
+    if (input.indexMarkdown !== undefined && input.indexMarkdown !== buildIndex(input.notes).markdown) {
+        add("warning", "index-stale", "index.md", 1, null, "index.md is out of date; run brain index");
+    }
+    return issues.sort((x, y) => compareCodePoints(x.path, y.path) || x.line - y.line || compareCodePoints(x.rule, y.rule) || compareCodePoints(x.message, y.message));
+}
+/** Status/decision agreement (spec/schema.md §11.1). */
+function proposalStatusProblem(a) {
+    const status = a.status;
+    const action = record(a.decision).action;
+    const stale = a.closed_reason === "stale";
+    if (a.closed_reason !== undefined && status !== "closed")
+        return "closed_reason is only allowed on a closed proposal";
+    const expected = {
+        pending: [undefined],
+        approved: ["approve"],
+        edited: ["edit"],
+        rejected: ["reject"],
+        applied: ["approve", "edit"],
+        closed: stale ? ["approve", "edit"] : ["reject"],
+    };
+    const allowed = expected[String(status)];
+    if (allowed === undefined)
+        return null; // the schema reports unknown statuses
+    if (!allowed.includes(action)) {
+        return `status ${String(status)}${stale ? " (stale)" : ""} needs decision ${allowed.map((value) => value ?? "absent").join(" or ")}, found ${action === undefined ? "none" : String(action)}`;
+    }
+    return null;
+}
+function collectIds(value, out = []) {
+    if (typeof value === "string") {
+        if (ID.test(value))
+            out.push(value);
+    }
+    else if (Array.isArray(value)) {
+        for (const item of value)
+            collectIds(item, out);
+    }
+    else if (value !== null && typeof value === "object") {
+        for (const item of Object.values(value))
+            collectIds(item, out);
+    }
+    return out;
+}
+/** Body lines outside fenced code blocks, with inline code removed: [index, text]. */
+function proseLines(body) {
+    const out = [];
+    let fence = null;
+    body.split("\n").forEach((line, index) => {
+        const marker = /^\s*(```|~~~)/.exec(line)?.[1];
+        if (marker !== undefined) {
+            fence = fence === null ? marker : fence === marker ? null : fence;
+            return;
+        }
+        if (fence === null)
+            out.push([index, line.replace(/`[^`]*`/g, "")]);
+    });
+    return out;
+}
+/** Targets of inline links (`[x](t)`, `[x](t "title")`, `[x](<t>)`) and reference definitions (`[x]: t`). */
+function linkTargets(line) {
+    const targets = [];
+    for (const match of line.matchAll(/\]\(\s*(?:<([^>]*)>|([^)\s]+))(?:\s+(?:"[^"]*"|'[^']*'|\([^)]*\)))?\s*\)/g)) {
+        targets.push(match[1] ?? match[2]);
+    }
+    const definition = /^\s{0,3}\[[^\]]+\]:\s*(?:<([^>]*)>|(\S+))/.exec(line);
+    if (definition !== null)
+        targets.push(definition[1] ?? definition[2]);
+    return targets;
+}
+/** Percent-decode each path segment; a segment that is not valid encoding is kept as written. */
+function decodePath(path) {
+    return path.split("/").map((segment) => {
+        try {
+            return decodeURIComponent(segment);
+        }
+        catch {
+            return segment;
+        }
+    }).join("/");
+}
+/** File existence with exact case on every segment, so macOS and Linux agree. */
+function caseSensitiveExists(root) {
+    const listings = new Map();
+    const entries = (dir) => {
+        if (!listings.has(dir)) {
+            try {
+                listings.set(dir, new Set(readdirSync(`${root}/${dir}`)));
+            }
+            catch {
+                listings.set(dir, null);
+            }
+        }
+        return listings.get(dir);
+    };
+    return (relative) => {
+        const parts = relative.split("/").filter((part) => part !== "" && part !== ".");
+        let dir = "";
+        for (const part of parts) {
+            if (!entries(dir === "" ? "." : dir)?.has(part))
+                return false;
+            dir = dir === "" ? part : `${dir}/${part}`;
+        }
+        return parts.length > 0;
+    };
+}
+/** 1-based line of a top-level frontmatter key, or 1. */
+function lineOfKey(note, key) {
+    const lines = note.raw.split("\n");
+    for (let index = 1; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line === "---" || line === "---\r")
+            break;
+        if (line.startsWith(`${key}:`))
+            return index + 1;
+    }
+    return 1;
+}
+/** 1-based line number of the first body line. */
+function bodyLineOffset(note) {
+    const head = note.raw.slice(0, note.raw.length - note.body.length);
+    return head.split("\n").length;
+}
+function list(value) {
+    return Array.isArray(value) ? value : [];
+}
+function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value) ? value : {};
+}
+function sameStringList(left, right) {
+    return left.length === right.length && left.every((value, index) => value === right[index]);
+}

package/dist/lib/log.js

@@ -0,0 +1,44 @@
+import { appendFile, stat, writeFile } from "node:fs/promises";
+import { ensureDirectory, resolveWritableTarget } from "./fs-safe.js";
+import { formatTimestamp } from "./time.js";
+export const LOG_HEADER = "<!-- GENERATED by brain. Append-only. -->";
+/** Format one log line (spec/cli.md §3.9). Always a single line: CR and LF are escaped. */
+export function formatLogLine(now, entry) {
+    const pairs = (entry.pairs ?? []).map(([key, value]) => ` ${key}=${quoteIfNeeded(String(value))}`).join("");
+    return `- ${formatTimestamp(now)} ${entry.op} ${entry.id} ${quote(entry.title)}${pairs}`;
+}
+/**
+ * Append lines to `log/<YYYY-MM>.md` (month of `now`). The file is created exclusively with
+ * its header, then lines are appended, so concurrent writers never overwrite each other and an
+ * unreadable log is an error, never a reason to start over. Returns the relative path.
+ */
+export async function appendLog(root, now, entries) {
+    const path = `log/${formatTimestamp(now).slice(0, 7)}.md`;
+    await ensureDirectory(root, "log");
+    const { target } = await resolveWritableTarget(root, path);
+    try {
+        await writeFile(target, `${LOG_HEADER}\n\n`, { flag: "wx" });
+    }
+    catch (error) {
+        if (!isNodeError(error) || error.code !== "EEXIST")
+            throw error;
+        if ((await stat(target)).size === 0)
+            await appendFile(target, `${LOG_HEADER}\n\n`);
+    }
+    await appendFile(target, entries.map((entry) => `${formatLogLine(now, entry)}\n`).join(""));
+    return path;
+}
+function quote(value) {
+    const escaped = value
+        .replaceAll("\\", "\\\\")
+        .replaceAll('"', '\\"')
+        .replaceAll("\r", "\\r")
+        .replaceAll("\n", "\\n");
+    return `"${escaped}"`;
+}
+function quoteIfNeeded(value) {
+    return /[\s"\\]/.test(value) || value === "" ? quote(value) : value;
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}