hafez 2.1.0 → 2.2.0

package/dist/db.js

@@ -23,8 +23,9 @@ import { localDay } from './dates.js';
 //     rows (REPLACE never fired the delete trigger) and must be rebuilt, not reused.
 // v11: next_action and the searchable body store action text with its
 //     added-date stamp stripped.
+// v12: sessions are indexed (#35); session_date column.
 // Existing instances will fully rebuild the index on first access after upgrade.
-export const SCHEMA_VERSION = '11';
+export const SCHEMA_VERSION = '12';
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS items (
   slug               TEXT PRIMARY KEY,
@@ -50,7 +51,8 @@ CREATE TABLE IF NOT EXISTS items (
   session_log_count  INTEGER DEFAULT 0,
   last_session_date  TEXT,
   last_session_type  TEXT,
-  last_session_summary TEXT
+  last_session_summary TEXT,
+  session_date       TEXT
 );
 
 CREATE TABLE IF NOT EXISTS links (
@@ -100,8 +102,14 @@ const SORT_COL_MAP = {
     staleness: 'i.staleness_days',
     reinforcement_count: 'i.reinforcement_count',
     last_reinforced: 'i.last_reinforced',
+    session_date: 'i.session_date',
+};
+/** Sort fields one branch cannot honour: the column is NULL for its rows. */
+const SORT_REJECTS = {
+    entity: new Set(['reinforcement_count', 'last_reinforced', 'session_date']),
+    knowledge: new Set(['session_date']),
+    session: new Set(['reinforcement_count', 'last_reinforced', 'last_touched', 'staleness']),
 };
-const KNOWLEDGE_ONLY_SORTS = new Set(['reinforcement_count', 'last_reinforced']);
 const SORT_FIELDS = Object.keys(SORT_COL_MAP);
 const SORT_ORDERS = ['asc', 'desc'];
 const QUERY_FILTERS = [...ENTITY_STATUSES, 'all', 'stale', 'capture'];
@@ -163,12 +171,18 @@ function queryItemsFn(db, opts) {
         conditions.push('i.kind = @kind');
         params.kind = opts.kind;
     }
+    else if (!opts.kind) {
+        // Unset is the working set. Sessions are a record of what happened, not
+        // a thing being worked on, and each one names every entity it touched:
+        // in the default view they would crowd out the note being looked for.
+        conditions.push("i.kind != 'session'");
+    }
     if (opts.status) {
-        // Status is an entity attribute — knowledge rows are indexed with a NULL
+        // Status is an entity attribute — other kinds are indexed with a NULL
         // status. In a kind-unset (unified) query the status filter narrows the
         // entity side only; applying it to every row is what made `query --kind
         // all` (filter defaults to active) return entities and nothing else.
-        conditions.push(opts.kind === 'entity' ? 'i.status = @status' : "(i.kind = 'knowledge' OR i.status = @status)");
+        conditions.push(opts.kind === 'entity' ? 'i.status = @status' : "(i.kind != 'entity' OR i.status = @status)");
         params.status = opts.status;
     }
     if (opts.type) {
@@ -212,12 +226,14 @@ function queryItemsFn(db, opts) {
     if (opts.filter === 'capture') {
         conditions.push("i.type = 'capture'");
     }
+    // A session's one day is its session date: the window reads it where an
+    // entity or plan has last_touched.
     if (opts.since) {
-        conditions.push('i.last_touched >= @since');
+        conditions.push('COALESCE(i.last_touched, i.session_date) >= @since');
         params.since = opts.since;
     }
     if (opts.before) {
-        conditions.push('i.last_touched <= @before');
+        conditions.push('COALESCE(i.last_touched, i.session_date) <= @before');
         params.before = opts.before;
     }
     if (opts.createdSince) {
@@ -242,12 +258,12 @@ function queryItemsFn(db, opts) {
     assertSortOrder(opts.sort_order);
     assertCount(opts.limit, 'limit');
     assertCount(opts.offset, 'offset');
-    let sortCol = 'i.last_touched';
+    let sortCol = opts.kind === 'session' ? 'i.session_date' : 'i.last_touched';
     if (opts.sort_by) {
         // Same rule as the unmappable opts, one code path over: a sort field the
         // branch cannot honour is rejected, not quietly swapped for recency.
-        if (KNOWLEDGE_ONLY_SORTS.has(opts.sort_by) && opts.kind === 'entity') {
-            outOfScope('sort_by', opts.sort_by, 'entity');
+        if (opts.kind && opts.kind !== 'all' && SORT_REJECTS[opts.kind].has(opts.sort_by)) {
+            outOfScope('sort_by', opts.sort_by, opts.kind);
         }
         if (SORT_COL_MAP[opts.sort_by])
             sortCol = SORT_COL_MAP[opts.sort_by];
@@ -280,7 +296,7 @@ function queryItemsFn(db, opts) {
                       i.confidence, i.reinforcement_count, i.last_reinforced,
                       i.created, i.last_touched, i.subtype,
                       i.description, i.resource, i.brief, i.session_log_count, i.last_session_date,
-                      i.last_session_type, i.last_session_summary
+                      i.last_session_type, i.last_session_summary, i.session_date
                FROM items i ${where}
                ORDER BY ${sortCol} ${sortOrder}${limitClause}`;
     const rows = db.prepare(sql).all(params);
@@ -310,9 +326,13 @@ function searchFn(db, query, kind) {
     const { fts: ftsQuery, terms } = sanitizeFtsQuery(query);
     if (!ftsQuery)
         return [];
-    let kindFilter = '';
+    // Same rule as queryItemsFn: unset is the working set, `all` is literal.
+    let kindFilter = "AND i.kind != 'session'";
     const params = { query: ftsQuery };
-    if (kind && kind !== 'all') {
+    if (kind === 'all') {
+        kindFilter = '';
+    }
+    else if (kind) {
         kindFilter = 'AND i.kind = @kind';
         params.kind = kind;
     }
@@ -553,11 +573,13 @@ export function createIndex(vaultPath, opts) {
     INSERT INTO items
       (slug, kind, name, type, status, parent, next_action, next_action_count, staleness_days,
        confidence, reinforcement_count, last_reinforced, created, last_touched, body, file_hash, subtype,
-       description, resource, brief, session_log_count, last_session_date, last_session_type, last_session_summary)
+       description, resource, brief, session_log_count, last_session_date, last_session_type, last_session_summary,
+       session_date)
     VALUES
       (@slug, @kind, @name, @type, @status, @parent, @next_action, @next_action_count, @staleness_days,
        @confidence, @reinforcement_count, @last_reinforced, @created, @last_touched, @body, @file_hash, @subtype,
-       @description, @resource, @brief, @session_log_count, @last_session_date, @last_session_type, @last_session_summary)
+       @description, @resource, @brief, @session_log_count, @last_session_date, @last_session_type, @last_session_summary,
+       @session_date)
   `);
     const deleteItemStmt = db.prepare('DELETE FROM items WHERE slug = ?');
     const deleteLinksStmt = db.prepare('DELETE FROM links WHERE source = ?');
@@ -620,6 +642,8 @@ export function createIndex(vaultPath, opts) {
             last_session_date: lastLog?.date ?? null,
             last_session_type: lastLog?.type ?? null,
             last_session_summary: lastLog?.summary?.slice(0, 300) ?? null,
+            // A session note's one day; the created stamp when digest gave none.
+            session_date: kind === 'session' ? (fm['session-date'] ?? fm.created) : null,
         };
         // Replace item and rebuild links. Delete-then-insert keeps the FTS index
         // trigger-consistent for externally changed files (hand edit, git pull),
@@ -657,12 +681,12 @@ export function createIndex(vaultPath, opts) {
         const linkRe = new RegExp(WIKI_LINK_RE.source, 'g');
         while ((wikiMatch = linkRe.exec(authoredBody)) !== null) {
             const targetSlug = wikiMatch[1];
-            // Check if target file exists on disk (not in index — target may not be indexed yet)
-            const targetEntityPath = join(vaultPath, kindDir('entity'), `${targetSlug}.md`);
-            const targetKnowledgePath = join(vaultPath, kindDir('knowledge'), `${targetSlug}.md`);
+            // Check if target file exists on disk (not in index — target may not be
+            // indexed yet), in every indexed dir — the same set the rebuild's
+            // knownSlugs covers, so a mention links the same way on either path.
             const targetExists = knownSlugs
                 ? knownSlugs.has(targetSlug)
-                : existsSync(targetEntityPath) || existsSync(targetKnowledgePath);
+                : INDEXED_KINDS.some(k => existsSync(join(vaultPath, kindDir(k), `${targetSlug}.md`)));
             if (targetExists) {
                 insertLinkStmt.run(slug, targetSlug, 'mention');
             }
@@ -675,17 +699,15 @@ export function createIndex(vaultPath, opts) {
         db.exec('DELETE FROM links');
         // Collect all vault slugs for wiki link target validation
         const allVaultSlugs = new Set();
-        for (const file of scanVaultDir(join(vaultPath, kindDir('entity')))) {
-            allVaultSlugs.add(basename(file, '.md'));
-        }
-        for (const file of scanVaultDir(join(vaultPath, kindDir('knowledge')))) {
-            allVaultSlugs.add(basename(file, '.md'));
-        }
-        for (const file of scanVaultDir(join(vaultPath, kindDir('entity')))) {
-            indexFile(file, 'entity', allVaultSlugs);
+        for (const kind of INDEXED_KINDS) {
+            for (const file of scanVaultDir(join(vaultPath, kindDir(kind)))) {
+                allVaultSlugs.add(basename(file, '.md'));
+            }
         }
-        for (const file of scanVaultDir(join(vaultPath, kindDir('knowledge')))) {
-            indexFile(file, 'knowledge', allVaultSlugs);
+        for (const kind of INDEXED_KINDS) {
+            for (const file of scanVaultDir(join(vaultPath, kindDir(kind)))) {
+                indexFile(file, kind, allVaultSlugs);
+            }
         }
         db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('last_sync', ?)")
             .run(scanStart.toString());
@@ -772,6 +794,7 @@ function withReadSurface(core) {
         queryChildren: (parentSlug) => queryEntitiesFn(index, { parent: parentSlug }),
         queryRelatedTo: (slug, relation) => queryRelatedToFn(index, slug, relation),
         queryKnowledge: (opts) => queryKnowledgeFn(index, opts),
+        querySessions: (opts) => querySessionsFn(index, opts),
         queryUnified: (opts) => queryUnifiedFn(index, opts),
     };
     return index;
@@ -812,6 +835,23 @@ function toKnowledgeResult(slug, row) {
         last_touched: row.last_touched ?? null,
     };
 }
+function toSessionResult(slug, row) {
+    return {
+        slug,
+        name: row.name,
+        session_date: row.session_date,
+        created: row.created,
+        related: row.related ?? [],
+    };
+}
+/** One row of any kind, shaped for its kind. */
+function toUnifiedResult(i) {
+    if (i.kind === 'entity')
+        return { ...toQueryResult(i.slug, i), kind: 'entity' };
+    if (i.kind === 'session')
+        return { ...toSessionResult(i.slug, i), kind: 'session' };
+    return { ...toKnowledgeResult(i.slug, i), kind: 'knowledge' };
+}
 const STATUS_FILTERS = new Set(ENTITY_STATUSES);
 function mapEntityFilterOpts(qopts, opts) {
     if (opts?.filter && STATUS_FILTERS.has(opts.filter))
@@ -867,11 +907,16 @@ function validateEntityFilterOpts(opts) {
  * Asserted against the CLI's flag matrix in query-surface.test.ts. */
 export const ENTITY_ONLY_OPTS = ['filter', 'type', 'parent'];
 export const KNOWLEDGE_ONLY_OPTS = ['confidence', 'subtype'];
+/** What a session query cannot map: both sides' opts, and the two every
+ * other kind shares — a session note carries no domain and no tags. */
+export const SESSION_REJECTED_OPTS = [...ENTITY_ONLY_OPTS, ...KNOWLEDGE_ONLY_OPTS, 'domain', 'tags'];
 /** The one sentence both scope rejections speak — opts here, sort fields in
  * queryItemsFn — so a caller sees the same shape whichever one they hit. */
 function outOfScope(label, name, branch) {
-    const belongsTo = branch === 'entity' ? 'knowledge notes only' : 'entities only';
-    throw new HafezError('VALIDATION_FAILED', `Invalid ${label} for a ${branch} query: "${name}" — ${belongsTo}. Use kind: 'all' to query both.`);
+    const belongsTo = branch === 'entity' ? 'knowledge notes only'
+        : branch === 'knowledge' ? 'entities only'
+            : 'entities and knowledge notes only';
+    throw new HafezError('VALIDATION_FAILED', `Invalid ${label} for a ${branch} query: "${name}" — ${belongsTo}. Use kind: 'all' to query every kind.`);
 }
 function rejectUnmappableOpts(opts, reject, branch) {
     if (!opts)
@@ -901,15 +946,11 @@ function queryEntitiesFn(index, opts) {
     const { items, total } = index.queryItems(qopts);
     return { items: items.map(i => toQueryResult(i.slug, i)), total };
 }
+/** Every kind: the sessions that touched an entity are the look back from it. */
 function queryRelatedToFn(index, slug, relation) {
     index.syncIfStale();
-    const { items, total } = index.queryItems({ relatedTo: slug, relation });
-    return {
-        items: items.map(i => i.kind === 'entity'
-            ? { ...toQueryResult(i.slug, i), kind: 'entity' }
-            : { ...toKnowledgeResult(i.slug, i), kind: 'knowledge' }),
-        total,
-    };
+    const { items, total } = index.queryItems({ kind: 'all', relatedTo: slug, relation });
+    return { items: items.map(toUnifiedResult), total };
 }
 function queryKnowledgeFn(index, opts) {
     index.syncIfStale();
@@ -924,6 +965,17 @@ function queryKnowledgeFn(index, opts) {
     const { items, total } = index.queryItems(qopts);
     return { items: items.map(i => toKnowledgeResult(i.slug, i)), total };
 }
+function querySessionsFn(index, opts) {
+    index.syncIfStale();
+    rejectUnmappableOpts(opts, SESSION_REJECTED_OPTS, 'session');
+    validateTimeOpts(opts);
+    validateListOpts(opts);
+    const qopts = { kind: 'session' };
+    mapTimeOpts(qopts, opts);
+    mapListOpts(qopts, opts);
+    const { items, total } = index.queryItems(qopts);
+    return { items: items.map(i => toSessionResult(i.slug, i)), total };
+}
 function queryUnifiedFn(index, opts) {
     index.syncIfStale();
     // The public type is a union discriminated on `kind`, so an out-of-scope opt
@@ -931,7 +983,7 @@ function queryUnifiedFn(index, opts) {
     // an untyped caller (JS, JSON over MCP) reaches here regardless — so widen
     // once, here, and let the checks below speak for both.
     const o = opts;
-    assertEnum(o?.kind, ['entity', 'knowledge', 'all'], 'kind');
+    assertEnum(o?.kind, ['entity', 'knowledge', 'session', 'all'], 'kind');
     validateEntityFilterOpts(o);
     validateKnowledgeFilterOpts(o);
     // Only `kind: 'all'` (or unset) maps both sides. `kind` also narrows this
@@ -943,24 +995,16 @@ function queryUnifiedFn(index, opts) {
         rejectUnmappableOpts(o, KNOWLEDGE_ONLY_OPTS, 'entity');
     if (o?.kind === 'knowledge')
         rejectUnmappableOpts(o, ENTITY_ONLY_OPTS, 'knowledge');
+    if (o?.kind === 'session')
+        rejectUnmappableOpts(o, SESSION_REJECTED_OPTS, 'session');
     validateTimeOpts(o);
     validateListOpts(o);
-    const qopts = {};
-    if (o?.kind && o.kind !== 'all')
-        qopts.kind = o.kind;
-    // When kind is 'all' or unset, no kind filter — both entities and knowledge are returned
+    // Unset is the working set (entity + knowledge); 'all' reaches every kind.
+    const qopts = { kind: o?.kind };
     mapEntityFilterOpts(qopts, o);
     mapKnowledgeFilterOpts(qopts, o);
     mapTimeOpts(qopts, o);
     mapListOpts(qopts, o);
     const result = index.queryItems(qopts);
-    const items = result.items.map(i => {
-        if (i.kind === 'entity') {
-            return { ...toQueryResult(i.slug, i), kind: 'entity' };
-        }
-        else {
-            return { ...toKnowledgeResult(i.slug, i), kind: 'knowledge' };
-        }
-    });
-    return { items, total: result.total };
+    return { items: result.items.map(toUnifiedResult), total: result.total };
 }

package/dist/git.js

@@ -6,6 +6,49 @@ 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';
+// Hafez runs git in the user's own shell, and git inherited that environment before simple-git
+// guarded it. simple-git 4 guards it two ways, and both are opened in full: `allowEnvironment`
+// names every key the process carries (the guard otherwise strips ambient GIT_* / EDITOR / PAGER
+// keys and rejects supplied ones — a user's GIT_SSH_COMMAND or GIT_AUTHOR_* would vanish), and
+// `unsafe` opens every category — `Required`, so a category the library adds fails the build
+// instead of rejecting some user's shell at runtime (4.0 moved GIT_EXEC_PATH to allowUnsafeExec).
+const OPEN_UNSAFE = {
+    allowUnsafeAlias: true,
+    allowUnsafeAskPass: true,
+    allowUnsafeCommandBinaries: true,
+    allowUnsafeConfigEnvCount: true,
+    allowUnsafeConfigPaths: true,
+    allowUnsafeCredentialHelper: true,
+    allowUnsafeDiffExternal: true,
+    allowUnsafeDiffTextConv: true,
+    allowUnsafeEditor: true,
+    allowUnsafeExec: true,
+    allowUnsafeFilter: true,
+    allowUnsafeFsMonitor: true,
+    allowUnsafeGitProxy: true,
+    allowUnsafeGpgProgram: true,
+    allowUnsafeHooksPath: true,
+    allowUnsafeInclude: true,
+    allowUnsafeMergeDriver: true,
+    allowUnsafePack: true,
+    allowUnsafePager: true,
+    allowUnsafeProtocolOverride: true,
+    allowUnsafeSshCommand: true,
+    allowUnsafeSubmodule: true,
+    allowUnsafeTemplateDir: true,
+    allowUnsafeUrlRewrite: true,
+    allowUnsafeCustomBinary: true,
+    // Otherwise the plugin exports GIT_TEST_DISALLOW_ABBREVIATED_OPTIONS to the child and the
+    // vault's own hooks start failing on abbreviated long options only when hafez commits.
+    allowAbbreviatedOptions: true
+};
+// Hafez's own git calls are never interactive: GIT_EDITOR outranks core.editor, -c, VISUAL and
+// EDITOR. `.env()` replaces the child env, hence the spread.
+const vaultGit = (vaultPath) => simpleGit({
+    baseDir: vaultPath,
+    allowEnvironment: [...Object.keys(process.env), 'GIT_EDITOR'],
+    unsafe: OPEN_UNSAFE
+}).env({ ...process.env, GIT_EDITOR: 'true' });
 const logMerge = (msg) => process.stderr.write(`[hafez-merge] ${msg}\n`);
 const MAX_PUSH_RETRIES = 3;
 const RETRY_BASE_MS = 200;
@@ -279,7 +322,7 @@ async function pushResolving(git, vaultPath, conflictMessage, exhaustedMessage)
  * All work must be committed before calling — no file save/restore needed.
  */
 export async function gitSync(vaultPath) {
-    const git = simpleGit(vaultPath);
+    const git = vaultGit(vaultPath);
     if (!(await hasOriginRemote(git))) {
         return { pulled: false, pushed: false, remote: false };
     }
@@ -330,7 +373,7 @@ export async function gitSync(vaultPath) {
  */
 async function gitUnstage(vaultPath, files) {
     try {
-        await simpleGit(vaultPath).raw(['reset', '-q', 'HEAD', '--', ...files]);
+        await vaultGit(vaultPath).raw(['reset', '-q', 'HEAD', '--', ...files]);
     }
     catch { /* best effort — rollback must not mask the original error */ }
 }
@@ -390,8 +433,26 @@ function parseNameStatusLine(line) {
     const operation = FILE_STATUS_MAP[match[1]];
     return operation ? [{ path: match[2], operation }] : [];
 }
+/**
+ * Read-side "no history": the one state where `git log` has nothing to say
+ * and empty is the true answer — a repo with no commits yet. Everything else
+ * (a directory that is not a repository, an env-guard or unsafe-category
+ * rejection, a missing git binary, a corrupt repo) is a failure the write
+ * side already reports loudly, so the read side must not hide it. Matched on
+ * git's stderr text, which simple-git carries in `GitError.message`; both
+ * callers pass a `--` pathspec and no revision, and an unborn HEAD then says
+ * exactly this.
+ */
+const NO_HISTORY_RE = /does not have any commits yet/i;
+function isNoHistory(err) {
+    return NO_HISTORY_RE.test(err instanceof Error ? err.message : String(err));
+}
+function gitReadFailed(err) {
+    const lines = (err instanceof Error ? err.message : String(err)).split('\n').map(l => l.trim()).filter(Boolean);
+    return new HafezError('GIT_READ_FAILED', `git read failed: ${lines[0] ?? 'unknown error'}`, lines);
+}
 export async function gitChangelog(vaultPath, since) {
-    const git = simpleGit(vaultPath);
+    const git = vaultGit(vaultPath);
     // Bare dates become local midnight — the same calendar-day boundary the
     // vault stamps and query comparisons use (see dates.ts).
     const normalizedSince = normalizeSinceDate(since);
@@ -402,8 +463,10 @@ export async function gitChangelog(vaultPath, since) {
             '--pretty=format:%H|%aI|%s', '--', ...INDEXED_DIR_PATHSPECS,
         ]);
     }
-    catch {
-        return []; // No git history or invalid since — return empty
+    catch (err) {
+        if (isNoHistory(err))
+            return [];
+        throw gitReadFailed(err);
     }
     if (!output.trim())
         return [];
@@ -439,7 +502,7 @@ export async function gitChangelog(vaultPath, since) {
  * Files with no history (not yet committed) are absent from the map.
  */
 export async function gitFileTimes(vaultPath, mode) {
-    const git = simpleGit(vaultPath);
+    const git = vaultGit(vaultPath);
     let output;
     try {
         const args = ['log', '--pretty=format:%x00%aI', '--name-only', '--', ...INDEXED_DIR_PATHSPECS];
@@ -447,8 +510,10 @@ export async function gitFileTimes(vaultPath, mode) {
             args.splice(1, 0, '--diff-filter=A');
         output = await git.raw(args);
     }
-    catch {
-        return new Map(); // no git history
+    catch (err) {
+        if (isNoHistory(err))
+            return new Map();
+        throw gitReadFailed(err);
     }
     const times = new Map();
     let current = '';
@@ -464,7 +529,7 @@ export async function gitFileTimes(vaultPath, mode) {
     return times;
 }
 export async function gitCommitAndPush(vaultPath, files, message, config = {}) {
-    const git = simpleGit(vaultPath);
+    const git = vaultGit(vaultPath);
     // If a previous run crashed mid-rebase/merge, the repo is stuck.
     // Aborting restores tracked files to their pre-rebase state, which may
     // overwrite files that index.ts just wrote. Save and restore them.

package/dist/index.d.ts

@@ -1,6 +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, UnifiedQueryOpts, AllQueryOpts, SortField, EntitySortField, 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 type { Hafez, HafezConfig, HafezErrorCode, EntityType, EntityStatus, EntityQueryOpts, KnowledgeQueryOpts, SessionQueryOpts, SessionQueryResult, SearchKind, UnifiedQueryOpts, AllQueryOpts, SortField, EntitySortField, KnowledgeSortField, SessionSortField, 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';

package/dist/index.js

@@ -1,5 +1,5 @@
 // src/index.ts
-import { parseFilePath, slugify, kindFromPath, kindDir, isIndexedRelPath, findVaultFile, vaultFileExists, resolveFilePath, scanVaultDir, INDEXED_KINDS } from './vault.js';
+import { parseFilePath, slugify, kindFromPath, kindDir, isMutableRelPath, findVaultFile, findReadableFile, vaultFileExists, resolveFilePath, scanVaultDir, archiveLogPath, MUTABLE_KINDS } from './vault.js';
 import { createGitJournal } from './git.js';
 import { validateSessionLogEntry } from './schema.js';
 import { validateVault } from './validate.js';
@@ -52,6 +52,7 @@ export function createHafez(config) {
         }
     }
     // Layout answers where a slug lives; these bind the vault path once.
+    // Mutations resolve the mutable kinds; `read` reaches a session note too.
     function findFile(slug) { return findVaultFile(vaultPath, slug); }
     function exists(slug) { return vaultFileExists(vaultPath, slug); }
     function regenerateIndexSafe() {
@@ -92,7 +93,7 @@ export function createHafez(config) {
         return idx ? fn(idx) : empty;
     }
     async function read(slug, depth = 'summary') {
-        const filePath = findFile(slug);
+        const filePath = findReadableFile(vaultPath, slug);
         if (!filePath) {
             // A miss carries the closest slugs as its details: the recovery the
             // `read` miss output renders (#91).
@@ -100,9 +101,6 @@ export function createHafez(config) {
             throw new HafezError('NOT_FOUND', `Entity or knowledge '${slug}' not found`, closest);
         }
         const parsed = parseFilePath(filePath);
-        // findFile only resolves the indexed kinds, so the session arm is unreachable
-        if (parsed.kind === 'session')
-            throw new HafezError('NOT_FOUND', `Entity or knowledge '${slug}' not found`);
         if (depth === 'frontmatter')
             return { ...parsed, body: '' };
         if (depth === 'summary') {
@@ -110,6 +108,15 @@ export function createHafez(config) {
         }
         return parsed;
     }
+    /** The archive is an attachment of its entity, reached from it on purpose
+     * (#34): a disk read behind the entity's own slug, never an index row. */
+    async function archive(slug) {
+        const entity = resolveFilePath(vaultPath, slug, 'entity');
+        if (!existsSync(entity))
+            throw new HafezError('NOT_FOUND', `Entity '${slug}' not found`);
+        const path = archiveLogPath(vaultPath, slug);
+        return existsSync(path) ? readFileSync(path, 'utf-8') : null;
+    }
     function rollbackFiles(originals) {
         for (const [path, content] of originals) {
             if (content === null) {
@@ -216,12 +223,10 @@ export function createHafez(config) {
             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)) {
+                // index.md shows the mutable kinds: a session-only write leaves it.
+                if ([...writtenAll, ...deletedAll].some(isMutableRelPath)) {
                     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');
@@ -390,9 +395,11 @@ export function createHafez(config) {
             simulateLinks: (slug, links) => { simulatedLinks.set(slug, links); },
             // Read from disk, not the index: the validate phase must see the vault
             // as `validate` will, and a stale index row would let a linked note go.
+            // The mutable kinds only: a session note's related are a record of
+            // what it touched, and a record must not keep a note from being deleted.
             referrers: (slug) => {
                 const candidates = new Set(simulated.keys());
-                for (const kind of INDEXED_KINDS) {
+                for (const kind of MUTABLE_KINDS) {
                     for (const fp of scanVaultDir(join(vaultPath, kindDir(kind))))
                         candidates.add(basename(fp, '.md'));
                 }
@@ -518,6 +525,8 @@ export function createHafez(config) {
         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 }),
+        query_sessions: async (opts) => withIndex(idx => idx.querySessions(opts), { items: [], total: 0 }),
+        archive,
         validate,
         search: async (query, kind) => withIndex(idx => { idx.syncIfStale(); return idx.search(query, kind); }, []),
         rebuildIndex: async () => {
@@ -540,6 +549,17 @@ export function createHafez(config) {
             return s;
         },
         changelog: (since) => journal.changelog(since),
+        close: () => {
+            // Forget the handle even if closing it throws: a retry must not
+            // re-throw, and getIndex() must never hand out a closed handle.
+            try {
+                _index?.close();
+            }
+            finally {
+                _index = null;
+                _indexInitialized = false;
+            }
+        },
     };
 }
 export { HafezError } from './types.js';

package/dist/knowledge-index.d.ts

@@ -5,7 +5,7 @@
  * imports from this file. */
 export interface VaultIndexRow {
     slug: string;
-    kind: 'entity' | 'knowledge';
+    kind: 'entity' | 'knowledge' | 'session';
     name: string;
     type: string | null;
     status: string | null;

package/dist/schema.d.ts

@@ -1,5 +1,7 @@
 export declare function validateEntityFrontmatter(fm: Record<string, any>): string[];
 export declare function validateKnowledgeFrontmatter(fm: Record<string, any>): string[];
+/** A session note: its name and created stamp, nothing else is required. */
+export declare function validateSessionFrontmatter(fm: Record<string, any>): string[];
 export declare function validateKnowledgeSubtype(fm: Record<string, any>): string[];
 export declare function validateSlugReference(slug: string, field: string, exists: (s: string) => boolean): string | null;
 export declare function validateSessionLogEntry(entry: {

package/dist/schema.js

@@ -30,6 +30,17 @@ export function validateKnowledgeFrontmatter(fm) {
     errors.push(...validateKnowledgeSubtype(fm));
     return errors;
 }
+/** A session note: its name and created stamp, nothing else is required. */
+export function validateSessionFrontmatter(fm) {
+    const errors = [];
+    if (!fm.name || typeof fm.name !== 'string')
+        errors.push('missing required field: name');
+    if (!fm.created)
+        errors.push('missing required field: created');
+    if (fm.related !== undefined && !Array.isArray(fm.related))
+        errors.push('session related must be an array');
+    return errors;
+}
 export function validateKnowledgeSubtype(fm) {
     const errors = [];
     if (fm.subtype && !VALID_SUBTYPES.includes(fm.subtype)) {