ultimate-brain 0.4.1 → 0.5.0

package/dist/commands/source.js

@@ -1,5 +1,6 @@
 import { BrainError } from "../lib/errors.js";
 import { rangesProblem, splitParts } from "../lib/parts.js";
+import { lineDiff } from "../lib/diff.js";
 import { hasInboxBody } from "../lib/sync.js";
 import { formatTimestamp } from "../lib/time.js";
 import { Workspace } from "../lib/workspace.js";
@@ -54,3 +55,36 @@ export const sourceFullTextCommand = {
         };
     },
 };
+/** `brain source diff <src-id>` (spec/cli.md §5.19, 0045): the lines that changed from the version it replaces. */
+export const sourceDiffCommand = {
+    name: "source diff",
+    usage: "brain source diff <src-id> [--json]",
+    summary: "Show the lines a new version of a source changed against the version it replaces, without context lines. Read-only.",
+    options: {},
+    maxPositionals: 1,
+    needsBrain: true,
+    async run({ args, brain }) {
+        const [id] = args.positionals;
+        if (id === undefined)
+            throw new BrainError("USAGE", "Name the source: brain source diff <src-id>");
+        const workspace = await Workspace.open(brain);
+        const note = workspace.get(id);
+        if (note === undefined)
+            throw new BrainError("UNKNOWN_ID", `No note with id ${id}`);
+        const invalid = (message) => { throw new BrainError("INPUT_INVALID", message, [{ pointer: "", message }]); };
+        if (note.type !== "source")
+            invalid(`${id} is a ${note.type}, not a source`);
+        const replaces = note.attributes.replaces;
+        if (typeof replaces !== "string")
+            invalid(`${id} has no replaces: it is the first version`);
+        const earlier = workspace.get(replaces);
+        if (earlier === undefined)
+            throw new BrainError("UNKNOWN_ID", `No note with id ${String(replaces)}`);
+        const lines = lineDiff(earlier.body, note.body);
+        const diff = lines.join("\n");
+        return {
+            data: { id: note.id, replaces: earlier.id, removed: lines.filter((line) => line.startsWith("- ")).length, added: lines.filter((line) => line.startsWith("+ ")).length, diff },
+            human: diff === "" ? "no lines changed\n" : `${diff}\n`,
+        };
+    },
+};

package/dist/commands/status.js

@@ -7,7 +7,7 @@ import { scanNotes } from "../lib/notes.js";
 import { describeErrors, loadSchemas } from "../lib/schemas.js";
 import { isRecord } from "../lib/input.js";
 import { expandPath, linkedRepos, workTreeTop } from "../lib/repos.js";
-const NOTE_TYPES = ["area", "project", "person", "org", "meeting", "decision", "question", "concept", "source", "view", "goal", "memory"];
+const NOTE_TYPES = ["area", "project", "person", "org", "meeting", "decision", "question", "concept", "source", "view", "goal", "memory", "reference"];
 const PROPOSAL_STATUSES = ["pending", "approved", "edited", "rejected", "applied", "closed"];
 /** `brain status` (spec/cli.md §5.2). */
 export const statusCommand = {
@@ -75,7 +75,7 @@ function readNotion(config) {
     const databases = notion.databases;
     const configured = [];
     const missing = [];
-    for (const key of ["areas", "goals", "key_results", "projects", "meetings", "people", "orgs", "decisions", "questions", "review", "inbox", "concepts"]) {
+    for (const key of ["areas", "goals", "key_results", "projects", "meetings", "people", "orgs", "decisions", "questions", "review", "inbox", "concepts", "references"]) {
         const value = key === "inbox" && databases.inbox === undefined ? databases.capture_inbox : databases[key];
         (typeof value === "string" && value !== "" ? configured : missing).push(key);
     }

package/dist/lib/apply.js

@@ -2,15 +2,16 @@ 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 { bodyHash, bodyOf, reviewTitle, sourceTitle, stageNewItem, writeProposal } from "./proposals.js";
 import { loadSchemas } from "./schemas.js";
 import { formatDate, normalizeTimestamp } from "./time.js";
-const ACTIONS = ["approve", "reject", "edit"];
-export const EDITABLE = new Set(["update_fact", "contradiction", "add_to_note", "answer"]);
+const ACTIONS = ["approve", "reject", "fix", "edit"];
+export const EDITABLE = new Set(["update_fact", "contradiction", "add_to_note", "update_body", "answer"]);
+const FIX_KEYS = ["value", "change", "note", "field", "link"];
 /** 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 KNOWLEDGE_TYPES = new Set(["area", "goal", "project", "person", "org", "meeting", "decision", "question", "concept", "reference", "memory"]);
 const REFERENCE_FIELDS = [
     "area", "areas", "goal", "client", "org", "projects", "people", "attendees", "deciders", "source", "sources",
     "answer", "project", "generated_from", "facts",
@@ -49,19 +50,25 @@ export function parseApplyInput(input) {
         const pointer = `/decisions/${index}`;
         if (!isRecord(item))
             return problems.push({ pointer, message: "must be an object" });
-        problems.push(...unknownKeys(item, ["proposal", "action", "value", "note", "exclude", "decided_at", "decided_by"], pointer));
+        problems.push(...unknownKeys(item, ["proposal", "action", "value", "note", "fixes", "exclude", "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" });
+            problems.push({ pointer: `${pointer}/action`, message: "must be approve, reject, fix or edit" });
+        if (item.action === "fix" && (typeof item.note !== "string" || item.note === ""))
+            problems.push({ pointer: `${pointer}/note`, message: "is required for fix: the user's words" });
+        if (item.action === "fix" && (!Array.isArray(item.fixes) || item.fixes.length === 0 || item.fixes.some((entry) => !isRecord(entry) || !Object.hasOwn(entry, "value") || Object.keys(entry).some((key) => !FIX_KEYS.includes(key)))))
+            problems.push({ pointer: `${pointer}/fixes`, message: "must be a non-empty list of entries with a value (spec/schema.md §11.3)" });
+        if (item.action !== "fix" && item.fixes !== undefined)
+            problems.push({ pointer: `${pointer}/fixes`, message: "is only allowed for fix" });
         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 (item.note !== undefined && typeof item.note !== "string")
             problems.push({ pointer: `${pointer}/note`, message: "must be a string" });
-        if (item.exclude !== undefined && (!Array.isArray(item.exclude) || item.exclude.some((entry) => !isRecord(entry) || !(isNoteExclude(entry) || (typeof entry.field === "string" && Object.hasOwn(entry, "value") && Object.keys(entry).every((key) => ["target", "field", "value"].includes(key)))))))
-            problems.push({ pointer: `${pointer}/exclude`, message: "must be a list of {field, value}, {target, field, value} or {note} entries" });
+        if (item.exclude !== undefined && (!Array.isArray(item.exclude) || item.exclude.some((entry) => !isRecord(entry) || !(isNoteExclude(entry) || isChangeExclude(entry) || (typeof entry.field === "string" && Object.hasOwn(entry, "value") && Object.keys(entry).every((key) => ["target", "field", "value"].includes(key)))))))
+            problems.push({ pointer: `${pointer}/exclude`, message: "must be a list of {field, value}, {target, field, value}, {note} or {change} entries" });
         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")
@@ -178,10 +185,10 @@ function applyDecision(workspace, input, today, recordOnly) {
     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 }), ...(input.note === undefined ? {} : { note: input.note }), ...(input.exclude === undefined ? {} : { exclude: input.exclude }), decided_at: input.decided_at, decided_by: input.decided_by };
+    const incoming = { action: input.action, ...(input.value === undefined ? {} : { value: input.value }), ...(input.note === undefined ? {} : { note: input.note }), ...(input.fixes === undefined ? {} : { fixes: input.fixes }), ...(input.exclude === undefined ? {} : { exclude: input.exclude }), 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) || !isDeepStrictEqual(recorded.exclude, incoming.exclude))) {
+    if (recorded !== undefined && (recorded.action !== incoming.action || !isDeepStrictEqual(recorded.value, incoming.value) || !isDeepStrictEqual(recorded.fixes, incoming.fixes) || !isDeepStrictEqual(recorded.exclude, incoming.exclude))) {
         // 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;
@@ -190,30 +197,31 @@ function applyDecision(workspace, input, today, recordOnly) {
         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)`);
+        throw new ItemFailure("EDIT_NOT_ALLOWED", `edit is not allowed on a ${String(p.kind)} proposal (spec/schema.md §11.1); use fix`);
     }
+    const exclude = decision.exclude ?? [];
     if (decision.exclude !== undefined) {
-        if (decision.action !== "approve" || (p.kind !== "add_link" && p.kind !== "review_notes"))
-            throw new ItemFailure("INPUT_INVALID", "exclude is only allowed on an approved add_link or review_notes proposal");
+        if ((decision.action !== "approve" && decision.action !== "fix") || (p.kind !== "add_link" && p.kind !== "review_notes"))
+            throw new ItemFailure("INPUT_INVALID", "exclude is only allowed on an approved or fixed add_link or review_notes proposal");
         if (p.kind === "add_link") {
-            if (decision.exclude.some((excluded) => excluded.target !== undefined || isNoteExclude(excluded)))
+            if (exclude.some((excluded) => excluded.target !== undefined || isNoteExclude(excluded) || isChangeExclude(excluded)))
                 throw new ItemFailure("INPUT_INVALID", "exclude on an add_link takes {field, value} entries");
             const links = proposalLinks(p);
-            if (decision.exclude.some((excluded) => !links.some((link) => link.field === excluded.field && isDeepStrictEqual(link.value, excluded.value))))
+            if (exclude.some((excluded) => !links.some((link) => link.field === excluded.field && isDeepStrictEqual(link.value, excluded.value))))
                 throw new ItemFailure("EXCLUDE_UNKNOWN", "exclude contains a link that is not in the proposal");
         }
         else {
-            if (decision.exclude.some((excluded) => !isNoteExclude(excluded) && excluded.target === undefined))
-                throw new ItemFailure("INPUT_INVALID", "exclude on a review_notes takes {note} and {target, field, value} entries");
-            const notes = list(p.notes);
-            const links = reviewLinks(p);
-            if (decision.exclude.some((excluded) => isNoteExclude(excluded) ? !notes.includes(excluded.note) : !links.some((link) => sameLink(link, excluded))))
+            if (exclude.some((excluded) => !isNoteExclude(excluded) && !isChangeExclude(excluded) && excluded.target === undefined))
+                throw new ItemFailure("INPUT_INVALID", "exclude on a review_notes takes {note}, {target, field, value} and {change} entries");
+            if (exclude.some((excluded) => !inReview(p, excluded)))
                 throw new ItemFailure("EXCLUDE_UNKNOWN", "exclude contains an entry that is not in the proposal");
         }
     }
+    // A fix corrects the proposal before it is applied; the file keeps what was proposed (spec/schema.md §11.3).
+    const fixed = decision.action === "fix" ? corrected(workspace, p, decision.fixes ?? [], exclude) : { q: p, noteFixes: new Map() };
     const action = decision.action === incoming.action ? undefined : decision.action;
     p.decision = decision;
-    p.status = decision.action === "approve" ? "approved" : decision.action === "edit" ? "edited" : "rejected";
+    p.status = decision.action === "approve" ? "approved" : decision.action === "reject" ? "rejected" : "edited";
     p.updated = today;
     if (recordOnly) {
         workspace.save(proposal.path, document);
@@ -223,18 +231,21 @@ function applyDecision(workspace, input, today, recordOnly) {
         p.status = "closed";
         workspace.save(proposal.path, document);
         // A rejected review_notes archives the notes still draft, with no successor (spec/schema.md §11.2).
-        const notes = p.kind === "review_notes" ? reviewNotes(workspace, p, "reject", [], today) : undefined;
+        const notes = p.kind === "review_notes" ? reviewNotes(workspace, p, "reject", [], today, "", new Map()).notes : undefined;
         return { result: "closed", action, ...(notes === undefined ? {} : { notes }) };
     }
     const D = decision.decided_at.slice(0, 10);
-    const V = decision.action === "edit" ? decision.value : undefined;
+    const V = decision.action === "edit" ? decision.value : fixed.value;
     if (p.kind === "review_notes") {
-        const notes = reviewNotes(workspace, p, "approve", decision.exclude ?? [], today);
+        const applied = reviewNotes(workspace, fixed.q, "approve", exclude, today, D, fixed.noteFixes);
+        if (applied.dropped.length > 0)
+            p.dropped = applied.dropped;
         p.status = "applied";
         workspace.save(proposal.path, document);
-        return { result: "applied", action, notes };
+        const deferred = exclude.length === 0 ? undefined : defer(workspace, proposal.id, p, exclude, today);
+        return { result: "applied", action, notes: applied.notes, changes: applied.changes, ...(deferred === undefined ? {} : { deferred }) };
     }
-    const stale = applyKind(workspace, p, proposal.path, V, D, today, (decision.exclude ?? []));
+    const stale = applyKind(workspace, fixed.q, proposal.path, V, D, today, exclude);
     if (stale !== null) {
         p.status = "closed";
         p.closed_reason = "stale";
@@ -245,6 +256,158 @@ function applyDecision(workspace, input, today, recordOnly) {
     workspace.save(proposal.path, document);
     return { result: "applied", action };
 }
+/** Whether an exclude or fix entry names an item of a review_notes (spec/schema.md §11.3). */
+function inReview(p, entry) {
+    if (entry.change !== undefined)
+        return Number.isInteger(entry.change) && entry.change >= 0 && entry.change < list(p.changes).length;
+    if (entry.note !== undefined)
+        return list(p.notes).includes(entry.note);
+    return reviewLinks(p).some((link) => sameLink(link, entry));
+}
+/**
+ * The proposal as `fixes` correct it (spec/schema.md §11.3): a copy of its fields, the value V for
+ * single-value kinds, and the fields to set on listed notes. Throws FIX_UNKNOWN for an entry that names
+ * no item, INVALID_RESULT for a value of the wrong shape, INPUT_INVALID for an item fixed and excluded.
+ */
+function corrected(workspace, p, fixes, exclude) {
+    const q = structuredClone(p);
+    const noteFixes = new Map();
+    const kind = String(p.kind);
+    const unknown = (entry) => { throw new ItemFailure("FIX_UNKNOWN", `fixes entry ${JSON.stringify(entry)} names no item of this ${kind} proposal`); };
+    const shape = (message) => { throw new ItemFailure("INVALID_RESULT", message); };
+    const only = (keys) => (entry) => Object.keys(entry).every((key) => keys.includes(key));
+    const single = () => {
+        const entry = fixes[0];
+        if (!only(["value"])(entry))
+            unknown(entry);
+        if (fixes.length !== 1)
+            shape(`a fix on a ${kind} takes exactly one {value}`);
+        return entry;
+    };
+    if (kind === "update_fact" || kind === "contradiction") {
+        const { value } = single();
+        if (typeof value !== "string" && typeof value !== "number")
+            shape("a fact value is a string or a number");
+        return { q, value, noteFixes };
+    }
+    if (kind === "add_to_note" || kind === "update_body" || kind === "answer") {
+        const { value } = single();
+        if (typeof value !== "string" || value.trim() === "")
+            shape(`a fix on a ${kind} is a non-empty text`);
+        return { q, value, noteFixes };
+    }
+    if (kind === "supersede" || kind === "merge") {
+        const { value } = single();
+        const key = kind === "supersede" ? "supersedes" : "merge_into";
+        const note = typeof value === "string" ? workspace.get(value) : undefined;
+        const target = workspace.get(String(p.target));
+        if (note === undefined || note.id === p.target || note.type !== target?.type)
+            shape(`${String(value)} must be another existing ${target?.type ?? "note"}`);
+        if (kind === "supersede" && list(note.attributes.relations).some((relation) => record(relation).type === "superseded_by"))
+            shape(`${note.id} is already superseded`);
+        q[key] = note.id;
+        return { q, noteFixes };
+    }
+    if (kind === "new_item") {
+        const note = record(q.note);
+        const frontmatter = record(note.frontmatter);
+        for (const entry of fixes) {
+            if (!only(["field", "value"])(entry) || typeof entry.field !== "string" || (entry.field !== "title" && !Object.hasOwn(frontmatter, entry.field)))
+                unknown(entry);
+            if (entry.field === "title")
+                note.title = entry.value;
+            else
+                frontmatter[entry.field] = entry.value;
+        }
+        return { q, noteFixes };
+    }
+    if (kind === "add_link") {
+        const links = list(q.links).map(record);
+        for (const entry of fixes) {
+            const link = record(entry.link);
+            const at = only(["link", "value"])(entry) ? links.findIndex((candidate) => candidate.field === link.field && isDeepStrictEqual(candidate.value, link.value)) : -1;
+            if (at === -1)
+                unknown(entry);
+            if (exclude.some((excluded) => excluded.field === link.field && isDeepStrictEqual(excluded.value, link.value)))
+                throw new ItemFailure("INPUT_INVALID", "an item can't be both fixed and excluded");
+            links[at] = { ...links[at], value: entry.value };
+        }
+        q.links = links;
+        return { q, noteFixes };
+    }
+    if (kind === "review_notes") {
+        const changes = list(q.changes).map(record);
+        const links = list(q.links).map(record);
+        for (const entry of fixes) {
+            const excluded = (item) => exclude.some((other) => isDeepStrictEqual(other, item));
+            if (entry.change !== undefined) {
+                if (!only(["change", "value"])(entry) || !inReview(p, { change: entry.change }))
+                    unknown(entry);
+                if (excluded({ change: entry.change }))
+                    throw new ItemFailure("INPUT_INVALID", "an item can't be both fixed and excluded");
+                const change = changes[entry.change];
+                if (change.kind === "update_fact") {
+                    if (typeof entry.value !== "string" && typeof entry.value !== "number")
+                        shape("a fact value is a string or a number");
+                    change.after = entry.value;
+                }
+                else {
+                    if (typeof entry.value !== "string" || entry.value.trim() === "")
+                        shape(`a fix on an ${String(change.kind)} is a non-empty text`);
+                    change.content = entry.value;
+                }
+            }
+            else if (entry.note !== undefined) {
+                if (!only(["note", "field", "value"])(entry) || !inReview(p, { note: entry.note }))
+                    unknown(entry);
+                if (excluded({ note: entry.note }))
+                    throw new ItemFailure("INPUT_INVALID", "an item can't be both fixed and excluded");
+                const field = entry.field;
+                if (typeof field !== "string" || !(NOTE_FIX_FIELDS.includes(field) || /^facts\.[a-z][a-z0-9_]*$/.test(field)))
+                    shape(`${String(field)} is not a field a fix may set on a note`);
+                noteFixes.set(String(entry.note), [...(noteFixes.get(String(entry.note)) ?? []), { field, value: entry.value }]);
+            }
+            else if (entry.link !== undefined) {
+                const link = record(entry.link);
+                const at = only(["link", "value"])(entry) ? links.findIndex((candidate) => sameLink({ target: candidate.target, field: candidate.field, value: candidate.value }, link)) : -1;
+                if (at === -1)
+                    unknown(entry);
+                if (excluded(link))
+                    throw new ItemFailure("INPUT_INVALID", "an item can't be both fixed and excluded");
+                links[at] = { ...links[at], value: entry.value };
+            }
+            else {
+                unknown(entry);
+            }
+        }
+        q.changes = changes;
+        q.links = links;
+        return { q, noteFixes };
+    }
+    throw new ItemFailure("INVALID_RESULT", `Unknown proposal kind ${kind}`);
+}
+/** Fields a fix may set on a note listed by a review_notes: those a correction may set, and projects (spec/schema.md §11.3). */
+const NOTE_FIX_FIELDS = ["title", "summary", "why", "area", "goal", "client", "org", "people", "projects"];
+/**
+ * Write the excluded items of an applied review_notes as one new pending review_notes (spec/schema.md
+ * §11.3): the same source, `deferred_from` = this proposal, each item as stored, in its original order.
+ */
+function defer(workspace, id, p, exclude, today) {
+    const notes = list(p.notes).filter((note) => exclude.some((entry) => isNoteExclude(entry) && entry.note === note));
+    const links = reviewLinks(p).filter((link) => exclude.some((entry) => sameLink(link, entry)));
+    const changes = list(p.changes).filter((_change, index) => exclude.some((entry) => entry.change === index));
+    const source = String(p.source);
+    const fields = {
+        kind: "review_notes",
+        title: reviewTitle(workspace, source, changes.length, notes.length, links.length, "Deferred from"),
+        notes, links,
+        ...(changes.length === 0 ? {} : { changes }),
+        deferred_from: id,
+        why: p.why,
+        source,
+    };
+    return writeProposal(workspace, fields, today).id;
+}
 /** Apply a proposal's kind to its targets. Returns a message when the proposal is stale. */
 function applyKind(workspace, p, proposalPath, V, D, today, exclude = []) {
     const kind = String(p.kind);
@@ -263,6 +426,8 @@ function applyKind(workspace, p, proposalPath, V, D, today, exclude = []) {
             return `facts.${field} is ${shown(current)}, proposal expected ${shown(p.before)}`;
         }
     }
+    if (kind === "update_body" && bodyHash(target.body) !== p.before_hash)
+        return `${target.id}'s body changed after the proposal was written`;
     switch (kind) {
         case "update_fact":
             setFact(a, field, V ?? p.after, String(p.from), D, String(p.source));
@@ -280,6 +445,10 @@ function applyKind(workspace, p, proposalPath, V, D, today, exclude = []) {
             a.sources = union(list(a.sources), [p.source]);
             break;
         }
+        case "update_body":
+            document.body = bodyOf(String(V ?? p.content));
+            a.sources = union(list(a.sources), [p.source]);
+            break;
         case "add_link":
             for (const link of proposalLinks(p))
                 if (!exclude.some((item) => item.field === link.field && isDeepStrictEqual(item.value, link.value)) && !list(a[String(link.field)]).some((value) => isDeepStrictEqual(value, link.value)))
@@ -308,23 +477,55 @@ function applyKind(workspace, p, proposalPath, V, D, today, exclude = []) {
     return null;
 }
 /**
- * Apply or reject a review_notes proposal (spec/schema.md §11.2): approve marks the listed draft
- * notes `reviewed` and applies the links, reject archives the draft notes. Excluded entries stay
- * as they are; a note no longer `draft` is left alone and reported `unchanged`.
+ * Apply or reject a review_notes proposal (spec/schema.md §11.2–11.3). Approve applies, in order, the
+ * changes not excluded (a stale one is dropped alone), marks the listed draft notes `reviewed` with
+ * their fixes, and applies the links; reject archives the draft notes. Excluded entries stay as they
+ * are; a note no longer `draft` is left alone and reported `unchanged`.
  */
-function reviewNotes(workspace, p, action, exclude, today) {
+function reviewNotes(workspace, p, action, exclude, today, D, noteFixes) {
+    const changes = [];
+    const dropped = [];
+    if (action === "approve") {
+        list(p.changes).map(record).forEach((change, index) => {
+            const entry = { index, kind: String(change.kind), target: String(change.target) };
+            if (exclude.some((excluded) => excluded.change === index)) {
+                changes.push({ ...entry, result: "deferred" });
+                return;
+            }
+            const stale = applyKind(workspace, { ...change, source: p.source }, "", undefined, D, today);
+            if (stale === null)
+                changes.push({ ...entry, result: "applied" });
+            else {
+                changes.push({ ...entry, result: "dropped", reason: "STALE_PROPOSAL" });
+                dropped.push({ change: index, reason: "stale" });
+            }
+        });
+    }
     const results = [];
     for (const id of list(p.notes).map(String)) {
         const note = existing(workspace, id);
-        const lifecycle = String(note.attributes.lifecycle);
         const excluded = exclude.some((entry) => isNoteExclude(entry) && entry.note === id);
+        const fixes = action === "approve" ? noteFixes.get(id) ?? [] : [];
+        if (fixes.length > 0) {
+            const document = workspace.edit(note);
+            for (const { field, value } of fixes) {
+                const fact = /^facts\.(.+)$/.exec(String(field))?.[1];
+                if (fact !== undefined)
+                    setFact(document.attributes, fact, value, D, D, String(p.source));
+                else
+                    document.attributes[String(field)] = value;
+            }
+            document.attributes.updated = today;
+            workspace.save(note.path, document);
+        }
+        const lifecycle = String(workspace.get(id).attributes.lifecycle);
         if (lifecycle !== "draft")
             results.push({ id, result: "unchanged", lifecycle });
         else if (excluded)
             results.push({ id, result: "kept_draft", lifecycle });
         else {
             const next = action === "approve" ? "reviewed" : "archived";
-            const document = workspace.edit(note);
+            const document = workspace.edit(workspace.get(id));
             document.attributes.lifecycle = next;
             document.attributes.updated = today;
             workspace.save(note.path, document);
@@ -345,7 +546,7 @@ function reviewNotes(workspace, p, action, exclude, today) {
             workspace.save(target.path, document);
         }
     }
-    return results;
+    return { notes: results, changes, dropped };
 }
 function reviewLinks(proposal) {
     return list(proposal.links).filter(isRecord).map((link) => ({ target: link.target, field: link.field, value: link.value }));
@@ -356,6 +557,9 @@ function sameLink(link, entry) {
 function isNoteExclude(entry) {
     return typeof entry.note === "string" && Object.keys(entry).length === 1;
 }
+function isChangeExclude(entry) {
+    return Number.isInteger(entry.change) && entry.change >= 0 && Object.keys(entry).length === 1;
+}
 function proposalLinks(proposal) {
     if (Array.isArray(proposal.links))
         return proposal.links.filter(isRecord).map((link) => ({ field: link.field, value: link.value }));

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/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", "References"],
 ];
 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 [["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",
 ]);
 /** 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,28 @@ 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 (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 +277,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 +290,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))