hafez 1.3.0 → 1.4.0

package/dist/index.js

@@ -1,17 +1,15 @@
 // src/index.ts
-import { parseFilePath, serializeFile, slugify, resolveFilePath, kindFromPath, kindDir, scanVaultDir, archiveLogPath, isIndexedRelPath } from './vault.js';
+import { parseFilePath, slugify, kindFromPath, kindDir, scanVaultDir, isIndexedRelPath, findVaultFile, vaultFileExists } from './vault.js';
 import { createGitJournal } from './git.js';
 import { validateEntityFrontmatter, validateKnowledgeFrontmatter, validateSessionLogEntry } from './schema.js';
-import { bodyTemplate, knowledgeBodyTemplate } from './templates.js';
-import { formatSessionLogEntry, countSessionLogEntries, extractOldestSessionLogEntry, setBrief, removeBrief, addNextAction, completeNextAction, removeNextAction, clearNextActions, syncRelatedSection, findSection, setSection, appendToSection, prependSessionLogEntry, bodyBeforeSessionLog } from './document.js';
-import { queryEntities, queryChildren, queryRelatedTo, queryKnowledge, queryUnified } from './query.js';
-import { getContract, ENTITY_STATUSES, CONFIDENCE_LEVELS } from './contracts.js';
+import { documentForFile } from './document.js';
 import { createIndex } from './db.js';
 import { generateVaultIndex } from './knowledge-index.js';
 import { HafezError } from './types.js';
-import { BatchOperationSchema, specFor } from './batch-ops.js';
-import { readFileSync, writeFileSync, existsSync, mkdirSync, appendFileSync, unlinkSync } from 'fs';
-import { join, relative, basename, dirname } from 'path';
+import { BatchOperationSchema, specFor, slugBearingOpNames, notFoundError, normalizeOperations, opErrorLine, batchInvalidHeader } from './batch-ops.js';
+import { applyOperation, buildEntityFrontmatter, buildKnowledgeFrontmatter, validateKindFields } from './apply.js';
+import { readFileSync, writeFileSync, existsSync, unlinkSync } from 'fs';
+import { join, basename } from 'path';
 import { lock as lockVault } from 'proper-lockfile';
 export function createHafez(config) {
     const { vaultPath, readOnly = false, git: gitConfig = {}, onWrite } = config;
@@ -51,215 +49,28 @@ export function createHafez(config) {
             catch { /* stale lock reclaimed by another process */ }
         }
     }
-    function entityPath(slug) { return resolveFilePath(vaultPath, slug, 'entity'); }
-    function knowledgePath(slug) { return resolveFilePath(vaultPath, slug, 'knowledge'); }
-    function findFile(slug) {
-        const ep = entityPath(slug);
-        if (existsSync(ep))
-            return ep;
-        const kp = knowledgePath(slug);
-        if (existsSync(kp))
-            return kp;
-        return null;
-    }
-    function exists(slug) {
-        // An invalid slug definitionally doesn't exist — reference checks (create
-        // parent/related, link targets, validate) must report "does not exist",
-        // not crash. validate() in particular exists to REPORT malformed refs.
-        try {
-            return findFile(slug) !== null;
-        }
-        catch {
-            return false;
-        }
-    }
-    function today() { return new Date().toISOString().slice(0, 10); }
-    const ENTITY_ONLY_FIELDS = ['status', 'add_action', 'add_actions', 'complete_action', 'remove_action', 'clear_actions', 'brief', 'current_state', 'session_log', 'resource'];
-    const KNOWLEDGE_ONLY_FIELDS = ['confidence', 'synthesis', 'add_evidence', 'add_source'];
-    function validateKindFields(kind, fields) {
-        if (kind === 'knowledge') {
-            const invalid = ENTITY_ONLY_FIELDS.filter(f => fields[f] !== undefined);
-            if (invalid.length > 0) {
-                throw new HafezError('VALIDATION_FAILED', `Cannot set entity-only fields on knowledge note: ${invalid.join(', ')}`);
-            }
-        }
-        if (kind === 'entity') {
-            const invalid = KNOWLEDGE_ONLY_FIELDS.filter(f => fields[f] !== undefined);
-            if (invalid.length > 0) {
-                throw new HafezError('VALIDATION_FAILED', `Cannot set knowledge-only fields on entity: ${invalid.join(', ')}`);
-            }
-        }
-    }
+    // Layout answers where a slug lives; these bind the vault path once.
+    function findFile(slug) { return findVaultFile(vaultPath, slug); }
+    function exists(slug) { return vaultFileExists(vaultPath, slug); }
     function regenerateIndexSafe() {
         // Runs post-commit: the vault write is already persisted/pushed, so an
         // index.md failure must warn, never reject the operation.
         try {
-            generateVaultIndex(vaultPath);
+            // index.md is rendered from the rows updateIndexPostCommit just
+            // refreshed, not from a second full-vault read: everything it shows
+            // (name, status, type, confidence, description, domain, body-derived
+            // summary) is already indexed. syncIfStale first so files changed
+            // outside hafez — a hand edit, a git pull — are represented too; that
+            // costs a stat per file, where the old path paid a parse per file on
+            // every single mutation.
+            const idx = getIndex();
+            idx?.syncIfStale();
+            generateVaultIndex(vaultPath, idx?.indexEntries());
         }
         catch (err) {
             process.stderr.write(`Warning: failed to regenerate index.md: ${err.message}\n`);
         }
     }
-    // Shared by create(), batch(), and the batch validate phase so optional
-    // fields can't silently diverge between paths (see CLAUDE.md Validation
-    // Gotchas). `existsFn` is pluggable so validateBatchCore can supply a
-    // simulation-aware check (same-batch creates count as existing).
-    function buildEntityFrontmatter(name, ef, existsFn = exists) {
-        const fm = { name, type: ef.type, status: 'active', created: today(), 'last-touched': today() };
-        if (ef.domain?.length)
-            fm.domain = ef.domain;
-        if (ef.parent) {
-            if (!existsFn(ef.parent))
-                throw new HafezError('VALIDATION_FAILED', `Parent '${ef.parent}' does not exist`);
-            fm.parent = ef.parent;
-        }
-        if (ef.related?.length) {
-            for (const r of ef.related) {
-                if (!existsFn(r))
-                    throw new HafezError('VALIDATION_FAILED', `Related slug '${r}' does not exist`);
-            }
-            fm.related = ef.related;
-        }
-        if (ef.tags?.length)
-            fm.tags = ef.tags;
-        if (ef.description)
-            fm.description = ef.description;
-        if (ef.resource)
-            fm.resource = ef.resource;
-        const errors = validateEntityFrontmatter(fm);
-        if (errors.length > 0)
-            throw new HafezError('VALIDATION_FAILED', 'Invalid entity frontmatter', errors);
-        return fm;
-    }
-    // Shared by create() and batch() like buildEntityFrontmatter — body-side
-    // optional fields (brief, actions) must behave identically in both paths.
-    function buildEntityBody(ef) {
-        let body = bodyTemplate(ef.type, { purpose: ef.purpose });
-        if (ef.brief)
-            body = setBrief(body, ef.brief);
-        if (ef.add_action)
-            body = addNextAction(body, ef.add_action);
-        for (const action of ef.add_actions ?? [])
-            body = addNextAction(body, action);
-        return body;
-    }
-    function buildKnowledgeFrontmatter(name, kf, existsFn = exists) {
-        const fm = { name, confidence: 'observation', 'reinforcement-count': 0, created: today() };
-        if (kf.domain?.length)
-            fm.domain = kf.domain;
-        if (kf.related?.length) {
-            for (const r of kf.related) {
-                if (!existsFn(r))
-                    throw new HafezError('VALIDATION_FAILED', `Related slug '${r}' does not exist`);
-            }
-            fm.related = kf.related;
-        }
-        if (kf.tags?.length)
-            fm.tags = kf.tags;
-        if (kf.description)
-            fm.description = kf.description;
-        const errors = validateKnowledgeFrontmatter(fm);
-        if (errors.length > 0)
-            throw new HafezError('VALIDATION_FAILED', 'Invalid knowledge frontmatter', errors);
-        if (kf.subtype)
-            fm.subtype = kf.subtype;
-        if (kf['session-date'])
-            fm['session-date'] = kf['session-date'];
-        return fm;
-    }
-    function applyUpdateFields(fm, body, fields) {
-        // Enum checks mirror the batch Zod shapes — without them the direct CLI
-        // path writes invalid values straight into frontmatter.
-        if (fields.status !== undefined) {
-            if (!ENTITY_STATUSES.includes(fields.status)) {
-                throw new HafezError('VALIDATION_FAILED', `Invalid status '${fields.status}'. Valid: ${ENTITY_STATUSES.join(', ')}`);
-            }
-            fm.status = fields.status;
-        }
-        if (fields.current_state !== undefined) {
-            body = setSection(body, 'Current State', fields.current_state, 'Session Log');
-        }
-        if (fields.brief !== undefined) {
-            body = fields.brief === null ? removeBrief(body) : setBrief(body, fields.brief);
-        }
-        let matchedAction;
-        if (fields.add_action)
-            body = addNextAction(body, fields.add_action);
-        if (fields.add_actions) {
-            for (const action of fields.add_actions) {
-                body = addNextAction(body, action);
-            }
-        }
-        if (fields.complete_action) {
-            const r = completeNextAction(body, fields.complete_action);
-            body = r.body;
-            matchedAction = r.matched;
-        }
-        if (fields.remove_action) {
-            const r = removeNextAction(body, fields.remove_action);
-            body = r.body;
-            matchedAction = r.matched;
-        }
-        if (fields.clear_actions)
-            body = clearNextActions(body);
-        if (fields.session_log) {
-            const logErrors = validateSessionLogEntry(fields.session_log);
-            if (logErrors.length > 0)
-                throw new HafezError('VALIDATION_FAILED', 'Invalid session log entry', logErrors);
-            body = prependSessionLogEntry(body, formatSessionLogEntry(fields.session_log));
-        }
-        // Domain (shared) + knowledge-only metadata
-        if (fields.domain !== undefined) {
-            if (fields.domain.length === 0)
-                delete fm.domain;
-            else
-                fm.domain = fields.domain;
-        }
-        if (fields.description !== undefined) {
-            if (fields.description === '' || fields.description === null)
-                delete fm.description;
-            else
-                fm.description = fields.description;
-        }
-        if (fields.resource !== undefined) {
-            if (fields.resource === '' || fields.resource === null)
-                delete fm.resource;
-            else
-                fm.resource = fields.resource;
-        }
-        if (fields.confidence !== undefined) {
-            if (!CONFIDENCE_LEVELS.includes(fields.confidence)) {
-                throw new HafezError('VALIDATION_FAILED', `Invalid confidence '${fields.confidence}'. Valid: ${CONFIDENCE_LEVELS.join(', ')}`);
-            }
-            fm.confidence = fields.confidence;
-        }
-        if (fields.tags !== undefined)
-            fm.tags = fields.tags;
-        if (fields.related !== undefined) {
-            for (const r of fields.related) {
-                if (!exists(r))
-                    throw new HafezError('VALIDATION_FAILED', `Related slug '${r}' does not exist`);
-            }
-            fm.related = fields.related;
-        }
-        if (fields.synthesis !== undefined) {
-            body = setSection(body, 'Synthesis', fields.synthesis);
-        }
-        if (fields.add_evidence) {
-            const sanitized = fields.add_evidence.replace(/^#{1,2}\s/gm, '### ');
-            body = appendToSection(body, 'Evidence', sanitized);
-            fm['reinforcement-count'] = (fm['reinforcement-count'] ?? 0) + 1;
-            fm['last-reinforced'] = today();
-            // NOTE: Confidence auto-promotion (observation→pattern at count>=3) was intentionally
-            // removed. Confidence changes are now a deliberate decision via update --confidence.
-        }
-        if (fields.add_source) {
-            body = appendToSection(body, 'Sources', fields.add_source);
-        }
-        if (fm['last-touched'] !== today())
-            fm['last-touched'] = today();
-        return { fm, body, matchedAction };
-    }
     let _index = null;
     let _indexInitialized = false;
     function getIndex() {
@@ -272,6 +83,12 @@ export function createHafez(config) {
         }
         return _index;
     }
+    // The one null-index guard: a read-only instance may have no on-disk index
+    // yet — reads then return their empty shape instead of crashing.
+    function withIndex(fn, empty) {
+        const idx = getIndex();
+        return idx ? fn(idx) : empty;
+    }
     async function read(slug, depth = 'summary') {
         const filePath = findFile(slug);
         if (!filePath)
@@ -284,7 +101,7 @@ export function createHafez(config) {
         if (depth === 'frontmatter')
             return { kind, frontmatter, body: '' };
         if (depth === 'summary') {
-            return { kind, frontmatter, body: bodyBeforeSessionLog(body) };
+            return { kind, frontmatter, body: documentForFile(parsed).bodyBeforeSessionLog(body) };
         }
         return { kind, frontmatter, body };
     }
@@ -313,301 +130,142 @@ export function createHafez(config) {
                 getIndex().upsertFromFile(u.slug, u.kind);
         }
     }
-    // The single apply path for every mutation. Writes vault files but never
-    // touches git or SQLite: callers commit [...filesWritten, ...filesDeleted]
-    // under commitMessage (single ops) or one composed batch message, then run
-    // updateIndexPostCommit. captureOriginal lets batch() snapshot files for
-    // rollback before they change.
-    function applyOperation(op, captureOriginal = () => { }) {
-        if (op.op === 'update') {
-            const filePath = findFile(op.slug);
-            if (!filePath)
-                throw new HafezError('NOT_FOUND', `'${op.slug}' not found`);
-            captureOriginal(filePath);
-            const kind = kindFromPath(filePath);
-            validateKindFields(kind, op.fields);
-            const parsedFile = parseFilePath(filePath);
-            let fm = parsedFile.frontmatter;
-            let body = parsedFile.body;
-            const applied = applyUpdateFields(fm, body, op.fields);
-            fm = applied.fm;
-            body = applied.body;
-            // Session log archival
-            const archivePath = archiveLogPath(vaultPath, op.slug);
-            if (countSessionLogEntries(body) >= 10) {
-                const extracted = extractOldestSessionLogEntry(body);
-                if (extracted) {
-                    captureOriginal(archivePath);
-                    mkdirSync(dirname(archivePath), { recursive: true });
-                    appendFileSync(archivePath, extracted.entry + '\n\n');
-                    body = extracted.remaining;
+    async function runMutations(operations, single) {
+        if (readOnly)
+            throw new HafezError('VALIDATION_FAILED', 'Hafez instance is read-only');
+        // Declared aliases (insight → synthesis) become canonical before anything
+        // else reads the payload: validate and apply must never see different
+        // field names, or an alias validates ok and then applies as nothing.
+        operations = normalizeOperations(operations);
+        return withLock(async () => {
+            // Validate the whole payload before touching anything — all errors
+            // surface at once, localised to their op. Single ops surface their
+            // primary error class (NOT_FOUND / SLUG_EXISTS) as the thrown code.
+            const validation = validateBatchCore(operations);
+            if (!validation.valid) {
+                if (single) {
+                    const opv = validation.operations[0];
+                    throw new HafezError(opv.primaryCode ?? 'VALIDATION_FAILED', opv.errors.length === 1 ? opv.errors[0] : opv.errors.join('; '), opv.errors.length > 1 ? opv.errors : undefined);
                 }
+                const invalidCount = validation.operations.filter(o => o.errors.length > 0).length;
+                throw new HafezError('VALIDATION_FAILED', batchInvalidHeader(invalidCount, operations.length), formatOpErrors(validation));
             }
-            body = syncRelatedSection(body, fm);
-            writeFileSync(filePath, serializeFile(fm, body));
-            const files = [relative(vaultPath, filePath)];
-            if (existsSync(archivePath))
-                files.push(relative(vaultPath, archivePath));
-            return {
-                filesWritten: files,
-                filesDeleted: [],
-                result: { op: 'update', slug: op.slug, status: 'ok' },
-                commitMessage: `update: ${op.slug}`,
-                indexRemovals: [],
-                indexUpserts: [{ slug: op.slug, kind }],
-                matchedAction: applied.matchedAction,
-            };
-        }
-        if (op.op === 'create' && op.kind === 'session') {
-            const slug = slugify(op.name);
-            if (exists(slug)) {
-                return {
-                    filesWritten: [], filesDeleted: [],
-                    result: { op: 'create', slug, status: 'error', error: `Slug '${slug}' already exists in the vault` },
-                    commitMessage: `create: ${op.name}`, indexRemovals: [], indexUpserts: [],
-                };
-            }
-            const sessionDir = join(vaultPath, kindDir('session'));
-            mkdirSync(sessionDir, { recursive: true });
-            const filePath = join(sessionDir, `${slug}.md`);
-            if (existsSync(filePath)) {
-                return {
-                    filesWritten: [], filesDeleted: [],
-                    result: { op: 'create', slug, status: 'error', error: `Session '${slug}' already exists` },
-                    commitMessage: `create: ${op.name}`, indexRemovals: [], indexUpserts: [],
-                };
-            }
-            captureOriginal(filePath);
-            const fm = { name: op.name, created: today() };
-            const kf = (op.fields ?? {});
-            if (kf['session-date'])
-                fm['session-date'] = kf['session-date'];
-            if (kf.related?.length)
-                fm.related = kf.related;
-            // Session files use sections: Summary, Entities Touched, Decisions
-            const sections = ['Summary', 'Entities Touched', 'Decisions'];
-            const lines = [];
-            for (const section of sections) {
-                lines.push(`## ${section}`);
-                if (section === 'Summary' && kf.synthesis)
-                    lines.push('', kf.synthesis);
-                lines.push('');
-            }
-            let sessionBody = lines.join('\n');
-            sessionBody = syncRelatedSection(sessionBody, fm);
-            writeFileSync(filePath, serializeFile(fm, sessionBody));
-            // Sessions are not indexed (db.ts only scans entities/ and knowledge/).
-            // They ARE included in git semantic merge (git.ts VAULT_FILE_RE).
-            return {
-                filesWritten: [relative(vaultPath, filePath)],
-                filesDeleted: [],
-                result: { op: 'create', slug, status: 'ok', created: true },
-                commitMessage: `create: ${op.name}`,
-                indexRemovals: [],
-                indexUpserts: [],
-            };
-        }
-        if (op.op === 'create') {
-            const slug = slugify(op.name);
-            if (exists(slug))
-                throw new HafezError('SLUG_EXISTS', `Slug '${slug}' already exists`);
-            if (op.kind === 'entity') {
-                const ef = op.fields;
-                const fm = buildEntityFrontmatter(op.name, ef);
-                let body = buildEntityBody(ef);
-                const filePath = entityPath(slug);
-                captureOriginal(filePath);
-                mkdirSync(join(vaultPath, kindDir('entity')), { recursive: true });
-                body = syncRelatedSection(body, fm);
-                writeFileSync(filePath, serializeFile(fm, body));
-                return {
-                    filesWritten: [relative(vaultPath, filePath)],
-                    filesDeleted: [],
-                    result: { op: 'create', slug, status: 'ok', created: true },
-                    commitMessage: `create: ${op.name}`,
-                    indexRemovals: [],
-                    indexUpserts: [{ slug, kind: 'entity' }],
-                };
+            // Apply receives the shape's output, not the raw payload, so a shape
+            // transform lands in the file instead of existing only in the
+            // validator's view.
+            operations = validation.parsedOps;
+            // Capture originals for rollback
+            const originals = new Map();
+            function captureOriginal(filePath) {
+                if (!originals.has(filePath)) {
+                    originals.set(filePath, existsSync(filePath) ? readFileSync(filePath, 'utf-8') : null);
+                }
             }
-            const kf = (op.fields || {});
-            const fm = buildKnowledgeFrontmatter(op.name, kf);
-            let body = knowledgeBodyTemplate(kf.subtype, { synthesis: kf.synthesis });
-            const filePath = knowledgePath(slug);
-            captureOriginal(filePath);
-            mkdirSync(join(vaultPath, kindDir('knowledge')), { recursive: true });
-            body = syncRelatedSection(body, fm);
-            writeFileSync(filePath, serializeFile(fm, body));
-            return {
-                filesWritten: [relative(vaultPath, filePath)],
-                filesDeleted: [],
-                result: { op: 'create', slug, status: 'ok', created: true },
-                commitMessage: `create: ${op.name}`,
-                indexRemovals: [],
-                indexUpserts: [{ slug, kind: 'knowledge' }],
-            };
-        }
-        if (op.op === 'capture') {
-            const slug = slugify(op.name);
-            if (exists(slug))
-                throw new HafezError('SLUG_EXISTS', `Slug '${slug}' already exists`);
-            const fm = {
-                name: op.name,
-                type: 'capture',
-                status: 'active',
-                created: today(),
-                'last-touched': today(),
-            };
-            const filePath = entityPath(slug);
-            captureOriginal(filePath);
-            mkdirSync(join(vaultPath, kindDir('entity')), { recursive: true });
-            writeFileSync(filePath, serializeFile(fm, bodyTemplate('capture', { notes: op.notes })));
-            return {
-                filesWritten: [relative(vaultPath, filePath)],
-                filesDeleted: [],
-                result: { op: 'capture', slug, status: 'ok', created: true },
-                commitMessage: `capture: ${op.name}`,
-                indexRemovals: [],
-                indexUpserts: [{ slug, kind: 'entity' }],
-            };
-        }
-        if (op.op === 'link') {
-            const filePath = findFile(op.slug);
-            if (!filePath)
-                throw new HafezError('NOT_FOUND', `'${op.slug}' not found`);
-            if (!exists(op.target))
-                throw new HafezError('VALIDATION_FAILED', `Target '${op.target}' does not exist`);
-            captureOriginal(filePath);
-            const parsedFile = parseFilePath(filePath);
-            const fm = parsedFile.frontmatter;
-            let body = parsedFile.body;
-            if (op.relation === 'parent') {
-                fm.parent = op.target;
+            const applied = [];
+            const results = [];
+            let currentOp = -1;
+            try {
+                for (const op of operations) {
+                    currentOp++;
+                    // A warned op is the validate phase's skip disposition (today: a
+                    // duplicate session — green-lit so the batch runs on, but nothing
+                    // to write). The Spine synthesizes the result rather than calling
+                    // Apply, so the rule lives only in the Op Spec. `code` rides along
+                    // for the single-op unwrap: that caller has nothing to return and
+                    // must throw under the target-exists class, not a generic one.
+                    const warning = validation.operations[currentOp].warning;
+                    if (warning) {
+                        results.push({
+                            op: op.op, slug: validation.operations[currentOp].slug,
+                            status: 'skipped', warning, code: 'SLUG_EXISTS',
+                        });
+                        continue;
+                    }
+                    const a = applyOperation(op, { vaultPath, captureOriginal });
+                    results.push(a.result);
+                    if (a.result.status === 'ok')
+                        applied.push(a);
+                }
             }
-            else {
-                const related = fm.related || [];
-                if (!related.includes(op.target))
-                    related.push(op.target);
-                fm.related = related;
+            catch (err) {
+                rollbackFiles(originals);
+                // The validate phase above catches semantic errors pre-execution;
+                // this localises residual execution-time failures (races, disk
+                // errors) to their op in batch mode.
+                if (!single && err instanceof HafezError && currentOp >= 0) {
+                    const op = operations[currentOp];
+                    const label = 'slug' in op ? op.slug : slugify(op.name);
+                    throw new HafezError(err.code, opErrorLine(currentOp, op.op, label, err.message), err.details);
+                }
+                throw err;
             }
-            body = syncRelatedSection(body, fm);
-            writeFileSync(filePath, serializeFile(fm, body));
-            return {
-                filesWritten: [relative(vaultPath, filePath)],
-                filesDeleted: [],
-                result: { op: 'link', slug: op.slug, status: 'ok' },
-                commitMessage: `link: ${op.slug} → ${op.target} (${op.relation})`,
-                indexRemovals: [],
-                indexUpserts: [{ slug: op.slug, kind: kindFromPath(filePath) }],
+            // Batch reports per-op non-'ok' results; a single-op caller unwraps
+            // applied[0], so anything that did not apply must surface as a thrown
+            // error, not a TypeError on the unwrap — under the result's own error
+            // class where it has one.
+            if (single && applied.length === 0) {
+                const failed = results.find(r => r.status !== 'ok');
+                throw new HafezError(failed?.code ?? 'VALIDATION_FAILED', failed?.error || failed?.warning || 'operation was not applied');
+            }
+            const writtenAll = [...new Set(applied.flatMap(a => a.filesWritten))];
+            const deletedAll = [...new Set(applied.flatMap(a => a.filesDeleted))];
+            const finalize = () => {
+                updateIndexPostCommit(applied);
+                // index.md regeneration is gated: session-only writes skip it
+                if ([...writtenAll, ...deletedAll].some(isIndexedRelPath)) {
+                    regenerateIndexSafe();
+                }
+                // Session creates carry no index upserts — they are not indexed
+                // entities and never notified.
+                for (const a of applied) {
+                    if (a.indexUpserts.length > 0)
+                        onWrite?.(a.result.slug, single ? single.action : 'batch');
+                }
             };
-        }
-        if (op.op === 'unlink') {
-            const filePath = findFile(op.slug);
-            if (!filePath)
-                throw new HafezError('NOT_FOUND', `'${op.slug}' not found`);
-            captureOriginal(filePath);
-            const parsedFile = parseFilePath(filePath);
-            const fm = parsedFile.frontmatter;
-            let body = parsedFile.body;
-            if (op.relation === 'parent' && fm.parent === op.target) {
-                delete fm.parent;
-            }
-            else if (op.relation === 'related' && fm.related) {
-                fm.related = fm.related.filter((r) => r !== op.target);
-                if (fm.related.length === 0)
-                    delete fm.related;
+            if (writtenAll.length + deletedAll.length > 0) {
+                const message = single ? applied[0].commitMessage : `batch: ${operations.length} operations`;
+                try {
+                    await journal.commit(writtenAll, deletedAll, message);
+                }
+                catch (err) {
+                    if (!(err instanceof HafezError && err.code === 'GIT_PUSH_FAILED')) {
+                        // Commit-stage failure (e.g. a raced .git/index.lock): nothing was
+                        // committed — restore the captured originals so files, journal,
+                        // and index stay consistent. The adapter has already cleaned up
+                        // its own partial state (staged files) before rethrowing.
+                        rollbackFiles(originals);
+                        throw err;
+                    }
+                    // Push-stage failure: the commit exists locally ("changes saved
+                    // locally") — keep it and index it, then surface the error.
+                    finalize();
+                    throw err;
+                }
+                finalize();
             }
-            body = syncRelatedSection(body, fm);
-            writeFileSync(filePath, serializeFile(fm, body));
-            return {
-                filesWritten: [relative(vaultPath, filePath)],
-                filesDeleted: [],
-                result: { op: 'unlink', slug: op.slug, status: 'ok' },
-                commitMessage: `unlink: ${op.slug} ✕ ${op.target} (${op.relation})`,
-                indexRemovals: [],
-                indexUpserts: [{ slug: op.slug, kind: kindFromPath(filePath) }],
-            };
-        }
-        // promote
-        const filePath = findFile(op.slug);
-        if (!filePath)
-            throw new HafezError('NOT_FOUND', `'${op.slug}' not found`);
-        captureOriginal(filePath);
-        if (op.target === 'knowledge')
-            captureOriginal(knowledgePath(op.slug));
-        const kind = kindFromPath(filePath);
-        const parsedFile = parseFilePath(filePath);
-        const fm = parsedFile.frontmatter;
-        const body = parsedFile.body;
-        const sourceType = kind === 'knowledge' ? 'knowledge' : fm.type;
-        const { modifiedFiles, deletedFiles } = promoteCore(op.slug, op.target, filePath, fm, body, kind);
-        return {
-            filesWritten: modifiedFiles,
-            filesDeleted: deletedFiles,
-            result: { op: 'promote', slug: op.slug, status: 'ok' },
-            commitMessage: `promote: ${op.slug} ${sourceType} → ${op.target}`,
-            indexRemovals: op.target === 'knowledge' ? [op.slug] : [],
-            indexUpserts: [{ slug: op.slug, kind: op.target === 'knowledge' ? 'knowledge' : 'entity' }],
-        };
+            return { applied, results };
+        });
     }
     async function create(kind, name, fields) {
-        if (readOnly)
-            throw new HafezError('VALIDATION_FAILED', 'Hafez instance is read-only');
-        return withLock(async () => {
-            const a = kind === 'entity'
-                ? applyOperation({ op: 'create', kind, name, fields: fields })
-                : applyOperation({ op: 'create', kind, name, fields: fields });
-            await journal.commit(a.filesWritten, a.filesDeleted, a.commitMessage);
-            updateIndexPostCommit([a]);
-            onWrite?.(a.result.slug, 'create');
-            regenerateIndexSafe();
-            return a.result.slug;
-        });
+        const op = kind === 'entity'
+            ? { op: 'create', kind, name, fields: fields }
+            : { op: 'create', kind, name, fields: fields };
+        const { applied } = await runMutations([op], { action: 'create' });
+        return applied[0].result.slug;
     }
     async function capture(name, notes) {
-        if (readOnly)
-            throw new HafezError('VALIDATION_FAILED', 'Hafez instance is read-only');
-        return withLock(async () => {
-            const a = applyOperation({ op: 'capture', name, notes });
-            await journal.commit(a.filesWritten, a.filesDeleted, a.commitMessage);
-            updateIndexPostCommit([a]);
-            regenerateIndexSafe();
-            onWrite?.(a.result.slug, 'capture');
-            return a.result.slug;
-        });
+        const { applied } = await runMutations([{ op: 'capture', name, notes }], { action: 'capture' });
+        return applied[0].result.slug;
     }
     async function update(slug, fields) {
-        if (readOnly)
-            throw new HafezError('VALIDATION_FAILED', 'Hafez instance is read-only');
-        return withLock(async () => {
-            const a = applyOperation({ op: 'update', slug, fields });
-            await journal.commit(a.filesWritten, a.filesDeleted, a.commitMessage);
-            updateIndexPostCommit([a]);
-            regenerateIndexSafe();
-            onWrite?.(slug, 'update');
-            return { matched_action: a.matchedAction };
-        });
+        const { applied } = await runMutations([{ op: 'update', slug, fields }], { action: 'update' });
+        return { matched_action: applied[0].matchedAction };
     }
     async function link(slug, target, relation) {
-        if (readOnly)
-            throw new HafezError('VALIDATION_FAILED', 'Hafez instance is read-only');
-        return withLock(async () => {
-            const a = applyOperation({ op: 'link', slug, target, relation });
-            await journal.commit(a.filesWritten, a.filesDeleted, a.commitMessage);
-            updateIndexPostCommit([a]);
-            regenerateIndexSafe();
-            onWrite?.(slug, 'link');
-        });
+        await runMutations([{ op: 'link', slug, target, relation }], { action: 'link' });
     }
     async function unlink(slug, target, relation) {
-        if (readOnly)
-            throw new HafezError('VALIDATION_FAILED', 'Hafez instance is read-only');
-        return withLock(async () => {
-            const a = applyOperation({ op: 'unlink', slug, target, relation });
-            await journal.commit(a.filesWritten, a.filesDeleted, a.commitMessage);
-            updateIndexPostCommit([a]);
-            regenerateIndexSafe();
-            onWrite?.(slug, 'unlink');
-        });
+        await runMutations([{ op: 'unlink', slug, target, relation }], { action: 'unlink' });
     }
     // "Recent" with day-granularity dates: primary sort is the frontmatter day,
     // ties break on git commit time (the real recency signal), then name for
@@ -656,8 +314,18 @@ export function createHafez(config) {
                 if (!fp)
                     return null;
                 const kind = kindFromPath(fp);
-                if (kind === 'knowledge')
-                    return { kind, type: 'knowledge' };
+                // The subtype decides which fields a knowledge note accepts (plan vs
+                // insight), so it is resolved here rather than re-read per op.
+                if (kind === 'knowledge') {
+                    try {
+                        const pf = parseFilePath(fp);
+                        const subtype = pf.kind === 'knowledge' ? pf.frontmatter.subtype : undefined;
+                        return { kind, type: 'knowledge', subtype };
+                    }
+                    catch {
+                        return { kind, type: 'knowledge' };
+                    }
+                }
                 try {
                     const pf = parseFilePath(fp);
                     return { kind, type: pf.kind === 'entity' ? pf.frontmatter.type : 'entity' };
@@ -676,118 +344,59 @@ export function createHafez(config) {
             buildKnowledgeFrontmatter: (name, fields) => { buildKnowledgeFrontmatter(name, fields, existsAnywhere); },
         };
         const report = [];
+        // The shape's OUTPUT, index-aligned with the report. Shapes may transform
+        // (action/evidence text is trimmed), and the semantic checks and Apply
+        // must both see what the shape emitted — validating the trimmed value but
+        // writing the raw one would store what validation never looked at.
+        const parsedOps = [];
         for (const [index, op] of operations.entries()) {
             // Shape and semantics in one pass: library callers get the same runtime
             // guarantee the CLI's JSON path has always had.
             const shape = BatchOperationSchema.safeParse(op);
             if (!shape.success) {
+                parsedOps.push(op);
                 const raw = op;
                 const label = raw && typeof raw.slug === 'string' ? raw.slug
                     : raw && typeof raw.name === 'string' ? slugify(raw.name) : '';
-                report.push({
+                const entry = {
                     index,
                     op: typeof raw?.op === 'string' ? raw.op : '?',
                     slug: label,
                     errors: shape.error.issues.map(i => `invalid shape at ${i.path.join('.') || '(root)'}: ${i.message}`),
-                });
+                };
+                // A missing slug outranks field-shape problems: spec.check never runs
+                // when the shape fails, but the direct paths always surfaced NOT_FOUND
+                // first (and scripts branch on its exit code) — keep that precedence.
+                if (raw && typeof raw.slug === 'string' && raw.slug &&
+                    slugBearingOpNames().includes(entry.op) &&
+                    !existsAnywhere(raw.slug)) {
+                    entry.errors.unshift(notFoundError(raw.slug));
+                    entry.primaryCode = 'NOT_FOUND';
+                }
+                report.push(entry);
                 continue;
             }
-            const spec = specFor(op);
-            const res = spec.check(op, ctx);
-            const entry = { index, op: op.op, slug: res.slug, errors: res.errors };
+            const parsed = shape.data;
+            parsedOps.push(parsed);
+            const spec = specFor(parsed);
+            const res = spec.check(parsed, ctx);
+            const entry = { index, op: parsed.op, slug: res.slug, errors: res.errors };
             if (res.created)
                 entry.created = true;
             if (res.warning)
                 entry.warning = res.warning;
+            if (res.primaryCode)
+                entry.primaryCode = res.primaryCode;
             report.push(entry);
         }
-        return { valid: report.every(o => o.errors.length === 0), operations: report };
+        return { valid: report.every(o => o.errors.length === 0), operations: report, parsedOps };
     }
     function formatOpErrors(report) {
-        return report.operations.flatMap(o => o.errors.map(e => `op[${o.index}] (${o.op} ${o.slug}): ${e}`));
+        return report.operations.flatMap(o => o.errors.map(e => opErrorLine(o.index, o.op, o.slug, e)));
     }
     async function batch(operations) {
-        if (readOnly)
-            throw new HafezError('VALIDATION_FAILED', 'Hafez instance is read-only');
-        return withLock(async () => {
-            // Validate the whole payload before touching anything — all errors
-            // surface at once, localised to their op.
-            const validation = validateBatchCore(operations);
-            if (!validation.valid) {
-                const invalidCount = validation.operations.filter(o => o.errors.length > 0).length;
-                throw new HafezError('VALIDATION_FAILED', `Batch failed validation: ${invalidCount} invalid operation${invalidCount === 1 ? '' : 's'} (0 of ${operations.length} applied)`, formatOpErrors(validation));
-            }
-            // Capture originals for rollback
-            const originals = new Map();
-            function captureOriginal(filePath) {
-                if (!originals.has(filePath)) {
-                    originals.set(filePath, existsSync(filePath) ? readFileSync(filePath, 'utf-8') : null);
-                }
-            }
-            const appliedOps = [];
-            const results = [];
-            let currentOp = -1;
-            try {
-                for (const op of operations) {
-                    currentOp++;
-                    const a = applyOperation(op, captureOriginal);
-                    results.push(a.result);
-                    if (a.result.status === 'ok')
-                        appliedOps.push(a);
-                }
-            }
-            catch (err) {
-                rollbackFiles(originals);
-                // Localise: which op failed, by index and slug/name. The validate
-                // phase above catches semantic errors pre-execution; this covers
-                // residual execution-time failures (races, disk errors).
-                if (err instanceof HafezError && currentOp >= 0) {
-                    const op = operations[currentOp];
-                    const label = 'slug' in op ? op.slug : slugify(op.name);
-                    throw new HafezError(err.code, `op[${currentOp}] (${op.op} ${label}): ${err.message}`, err.details);
-                }
-                throw err;
-            }
-            // Single journal commit for all batch operations
-            const writtenAll = [...new Set(appliedOps.flatMap(a => a.filesWritten))];
-            const deletedAll = [...new Set(appliedOps.flatMap(a => a.filesDeleted))];
-            const indexAfterBatch = () => {
-                updateIndexPostCommit(appliedOps);
-                // Regenerate vault index if any entity or knowledge was touched (session-only batches skip)
-                const anyIndexedTouched = [...writtenAll, ...deletedAll].some(isIndexedRelPath);
-                if (anyIndexedTouched) {
-                    regenerateIndexSafe();
-                }
-                // Session creates carry no index upserts — they were never notified
-                // pre-collapse either (sessions aren't indexed entities).
-                for (const a of appliedOps) {
-                    if (a.indexUpserts.length > 0)
-                        onWrite?.(a.result.slug, 'batch');
-                }
-            };
-            if (writtenAll.length + deletedAll.length > 0) {
-                try {
-                    await journal.commit(writtenAll, deletedAll, `batch: ${operations.length} operations`);
-                }
-                catch (err) {
-                    if (!(err instanceof HafezError && err.code === 'GIT_PUSH_FAILED')) {
-                        // Commit-stage failure (e.g. a raced .git/index.lock): nothing was
-                        // committed — restore the captured originals so files, journal,
-                        // and index stay consistent instead of leaving the batch
-                        // half-applied. The adapter has already cleaned up its own
-                        // partial state (staged files) before rethrowing.
-                        rollbackFiles(originals);
-                        throw err;
-                    }
-                    // Push-stage failure: the batch commit exists locally ("changes
-                    // saved locally") — keep it and index it, then surface the error.
-                    indexAfterBatch();
-                    throw err;
-                }
-                indexAfterBatch();
-            }
-            return results;
-        });
+        const { results } = await runMutations(operations, null);
+        return results;
     }
     async function validate() {
         const report = {
@@ -878,117 +487,14 @@ export function createHafez(config) {
         }
         return report;
     }
-    function promoteCore(slug, target, filePath, fm, body, kind) {
-        const currentType = kind === 'knowledge' ? 'knowledge' : fm.type;
-        const contract = getContract(currentType);
-        if (!contract.canPromoteTo.includes(target)) {
-            throw new HafezError('VALIDATION_FAILED', `Cannot promote ${currentType} to ${target}. Valid targets: ${contract.canPromoteTo.join(', ') || 'none (terminal type)'}`);
-        }
-        const modifiedFiles = [];
-        const deletedFiles = [];
-        if (target === 'knowledge') {
-            // Cross-kind: move file from entities/ to knowledge/
-            const newPath = knowledgePath(slug);
-            const notesSection = findSection(body, 'Notes');
-            const notesContent = notesSection?.content ?? '';
-            const newFm = {
-                name: fm.name, subtype: 'insight', confidence: 'observation', created: fm.created || today(),
-            };
-            if (fm.description)
-                newFm.description = fm.description;
-            // resource is intentionally dropped on entity→knowledge promote (entity-only field)
-            if (fm.domain)
-                newFm.domain = fm.domain;
-            if (fm.related)
-                newFm.related = fm.related;
-            if (fm.tags)
-                newFm.tags = fm.tags;
-            const knBody = knowledgeBodyTemplate('insight', { synthesis: notesContent || undefined });
-            const finalBody = syncRelatedSection(knBody, newFm);
-            writeFileSync(newPath, serializeFile(newFm, finalBody));
-            unlinkSync(filePath);
-            modifiedFiles.push(relative(vaultPath, newPath));
-            // The deletion must be staged too — `git add` of a removed path stages
-            // the removal; omitting it leaves the vault permanently dirty.
-            deletedFiles.push(relative(vaultPath, filePath));
-        }
-        else {
-            // Same-kind: capture→entity, capture→project, entity→project
-            fm.type = target;
-            fm['last-touched'] = today();
-            let newBody = body;
-            if (target === 'entity') {
-                newBody = newBody.replace(/^## Notes$/m, '## Context');
-            }
-            else {
-                // project
-                newBody = newBody.replace(/^## Notes$/m, '## Purpose');
-                newBody = newBody.replace(/^## Context$/m, '## Purpose');
-                if (!newBody.includes('## Goals')) {
-                    const sections = newBody.split(/\n(?=## )/m);
-                    const purposeIdx = sections.findIndex(s => s.startsWith('## Purpose'));
-                    if (purposeIdx !== -1) {
-                        sections.splice(purposeIdx + 1, 0, '## Goals\n');
-                    }
-                    else {
-                        sections.push('## Goals\n');
-                    }
-                    newBody = sections.join('\n');
-                }
-            }
-            if (!newBody.includes('## Session Log'))
-                newBody += '\n## Session Log\n';
-            // Add promotion session log entry
-            const logEntry = `### ${today()} — system [decision]\nSummary: Promoted from ${currentType} to ${target}\n`;
-            const logIdx = newBody.lastIndexOf('## Session Log');
-            if (logIdx !== -1) {
-                const insertAt = logIdx + '## Session Log'.length + 1;
-                newBody = newBody.slice(0, insertAt) + '\n' + logEntry + newBody.slice(insertAt);
-            }
-            newBody = syncRelatedSection(newBody, fm);
-            writeFileSync(filePath, serializeFile(fm, newBody));
-            modifiedFiles.push(relative(vaultPath, filePath));
-        }
-        return { modifiedFiles, deletedFiles };
-    }
     async function promote(slug, target) {
-        if (readOnly)
-            throw new HafezError('VALIDATION_FAILED', 'Hafez instance is read-only');
-        return withLock(async () => {
-            const filePath = findFile(slug);
-            if (!filePath)
-                throw new HafezError('NOT_FOUND', `'${slug}' not found`);
-            // Capture original content for rollback
-            const originalContent = target === 'knowledge' ? readFileSync(filePath, 'utf-8') : null;
-            const knowledgeTarget = target === 'knowledge' ? knowledgePath(slug) : null;
-            let a;
-            try {
-                a = applyOperation({ op: 'promote', slug, target });
-                await journal.commit(a.filesWritten, a.filesDeleted, a.commitMessage);
-            }
-            catch (err) {
-                if (a && err instanceof HafezError && err.code === 'GIT_PUSH_FAILED') {
-                    // Push-stage failure: the promote commit exists locally — keep the
-                    // files and index them (same policy as batch); rolling back here
-                    // would leave the worktree contradicting HEAD.
-                    updateIndexPostCommit([a]);
-                    regenerateIndexSafe();
-                    throw err;
-                }
-                // Apply- or commit-stage failure: nothing was committed — restore.
-                if (target === 'knowledge' && originalContent) {
-                    writeFileSync(filePath, originalContent);
-                    // Never unlink the file we just restored (SEC-4)
-                    if (knowledgeTarget && knowledgeTarget !== filePath && existsSync(knowledgeTarget))
-                        unlinkSync(knowledgeTarget);
-                }
-                throw err;
-            }
-            updateIndexPostCommit([a]);
-            regenerateIndexSafe();
-            onWrite?.(slug, 'promote');
-            return slug;
-        });
+        // Rollback safety rides the Spine: applyOperation's promote arm captures
+        // both the source file and (for cross-kind moves) the knowledge target
+        // before writing, so a commit-stage failure restores the source and
+        // removes the created file (SEC-4: never unlink a restored path —
+        // rollbackFiles only unlinks paths captured as previously-absent).
+        await runMutations([{ op: 'promote', slug, target }], { action: 'promote' });
+        return slug;
     }
     const emptyStats = {
         counts: { active: 0, paused: 0, done: 0 },
@@ -1000,59 +506,38 @@ export function createHafez(config) {
         read,
         update,
         promote,
-        query: async (opts) => {
-            const idx = getIndex();
-            if (!idx)
-                return { items: [], total: 0 };
-            return queryEntities(idx, opts);
-        },
-        queryUnified: async (opts) => {
-            const idx = getIndex();
-            if (!idx)
-                return { items: [], total: 0 };
-            return queryUnified(idx, opts);
-        },
+        query: async (opts) => withIndex(idx => idx.queryEntities(opts), { items: [], total: 0 }),
+        queryUnified: async (opts) => withIndex(idx => idx.queryUnified(opts), { items: [], total: 0 }),
         create,
         capture,
         link,
         unlink,
         batch,
-        validateBatch: async (operations) => validateBatchCore(operations),
+        // Same normalization as the apply path — dry-run must judge the payload
+        // apply would actually run.
+        validateBatch: async (operations) => {
+            // parsedOps is the Spine's internal handoff, not part of the report.
+            const { valid, operations: report } = validateBatchCore(normalizeOperations(operations));
+            return { valid, operations: report };
+        },
         sync: async () => {
             if (readOnly)
                 throw new HafezError('VALIDATION_FAILED', 'Hafez instance is read-only');
             return withLock(() => journal.sync());
         },
-        children: async (slug) => {
-            const idx = getIndex();
-            if (!idx)
-                return { items: [], total: 0 };
-            return queryChildren(idx, slug);
-        },
-        related_to: async (slug, relation) => {
-            const idx = getIndex();
-            if (!idx)
-                return { items: [], total: 0 };
-            return queryRelatedTo(idx, slug, relation);
-        },
-        query_knowledge: async (opts) => {
-            const idx = getIndex();
-            if (!idx)
-                return { items: [], total: 0 };
-            return queryKnowledge(idx, opts);
-        },
+        children: async (slug) => withIndex(idx => idx.queryChildren(slug), { items: [], total: 0 }),
+        related_to: async (slug, relation) => withIndex(idx => idx.queryRelatedTo(slug, relation), { items: [], total: 0 }),
+        query_knowledge: async (opts) => withIndex(idx => idx.queryKnowledge(opts), { items: [], total: 0 }),
         validate,
-        search: async (query, kind) => {
-            const idx = getIndex();
-            if (!idx)
-                return [];
-            idx.syncIfStale();
-            return idx.search(query, kind);
-        },
+        search: async (query, kind) => withIndex(idx => { idx.syncIfStale(); return idx.search(query, kind); }, []),
         rebuildIndex: async () => {
             if (readOnly)
                 throw new HafezError('VALIDATION_FAILED', 'Hafez instance is read-only');
-            getIndex().rebuild();
+            // A rebuild reads every vault file and rewrites the whole index, so it
+            // takes the same two-level write lock every mutation takes — otherwise it
+            // can interleave with a mutation's file writes and index a half-written
+            // vault.
+            await withLock(async () => { getIndex().rebuild(); });
         },
         stats: async () => {
             const idx = getIndex();
@@ -1068,5 +553,5 @@ export function createHafez(config) {
     };
 }
 export { HafezError } from './types.js';
-export { getBrief, getNextActions, findSection } from './document.js';
+export { getBrief, getNextActions } from './document.js';
 export { parseSessionLogHeading, parseSessionLog } from './document.js';