hafez 2.2.0 → 2.3.0

package/dist/cli/block-hook.d.ts

@@ -7,3 +7,9 @@ export interface BlockHookCtx extends ConfigHome {
 }
 /** The render, or null for any failure: the caller prints nothing. */
 export declare function blockHook(ctx: BlockHookCtx): Promise<string | null>;
+/** The working directory, its git root, and in a linked worktree the main
+ * repository's root. */
+export declare function foldersOf(cwd: string): string[];
+/** Every remote's URL, normalised. */
+export declare function remoteUrls(cwd: string): string[];
+export declare function resourceMatches(resource: string, folders: string[], remotes: string[]): boolean;

package/dist/cli/block-hook.js

@@ -58,7 +58,7 @@ function git(cwd, ...args) {
 }
 /** The working directory, its git root, and in a linked worktree the main
  * repository's root. */
-function foldersOf(cwd) {
+export function foldersOf(cwd) {
     const folders = [cwd];
     const out = git(cwd, 'rev-parse', '--path-format=absolute', '--show-toplevel', '--git-common-dir');
     const [top, common] = out?.split('\n') ?? [];
@@ -84,7 +84,7 @@ function canonical(path) {
     return existsSync(abs) ? realpathSync.native(abs) : abs;
 }
 /** Every remote's URL, normalised. */
-function remoteUrls(cwd) {
+export function remoteUrls(cwd) {
     const out = git(cwd, 'config', '--get-regexp', '^remote\\..*\\.url$');
     return out ? out.split('\n').map(line => normaliseUrl(line.slice(line.indexOf(' ') + 1))) : [];
 }
@@ -98,7 +98,7 @@ function normaliseUrl(url) {
         .replace(/\/+$/, '')
         .replace(/\.git$/, '');
 }
-function resourceMatches(resource, folders, remotes) {
+export function resourceMatches(resource, folders, remotes) {
     if (isAbsolute(resource))
         return folders.includes(canonical(resource));
     return remotes.includes(normaliseUrl(resource));

package/dist/cli/commands.d.ts

@@ -36,6 +36,8 @@ export declare function cmdCapture(os: Hafez, args: string[], opts?: CommandOpts
 export declare function cmdPromote(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdDelete(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdValidate(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
+export declare function cmdHealth(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
+export declare function cmdGraph(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdIndexRebuild(os: Hafez): Promise<string>;
 export declare function cmdSync(os: Hafez, args: string[]): Promise<string>;
 export declare function cmdStats(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;

package/dist/cli/commands.js

@@ -7,13 +7,14 @@ import { BatchOperationSchema, normalizeAliases, opErrorLine, batchInvalidHeader
 import { formatBatchError } from './batch-errors.js';
 import { parseDigestInput, digest } from '../digest.js';
 import { detectAgent } from '../harness.js';
-import { getActionItems, parseSessionLogHeading } from '../document.js';
 import { resemblances } from '../near-match.js';
-import { actionAge, agedActions, staleHandles, stalenessDaysOf } from '../stale.js';
+import { actionAge, staleHandles, stalenessDaysOf } from '../stale.js';
 import { slugify } from '../vault.js';
-import { ITEMS, footerOp } from '../surfaces/items.js';
+import { GRAPH_LAYERS } from '../contracts.js';
+import { ITEMS } from '../surfaces/items.js';
+import { footerFor, pointersFor, readJsonOf } from '../read-json.js';
 import { placeIn } from '../surfaces/surfaces.js';
-import { formatEntityHeader, formatKnowledgeHeader, formatSessionHeader, formatQueryTable, formatKnowledgeTable, formatSessionTable, formatSearchResults, formatValidation, formatStats, formatChangelog } from './format.js';
+import { formatEntityHeader, formatKnowledgeHeader, formatSessionHeader, formatQueryTable, formatKnowledgeTable, formatSessionTable, formatSearchResults, formatValidation, formatHealth, formatStats, formatChangelog } from './format.js';
 function jsonOut(data) {
     return JSON.stringify(data, null, 2);
 }
@@ -25,14 +26,7 @@ export async function cmdRead(os, args, opts = {}) {
     if (!slug)
         throw new UsageError(READ_USAGE);
     const depth = (str(flags.depth) ?? 'summary');
-    const result = await os.read(slug, depth).catch(err => {
-        if (!(err instanceof HafezError) || err.code !== 'NOT_FOUND')
-            throw err;
-        const closest = err.details ?? [];
-        throw opts.json
-            ? new RenderedError('NOT_FOUND', jsonOut({ slug, closest }), 'stdout')
-            : new RenderedError('NOT_FOUND', ITEMS.slugMissRecovery.render({ slug, closest }), 'stderr');
-    });
+    const result = await os.read(slug, depth).catch(err => { throw readMiss(err, slug, opts); });
     if (flags.archive) {
         // The archive is an entity's: reached from it on purpose (#34).
         if (result.kind !== 'entity')
@@ -42,26 +36,23 @@ export async function cmdRead(os, args, opts = {}) {
             return jsonOut({ slug, archive });
         return archive ?? `no archive for ${slug}`;
     }
+    if (opts.json)
+        return jsonOut(await readJsonOf(os, slug, depth, result));
     // A session note is read, never written: no Footer (#35).
-    if (result.kind === 'session') {
-        if (opts.json)
-            return jsonOut(result);
+    if (result.kind === 'session')
         return formatSessionHeader(result.frontmatter, result.body);
-    }
-    const footer = await footerFor(os, slug, result, depth);
-    const pointers = result.kind === 'entity' ? await pointersFor(os, slug) : null;
-    if (opts.json) {
-        const writes = footerOp(footer);
-        // A frontmatter-depth read carries no body, so it has no actions to list.
-        if (result.kind !== 'entity' || depth === 'frontmatter')
-            return jsonOut({ ...result, ...pointers, writes });
-        return jsonOut({ ...result, actions: agedActions(result.body, result.frontmatter), ...pointers, writes });
-    }
+    // The Footer and the pointers are the same at every depth: they read the
+    // whole file, not the body this depth shows.
+    const whole = depth === 'full' ? result : await os.read(slug, 'full');
+    const footer = footerFor(slug, whole);
+    const pointers = whole.kind === 'entity' ? await pointersFor(os, slug, whole.body) : null;
     const fm = result.frontmatter;
     const days = stalenessDaysOf(fm);
     const staleMark = (added) => ITEMS.staleMarker.render(actionAge(added, days));
     const text = result.kind === 'entity'
         ? formatEntityHeader(fm, ITEMS.handles.render(result.body, staleMark), await parentLine(os, fm.parent), [
+            ITEMS.childrenBlock.render({ slug, children: pointers.children }),
+            ...pointers.workstreams.map(w => ITEMS.workstreamLine.render(w)),
             ITEMS.sessionsLine.render({ slug, ...pointers.sessions }),
             ITEMS.archivePointer.render({ slug, entries: pointers.archive_entries }),
         ].filter(Boolean))
@@ -69,15 +60,15 @@ export async function cmdRead(os, args, opts = {}) {
     // Trailing newlines only: the Footer brings its own blank line.
     return `${text.replace(/\n+$/, '')}\n${ITEMS.writeLine.render(footer)}`;
 }
-/** What hangs off an entity elsewhere: the sessions that touched it (the
- * look back, #35) and its archived log entries (#34). Counted at read time,
- * nothing written. */
-async function pointersFor(os, slug) {
-    const sessions = (await os.related_to(slug)).items.filter((i) => i.kind === 'session');
-    const latest = sessions.reduce((max, s) => (max === null || s.session_date > max ? s.session_date : max), null);
-    const archive = await os.archive(slug);
-    const entries = archive ? archive.split('\n').filter(line => parseSessionLogHeading(line)).length : 0;
-    return { sessions: { count: sessions.length, latest }, archive_entries: entries };
+/** A `read` miss as the CLI renders it: the closest slugs on stderr (`--json`:
+ * `{slug, closest}` on stdout), exit 1. Any other error passes through. */
+function readMiss(err, slug, opts) {
+    if (!(err instanceof HafezError) || err.code !== 'NOT_FOUND')
+        return err;
+    const closest = err.details ?? [];
+    return opts.json
+        ? new RenderedError('NOT_FOUND', jsonOut({ slug, closest }), 'stdout')
+        : new RenderedError('NOT_FOUND', ITEMS.slugMissRecovery.render({ slug, closest }), 'stderr');
 }
 /** The `parent:` line's value: the slug with the parent's description. The
  * one thing `read` takes from another file; a parent that cannot be read
@@ -102,17 +93,6 @@ async function staleAfterWrite(os, slug) {
         return [];
     }
 }
-/** The Footer for a file `read` returned at `depth`. The Footer is the same
- * at every depth, so its Handle comes from the whole file, not from the body
- * this depth shows. A session note has none: it is never written to. */
-async function footerFor(os, slug, result, depth) {
-    return { slug, agent: detectAgent(), ...(result.kind === 'entity'
-            ? {
-                target: { kind: 'entity', type: result.frontmatter.type },
-                handle: getActionItems(depth === 'full' ? result.body : (await os.read(slug, 'full')).body).find(a => a.handle)?.handle,
-            }
-            : { target: { kind: 'knowledge', subtype: result.frontmatter.subtype } }) };
-}
 const QUERY_USAGE = `Usage: hafez query [--kind entity|knowledge|session|all] [--filter ...] [--type t] [--parent slug] [--related-to slug] [--domain d] [--confidence c] [--subtype s] [--tag t] [--since d] [--before d] [--created-since d] [--created-before d] [--sort-by f] [--sort-order asc|desc] [--limit n] [--offset n]
 
   --filter active|paused|done matches entity status; knowledge and session
@@ -520,7 +500,7 @@ async function updateFailure(os, slug, err, opts) {
         if (file.kind === 'session') {
             return new RenderedError('VALIDATION_FAILED', `'${slug}' is a session note: written once and read, never updated. What matters from it belongs on the entity it touched.`, 'stderr');
         }
-        retry = { footer: await footerFor(os, slug, file, 'full') };
+        retry = { footer: footerFor(slug, file) };
     }
     catch (readErr) {
         if (!(readErr instanceof HafezError) || readErr.code !== 'NOT_FOUND')
@@ -600,6 +580,78 @@ export async function cmdValidate(os, args, opts = {}) {
         return jsonOut(report);
     return formatValidation(report);
 }
+export async function cmdHealth(os, args, opts = {}) {
+    helpIfAsked(args, 'Usage: hafez health  (what placement would change; applies nothing)');
+    const report = await os.health();
+    if (opts.json)
+        return jsonOut(report);
+    return formatHealth(report);
+}
+const GRAPH_USAGE = "Usage: hafez graph [slug] [--port N] [--no-open]  (serve the vault's graph on 127.0.0.1 and open it in the browser; a slug opens it focused on that note)\n       hafez graph --json [--layers tag,domain,session]  (the vault's structure as {nodes, edges})";
+const GRAPH_FLAGS = { layers: 'string', port: 'string', 'no-open': 'boolean' };
+/** The local-graph depth `hafez graph <slug>` opens at (#256). */
+const GRAPH_FOCUS_DEPTH = 2;
+export async function cmdGraph(os, args, opts = {}) {
+    const { flags, positionals } = parseArgs(args, GRAPH_FLAGS, GRAPH_USAGE);
+    if (positionals.length > 1)
+        throw new UsageError(GRAPH_USAGE);
+    const slug = positionals[0];
+    if (!opts.json) {
+        if (flags.layers !== undefined)
+            throw new UsageError('--layers requires --json', GRAPH_USAGE);
+        // A miss fails as `read` does, before any server starts.
+        if (slug !== undefined)
+            await os.read(slug, 'frontmatter').catch(err => { throw readMiss(err, slug, opts); });
+        return serveGraph(opts.vaultPath, flags, slug);
+    }
+    if (slug !== undefined)
+        throw new UsageError('a slug opens the page focused on it; --json prints the whole Graph', GRAPH_USAGE);
+    if (flags.port !== undefined || flags['no-open'])
+        throw new UsageError('--port and --no-open serve the page; --json prints the Graph and exits', GRAPH_USAGE);
+    const layers = splitList(flags.layers);
+    const unknown = layers?.find(l => !GRAPH_LAYERS.includes(l));
+    if (unknown !== undefined)
+        throw new UsageError(`Unknown layer: ${unknown}. Valid layers: ${GRAPH_LAYERS.join(', ')}`, GRAPH_USAGE);
+    return jsonOut(await os.graph(layers ? { layers: layers } : undefined));
+}
+const STOP_SIGNALS = ['SIGINT', 'SIGTERM'];
+/** `hafez graph` without --json: serve the page until Ctrl-C or SIGTERM, then close the
+ * server and the index. The server gets its own instance whose reads trust the
+ * index: it syncs the index when its poll sees a commit (#271). */
+async function serveGraph(vaultPath, flags, focus) {
+    const portFlag = str(flags.port);
+    if (portFlag !== undefined && !(/^\d+$/.test(portFlag) && Number(portFlag) <= 65535)) {
+        throw new UsageError(`--port takes a port number (0-65535), got "${portFlag}"`, GRAPH_USAGE);
+    }
+    const port = portFlag === undefined ? undefined : Number(portFlag);
+    const { startGraphServer, DEFAULT_PORT } = await import('../graph/server.js');
+    const { createInternalHafez } = await import('../internal.js');
+    const os = createInternalHafez({ vaultPath, git: { push: false }, indexSync: 'manual' });
+    const server = await startGraphServer({ os, port }).catch(err => {
+        os.close();
+        if (err.code !== 'EADDRINUSE' || port === undefined)
+            throw err;
+        throw new UsageError(`port ${port} is in use: pick another with --port, or leave it off for the first free port from ${DEFAULT_PORT}`);
+    });
+    // The page reads its view from the URL: a focus opens local-graph mode around it.
+    const url = focus === undefined ? server.url : `${server.url}/?focus=${encodeURIComponent(focus)}&depth=${GRAPH_FOCUS_DEPTH}`;
+    process.stdout.write(`Serving the graph at ${url}  (Ctrl-C to stop)\n`);
+    if (!flags['no-open'])
+        (await import('../graph/open.js')).openBrowser(url);
+    // SIGTERM (a supervisor's kill) stops it as Ctrl-C does, so the index is
+    // closed either way (#280). A second signal during the close is not caught.
+    await new Promise(resolve => {
+        const stop = () => {
+            for (const signal of STOP_SIGNALS)
+                process.off(signal, stop);
+            resolve();
+        };
+        for (const signal of STOP_SIGNALS)
+            process.on(signal, stop);
+    });
+    await server.close();
+    return 'Graph server stopped.';
+}
 export async function cmdIndexRebuild(os) {
     await os.rebuildIndex();
     return 'Index rebuilt.';

package/dist/cli/format.d.ts

@@ -1,4 +1,4 @@
-import type { QueryResult, KnowledgeQueryResult, SessionQueryResult, ValidationReport, SearchResult, VaultStats, ChangelogEntry } from '../types.js';
+import type { QueryResult, KnowledgeQueryResult, SessionQueryResult, ValidationReport, HealthReport, SearchResult, VaultStats, ChangelogEntry } from '../types.js';
 /** `parent` is the rendered value of the `parent:` line (the slug with the
  * parent's description); absent, the slug alone. `pointers` are the lines
  * naming what hangs off the entity elsewhere (its sessions, its archive). */
@@ -15,4 +15,7 @@ export declare function formatSessionTable(results: SessionTableRow[], total?: n
 export declare function formatSearchResults(results: SearchResult[]): string;
 export declare function formatStats(stats: VaultStats): string;
 export declare function formatChangelog(entries: ChangelogEntry[]): string;
+/** The Health pass as markdown: one section per check, every section
+ * printed, so an empty report still shows what was checked. */
+export declare function formatHealth(report: HealthReport): string;
 export declare function formatValidation(report: ValidationReport): string;

package/dist/cli/format.js

@@ -1,3 +1,4 @@
+import { ITEMS } from '../surfaces/items.js';
 /** `parent` is the rendered value of the `parent:` line (the slug with the
  * parent's description); absent, the slug alone. `pointers` are the lines
  * naming what hangs off the entity elsewhere (its sessions, its archive). */
@@ -196,6 +197,24 @@ export function formatChangelog(entries) {
     const rows = entries.map(e => `| ${e.slug} | ${e.kind} | ${e.operation} | ${e.timestamp.slice(0, 10)} | ${e.commit_message} |`);
     return [header, sep, ...rows].join('\n');
 }
+/** The Health pass as markdown: one section per check, every section
+ * printed, so an empty report still shows what was checked. */
+export function formatHealth(report) {
+    const out = ['## Health'];
+    const section = (title, items) => {
+        out.push('', `### ${title} (${items.length})`);
+        for (const item of items)
+            out.push(`- ${item}`);
+    };
+    // The workstream Item's own text (ADR 0001), prefixed with the entity.
+    section('Workstreams', report.workstreams.map(w => `${w.entity} ${ITEMS.workstreamLine.render(w)}`));
+    section('Recurring names', report.recurring_names.map(r => `${r.entity}: \`${r.term}\` in ${r.units} units across ${r.days.length} days (${r.days[0]} .. ${r.days[r.days.length - 1]})`));
+    section('Leakage', report.leakage.map(l => `${l.parent} → ${l.child} (${l.relation}): ${l.hits} of ${l.entries} entries (${Math.round(100 * l.hits / l.entries)}%)`));
+    section('One-way edges', report.one_way_edges.map(e => `${e.from} → ${e.to}: \`hafez link ${e.to} ${e.from} --relation related\``));
+    section('Unlinked mentions', report.unlinked_mentions.map(e => `${e.from} mentions [[${e.to}]]: \`hafez link ${e.from} ${e.to} --relation related\``));
+    section('Restated decisions', report.restated_decisions.map(r => `${r.day} ${r.entity} → ${r.note} (${Math.round(100 * r.share)}%): ${r.summary}`));
+    return out.join('\n');
+}
 export function formatValidation(report) {
     const issues = report.broken_slugs.length + report.orphaned_knowledge.length +
         report.missing_fields.length;

package/dist/cli/index.js

@@ -41,6 +41,8 @@ export const COMMANDS = {
     delete: { phase: 'vault', mutating: true, run: lazy(m => m.cmdDelete) },
     batch: { phase: 'vault', mutating: true, run: lazy(m => m.cmdBatch) },
     validate: { phase: 'vault', run: lazy(m => m.cmdValidate) },
+    health: { phase: 'vault', run: lazy(m => m.cmdHealth) },
+    graph: { phase: 'vault', run: lazy(m => m.cmdGraph) },
     index: {
         phase: 'vault',
         run: async (os, args) => {
@@ -109,6 +111,12 @@ Commands:
   changelog --since <when>   Git-derived change history (e.g. --since 7.days.ago)
   schema [op] [--examples]   Machine-readable JSON schema for batch operations
   validate                   Check vault integrity
+  health                     The Health pass: what placement would change (applies nothing)
+  graph --json               The vault's structure: entities and knowledge, parent/related/wiki-link edges
+    --layers tag,domain,session  Add tag and domain nodes, and sessions
+  graph [slug] [--port N] [--no-open]
+                             Serve the graph on 127.0.0.1 (first free port from 4747) and open the browser;
+                             a slug opens it focused on that note, local graph at depth 2
   index rebuild              Rebuild the SQLite index
   init --register <path>     Register an existing vault
   init                       Show current vault resolution
@@ -285,8 +293,9 @@ export async function main(argv) {
         // First touch of the core — and so of the native SQLite binding. A
         // failure to load it lands in the catch below and is recognised by
         // isBindingsFailure, exactly as it was when this import was static.
-        const { createHafez } = await import('../index.js');
-        const os = createHafez({ vaultPath, git: { push: false } });
+        const { createInternalHafez } = await import('../internal.js');
+        // One index scan per process (#269): the first read syncs, later reads trust it.
+        const os = createInternalHafez({ vaultPath, git: { push: false }, indexSync: 'once' });
         try {
             const result = await spec.run(os, args, { json, vaultPath });
             // Auto-sync after mutating commands

package/dist/cli/upgrade.js

@@ -34,7 +34,7 @@ const PLAIN_SEMVER = /^\d+\.\d+\.\d+$/;
 const REGISTRY_TIMEOUT_MS = 3000;
 const NPM_PROBE_TIMEOUT_MS = 3000;
 const DEFAULT_REGISTRY_URL = 'https://registry.npmjs.org/hafez/latest';
-const DEV_CHECKOUT_WORK = 'git pull && npm run build && npm run install:local';
+const DEV_CHECKOUT_WORK = 'git pull && npm ci && npm run build && npm run install:local';
 const NPM_PROBE_NOTE = 'The local npm version could not be determined, so every install flag is included above. ' +
     'npm majors that predate a flag print `npm warn Unknown cli config` and proceed — that warning is harmless.';
 const ETARGET_NOTE = 'If the install fails with ETARGET, your configured registry (a mirror or proxy) does not have the pinned version — ' +

package/dist/contracts.d.ts

@@ -4,6 +4,15 @@ export declare const ENTITY_STATUSES: readonly ["active", "paused", "done"];
 export declare const SESSION_LOG_TYPES: readonly ["progress", "decision", "blocker", "research"];
 export declare const CONFIDENCE_LEVELS: readonly ["observation", "pattern", "principle"];
 export declare const VALID_SUBTYPES: readonly ["insight", "plan"];
+/** The Graph's layers whose nodes are synthetic, one per distinct value
+ * (`<layer>:<value>`); each adds the edge relation of the same name. */
+export declare const SYNTHETIC_LAYERS: readonly ["tag", "domain"];
+/** The Graph's optional layers (#253): tag and domain nodes, Session nodes. */
+export declare const GRAPH_LAYERS: readonly ["tag", "domain", "session"];
+/** The Graph's edges between notes; the synthetic layers add their own. */
+export declare const GRAPH_NOTE_RELATIONS: readonly ["parent", "related", "mention"];
+/** What a write did to a note, as history tells it (changesSince, #258). */
+export declare const CHANGE_OPS: readonly ["create", "update", "delete"];
 export interface TypeContract {
     type: string;
     description: string;

package/dist/contracts.js

@@ -10,6 +10,15 @@ export const CONFIDENCE_LEVELS = ['observation', 'pattern', 'principle'];
 // 'insight' is the subtype (frontmatter classification), 'Synthesis' is the section heading.
 // The rename was insight→synthesis for the section/field only; the subtype stays 'insight'.
 export const VALID_SUBTYPES = ['insight', 'plan'];
+/** The Graph's layers whose nodes are synthetic, one per distinct value
+ * (`<layer>:<value>`); each adds the edge relation of the same name. */
+export const SYNTHETIC_LAYERS = ['tag', 'domain'];
+/** The Graph's optional layers (#253): tag and domain nodes, Session nodes. */
+export const GRAPH_LAYERS = [...SYNTHETIC_LAYERS, 'session'];
+/** The Graph's edges between notes; the synthetic layers add their own. */
+export const GRAPH_NOTE_RELATIONS = ['parent', 'related', 'mention'];
+/** What a write did to a note, as history tells it (changesSince, #258). */
+export const CHANGE_OPS = ['create', 'update', 'delete'];
 /** The item frontmatter contract, shared by all three item types — they
  * differ in sections and lifecycle, never in which fields are mandatory.
  * schema.validateEntityFrontmatter enforces exactly this list (parity test in

package/dist/dates.d.ts

@@ -1,5 +1,8 @@
 /** The local calendar day as YYYY-MM-DD. The single source of "today". */
 export declare function localDay(d?: Date): string;
+/** Whole days from one YYYY-MM-DD day to another, as calendar days: a
+ * difference that ignores DST. */
+export declare function daysBetween(from: string, to: string): number;
 /**
  * Bare YYYY-MM-DD → local midnight, for git's approxidate. A date-only
  * `--since` is otherwise filled with the *current* time of day ("since right

package/dist/dates.js

@@ -15,6 +15,15 @@ function pad(n) {
 export function localDay(d = new Date()) {
     return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
 }
+/** Whole days from one YYYY-MM-DD day to another, as calendar days: a
+ * difference that ignores DST. */
+export function daysBetween(from, to) {
+    return dayNumber(to) - dayNumber(from);
+}
+function dayNumber(day) {
+    const [y, m, d] = day.split('-').map(Number);
+    return Date.UTC(y, m - 1, d) / 86_400_000;
+}
 /**
  * Bare YYYY-MM-DD → local midnight, for git's approxidate. A date-only
  * `--since` is otherwise filled with the *current* time of day ("since right

package/dist/db.d.ts

@@ -1,7 +1,7 @@
 import { type VaultKind } from './vault.js';
 import { type VaultIndexRow } from './knowledge-index.js';
-import type { SearchResult, SearchKind, VaultStats, QueryResult, KnowledgeQueryResult, SessionQueryResult, UnifiedResult, EntityQueryOpts, KnowledgeQueryOpts, SessionQueryOpts, UnifiedQueryOpts, SortField } from './types.js';
-export declare const SCHEMA_VERSION = "12";
+import type { SearchResult, SearchKind, VaultStats, QueryResult, KnowledgeQueryResult, SessionQueryResult, UnifiedResult, EntityQueryOpts, KnowledgeQueryOpts, SessionQueryOpts, UnifiedQueryOpts, SortField, Graph, GraphOpts } from './types.js';
+export declare const SCHEMA_VERSION = "13";
 interface IndexItem {
     slug: string;
     kind: VaultKind;
@@ -28,6 +28,8 @@ interface IndexItem {
     last_session_type: string | null;
     last_session_summary: string | null;
     session_date: string | null;
+    /** An entity's open actions' added days as a JSON array, null for an undated line. */
+    action_added: string | null;
 }
 export interface IndexQueryResult {
     items: IndexItem[];
@@ -35,7 +37,11 @@ export interface IndexQueryResult {
 }
 export interface HafezIndex {
     rebuild(): void;
+    /** Catch the index up with the files, whatever the mode: a stat per note
+     * (read-only: reopen a database another process rewrote). */
     syncIfStale(): void;
+    /** What a read runs first, by the index's `sync` mode (`IndexOpts`). */
+    syncForRead(): void;
     upsertFromFile(slug: string, kind: VaultKind): void;
     removeItem(slug: string): void;
     queryItems(opts: QueryOpts): IndexQueryResult;
@@ -43,6 +49,8 @@ export interface HafezIndex {
     getStats(): VaultStats;
     /** Every indexed document, in the shape index.md is rendered from. */
     indexEntries(): VaultIndexRow[];
+    /** The rows the Graph is shaped from: every item, every link. */
+    graphRows(): GraphRows;
     close(): void;
     queryEntities(opts?: EntityQueryOpts): {
         items: QueryResult[];
@@ -68,6 +76,18 @@ export interface HafezIndex {
         items: UnifiedResult[];
         total: number;
     };
+    queryGraph(opts?: GraphOpts): Graph;
+}
+export interface GraphRows {
+    items: Array<Pick<IndexItem, 'slug' | 'kind' | 'name' | 'type' | 'status' | 'subtype' | 'confidence' | 'last_touched' | 'description' | 'next_action_count' | 'staleness_days' | 'action_added'> & {
+        /** Entity-stale by the index's stale rule, 1 or 0; null for a note with no last-touched. */
+        stale: number | null;
+    }>;
+    links: Array<{
+        source: string;
+        target: string;
+        relation: string;
+    }>;
 }
 /** `kind` unset is the working set, entity + knowledge; `all` is literal. */
 export interface QueryOpts {
@@ -93,8 +113,18 @@ export interface QueryOpts {
 }
 /** @internal */
 export declare function __setAfterScanHook(fn: (() => void) | null): void;
-export declare function createIndex(vaultPath: string): HafezIndex;
-export declare function createIndex(vaultPath: string, opts: {
+/** `sync`: what `syncForRead`, run first by every read-surface query, does.
+ * 'read' (default): runs `syncIfStale`. 'once': runs it until a sync has
+ * caught the index up, then trusts the index (#269). 'manual': trusts the
+ * index, and the caller syncs it. */
+export type IndexSync = 'read' | 'once' | 'manual';
+export interface IndexOpts {
+    sync?: IndexSync;
+}
+export declare function createIndex(vaultPath: string, opts?: IndexOpts & {
+    readonly?: false;
+}): HafezIndex;
+export declare function createIndex(vaultPath: string, opts: IndexOpts & {
     readonly: true;
 }): HafezIndex | null;
 /** Opts a branch cannot map into SQL. Declared per branch and rejected on