hafez 1.2.0 → 1.4.0

package/dist/index.js

@@ -1,20 +1,21 @@
 // src/index.ts
-import { parseFilePath, serializeFile, slugify, resolveFilePath, kindFromPath } from './vault.js';
-import { gitCommitAndPush, gitSync, gitChangelog, gitUnstage, gitFileTimes } from './git.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 } from './parser.js';
-import { setBrief, removeBrief, addNextAction, completeNextAction, removeNextAction, clearNextActions, syncRelatedSection, findNextStructuralHeading, findSection } from './sections.js';
-import { queryEntities, queryChildren, queryRelatedTo, queryKnowledge, queryUnified } from './query.js';
-import { getContract } 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 { readFileSync, writeFileSync, existsSync, mkdirSync, readdirSync, appendFileSync, unlinkSync } from 'fs';
-import { join, relative, basename } 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;
+    // The persistence seam (CONTEXT.md: Journal). Everything below talks to
+    // history through this port; git is just the default adapter.
+    const journal = config.persistence ?? createGitJournal(vaultPath, gitConfig);
     // Two-level write lock: an in-process promise chain serializes calls within
     // this instance, then a cross-process advisory lock (proper-lockfile, mkdir
     // based — works on network/drvfs mounts) serializes against other hafez
@@ -48,244 +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 replaceSection(body, heading, content, insertBefore) {
-        const idx = body.indexOf(heading);
-        if (idx >= 0) {
-            const afterPos = idx + heading.length;
-            const nextH = findNextStructuralHeading(body, afterPos);
-            if (nextH !== -1) {
-                return body.slice(0, afterPos) + '\n\n' + content + '\n' + body.slice(nextH);
-            }
-            return body.slice(0, afterPos) + '\n\n' + content + '\n';
-        }
-        if (insertBefore) {
-            const beforeIdx = body.indexOf(insertBefore);
-            if (beforeIdx >= 0) {
-                return body.slice(0, beforeIdx) + heading + '\n\n' + content + '\n\n' + body.slice(beforeIdx);
-            }
-        }
-        return body + '\n\n' + heading + '\n\n' + content + '\n';
-    }
-    function insertSessionLog(body, entry) {
-        const slHeader = '## Session Log';
-        const slIdx = body.indexOf(slHeader);
-        if (slIdx >= 0) {
-            const insertPos = slIdx + slHeader.length;
-            return body.slice(0, insertPos) + '\n\n' + entry + '\n' + body.slice(insertPos);
-        }
-        return body + '\n\n' + slHeader + '\n\n' + entry + '\n';
-    }
-    function appendToSection(body, heading, content) {
-        const idx = body.indexOf(heading);
-        if (idx >= 0) {
-            const afterPos = idx + heading.length;
-            const nextH = findNextStructuralHeading(body, afterPos);
-            if (nextH !== -1) {
-                return body.slice(0, afterPos) + body.slice(afterPos, nextH) + '\n' + content + body.slice(nextH);
-            }
-            return body.slice(0, afterPos) + body.slice(afterPos) + '\n' + content + '\n';
-        }
-        return body + '\n\n' + heading + '\n\n' + content + '\n';
-    }
-    function applyUpdateFields(fm, body, fields) {
-        if (fields.status !== undefined)
-            fm.status = fields.status;
-        if (fields.current_state !== undefined) {
-            body = replaceSection(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 = insertSessionLog(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)
-            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 = replaceSection(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() {
@@ -298,171 +83,190 @@ 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)
             throw new HafezError('NOT_FOUND', `Entity or knowledge '${slug}' not found`);
         const parsed = parseFilePath(filePath);
+        // findFile only resolves the indexed kinds, so the session arm is unreachable
+        const kind = parsed.kind === 'session' ? 'knowledge' : parsed.kind;
         const frontmatter = parsed.frontmatter;
         const body = parsed.body;
         if (depth === 'frontmatter')
-            return { frontmatter, body: '' };
+            return { kind, frontmatter, body: '' };
         if (depth === 'summary') {
-            const sessionLogIdx = body.indexOf('## Session Log');
-            return { frontmatter, body: sessionLogIdx >= 0 ? body.slice(0, sessionLogIdx).trim() : body };
+            return { kind, frontmatter, body: documentForFile(parsed).bodyBeforeSessionLog(body) };
         }
-        return { frontmatter, body };
+        return { kind, frontmatter, body };
     }
-    async function create(kind, name, fields) {
-        if (readOnly)
-            throw new HafezError('VALIDATION_FAILED', 'Hafez instance is read-only');
-        return withLock(async () => {
-            const slug = slugify(name);
-            if (exists(slug))
-                throw new HafezError('SLUG_EXISTS', `Slug '${slug}' already exists`);
-            if (kind === 'entity') {
-                const ef = fields;
-                const fm = buildEntityFrontmatter(name, ef);
-                let body = buildEntityBody(ef);
-                const filePath = entityPath(slug);
-                mkdirSync(join(vaultPath, 'entities'), { recursive: true });
-                body = syncRelatedSection(body, fm);
-                writeFileSync(filePath, serializeFile(fm, body));
-                await gitCommitAndPush(vaultPath, [relative(vaultPath, filePath)], `create: ${name}`, gitConfig);
-                getIndex().upsertFromFile(slug, 'entity');
-                onWrite?.(slug, 'create');
+    function rollbackFiles(originals) {
+        for (const [path, content] of originals) {
+            if (content === null) {
+                try {
+                    unlinkSync(path);
+                }
+                catch { }
             }
             else {
-                const kf = (fields || {});
-                const fm = buildKnowledgeFrontmatter(name, kf);
-                let body = knowledgeBodyTemplate(kf.subtype, { synthesis: kf.synthesis });
-                const filePath = knowledgePath(slug);
-                mkdirSync(join(vaultPath, 'knowledge'), { recursive: true });
-                body = syncRelatedSection(body, fm);
-                writeFileSync(filePath, serializeFile(fm, body));
-                await gitCommitAndPush(vaultPath, [relative(vaultPath, filePath)], `create: ${name}`, gitConfig);
-                getIndex().upsertFromFile(slug, 'knowledge');
-                onWrite?.(slug, 'create');
+                writeFileSync(path, content);
             }
-            regenerateIndexSafe();
-            return slug;
-        });
+        }
     }
-    async function capture(name, notes) {
-        if (readOnly)
-            throw new HafezError('VALIDATION_FAILED', 'Hafez instance is read-only');
-        return withLock(async () => {
-            const slug = slugify(name);
-            if (exists(slug))
-                throw new HafezError('SLUG_EXISTS', `Slug '${slug}' already exists`);
-            const fm = {
-                name,
-                type: 'capture',
-                status: 'active',
-                created: today(),
-                'last-touched': today(),
-            };
-            const body = bodyTemplate('capture', { notes });
-            const filePath = entityPath(slug);
-            mkdirSync(join(vaultPath, 'entities'), { recursive: true });
-            writeFileSync(filePath, serializeFile(fm, body));
-            await gitCommitAndPush(vaultPath, [relative(vaultPath, filePath)], `capture: ${name}`, gitConfig);
-            getIndex().upsertFromFile(slug, 'entity');
-            regenerateIndexSafe();
-            onWrite?.(slug, 'capture');
-            return slug;
-        });
+    // All SQLite writes happen here, strictly after the git commit succeeded.
+    // A failed commit rolls back files only — the index was never touched, so
+    // files, git, and index stay consistent (pre-collapse, promote removed its
+    // index row mid-apply and a rollback lost it).
+    function updateIndexPostCommit(applied) {
+        for (const a of applied) {
+            for (const slug of a.indexRemovals)
+                getIndex().removeItem(slug);
+            for (const u of a.indexUpserts)
+                getIndex().upsertFromFile(u.slug, u.kind);
+        }
     }
-    async function update(slug, fields) {
+    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 () => {
-            const filePath = findFile(slug);
-            if (!filePath)
-                throw new HafezError('NOT_FOUND', `'${slug}' not found`);
-            const kind = kindFromPath(filePath);
-            validateKindFields(kind, fields);
-            let { frontmatter: fm, body } = parseFilePath(filePath);
-            const applied = applyUpdateFields(fm, body, fields);
-            fm = applied.fm;
-            body = applied.body;
-            // Session log archival
-            if (countSessionLogEntries(body) >= 10) {
-                const extracted = extractOldestSessionLogEntry(body);
-                if (extracted) {
-                    const archiveDir = join(vaultPath, 'entities', 'archive');
-                    mkdirSync(archiveDir, { recursive: true });
-                    const archivePath = join(archiveDir, `${slug}-log.md`);
-                    appendFileSync(archivePath, extracted.entry + '\n\n');
-                    body = extracted.remaining;
+            // 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)];
-            const archivePath = join(vaultPath, 'entities', 'archive', `${slug}-log.md`);
-            if (existsSync(archivePath))
-                files.push(relative(vaultPath, archivePath));
-            await gitCommitAndPush(vaultPath, files, `update: ${slug}`, gitConfig);
-            getIndex().upsertFromFile(slug, kind);
-            regenerateIndexSafe();
-            onWrite?.(slug, 'update');
-            return { matched_action: applied.matchedAction };
-        });
-    }
-    async function link(slug, target, relation) {
-        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`);
-            if (!exists(target))
-                throw new HafezError('VALIDATION_FAILED', `Target '${target}' does not exist`);
-            let { frontmatter: fm, body } = parseFilePath(filePath);
-            if (relation === 'parent') {
-                fm.parent = target;
+            // 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);
+                }
             }
-            else {
-                const related = fm.related || [];
-                if (!related.includes(target))
-                    related.push(target);
-                fm.related = related;
+            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);
+                }
             }
-            body = syncRelatedSection(body, fm);
-            writeFileSync(filePath, serializeFile(fm, body));
-            await gitCommitAndPush(vaultPath, [relative(vaultPath, filePath)], `link: ${slug} → ${target} (${relation})`, gitConfig);
-            const kind = kindFromPath(filePath);
-            getIndex().upsertFromFile(slug, kind);
-            regenerateIndexSafe();
-            onWrite?.(slug, 'link');
-        });
-    }
-    async function unlink(slug, target, relation) {
-        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`);
-            let { frontmatter: fm, body } = parseFilePath(filePath);
-            if (relation === 'parent' && fm.parent === target) {
-                delete fm.parent;
+            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;
             }
-            else if (relation === 'related' && fm.related) {
-                fm.related = fm.related.filter((r) => r !== target);
-                if (fm.related.length === 0)
-                    delete fm.related;
+            // 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 (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));
-            await gitCommitAndPush(vaultPath, [relative(vaultPath, filePath)], `unlink: ${slug} ✕ ${target} (${relation})`, gitConfig);
-            const kind = kindFromPath(filePath);
-            getIndex().upsertFromFile(slug, kind);
-            regenerateIndexSafe();
-            onWrite?.(slug, 'unlink');
+            return { applied, results };
         });
     }
+    async function create(kind, name, fields) {
+        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) {
+        const { applied } = await runMutations([{ op: 'capture', name, notes }], { action: 'capture' });
+        return applied[0].result.slug;
+    }
+    async function update(slug, fields) {
+        const { applied } = await runMutations([{ op: 'update', slug, fields }], { action: 'update' });
+        return { matched_action: applied[0].matchedAction };
+    }
+    async function link(slug, target, relation) {
+        await runMutations([{ op: 'link', slug, target, relation }], { action: 'link' });
+    }
+    async function unlink(slug, target, relation) {
+        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
     // files with no commit history yet. Without this the top-5 lists leak
@@ -478,8 +282,8 @@ export function createHafez(config) {
         const hasTies = new Set(candidates.map(day)).size < candidates.length;
         if (!hasTies)
             return rows.slice(0, 5);
-        const times = await gitFileTimes(vaultPath, mode);
-        const gitTime = (r) => times.get(`entities/${r.slug}.md`) ?? '';
+        const times = await journal.fileTimes(mode);
+        const gitTime = (r) => times.get(`${kindDir('entity')}/${r.slug}.md`) ?? '';
         candidates.sort((a, b) => {
             const dayCmp = day(b).localeCompare(day(a));
             if (dayCmp !== 0)
@@ -499,399 +303,100 @@ export function createHafez(config) {
         // slug → what it would be after earlier ops in this batch
         const simulated = new Map();
         const simulatedSessions = new Set();
-        const resolve = (slug) => {
-            const sim = simulated.get(slug);
-            if (sim)
-                return sim;
-            const fp = findFile(slug);
-            if (!fp)
-                return null;
-            const kind = kindFromPath(fp);
-            if (kind === 'knowledge')
-                return { kind, type: 'knowledge' };
-            try {
-                return { kind, type: parseFilePath(fp).frontmatter.type };
-            }
-            catch {
-                return { kind, type: 'entity' };
-            }
-        };
         const existsAnywhere = (slug) => simulated.has(slug) || exists(slug);
-        const report = [];
-        for (const [index, op] of operations.entries()) {
-            const errors = [];
-            let warning;
-            let slug;
-            let created = false;
-            const pushErr = (err) => {
-                const e = err;
-                errors.push(e.details?.length ? `${e.message}: ${e.details.join('; ')}` : e.message);
-            };
-            if (op.op === 'update') {
-                slug = op.slug;
-                const target = resolve(op.slug);
-                if (!target)
-                    errors.push(`'${op.slug}' not found`);
-                else {
+        // Vault context for the Op Spec table's semantic checks (src/batch-ops.ts).
+        const ctx = {
+            resolve: (slug) => {
+                const sim = simulated.get(slug);
+                if (sim)
+                    return sim;
+                const fp = findFile(slug);
+                if (!fp)
+                    return null;
+                const kind = kindFromPath(fp);
+                // 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 {
-                        validateKindFields(target.kind, op.fields);
+                        const pf = parseFilePath(fp);
+                        const subtype = pf.kind === 'knowledge' ? pf.frontmatter.subtype : undefined;
+                        return { kind, type: 'knowledge', subtype };
                     }
-                    catch (err) {
-                        pushErr(err);
-                    }
-                }
-                if (op.fields.session_log) {
-                    const logErrors = validateSessionLogEntry(op.fields.session_log);
-                    if (logErrors.length > 0)
-                        errors.push(`Invalid session log entry: ${logErrors.join('; ')}`);
-                }
-                if (op.fields.related) {
-                    for (const r of op.fields.related) {
-                        if (!existsAnywhere(r))
-                            errors.push(`Related slug '${r}' does not exist`);
+                    catch {
+                        return { kind, type: 'knowledge' };
                     }
                 }
-            }
-            else if (op.op === 'create' && op.kind === 'session') {
-                slug = slugify(op.name);
-                if (exists(slug) || existsSync(join(vaultPath, 'sessions', `${slug}.md`)) || simulatedSessions.has(slug)) {
-                    warning = `session '${slug}' already exists — op will be skipped (batch continues)`;
-                }
-                else {
-                    simulatedSessions.add(slug);
-                    created = true;
-                }
-            }
-            else if (op.op === 'create') {
-                slug = slugify(op.name);
-                if (existsAnywhere(slug))
-                    errors.push(`Slug '${slug}' already exists`);
-                if (op.kind === 'entity') {
-                    try {
-                        buildEntityFrontmatter(op.name, op.fields, existsAnywhere);
-                    }
-                    catch (err) {
-                        pushErr(err);
-                    }
-                    simulated.set(slug, { kind: 'entity', type: op.fields.type });
+                try {
+                    const pf = parseFilePath(fp);
+                    return { kind, type: pf.kind === 'entity' ? pf.frontmatter.type : 'entity' };
                 }
-                else {
-                    try {
-                        buildKnowledgeFrontmatter(op.name, (op.fields || {}), existsAnywhere);
-                    }
-                    catch (err) {
-                        pushErr(err);
-                    }
-                    simulated.set(slug, { kind: 'knowledge', type: 'knowledge' });
+                catch {
+                    return { kind, type: 'entity' };
                 }
-                created = errors.length === 0;
-            }
-            else if (op.op === 'capture') {
-                slug = slugify(op.name);
-                if (existsAnywhere(slug))
-                    errors.push(`Slug '${slug}' already exists`);
-                simulated.set(slug, { kind: 'entity', type: 'capture' });
-                created = errors.length === 0;
-            }
-            else if (op.op === 'link') {
-                slug = op.slug;
-                if (!resolve(op.slug))
-                    errors.push(`'${op.slug}' not found`);
-                if (!existsAnywhere(op.target))
-                    errors.push(`Target '${op.target}' does not exist`);
-            }
-            else if (op.op === 'unlink') {
-                slug = op.slug;
-                if (!resolve(op.slug))
-                    errors.push(`'${op.slug}' not found`);
-            }
-            else {
-                // promote
-                slug = op.slug;
-                const cur = resolve(op.slug);
-                if (!cur)
-                    errors.push(`'${op.slug}' not found`);
-                else {
-                    const currentType = cur.kind === 'knowledge' ? 'knowledge' : cur.type;
-                    try {
-                        const contract = getContract(currentType);
-                        if (!contract.canPromoteTo.includes(op.target)) {
-                            errors.push(`Cannot promote ${currentType} to ${op.target}. Valid targets: ${contract.canPromoteTo.join(', ') || 'none (terminal type)'}`);
-                        }
-                        else {
-                            simulated.set(op.slug, op.target === 'knowledge' ? { kind: 'knowledge', type: 'knowledge' } : { kind: 'entity', type: op.target });
-                        }
-                    }
-                    catch (err) {
-                        pushErr(err);
-                    }
+            },
+            existsAnywhere,
+            sessionExists: (slug) => existsSync(join(vaultPath, kindDir('session'), `${slug}.md`)) || simulatedSessions.has(slug),
+            simulate: (slug, info) => { simulated.set(slug, info); },
+            simulateSession: (slug) => { simulatedSessions.add(slug); },
+            validateKindFields,
+            validateSessionLogEntry: (entry) => validateSessionLogEntry(entry),
+            buildEntityFrontmatter: (name, fields) => { buildEntityFrontmatter(name, fields, existsAnywhere); },
+            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) : '';
+                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';
                 }
-            }
-            const entry = { index, op: op.op, slug, errors };
-            if (created)
+                report.push(entry);
+                continue;
+            }
+            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 (warning)
-                entry.warning = warning;
+            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 modifiedFiles = [];
-            const affectedSlugs = [];
-            const results = [];
-            let currentOp = -1;
-            try {
-                for (const op of operations) {
-                    currentOp++;
-                    if (op.op === 'update') {
-                        const filePath = findFile(op.slug);
-                        if (!filePath)
-                            throw new HafezError('VALIDATION_FAILED', `'${op.slug}' not found`);
-                        captureOriginal(filePath);
-                        validateKindFields(kindFromPath(filePath), op.fields);
-                        const { frontmatter: fm, body } = parseFilePath(filePath);
-                        const applied = applyUpdateFields(fm, body, op.fields);
-                        applied.body = syncRelatedSection(applied.body, applied.fm);
-                        writeFileSync(filePath, serializeFile(applied.fm, applied.body));
-                        modifiedFiles.push(relative(vaultPath, filePath));
-                        affectedSlugs.push(op.slug);
-                        results.push({ op: 'update', slug: op.slug, status: 'ok' });
-                    }
-                    else if (op.op === 'create' && op.kind === 'session') {
-                        const slug = slugify(op.name);
-                        if (exists(slug)) {
-                            results.push({ op: 'create', slug, status: 'error', error: `Slug '${slug}' already exists in the vault` });
-                            continue;
-                        }
-                        const sessionDir = join(vaultPath, 'sessions');
-                        mkdirSync(sessionDir, { recursive: true });
-                        const filePath = join(sessionDir, `${slug}.md`);
-                        if (existsSync(filePath)) {
-                            results.push({ op: 'create', slug, status: 'error', error: `Session '${slug}' already exists` });
-                            continue;
-                        }
-                        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));
-                        modifiedFiles.push(relative(vaultPath, filePath));
-                        // Sessions are not indexed (db.ts only scans entities/ and knowledge/).
-                        // They ARE included in git semantic merge (git.ts VAULT_FILE_RE).
-                        results.push({ op: 'create', slug, status: 'ok', created: true });
-                    }
-                    else if (op.op === 'create') {
-                        const slug = slugify(op.name);
-                        if (exists(slug))
-                            throw new HafezError('VALIDATION_FAILED', `Slug '${slug}' already exists`);
-                        if (op.kind === 'entity') {
-                            const ef = op.fields;
-                            const fm = buildEntityFrontmatter(op.name, ef);
-                            let entBody = buildEntityBody(ef);
-                            const filePath = entityPath(slug);
-                            captureOriginal(filePath);
-                            mkdirSync(join(vaultPath, 'entities'), { recursive: true });
-                            entBody = syncRelatedSection(entBody, fm);
-                            writeFileSync(filePath, serializeFile(fm, entBody));
-                            modifiedFiles.push(relative(vaultPath, filePath));
-                            affectedSlugs.push(slug);
-                            results.push({ op: 'create', slug, status: 'ok', created: true });
-                        }
-                        else {
-                            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, 'knowledge'), { recursive: true });
-                            body = syncRelatedSection(body, fm);
-                            writeFileSync(filePath, serializeFile(fm, body));
-                            modifiedFiles.push(relative(vaultPath, filePath));
-                            affectedSlugs.push(slug);
-                            results.push({ op: 'create', slug, status: 'ok', created: true });
-                        }
-                    }
-                    else if (op.op === 'capture') {
-                        const slug = slugify(op.name);
-                        if (exists(slug))
-                            throw new HafezError('VALIDATION_FAILED', `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, 'entities'), { recursive: true });
-                        writeFileSync(filePath, serializeFile(fm, bodyTemplate('capture', { notes: op.notes })));
-                        modifiedFiles.push(relative(vaultPath, filePath));
-                        affectedSlugs.push(slug);
-                        results.push({ op: 'capture', slug, status: 'ok', created: true });
-                    }
-                    else if (op.op === 'link') {
-                        const filePath = findFile(op.slug);
-                        if (!filePath)
-                            throw new HafezError('VALIDATION_FAILED', `'${op.slug}' not found`);
-                        if (!exists(op.target))
-                            throw new HafezError('VALIDATION_FAILED', `Target '${op.target}' does not exist`);
-                        captureOriginal(filePath);
-                        let { frontmatter: fm, body } = parseFilePath(filePath);
-                        if (op.relation === 'parent') {
-                            fm.parent = op.target;
-                        }
-                        else {
-                            const related = fm.related || [];
-                            if (!related.includes(op.target))
-                                related.push(op.target);
-                            fm.related = related;
-                        }
-                        body = syncRelatedSection(body, fm);
-                        writeFileSync(filePath, serializeFile(fm, body));
-                        modifiedFiles.push(relative(vaultPath, filePath));
-                        affectedSlugs.push(op.slug);
-                        results.push({ op: 'link', slug: op.slug, status: 'ok' });
-                    }
-                    else if (op.op === 'unlink') {
-                        const filePath = findFile(op.slug);
-                        if (!filePath)
-                            throw new HafezError('VALIDATION_FAILED', `'${op.slug}' not found`);
-                        captureOriginal(filePath);
-                        let { frontmatter: fm, body } = parseFilePath(filePath);
-                        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;
-                        }
-                        body = syncRelatedSection(body, fm);
-                        writeFileSync(filePath, serializeFile(fm, body));
-                        modifiedFiles.push(relative(vaultPath, filePath));
-                        affectedSlugs.push(op.slug);
-                        results.push({ op: 'unlink', slug: op.slug, status: 'ok' });
-                    }
-                    else if (op.op === 'promote') {
-                        const filePath = findFile(op.slug);
-                        if (!filePath)
-                            throw new HafezError('VALIDATION_FAILED', `'${op.slug}' not found`);
-                        captureOriginal(filePath);
-                        if (op.target === 'knowledge') {
-                            captureOriginal(knowledgePath(op.slug));
-                        }
-                        const kind = kindFromPath(filePath);
-                        const { frontmatter: fm, body } = parseFilePath(filePath);
-                        const { modifiedFiles: promoteFiles } = promoteCore(op.slug, op.target, filePath, fm, body, kind);
-                        modifiedFiles.push(...promoteFiles);
-                        affectedSlugs.push(op.slug);
-                        results.push({ op: 'promote', slug: op.slug, status: 'ok' });
-                    }
-                }
-            }
-            catch (err) {
-                // Rollback all modified files
-                for (const [path, content] of originals) {
-                    if (content === null) {
-                        try {
-                            unlinkSync(path);
-                        }
-                        catch { }
-                    }
-                    else {
-                        writeFileSync(path, content);
-                    }
-                }
-                // 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 git commit for all batch operations
-            const uniqueFiles = [...new Set(modifiedFiles)];
-            const indexAfterBatch = () => {
-                for (const slug of affectedSlugs) {
-                    const fp = findFile(slug);
-                    if (fp) {
-                        getIndex().upsertFromFile(slug, kindFromPath(fp));
-                    }
-                }
-                // Regenerate vault index if any entity or knowledge was touched (session-only batches skip)
-                const anyIndexedTouched = uniqueFiles.some(f => f.startsWith('knowledge/') || f.startsWith('entities/'));
-                if (anyIndexedTouched) {
-                    regenerateIndexSafe();
-                }
-                for (const slug of affectedSlugs)
-                    onWrite?.(slug, 'batch');
-            };
-            if (uniqueFiles.length > 0) {
-                try {
-                    await gitCommitAndPush(vaultPath, uniqueFiles, `batch: ${operations.length} operations`, gitConfig);
-                }
-                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, git, and
-                        // index stay consistent instead of leaving the batch half-applied.
-                        for (const [path, content] of originals) {
-                            if (content === null) {
-                                try {
-                                    unlinkSync(path);
-                                }
-                                catch { }
-                            }
-                            else {
-                                writeFileSync(path, content);
-                            }
-                        }
-                        // Also clear anything the failed commit left staged, or the next
-                        // commit would publish the rolled-back content.
-                        await gitUnstage(vaultPath, uniqueFiles);
-                        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 = {
@@ -906,16 +411,16 @@ export function createHafez(config) {
         const knowledgeSlugs = new Set();
         const referencedKnowledge = new Set();
         // Scan entities
-        const entDir = join(vaultPath, 'entities');
-        if (existsSync(entDir)) {
-            const files = readdirSync(entDir).filter(f => f.endsWith('.md'));
+        const entDir = join(vaultPath, kindDir('entity'));
+        {
+            const files = scanVaultDir(entDir);
             report.total_entities = files.length;
-            for (const file of files) {
-                const slug = basename(file, '.md');
+            for (const filePath of files) {
+                const slug = basename(filePath, '.md');
                 allSlugs.add(slug);
                 let fm;
                 try {
-                    fm = parseFilePath(join(entDir, file)).frontmatter;
+                    fm = parseFilePath(filePath).frontmatter;
                 }
                 catch {
                     report.missing_fields.push({ slug, field: '', issue: 'failed to parse frontmatter' });
@@ -939,17 +444,17 @@ export function createHafez(config) {
             }
         }
         // Scan knowledge
-        const knDir = join(vaultPath, 'knowledge');
-        if (existsSync(knDir)) {
-            const files = readdirSync(knDir).filter(f => f.endsWith('.md'));
+        const knDir = join(vaultPath, kindDir('knowledge'));
+        {
+            const files = scanVaultDir(knDir);
             report.total_knowledge = files.length;
-            for (const file of files) {
-                const slug = basename(file, '.md');
+            for (const filePath of files) {
+                const slug = basename(filePath, '.md');
                 allSlugs.add(slug);
                 knowledgeSlugs.add(slug);
                 let fm;
                 try {
-                    fm = parseFilePath(join(knDir, file)).frontmatter;
+                    fm = parseFilePath(filePath).frontmatter;
                 }
                 catch {
                     report.missing_fields.push({ slug, field: '', issue: 'failed to parse frontmatter' });
@@ -982,110 +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 = [];
-        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.
-            modifiedFiles.push(relative(vaultPath, filePath));
-            getIndex().removeItem(slug);
-        }
-        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 };
-    }
     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`);
-            const kind = kindFromPath(filePath);
-            // Capture original content for rollback before parsing (avoids double read)
-            const originalContent = target === 'knowledge' ? readFileSync(filePath, 'utf-8') : null;
-            const knowledgeTarget = target === 'knowledge' ? knowledgePath(slug) : null;
-            const { frontmatter: fm, body } = parseFilePath(filePath);
-            const sourceType = kind === 'knowledge' ? 'knowledge' : fm.type;
-            try {
-                const { modifiedFiles } = promoteCore(slug, target, filePath, fm, body, kind);
-                await gitCommitAndPush(vaultPath, modifiedFiles, `promote: ${slug} ${sourceType} → ${target}`, gitConfig);
-                getIndex().upsertFromFile(slug, target === 'knowledge' ? 'knowledge' : 'entity');
-                regenerateIndexSafe();
-                onWrite?.(slug, 'promote');
-            }
-            catch (err) {
-                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;
-            }
-            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 },
@@ -1097,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(() => gitSync(vaultPath));
-        },
-        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);
+            return withLock(() => journal.sync());
         },
+        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();
@@ -1161,10 +549,9 @@ export function createHafez(config) {
             s.recently_created = await rankRecents(s.recently_created, 'created', 'added');
             return s;
         },
-        changelog: (since) => gitChangelog(vaultPath, since),
+        changelog: (since) => journal.changelog(since),
     };
 }
 export { HafezError } from './types.js';
-export { getBrief, getNextActions, findSection } from './sections.js';
-export { parseSessionLogHeading, parseSessionLog } from './parser.js';
-export { formatStats, formatChangelog, formatValidation } from './cli/format.js';
+export { getBrief, getNextActions } from './document.js';
+export { parseSessionLogHeading, parseSessionLog } from './document.js';