hafez 1.3.0 → 1.4.0

package/dist/knowledge-index.d.ts

@@ -1,3 +1,25 @@
+/** One indexed document, as the SQLite index can hand it over. index.md needs
+ * nothing the index does not already hold, so a regeneration reads rows
+ * instead of re-reading and re-parsing every file in the vault. Declared here
+ * (not in db.ts) to keep the module edge pointing one way: db.ts already
+ * imports from this file. */
+export interface VaultIndexRow {
+    slug: string;
+    kind: 'entity' | 'knowledge';
+    name: string;
+    type: string | null;
+    status: string | null;
+    confidence: string | null;
+    description: string | null;
+    domain: string[];
+    body: string;
+}
 /** Ensure every generated local-only artifact is covered by .git/info/exclude. */
 export declare function ensureLocalExclude(vaultPath: string): void;
-export declare function generateVaultIndex(vaultPath: string): void;
+/** Regenerate the vault-root index.md.
+ *
+ * `rows` is the SQLite index's view of the vault — every mutation refreshes
+ * those rows anyway, so passing them avoids a second full-vault read for the
+ * same content. Omitting them (standalone/one-off use) falls back to reading
+ * the files directly. */
+export declare function generateVaultIndex(vaultPath: string, rows?: VaultIndexRow[]): void;

package/dist/knowledge-index.js

@@ -2,10 +2,28 @@
 // Generates the vault-root index.md covering entities (grouped by status) and
 // knowledge (grouped by domain) — local-only, auto-regenerated on every entity/knowledge write.
 import { readFileSync, writeFileSync, existsSync, statSync, mkdirSync } from 'fs';
-import { join, basename } from 'path';
+import { join, basename, resolve } from 'path';
 import { parseFilePath, scanVaultDir, kindDir } from './vault.js';
 import { deriveSummary } from './document.js';
 import { ENTITY_STATUSES } from './contracts.js';
+/** Index rows in the shape the renderer below expects — the same
+ * {slug, fm, body} triple scanParsed produces from disk. */
+function fromRows(rows, kind) {
+    return rows
+        .filter(r => r.kind === kind)
+        .map(r => ({
+        slug: r.slug,
+        body: r.body,
+        fm: {
+            name: r.name,
+            type: r.type ?? undefined,
+            status: r.status ?? undefined,
+            confidence: r.confidence ?? undefined,
+            description: r.description ?? undefined,
+            domain: r.domain,
+        },
+    }));
+}
 function truncate(s) {
     return s.length > 100 ? s.slice(0, 97) + '...' : s;
 }
@@ -38,11 +56,42 @@ function scanParsed(dir) {
  * show up in the user's `git status`, but forcing a tracked .gitignore entry
  * would dirty their vault — so they go into .git/info/exclude instead. */
 const LOCAL_EXCLUDES = ['/index.md', '/.hafez.db', '/.hafez.db-shm', '/.hafez.db-wal'];
+/** Locate the git directory that owns `info/exclude` for this vault.
+ * `.git` is a directory in a normal clone, but a *gitfile* (`gitdir: <path>`)
+ * in a linked worktree or submodule — treating that file as "not a repo" is
+ * what let index.md and .hafez.db pollute `git status` there. Git reads
+ * `info/exclude` from the COMMON dir, so for a linked worktree the pointed-at
+ * per-worktree dir is one more hop from the answer: its `commondir` file names
+ * the shared dir (writing the exclude in the per-worktree dir has no effect).
+ * Returns null when the vault is not a git repo at all. */
+function resolveExcludeGitDir(vaultPath) {
+    const dotGit = join(vaultPath, '.git');
+    if (!existsSync(dotGit))
+        return null;
+    const stat = statSync(dotGit);
+    if (stat.isDirectory())
+        return dotGit;
+    if (!stat.isFile())
+        return null;
+    const pointer = /^gitdir:\s*(.+)$/m.exec(readFileSync(dotGit, 'utf-8'));
+    if (!pointer)
+        return null;
+    const gitDir = resolve(vaultPath, pointer[1].trim());
+    if (!existsSync(gitDir))
+        return null;
+    const commonDirFile = join(gitDir, 'commondir');
+    if (existsSync(commonDirFile)) {
+        const commonDir = resolve(gitDir, readFileSync(commonDirFile, 'utf-8').trim());
+        if (existsSync(commonDir))
+            return commonDir;
+    }
+    return gitDir;
+}
 /** Ensure every generated local-only artifact is covered by .git/info/exclude. */
 export function ensureLocalExclude(vaultPath) {
     try {
-        const gitDir = join(vaultPath, '.git');
-        if (!existsSync(gitDir) || !statSync(gitDir).isDirectory())
+        const gitDir = resolveExcludeGitDir(vaultPath);
+        if (!gitDir)
             return;
         const excludePath = join(gitDir, 'info', 'exclude');
         const existing = existsSync(excludePath) ? readFileSync(excludePath, 'utf-8') : '';
@@ -56,17 +105,24 @@ export function ensureLocalExclude(vaultPath) {
     }
     catch { /* best effort — never fail a vault write over ignore hygiene */ }
 }
-export function generateVaultIndex(vaultPath) {
+/** Regenerate the vault-root index.md.
+ *
+ * `rows` is the SQLite index's view of the vault — every mutation refreshes
+ * those rows anyway, so passing them avoids a second full-vault read for the
+ * same content. Omitting them (standalone/one-off use) falls back to reading
+ * the files directly. */
+export function generateVaultIndex(vaultPath, rows) {
     const entitiesDir = join(vaultPath, kindDir('entity'));
     const knowledgeDir = join(vaultPath, kindDir('knowledge'));
     const hasEntities = existsSync(entitiesDir);
     const hasKnowledge = existsSync(knowledgeDir);
     if (!hasEntities && !hasKnowledge)
         return;
+    const docsFor = (kind, dir) => rows ? fromRows(rows, kind) : scanParsed(dir);
     const lines = ['# Vault Index', '', '> Auto-generated by hafez. Do not edit manually.', ''];
     if (hasEntities) {
         const byStatus = new Map();
-        for (const { slug, fm, body } of scanParsed(entitiesDir)) {
+        for (const { slug, fm, body } of docsFor('entity', entitiesDir)) {
             const status = fm.status ?? 'active';
             const list = byStatus.get(status) ?? [];
             list.push({ slug, name: fm.name, summary: truncate(deriveSummary('entity', fm, body)), suffix: fm.type ?? 'entity' });
@@ -92,7 +148,7 @@ export function generateVaultIndex(vaultPath) {
     }
     if (hasKnowledge) {
         const entries = [];
-        for (const { slug, fm, body } of scanParsed(knowledgeDir)) {
+        for (const { slug, fm, body } of docsFor('knowledge', knowledgeDir)) {
             entries.push({
                 slug,
                 name: fm.name,

package/dist/merge.d.ts

@@ -1 +1 @@
-export declare function mergeVaultContent(remote: string, local: string): string;
+export declare function mergeVaultContent(remote: string, local: string, kind: 'entity' | 'knowledge' | 'session'): string;

package/dist/merge.js

@@ -1,14 +1,13 @@
 // src/merge.ts
-import { parseContent, serializeFile } from './vault.js';
-import { parseSessionLogHeading, splitStructural } from './document.js';
+import { parseContent, serializeFile, ARRAY_FIELDS } from './vault.js';
+import { parseSessionLogHeading, splitLogEntries, documentFor } from './document.js';
 import { APPEND_ONLY_SECTIONS } from './contracts.js';
 // Fields that are ISO date strings — latest date wins
 const DATE_FIELDS = ['last-touched', 'last-reinforced', 'created'];
 // Fields that are numeric counters — max wins
 const COUNT_FIELDS = ['reinforcement-count', 'staleness-days'];
-// Fields that are always arrays — union with dedup
-const ARRAY_FIELDS_UNCAPPED = ['tags', 'domain', 'related'];
-export function mergeVaultContent(remote, local) {
+// Array fields (vault.ARRAY_FIELDS — the same set parsing coerces) union with dedup
+export function mergeVaultContent(remote, local, kind) {
     const r = parseContent(remote);
     const l = parseContent(local);
     // Scalar policy: the side with the newer last-touched wins; local on tie.
@@ -16,7 +15,18 @@ export function mergeVaultContent(remote, local) {
     // array/date/count frontmatter fields are always unioned regardless.
     const localWins = String(l.frontmatter?.['last-touched'] ?? '') >= String(r.frontmatter?.['last-touched'] ?? '');
     const fm = mergeFrontmatter(r.frontmatter, l.frontmatter, localWins);
-    const body = mergeBody(r.body, l.body, localWins);
+    // The Document binds by kind — the same binding every write path uses (see
+    // DocContext), so a section this merge preserves stays structural for the
+    // next update too. The two sides come from divergent histories whose type
+    // may differ (a promote race leaves one side 'capture' and the other
+    // 'project'); the kind-level set keeps every same-kind section structural,
+    // while cross-KIND headings (a session-only ## Decisions quoted in an
+    // entity Brief) are not boundaries. Known residual: a same-kind heading
+    // quoted at line start in one side's section splits at that false boundary
+    // and can survive the merge as its own section — the fix is fence/quote
+    // awareness in Document's splitter, not a narrower binding here.
+    const doc = documentFor({ kind });
+    const body = mergeBody(doc, r.body, l.body, localWins);
     return serializeFile(fm, body);
 }
 function mergeFrontmatter(remote, local, localWins) {
@@ -39,7 +49,7 @@ function mergeFrontmatter(remote, local, localWins) {
             merged[key] = r;
     }
     // Array fields: union
-    for (const key of ARRAY_FIELDS_UNCAPPED) {
+    for (const key of ARRAY_FIELDS) {
         merged[key] = unionArrays(remote[key], local[key]);
         if (merged[key].length === 0)
             delete merged[key];
@@ -47,20 +57,21 @@ function mergeFrontmatter(remote, local, localWins) {
     return merged;
 }
 function unionArrays(a, b) {
-    // Local (b) items first so they survive cap truncation
+    // Local (b) items first: nothing is truncated, but the local side's order is
+    // the one the user last saw, so it stays the order they get back.
     const arrA = Array.isArray(a) ? a : a ? [a] : [];
     const arrB = Array.isArray(b) ? b : b ? [b] : [];
     return [...new Set([...arrB, ...arrA])];
 }
 // --- Body merge ---
-function mergeBody(remoteBody, localBody, localWins) {
+function mergeBody(doc, remoteBody, localBody, localWins) {
     if (remoteBody === localBody)
         return localBody;
     // Structural split (see document.ts): sections are atomic — a user ##
     // heading inside a Brief or a session-log entry body stays with its
     // section instead of being split out and merged under its own policy.
-    const remote = splitStructural(remoteBody);
-    const local = splitStructural(localBody);
+    const remote = doc.splitStructural(remoteBody);
+    const local = doc.splitStructural(localBody);
     // Build merged sections starting from local (local section order is canonical)
     const localHeadings = new Set(local.sections.map(s => s.heading));
     const mergedSections = [];
@@ -90,10 +101,16 @@ function mergeBody(remoteBody, localBody, localWins) {
             mergedSections.push(rs);
         }
     }
-    // Reassemble
-    const preamble = localWins
-        ? (local.preamble || remote.preamble)
-        : (remote.preamble || local.preamble);
+    // Reassemble. A preamble that is itself a session-log entry stream is
+    // append-only content living outside any heading — the archive-log files
+    // under entities/archive/ are exactly this shape. Merging those by the
+    // scalar wins policy drops one machine's archived entries wholesale, so
+    // union them by the same entry policy the Session Log section uses.
+    const preamble = isLogEntryStream(remote.preamble) && isLogEntryStream(local.preamble)
+        ? mergeSessionLogs(remote.preamble, local.preamble)
+        : localWins
+            ? (local.preamble || remote.preamble)
+            : (remote.preamble || local.preamble);
     const parts = [preamble, ...mergedSections.map(s => `## ${s.heading}\n\n${s.content}`)].filter(Boolean);
     return parts.join('\n\n');
 }
@@ -111,6 +128,12 @@ function mergeAppendOnlyLines(remoteContent, localContent) {
         return localContent;
     return [...localLines, ...remoteOnly].join('\n');
 }
+/** True when a block is nothing but session-log entries — it starts with an
+ *  entry heading, so splitLogEntries drops no leading prose. */
+function isLogEntryStream(text) {
+    const first = text.trim().split('\n')[0];
+    return first !== '' && parseSessionLogHeading(first) !== null;
+}
 function mergeSessionLogs(remoteContent, localContent) {
     const remoteEntries = parseLogEntries(remoteContent);
     const localEntries = parseLogEntries(localContent);
@@ -128,64 +151,73 @@ function mergeSessionLogs(remoteContent, localContent) {
     return merged.map(e => e.raw).join('\n\n');
 }
 function parseLogEntries(content) {
-    const entries = [];
-    const blocks = content.split(/\n(?=### \d{4}-\d{2}-\d{2})/);
-    for (const block of blocks) {
-        const trimmed = block.trim();
-        if (!trimmed)
-            continue;
-        const firstLine = trimmed.split('\n')[0];
-        const parsed = parseSessionLogHeading(firstLine);
-        if (parsed) {
-            entries.push({
-                key: `${parsed.date}|${parsed.agent}|${parsed.type}`,
-                date: parsed.date,
-                raw: trimmed,
-            });
-        }
-    }
-    return entries;
+    // Document owns entry block splitting; the identity key and dedup/sort
+    // policy stay here — merge semantics, not document structure.
+    //
+    // Identity is the entry's whole content. Date+agent+type is not an identity:
+    // two machines each running a digest on the same day produce two entries with
+    // the same heading and different bodies, and keying on the heading collapses
+    // them to one — the other machine's session history is gone. Entries the two
+    // sides share came from the same commit, so they are byte-identical and still
+    // dedup.
+    return splitLogEntries(content).map(raw => {
+        const parsed = parseSessionLogHeading(raw.split('\n')[0]);
+        return { key: raw, date: parsed.date, raw };
+    });
 }
 function mergeNextActions(remoteContent, localContent) {
-    const remoteItems = parseActionItems(remoteContent);
-    const localItems = parseActionItems(localContent);
-    // Build merged set: start with local items
-    const seen = new Set();
-    const merged = [];
-    // Add all local items
-    for (const item of localItems) {
-        seen.add(item.text);
-        merged.push(item);
-    }
-    // Add remote items not in local
-    for (const item of remoteItems) {
-        if (!seen.has(item.text)) {
-            seen.add(item.text);
-            merged.push(item);
-        }
-        else {
-            // If remote has it checked but local has it unchecked, upgrade to checked
-            const existing = merged.find(m => m.text === item.text);
-            if (existing && item.checked && !existing.checked) {
-                existing.checked = true;
-            }
+    const remote = parseActionItems(remoteContent);
+    const local = parseActionItems(localContent);
+    // Start with local items; index by action text for the remote pass
+    const merged = local.items.map(i => ({ ...i, notes: [...i.notes] }));
+    const byText = new Map(merged.map(i => [i.text, i]));
+    for (const item of remote.items) {
+        const existing = byText.get(item.text);
+        if (!existing) {
+            merged.push({ ...item, notes: [...item.notes] });
+            byText.set(item.text, merged[merged.length - 1]);
+            continue;
         }
+        // Checked on either side means done
+        if (item.checked)
+            existing.checked = true;
+        // Union the item's own notes/sub-bullets — they are authored content, not
+        // re-derivable from the checkbox line
+        existing.notes.push(...unionLines(item.notes, existing.notes));
+    }
+    const lines = [...local.preamble, ...unionLines(remote.preamble, local.preamble)];
+    for (const item of merged) {
+        lines.push(`- [${item.checked ? 'x' : ' '}] ${item.text}`);
+        lines.push(...item.notes);
     }
-    return merged.map(i => `- [${i.checked ? 'x' : ' '}] ${i.text}`).join('\n');
+    return lines.join('\n').replace(/\n+$/, '');
 }
+/** Lines of `from` not already present in `into` (blank lines only from `into`). */
+function unionLines(from, into) {
+    const seen = new Set(into.map(l => l.trim()).filter(Boolean));
+    return from.filter(l => l.trim() && !seen.has(l.trim()));
+}
+/**
+ * Split a Next Actions section into its leading non-item lines and its items,
+ * each item carrying the lines that follow it (indented sub-bullets, notes)
+ * until the next checkbox. Non-checkbox lines are authored content — parsing
+ * checkbox lines alone and re-rendering from them deletes everything else.
+ * `- [X]` is the same as `- [x]`: a completed action, not an unknown line.
+ */
 function parseActionItems(content) {
+    const preamble = [];
     const items = [];
     for (const line of content.split('\n')) {
-        const unchecked = line.match(/^- \[ \] (.+)$/);
-        if (unchecked) {
-            items.push({ checked: false, text: unchecked[1] });
-            continue;
+        const match = line.match(/^- \[([ xX])\] (.+)$/);
+        if (match) {
+            items.push({ checked: match[1].toLowerCase() === 'x', text: match[2], notes: [] });
         }
-        const checked = line.match(/^- \[x\] (.+)$/);
-        if (checked) {
-            items.push({ checked: true, text: checked[1] });
-            continue;
+        else if (items.length === 0) {
+            preamble.push(line);
+        }
+        else {
+            items[items.length - 1].notes.push(line);
         }
     }
-    return items;
+    return { preamble, items };
 }

package/dist/schema.js

@@ -1,5 +1,5 @@
 // src/schema.ts
-import { ENTITY_TYPES, ENTITY_STATUSES, CONFIDENCE_LEVELS, SESSION_LOG_TYPES, VALID_SUBTYPES, } from './contracts.js';
+import { ENTITY_TYPES, ENTITY_STATUSES, CONFIDENCE_LEVELS, SESSION_LOG_TYPES, VALID_SUBTYPES, PLAN_STATUSES, } from './contracts.js';
 export function validateEntityFrontmatter(fm) {
     const errors = [];
     if (!fm.name || typeof fm.name !== 'string')
@@ -35,9 +35,9 @@ export function validateKnowledgeSubtype(fm) {
     if (fm.subtype && !VALID_SUBTYPES.includes(fm.subtype)) {
         errors.push(`invalid subtype: ${fm.subtype} (expected: ${VALID_SUBTYPES.join(', ')})`);
     }
-    // Plan-specific: status must be active or done
-    if (fm.subtype === 'plan' && fm.status && !['active', 'done'].includes(fm.status)) {
-        errors.push(`invalid plan status: ${fm.status} (expected: active, done)`);
+    // Plan-specific: status must be one of the plan lifecycle statuses
+    if (fm.subtype === 'plan' && fm.status && !PLAN_STATUSES.includes(fm.status)) {
+        errors.push(`invalid plan status: ${fm.status} (expected: ${PLAN_STATUSES.join(', ')})`);
     }
     return errors;
 }

package/dist/templates.d.ts

@@ -6,3 +6,9 @@ export declare function bodyTemplate(type: EntityType, fields?: {
 export declare function knowledgeBodyTemplate(subtype?: KnowledgeSubtype, fields?: {
     synthesis?: string;
 }): string;
+/** Session bodies. Sessions have no TypeContract, but their headings are
+ * structural for Document splitting — so the list lives in contracts with
+ * every other section set, and this renders it. */
+export declare function sessionBodyTemplate(fields?: {
+    synthesis?: string;
+}): string;

package/dist/templates.js

@@ -1,39 +1,39 @@
-import { SUBTYPE_SECTIONS } from './contracts.js';
-const ITEM_TEMPLATES = {
-    capture: ['## Notes'],
-    entity: ['## Context', '## Session Log'],
-    project: ['## Purpose', '## Goals', '## Session Log'],
-};
-export function bodyTemplate(type, fields) {
-    const sections = ITEM_TEMPLATES[type];
-    if (!sections)
-        throw new Error(`Unknown item type: ${type}`);
+import { SUBTYPE_SECTIONS, DEFAULT_KNOWLEDGE_SUBTYPE, SESSION_SECTIONS, ENTITY_TYPES, getContract } from './contracts.js';
+/** Render a body from a section list, injecting each field's text under the
+ * section that field writes into (contracts.CREATE_FIELD_SECTIONS names the
+ * pairs; a field whose section this template lacks is rejected upstream by
+ * `unreachableFields`, so an unplaced value never reaches here). */
+function render(sections, content) {
     const lines = [];
     for (const section of sections) {
-        lines.push(section);
-        if (section === '## Purpose' && fields?.purpose) {
-            lines.push('', fields.purpose);
-        }
-        if (section === '## Notes' && fields?.notes) {
-            lines.push('', fields.notes);
-        }
+        lines.push(`## ${section}`);
+        const text = content[section];
+        if (text)
+            lines.push('', text);
         lines.push('');
     }
     return lines.join('\n');
 }
+export function bodyTemplate(type, fields) {
+    // The template IS the contract's default sections — the Document module
+    // derives its structural set from the same place, so the two can't drift.
+    if (!ENTITY_TYPES.includes(type))
+        throw new Error(`Unknown item type: ${type}`);
+    return render(getContract(type).defaultSections, { Purpose: fields?.purpose, Notes: fields?.notes });
+}
 export function knowledgeBodyTemplate(subtype, fields) {
     if (subtype === 'session') {
         throw new Error("subtype 'session' is no longer supported for knowledge notes. " +
             "Use batch kind: 'session' instead. See knowledge-v2 migration.");
     }
-    const sections = SUBTYPE_SECTIONS[subtype ?? 'insight'];
-    const lines = [];
-    for (const section of sections) {
-        lines.push(`## ${section}`);
-        if ((section === 'Synthesis' || section === 'Summary') && fields?.synthesis) {
-            lines.push('', fields.synthesis);
-        }
-        lines.push('');
-    }
-    return lines.join('\n');
+    // 'Summary' was a second injection target here until sessions stopped being
+    // a knowledge subtype; no SUBTYPE_SECTIONS entry has carried it since — the
+    // session body is its own template below.
+    return render(SUBTYPE_SECTIONS[subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE], { Synthesis: fields?.synthesis });
+}
+/** Session bodies. Sessions have no TypeContract, but their headings are
+ * structural for Document splitting — so the list lives in contracts with
+ * every other section set, and this renders it. */
+export function sessionBodyTemplate(fields) {
+    return render([...SESSION_SECTIONS], { Summary: fields?.synthesis });
 }

package/dist/types.d.ts

@@ -1,11 +1,14 @@
-export type EntityType = 'capture' | 'entity' | 'project';
-export type EntityStatus = 'active' | 'paused' | 'done';
-export type ConfidenceLevel = 'observation' | 'pattern' | 'principle';
-export type SessionLogType = 'progress' | 'decision' | 'blocker' | 'research';
+import type { ENTITY_TYPES, ENTITY_STATUSES, CONFIDENCE_LEVELS, SESSION_LOG_TYPES, VALID_SUBTYPES, PLAN_STATUSES } from './contracts.js';
+export type EntityType = typeof ENTITY_TYPES[number];
+export type EntityStatus = typeof ENTITY_STATUSES[number];
+export type ConfidenceLevel = typeof CONFIDENCE_LEVELS[number];
+export type SessionLogType = typeof SESSION_LOG_TYPES[number];
 export type ReadDepth = 'frontmatter' | 'summary' | 'full';
-export type QueryFilter = 'active' | 'paused' | 'done' | 'all' | 'stale' | 'capture';
+export type QueryFilter = EntityStatus | 'all' | 'stale' | 'capture';
 export type LinkRelation = 'parent' | 'related';
-export type KnowledgeSubtype = 'insight' | 'plan';
+export type KnowledgeSubtype = typeof VALID_SUBTYPES[number];
+/** Plans are the one knowledge subtype with a lifecycle (see PLAN_STATUSES). */
+export type PlanStatus = typeof PLAN_STATUSES[number];
 export interface EntityQueryOpts {
     filter?: QueryFilter;
     type?: EntityType;
@@ -26,12 +29,23 @@ export interface KnowledgeQueryOpts {
     domain?: string;
     confidence?: ConfidenceLevel;
     subtype?: KnowledgeSubtype;
+    since?: string;
+    before?: string;
+    createdSince?: string;
+    createdBefore?: string;
     tags?: string[];
     sort_by?: 'last_touched' | 'created' | 'name' | 'staleness' | 'last_reinforced' | 'reinforcement_count';
     sort_order?: 'asc' | 'desc';
     limit?: number;
     offset?: number;
 }
+/** The unified (`kind: 'all'`) query takes the entity filter set plus the
+ * knowledge-only narrowing flags. Status filters apply to the entity side
+ * only — knowledge notes carry no status and are never excluded by one. */
+export interface UnifiedQueryOpts extends EntityQueryOpts {
+    kind?: 'entity' | 'knowledge' | 'all';
+    subtype?: KnowledgeSubtype;
+}
 export interface EntityFrontmatter {
     name: string;
     type: EntityType;
@@ -58,7 +72,7 @@ export interface KnowledgeFrontmatter {
     'reinforcement-count'?: number;
     tags?: string[];
     'session-date'?: string;
-    status?: 'active' | 'done';
+    status?: PlanStatus;
     'last-touched'?: string;
 }
 export interface SessionFrontmatter {
@@ -118,6 +132,7 @@ export interface UpdateFields {
     tags?: string[];
     related?: string[];
     synthesis?: string;
+    insight?: string;
     add_evidence?: string;
     add_source?: string;
 }
@@ -139,7 +154,9 @@ export interface CreateEntityFields {
 }
 export interface CreateKnowledgeFields {
     subtype?: KnowledgeSubtype;
+    status?: PlanStatus;
     synthesis?: string;
+    insight?: string;
     description?: string;
     domain?: string[];
     related?: string[];
@@ -241,8 +258,16 @@ export interface ChangelogEntry {
 export interface BatchResult {
     op: string;
     slug: string;
-    status: 'ok' | 'error';
+    /** 'skipped' = the Op Spec green-lit the op but there was nothing to do
+     * (today: a duplicate session note) — no write, no error, batch continues.
+     * Dry-run reports the same disposition as a warning. */
+    status: 'ok' | 'error' | 'skipped';
     error?: string;
+    /** Why an op was skipped — same text the dry-run warning carries. */
+    warning?: string;
+    /** Error class when the failure — or the skip — maps to a specific HafezError
+     * code, so a single-op caller unwrapping this result keeps the right exit code. */
+    code?: 'SLUG_EXISTS';
     created?: boolean;
 }
 export type BatchOperation = {
@@ -290,6 +315,10 @@ export interface BatchOpValidation {
     created?: boolean;
     errors: string[];
     warning?: string;
+    /** Error class of the primary failure (NOT_FOUND / SLUG_EXISTS) when it
+     * maps to a specific HafezError code; single-op callers surface it as that
+     * code, batch-level failures stay VALIDATION_FAILED. */
+    primaryCode?: 'NOT_FOUND' | 'SLUG_EXISTS';
 }
 export interface BatchValidationReport {
     valid: boolean;
@@ -341,9 +370,7 @@ export interface Hafez {
         items: QueryResult[];
         total: number;
     }>;
-    queryUnified(opts?: EntityQueryOpts & {
-        kind?: 'entity' | 'knowledge' | 'all';
-    }): Promise<{
+    queryUnified(opts?: UnifiedQueryOpts): Promise<{
         items: UnifiedResult[];
         total: number;
     }>;

package/dist/vault.d.ts

@@ -25,13 +25,31 @@ export declare function scanVaultDir(dirPath: string): string[];
 /** Where an entity's overflow session-log entries are archived. */
 export declare function archiveLogPath(vaultPath: string, slug: string): string;
 export declare function resolveFilePath(vaultPath: string, slug: string, kind: VaultKind): string;
+/** The file a slug names, or null — entities are resolved before knowledge,
+ * the one resolution order every operation sees. */
+export declare function findVaultFile(vaultPath: string, slug: string): string | null;
+/** Does this slug name a vault file? 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. */
+export declare function vaultFileExists(vaultPath: string, slug: string): boolean;
 export declare function kindFromPath(filePath: string): 'entity' | 'knowledge';
+/** Fields that must always be arrays when present (may be scalar in
+ * hand-edited YAML). Parsing coerces them here; merge.ts unions them on
+ * conflict — one list, so a new list-valued field cannot be normalized on
+ * read and then overwritten wholesale on merge. */
+export declare const ARRAY_FIELDS: string[];
 /** Full-kind path classification (kindFromPath only distinguishes the
  * indexed kinds — sessions default to knowledge there for compatibility).
  * Session files live directly in sessions/, so only the immediate parent
  * counts — matching anywhere in the path misclassifies every file of a
  * vault that happens to live under a directory named "sessions". */
 export declare function vaultKindFromPath(filePath: string): VaultKind;
+/** Total kind classification for a vault-relative content file (anything
+ * matching VAULT_FILE_RE) — derived from KIND_DIRS, so adding a vault dir
+ * can't silently fall a new kind through to the wrong one. Throws on paths
+ * outside the vault dirs; callers gate on VAULT_FILE_RE first. */
+export declare function vaultKindFromRelPath(relPath: string): VaultKind;
 export declare function parseFilePath(path: string): ParsedVaultFile;
 export declare function parseContent(content: string): {
     frontmatter: Record<string, any>;