hafez 2.2.0 → 2.3.0

package/dist/graph/server.js

@@ -0,0 +1,189 @@
+// src/graph/server.ts
+// The graph server (#251): the Vault's Graph and the page that draws it,
+// served on 127.0.0.1 over node:http. Read-only by construction: every route
+// is a GET, and none of them reaches a write on the Hafez instance.
+import { createServer } from 'http';
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+import { HafezError } from '../types.js';
+import { GRAPH_LAYERS } from '../contracts.js';
+import { readJsonOf } from '../read-json.js';
+import { parseSessionLog } from '../document.js';
+import { DEFAULT_POLL_MS, startLive } from './live.js';
+import { FONT_FILES } from './fonts.js';
+import { activity } from './activity.js';
+/** Where the port search starts when no port is asked for. */
+export const DEFAULT_PORT = 4747;
+/** The esbuild bundle of src/graph/client/. From src/graph (tests) and from
+ * dist/graph (installed) alike, `../../dist/graph` is the build output. */
+const BUILD_DIR = join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'dist', 'graph');
+const BUNDLE_PATH = join(BUILD_DIR, 'client.js');
+const PAGE = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Hafez graph</title>
+<link rel="icon" href="data:,">
+</head>
+<body>
+<script src="/client.js"></script>
+</body>
+</html>
+`;
+export async function startGraphServer({ os, port, pollMs = DEFAULT_POLL_MS }) {
+    // Every layer: the page holds them all and toggles them locally (#257).
+    let graphJson = '';
+    /** Each node's name by id, for `/activity`'s rows. */
+    let names = new Map();
+    /** `/activity`'s body, read on first request after each rebuild. */
+    let activityJson;
+    // The server trusts its poll (#264, #271): the index syncs here, at start and
+    // on each commit the poll sees, never per request. On an instance whose
+    // indexSync is 'manual', `/note` then reads the index as the Graph drew it.
+    const rebuild = async () => {
+        await os.syncIndex();
+        const graph = await os.graph({ layers: [...GRAPH_LAYERS] });
+        graphJson = JSON.stringify(graph);
+        names = new Map(graph.nodes.map(n => [n.id, n.name]));
+        activityJson = undefined;
+    };
+    const live = await startLive(os, pollMs, rebuild);
+    await rebuild().catch(async (err) => { await live.stop(); throw err; });
+    let bundle;
+    // One entry per fixed GET route; a route is added here and nowhere else, but
+    // for the four matched before the record: the `/events` stream, `/activity`
+    // (built asynchronously), and the `/note/` and `/fonts/` prefixes.
+    const routes = {
+        '/': () => ({ type: 'text/html', body: PAGE }),
+        '/client.js': () => ({ type: 'text/javascript', body: bundle ??= readFileSync(BUNDLE_PATH, 'utf-8') }),
+        '/graph': () => ({ type: 'application/json', body: graphJson }),
+    };
+    // A page on any other origin can reach 127.0.0.1 too; checking the Host
+    // header is what keeps DNS rebinding from reading the Vault through it.
+    let allowedHosts = new Set();
+    const server = createServer((req, res) => {
+        if (!allowedHosts.has(req.headers.host ?? ''))
+            return send(res, 403, { type: 'text/plain', body: 'Forbidden' });
+        if (req.method !== 'GET')
+            return send(res, 405, { type: 'text/plain', body: 'Method Not Allowed' }, { Allow: 'GET' });
+        const path = new URL(req.url ?? '/', 'http://localhost').pathname;
+        if (path === '/events')
+            return live.subscribe(req, res);
+        if (path === '/activity')
+            return void sendActivity(res);
+        if (path.startsWith(NOTE_PREFIX))
+            return void sendNote(os, res, path.slice(NOTE_PREFIX.length));
+        if (path.startsWith(FONT_PREFIX))
+            return sendFont(res, path.slice(FONT_PREFIX.length));
+        const route = routes[path];
+        if (!route)
+            return send(res, 404, { type: 'text/plain', body: 'Not Found' });
+        try {
+            send(res, 200, route());
+        }
+        catch (err) {
+            send(res, 500, { type: 'text/plain', body: err.message });
+        }
+    });
+    async function sendActivity(res) {
+        const body = activityJson ??= activity(os, names).then(rows => JSON.stringify(rows));
+        try {
+            send(res, 200, { type: 'application/json', body: await body });
+        }
+        catch (err) {
+            if (activityJson === body)
+                activityJson = undefined; // the next request tries again
+            send(res, 500, { type: 'text/plain', body: err.message });
+        }
+    }
+    const bound = await (port === undefined ? listenFirstFree(server, DEFAULT_PORT) : listen(server, port))
+        .catch(async (err) => { await live.stop(); throw err; });
+    allowedHosts = new Set([`127.0.0.1:${bound}`, `localhost:${bound}`]);
+    return {
+        url: `http://127.0.0.1:${bound}`,
+        close: async () => {
+            await live.stop();
+            await new Promise(resolve => {
+                server.close(() => resolve());
+                server.closeAllConnections();
+            });
+            os.close();
+        },
+    };
+}
+function listen(server, port) {
+    return new Promise((resolve, reject) => {
+        const onError = (err) => reject(err);
+        server.once('error', onError);
+        server.listen(port, '127.0.0.1', () => {
+            server.off('error', onError);
+            resolve(server.address().port);
+        });
+    });
+}
+async function listenFirstFree(server, from) {
+    for (let port = from;; port++) {
+        try {
+            return await listen(server, port);
+        }
+        catch (err) {
+            if (err.code !== 'EADDRINUSE' || port >= 65535)
+                throw err;
+        }
+    }
+}
+const NOTE_PREFIX = '/note/';
+/** How many Session Log entries `/note` gives an entity. */
+const LOG_SHOWN = 5;
+/** `/note/:slug`: `read --json` at summary depth; an entity's adds `log`, its
+ * Session Log's last LOG_SHOWN entries newest first (#271). A slug with no
+ * note, or one that cannot name a note at all, is 404 with the closest slugs,
+ * as a `read --json` miss prints them. */
+async function sendNote(os, res, encoded) {
+    let slug = encoded;
+    try {
+        slug = decodeURIComponent(encoded);
+        send(res, 200, { type: 'application/json', body: JSON.stringify(await noteJson(os, slug)) });
+    }
+    catch (err) {
+        const miss = err instanceof URIError || (err instanceof HafezError && (err.code === 'NOT_FOUND' || err.code === 'VALIDATION_FAILED'));
+        if (!miss)
+            return send(res, 500, { type: 'text/plain', body: err.message });
+        const closest = err instanceof HafezError && err.code === 'NOT_FOUND' ? err.details ?? [] : [];
+        send(res, 404, { type: 'application/json', body: JSON.stringify({ slug, closest }) });
+    }
+}
+async function noteJson(os, slug) {
+    const summary = await os.read(slug, 'summary');
+    if (summary.kind !== 'entity')
+        return readJsonOf(os, slug, 'summary', summary);
+    // The whole entity, read once: readJsonOf's Footer and pointers, and the log.
+    const whole = await os.read(slug, 'full');
+    const log = parseSessionLog(whole.body).slice(0, LOG_SHOWN);
+    return { ...await readJsonOf(os, slug, 'summary', summary, whole), log };
+}
+const FONT_PREFIX = '/fonts/';
+/** Read once each, on first request. */
+const fontCache = new Map();
+/** `/fonts/:file`: a bundled font or its licence, by the fixed list in fonts.ts
+ * and nothing else. The name is matched as given, never joined to a path. */
+function sendFont(res, file) {
+    if (!FONT_FILES.has(file))
+        return send(res, 404, { type: 'text/plain', body: 'Not Found' });
+    try {
+        let body = fontCache.get(file);
+        if (!body)
+            fontCache.set(file, body = readFileSync(join(BUILD_DIR, 'fonts', file)));
+        const type = file.endsWith('.woff2') ? 'font/woff2' : 'text/plain';
+        send(res, 200, { type, body }, { 'Cache-Control': 'max-age=86400' });
+    }
+    catch (err) {
+        send(res, 500, { type: 'text/plain', body: err.message });
+    }
+}
+function send(res, status, { type, body }, headers = {}) {
+    res.writeHead(status, { 'Content-Type': type.startsWith('font/') ? type : `${type}; charset=utf-8`, ...headers });
+    res.end(body);
+}

package/dist/health.d.ts

@@ -0,0 +1,6 @@
+import type { HealthReport } from './types.js';
+/** The threshold a recurring name lists at (#239). */
+export declare const RECURRING_MIN_UNITS = 10;
+/** The share of a decision's summary tokens a note must carry. */
+export declare const RESTATE_SHARE = 0.5;
+export declare function healthReport(vaultPath: string): HealthReport;

package/dist/health.js

@@ -0,0 +1,310 @@
+// src/health.ts
+// The Health pass (see CONTEXT.md; #239, #244): what placement would change,
+// as a typed report. Like the Vault Scan (validate.ts) it reads the vault
+// files directly and never the index, so it reports what is on disk. It
+// applies nothing. Reference definitions: tools/research/ws_caps_prefix.py
+// (through src/workstream.ts), ws_recurring_name.py, ws_leak.py,
+// ws_restate.py; (iii) and (v) follow ADR 0002.
+import { join, basename } from 'path';
+import { existsSync, readFileSync } from 'fs';
+import { parseFilePath, scanVaultDir, kindDir, archiveLogPath } from './vault.js';
+import { ACTION_RE, actionAdded, documentForFile, escapeRegex, parseSessionLogHeading, splitLogEntries, stripActionStamp, WIKI_LINK_RE } from './document.js';
+import { workstreams, wordTokens } from './workstream.js';
+const ENTITY_DOC = documentForFile({ kind: 'entity' });
+const KNOWLEDGE_DOC = documentForFile({ kind: 'knowledge' });
+function parseActions(body) {
+    return ENTITY_DOC.actionLines(body).map(block => {
+        const [line, ...carried] = block.split('\n');
+        const m = ACTION_RE.exec(line);
+        const folded = carried.filter(l => l.startsWith('  ') && l.trim()).map(l => l.trim());
+        return { text: [stripActionStamp(m[2]), ...folded].join(' '), added: actionAdded(m[2]) };
+    });
+}
+/** The entries of a Session Log section or an archive, as ws_common.py
+ * reads them: the summary is the first `Summary:` line anywhere in the
+ * entry. */
+function parseLog(content) {
+    return splitLogEntries(content).map(block => {
+        const [heading, ...rest] = block.split('\n');
+        const head = parseSessionLogHeading(heading);
+        const lines = rest.map(l => l.trim()).filter(Boolean);
+        const at = lines.findIndex(l => l.startsWith('Summary:'));
+        const summary = at === -1 ? '' : lines[at].slice(8).trim();
+        const text = lines.map((l, i) => i === at ? summary : l).join(' ');
+        return { day: head.date, type: head.type, summary, text };
+    });
+}
+function loadLog(vaultPath, slug, body) {
+    const section = ENTITY_DOC.findSection(body, 'Session Log')?.content ?? '';
+    const archive = archiveLogPath(vaultPath, slug);
+    return [...parseLog(section), ...(existsSync(archive) ? parseLog(readFileSync(archive, 'utf-8')) : [])];
+}
+/** Every parseable entity, slug order. A file that fails to parse is
+ * `validate`'s to report, not this pass's. */
+function loadEntities(vaultPath) {
+    const out = [];
+    for (const filePath of scanVaultDir(join(vaultPath, kindDir('entity'))).sort()) {
+        const slug = basename(filePath, '.md');
+        let fm, body;
+        try {
+            ({ frontmatter: fm, body } = parseFilePath(filePath));
+        }
+        catch {
+            continue;
+        }
+        out.push({
+            slug,
+            name: String(fm.name ?? slug),
+            created: String(fm.created ?? ''),
+            parent: typeof fm.parent === 'string' ? fm.parent : null,
+            related: Array.isArray(fm.related) ? fm.related.map(String) : [],
+            body,
+            actions: parseActions(body),
+            log: loadLog(vaultPath, slug, body),
+        });
+    }
+    return out;
+}
+/** Every parseable knowledge note, slug order. */
+function loadKnowledge(vaultPath) {
+    const out = [];
+    for (const filePath of scanVaultDir(join(vaultPath, kindDir('knowledge'))).sort()) {
+        const slug = basename(filePath, '.md');
+        let fm, body;
+        try {
+            ({ frontmatter: fm, body } = parseFilePath(filePath));
+        }
+        catch {
+            continue;
+        }
+        out.push({
+            slug,
+            name: String(fm.name ?? slug),
+            created: String(fm.created ?? ''),
+            parent: null,
+            related: Array.isArray(fm.related) ? fm.related.map(String) : [],
+            body,
+        });
+    }
+    return out;
+}
+/** Check (i): the family module over each entity, against the entities
+ * whose `parent` or `related` name it. */
+function checkWorkstreams(entities) {
+    return entities.flatMap(e => {
+        const naming = entities.filter(o => o.parent === e.slug || o.related.includes(e.slug));
+        return workstreams(e.body, naming).map(w => ({ entity: e.slug, ...w }));
+    });
+}
+// --- Check (ii): ws_recurring_name.py ---
+/** The threshold a recurring name lists at (#239). */
+export const RECURRING_MIN_UNITS = 10;
+const SLUGISH_RE = /(?<![\w/.])([a-z][a-z0-9]*(?:-[a-z0-9]+)+)(?![\w/])/g;
+const CAPWORD = '[A-Z][a-zA-Z0-9]+';
+const PROPER_RE = new RegExp(`(?<![.!?:;]\\s)(?<!^)(?<!\\n)\\b(${CAPWORD}(?: ${CAPWORD})?)\\b`, 'g');
+const FAMILY_RE = /\b(WS\d+|WS-[A-Z])\b/g;
+const DATE_LIKE_RE = /^\d{4}-\d{2}-\d{2}$|^\d+-\d+$/;
+const SLUGISH_SKIP_HEADS = new Set(['add', 'dry', 'read', 'auto']);
+/** The script's list minus the owner's first name (a leak pattern in the public
+ * tree): months, weekdays, agents, function
+ * words, number words, acronyms, products, pronouns, quantifiers. */
+const RECURRING_STOP = new Set(`January February March April May June July August September October November December
+Jan Feb Mar Apr Jun Jul Aug Sep Sept Oct Nov Dec Monday Tuesday Wednesday Thursday Friday Saturday Sunday
+Claude Codex Summary Decision Decisions Next Step Steps Phase Session Sessions Day Week Workshop
+The A An And Or But Not No Yes For From With Into Over Under Then Now Done Open Owner Owned Fix Fixed
+Also New Old One Two Three Four Five Six Seven Eight Nine Ten First Second Third Last Final Draft
+PR PRs CI API URL CLI SDK UK US ID MD JSON YAML CSV PDF HTML SQL FTS SHA IP UI UX QA DAX
+Notion GitHub Google Windows Linux WSL Python Node Power BI Excel Teams Outlook Slack Telegram
+If When Where What Which Who Why How This That These Those It Its He His Him She Her They Them We Our
+Still Both Either Neither Each Every Any Some Most Many Few Such Same Other Another Only Just Even
+Before After Since Until While Because So Than Too Very Here There`.split(/\s+/));
+const isUpper = (w) => w === w.toUpperCase() && w !== w.toLowerCase();
+/** The terms of one unit's text: slug-shaped names that are no note's slug,
+ * capitalised words or bigrams not at a sentence start (minus the stop set,
+ * the entity's own name tokens and all-caps runs, which are check (i)), and
+ * `WS` family codes. */
+function termsIn(text, ownTokens, slugs) {
+    const terms = new Set();
+    for (const m of text.matchAll(SLUGISH_RE)) {
+        const s = m[1];
+        if (slugs.has(s) || DATE_LIKE_RE.test(s) || s.length < 6)
+            continue;
+        if (s.startsWith('http') || s.startsWith('www') || SLUGISH_SKIP_HEADS.has(s.split('-')[0]))
+            continue;
+        terms.add(s);
+    }
+    for (const m of text.matchAll(PROPER_RE)) {
+        const words = m[1].split(' ');
+        if (words.some(w => RECURRING_STOP.has(w) || ownTokens.has(w.toLowerCase())))
+            continue;
+        if (words.every(isUpper))
+            continue;
+        terms.add(m[1]);
+    }
+    for (const m of text.matchAll(FAMILY_RE))
+        terms.add(m[1]);
+    return terms;
+}
+/** Check (ii): a term in RECURRING_MIN_UNITS or more units (log entries and
+ * action lines) of one entity across two or more days; an undated action
+ * line counts as a unit but not as a day. */
+function checkRecurringNames(entities, slugs) {
+    const out = [];
+    for (const e of entities) {
+        const own = wordTokens(`${e.name} ${e.slug}`);
+        const units = new Map();
+        const add = (text, day) => {
+            for (const t of termsIn(text, own, slugs))
+                units.set(t, [...(units.get(t) ?? []), day]);
+        };
+        for (const entry of e.log)
+            add(entry.text, entry.day);
+        for (const a of e.actions)
+            add(a.text, a.added);
+        const rows = [];
+        for (const [term, days] of units) {
+            const distinct = [...new Set(days.filter((d) => d !== null))].sort();
+            if (days.length >= RECURRING_MIN_UNITS && distinct.length >= 2)
+                rows.push({ entity: e.slug, term, units: days.length, days: distinct });
+        }
+        out.push(...rows.sort((a, b) => b.units - a.units || a.term.localeCompare(b.term)));
+    }
+    return out;
+}
+// --- Check (iv): ws_leak.py ---
+/** The child's slug, or its name when longer than three characters, as a
+ * whole word (ws_leak.py `mentions`). */
+function mentionsRe(c) {
+    const pats = [escapeRegex(c.slug)];
+    if (c.name.length > 3)
+        pats.push(escapeRegex(c.name));
+    return new RegExp(`(?<![\\w-])(?:${pats.join('|')})(?![\\w-])`, 'i');
+}
+/** Check (iv): for each child C and each P that is C's parent or an entity
+ * in C's related, P's log entries dated on or after C's `created` naming C.
+ * Pairs with no hit are left out. */
+function checkLeakage(entities) {
+    const bySlug = new Map(entities.map(e => [e.slug, e]));
+    const out = [];
+    for (const c of entities) {
+        const parents = [...(c.parent ? [c.parent] : []), ...c.related.filter(r => r !== c.parent)];
+        const rx = mentionsRe(c);
+        for (const p of parents) {
+            const P = bySlug.get(p);
+            if (!P)
+                continue;
+            const after = P.log.filter(e => e.day >= c.created);
+            const hits = after.filter(e => rx.test(e.text)).length;
+            if (hits === 0)
+                continue;
+            out.push({ parent: p, child: c.slug, relation: p === c.parent ? 'parent' : 'related', hits, entries: after.length });
+        }
+    }
+    return out;
+}
+// --- Checks (iii) and (v): ADR 0002 ---
+const WIKI_LINK_ALL_RE = new RegExp(WIKI_LINK_RE.source, 'g');
+/** A parent and its child are never `related` (parent subsumes related):
+ * the link line for such a pair would be rejected, so neither check lists it. */
+const parentBound = (a, b) => a.parent === b.slug || b.parent === a.slug;
+/** Check (iii): a same-kind `related` edge with one end. A target that is
+ * not a note of the kind is a cross-kind edge or a broken slug, neither
+ * this check's. */
+function checkOneWayEdges(notes) {
+    const bySlug = new Map(notes.map(n => [n.slug, n]));
+    const out = [];
+    for (const a of notes) {
+        for (const b of a.related) {
+            const B = bySlug.get(b);
+            if (B && b !== a.slug && !B.related.includes(a.slug) && !parentBound(a, B))
+                out.push({ from: a.slug, to: b });
+        }
+    }
+    return out;
+}
+/** Check (v): a `[[slug]]` in a note's body naming another note of the
+ * kind, with no `related` edge either way; a pair mentioned from both sides
+ * lists once, from the first in slug order. */
+function checkUnlinkedMentions(notes) {
+    const bySlug = new Map(notes.map(n => [n.slug, n]));
+    const seen = new Set();
+    const out = [];
+    for (const a of notes) {
+        for (const m of a.body.matchAll(WIKI_LINK_ALL_RE)) {
+            const b = m[1];
+            const B = bySlug.get(b);
+            if (!B || b === a.slug || a.related.includes(b) || B.related.includes(a.slug) || parentBound(a, B))
+                continue;
+            const pair = [a.slug, b].sort().join('\0');
+            if (seen.has(pair))
+                continue;
+            seen.add(pair);
+            out.push({ from: a.slug, to: b });
+        }
+    }
+    return out;
+}
+// --- Check (vi): ws_restate.py ---
+/** The share of a decision's summary tokens a note must carry. */
+export const RESTATE_SHARE = 0.5;
+/** The script's own stop list, verbatim; not src/stopwords.ts. */
+const RESTATE_STOP = new Set(`the a an and or but not of to in on for with by from at as is are was were be been being it its
+this that these those we our you your they their he she his her them us i me my if then than so no yes
+do does did done has have had having can could will would should may might must into over under out up
+down off about after before between through during per via one two three four five six seven eight nine
+ten first second third new old now here there when where which who whom whose what why how all any each
+every some such same other another only also just even still both either neither own very more most less
+few many much see entry entries issue map ticket pr`.split(/\s+/));
+function restateTokens(text) {
+    const out = new Set();
+    for (const m of text.toLowerCase().matchAll(/[a-z0-9][a-z0-9'’\-]*/g)) {
+        if (m[0].length >= 3 && !RESTATE_STOP.has(m[0]))
+            out.add(m[0]);
+    }
+    return out;
+}
+/** Check (vi): for each `decision` entry on an entity, each knowledge note
+ * created on the entry's day and `related` to the entity whose name plus
+ * Synthesis carries RESTATE_SHARE or more of the entry's summary tokens. */
+function checkRestatedDecisions(entities, knowledge) {
+    const out = [];
+    for (const e of entities) {
+        const notes = knowledge.filter(n => n.related.includes(e.slug));
+        if (!notes.length)
+            continue;
+        for (const entry of e.log) {
+            if (entry.type !== 'decision')
+                continue;
+            const st = restateTokens(entry.summary);
+            if (!st.size)
+                continue;
+            for (const n of notes) {
+                if (n.created !== entry.day)
+                    continue;
+                const nt = restateTokens(`${n.name} ${KNOWLEDGE_DOC.findSection(n.body, 'Synthesis')?.content ?? ''}`);
+                const share = [...st].filter(t => nt.has(t)).length / st.size;
+                if (share >= RESTATE_SHARE)
+                    out.push({ day: entry.day, entity: e.slug, note: n.slug, share, summary: entry.summary });
+            }
+        }
+    }
+    return out;
+}
+/** Every note's slug, every kind: a slug-shaped name that is a note is not
+ * a recurring name. */
+function allSlugs(vaultPath) {
+    const kinds = ['entity', 'knowledge', 'session'];
+    return new Set(kinds.flatMap(k => scanVaultDir(join(vaultPath, kindDir(k))).map(f => basename(f, '.md'))));
+}
+export function healthReport(vaultPath) {
+    const entities = loadEntities(vaultPath);
+    const knowledge = loadKnowledge(vaultPath);
+    return {
+        workstreams: checkWorkstreams(entities),
+        recurring_names: checkRecurringNames(entities, allSlugs(vaultPath)),
+        leakage: checkLeakage(entities),
+        one_way_edges: [...checkOneWayEdges(entities), ...checkOneWayEdges(knowledge)],
+        unlinked_mentions: [...checkUnlinkedMentions(entities), ...checkUnlinkedMentions(knowledge)],
+        restated_decisions: checkRestatedDecisions(entities, knowledge),
+    };
+}

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, 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 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, CreateSessionFields, QueryFilter, QueryResult, KnowledgeQueryResult, UnifiedResult, ValidationReport, BatchOperation, BatchResult, ReadDepth, ConfidenceLevel, LinkRelation, GitConfig, Journal, SearchResult, VaultStats, ChangelogEntry, KnowledgeSubtype, Graph, GraphNode, GraphEdge, GraphOpts, ChangesSince, NoteChange, ChangeOp, FileChange } from './types.js';
 export { getBrief, getNextActions } from './document.js';
 export { parseSessionLogHeading, parseSessionLog } from './document.js';

package/dist/index.js

@@ -1,8 +1,9 @@
 // src/index.ts
-import { parseFilePath, slugify, kindFromPath, kindDir, isMutableRelPath, findVaultFile, findReadableFile, vaultFileExists, resolveFilePath, scanVaultDir, archiveLogPath, MUTABLE_KINDS } from './vault.js';
+import { parseFilePath, slugify, kindFromPath, kindDir, isMutableRelPath, findVaultFile, findReadableFile, vaultFileExists, resolveFilePath, scanVaultDir, archiveLogPath, noteAtRelPath, MUTABLE_KINDS } from './vault.js';
 import { createGitJournal } from './git.js';
 import { validateSessionLogEntry } from './schema.js';
 import { validateVault } from './validate.js';
+import { healthReport } from './health.js';
 import { documentForFile } from './document.js';
 import { createIndex } from './db.js';
 import { closestSlugs } from './closest.js';
@@ -14,7 +15,9 @@ import { readFileSync, writeFileSync, existsSync, unlinkSync } from 'fs';
 import { join, basename } from 'path';
 import { lock as lockVault } from 'proper-lockfile';
 export function createHafez(config) {
-    const { vaultPath, readOnly = false, git: gitConfig = {}, onWrite } = config;
+    const { vaultPath, readOnly = false, git: gitConfig = {}, onWrite, indexSync = 'read' } = config;
+    // When reads catch the index up with the files (src/internal.ts, off the
+    // public types): 'once' is the CLI's (#269), 'manual' the graph server's (#271).
     // The persistence seam (CONTEXT.md: Journal). Everything below talks to
     // history through this port; git is just the default adapter.
     const journal = config.persistence ?? createGitJournal(vaultPath, gitConfig);
@@ -66,8 +69,12 @@ export function createHafez(config) {
             // outside hafez — a hand edit, a git pull — are represented too; that
             // costs a stat per file, where the old path paid a parse per file on
             // every single mutation.
+            // Under 'once' the process's first read already caught up.
             const idx = getIndex();
-            idx?.syncIfStale();
+            if (indexSync === 'once')
+                idx?.syncForRead();
+            else
+                idx?.syncIfStale();
             generateVaultIndex(vaultPath, idx?.indexEntries());
         }
         catch (err) {
@@ -78,7 +85,7 @@ export function createHafez(config) {
     let _indexInitialized = false;
     function getIndex() {
         if (!_indexInitialized) {
-            _index = readOnly ? createIndex(vaultPath, { readonly: true }) : createIndex(vaultPath);
+            _index = readOnly ? createIndex(vaultPath, { readonly: true, sync: indexSync }) : createIndex(vaultPath, { sync: indexSync });
             // A null read-only open means the on-disk index is missing or from another
             // schema version. Don't latch it: retry on the next call so a long-lived
             // read-only instance starts serving once a write-capable process rebuilds.
@@ -97,7 +104,7 @@ export function createHafez(config) {
         if (!filePath) {
             // A miss carries the closest slugs as its details: the recovery the
             // `read` miss output renders (#91).
-            const closest = withIndex(idx => { idx.syncIfStale(); return closestSlugs(slug, idx.indexEntries()); }, []);
+            const closest = withIndex(idx => { idx.syncForRead(); return closestSlugs(slug, idx.indexEntries()); }, []);
             throw new HafezError('NOT_FOUND', `Entity or knowledge '${slug}' not found`, closest);
         }
         const parsed = parseFilePath(filePath);
@@ -483,6 +490,9 @@ export function createHafez(config) {
     async function validate() {
         return validateVault(vaultPath);
     }
+    async function health() {
+        return healthReport(vaultPath);
+    }
     async function promote(slug, target) {
         // Rollback safety rides the Spine: applyOperation's promote arm captures
         // both the source file and (for cross-kind moves) the knowledge target
@@ -498,7 +508,8 @@ export function createHafez(config) {
         knowledge_count: 0,
         stale: [], no_next_action: [], recently_touched: [], recently_created: [],
     };
-    return {
+    // An InternalHafez: syncIndex() is here, off the public Hafez type.
+    const hafez = {
         read,
         update,
         promote,
@@ -528,7 +539,10 @@ export function createHafez(config) {
         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); }, []),
+        health,
+        search: async (query, kind) => withIndex(idx => { idx.syncForRead(); return idx.search(query, kind); }, []),
+        graph: async (opts) => withIndex(idx => idx.queryGraph(opts), { nodes: [], edges: [] }),
+        syncIndex: async () => { withIndex(idx => idx.syncIfStale(), undefined); },
         rebuildIndex: async () => {
             if (readOnly)
                 throw new HafezError('VALIDATION_FAILED', 'Hafez instance is read-only');
@@ -542,13 +556,26 @@ export function createHafez(config) {
             const idx = getIndex();
             if (!idx)
                 return emptyStats;
-            idx.syncIfStale();
+            idx.syncForRead();
             const s = idx.getStats();
             s.recently_touched = await rankRecents(s.recently_touched, 'last_touched', 'modified');
             s.recently_created = await rankRecents(s.recently_created, 'created', 'added');
             return s;
         },
-        changelog: (since) => journal.changelog(since),
+        changelog: async (since, limit) => {
+            if (limit !== undefined && !(Number.isInteger(limit) && limit > 0)) {
+                throw new HafezError('VALIDATION_FAILED', `changelog limit must be a positive whole number of commits, got ${limit}`);
+            }
+            return journal.changelog(since, limit);
+        },
+        changesSince: async (cursor) => {
+            const { cursor: next, files } = await journal.changesSince(cursor);
+            const changes = files.flatMap(({ path, op }) => {
+                const note = noteAtRelPath(path);
+                return note ? [{ ...note, op }] : [];
+            });
+            return { cursor: next, changes };
+        },
         close: () => {
             // Forget the handle even if closing it throws: a retry must not
             // re-throw, and getIndex() must never hand out a closed handle.
@@ -561,6 +588,7 @@ export function createHafez(config) {
             }
         },
     };
+    return hafez;
 }
 export { HafezError } from './types.js';
 export { getBrief, getNextActions } from './document.js';

package/dist/internal.d.ts

@@ -0,0 +1,21 @@
+import type { Hafez, HafezConfig } from './types.js';
+import type { IndexSync } from './db.js';
+export interface InternalHafezConfig extends HafezConfig {
+    /** When the index catches up with files changed outside hafez (a hand edit,
+     * a raw git pull). 'read' (default): before every index read, a stat per
+     * note, so a long-lived instance never reads a stale index. 'once': the
+     * first index read syncs, later reads trust the index — the CLI's mode, one
+     * scan per process (#269); a file changed outside hafez after that read is
+     * seen by the next process, or after `syncIndex()`. Writes through the
+     * instance are indexed as they commit in every mode. 'manual': reads trust
+     * the index, and `syncIndex()` syncs it — the graph server's mode, which
+     * syncs when its poll sees a commit (#271). */
+    indexSync?: IndexSync;
+}
+export interface InternalHafez extends Hafez {
+    /** Catch the index up with files changed outside hafez, in every mode:
+     * what a read does first under `indexSync` 'read', and the first read under 'once'. */
+    syncIndex(): Promise<void>;
+}
+/** createHafez with the internal options: every instance it builds is an InternalHafez. */
+export declare function createInternalHafez(config: InternalHafezConfig): InternalHafez;

package/dist/internal.js

@@ -0,0 +1,9 @@
+// src/internal.ts
+// What hafez's own CLI and graph server reach that the package does not
+// export: src/index.ts re-exports none of it, and package.json's `exports`
+// map stops a deep import. Off the library surface by the owner's call (#270).
+import { createHafez } from './index.js';
+/** createHafez with the internal options: every instance it builds is an InternalHafez. */
+export function createInternalHafez(config) {
+    return createHafez(config);
+}