hafez 1.3.0 → 1.4.0

package/dist/document.js

@@ -1,140 +1,18 @@
 // src/document.ts
 // The Document module (see CONTEXT.md): owns the body of a vault file —
-// structural sections, session-log entries, wiki-links. Absorbs the former
-// sections.ts and parser.ts; every body read or mutation goes through the
-// single structural-heading model defined here. Pure string→string.
-import { ALL_CONTRACTS, SUBTYPE_SECTIONS, SESSION_SECTIONS } from './contracts.js';
+// structural sections, session-log entries, wiki-links. Every body read or
+// mutation goes through the single structural-heading model defined here.
+// Pure string→string.
+//
+// Which headings are structural is per-file knowledge: documentFor(ctx)
+// derives the section set from the file's kind/type/subtype via contracts
+// and returns the Document operations bound to it. There is deliberately no
+// global fallback set — a session-only heading like '## Decisions' quoted
+// inside an entity's Brief must NOT terminate that section.
+import { ALL_CONTRACTS, SUBTYPE_SECTIONS, SESSION_SECTIONS, getContract } from './contracts.js';
+import { localDay } from './dates.js';
 const UNCHECKED_RE = /^- \[ \] (.+)$/gm;
-/**
- * Known structural section headings in Hafez entities, knowledge notes, and
- * session files. Derived from contracts.ts (defaultSections + optionalSections
- * + session sections) plus auto-generated sections not tracked in contracts
- * (Related). Only these are treated as section boundaries. Any other `## `
- * heading inside section content (e.g. in a brief or session log) is
- * preserved as-is.
- */
-export const STRUCTURAL_SECTIONS = new Set([
-    ...ALL_CONTRACTS.flatMap(c => [...c.defaultSections, ...c.optionalSections]),
-    ...Object.values(SUBTYPE_SECTIONS).flat(),
-    ...SESSION_SECTIONS,
-    'Related', // auto-generated by syncRelatedSection
-]);
-/**
- * Find the next structural `## Heading` boundary after a given position.
- * Skips `## ` headings that are not known structural sections (content headings).
- * Returns the index of the `\n` before the `## `, or -1 if no structural heading found.
- */
-export function findNextStructuralHeading(body, from) {
-    const re = /\n## ([^\n]+)/g;
-    re.lastIndex = from;
-    let match;
-    while ((match = re.exec(body)) !== null) {
-        const headingName = match[1].trim();
-        if (STRUCTURAL_SECTIONS.has(headingName)) {
-            return match.index;
-        }
-    }
-    return -1;
-}
-/**
- * Find a ## Heading section and its content.
- * Returns { start, headingEnd, end, content } or null if not found.
- * Matches heading exactly (e.g. "## Brief" won't match "## Briefing").
- * Trailing whitespace on the heading line is tolerated — the splitter's
- * boundary tokenizer trims headings, so anything it treats as a boundary
- * must also be findable here (a hand-edited `## Session Log ` otherwise
- * gets a duplicate section and archival never fires).
- * Only treats known structural headings as section boundaries -- content
- * inside a section may contain arbitrary `## ` headings without corruption.
- */
-export function findSection(body, heading) {
-    const re = new RegExp(`(^|\\n)(## ${escapeRegex(heading)}[ \\t]*)(?:\\n|$)`);
-    const match = re.exec(body);
-    if (!match)
-        return null;
-    const start = match.index + match[1].length;
-    const headingEnd = start + match[2].length;
-    const afterHeading = headingEnd + 1;
-    // Find the next structural ## heading or EOF. Scan from the heading's own
-    // trailing newline (afterHeading - 1), not past it — otherwise a structural
-    // heading on the immediately following line (no blank line between, as in
-    // hand-edited files) is invisible and mutators swallow the next section.
-    const nextHeading = findNextStructuralHeading(body, Math.max(0, afterHeading - 1));
-    const end = nextHeading === -1 ? body.length : nextHeading;
-    const rawContent = body.slice(afterHeading, end);
-    const content = rawContent.replace(/^\n+/, '').replace(/\n+$/, '');
-    return { start, headingEnd, end, content };
-}
-function escapeRegex(s) {
-    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
-/**
- * Split a body into preamble + structural sections. Non-structural `## `
- * headings stay inside the enclosing section's content — sections are
- * atomic units of authored content, never split at user headings.
- * Headings and content come back trimmed; reassemble with
- * `## ${heading}\n\n${content}` joined by blank lines.
- */
-export function splitStructural(body) {
-    const marks = [];
-    const re = /(^|\n)## ([^\n]*)/g;
-    let m;
-    while ((m = re.exec(body)) !== null) {
-        const heading = m[2].trim();
-        if (!STRUCTURAL_SECTIONS.has(heading))
-            continue;
-        marks.push({ start: m.index + m[1].length, contentStart: m.index + m[0].length, heading });
-    }
-    if (marks.length === 0)
-        return { preamble: body.trim(), sections: [] };
-    const preamble = body.slice(0, marks[0].start).trim();
-    const sections = marks.map((mk, i) => ({
-        heading: mk.heading,
-        content: body.slice(mk.contentStart, i + 1 < marks.length ? marks[i + 1].start : body.length).trim(),
-    }));
-    return { preamble, sections };
-}
-// --- Generic section mutation ---
-/**
- * Replace a structural section's content, or create the section: before
- * `insertBefore` when that section exists, at EOF otherwise.
- */
-export function setSection(body, heading, content, insertBefore) {
-    const existing = findSection(body, heading);
-    if (existing) {
-        return body.slice(0, existing.start) + `## ${heading}\n\n${content}\n` + body.slice(existing.end);
-    }
-    if (insertBefore) {
-        const target = findSection(body, insertBefore);
-        if (target) {
-            return body.slice(0, target.start) + `## ${heading}\n\n${content}\n\n` + body.slice(target.start);
-        }
-    }
-    return body + `\n\n## ${heading}\n\n${content}\n`;
-}
-/** Append content at the end of a structural section (creating it at EOF if absent). */
-export function appendToSection(body, heading, content) {
-    const section = findSection(body, heading);
-    if (!section)
-        return body + `\n\n## ${heading}\n\n${content}\n`;
-    if (section.end === body.length)
-        return body + '\n' + content + '\n';
-    return body.slice(0, section.end) + '\n' + content + body.slice(section.end);
-}
-/** Insert a formatted session-log entry newest-first (creating the section at EOF if absent). */
-export function prependSessionLogEntry(body, entry) {
-    const section = findSection(body, 'Session Log');
-    if (!section)
-        return body + `\n\n## Session Log\n\n${entry}\n`;
-    const insertPos = section.headingEnd;
-    return body.slice(0, insertPos) + '\n\n' + entry + '\n' + body.slice(insertPos);
-}
-/** Body up to the real Session Log section — the `summary` read depth. */
-export function bodyBeforeSessionLog(body) {
-    const section = findSection(body, 'Session Log');
-    return section ? body.slice(0, section.start).trim() : body;
-}
-// --- Session log parsing ---
+// --- Set-independent helpers ---
 const HEADING_RE = /^### (\d{4}-\d{2}-\d{2}) (?:—|--) (.+?)(?:\s+\[(\w+)\])?$/;
 export function parseSessionLogHeading(line) {
     const match = line.match(HEADING_RE);
@@ -147,120 +25,36 @@ export function parseSessionLogHeading(line) {
     };
 }
 export function formatSessionLogEntry(entry) {
-    const today = new Date().toISOString().slice(0, 10);
+    const today = localDay();
     const lines = [`### ${today} — ${entry.agent} [${entry.type}]`, `Summary: ${entry.summary}`];
     if (entry.body)
         lines.push(entry.body);
     return lines.join('\n');
 }
-/** Entries inside the real Session Log section only — entry-shaped lines
- * elsewhere in the body (e.g. quoted in a Brief) do not count. */
-export function countSessionLogEntries(body) {
-    const section = findSection(body, 'Session Log');
-    if (!section)
-        return 0;
-    return (section.content.match(/^### \d{4}-\d{2}-\d{2} (?:—|--)/gm) || []).length;
-}
-export function parseSessionLog(body) {
-    const section = findSection(body, 'Session Log');
-    if (!section)
-        return [];
-    const entries = [];
-    const lines = section.content.split('\n');
-    let current = null;
-    let summaryLine = null;
-    for (const line of lines) {
-        const heading = parseSessionLogHeading(line);
-        if (heading) {
-            if (current && summaryLine) {
-                entries.push({ ...current, summary: summaryLine });
-            }
-            current = heading;
-            summaryLine = null;
-        }
-        else if (current && !summaryLine && line.startsWith('Summary: ')) {
-            summaryLine = line.slice('Summary: '.length);
-        }
-    }
-    if (current && summaryLine) {
-        entries.push({ ...current, summary: summaryLine });
-    }
-    return entries;
-}
-export function extractOldestSessionLogEntry(body) {
-    const section = findSection(body, 'Session Log');
-    if (!section)
-        return null;
-    // Work on the raw slice between the heading and the section's structural
-    // end, so the extracted entry can never swallow a following section
-    // (e.g. an auto-appended Related) into the archive.
-    const contentStart = section.headingEnd;
-    const region = body.slice(contentStart, section.end);
-    const entryStarts = [...region.matchAll(/^### \d{4}-\d{2}-\d{2} (?:—|--)/gm)];
-    if (entryStarts.length < 2)
-        return null;
-    // Entries are newest-first in the file, so the oldest is the last match
-    const oldestStart = entryStarts[entryStarts.length - 1].index;
-    const entry = region.slice(oldestStart).trim();
-    const remaining = body.slice(0, contentStart) + region.slice(0, oldestStart) + body.slice(section.end);
-    return { entry, remaining };
-}
-// --- Section removal / insertion helpers (Brief, Next Actions) ---
 /**
- * Remove a section (heading + content) from body, cleaning up extra whitespace.
+ * Split a Session Log section's content into raw entry blocks, each beginning
+ * with a parseable entry heading. Non-entry text before the first heading is
+ * not an entry and is dropped. Document owns entry block splitting — merge's
+ * dedup/sort policy stays in merge.ts.
  */
-function removeSection(body, heading) {
-    const section = findSection(body, heading);
-    if (!section)
-        return body;
-    const before = body.slice(0, section.start);
-    const after = body.slice(section.end);
-    // Clean up: avoid triple+ newlines at the splice point
-    const trimmedBefore = before.replace(/\n+$/, '');
-    const trimmedAfter = after.replace(/^\n+/, '');
-    if (!trimmedBefore)
-        return trimmedAfter;
-    if (!trimmedAfter)
-        return trimmedBefore;
-    return trimmedBefore + '\n\n' + trimmedAfter;
+export function splitLogEntries(content) {
+    return content
+        .split(/\n(?=### \d{4}-\d{2}-\d{2})/)
+        .map(b => b.trim())
+        .filter(b => b && parseSessionLogHeading(b.split('\n')[0]) !== null);
 }
-/**
- * Insert a new section before a target heading, or at EOF.
- * `before` is an array of headings to try inserting before (first found wins).
- */
-function insertSectionBefore(body, heading, content, before) {
-    const sectionBlock = `## ${heading}\n\n${content}`;
-    for (const target of before) {
-        const targetSection = findSection(body, target);
-        if (targetSection) {
-            const insertPoint = targetSection.start;
-            const textBefore = body.slice(0, insertPoint).replace(/\n+$/, '');
-            const textAfter = body.slice(insertPoint);
-            if (!textBefore)
-                return sectionBlock + '\n\n' + textAfter;
-            return textBefore + '\n\n' + sectionBlock + '\n\n' + textAfter;
-        }
-    }
-    // No target found — append at EOF
-    const trimmed = body.replace(/\n+$/, '');
-    return trimmed + '\n\n' + sectionBlock;
+export function firstNonEmptyLine(s) {
+    return s?.split('\n').find(l => l.trim())?.trim() ?? '';
 }
-/**
- * Insert a new section after a target heading (and its content), or fall back to inserting before fallbacks.
- */
-function insertSectionAfter(body, heading, content, after, beforeFallbacks) {
-    const afterSection = findSection(body, after);
-    if (afterSection) {
-        const insertPoint = afterSection.end;
-        const textBefore = body.slice(0, insertPoint).replace(/\n+$/, '');
-        const textAfter = body.slice(insertPoint).replace(/^\n+/, '');
-        const sectionBlock = `## ${heading}\n\n${content}`;
-        if (!textAfter)
-            return textBefore + '\n\n' + sectionBlock;
-        return textBefore + '\n\n' + sectionBlock + '\n\n' + textAfter;
-    }
-    // After-target not found — fall back to insertBefore logic
-    return insertSectionBefore(body, heading, content, beforeFallbacks);
+/** The one wiki-link syntax the vault recognizes: [[slug]] or
+ * [[slug|display text]] — slug in group 1, display text in group 2.
+ * Padding inside the brackets is Obsidian-idiomatic ([[ slug ]], [[slug | Label]])
+ * and is absorbed by the pattern, so both captures come out already trimmed —
+ * every consumer (Related coverage, mention harvesting, export) sees the bare slug.
+ * Non-global — wrap with `new RegExp(WIKI_LINK_RE.source, 'g')` for iteration. */
+export const WIKI_LINK_RE = /\[\[\s*([^\]|]+?)\s*(?:\|\s*([^\]]+?)\s*)?\]\]/;
+function escapeRegex(s) {
+    return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 /**
  * Normalize text for matching: trim whitespace, replace smart quotes with
@@ -274,113 +68,494 @@ function normalizeForMatch(s) {
         .replace(/[“”]/g, '"')
         .replace(/—/g, '-');
 }
-/**
- * Match an action by case-insensitive substring against unchecked items.
- * Throws on 0 or >1 matches.
- */
-function matchAction(body, query) {
-    const section = findSection(body, 'Next Actions');
-    if (!section)
-        throw new Error(`No matching action for "${query}"`);
-    const normalizedQuery = normalizeForMatch(query).toLowerCase();
-    const matches = [];
-    const allActions = [];
-    let m;
-    const re = new RegExp(UNCHECKED_RE.source, 'gm');
-    while ((m = re.exec(section.content)) !== null) {
-        allActions.push(m[1]);
-        if (normalizeForMatch(m[1]).toLowerCase().includes(normalizedQuery)) {
-            matches.push(m[1]);
-        }
+const ENTITY_CONTRACTS = ALL_CONTRACTS.filter(c => c.kind === 'item');
+function sectionNamesFor(ctx) {
+    if (ctx.kind === 'session')
+        return [...SESSION_SECTIONS];
+    if (ctx.kind === 'knowledge') {
+        const subtypeTable = SUBTYPE_SECTIONS;
+        const names = [...getContract('knowledge').defaultSections];
+        for (const s of Object.keys(subtypeTable))
+            names.push(...subtypeTable[s]);
+        return names;
     }
-    if (matches.length === 0) {
-        throw new Error(`No matching action for "${query}". Actions: ${JSON.stringify(allActions)}`);
-    }
-    if (matches.length > 1)
-        throw new Error(`Ambiguous match for "${query}": ${matches.join(', ')}`);
-    return matches[0];
+    return ENTITY_CONTRACTS.flatMap(c => [...c.defaultSections, ...c.optionalSections]);
 }
-// --- Brief functions ---
-export function getBrief(body) {
-    const section = findSection(body, 'Brief');
-    if (!section)
-        return null;
-    return section.content || null;
+/** The structural set a context binds — exposed for introspection and the
+ * contract-coverage tests; runtime consumers go through documentFor. */
+export function structuralSectionsFor(ctx) {
+    return new Set([...sectionNamesFor(ctx), 'Related']);
 }
-export function setBrief(body, content) {
-    const existing = findSection(body, 'Brief');
-    if (existing) {
-        // Replace existing brief content
-        const updated = removeSection(body, 'Brief');
-        return setBrief(updated, content);
+const docCache = new Map();
+/** The Document operations bound to one file's structural section set. */
+export function documentFor(ctx) {
+    const key = ctx.kind;
+    let doc = docCache.get(key);
+    if (!doc) {
+        doc = makeDoc(new Set(structuralSectionsFor(ctx)));
+        docCache.set(key, doc);
     }
-    // Insert before: Next Actions > Current State > Session Log > EOF
-    return insertSectionBefore(body, 'Brief', content, ['Next Actions', 'Current State', 'Session Log']);
+    return doc;
 }
-export function removeBrief(body) {
-    return removeSection(body, 'Brief');
+/** Bind from a parsed vault file — kind from Layout. */
+export function documentForFile(parsed) {
+    return documentFor({ kind: parsed.kind });
 }
-// --- Next Actions functions ---
-export function getNextActions(body) {
-    const section = findSection(body, 'Next Actions');
-    if (!section)
-        return [];
-    const actions = [];
-    let m;
-    const re = new RegExp(UNCHECKED_RE.source, 'gm');
-    while ((m = re.exec(section.content)) !== null) {
-        actions.push(m[1]);
+// --- The bound implementation ---
+function makeDoc(structuralSections) {
+    /**
+     * Find the next structural `## Heading` boundary after a given position.
+     * Skips `## ` headings that are not known structural sections (content headings).
+     * Returns the index of the `\n` before the `## `, or -1 if no structural heading found.
+     */
+    function findNextStructuralHeading(body, from) {
+        const re = /\n## ([^\n]+)/g;
+        re.lastIndex = from;
+        let match;
+        while ((match = re.exec(body)) !== null) {
+            const headingName = match[1].trim();
+            if (structuralSections.has(headingName)) {
+                return match.index;
+            }
+        }
+        return -1;
     }
-    return actions;
-}
-export function addNextAction(body, action) {
-    const section = findSection(body, 'Next Actions');
-    if (section) {
-        // Add the new item at the end of unchecked items (before any checked items)
+    /**
+     * Find a ## Heading section and its content.
+     * Returns { start, headingEnd, end, content } or null if not found.
+     * Matches heading exactly (e.g. "## Brief" won't match "## Briefing").
+     * Trailing whitespace on the heading line is tolerated — the splitter's
+     * boundary tokenizer trims headings, so anything it treats as a boundary
+     * must also be findable here (a hand-edited `## Session Log ` otherwise
+     * gets a duplicate section and archival never fires).
+     * Only treats known structural headings as section boundaries -- content
+     * inside a section may contain arbitrary `## ` headings without corruption.
+     */
+    function findSection(body, heading) {
+        const re = new RegExp(`(^|\\n)(## ${escapeRegex(heading)}[ \\t]*)(?:\\n|$)`);
+        const match = re.exec(body);
+        if (!match)
+            return null;
+        const start = match.index + match[1].length;
+        const headingEnd = start + match[2].length;
+        const afterHeading = headingEnd + 1;
+        // Find the next structural ## heading or EOF. Scan from the heading's own
+        // trailing newline (afterHeading - 1), not past it — otherwise a structural
+        // heading on the immediately following line (no blank line between, as in
+        // hand-edited files) is invisible and mutators swallow the next section.
+        const nextHeading = findNextStructuralHeading(body, Math.max(0, afterHeading - 1));
+        const end = nextHeading === -1 ? body.length : nextHeading;
+        const rawContent = body.slice(afterHeading, end);
+        const content = rawContent.replace(/^\n+/, '').replace(/\n+$/, '');
+        return { start, headingEnd, end, content };
+    }
+    /**
+     * Split a body into preamble + structural sections. Non-structural `## `
+     * headings stay inside the enclosing section's content — sections are
+     * atomic units of authored content, never split at user headings.
+     * Headings and content come back trimmed; reassemble with
+     * `## ${heading}\n\n${content}` joined by blank lines.
+     */
+    function splitStructural(body) {
+        const marks = [];
+        const re = /(^|\n)## ([^\n]*)/g;
+        let m;
+        while ((m = re.exec(body)) !== null) {
+            const heading = m[2].trim();
+            if (!structuralSections.has(heading))
+                continue;
+            marks.push({ start: m.index + m[1].length, contentStart: m.index + m[0].length, heading });
+        }
+        if (marks.length === 0)
+            return { preamble: body.trim(), sections: [] };
+        const preamble = body.slice(0, marks[0].start).trim();
+        const sections = marks.map((mk, i) => ({
+            heading: mk.heading,
+            content: body.slice(mk.contentStart, i + 1 < marks.length ? marks[i + 1].start : body.length).trim(),
+        }));
+        return { preamble, sections };
+    }
+    /**
+     * Replace a structural section's content, or create the section: before
+     * `insertBefore` when that section exists, at EOF otherwise.
+     */
+    function setSection(body, heading, content, insertBefore) {
+        const existing = findSection(body, heading);
+        if (existing) {
+            return body.slice(0, existing.start) + `## ${heading}\n\n${content}\n` + body.slice(existing.end);
+        }
+        if (insertBefore) {
+            const target = findSection(body, insertBefore);
+            if (target) {
+                return body.slice(0, target.start) + `## ${heading}\n\n${content}\n\n` + body.slice(target.start);
+            }
+        }
+        return body + `\n\n## ${heading}\n\n${content}\n`;
+    }
+    /** Append content at the end of a structural section (creating it at EOF if absent). */
+    function appendToSection(body, heading, content) {
+        const section = findSection(body, heading);
+        if (!section)
+            return body + `\n\n## ${heading}\n\n${content}\n`;
+        if (section.end === body.length)
+            return body + '\n' + content + '\n';
+        return body.slice(0, section.end) + '\n' + content + body.slice(section.end);
+    }
+    /**
+     * Rename a structural section's heading in place, keeping its content.
+     * No-op when the section is absent. Any trailing whitespace on the old
+     * heading line is dropped with it.
+     */
+    function renameSection(body, from, to) {
+        const section = findSection(body, from);
+        if (!section)
+            return body;
+        return body.slice(0, section.start) + `## ${to}` + body.slice(section.headingEnd);
+    }
+    /**
+     * Ensure a structural section exists: no-op when present, otherwise insert
+     * an empty section after `opts.after` (when that section exists) or at EOF.
+     */
+    function ensureSection(body, heading, opts = {}) {
+        if (findSection(body, heading))
+            return body;
+        const block = `## ${heading}`;
+        if (opts.after) {
+            const anchor = findSection(body, opts.after);
+            if (anchor) {
+                const before = body.slice(0, anchor.end).replace(/\n+$/, '');
+                const after = body.slice(anchor.end).replace(/^\n+/, '');
+                return after ? `${before}\n\n${block}\n\n${after}` : `${before}\n\n${block}\n`;
+            }
+        }
+        return body.replace(/\n+$/, '') + `\n\n${block}\n`;
+    }
+    /** Insert a formatted session-log entry newest-first (creating the section at EOF if absent). */
+    function prependSessionLogEntry(body, entry) {
+        const section = findSection(body, 'Session Log');
+        if (!section)
+            return body + `\n\n## Session Log\n\n${entry}\n`;
+        const insertPos = section.headingEnd;
+        return body.slice(0, insertPos) + '\n\n' + entry + '\n' + body.slice(insertPos);
+    }
+    /** Body up to the real Session Log section — the `summary` read depth. */
+    function bodyBeforeSessionLog(body) {
+        const section = findSection(body, 'Session Log');
+        return section ? body.slice(0, section.start).trim() : body;
+    }
+    /** Entries inside the real Session Log section only — entry-shaped lines
+     * elsewhere in the body (e.g. quoted in a Brief) do not count. */
+    function countSessionLogEntries(body) {
+        const section = findSection(body, 'Session Log');
+        if (!section)
+            return 0;
+        return (section.content.match(/^### \d{4}-\d{2}-\d{2} (?:—|--)/gm) || []).length;
+    }
+    function parseSessionLog(body) {
+        const section = findSection(body, 'Session Log');
+        if (!section)
+            return [];
+        const entries = [];
         const lines = section.content.split('\n');
-        const lastUncheckedIdx = lines.reduce((last, line, i) => line.startsWith('- [ ] ') ? i : last, -1);
-        const insertIdx = lastUncheckedIdx === -1 ? 0 : lastUncheckedIdx + 1;
-        lines.splice(insertIdx, 0, `- [ ] ${action}`);
-        const newContent = lines.join('\n');
-        const before = body.slice(0, section.start).replace(/\n+$/, '');
-        const after = body.slice(section.end).replace(/^\n+/, '');
-        const sectionBlock = `## Next Actions\n\n${newContent}`;
-        const parts = [before, sectionBlock, after].filter(Boolean);
-        return parts.join('\n\n');
+        let current = null;
+        let summaryLine = null;
+        for (const line of lines) {
+            const heading = parseSessionLogHeading(line);
+            if (heading) {
+                if (current && summaryLine) {
+                    entries.push({ ...current, summary: summaryLine });
+                }
+                current = heading;
+                summaryLine = null;
+            }
+            else if (current && !summaryLine && line.startsWith('Summary: ')) {
+                summaryLine = line.slice('Summary: '.length);
+            }
+        }
+        if (current && summaryLine) {
+            entries.push({ ...current, summary: summaryLine });
+        }
+        return entries;
     }
-    // No section — insert after Brief if present, otherwise before Session Log
-    return insertSectionAfter(body, 'Next Actions', `- [ ] ${action}`, 'Brief', ['Session Log']);
-}
-export function completeNextAction(body, query) {
-    const matched = matchAction(body, query);
-    // Replace the unchecked item with checked
-    const updatedBody = body.replace(`- [ ] ${matched}`, `- [x] ${matched}`);
-    // Check if any unchecked items remain
-    const remaining = getNextActions(updatedBody);
-    if (remaining.length === 0) {
-        return { matched, body: clearNextActions(updatedBody) };
+    function extractOldestSessionLogEntry(body) {
+        const section = findSection(body, 'Session Log');
+        if (!section)
+            return null;
+        // Work on the raw slice between the heading and the section's structural
+        // end, so the extracted entry can never swallow a following section
+        // (e.g. an auto-appended Related) into the archive.
+        const contentStart = section.headingEnd;
+        const region = body.slice(contentStart, section.end);
+        const entryStarts = [...region.matchAll(/^### \d{4}-\d{2}-\d{2} (?:—|--)/gm)];
+        if (entryStarts.length < 2)
+            return null;
+        // Entries are newest-first in the file, so the oldest is the last match
+        const oldestStart = entryStarts[entryStarts.length - 1].index;
+        const entry = region.slice(oldestStart).trim();
+        const remaining = body.slice(0, contentStart) + region.slice(0, oldestStart) + body.slice(section.end);
+        return { entry, remaining };
     }
-    return { matched, body: updatedBody };
-}
-export function removeNextAction(body, query) {
-    const matched = matchAction(body, query);
-    // Remove the line
-    const line = `- [ ] ${matched}`;
-    const updatedBody = body.split('\n').filter(l => l !== line).join('\n');
-    // Check if any unchecked items remain
-    const remaining = getNextActions(updatedBody);
-    if (remaining.length === 0) {
-        return { matched, body: clearNextActions(updatedBody) };
+    /**
+     * Remove a section (heading + content) from body, cleaning up extra whitespace.
+     */
+    function removeSection(body, heading) {
+        const section = findSection(body, heading);
+        if (!section)
+            return body;
+        const before = body.slice(0, section.start);
+        const after = body.slice(section.end);
+        // Clean up: avoid triple+ newlines at the splice point
+        const trimmedBefore = before.replace(/\n+$/, '');
+        const trimmedAfter = after.replace(/^\n+/, '');
+        if (!trimmedBefore)
+            return trimmedAfter;
+        if (!trimmedAfter)
+            return trimmedBefore;
+        return trimmedBefore + '\n\n' + trimmedAfter;
+    }
+    /**
+     * Insert a new section before a target heading, or at EOF.
+     * `before` is an array of headings to try inserting before (first found wins).
+     */
+    function insertSectionBefore(body, heading, content, before) {
+        const sectionBlock = `## ${heading}\n\n${content}`;
+        for (const target of before) {
+            const targetSection = findSection(body, target);
+            if (targetSection) {
+                const insertPoint = targetSection.start;
+                const textBefore = body.slice(0, insertPoint).replace(/\n+$/, '');
+                const textAfter = body.slice(insertPoint);
+                if (!textBefore)
+                    return sectionBlock + '\n\n' + textAfter;
+                return textBefore + '\n\n' + sectionBlock + '\n\n' + textAfter;
+            }
+        }
+        // No target found — append at EOF
+        const trimmed = body.replace(/\n+$/, '');
+        return trimmed + '\n\n' + sectionBlock;
+    }
+    /**
+     * Insert a new section after a target heading (and its content), or fall back to inserting before fallbacks.
+     */
+    function insertSectionAfter(body, heading, content, after, beforeFallbacks) {
+        const afterSection = findSection(body, after);
+        if (afterSection) {
+            const insertPoint = afterSection.end;
+            const textBefore = body.slice(0, insertPoint).replace(/\n+$/, '');
+            const textAfter = body.slice(insertPoint).replace(/^\n+/, '');
+            const sectionBlock = `## ${heading}\n\n${content}`;
+            if (!textAfter)
+                return textBefore + '\n\n' + sectionBlock;
+            return textBefore + '\n\n' + sectionBlock + '\n\n' + textAfter;
+        }
+        // After-target not found — fall back to insertBefore logic
+        return insertSectionBefore(body, heading, content, beforeFallbacks);
+    }
+    /**
+     * Match an action by case-insensitive substring against unchecked items.
+     * Throws on 0 or >1 matches.
+     */
+    function matchAction(body, query) {
+        const section = findSection(body, 'Next Actions');
+        if (!section)
+            throw new Error(`No matching action for "${query}"`);
+        const normalizedQuery = normalizeForMatch(query).toLowerCase();
+        const matches = [];
+        const allActions = [];
+        let m;
+        const re = new RegExp(UNCHECKED_RE.source, 'gm');
+        while ((m = re.exec(section.content)) !== null) {
+            allActions.push(m[1]);
+            if (normalizeForMatch(m[1]).toLowerCase().includes(normalizedQuery)) {
+                matches.push(m[1]);
+            }
+        }
+        if (matches.length === 0) {
+            throw new Error(`No matching action for "${query}". Actions: ${JSON.stringify(allActions)}`);
+        }
+        if (matches.length > 1)
+            throw new Error(`Ambiguous match for "${query}": ${matches.join(', ')}`);
+        return matches[0];
+    }
+    // --- Brief functions ---
+    function getBrief(body) {
+        const section = findSection(body, 'Brief');
+        if (!section)
+            return null;
+        return section.content || null;
+    }
+    function setBrief(body, content) {
+        const existing = findSection(body, 'Brief');
+        if (existing) {
+            // Replace existing brief content
+            const updated = removeSection(body, 'Brief');
+            return setBrief(updated, content);
+        }
+        // Insert before: Next Actions > Current State > Session Log > EOF
+        return insertSectionBefore(body, 'Brief', content, ['Next Actions', 'Current State', 'Session Log']);
+    }
+    function removeBrief(body) {
+        return removeSection(body, 'Brief');
+    }
+    // --- Next Actions functions ---
+    function getNextActions(body) {
+        const section = findSection(body, 'Next Actions');
+        if (!section)
+            return [];
+        const actions = [];
+        let m;
+        const re = new RegExp(UNCHECKED_RE.source, 'gm');
+        while ((m = re.exec(section.content)) !== null) {
+            actions.push(m[1]);
+        }
+        return actions;
     }
-    return { matched, body: updatedBody };
+    function addNextAction(body, action) {
+        const section = findSection(body, 'Next Actions');
+        if (section) {
+            // Add the new item at the end of unchecked items (before any checked items)
+            const lines = section.content.split('\n');
+            const lastUncheckedIdx = lines.reduce((last, line, i) => line.startsWith('- [ ] ') ? i : last, -1);
+            const insertIdx = lastUncheckedIdx === -1 ? 0 : lastUncheckedIdx + 1;
+            lines.splice(insertIdx, 0, `- [ ] ${action}`);
+            const newContent = lines.join('\n');
+            const before = body.slice(0, section.start).replace(/\n+$/, '');
+            const after = body.slice(section.end).replace(/^\n+/, '');
+            const sectionBlock = `## Next Actions\n\n${newContent}`;
+            const parts = [before, sectionBlock, after].filter(Boolean);
+            return parts.join('\n\n');
+        }
+        // No section — insert after Brief if present, otherwise before Session Log
+        return insertSectionAfter(body, 'Next Actions', `- [ ] ${action}`, 'Brief', ['Session Log']);
+    }
+    /**
+     * Edit the matched action's line inside the Next Actions section only.
+     * Matching was always section-scoped; editing must be too — an identical
+     * checkbox line quoted elsewhere in the body (a Brief restating a blocker)
+     * is authored content, not an action. Works on the section's raw slice and
+     * on whole lines, so action text is never interpreted as a replacement
+     * pattern ($&, $', $1 survive byte-identical).
+     */
+    function editActionLine(body, matched, edit) {
+        const section = findSection(body, 'Next Actions');
+        if (!section)
+            return body;
+        const lines = body.slice(section.headingEnd, section.end).split('\n');
+        const idx = lines.indexOf(`- [ ] ${matched}`);
+        if (idx === -1)
+            return body;
+        edit(lines, idx);
+        return body.slice(0, section.headingEnd) + lines.join('\n') + body.slice(section.end);
+    }
+    function completeNextAction(body, query) {
+        const matched = matchAction(body, query);
+        // Replace the unchecked item with checked
+        const updatedBody = editActionLine(body, matched, (lines, i) => { lines[i] = `- [x] ${matched}`; });
+        // Check if any unchecked items remain
+        const remaining = getNextActions(updatedBody);
+        if (remaining.length === 0) {
+            return { matched, body: clearNextActions(updatedBody) };
+        }
+        return { matched, body: updatedBody };
+    }
+    function removeNextAction(body, query) {
+        const matched = matchAction(body, query);
+        // Remove the line
+        const updatedBody = editActionLine(body, matched, (lines, i) => { lines.splice(i, 1); });
+        // Check if any unchecked items remain
+        const remaining = getNextActions(updatedBody);
+        if (remaining.length === 0) {
+            return { matched, body: clearNextActions(updatedBody) };
+        }
+        return { matched, body: updatedBody };
+    }
+    function clearNextActions(body) {
+        return removeSection(body, 'Next Actions');
+    }
+    // --- Related section sync ---
+    function syncRelatedSection(body, frontmatter) {
+        const targets = [];
+        if (frontmatter.parent)
+            targets.push({ slug: frontmatter.parent, label: 'parent' });
+        for (const slug of frontmatter.related ?? [])
+            targets.push({ slug });
+        if (targets.length === 0) {
+            // No frontmatter links — remove Related section if present
+            const existing = findSection(body, 'Related');
+            if (!existing)
+                return body;
+            const before = body.slice(0, existing.start).replace(/\n+$/, '');
+            const after = body.slice(existing.end).replace(/^\n+/, '');
+            return [before, after].filter(Boolean).join('\n\n');
+        }
+        // Strip existing Related section before checking coverage
+        let authoredBody = body;
+        const existingRelated = findSection(body, 'Related');
+        if (existingRelated) {
+            const before = body.slice(0, existingRelated.start);
+            const after = body.slice(existingRelated.end);
+            authoredBody = (before + after).replace(/\n{3,}/g, '\n\n');
+        }
+        // Find which targets are NOT mentioned in authored body
+        const mentionedSlugs = new Set();
+        let match;
+        const re = new RegExp(WIKI_LINK_RE.source, 'g');
+        while ((match = re.exec(authoredBody)) !== null) {
+            mentionedSlugs.add(match[1]);
+        }
+        const uncovered = targets.filter(t => !mentionedSlugs.has(t.slug));
+        if (uncovered.length === 0) {
+            // All covered inline — return body without Related section
+            return authoredBody.replace(/\n+$/, '');
+        }
+        // Build Related section
+        const lines = uncovered.map(t => t.label ? `- [[${t.slug}]] (${t.label})` : `- [[${t.slug}]]`);
+        const section = `## Related\n\n${lines.join('\n')}`;
+        // Append at end
+        return authoredBody.replace(/\n+$/, '') + '\n\n' + section;
+    }
+    return {
+        findNextStructuralHeading,
+        findSection,
+        splitStructural,
+        setSection,
+        appendToSection,
+        renameSection,
+        ensureSection,
+        prependSessionLogEntry,
+        bodyBeforeSessionLog,
+        countSessionLogEntries,
+        parseSessionLog,
+        extractOldestSessionLogEntry,
+        getBrief,
+        setBrief,
+        removeBrief,
+        getNextActions,
+        addNextAction,
+        completeNextAction,
+        removeNextAction,
+        clearNextActions,
+        syncRelatedSection,
+    };
+}
+// --- Entity-bound convenience exports (public API) ---
+// getBrief / getNextActions / parseSessionLog are read-only accessors on
+// entity bodies; they bind the entity Document (Brief, Next Actions, and
+// Session Log only exist on entity kinds).
+const ENTITY_UNION_DOC = documentFor({ kind: 'entity' });
+export function getBrief(body) {
+    return ENTITY_UNION_DOC.getBrief(body);
 }
-export function clearNextActions(body) {
-    return removeSection(body, 'Next Actions');
+export function getNextActions(body) {
+    return ENTITY_UNION_DOC.getNextActions(body);
 }
-// --- Summary derivation ---
-export function firstNonEmptyLine(s) {
-    return s?.split('\n').find(l => l.trim())?.trim() ?? '';
+export function parseSessionLog(body) {
+    return ENTITY_UNION_DOC.parseSessionLog(body);
+}
+export function countSessionLogEntries(body) {
+    return ENTITY_UNION_DOC.countSessionLogEntries(body);
 }
+// --- Summary derivation ---
 /**
  * One-line summary for a doc: frontmatter description first, then the first
  * non-empty line of the kind's primary section (entity: Brief; knowledge:
@@ -390,59 +565,14 @@ export function firstNonEmptyLine(s) {
 export function deriveSummary(kind, fm, body) {
     if (fm.description)
         return fm.description;
+    const doc = documentFor({ kind });
     if (kind === 'entity')
-        return firstNonEmptyLine(getBrief(body));
+        return firstNonEmptyLine(doc.getBrief(body));
     if (kind === 'knowledge') {
-        const synthesis = findSection(body, 'Synthesis');
+        const synthesis = doc.findSection(body, 'Synthesis');
         if (synthesis?.content)
             return firstNonEmptyLine(synthesis.content);
-        return firstNonEmptyLine(findSection(body, 'Goal')?.content);
-    }
-    return firstNonEmptyLine(findSection(body, 'Summary')?.content);
-}
-// --- Wiki-links ---
-/** The one wiki-link syntax the vault recognizes: [[slug]] or
- * [[slug|display text]] — slug in group 1, display text in group 2.
- * Non-global — wrap with `new RegExp(WIKI_LINK_RE.source, 'g')` for iteration. */
-export const WIKI_LINK_RE = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/;
-export function syncRelatedSection(body, frontmatter) {
-    const targets = [];
-    if (frontmatter.parent)
-        targets.push({ slug: frontmatter.parent, label: 'parent' });
-    for (const slug of frontmatter.related ?? [])
-        targets.push({ slug });
-    if (targets.length === 0) {
-        // No frontmatter links — remove Related section if present
-        const existing = findSection(body, 'Related');
-        if (!existing)
-            return body;
-        const before = body.slice(0, existing.start).replace(/\n+$/, '');
-        const after = body.slice(existing.end).replace(/^\n+/, '');
-        return [before, after].filter(Boolean).join('\n\n');
-    }
-    // Strip existing Related section before checking coverage
-    let authoredBody = body;
-    const existingRelated = findSection(body, 'Related');
-    if (existingRelated) {
-        const before = body.slice(0, existingRelated.start);
-        const after = body.slice(existingRelated.end);
-        authoredBody = (before + after).replace(/\n{3,}/g, '\n\n');
-    }
-    // Find which targets are NOT mentioned in authored body
-    const mentionedSlugs = new Set();
-    let match;
-    const re = new RegExp(WIKI_LINK_RE.source, 'g');
-    while ((match = re.exec(authoredBody)) !== null) {
-        mentionedSlugs.add(match[1]);
-    }
-    const uncovered = targets.filter(t => !mentionedSlugs.has(t.slug));
-    if (uncovered.length === 0) {
-        // All covered inline — return body without Related section
-        return authoredBody.replace(/\n+$/, '');
+        return firstNonEmptyLine(doc.findSection(body, 'Goal')?.content);
     }
-    // Build Related section
-    const lines = uncovered.map(t => t.label ? `- [[${t.slug}]] (${t.label})` : `- [[${t.slug}]]`);
-    const section = `## Related\n\n${lines.join('\n')}`;
-    // Append at end
-    return authoredBody.replace(/\n+$/, '') + '\n\n' + section;
+    return firstNonEmptyLine(doc.findSection(body, 'Summary')?.content);
 }