ultimate-brain 0.4.1 → 0.6.0

package/dist/lib/diff.js

@@ -0,0 +1,31 @@
+/**
+ * The changed lines of `after` against `before`, as `- ` and `+ ` lines with no context, by the
+ * longest common subsequence walk of spec/cli.md §5.19 (a tie removes first).
+ */
+export function lineDiff(before, after) {
+    const o = before.replace(/\r\n/g, "\n").split("\n");
+    const n = after.replace(/\r\n/g, "\n").split("\n");
+    const L = Array.from({ length: o.length + 1 }, () => new Array(n.length + 1).fill(0));
+    for (let i = o.length - 1; i >= 0; i -= 1) {
+        for (let j = n.length - 1; j >= 0; j -= 1)
+            L[i][j] = o[i] === n[j] ? L[i + 1][j + 1] + 1 : Math.max(L[i + 1][j], L[i][j + 1]);
+    }
+    const out = [];
+    let i = 0;
+    let j = 0;
+    while (i < o.length && j < n.length) {
+        if (o[i] === n[j]) {
+            i += 1;
+            j += 1;
+        }
+        else if (L[i + 1][j] >= L[i][j + 1])
+            out.push(`- ${o[i++]}`);
+        else
+            out.push(`+ ${n[j++]}`);
+    }
+    while (i < o.length)
+        out.push(`- ${o[i++]}`);
+    while (j < n.length)
+        out.push(`+ ${n[j++]}`);
+    return out;
+}

package/dist/lib/errors.js

@@ -1,6 +1,7 @@
 /** Error codes and exit codes from spec/cli.md §3.4–3.5. */
 export const EXIT_CODES = {
     USAGE: 2,
+    RETIRED: 2,
     BRAIN_NOT_CONFIGURED: 3,
     BRAIN_NOT_FOUND: 3,
     BRAIN_IS_PRODUCT_REPO: 3,
@@ -15,6 +16,7 @@ export const EXIT_CODES = {
     REPO_NOT_FOUND: 4,
     REPO_IS_BRAIN: 4,
     REPO_COMMIT_UNKNOWN: 4,
+    MODULE_OFF: 4,
     TARGET_NOT_EMPTY: 5,
     ALREADY_A_BRAIN: 5,
     OUTSIDE_ROOT: 5,

package/dist/lib/ids.js

@@ -10,6 +10,7 @@ export const ID_PREFIXES = [
     "dec",
     "que",
     "con",
+    "ref",
     "src",
     "mem",
     "prp",
@@ -44,6 +45,7 @@ export const TYPE_PREFIX = {
     decision: "dec",
     question: "que",
     concept: "con",
+    reference: "ref",
     source: "src",
     memory: "mem",
     proposal: "prp",

package/dist/lib/index-builder.js

@@ -11,8 +11,10 @@ const SECTIONS = [
     ["question", "Questions"],
     ["meeting", "Meetings"],
     ["concept", "Concepts"],
+    ["reference", "Documents"],
 ];
 const NON_KNOWLEDGE = new Set(["source", "view", "proposal"]);
+const TYPES = [...SECTIONS.map(([type]) => type), "source", "view", "proposal", "memory"];
 /** Computed inverses exposed as backlinks (spec/schema.md §6). */
 const RELATION_INVERSES = {
     about: "mentioned_in",
@@ -45,7 +47,8 @@ export function buildIndex(allNotes) {
         byId.set(note.id, note);
         notes.push(note);
     }
-    const counts = {};
+    // Every type has a count, zero included (spec/cli.md §5.8).
+    const counts = Object.fromEntries(TYPES.map((type) => [type, 0]));
     for (const note of notes)
         counts[note.type] = (counts[note.type] ?? 0) + 1;
     return {
@@ -114,6 +117,8 @@ function typeFields(note, byId) {
             return [["kind", scalar(a.kind)], ["status", notionField("status")]];
         case "meeting":
             return [["date", scalar(a.date)], ["project", refs(a.projects)]];
+        case "reference":
+            return [["origin", scalar(a.origin)], ["area", ref(a.area)], ["project", refs(a.projects)]];
         default:
             return [];
     }

package/dist/lib/lint.js

@@ -8,12 +8,12 @@ import { rangesProblem, splitParts } from "./parts.js";
 import { sourceFolder } from "./paths.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}$/;
+const ID = /^(area|gol|prj|per|org|mtg|dec|que|con|ref|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", "notes", "answer_note", "links", "attached_to",
+    "generated_from", "facts", "notes", "answer_note", "links", "attached_to", "changes", "replaces", "deferred_from", "promoted_from",
 ]);
 /** Where each kind of view must live (spec/schema.md §2, 0041, 0043). */
 const VIEW_FOLDERS = {
@@ -32,12 +32,13 @@ const FOLDERS = {
     decision: /^knowledge\/decisions\/\d{4}-\d{2}-\d{2}-[^/]+\.md$/,
     question: /^knowledge\/questions\/[^/]+\.md$/,
     concept: /^knowledge\/concepts\/[^/]+\.md$/,
+    reference: /^knowledge\/references\/[^/]+\.md$/,
     source: /^sources\/(notion|files|text)\/\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 KNOWLEDGE = new Set(["area", "goal", "project", "person", "org", "meeting", "decision", "question", "concept", "reference", "memory"]);
+const UNDATED = new Set(["area", "goal", "project", "person", "org", "question", "concept", "reference"]);
 const FRESHNESS_WORDS = /\b(currently|now|at the moment|this week|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" };
@@ -75,6 +76,12 @@ export function lintBrain(input) {
         for (const id of new Set(list(note.attributes.notes).map(String)))
             reviewedBy.set(id, [...(reviewedBy.get(id) ?? []), note.id]);
     }
+    // Every source replacing each source id (rule source-replaces, 0045).
+    const replacedBy = new Map();
+    for (const note of input.notes) {
+        if (note.type === "source" && typeof note.attributes.replaces === "string")
+            replacedBy.set(note.attributes.replaces, [...(replacedBy.get(note.attributes.replaces) ?? []), note.id]);
+    }
     const onDisk = caseSensitiveExists(input.root);
     const exists = (path) => input.pendingPaths?.has(path) === true || onDisk(path);
     for (const note of input.notes) {
@@ -218,11 +225,35 @@ export function lintBrain(input) {
                 const listed = byId.get(String(id));
                 if (listed !== undefined && !KNOWLEDGE.has(listed.type))
                     err("review-notes", lineOfKey(note, "notes"), `${String(id)} is a ${listed.type}, not a knowledge note`);
-                const others = (reviewedBy.get(String(id)) ?? []).filter((other) => other !== note.id);
+                // A deferred row lists again the notes the row it came from excluded (0045).
+                const others = (reviewedBy.get(String(id)) ?? []).filter((other) => other !== note.id && !deferredPair(note, byId.get(other), String(id)));
                 if (others.length > 0)
                     err("review-notes", lineOfKey(note, "notes"), `${String(id)} is also listed by ${others.join(", ")}`);
             }
         }
+        if (note.type === "proposal") {
+            const bodies = [...(a.kind === "update_body" ? [a.target] : []), ...list(a.changes).map(record).filter((change) => change.kind === "update_body").map((change) => change.target)];
+            for (const target of bodies) {
+                const reference = typeof target === "string" ? byId.get(target) : undefined;
+                if (reference !== undefined && reference.type !== "reference")
+                    err("update-body", lineOfKey(note, a.kind === "update_body" ? "target" : "changes"), `update_body targets ${reference.id}, a ${reference.type}; only a reference has its body replaced (0045)`);
+                if (reference?.type === "reference" && reference.attributes.origin === "promoted")
+                    err("update-body", lineOfKey(note, a.kind === "update_body" ? "target" : "changes"), `update_body targets ${reference.id}, a promoted Document, whose body is yours (0049)`);
+            }
+        }
+        if (note.type === "reference" && typeof a.promoted_from === "string") {
+            const from = byId.get(a.promoted_from);
+            if (from !== undefined && from.type !== "decision" && from.type !== "concept")
+                err("promoted-from", lineOfKey(note, "promoted_from"), `promoted_from names ${a.promoted_from}, a ${from.type}, not a decision or concept (0049)`);
+        }
+        if (note.type === "source" && typeof a.replaces === "string") {
+            const replaced = byId.get(a.replaces);
+            if (replaced !== undefined && replaced.type !== "source")
+                err("source-replaces", lineOfKey(note, "replaces"), `replaces ${a.replaces}, a ${replaced.type}, not a source`);
+            const others = (replacedBy.get(a.replaces) ?? []).filter((other) => other !== note.id);
+            if (others.length > 0)
+                err("source-replaces", lineOfKey(note, "replaces"), `${a.replaces} is also replaced by ${others.join(", ")}`);
+        }
         if (note.type === "source" && Array.isArray(a.notion_parts)) {
             const problem = rangesProblem(a.notion_parts, splitParts(note.body).parts.length);
             if (problem !== null)
@@ -253,10 +284,10 @@ function proposalStatusProblem(a) {
     const expected = {
         pending: [undefined],
         approved: ["approve"],
-        edited: ["edit"],
+        edited: ["fix", "edit"],
         rejected: ["reject"],
-        applied: ["approve", "edit"],
-        closed: stale ? ["approve", "edit"] : ["reject"],
+        applied: ["approve", "fix", "edit"],
+        closed: stale ? ["approve", "fix", "edit"] : ["reject"],
     };
     const allowed = expected[String(status)];
     if (allowed === undefined)
@@ -266,6 +297,13 @@ function proposalStatusProblem(a) {
     }
     return null;
 }
+/** A deferred row and the row whose excluded note it took over (spec/schema.md §15, 0045). */
+function deferredPair(note, other, id) {
+    if (other === undefined)
+        return false;
+    const excluded = (proposal) => list(record(proposal.attributes.decision).exclude).some((entry) => record(entry).note === id);
+    return (note.attributes.deferred_from === other.id && excluded(other)) || (other.attributes.deferred_from === note.id && excluded(note));
+}
 function collectIds(value, out = []) {
     if (typeof value === "string") {
         if (ID.test(value))

package/dist/lib/modules.js

@@ -0,0 +1,91 @@
+import { isRecord } from "./input.js";
+/** The optional modules of spec/schema.md §12 (decision 0048), in contract order. */
+export const MODULES = ["knowledge", "orgs", "documents", "reports", "tasks", "planning"];
+export const MODULE_DEFAULTS = {
+    knowledge: true,
+    orgs: true,
+    documents: false,
+    reports: false,
+    tasks: false,
+    planning: false,
+};
+/** The `notion.databases` keys each module owns. Reports and Tasks own none (Tasks uses `notion.tasks`). */
+export const MODULE_DATABASES = {
+    knowledge: ["decisions", "questions", "concepts"],
+    orgs: ["orgs"],
+    documents: ["documents"],
+    reports: [],
+    tasks: [],
+    planning: ["goals", "key_results"],
+};
+const MODULE_FOR_TYPE = {
+    decision: "knowledge",
+    question: "knowledge",
+    concept: "knowledge",
+    org: "orgs",
+    reference: "documents",
+    goal: "planning",
+};
+export function isModuleName(value) {
+    return MODULES.includes(value);
+}
+/** Which modules are on: every module when the block is absent, else each absent key at its default. */
+export function modulesOf(config) {
+    const block = config.modules;
+    if (!isRecord(block))
+        return Object.fromEntries(MODULES.map((name) => [name, true]));
+    return Object.fromEntries(MODULES.map((name) => [name, typeof block[name] === "boolean" ? block[name] : MODULE_DEFAULTS[name]]));
+}
+/** The module a note type belongs to, or null for a core type (or one that is never published). */
+export function moduleForType(type) {
+    return MODULE_FOR_TYPE[type] ?? null;
+}
+/** The module a `notion.databases` key belongs to, or null for a core database. */
+export function moduleForDatabase(key) {
+    const name = MODULES.find((module) => MODULE_DATABASES[module].includes(key));
+    return name ?? null;
+}
+/** Whether rows of this note type are published and taken in. */
+export function typeIsOn(config, type) {
+    const module = moduleForType(type);
+    return module === null || modulesOf(config)[module];
+}
+/**
+ * Read a `notion.databases` id, accepting the keys renamed by `brain upgrade`: `inbox` was
+ * `capture_inbox` and `documents` was `references` (schema §12, 0049). Empty string when unset.
+ */
+export function databaseId(config, key) {
+    const notion = config.notion;
+    const databases = isRecord(notion) && isRecord(notion.databases) ? notion.databases : {};
+    const legacy = key === "inbox" ? "capture_inbox" : key === "documents" ? "references" : null;
+    const value = databases[key] === undefined && legacy !== null ? databases[legacy] : databases[key];
+    return typeof value === "string" ? value : "";
+}
+/** The Notion pieces a module still lacks: its empty database ids, and `tasks` when the tasks database is unset. */
+export function missingFor(config, module) {
+    const missing = MODULE_DATABASES[module].filter((key) => databaseId(config, key) === "");
+    if (module === "tasks") {
+        const notion = config.notion;
+        const tasks = isRecord(notion) && isRecord(notion.tasks) ? notion.tasks : {};
+        if (typeof tasks.database !== "string" || tasks.database === "")
+            missing.push("tasks");
+    }
+    return missing;
+}
+/**
+ * A copy of `config` with `block` as its `modules` block: in place when it has one, else after
+ * `settings`, or after `budgets` when there is no `settings`, or at the end (spec/cli.md §5.15 step 5).
+ */
+export function withModules(config, block) {
+    const anchor = "modules" in config ? "modules" : "settings" in config ? "settings" : "budgets" in config ? "budgets" : null;
+    const next = {};
+    for (const [key, value] of Object.entries(config)) {
+        if (key !== "modules")
+            next[key] = value;
+        if (key === anchor)
+            next.modules = block;
+    }
+    if (anchor === null)
+        next.modules = block;
+    return next;
+}

package/dist/lib/note-new.js

@@ -3,11 +3,10 @@ import { BrainError } from "./errors.js";
 import { serializeNewFile } from "./frontmatter.js";
 import { generateId, TYPE_PREFIX } from "./ids.js";
 import { assertNoProblems, escapePointer, isRecord, unknownKeys } from "./input.js";
-import { rangesProblem, splitParts } from "./parts.js";
 import { newNotePath } from "./paths.js";
 import { formatDate, formatTimestamp } from "./time.js";
 const ITEM_KEYS = ["type", "id", "title", "file_date", "frontmatter", "body"];
-const KNOWLEDGE_TYPES = new Set(["area", "goal", "project", "person", "org", "meeting", "decision", "question", "concept", "memory"]);
+const KNOWLEDGE_TYPES = new Set(["area", "goal", "project", "person", "org", "meeting", "decision", "question", "concept", "reference", "memory"]);
 const NEW_NOTE_TYPES = new Set([...KNOWLEDGE_TYPES, "source"]);
 const FORBIDDEN_KEYS = ["id", "type", "title", "created", "updated", "lifecycle"];
 const DATE = /^\d{4}-\d{2}-\d{2}$/;
@@ -52,16 +51,16 @@ export function checkNoteInput(value, pointer, withId = true) {
                 at(`frontmatter/${escapePointer(key)}`, "is set by the CLI");
         }
         if (value.type === "source") {
-            // Order, overlap and the part count are not in the JSON Schema (spec/cli.md §5.5).
-            if (value.frontmatter.notion_text_requested !== undefined)
-                at("frontmatter/notion_text_requested", "is set by brain source full-text");
-            const parts = value.frontmatter.notion_parts;
-            if (Array.isArray(parts) && typeof value.body === "string") {
-                const problem = rangesProblem(parts, splitParts(value.body).parts.length);
-                if (problem !== null)
-                    at("frontmatter/notion_parts", problem);
+            // Read on existing sources, never written again (spec/cli.md §5.5, 0049).
+            if (value.frontmatter.keep !== undefined)
+                at("frontmatter/keep", "is the name before 0.6.0: use only_keep");
+            for (const key of ["notion_text", "notion_parts", "notion_text_requested"]) {
+                if (value.frontmatter[key] !== undefined)
+                    at(`frontmatter/${key}`, "is retired in 0.6.0: Keep as document gives the whole text");
             }
         }
+        if (value.type === "reference" && value.frontmatter.origin === undefined)
+            at("frontmatter/origin", "is required on a new Document: whole, part or promoted");
     }
     return problems;
 }
@@ -100,6 +99,24 @@ export function stageNotes(workspace, items, pointerOf, options) {
         if (problem !== undefined)
             parents.push({ pointer: `${pointerOf(index)}/frontmatter/attached_to`, message: problem });
     });
+    // replaces names a source, existing or earlier in the batch, that no other source replaces (spec/cli.md §5.5, 0045).
+    const replaced = new Map();
+    for (const note of workspace.notes)
+        if (note.type === "source" && typeof note.attributes.replaces === "string")
+            replaced.set(note.attributes.replaces, note.id);
+    items.forEach((item, index) => {
+        const earlier = item.type === "source" ? item.frontmatter.replaces : undefined;
+        if (earlier === undefined)
+            return;
+        const type = workspace.get(String(earlier))?.type ?? items.slice(0, index).find((candidate) => candidate.id === earlier)?.type;
+        const problem = type === undefined ? `${String(earlier)} is not an existing source or one earlier in the batch`
+            : type !== "source" ? `${String(earlier)} is a ${type}, not a source`
+                : replaced.has(String(earlier)) ? `${String(earlier)} is already replaced by ${replaced.get(String(earlier))}`
+                    : undefined;
+        if (problem !== undefined)
+            parents.push({ pointer: `${pointerOf(index)}/frontmatter/replaces`, message: problem });
+        replaced.set(String(earlier), item.id ?? `/notes/${index}`);
+    });
     // A repo file names a linked repo of brain.json (0042).
     const repoNames = new Set(Array.isArray(workspace.config.repos) ? workspace.config.repos.filter(isRecord).map((repo) => repo.name) : []);
     items.forEach((item, index) => {
@@ -107,20 +124,39 @@ export function stageNotes(workspace, items, pointerOf, options) {
         if (repo !== undefined && !repoNames.has(repo))
             parents.push({ pointer: `${pointerOf(index)}/frontmatter/repo`, message: `${String(repo)} is not a linked repo in brain.json repos` });
     });
+    parents.push(...documentProblems(workspace, items, pointerOf));
     assertNoProblems(parents);
+    assertPlacesExist(workspace, items, pointerOf);
     const today = formatDate(options.now);
     const taken = new Set([...existing, ...seen]);
     const result = { created: [], skipped: [], pointers: new Map() };
+    const wholeKept = new Map();
     items.forEach((item, index) => {
         const lf = item.body.replace(/\r\n?/g, "\n");
         const body = lf === "" || lf.endsWith("\n") ? lf : `${lf}\n`;
         const attributes = { type: item.type, title: item.title, ...item.frontmatter };
         if (KNOWLEDGE_TYPES.has(item.type))
             attributes.lifecycle = options.lifecycle ?? "draft";
+        if (item.type === "reference" && attributes.origin === "whole") {
+            // The source's own text needs no Review; one whole Document per source (spec/cli.md §5.5, 0049).
+            const source = String(attributes.sources[0]);
+            const kept = workspace.notes.find((note) => note.type === "reference" && note.attributes.origin === "whole" && Array.isArray(note.attributes.sources) && note.attributes.sources[0] === source)?.id
+                ?? wholeKept.get(source);
+            if (kept !== undefined) {
+                result.skipped.push({ input_index: index, reason: "ALREADY_KEPT", existing: kept });
+                return;
+            }
+            attributes.lifecycle = "reviewed";
+        }
+        if (item.type === "reference" && attributes.origin === "promoted") {
+            // A promoted Document stands where its note stands (0049).
+            attributes.lifecycle = workspace.get(String(attributes.promoted_from))?.attributes.lifecycle ?? attributes.lifecycle;
+        }
         if (item.type === "source") {
             const hash = `sha256:${createHash("sha256").update(body, "utf8").digest("hex")}`;
             const sourceKey = attributes.source_key;
-            const duplicateByKey = typeof sourceKey === "string" && (sourceKey.startsWith("file:") || attributes.kind === "capture");
+            // A new version (replaces) is compared by its text only, so a corrected input can be read again (0045).
+            const duplicateByKey = attributes.replaces === undefined && typeof sourceKey === "string" && (sourceKey.startsWith("file:") || attributes.kind === "capture");
             const duplicate = workspace.notes.find((note) => note.type === "source" && (note.attributes.content_hash === hash || (duplicateByKey && note.attributes.source_key === sourceKey)));
             if (duplicate !== undefined) {
                 result.skipped.push({ input_index: index, reason: "DUPLICATE_SOURCE", existing: duplicate.id });
@@ -128,13 +164,6 @@ export function stageNotes(workspace, items, pointerOf, options) {
             }
             attributes.content_hash = hash;
             attributes.captured ??= formatTimestamp(options.now);
-            // The kind sets whether the Inbox row shows the text (0043): full for email and chat.
-            if (attributes.notion_text === undefined && attributes.attached_to === undefined) {
-                if (attributes.kind === "email" || attributes.kind === "chat")
-                    attributes.notion_text = "full";
-                else if (attributes.kind === "document" || attributes.kind === "note")
-                    attributes.notion_text = "digest";
-            }
         }
         const id = item.id ?? generateId(TYPE_PREFIX[item.type], taken);
         taken.add(id);
@@ -146,10 +175,74 @@ export function stageNotes(workspace, items, pointerOf, options) {
         const path = newNotePath(item.type, item.title, date, (candidate) => workspace.exists(candidate), attributes.source_key);
         workspace.write(path, serializeNewFile(attributes, body));
         result.created.push({ id, type: item.type, title: item.title, path });
+        if (item.type === "reference" && attributes.origin === "whole")
+            wholeKept.set(String(attributes.sources[0]), id);
         result.pointers.set(path, pointerOf(index));
     });
     return result;
 }
+/** Normalized body as `stageNotes` writes it: LF line endings and a trailing newline. */
+function writtenBody(body) {
+    const lf = body.replace(/\r\n?/g, "\n");
+    return lf === "" || lf.endsWith("\n") ? lf : `${lf}\n`;
+}
+function sha256(body) {
+    return `sha256:${createHash("sha256").update(body, "utf8").digest("hex")}`;
+}
+/** The Document rules of spec/cli.md §5.5 (0049) that the JSON Schema can't state. */
+function documentProblems(workspace, items, pointerOf) {
+    const problems = [];
+    const promoted = new Map();
+    for (const note of workspace.notes)
+        if (note.type === "reference" && note.attributes.origin === "promoted")
+            promoted.set(String(note.attributes.promoted_from), note.id);
+    items.forEach((item, index) => {
+        if (item.type !== "reference")
+            return;
+        const at = (key, message) => problems.push({ pointer: `${pointerOf(index)}/${key}`, message });
+        const { origin, sources, promoted_from: from } = item.frontmatter;
+        if (origin === "whole") {
+            if (!Array.isArray(sources) || sources.length !== 1 || typeof sources[0] !== "string" || !sources[0].startsWith("src-")) {
+                return at("frontmatter/sources", "a whole Document names exactly one source (src-)");
+            }
+            const id = sources[0];
+            const existing = workspace.get(id);
+            const earlier = items.slice(0, index).find((candidate) => candidate.id === id && candidate.type === "source");
+            const hash = existing?.type === "source" ? existing.attributes.content_hash : earlier !== undefined ? sha256(writtenBody(earlier.body)) : undefined;
+            if (hash === undefined)
+                return at("frontmatter/sources", `${id} is not an existing source or one earlier in the batch`);
+            if (sha256(writtenBody(item.body)) !== hash)
+                at("body", `a whole Document's body must be ${id}'s body byte for byte`);
+        }
+        if (origin === "promoted" && typeof from === "string") {
+            const type = workspace.get(from)?.type;
+            if (type !== "decision" && type !== "concept")
+                return at("frontmatter/promoted_from", `${from} is not an existing decision or concept`);
+            const other = promoted.get(from);
+            if (other !== undefined)
+                return at("frontmatter/promoted_from", `${from} is already promoted to ${other}`);
+            promoted.set(from, item.id ?? `${pointerOf(index)}`);
+        }
+    });
+    return problems;
+}
+/** A source's `area` and `projects` name existing notes of those types (spec/cli.md §5.5, 0050). */
+function assertPlacesExist(workspace, items, pointerOf) {
+    const problems = [];
+    items.forEach((item, index) => {
+        if (item.type !== "source")
+            return;
+        const { area, projects } = item.frontmatter;
+        if (typeof area === "string" && workspace.get(area)?.type !== "area")
+            problems.push({ pointer: `${pointerOf(index)}/frontmatter/area`, message: `${area} is not an existing area` });
+        (Array.isArray(projects) ? projects : []).forEach((project, position) => {
+            if (typeof project === "string" && workspace.get(project)?.type !== "project")
+                problems.push({ pointer: `${pointerOf(index)}/frontmatter/projects/${position}`, message: `${project} is not an existing project` });
+        });
+    });
+    if (problems.length > 0)
+        throw new BrainError("UNKNOWN_ID", `${problems[0].pointer} ${problems[0].message}`, problems);
+}
 /**
  * Throw INPUT_INVALID if the staged writes add lint errors anywhere in the brain (spec/cli.md
  * §3.6.1). Errors in a staged file point at its input item; others name the file and point at `root`.

package/dist/lib/paths.js

@@ -49,6 +49,7 @@ function layout(type, slug, date, sourceKey) {
         case "org": return file(`knowledge/orgs/${slug}.md`);
         case "question": return file(`knowledge/questions/${slug}.md`);
         case "concept": return file(`knowledge/concepts/${slug}.md`);
+        case "reference": return file(`knowledge/references/${slug}.md`);
         case "meeting": return file(`knowledge/meetings/${date}-${slug}.md`);
         case "decision": return file(`knowledge/decisions/${date}-${slug}.md`);
         case "source": return file(`sources/${sourceFolder(sourceKey)}/${date}-${slug}.md`);