@plebeiantech/lat.md 0.12.3-fork.2 → 0.12.3-fork.20

package/dist/src/fork/upstream-guard.js

@@ -0,0 +1,445 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, readFileSync, writeFileSync } from 'node:fs';
+import { isAbsolute, resolve } from 'node:path';
+// @lat: [[upstream-guard#The upstream guard]]
+export const SYNC_POINT_FILE = 'fork-upstream-sync-point';
+/**
+ * The commit this fork was originally cut from. It is not the guard's
+ * baseline — see [[upstream-guard#The upstream guard#The sync point]] for why a frozen
+ * one cannot tell the fork's changes from upstream's.
+ */
+export const ORIGINAL_FORK_POINT = '65d2f5b220853b2b10dca3de18d511f575bc12c7';
+// @lat: [[upstream-guard#The upstream guard#The allowlist]]
+export const ALLOWLIST_FILE = 'fork-upstream-allowlist.tsv';
+export const REASON_PLACEHOLDER = 'TODO';
+const ALLOWLIST_HEADER = [
+    '# Upstream files this fork is permitted to modify.',
+    '#',
+    '# Generated by `node dist/src/fork/upstream-guard-cli.js --regenerate`.',
+    '# One entry per line: the repo-relative path, a TAB, then the reason the',
+    '# fork must diverge in that file. A placeholder reason fails the check —',
+    '# regenerate writes the marker, a person replaces it with the real reason.',
+    '#',
+    '# Paths are relative to the sync point in fork-upstream-sync-point, so an',
+    '# upstream merge moves this list. Regenerate in the same commit.',
+    '#',
+    '# Deleting an upstream file is never allowlistable. See lat.md/fork.md.',
+    '',
+];
+export function parseAllowlist(text) {
+    const entries = [];
+    const errors = [];
+    const seen = new Map();
+    text.split('\n').forEach((raw, index) => {
+        const line = index + 1;
+        const stripped = raw.replace(/\r$/, '');
+        if (stripped.trim() === '' || stripped.trimStart().startsWith('#'))
+            return;
+        const tab = stripped.indexOf('\t');
+        const split = tab >= 0 ? tab : stripped.search(/\s/);
+        if (split < 0) {
+            errors.push(`${ALLOWLIST_FILE}:${line}: entry has no reason: ${stripped}`);
+            return;
+        }
+        const path = stripped.slice(0, split).trim();
+        const reason = stripped.slice(split + 1).trim();
+        if (path === '') {
+            errors.push(`${ALLOWLIST_FILE}:${line}: entry has no path`);
+            return;
+        }
+        if (reason === '') {
+            errors.push(`${ALLOWLIST_FILE}:${line}: entry has no reason: ${path}`);
+            return;
+        }
+        const first = seen.get(path);
+        if (first !== undefined) {
+            errors.push(`${ALLOWLIST_FILE}:${line}: duplicate entry for ${path} ` +
+                `(first at line ${first})`);
+            return;
+        }
+        seen.set(path, line);
+        entries.push({ path, reason, line });
+    });
+    return { entries, errors };
+}
+export function renderAllowlist(entries) {
+    const sorted = [...entries].sort((a, b) => (a.path < b.path ? -1 : 1));
+    const body = sorted.map((e) => `${e.path}\t${e.reason}`);
+    return [...ALLOWLIST_HEADER, ...body, ''].join('\n');
+}
+export function needsReason(reason) {
+    return reason.trimStart().toUpperCase().startsWith(REASON_PLACEHOLDER);
+}
+export function parseNameStatus(raw) {
+    const fields = raw.split('\0').filter((f) => f !== '');
+    const out = [];
+    for (let i = 0; i + 1 < fields.length; i += 2) {
+        out.push({ status: fields[i], path: fields[i + 1] });
+    }
+    return out;
+}
+export function classify(input) {
+    const findings = [];
+    const touched = [];
+    for (const entry of input.diff) {
+        if (!input.upstream.has(entry.path))
+            continue;
+        touched.push(entry.path);
+        if (entry.status.startsWith('D')) {
+            findings.push({
+                kind: 'deletion',
+                path: entry.path,
+                message: `${entry.path}: deletes an upstream file.\n` +
+                    '    No allowlist entry can permit this. A file this fork deletes ' +
+                    'conflicts on\n' +
+                    '    every future merge that touches it upstream; a file this fork ' +
+                    'modifies\n' +
+                    '    conflicts once and stays resolved. Leave the file in place and ' +
+                    'change\n' +
+                    '    what it does, or turn it off out of band.',
+            });
+            continue;
+        }
+        const reason = input.allowlist.get(entry.path);
+        if (reason === undefined) {
+            findings.push({
+                kind: 'unallowlisted',
+                path: entry.path,
+                message: `${entry.path}: modifies an upstream file that is not allowlisted.\n` +
+                    '    Move the change into a new fork-owned file, or add the path to ' +
+                    `${ALLOWLIST_FILE}\n` +
+                    '    with the reason the fork must diverge here.',
+            });
+            continue;
+        }
+        if (needsReason(reason)) {
+            findings.push({
+                kind: 'missing-reason',
+                path: entry.path,
+                message: `${entry.path}: allowlisted with a placeholder reason.\n` +
+                    `    Replace the ${REASON_PLACEHOLDER} in ${ALLOWLIST_FILE} with why ` +
+                    'this file must diverge.',
+            });
+        }
+    }
+    const touchedSet = new Set(touched);
+    const warnings = [];
+    for (const path of input.allowlist.keys()) {
+        if (!touchedSet.has(path)) {
+            warnings.push(`${path}: allowlisted but no longer modified — regenerate to drop it.`);
+        }
+    }
+    return { findings, warnings, touched };
+}
+function git(repo, args, stdin) {
+    const result = spawnSync('git', ['-C', repo, ...args], {
+        input: stdin,
+        encoding: 'utf-8',
+        maxBuffer: 64 * 1024 * 1024,
+    });
+    if (result.error)
+        throw result.error;
+    return result;
+}
+export function repoRoot(from) {
+    const result = git(from, ['rev-parse', '--show-toplevel']);
+    if (result.status !== 0) {
+        throw new Error(`not a git repository: ${from}`);
+    }
+    return result.stdout.trim();
+}
+export function hasCommit(repo, rev) {
+    return git(repo, ['cat-file', '-e', `${rev}^{commit}`]).status === 0;
+}
+export function diffAgainst(repo, rev) {
+    const result = git(repo, [
+        'diff',
+        '--no-renames',
+        '--name-status',
+        '-z',
+        rev,
+        '--',
+    ]);
+    if (result.status !== 0) {
+        throw new Error(`git diff against ${rev} failed: ${result.stderr.trim()}`);
+    }
+    return parseNameStatus(result.stdout);
+}
+export function upstreamPaths(repo, rev, paths) {
+    const out = new Set();
+    if (paths.length === 0)
+        return out;
+    const batchable = paths.filter((p) => !p.includes('\n'));
+    const input = batchable.map((p) => `${rev}:${p}`).join('\n') + '\n';
+    const result = git(repo, ['cat-file', '--batch-check'], input);
+    const lines = result.stdout.split('\n').filter((l) => l !== '');
+    const aligned = lines.length === batchable.length;
+    if (aligned) {
+        lines.forEach((line, index) => {
+            if (/ blob \d+$/.test(line))
+                out.add(batchable[index]);
+        });
+    }
+    const leftover = aligned ? paths.filter((p) => p.includes('\n')) : paths;
+    for (const path of leftover) {
+        const probe = git(repo, ['cat-file', '-t', `${rev}:${path}`]);
+        if (probe.status === 0 && probe.stdout.trim() === 'blob')
+            out.add(path);
+    }
+    return out;
+}
+// @lat: [[upstream-guard#The upstream guard#The sync point]]
+export function parseSyncPoint(text) {
+    for (const raw of text.split('\n')) {
+        const line = raw.replace(/\r$/, '').trim();
+        if (line === '' || line.startsWith('#'))
+            continue;
+        return line.split(/\s/)[0];
+    }
+    return undefined;
+}
+export function renderSyncPoint(previous, rev) {
+    const kept = previous
+        .split('\n')
+        .filter((raw) => {
+        const line = raw.replace(/\r$/, '').trim();
+        return line === '' || line.startsWith('#');
+    })
+        .join('\n')
+        .replace(/\n+$/, '');
+    return `${kept}\n\n${rev}\n`;
+}
+export function isAncestorOfHead(repo, rev) {
+    return git(repo, ['merge-base', '--is-ancestor', rev, 'HEAD']).status === 0;
+}
+export function isShallow(repo) {
+    const result = git(repo, ['rev-parse', '--is-shallow-repository']);
+    return result.stdout.trim() === 'true';
+}
+// @lat: [[upstream-guard#The upstream guard#Running it in CI]]
+export function fetchSyncPoint(repo, rev) {
+    const result = git(repo, ['fetch', '--no-tags', '--depth=1', 'origin', rev]);
+    return result.status === 0 && hasCommit(repo, rev);
+}
+function pathFor(repo, file) {
+    return isAbsolute(file) ? file : resolve(repo, file);
+}
+function allowlistPathFor(options) {
+    return pathFor(options.repo, options.allowlistFile);
+}
+function syncPointPathFor(options) {
+    return pathFor(options.repo, options.syncPointFile ?? SYNC_POINT_FILE);
+}
+function loadAllowlist(file) {
+    if (!existsSync(file))
+        return { entries: [], errors: [] };
+    return parseAllowlist(readFileSync(file, 'utf-8'));
+}
+function fail(report) {
+    return { ok: false, report, findings: [], warnings: [] };
+}
+export function runGuard(options) {
+    const root = repoRoot(options.repo);
+    const opts = { ...options, repo: root };
+    const syncFile = syncPointPathFor(opts);
+    if (opts.setSyncPoint !== undefined) {
+        return recordSyncPoint(root, syncFile, opts.setSyncPoint);
+    }
+    let syncPoint = opts.syncPoint;
+    if (syncPoint === undefined) {
+        if (!existsSync(syncFile)) {
+            return fail(`upstream-guard: no sync point recorded at ${syncFile}\n` +
+                '    The guard measures everything from the last upstream commit ' +
+                'merged\n' +
+                '    into this fork. Record it:\n' +
+                '      node dist/src/fork/upstream-guard-cli.js --set-sync-point ' +
+                '<rev>\n');
+        }
+        syncPoint = parseSyncPoint(readFileSync(syncFile, 'utf-8'));
+        if (syncPoint === undefined || syncPoint === '') {
+            return fail(`upstream-guard: ${syncFile} holds no revision.\n` +
+                '    It must contain one commit id on a line of its own.\n');
+        }
+    }
+    const present = hasCommit(root, syncPoint) ||
+        (opts.fetch && fetchSyncPoint(root, syncPoint));
+    if (!present) {
+        return fail(`upstream-guard: sync point ${syncPoint} is not in this repository.\n` +
+            '    A shallow clone does not carry it. Fetch it first:\n' +
+            `      git fetch --no-tags --depth=1 origin ${syncPoint}\n`);
+    }
+    // A sync point off the current history makes every number below
+    // meaningless — the diff would report upstream's own commits as the fork's.
+    // Truncated history cannot answer the question, so shallow clones skip it.
+    if (!isShallow(root) && !isAncestorOfHead(root, syncPoint)) {
+        return fail(`upstream-guard: sync point ${syncPoint.slice(0, 7)} is not an ancestor ` +
+            'of HEAD.\n' +
+            '    Merge that upstream commit before recording it, or record the ' +
+            'one\n' +
+            '    this branch actually descends from.\n');
+    }
+    const file = allowlistPathFor(opts);
+    const diff = diffAgainst(root, syncPoint);
+    const upstream = upstreamPaths(root, syncPoint, diff.map((d) => d.path));
+    if (opts.regenerate) {
+        return regenerateInto(file, diff, upstream);
+    }
+    const parsed = loadAllowlist(file);
+    if (!existsSync(file)) {
+        return fail(`upstream-guard: allowlist not found at ${file}\n`);
+    }
+    const map = new Map(parsed.entries.map((e) => [e.path, e.reason]));
+    const result = classify({ diff, upstream, allowlist: map });
+    const findings = [
+        ...parsed.errors.map((message) => ({ kind: 'allowlist-error', path: file, message })),
+        ...result.findings,
+    ];
+    const lines = [];
+    if (findings.length > 0) {
+        lines.push(`upstream-guard: ${findings.length} violation(s) against sync point ` +
+            `${syncPoint.slice(0, 7)}`, '');
+        for (const finding of findings)
+            lines.push(`  ${finding.message}`, '');
+        lines.push('The fork keeps its diff small: new behaviour goes in new fork-owned ' +
+            'files,', 'and an upstream file takes an import plus one call line. See ' +
+            'lat.md/fork.md.');
+    }
+    else {
+        lines.push(`upstream-guard: ok — ${result.touched.length} upstream file(s) ` +
+            'modified, all allowlisted.');
+    }
+    for (const warning of result.warnings)
+        lines.push(`  warning: ${warning}`);
+    return {
+        ok: findings.length === 0,
+        report: lines.join('\n') + '\n',
+        findings,
+        warnings: result.warnings,
+    };
+}
+// @lat: [[upstream-guard#The upstream guard#The sync point]]
+function recordSyncPoint(repo, file, rev) {
+    const resolved = git(repo, ['rev-parse', `${rev}^{commit}`]);
+    if (resolved.status !== 0) {
+        return fail(`upstream-guard: ${rev} is not a commit in this repository.\n`);
+    }
+    const sha = resolved.stdout.trim();
+    if (!isShallow(repo) && !isAncestorOfHead(repo, sha)) {
+        return fail(`upstream-guard: ${sha.slice(0, 7)} is not an ancestor of HEAD.\n` +
+            '    Record a sync point only once its merge has landed.\n');
+    }
+    const previous = existsSync(file) ? readFileSync(file, 'utf-8') : '';
+    writeFileSync(file, renderSyncPoint(previous, sha), 'utf-8');
+    return {
+        ok: true,
+        report: `upstream-guard: sync point is now ${sha}\n` +
+            '  regenerate the allowlist next — the set of files the fork ' +
+            'diverges in has moved.\n',
+        findings: [],
+        warnings: [],
+    };
+}
+function regenerateInto(file, diff, upstream) {
+    const existing = new Map(loadAllowlist(file).entries.map((e) => [e.path, e.reason]));
+    const entries = [];
+    const deletions = [];
+    const fresh = [];
+    for (const entry of diff) {
+        if (!upstream.has(entry.path))
+            continue;
+        if (entry.status.startsWith('D')) {
+            deletions.push({
+                kind: 'deletion',
+                path: entry.path,
+                message: `${entry.path}: deletes an upstream file, which is never ` +
+                    'allowlistable — left out of the regenerated list.',
+            });
+            continue;
+        }
+        const reason = existing.get(entry.path) ??
+            `${REASON_PLACEHOLDER}: why must this upstream file diverge?`;
+        if (!existing.has(entry.path))
+            fresh.push(entry.path);
+        entries.push({ path: entry.path, reason, line: 0 });
+    }
+    writeFileSync(file, renderAllowlist(entries), 'utf-8');
+    const lines = [
+        `upstream-guard: wrote ${entries.length} entr(ies) to ${file}`,
+    ];
+    for (const path of fresh) {
+        lines.push(`  new entry needs a reason: ${path}`);
+    }
+    for (const finding of deletions)
+        lines.push(`  ${finding.message}`);
+    return {
+        ok: deletions.length === 0,
+        report: lines.join('\n') + '\n',
+        findings: deletions,
+        warnings: [],
+    };
+}
+const USAGE = `Usage: node dist/src/fork/upstream-guard-cli.js [options]
+
+  --regenerate            rewrite the allowlist from the current diff
+  --fetch                 fetch the sync point from origin if it is absent
+  --set-sync-point <rev>  record <rev> as the last merged upstream commit
+  --sync-point <rev>      check against <rev> instead of the recorded one
+  --repo <dir>            default the current working directory
+  --allowlist <file>      default <repo>/${ALLOWLIST_FILE}
+  --sync-point-file <f>   default <repo>/${SYNC_POINT_FILE}
+  -h, --help              this text
+`;
+export function parseArgs(argv) {
+    const options = {
+        repo: process.cwd(),
+        allowlistFile: ALLOWLIST_FILE,
+        regenerate: false,
+        fetch: false,
+    };
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg === '-h' || arg === '--help')
+            return { help: true };
+        else if (arg === '--regenerate' || arg === '--write')
+            options.regenerate = true;
+        else if (arg === '--fetch')
+            options.fetch = true;
+        else if (arg === '--set-sync-point')
+            options.setSyncPoint = argv[++i] ?? '';
+        else if (arg === '--sync-point')
+            options.syncPoint = argv[++i] ?? '';
+        else if (arg === '--sync-point-file')
+            options.syncPointFile = argv[++i] ?? '';
+        else if (arg === '--repo')
+            options.repo = argv[++i] ?? '';
+        else if (arg === '--allowlist')
+            options.allowlistFile = argv[++i] ?? '';
+        else
+            throw new Error(`unknown argument: ${arg}`);
+    }
+    return options;
+}
+export function main(argv) {
+    let options;
+    try {
+        options = parseArgs(argv);
+    }
+    catch (error) {
+        process.stderr.write(`${error.message}\n\n${USAGE}`);
+        return 2;
+    }
+    if ('help' in options) {
+        process.stdout.write(USAGE);
+        return 0;
+    }
+    let result;
+    try {
+        result = runGuard(options);
+    }
+    catch (error) {
+        process.stderr.write(`upstream-guard: ${error.message}\n`);
+        return 2;
+    }
+    process.stdout.write(result.report);
+    return result.ok ? 0 : 1;
+}

package/dist/src/graph-export.d.ts

@@ -8,6 +8,8 @@ export type GraphNode = {
     mode?: string;
     status?: string;
     reviewedHash?: string;
+    /** sha256 of a section's own prose, excluding its heading and children. */
+    bodyHash?: string;
 };
 export type GraphEdge = {
     from: string;

package/dist/src/graph-export.js

@@ -8,15 +8,18 @@
 // `quoteUntrusted`) is correct here: node ids and labels must not be
 // truncated, and quoting them would corrupt them as identifiers.
 import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { join, relative } from 'node:path';
 import { promisify } from 'node:util';
-import { extractRefs, buildFileIndex, buildSectionSlugIndex, parseSections, parseFrontmatter, resolveRef, } from './lattice.js';
-import { scanCodeRefs } from './code-refs.js';
-import { DIATAXIS_MODES, MODE_DIRS } from './cli/check-mode.js';
-import { readProvenance } from './cli/check-status.js';
-import { cleanUntrustedId } from './untrusted.js';
-import { toPosix } from './walk.js';
+import { extractRefs, buildFileIndex, buildSectionSlugIndex, parseSections, parseFrontmatter, resolveRef, } from '@plebeiantech/lat.md-core/lattice';
+import { scanCodeRefs } from '@plebeiantech/lat.md-core/code-refs';
+import { DIATAXIS_MODES, MODE_DIRS, } from '@plebeiantech/lat.md-core/cli/check-mode';
+import { readProvenance } from '@plebeiantech/lat.md-core/cli/check-status';
+import { cleanUntrustedId } from '@plebeiantech/lat.md-core/untrusted';
+import { toPosix } from '@plebeiantech/lat.md-core/path';
 const execFileAsync = promisify(execFile);
+/** Bytes. Node's `execFile` default is 1 MB, which a large document exceeds. */
+const GIT_MAX_BUFFER = 256 * 1024 * 1024;
 function docId(relPath) {
     return `doc:${relPath}`;
 }
@@ -41,6 +44,15 @@ function modeForFile(relPath, fm) {
     }
     return undefined;
 }
+/** sha256 over lines (startLine, endLine], with trailing blanks normalized. */
+function hashSectionBody(lines, section) {
+    const body = lines
+        .slice(section.startLine, section.endLine)
+        .map((line) => line.replace(/[ \t]+$/, ''))
+        .join('\n')
+        .trim();
+    return createHash('sha256').update(body, 'utf-8').digest('hex');
+}
 function tagsForFile(fm) {
     const raw = fm['tags'];
     if (Array.isArray(raw))
@@ -107,10 +119,12 @@ export async function buildGraph(files, projectRoot, includeCode) {
             addNode({ id: tId, type: 'tag', label: cleanUntrustedId(tag) });
             addEdge({ from: dId, to: tId, type: 'tag' });
         }
+        const bodyLines = f.content.replace(/\r\n/g, '\n').split('\n');
         const walkSection = (section, parentId) => {
             const sId = ensureSectionNode(section.id, section.heading);
             const node = nodes.get(sId);
             node.file = f.relPath;
+            node.bodyHash = hashSectionBody(bodyLines, section);
             addEdge({ from: parentId, to: sId, type: 'contains' });
             for (const child of section.children) {
                 walkSection(child, sId);
@@ -129,6 +143,13 @@ export async function buildGraph(files, projectRoot, includeCode) {
     };
     flatten(allSections);
     const sectionIds = new Set(flat.map((s) => s.id.toLowerCase()));
+    const canonicalIds = new Map();
+    for (const s of flat) {
+        const key = s.id.toLowerCase();
+        if (!canonicalIds.has(key))
+            canonicalIds.set(key, s.id);
+    }
+    const canonicalize = (id) => canonicalIds.get(id.toLowerCase());
     const fileIndex = buildFileIndex(allSections);
     const slugIndex = buildSectionSlugIndex(allSections);
     // Wiki links: section -> section (or section -> code target).
@@ -137,9 +158,10 @@ export async function buildGraph(files, projectRoot, includeCode) {
         const refs = extractRefs(absPath, f.content, projectRoot);
         for (const ref of refs) {
             const { resolved, ambiguous } = resolveRef(ref.target, sectionIds, fileIndex, slugIndex);
-            const fromId = ensureSectionNode(ref.fromSection);
-            if (!ambiguous && sectionIds.has(resolved.toLowerCase())) {
-                const toId = ensureSectionNode(resolved);
+            const fromId = ensureSectionNode(canonicalize(ref.fromSection) ?? ref.fromSection);
+            const canonicalTarget = ambiguous ? undefined : canonicalize(resolved);
+            if (canonicalTarget !== undefined) {
+                const toId = ensureSectionNode(canonicalTarget);
                 addEdge({ from: fromId, to: toId, type: 'wikilink' });
             }
             else {
@@ -161,9 +183,8 @@ export async function buildGraph(files, projectRoot, includeCode) {
             const label = `${ref.file}:${ref.line}`;
             const cId = codeId(label);
             addNode({ id: cId, type: 'code', label: cleanUntrustedId(label) });
-            const toId = !ambiguous && sectionIds.has(resolved.toLowerCase())
-                ? ensureSectionNode(resolved)
-                : ensureSectionNode(ref.target);
+            const canonicalTarget = ambiguous ? undefined : canonicalize(resolved);
+            const toId = ensureSectionNode(canonicalTarget ?? ref.target);
             addEdge({ from: cId, to: toId, type: 'code-ref' });
         }
     }
@@ -171,7 +192,7 @@ export async function buildGraph(files, projectRoot, includeCode) {
 }
 /** Read the working tree's lat.md files straight off disk. */
 export async function loadWorkingTreeFiles(latticeDir, projectRoot) {
-    const { listLatticeFiles } = await import('./lattice.js');
+    const { listLatticeFiles } = await import('@plebeiantech/lat.md-core/lattice');
     const { readFile } = await import('node:fs/promises');
     const paths = await listLatticeFiles(latticeDir);
     const files = [];
@@ -190,20 +211,18 @@ export async function loadRevisionFiles(projectRoot, latticeDir, rev) {
     const latRelDir = toPosix(relative(projectRoot, latticeDir));
     let lsOutput;
     try {
-        const { stdout } = await execFileAsync('git', ['ls-tree', '-r', '--name-only', rev, '--', latRelDir], { cwd: projectRoot });
+        const { stdout } = await execFileAsync('git', ['ls-tree', '-r', '-z', '--name-only', rev, '--', latRelDir], { cwd: projectRoot, maxBuffer: GIT_MAX_BUFFER });
         lsOutput = stdout;
     }
     catch (err) {
         throw new Error(`failed to list "${latRelDir}" at revision "${rev}": ${err instanceof Error ? err.message : String(err)}`);
     }
-    const paths = lsOutput
-        .split('\n')
-        .map((l) => l.trim())
-        .filter((l) => l.endsWith('.md'));
+    const paths = lsOutput.split('\0').filter((l) => l.endsWith('.md'));
     const files = [];
     for (const p of paths) {
         const { stdout } = await execFileAsync('git', ['show', `${rev}:${p}`], {
             cwd: projectRoot,
+            maxBuffer: GIT_MAX_BUFFER,
         });
         files.push({ relPath: p, content: stdout });
     }
@@ -221,7 +240,7 @@ export function diffGraphs(before, after) {
         if (!prior) {
             added.push(id);
         }
-        else if (prior.label !== node.label) {
+        else if (prior.bodyHash !== node.bodyHash || prior.label !== node.label) {
             changed.push(id);
         }
     }

package/dist/src/knowledge/claude-memory.d.ts

@@ -10,4 +10,5 @@ import type { Store } from './types.js';
  * containing a dot.
  */
 export declare function slugify(absPath: string): string;
+export declare function readFileCapped(path: string): string | undefined;
 export declare const claudeMemoryStore: Store;

package/dist/src/knowledge/claude-memory.js

@@ -84,16 +84,45 @@ function unquote(value) {
     }
     return value;
 }
+/** The body of a leading `---` / `---` block, or undefined if there is none. */
+function frontmatterBlock(text) {
+    const match = /^---\r?\n([\s\S]*?)\r?\n---[ \t]*(?:\r?\n|$)/.exec(text);
+    return match ? match[1] : undefined;
+}
 /** Pull a `key: value` line out of YAML-ish frontmatter, quotes stripped. */
 function frontmatterField(text, key) {
-    const re = new RegExp(`^${key}:\\s*(.*)$`, 'm');
-    const match = re.exec(text);
+    const block = frontmatterBlock(text);
+    if (block === undefined)
+        return undefined;
+    const re = new RegExp(`^${escapeRegExp(key)}:[ \\t]*(.*)$`, 'm');
+    const match = re.exec(block);
     return match ? unquote(match[1].trim()) : undefined;
 }
-function readFileCapped(path) {
+function severedTailBytes(buf) {
+    for (let back = 1; back <= 3 && back <= buf.length; back++) {
+        const byte = buf[buf.length - back];
+        if ((byte & 0xc0) === 0x80)
+            continue;
+        let width = 0;
+        if ((byte & 0xe0) === 0xc0)
+            width = 2;
+        else if ((byte & 0xf0) === 0xe0)
+            width = 3;
+        else if ((byte & 0xf8) === 0xf0)
+            width = 4;
+        return width > back ? back : 0;
+    }
+    return 0;
+}
+export function readFileCapped(path) {
     try {
         const buf = readFileSync(path);
-        return buf.subarray(0, MAX_FILE_BYTES).toString('utf-8');
+        if (buf.length <= MAX_FILE_BYTES)
+            return buf.toString('utf-8');
+        const capped = buf.subarray(0, MAX_FILE_BYTES);
+        return capped
+            .subarray(0, capped.length - severedTailBytes(capped))
+            .toString('utf-8');
     }
     catch {
         return undefined;

package/dist/src/knowledge/index.js

@@ -1,7 +1,7 @@
 import { readFile } from 'node:fs/promises';
 import { join } from 'node:path';
-import { parseFrontmatter } from '../lattice.js';
-import { UNTRUSTED_NOTICE, quoteUntrusted, cleanUntrustedId, } from '../untrusted.js';
+import { parseFrontmatter } from '@plebeiantech/lat.md-core/lattice';
+import { UNTRUSTED_NOTICE, quoteUntrusted, cleanUntrustedId, } from '@plebeiantech/lat.md-core/untrusted';
 import { tagsToTerms, capHits } from './ranking.js';
 const STORE_GROUP_LABELS = {
     cq: 'cq:',