hafez 1.2.0 → 1.4.0

package/dist/apply.js

@@ -0,0 +1,582 @@
+// src/apply.ts
+// Apply (see CONTEXT.md): the Spine's apply stage — one arm per Op Spec row,
+// behind a dispatch table keyed by the same names. The table's key type is
+// derived from the Op Spec's, so a spec row with no arm here fails to build:
+// adding an op is one Op Spec entry plus one entry in APPLY.
+//
+// Apply trusts the Spine: every semantic gate ran exactly once, in the
+// validate phase (the Op Spec's check), so no arm re-checks a rule. Branches
+// validation has ruled out are bare internal throws — a Spine bug must be loud
+// in the test suite, not masquerade as caller error. The branches that are
+// NOT internal are the two directions of the validate→apply race, where an
+// external actor removed a file the op resolved (vanished()) or created one
+// the op claimed (appeared()); both throw caller-facing.
+//
+// Apply owns every vault-file write and nothing else — it touches neither git
+// nor SQLite. The Spine commits [...filesWritten, ...filesDeleted] under
+// commitMessage and runs the index updates afterwards. The Op Spec table stays
+// pure (no filesystem access); the frontmatter builders live here and are
+// exported so the batch validate phase can run them against a simulated vault.
+import { writeFileSync, existsSync, mkdirSync, appendFileSync, unlinkSync } from 'fs';
+import { join, relative, dirname } from 'path';
+import { parseFilePath, serializeFile, slugify, resolveFilePath, kindFromPath, kindDir, archiveLogPath, findVaultFile, vaultFileExists } from './vault.js';
+import { validateEntityFrontmatter, validateKnowledgeFrontmatter } from './schema.js';
+import { bodyTemplate, knowledgeBodyTemplate, sessionBodyTemplate } from './templates.js';
+import { formatSessionLogEntry, documentFor, documentForFile } from './document.js';
+import { sectionsFor, statusesFor, unreachableFields, describeTarget } from './contracts.js';
+import { localDay } from './dates.js';
+import { specFor } from './batch-ops.js';
+import { HafezError } from './types.js';
+/** A vault file that validation resolved but is gone at apply time. The vault
+ * lock excludes other hafez processes, not external actors (Obsidian, a hand
+ * rm, a git checkout), so unlike a branch validation has truly ruled out —
+ * which would stay a bare internal throw, loud in the test suite — this is a
+ * recoverable race: a caller-facing NOT_FOUND naming the actionable fact, and
+ * a HafezError so batch mode keeps its op[i] localisation. */
+function vanished(slug) {
+    throw new HafezError('NOT_FOUND', `'${slug}' vanished after validation — something outside hafez removed it; re-run`);
+}
+/** The mirror image: a vault file validation confirmed absent, but which
+ * exists at apply time. Same external actors, same window — and a create arm
+ * that wrote anyway would overwrite a file hafez never saw, which rollback
+ * only undoes when some LATER op in the batch happens to fail. Guarding one
+ * direction of the race and not the other reads as intentional to the next
+ * person, so both directions throw. */
+function appeared(slug) {
+    throw new HafezError('SLUG_EXISTS', `'${slug}' appeared after validation — something outside hafez created it; nothing was overwritten, re-run`);
+}
+function entityPath(vaultPath, slug) { return resolveFilePath(vaultPath, slug, 'entity'); }
+function knowledgePath(vaultPath, slug) { return resolveFilePath(vaultPath, slug, 'knowledge'); }
+function today() { return localDay(); }
+// --- Field policy ---
+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'];
+// An entity-only field is still reachable on a knowledge note when THAT
+// note's contract declares the capability the field needs. The gate asks the
+// contract (contracts.ts), not the field name, so the plan/insight split is
+// one table entry rather than a special case threaded through the paths.
+const KNOWLEDGE_FIELD_CAPABILITY = {
+    status: t => statusesFor(t).length > 0,
+};
+/** Reject a status the target's contract does not define (a plan has no
+ * 'paused'; an insight has no status at all). One check for create and
+ * update alike. */
+function assertStatusAllowed(target, status) {
+    const allowed = statusesFor(target);
+    if (allowed.length === 0) {
+        throw new HafezError('VALIDATION_FAILED', `Cannot set status on ${describeTarget(target)}: status is plan-subtype only`);
+    }
+    if (!allowed.includes(status)) {
+        throw new HafezError('VALIDATION_FAILED', `Invalid status '${status}' for ${describeTarget(target)} (expected: ${allowed.join(', ')})`);
+    }
+}
+/** Content-field policy: reject, never route, never drop. A create field
+ * writes into a named body section; when the chosen template has no such
+ * section the text would vanish on write, so the op fails loudly instead.
+ * Generic over the (template, field) pair — see contracts.unreachableFields. */
+function assertFieldsReachable(target, fields) {
+    const unreachable = unreachableFields(target, fields);
+    if (unreachable.length === 0)
+        return;
+    const named = unreachable.map(u => `'${u.field}' (needs a '## ${u.section}' section)`).join(', ');
+    throw new HafezError('VALIDATION_FAILED', `Cannot set ${named} on ${describeTarget(target)} — its template has no such section, and text is never silently dropped. Sections available: ${sectionsFor(target).join(', ')}`);
+}
+export function validateKindFields(kind, fields, subtype) {
+    if (kind === 'knowledge') {
+        const target = { kind: 'knowledge', subtype };
+        const invalid = ENTITY_ONLY_FIELDS.filter(f => fields[f] !== undefined && !(KNOWLEDGE_FIELD_CAPABILITY[f]?.(target) ?? false));
+        if (invalid.length > 0) {
+            throw new HafezError('VALIDATION_FAILED', `Cannot set entity-only fields on knowledge note: ${invalid.join(', ')}`);
+        }
+        if (fields.status !== undefined)
+            assertStatusAllowed(target, fields.status);
+    }
+    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(', ')}`);
+        }
+    }
+}
+// --- Builders ---
+// Shared by the create arms and the batch validate phase so optional fields
+// can't silently diverge between paths (see CLAUDE.md Validation Gotchas).
+// `existsFn` is the caller's: apply passes the real vault, validateBatchCore a
+// simulation-aware check (same-batch creates count as existing).
+export function buildEntityFrontmatter(name, ef, existsFn) {
+    assertFieldsReachable({ kind: 'entity', type: ef.type }, ef);
+    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;
+}
+// Body-side optional fields (brief, actions) must behave identically in both
+// paths, like buildEntityFrontmatter's.
+function buildEntityBody(ef) {
+    const doc = documentFor({ kind: 'entity' });
+    let body = bodyTemplate(ef.type, { purpose: ef.purpose });
+    if (ef.brief)
+        body = doc.setBrief(body, ef.brief);
+    if (ef.add_action !== undefined)
+        body = doc.addNextAction(body, ef.add_action);
+    for (const action of ef.add_actions ?? [])
+        body = doc.addNextAction(body, action);
+    return body;
+}
+export function buildKnowledgeFrontmatter(name, kf, existsFn) {
+    const target = { kind: 'knowledge', subtype: kf.subtype };
+    assertFieldsReachable(target, kf);
+    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;
+    if (kf.status !== undefined) {
+        // Plans are tracked work: they carry a lifecycle and therefore a
+        // last-touched day, exactly like entities do.
+        assertStatusAllowed(target, kf.status);
+        fm.status = kf.status;
+        fm['last-touched'] = today();
+    }
+    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;
+}
+// Pure field application, like every arm above it: the Spine has already run
+// Op Spec validation (shape + semantics). `doc` is the Document bound to the
+// file's kind (see documentFor).
+function applyUpdateFields(doc, fm, body, fields) {
+    if (fields.status !== undefined)
+        fm.status = fields.status;
+    if (fields.current_state !== undefined) {
+        body = doc.setSection(body, 'Current State', fields.current_state, 'Session Log');
+    }
+    if (fields.brief !== undefined) {
+        body = fields.brief === null ? doc.removeBrief(body) : doc.setBrief(body, fields.brief);
+    }
+    let matchedAction;
+    if (fields.add_action !== undefined)
+        body = doc.addNextAction(body, fields.add_action);
+    if (fields.add_actions !== undefined) {
+        for (const action of fields.add_actions) {
+            body = doc.addNextAction(body, action);
+        }
+    }
+    if (fields.complete_action !== undefined) {
+        const r = doc.completeNextAction(body, fields.complete_action);
+        body = r.body;
+        matchedAction = r.matched;
+    }
+    if (fields.remove_action !== undefined) {
+        const r = doc.removeNextAction(body, fields.remove_action);
+        body = r.body;
+        matchedAction = r.matched;
+    }
+    if (fields.clear_actions)
+        body = doc.clearNextActions(body);
+    if (fields.session_log) {
+        body = doc.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)
+        fm.confidence = fields.confidence;
+    if (fields.tags !== undefined)
+        fm.tags = fields.tags;
+    if (fields.related !== undefined)
+        fm.related = fields.related;
+    if (fields.synthesis !== undefined) {
+        body = doc.setSection(body, 'Synthesis', fields.synthesis);
+    }
+    if (fields.add_evidence !== undefined) {
+        const sanitized = fields.add_evidence.replace(/^#{1,2}\s/gm, '### ');
+        body = doc.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 !== undefined) {
+        body = doc.appendToSection(body, 'Sources', fields.add_source);
+    }
+    if (fm['last-touched'] !== today())
+        fm['last-touched'] = today();
+    return { fm, body, matchedAction };
+}
+function promoteCore(ctx, slug, target, filePath, fm, body, kind) {
+    const { vaultPath } = ctx;
+    const currentType = kind === 'knowledge' ? 'knowledge' : fm.type;
+    const modifiedFiles = [];
+    const deletedFiles = [];
+    if (target === 'knowledge') {
+        // Cross-kind: move file from entities/ to knowledge/. The source body
+        // is read under the entity Document binding.
+        const sourceDoc = documentFor({ kind: 'entity' });
+        const newPath = knowledgePath(vaultPath, slug);
+        // Promote must behave like create AT THE TARGET. A diverged vault can
+        // hold the same slug as both an entity and a knowledge note (findFile
+        // resolves entities first, so the validate phase sees only the entity);
+        // without this check the write below silently destroys the note.
+        if (existsSync(newPath)) {
+            throw new HafezError('SLUG_EXISTS', `Slug '${slug}' already exists in ${kindDir('knowledge')}/`);
+        }
+        const notesSection = sourceDoc.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 = documentFor({ kind: 'knowledge' }).syncRelatedSection(knBody, newFm);
+        // An entities-only vault has no knowledge/ yet — create it like the
+        // create-knowledge arm does, and map any fs failure onto a HafezError
+        // so no raw ENOENT/ENOTDIR escapes the promote path.
+        try {
+            mkdirSync(join(vaultPath, kindDir('knowledge')), { recursive: true });
+            writeFileSync(newPath, serializeFile(newFm, finalBody));
+            unlinkSync(filePath);
+        }
+        catch (err) {
+            throw new HafezError('VALIDATION_FAILED', `Failed to promote '${slug}' to knowledge: ${err instanceof Error ? err.message : String(err)}`);
+        }
+        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();
+        // All body reshaping goes through Document — structural sections only,
+        // so quoted heading mentions inside content can no longer suppress or
+        // hijack the splice points.
+        const doc = documentFor({ kind: 'entity' });
+        let newBody = body;
+        if (target === 'entity') {
+            newBody = doc.renameSection(newBody, 'Notes', 'Context');
+        }
+        else {
+            // project
+            newBody = doc.renameSection(newBody, 'Notes', 'Purpose');
+            newBody = doc.renameSection(newBody, 'Context', 'Purpose');
+            newBody = doc.ensureSection(newBody, 'Goals', { after: 'Purpose' });
+        }
+        newBody = doc.prependSessionLogEntry(newBody, formatSessionLogEntry({
+            type: 'decision',
+            agent: 'system',
+            summary: `Promoted from ${currentType} to ${target}`,
+        }));
+        newBody = doc.syncRelatedSection(newBody, fm);
+        writeFileSync(filePath, serializeFile(fm, newBody));
+        modifiedFiles.push(relative(vaultPath, filePath));
+    }
+    return { modifiedFiles, deletedFiles };
+}
+// --- The arms ---
+function applyUpdate(op, ctx) {
+    const { vaultPath } = ctx;
+    const filePath = findVaultFile(vaultPath, op.slug) ?? vanished(op.slug);
+    ctx.captureOriginal(filePath);
+    const kind = kindFromPath(filePath);
+    const parsedFile = parseFilePath(filePath);
+    const doc = documentForFile(parsedFile);
+    let fm = parsedFile.frontmatter;
+    let body = parsedFile.body;
+    const applied = applyUpdateFields(doc, fm, body, op.fields);
+    fm = applied.fm;
+    body = applied.body;
+    // Session log archival
+    const archivePath = archiveLogPath(vaultPath, op.slug);
+    let archived = false;
+    if (doc.countSessionLogEntries(body) >= 10) {
+        const extracted = doc.extractOldestSessionLogEntry(body);
+        if (extracted) {
+            ctx.captureOriginal(archivePath);
+            mkdirSync(dirname(archivePath), { recursive: true });
+            appendFileSync(archivePath, extracted.entry + '\n\n');
+            body = extracted.remaining;
+            archived = true;
+        }
+    }
+    body = doc.syncRelatedSection(body, fm);
+    writeFileSync(filePath, serializeFile(fm, body));
+    // Only the files THIS update wrote. Keying off the archive file merely
+    // existing swept any external hand-edit sitting in entities/archive/
+    // into an unrelated commit.
+    const files = [relative(vaultPath, filePath)];
+    if (archived)
+        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,
+    };
+}
+function applyCreateEntity(op, ctx) {
+    const { vaultPath } = ctx;
+    const slug = slugify(op.name);
+    const ef = op.fields;
+    const fm = buildEntityFrontmatter(op.name, ef, s => vaultFileExists(vaultPath, s));
+    let body = buildEntityBody(ef);
+    const filePath = entityPath(vaultPath, slug);
+    // Re-checked against the same cross-kind test claimNew ran (vaultFileExists
+    // is the real-disk half of the Spine's existsAnywhere) — not a re-litigation
+    // of the rule, just the race window.
+    if (vaultFileExists(vaultPath, slug))
+        appeared(slug);
+    ctx.captureOriginal(filePath);
+    mkdirSync(join(vaultPath, kindDir('entity')), { recursive: true });
+    body = documentFor({ kind: 'entity' }).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' }],
+    };
+}
+function applyCreateKnowledge(op, ctx) {
+    const { vaultPath } = ctx;
+    const slug = slugify(op.name);
+    const kf = (op.fields || {});
+    const fm = buildKnowledgeFrontmatter(op.name, kf, s => vaultFileExists(vaultPath, s));
+    let body = knowledgeBodyTemplate(kf.subtype, { synthesis: kf.synthesis });
+    const filePath = knowledgePath(vaultPath, slug);
+    if (vaultFileExists(vaultPath, slug))
+        appeared(slug);
+    ctx.captureOriginal(filePath);
+    mkdirSync(join(vaultPath, kindDir('knowledge')), { recursive: true });
+    body = documentFor({ kind: 'knowledge' }).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' }],
+    };
+}
+function applyCreateSession(op, ctx) {
+    const { vaultPath } = ctx;
+    const slug = slugify(op.name);
+    // A slug taken at validate time never reaches here: that is the
+    // create-session spec's skip disposition (a warning, not an error), and the
+    // Spine synthesizes the result without calling Apply. One taken DURING the
+    // validate→apply window does reach here, and overwriting someone else's
+    // session note is worse than the error — so the race throws even though the
+    // ordinary duplicate warns. Mirrors the spec's own `existsAnywhere ||
+    // sessionExists` test.
+    const sessionDir = join(vaultPath, kindDir('session'));
+    mkdirSync(sessionDir, { recursive: true });
+    const filePath = join(sessionDir, `${slug}.md`);
+    if (existsSync(filePath) || vaultFileExists(vaultPath, slug))
+        appeared(slug);
+    ctx.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 sections come from contracts.SESSION_SECTIONS — the same list
+    // Document splits on, so the written body and the structural set agree.
+    let sessionBody = sessionBodyTemplate({ synthesis: kf.synthesis });
+    sessionBody = documentFor({ kind: 'session' }).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: [],
+    };
+}
+function applyCapture(op, ctx) {
+    const { vaultPath } = ctx;
+    const slug = slugify(op.name);
+    const fm = {
+        name: op.name,
+        type: 'capture',
+        status: 'active',
+        created: today(),
+        'last-touched': today(),
+    };
+    const filePath = entityPath(vaultPath, slug);
+    if (vaultFileExists(vaultPath, slug))
+        appeared(slug);
+    ctx.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' }],
+    };
+}
+function applyLink(op, ctx) {
+    const { vaultPath } = ctx;
+    const filePath = findVaultFile(vaultPath, op.slug) ?? vanished(op.slug);
+    ctx.captureOriginal(filePath);
+    const parsedFile = parseFilePath(filePath);
+    const fm = parsedFile.frontmatter;
+    let body = parsedFile.body;
+    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 = documentForFile(parsedFile).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) }],
+    };
+}
+function applyUnlink(op, ctx) {
+    const { vaultPath } = ctx;
+    const filePath = findVaultFile(vaultPath, op.slug) ?? vanished(op.slug);
+    ctx.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;
+    }
+    body = documentForFile(parsedFile).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) }],
+    };
+}
+function applyPromote(op, ctx) {
+    const { vaultPath } = ctx;
+    const filePath = findVaultFile(vaultPath, op.slug) ?? vanished(op.slug);
+    ctx.captureOriginal(filePath);
+    if (op.target === 'knowledge')
+        ctx.captureOriginal(knowledgePath(vaultPath, 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(ctx, 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' }],
+    };
+}
+const APPLY = {
+    'update': applyUpdate,
+    'create-entity': applyCreateEntity,
+    'create-knowledge': applyCreateKnowledge,
+    'create-session': applyCreateSession,
+    'capture': applyCapture,
+    'link': applyLink,
+    'unlink': applyUnlink,
+    'promote': applyPromote,
+};
+/** The single apply path for every mutation. Writes vault files but never
+ * touches git or SQLite: the Spine commits [...filesWritten, ...filesDeleted]
+ * under commitMessage (single ops) or one composed batch message, then runs
+ * the index updates. ctx.captureOriginal snapshots files for rollback before
+ * they change. */
+export function applyOperation(op, ctx) {
+    const arm = APPLY[specFor(op).name];
+    return arm(op, ctx);
+}