ultimate-brain 0.4.1 → 0.5.0

package/dist/lib/note-new.js

@@ -7,7 +7,7 @@ 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}$/;
@@ -100,6 +100,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) => {
@@ -120,7 +138,8 @@ export function stageNotes(workspace, items, pointerOf, options) {
         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 });

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`);

package/dist/lib/proposals.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { isDeepStrictEqual } from "node:util";
 import { BrainError } from "./errors.js";
 import { serializeNewFile } from "./frontmatter.js";
@@ -8,13 +9,15 @@ import { compareCodePoints } from "./notes.js";
 import { newNotePath } from "./paths.js";
 import { loadSchemas } from "./schemas.js";
 import { formatDate } from "./time.js";
-export const PROPOSAL_KINDS = ["update_fact", "add_to_note", "add_link", "supersede", "contradiction", "merge", "new_item", "review_notes", "answer"];
+export const PROPOSAL_KINDS = ["update_fact", "add_to_note", "update_body", "add_link", "supersede", "contradiction", "merge", "new_item", "review_notes", "answer"];
 export const PROPOSAL_STATUSES = ["pending", "approved", "rejected", "edited", "applied", "closed"];
 /** Input keys of `proposal new`: the schema §11 fields the CLI does not set (spec/cli.md §5.6). */
 const INPUT_KEYS = ["title", "kind", "target", "field", "notes", "answer", "answer_note", "before", "after", "from", "content", "note", "supersedes", "merge_into", "why", "source"];
 const ID = /^[a-z]{2,4}-[0-9a-hjkmnp-tv-z]{8}$/;
-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 ADD_LINK_FIELDS = new Set(["aliases", "tags", "projects", "people", "attendees", "deciders"]);
+/** Kinds a review_notes takes in as `changes`, in the order they are stored (spec/schema.md §11.3, 0045). */
+export const CHANGE_KINDS = ["update_fact", "update_body", "add_to_note"];
 /** Fields that make two pending proposals the same change (dedupe, spec/cli.md §5.6). */
 const DEDUPE_KEYS = ["kind", "target", "field", "after", "content", "note", "supersedes", "merge_into", "answer", "answer_note"];
 /**
@@ -40,7 +43,7 @@ export function stageProposals(workspace, items, now) {
         if (item.kind === "new_item")
             checkNewItem(workspace, item.note, `/proposals/${index}/note`, today);
     });
-    // One review_notes per source; it takes in that source's add_link items (spec/cli.md §5.6, 0043).
+    // One review_notes per source; it takes in that source's add_link items and changes (spec/cli.md §5.6, 0043, 0045).
     const reviews = new Map();
     list.forEach((item, index) => {
         if (item.kind !== "review_notes")
@@ -49,7 +52,7 @@ export function stageProposals(workspace, items, now) {
         if (reviews.has(source))
             assertNoProblems([{ pointer: `/proposals/${index}/source`, message: `a second review_notes for ${source} in one input` }]);
         checkReviewNotes(workspace, item, `/proposals/${index}`);
-        reviews.set(source, { index, item, links: [] });
+        reviews.set(source, { index, item, links: [], changes: [] });
     });
     const start = workspace.checkpoint();
     try {
@@ -62,7 +65,12 @@ export function stageProposals(workspace, items, now) {
                 skipped.push({ input_index: index, reason: "ALREADY_ANSWERED" });
                 return;
             }
-            const review = item.kind === "add_link" ? reviews.get(String(fields.source)) : undefined;
+            if (item.kind === "update_body" && bodyOf(String(fields.content)) === workspace.get(String(fields.target)).body) {
+                skipped.push({ input_index: index, reason: "NO_CHANGE" });
+                return;
+            }
+            const folds = item.kind === "add_link" || CHANGE_KINDS.includes(String(item.kind));
+            const review = folds ? reviews.get(String(fields.source)) : undefined;
             if (item.kind === "add_link" && listField(workspace.get(String(fields.target)), String(fields.field)).some((value) => isDeepStrictEqual(value, fields.after))) {
                 skipped.push({ input_index: index, reason: "ALREADY_LINKED" });
                 return;
@@ -72,11 +80,20 @@ export function stageProposals(workspace, items, now) {
                     ? (note.attributes.kind === "review_notes"
                         ? review !== undefined && reviewLinks(note.attributes).some((link) => link.target === fields.target && link.field === fields.field && isDeepStrictEqual(link.value, fields.after))
                         : note.attributes.target === fields.target && proposalLinks(note.attributes).some((link) => link.field === fields.field && isDeepStrictEqual(link.value, fields.after)))
-                    : DEDUPE_KEYS.every((key) => isDeepStrictEqual(note.attributes[key], fields[key]))));
+                    : DEDUPE_KEYS.every((key) => isDeepStrictEqual(note.attributes[key], fields[key]))
+                        || (CHANGE_KINDS.includes(String(item.kind)) && note.attributes.kind === "review_notes" && listOf(note.attributes.changes).some((change) => sameChange(change, fields)))));
             if (duplicate !== undefined) {
                 skipped.push({ input_index: index, reason: "DUPLICATE_PENDING", existing: duplicate.id });
                 return;
             }
+            if (review !== undefined && CHANGE_KINDS.includes(String(item.kind))) {
+                if (review.changes.some(({ change }) => sameChange(change, fields))) {
+                    skipped.push({ input_index: index, reason: "DUPLICATE_PENDING" });
+                    return;
+                }
+                review.changes.push({ index, change: changeEntry(fields) });
+                return;
+            }
             if (item.kind === "add_link") {
                 const key = JSON.stringify([fields.target, fields.source, fields.field, fields.after]);
                 if (linkKeys.has(key)) {
@@ -111,20 +128,24 @@ export function stageProposals(workspace, items, now) {
         }
         for (const review of reviews.values()) {
             const notes = review.item.notes;
-            if (notes.length === 0 && review.links.length === 0) {
+            if (notes.length === 0 && review.links.length === 0 && review.changes.length === 0) {
                 skipped.push({ input_index: review.index, reason: "NOTHING_TO_REVIEW" });
                 continue;
             }
             const source = String(review.item.source);
+            // Changes are stored in render order: every update_fact, then update_body, then add_to_note (spec/schema.md §11.3).
+            const changes = [...review.changes].sort((a, b) => CHANGE_KINDS.indexOf(String(a.change.kind)) - CHANGE_KINDS.indexOf(String(b.change.kind)) || a.index - b.index);
             const fields = {
                 kind: "review_notes",
-                title: review.item.title ?? reviewTitle(workspace, source, notes.length, review.links.length),
+                title: review.item.title ?? reviewTitle(workspace, source, changes.length, notes.length, review.links.length),
                 notes,
                 links: review.links.map(({ fields }) => ({ target: fields.target, field: fields.field, value: fields.after })),
-                why: review.item.why ?? `New notes and links from ${sourceTitle(workspace, source)}`,
+                ...(changes.length === 0 ? {} : { changes: changes.map(({ change }) => change) }),
+                why: review.item.why ?? `What came in from ${sourceTitle(workspace, source)}`,
                 source,
             };
-            const proposal = createProposal(workspace, fields, [review.index, ...review.links.map(({ index }) => index)].sort((a, b) => a - b), today, `/proposals/${review.index}`, pointers, created);
+            const held = [review.index, ...review.links.map(({ index }) => index), ...changes.map(({ index }) => index)].sort((a, b) => a - b);
+            const proposal = createProposal(workspace, fields, held, today, `/proposals/${review.index}`, pointers, created);
             for (const link of review.links)
                 createdLinks.set(JSON.stringify([link.fields.target, link.fields.source, link.fields.field, link.fields.after]), proposal.id);
         }
@@ -148,6 +169,11 @@ function createProposal(workspace, fields, inputIndexes, today, pointer, pointer
     created.push(proposal);
     return proposal;
 }
+/** Write a new pending proposal with these fields (apply's deferred row, spec/schema.md §11.3). Not validated. */
+export function writeProposal(workspace, fields, today) {
+    const { id, path } = createProposal(workspace, fields, [], today, "", new Map(), []);
+    return { id, path };
+}
 /** The `{target, field, value}` links of a review_notes proposal. */
 function reviewLinks(attributes) {
     return Array.isArray(attributes.links) ? attributes.links.filter(isRecord).map((link) => ({ target: link.target, field: link.field, value: link.value })) : [];
@@ -165,17 +191,38 @@ function reviewedIds(workspace) {
     return listed;
 }
 /** The meeting's title for a meeting id, else the source's (spec/cli.md §5.6). */
-function sourceTitle(workspace, source) {
+export function sourceTitle(workspace, source) {
     return String(workspace.get(source)?.attributes.title ?? source);
 }
-function reviewTitle(workspace, source, notes, links) {
+/** `From <source title>: 1 change, 3 new notes and 2 links` (spec/cli.md §5.6, 0045); a deferred row starts `Deferred from`. */
+export function reviewTitle(workspace, source, changes, notes, links, lead = "From") {
     const count = (n, one, many) => `${n} ${n === 1 ? one : many}`;
-    const from = sourceTitle(workspace, source);
-    const title = notes === 0
-        ? `Accept ${count(links, "link", "links")} from ${from}`
-        : `Accept ${count(notes, "new note", "new notes")} from ${from}${links === 0 ? "" : `, and ${count(links, "link", "links")}`}`;
+    const parts = [[changes, "change", "changes"], [notes, "new note", "new notes"], [links, "link", "links"]];
+    const counts = parts.filter(([n]) => n > 0).map(([n, one, many]) => count(n, one, many));
+    const joined = counts.length <= 1 ? counts.join("") : `${counts.slice(0, -1).join(", ")} and ${counts.at(-1)}`;
+    const title = `${lead} ${sourceTitle(workspace, source)}: ${joined}`;
     return title.length > 120 ? `${title.slice(0, 119)}…` : title;
 }
+/** A change entry of a review_notes: the item's kind, target, why and that kind's fields (spec/schema.md §11). */
+function changeEntry(fields) {
+    const keys = ["kind", "target", "why", "field", "before", "after", "from", "content", "before_hash"];
+    return Object.fromEntries(keys.filter((key) => fields[key] !== undefined).map((key) => [key, fields[key]]));
+}
+function sameChange(change, fields) {
+    return isRecord(change) && ["kind", "target", "field", "after", "content"].every((key) => isDeepStrictEqual(change[key], fields[key]));
+}
+/** A reference's body as stored, for `content`: one blank line after the frontmatter, LF endings, a final newline. */
+export function bodyOf(content) {
+    const text = content.replace(/\r\n?/g, "\n").replace(/^\n+/, "");
+    return `\n${text.endsWith("\n") ? text : `${text}\n`}`;
+}
+/** The body hash an update_body is checked against (the source hash rule, spec/schema.md §4). */
+export function bodyHash(body) {
+    return `sha256:${createHash("sha256").update(body, "utf8").digest("hex")}`;
+}
+function listOf(value) {
+    return Array.isArray(value) ? value : [];
+}
 /** A review_notes item's notes: existing knowledge notes, listed once here and by no other review_notes. */
 function checkReviewNotes(workspace, item, pointer) {
     const source = workspace.get(String(item.source));
@@ -248,6 +295,8 @@ function checkShape(item, pointer) {
     }
     if (item.kind === "answer" && (typeof item.answer !== "string" || item.answer.trim() === ""))
         at("answer", "must be a non-empty string");
+    if (item.kind === "update_body" && (typeof item.content !== "string" || item.content.trim() === ""))
+        at("content", "must be the whole new body");
     if (item.kind !== "answer") {
         for (const key of ["answer", "answer_note"])
             if (item[key] !== undefined)
@@ -324,6 +373,11 @@ function resolveFields(workspace, item, pointer, today) {
             fields.from = typeof meeting?.attributes.date === "string" ? meeting.attributes.date : today;
         }
     }
+    if (kind === "update_body") {
+        if (target.type !== "reference")
+            invalid("target", `is a ${target.type}; update_body replaces the body of a reference`);
+        fields.before_hash = bodyHash(target.body);
+    }
     if (kind === "add_link") {
         const field = typeof item.field === "string" ? item.field : "";
         if (!ADD_LINK_FIELDS.has(field))
@@ -403,7 +457,7 @@ export function listProposals(workspace, statuses, target) {
         .filter((note) => note.type === "proposal")
         .filter((note) => statuses.length === 0 || statuses.includes(String(note.attributes.status)))
         .filter((note) => target === undefined || note.attributes.target === target
-        || (note.attributes.kind === "review_notes" && ((Array.isArray(note.attributes.notes) && note.attributes.notes.includes(target)) || reviewLinks(note.attributes).some((link) => link.target === target))))
+        || (note.attributes.kind === "review_notes" && ((Array.isArray(note.attributes.notes) && note.attributes.notes.includes(target)) || reviewLinks(note.attributes).some((link) => link.target === target) || listOf(note.attributes.changes).some((change) => isRecord(change) && change.target === target))))
         .map((note) => ({ ...note.attributes, path: note.path }))
         .sort((a, b) => compareCodePoints(String(a.created), String(b.created)) || compareCodePoints(String(a.id), String(b.id)));
 }
@@ -436,7 +490,7 @@ export function stageBacklog(workspace, now) {
                 claimed.add(note.id);
             const fields = {
                 kind: "review_notes",
-                title: reviewTitle(workspace, provenance, notes.length, 0),
+                title: reviewTitle(workspace, provenance, 0, notes.length, 0),
                 notes: notes.map((note) => note.id),
                 links: [],
                 why: `Notes from ${sourceTitle(workspace, provenance)} waiting for your review`,

package/dist/lib/query.js

@@ -4,7 +4,7 @@ import { BrainError } from "./errors.js";
 import { compareCodePoints } from "./notes.js";
 /** V1 note types accepted by `brain query --types` (spec/cli.md §5.13). */
 export const QUERY_TYPES = [
-    "area", "goal", "project", "person", "org", "meeting", "decision", "question", "concept", "source", "view", "memory", "proposal",
+    "area", "goal", "project", "person", "org", "meeting", "decision", "question", "concept", "reference", "source", "view", "memory", "proposal",
 ];
 const DEFAULT_TYPES = new Set(QUERY_TYPES.filter((type) => !["view", "proposal", "memory"].includes(type)));
 const STOPWORDS = new Set([

package/dist/lib/schemas.js

@@ -3,7 +3,7 @@ import { Ajv2020 } from "ajv/dist/2020.js";
 /** The JSON Schemas of spec/schemas/, the single source of truth for file shapes. */
 const SCHEMA_DIR = new URL("../../spec/schemas/", import.meta.url);
 const KNOWLEDGE_TYPES = new Set([
-    "area", "goal", "project", "person", "org", "meeting", "decision", "question", "concept", "memory",
+    "area", "goal", "project", "person", "org", "meeting", "decision", "question", "concept", "reference", "memory",
 ]);
 let cached;
 export function loadSchemas() {