hafez 1.2.0 → 1.4.0

package/dist/export-okf.js

@@ -7,22 +7,36 @@
 // regenerated indexes) until the bundle directory is deleted and re-exported.
 import { readdirSync, writeFileSync, existsSync, mkdirSync } from 'fs';
 import { join, resolve, sep, basename } from 'path';
-import { parseFilePath, serializeFile } from './vault.js';
-import { deriveSummary } from './sections.js';
-const KIND_DIRS = [
-    { dir: 'entities', kind: 'entity' },
-    { dir: 'knowledge', kind: 'knowledge' },
-    { dir: 'sessions', kind: 'session' },
-];
-// Local capturing variant of the shared WIKI_LINK_RE — captures display text in
-// group 2, which the shared regex's consumers don't need.
-const OKF_LINK_RE = /\[\[([^\]|]+)(?:\|([^\]]+))?\]\]/g;
-function scanDir(dirPath) {
-    try {
-        return readdirSync(dirPath).filter(f => f.endsWith('.md')).map(f => join(dirPath, f));
+import { parseFilePath, serializeFile, scanVaultDir, kindDir } from './vault.js';
+import { DEFAULT_KNOWLEDGE_SUBTYPE } from './contracts.js';
+import { deriveSummary, WIKI_LINK_RE } from './document.js';
+const SOURCE_KINDS = ['entity', 'knowledge', 'session'];
+const KIND_DIRS = SOURCE_KINDS.map(kind => ({ dir: kindDir(kind), kind }));
+// The shared wiki-link syntax (document.ts) — group 1 slug, group 2 display.
+const OKF_LINK_RE = new RegExp(WIKI_LINK_RE.source, 'g');
+/** `index.md` is reserved in every bundle directory for the generated index, so
+ * a vault doc slugged `index` cannot keep its name — before this it was silently
+ * overwritten by the index that ran after it. Deterministic rule: rename to
+ * `index-doc`, then `index-doc-2`, `index-doc-3`, … until the name is free among
+ * that directory's real slugs (a vault may legitimately hold both `index` and
+ * `index-doc`). Same vault contents always produce the same bundle names, and
+ * every link/index reference is written against the renamed file. */
+const RESERVED_INDEX = 'index';
+function assignBundleNames(docs) {
+    const slugsByDir = new Map();
+    for (const doc of docs) {
+        const slugs = slugsByDir.get(doc.dir) ?? new Set();
+        slugs.add(doc.slug);
+        slugsByDir.set(doc.dir, slugs);
     }
-    catch {
-        return [];
+    for (const doc of docs) {
+        if (doc.slug !== RESERVED_INDEX)
+            continue;
+        const taken = slugsByDir.get(doc.dir);
+        let candidate = `${RESERVED_INDEX}-doc`;
+        for (let n = 2; taken.has(candidate); n++)
+            candidate = `${RESERVED_INDEX}-doc-${n}`;
+        doc.file = candidate;
     }
 }
 function mapFrontmatter(doc) {
@@ -31,7 +45,7 @@ function mapFrontmatter(doc) {
     if (kind === 'entity')
         mapped.type = fm.type ?? 'entity';
     else if (kind === 'knowledge')
-        mapped.type = fm.subtype ? `knowledge/${fm.subtype}` : 'knowledge';
+        mapped.type = `knowledge/${fm.subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE}`;
     else
         mapped.type = 'session';
     mapped.title = fm.name;
@@ -88,7 +102,7 @@ export function exportOkf(vaultPath, outDir) {
     // Enumerate and parse. Sessions are not in SQLite — disk enumeration is required.
     const docs = [];
     for (const { dir, kind } of KIND_DIRS) {
-        for (const filePath of scanDir(join(resolvedVault, dir))) {
+        for (const filePath of scanVaultDir(join(resolvedVault, dir))) {
             const slug = basename(filePath, '.md');
             const relFile = `${dir}/${slug}.md`;
             let fm, body;
@@ -107,28 +121,28 @@ export function exportOkf(vaultPath, outDir) {
                 process.stderr.write(`Warning: skipping ${relFile}: missing name\n`);
                 continue;
             }
-            docs.push({ slug, dir, kind, fm, body });
+            docs.push({ slug, dir, kind, fm, body, file: slug });
         }
     }
-    // Slug→dir map: insertion order entities/knowledge/sessions, first write wins,
-    // giving entity precedence on cross-kind slug collisions.
-    const slugDirs = new Map();
+    assignBundleNames(docs);
+    // Slug→bundle path map: insertion order entities/knowledge/sessions, first write
+    // wins, giving entity precedence on cross-kind slug collisions. Paths are
+    // bundle-root-absolute with hardcoded '/' separators.
+    const slugPaths = new Map();
     for (const doc of docs) {
-        if (!slugDirs.has(doc.slug))
-            slugDirs.set(doc.slug, doc.dir);
+        if (!slugPaths.has(doc.slug))
+            slugPaths.set(doc.slug, `/${doc.dir}/${doc.file}.md`);
     }
     function transformBody(body) {
         return body.replace(OKF_LINK_RE, (_m, rawSlug, rawDisplay) => {
-            // Trim: Obsidian-idiomatic [[ foo ]] / [[foo | Label]] carry whitespace in the captures
             const slug = rawSlug.trim();
             const label = rawDisplay?.trim() || slug;
-            const dir = slugDirs.get(slug);
-            if (!dir) {
+            const path = slugPaths.get(slug);
+            if (!path) {
                 report.unresolvedLinks++;
                 return label;
             }
-            // Bundle-root-absolute path, hardcoded '/' separators
-            return `[${label}](/${dir}/${slug}.md)`;
+            return `[${label}](${path})`;
         });
     }
     mkdirSync(resolvedOut, { recursive: true });
@@ -137,7 +151,7 @@ export function exportOkf(vaultPath, outDir) {
         const mapped = mapFrontmatter(doc);
         const outSubdir = join(resolvedOut, doc.dir);
         mkdirSync(outSubdir, { recursive: true });
-        writeFileSync(join(outSubdir, `${doc.slug}.md`), serializeFile(mapped, transformBody(doc.body)));
+        writeFileSync(join(outSubdir, `${doc.file}.md`), serializeFile(mapped, transformBody(doc.body)));
         if (doc.kind === 'entity')
             report.entities++;
         else if (doc.kind === 'knowledge')
@@ -145,7 +159,7 @@ export function exportOkf(vaultPath, outDir) {
         else
             report.sessions++;
         const list = byDir.get(doc.dir) ?? [];
-        list.push({ slug: doc.slug, title: mapped.title, description: mapped.description ?? '' });
+        list.push({ file: doc.file, title: mapped.title, description: mapped.description ?? '' });
         byDir.set(doc.dir, list);
     }
     // Per-dir index.md — reserved file: NO frontmatter, sorted bullets
@@ -154,15 +168,15 @@ export function exportOkf(vaultPath, outDir) {
         const lines = [`# ${heading}`, ''];
         for (const item of items.sort((a, b) => a.title.localeCompare(b.title))) {
             const desc = item.description ? ` — ${item.description}` : '';
-            lines.push(`- [${item.title}](/${dir}/${item.slug}.md)${desc}`);
+            lines.push(`- [${item.title}](/${dir}/${item.file}.md)${desc}`);
         }
         writeFileSync(join(resolvedOut, dir, 'index.md'), lines.join('\n') + '\n');
     }
     // Root index.md — the only place okf_version may appear
     const counts = [
-        ['entities', report.entities],
-        ['knowledge', report.knowledge],
-        ['sessions', report.sessions],
+        [kindDir('entity'), report.entities],
+        [kindDir('knowledge'), report.knowledge],
+        [kindDir('session'), report.sessions],
     ];
     const rootLines = ['# Vault Export', ''];
     for (const [dir, count] of counts) {

package/dist/git.d.ts

@@ -1,4 +1,4 @@
-import { type GitConfig, type ChangelogEntry } from './types.js';
+import { type GitConfig, type ChangelogEntry, type Journal } from './types.js';
 /**
  * Bidirectional sync: pull remote changes, push local commits.
  * All work must be committed before calling — no file save/restore needed.
@@ -8,13 +8,6 @@ export declare function gitSync(vaultPath: string): Promise<{
     pushed: boolean;
     remote: boolean;
 }>;
-/**
- * Unstage files (best effort). Used by batch rollback: a commit that fails
- * after `git add` leaves the new blobs staged in .git/index, and the next
- * successful commit would publish the rolled-back content under the wrong
- * message. Clearing the index entries restores worktree/HEAD/index agreement.
- */
-export declare function gitUnstage(vaultPath: string, files: string[]): Promise<void>;
 export declare function gitChangelog(vaultPath: string, since: string): Promise<ChangelogEntry[]>;
 /**
  * Latest git time per file (repo-relative, forward-slash paths). Used to
@@ -24,3 +17,9 @@ export declare function gitChangelog(vaultPath: string, since: string): Promise<
  */
 export declare function gitFileTimes(vaultPath: string, mode: 'modified' | 'added'): Promise<Map<string, string>>;
 export declare function gitCommitAndPush(vaultPath: string, files: string[], message: string, config?: GitConfig): Promise<void>;
+/**
+ * The production Journal (see CONTEXT.md): vault persistence backed by git.
+ * Local-only vaults (no origin remote) commit silently without pushing —
+ * that behavior lives in gitCommitAndPush/gitSync, inside this adapter.
+ */
+export declare function createGitJournal(vaultPath: string, config?: GitConfig): Journal;

package/dist/git.js

@@ -3,6 +3,8 @@ import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { simpleGit } from 'simple-git';
 import { mergeVaultContent } from './merge.js';
+import { VAULT_FILE_RE, INDEXED_DIR_PATHSPECS, classifyIndexedRelPath, vaultKindFromRelPath } from './vault.js';
+import { normalizeSinceDate } from './dates.js';
 import { HafezError } from './types.js';
 const logMerge = (msg) => process.stderr.write(`[hafez-merge] ${msg}\n`);
 const MAX_PUSH_RETRIES = 3;
@@ -40,7 +42,6 @@ async function ensureCleanState(git, vaultPath) {
         }
     }
 }
-const VAULT_FILE_RE = /^(?:entities|knowledge|sessions)\/.+\.md$/;
 /**
  * True if the vault repo has an `origin` remote. A local-only vault (the
  * default the README setup produces) has none — every pull/push must be
@@ -50,6 +51,61 @@ async function hasOriginRemote(git) {
     const remotes = await git.getRemotes();
     return remotes.some(r => r.name === 'origin');
 }
+/** The branch this vault is on (symbolic HEAD). */
+async function currentBranch(git) {
+    return (await git.raw(['rev-parse', '--abbrev-ref', 'HEAD'])).trim();
+}
+/** The branch's configured upstream (`origin/main`), or null when it has none. */
+async function upstreamRef(git) {
+    try {
+        const ref = (await git.raw(['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{u}'])).trim();
+        return ref || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Give the current branch an upstream when git does not know about one yet.
+ *
+ * `git remote add origin …` on a vault that has only ever been local leaves
+ * the branch both unpublished and untracked, and in that state `git pull`,
+ * `git push` and `@{u}` are all fatal — so every mutation after the remote
+ * was added died at the sync/push stage. Returns false when origin does not
+ * carry the branch at all: there is nothing to pull and nothing to track
+ * until the first push creates it (see pushCurrent).
+ *
+ * A remote we cannot reach also reports false — the caller's push, and its
+ * retry loop, is where a network failure belongs.
+ */
+async function ensureUpstream(git) {
+    if (await upstreamRef(git))
+        return true;
+    try {
+        const branch = await currentBranch(git);
+        const heads = await git.raw(['ls-remote', '--heads', 'origin', branch]);
+        if (!heads.trim())
+            return false;
+        await git.fetch('origin', branch);
+        await git.raw(['branch', `--set-upstream-to=origin/${branch}`, branch]);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Push the current branch, publishing it when it has no upstream yet. That
+ * first `push --set-upstream` is what turns a freshly-added origin into a
+ * normal tracking setup; every push after it is the plain push.
+ */
+async function pushCurrent(git) {
+    if (await upstreamRef(git)) {
+        await git.push();
+        return;
+    }
+    await git.push(['--set-upstream', 'origin', await currentBranch(git)]);
+}
 /** Read one side of a conflicted file from the index; null if that side deleted it. */
 async function showStage(git, stage, file) {
     try {
@@ -104,9 +160,12 @@ async function resolveRebaseConflicts(git, vaultPath) {
                     await git.raw(['rm', '--force', '--ignore-unmatch', '--', file]);
                     continue;
                 }
+                // Classify from the repo-relative path: every file here passed
+                // VAULT_FILE_RE, so the Layout classifier is total over it — no
+                // fallback kind to drift when a vault dir is added.
                 const merged = localContent === null ? remoteContent
                     : remoteContent === null ? localContent
-                        : mergeVaultContent(remoteContent, localContent);
+                        : mergeVaultContent(remoteContent, localContent, vaultKindFromRelPath(file));
                 const fullPath = join(vaultPath, file);
                 mkdirSync(dirname(fullPath), { recursive: true });
                 writeFileSync(fullPath, merged);
@@ -188,10 +247,13 @@ async function pullResolving(git, vaultPath, conflictMessage) {
  * local data survives a conflict.
  */
 async function pushResolving(git, vaultPath, conflictMessage, exhaustedMessage) {
+    // Bootstrap a freshly-added origin before the retry loop: without an
+    // upstream the rejection handling below (pull --rebase) is itself fatal.
+    await ensureUpstream(git);
     let lastDetail = '';
     for (let attempt = 1; attempt <= MAX_PUSH_RETRIES; attempt++) {
         try {
-            await git.push();
+            await pushCurrent(git);
             return;
         }
         catch (pushErr) {
@@ -226,44 +288,69 @@ export async function gitSync(vaultPath) {
     await ensureCleanState(git, vaultPath);
     const syncConflictMessage = (files) => `Git conflict during sync (files: ${files.join(', ')}). Changes saved locally.`;
     let pulled = false;
-    // Always pull first (bidirectional sync)
-    const headBefore = (await git.revparse(['HEAD'])).trim();
-    for (let attempt = 1; attempt <= MAX_PUSH_RETRIES; attempt++) {
-        try {
-            await pullResolving(git, vaultPath, syncConflictMessage);
-            const headAfter = (await git.revparse(['HEAD'])).trim();
-            pulled = headAfter !== headBefore;
-            break;
-        }
-        catch (err) {
-            if (err instanceof HafezError)
-                throw err;
-            if (attempt === MAX_PUSH_RETRIES) {
-                const detail = err instanceof Error ? err.message : String(err);
-                throw new HafezError('GIT_PUSH_FAILED', `Git pull failed after ${MAX_PUSH_RETRIES} attempts during sync. Changes saved locally.`, [detail]);
+    // A remote that does not carry this branch yet (freshly added to a vault
+    // that has only ever been local) has nothing to pull and no `@{u}` to count
+    // against — both steps would be fatal. Skip straight to the push, which
+    // publishes the branch and sets the upstream.
+    const tracking = await ensureUpstream(git);
+    if (tracking) {
+        // Always pull first (bidirectional sync)
+        const headBefore = (await git.revparse(['HEAD'])).trim();
+        for (let attempt = 1; attempt <= MAX_PUSH_RETRIES; attempt++) {
+            try {
+                await pullResolving(git, vaultPath, syncConflictMessage);
+                const headAfter = (await git.revparse(['HEAD'])).trim();
+                pulled = headAfter !== headBefore;
+                break;
+            }
+            catch (err) {
+                if (err instanceof HafezError)
+                    throw err;
+                if (attempt === MAX_PUSH_RETRIES) {
+                    const detail = err instanceof Error ? err.message : String(err);
+                    throw new HafezError('GIT_PUSH_FAILED', `Git pull failed after ${MAX_PUSH_RETRIES} attempts during sync. Changes saved locally.`, [detail]);
+                }
+                await new Promise((resolve) => setTimeout(resolve, RETRY_BASE_MS * attempt));
             }
-            await new Promise((resolve) => setTimeout(resolve, RETRY_BASE_MS * attempt));
         }
+        // Check if there are local commits to push
+        const ahead = await git.raw(['rev-list', '--count', '@{u}..HEAD']).then(s => parseInt(s.trim(), 10));
+        if (ahead === 0)
+            return { pulled, pushed: false, remote: true };
     }
-    // Check if there are local commits to push
-    const ahead = await git.raw(['rev-list', '--count', '@{u}..HEAD']).then(s => parseInt(s.trim(), 10));
-    if (ahead === 0)
-        return { pulled, pushed: false, remote: true };
     await pushResolving(git, vaultPath, syncConflictMessage, `Git push failed after ${MAX_PUSH_RETRIES} attempts during sync. Changes saved locally.`);
     return { pulled, pushed: true, remote: true };
 }
 /**
- * Unstage files (best effort). Used by batch rollback: a commit that fails
- * after `git add` leaves the new blobs staged in .git/index, and the next
- * successful commit would publish the rolled-back content under the wrong
- * message. Clearing the index entries restores worktree/HEAD/index agreement.
+ * Unstage files (best effort). Used by the journal adapter's commit-failure
+ * repair: a commit that fails after `git add` leaves the new blobs staged in
+ * .git/index, and the next successful commit would publish rolled-back
+ * content under the wrong message. Clearing the index entries restores
+ * worktree/HEAD/index agreement.
  */
-export async function gitUnstage(vaultPath, files) {
+async function gitUnstage(vaultPath, files) {
     try {
         await simpleGit(vaultPath).raw(['reset', '-q', 'HEAD', '--', ...files]);
     }
     catch { /* best effort — rollback must not mask the original error */ }
 }
+/**
+ * The subset of `files` that `git add` can actually stage. `git add` is fatal
+ * on a pathspec matching nothing, and a batch that creates then deletes the
+ * same slug (capture then cross-kind promote) hands the Journal a deleted path
+ * that is absent from the worktree AND was never tracked — unstageable by
+ * construction, and it needs no staging: git never knew about it. A deleted
+ * path git DOES track still goes through `add`, which stages its removal.
+ */
+async function stageablePaths(git, vaultPath, files) {
+    const absent = files.filter(f => !existsSync(join(vaultPath, f)));
+    if (absent.length === 0)
+        return files;
+    // -z: NUL-separated, so git never quotes/escapes the paths it echoes back.
+    const tracked = new Set((await git.raw(['ls-files', '-z', '--', ...absent])).split('\0').filter(Boolean));
+    const absentSet = new Set(absent);
+    return files.filter(f => !absentSet.has(f) || tracked.has(f));
+}
 /** Get list of files with unresolved conflicts */
 async function getConflictingFiles(git) {
     try {
@@ -279,18 +366,40 @@ const FILE_STATUS_MAP = {
     M: 'updated',
     D: 'deleted',
 };
+/**
+ * One `--name-status` line → the (path, operation) pairs it stands for.
+ *
+ * Rename and copy lines carry a similarity score and TWO paths
+ * (`R100\told\tnew`), so they match neither the single-path shape nor a
+ * bare status letter. A promote moves entities/<slug>.md to
+ * knowledge/<slug>.md, which git reports exactly that way — dropping the
+ * line made every promote invisible in the changelog. A rename reads as the
+ * old path disappearing and the new one appearing; a copy leaves the source
+ * in place, so only the destination is news.
+ */
+function parseNameStatusLine(line) {
+    const moveMatch = line.match(/^([RC])\d*\t([^\t]+)\t(.+)$/);
+    if (moveMatch) {
+        const [, statusChar, from, to] = moveMatch;
+        const dest = [{ path: to, operation: 'created' }];
+        return statusChar === 'C' ? dest : [{ path: from, operation: 'deleted' }, ...dest];
+    }
+    const match = line.match(/^([A-Z])\t(.+)$/);
+    if (!match)
+        return [];
+    const operation = FILE_STATUS_MAP[match[1]];
+    return operation ? [{ path: match[2], operation }] : [];
+}
 export async function gitChangelog(vaultPath, since) {
     const git = simpleGit(vaultPath);
-    // git approxidate fills a date-only --since with the *current* time of
-    // day, so `--since <today>` means "since right now" and silently returns
-    // nothing — the obvious "what happened today" query was the one that
-    // failed. Normalise bare dates to local midnight.
-    const normalizedSince = /^\d{4}-\d{2}-\d{2}$/.test(since) ? `${since}T00:00:00` : since;
+    // Bare dates become local midnight — the same calendar-day boundary the
+    // vault stamps and query comparisons use (see dates.ts).
+    const normalizedSince = normalizeSinceDate(since);
     let output;
     try {
         output = await git.raw([
             'log', `--since=${normalizedSince}`, '--name-status',
-            '--pretty=format:%H|%aI|%s', '--', 'entities/', 'knowledge/',
+            '--pretty=format:%H|%aI|%s', '--', ...INDEXED_DIR_PATHSPECS,
         ]);
     }
     catch {
@@ -309,31 +418,16 @@ export async function gitChangelog(vaultPath, since) {
             continue;
         const [, , timestamp, commit_message] = headerMatch;
         for (let i = 1; i < lines.length; i++) {
-            const fileMatch = lines[i].match(/^([AMDRC])\t(.+)$/);
-            if (!fileMatch)
-                continue;
-            const [, statusChar, filePath] = fileMatch;
-            const operation = FILE_STATUS_MAP[statusChar];
-            if (!operation)
-                continue;
-            // Only vault documents — scaffold files (.gitkeep) live in the same
-            // dirs and would otherwise surface as changelog rows.
-            if (!filePath.endsWith('.md'))
-                continue;
-            let kind;
-            let slug;
-            if (filePath.startsWith('entities/')) {
-                kind = 'entity';
-                slug = filePath.replace('entities/', '').replace('.md', '');
-            }
-            else if (filePath.startsWith('knowledge/')) {
-                kind = 'knowledge';
-                slug = filePath.replace('knowledge/', '').replace('.md', '');
-            }
-            else {
-                continue;
+            for (const { path: filePath, operation } of parseNameStatusLine(lines[i])) {
+                // Only vault documents — scaffold files (.gitkeep) live in the same
+                // dirs and would otherwise surface as changelog rows.
+                if (!filePath.endsWith('.md'))
+                    continue;
+                const classified = classifyIndexedRelPath(filePath);
+                if (!classified)
+                    continue;
+                entries.push({ slug: classified.slug, kind: classified.kind, operation, timestamp, commit_message });
             }
-            entries.push({ slug, kind, operation, timestamp, commit_message });
         }
     }
     return entries;
@@ -348,7 +442,7 @@ export async function gitFileTimes(vaultPath, mode) {
     const git = simpleGit(vaultPath);
     let output;
     try {
-        const args = ['log', '--pretty=format:%x00%aI', '--name-only', '--', 'entities/', 'knowledge/'];
+        const args = ['log', '--pretty=format:%x00%aI', '--name-only', '--', ...INDEXED_DIR_PATHSPECS];
         if (mode === 'added')
             args.splice(1, 0, '--diff-filter=A');
         output = await git.raw(args);
@@ -386,10 +480,19 @@ export async function gitCommitAndPush(vaultPath, files, message, config = {}) {
             writeFileSync(fullPath, content);
         }
     }
-    await git.add(files);
-    // Handle "nothing to commit" (e.g., idempotent update wrote identical content)
-    const status = await git.status();
-    if (status.staged.length === 0)
+    const stageable = await stageablePaths(git, vaultPath, files);
+    if (stageable.length === 0)
+        return;
+    await git.add(stageable);
+    // Handle "nothing to commit" (e.g., idempotent update wrote identical
+    // content). Ask the index directly rather than via simple-git's status:
+    // its `staged` list omits renamed paths (they go to `renamed` only), so a
+    // promote git detected as a rename read as "nothing to commit" and was
+    // silently dropped — left staged, uncommitted, absent from the changelog.
+    // Same output-based protocol the rebase loop uses, and it is well-defined
+    // against an unborn HEAD (diffs the empty tree).
+    const stagedPaths = (await git.raw(['diff', '--cached', '--name-only'])).trim();
+    if (stagedPaths.length === 0)
         return;
     const committed = await git.commit(message);
     // simple-git swallows some commit failures (e.g. a rejected pre-commit
@@ -405,3 +508,35 @@ export async function gitCommitAndPush(vaultPath, files, message, config = {}) {
         return;
     await pushResolving(git, vaultPath, (conflictFiles) => `Git conflict with remote (files: ${conflictFiles.join(', ')}). Changes saved locally.`, `Git push failed after ${MAX_PUSH_RETRIES} attempts. Changes saved locally.`);
 }
+/**
+ * The production Journal (see CONTEXT.md): vault persistence backed by git.
+ * Local-only vaults (no origin remote) commit silently without pushing —
+ * that behavior lives in gitCommitAndPush/gitSync, inside this adapter.
+ */
+export function createGitJournal(vaultPath, config = {}) {
+    return {
+        async commit(written, deleted, message) {
+            const files = [...written, ...deleted];
+            try {
+                await gitCommitAndPush(vaultPath, files, message, config);
+            }
+            catch (err) {
+                // Commit-stage failure: nothing landed, but `git add` may have staged
+                // the new blobs — clean up our own partial state before rethrowing.
+                // Push-stage failure keeps the local commit (GIT_PUSH_FAILED).
+                if (!(err instanceof HafezError && err.code === 'GIT_PUSH_FAILED')) {
+                    await gitUnstage(vaultPath, files);
+                }
+                // The Journal is the seam: git's own error types must not escape it,
+                // or callers (and the CLI exit-code table) see an unclassified failure.
+                if (err instanceof HafezError)
+                    throw err;
+                const detail = err instanceof Error ? err.message : String(err);
+                throw new HafezError('GIT_COMMIT_FAILED', `git commit failed for: ${files.join(', ')}`, [detail]);
+            }
+        },
+        sync: () => gitSync(vaultPath),
+        changelog: (since) => gitChangelog(vaultPath, since),
+        fileTimes: (mode) => gitFileTimes(vaultPath, mode),
+    };
+}

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 import type { Hafez, HafezConfig } from './types.js';
 export declare function createHafez(config: HafezConfig): Hafez;
 export { HafezError } from './types.js';
-export type { Hafez, HafezConfig, HafezErrorCode, EntityType, EntityStatus, EntityQueryOpts, KnowledgeQueryOpts, EntityFrontmatter, KnowledgeFrontmatter, ParsedFile, SessionLogEntry, UpdateFields, UpdateResult, CreateEntityFields, CreateKnowledgeFields, QueryFilter, QueryResult, KnowledgeQueryResult, UnifiedResult, ValidationReport, BatchOperation, BatchResult, ReadDepth, ConfidenceLevel, LinkRelation, GitConfig, SearchResult, VaultStats, ChangelogEntry, KnowledgeSubtype } 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 type { Hafez, HafezConfig, HafezErrorCode, EntityType, EntityStatus, EntityQueryOpts, KnowledgeQueryOpts, UnifiedQueryOpts, EntityFrontmatter, KnowledgeFrontmatter, ParsedFile, SessionLogEntry, UpdateFields, UpdateResult, CreateEntityFields, CreateKnowledgeFields, QueryFilter, QueryResult, KnowledgeQueryResult, UnifiedResult, ValidationReport, BatchOperation, BatchResult, ReadDepth, ConfidenceLevel, LinkRelation, GitConfig, Journal, SearchResult, VaultStats, ChangelogEntry, KnowledgeSubtype } from './types.js';
+export { getBrief, getNextActions } from './document.js';
+export { parseSessionLogHeading, parseSessionLog } from './document.js';