hafez 2.1.0 → 2.3.0

package/dist/cli/install.js

@@ -14,6 +14,7 @@ import { dirname, join } from 'path';
 import { HafezError } from '../types.js';
 import { HARNESSES } from '../harness.js';
 import { contentHash, renderBlock, renderHafezSaveSkill, renderHafezSkill } from '../surfaces/surfaces.js';
+import { isVaultRepo } from '../surfaces/items.js';
 export const MODES = ['always-on', 'invoke-only'];
 export const isMode = (value) => MODES.includes(value);
 export const SKILL_DIRS = ['.claude/skills', '.agents/skills'];
@@ -36,7 +37,8 @@ function hashState(found, rendered) {
     return 'stale';
 }
 // --- The Block region ---
-const BEGIN = /^<!-- hafez:begin ([0-9a-f]{12}) -->$/;
+/** The hash, then a cloud Block's vault repo (#160). */
+const BEGIN = /^<!-- hafez:begin ([0-9a-f]{12})(?: vault-repo=(\S+))? -->$/;
 const END = '<!-- hafez:end -->';
 /** What broken markers are, for a refusal or a report about `path`. */
 const brokenMarkers = (path) => `The Hafez markers in ${path} are broken: expected one "<!-- hafez:begin <hash> -->" line followed by one "${END}" line.`;
@@ -62,8 +64,9 @@ function findRegion(file, displayPath) {
         return null;
     const [begin] = begins;
     const [end] = ends;
-    const hash = begin ? BEGIN.exec(begin.line)?.[1] : undefined;
-    if (begins.length !== 1 || ends.length !== 1 || end.start < begin.start || !hash || end.line !== END) {
+    const [, hash, vaultRepo] = (begin && BEGIN.exec(begin.line)) || [];
+    if (begins.length !== 1 || ends.length !== 1 || end.start < begin.start || !hash || end.line !== END
+        || (vaultRepo !== undefined && !isVaultRepo(vaultRepo))) {
         throw new HafezError('VALIDATION_FAILED', `${brokenMarkers(displayPath)} Fix or delete them by hand, then re-run.`);
     }
     return {
@@ -73,8 +76,11 @@ function findRegion(file, displayPath) {
         hash,
         body: file.slice(begin.next, end.start),
         text: file.slice(begin.start, end.start + END.length),
+        ...(vaultRepo !== undefined && { vaultRepo }),
     };
 }
+/** The flag that keeps an install a cloud one, for every printed install line. */
+export const vaultRepoFlag = (vaultRepo) => (vaultRepo === undefined ? '' : ` --vault-repo ${vaultRepo}`);
 // --- The 1.x section ---
 /** The heading 1.2–1.4 `onboard` had the agent paste, with no markers (#157). */
 const LEGACY_HEADING = '## Hafez — Session Memory';
@@ -169,14 +175,22 @@ function skillSteps(home, want) {
         return { line: `~/${rel}: ${state === 'absent' ? 'written' : `replaced (was ${state})`}`, write: () => write(path, rendered) };
     });
 }
-const RENDERED = findRegion(renderBlock(), 'the render');
-function blockStep({ home, rel, want, confirm, rerun, suffix = '' }) {
+const RENDERS = new Map();
+/** The Block Hafez writes, as a region; with `vaultRepo`, the cloud Block. A
+ * found Block is checked against the render for its own marker's repo. */
+function rendered(vaultRepo) {
+    if (!RENDERS.has(vaultRepo))
+        RENDERS.set(vaultRepo, findRegion(renderBlock(vaultRepo), 'the render'));
+    return RENDERS.get(vaultRepo);
+}
+function blockStep({ home, rel, want, confirm, rerun, suffix = '', vaultRepo }) {
     const path = join(home, rel);
     const label = `Block in ~/${rel}`;
     const file = readInstalled(path);
     const text = file ?? '';
     const region = findRegion(text, `~/${rel}`);
-    const state = hashState(region, RENDERED.text);
+    const target = rendered(want === 'write' ? vaultRepo : region?.vaultRepo);
+    const state = hashState(region, target.text);
     if (region && state === 'hand-edited' && !confirm) {
         return {
             line: `${label}: hand-edited, left alone`,
@@ -186,7 +200,7 @@ function blockStep({ home, rel, want, confirm, rerun, suffix = '' }) {
                 rerun,
                 '',
                 '````diff',
-                lineDiff(region.body, RENDERED.body),
+                lineDiff(region.body, target.body),
                 '````',
             ].join('\n'),
         };
@@ -200,11 +214,11 @@ function blockStep({ home, rel, want, confirm, rerun, suffix = '' }) {
         return { line: `${label}: current` };
     if (!region) {
         const before = text === '' || text.endsWith('\n') ? text : `${text}\n`;
-        return { line: `${label}: written`, write: () => write(path, before + renderBlock()) };
+        return { line: `${label}: written`, write: () => write(path, before + renderBlock(vaultRepo)) };
     }
     return {
         line: `${label}: replaced (was ${state})`,
-        write: () => write(path, text.slice(0, region.start) + RENDERED.text + text.slice(region.end)),
+        write: () => write(path, text.slice(0, region.start) + target.text + text.slice(region.end)),
     };
 }
 /** Codex reads an `AGENTS.override.md` in place of `AGENTS.md` when one
@@ -228,13 +242,15 @@ export function installState(home, harness) {
     const { instructions } = HARNESSES[harness];
     let block = null;
     let legacy = null;
+    let vaultRepo;
     if (instructions !== null) {
         const rel = instructionsFile(home, instructions);
         const text = readInstalled(join(home, rel)) ?? '';
         let region;
         try {
             region = findRegion(text, `~/${rel}`);
-            block = hashState(region, RENDERED.text);
+            vaultRepo = region?.vaultRepo;
+            block = hashState(region, rendered(vaultRepo).text);
         }
         catch {
             block = 'broken';
@@ -249,11 +265,13 @@ export function installState(home, harness) {
     const states = new Set(skills.map(s => s.state));
     const [only] = states;
     const merged = states.size === 1 ? only : states.has('hand-edited') ? 'hand-edited' : 'stale';
-    return { block, skills: merged, onboarded: skills.some(s => s.hashed), legacy };
+    return { block, skills: merged, onboarded: skills.some(s => s.hashed), legacy, ...(vaultRepo !== undefined && { vaultRepo }) };
 }
 // --- The two commands ---
+/** `vaultRepo`: the install is for a cloud container, whose Block carries
+ * the rule that attaches that repo as the vault (#160). */
 export function install(opts) {
-    const { home, harness, mode, confirm } = opts;
+    const { home, harness, mode, confirm, vaultRepo } = opts;
     const { label, instructions } = HARNESSES[harness];
     const steps = skillSteps(home, 'write');
     const tail = [];
@@ -273,8 +291,9 @@ export function install(opts) {
             rel,
             want: mode === 'always-on' ? 'write' : 'remove',
             confirm,
-            rerun: `hafez onboard --install --harness ${harness} --mode ${mode} --confirm`,
+            rerun: `hafez onboard --install --harness ${harness} --mode ${mode}${vaultRepoFlag(vaultRepo)} --confirm`,
             suffix: mode === 'invoke-only' ? ' (invoke-only)' : '',
+            vaultRepo,
         }));
     }
     const out = run({ header: `${label}, ${mode}:`, steps, tail, unchanged: 'Nothing changed: the install is current.', listAll: true });
@@ -316,8 +335,10 @@ export function checkInstall(home) {
             legacy.push({ harness, path, line });
         if (!region)
             continue;
-        const state = hashState(region, RENDERED.text);
-        blocks.push({ harness, path, state, renderChanged: region.hash !== RENDERED.hash });
+        const { vaultRepo } = region;
+        const render = rendered(vaultRepo);
+        const state = hashState(region, render.text);
+        blocks.push({ harness, path, state, renderChanged: region.hash !== render.hash, ...(vaultRepo !== undefined && { vaultRepo }) });
     }
     return { skills, blocks, legacy };
 }

package/dist/cli/onboard.js

@@ -9,33 +9,36 @@
 // `--install` and `--remove` write the files Hafez owns outside the vault
 // (install.ts). The binary has no interactive prompts: the agent asks, then
 // passes the answer as a flag. `--block` is the SessionStart hook's render
-// (block-hook.ts) and writes nothing.
+// (block-hook.ts) and writes nothing. `--cloud` prints the setup script for a
+// Claude Code cloud environment, whose `--install --vault-repo` writes the
+// Block with the rule that attaches the vault repo (#160).
 import { existsSync, readFileSync } from 'fs';
 import { homedir } from 'os';
 import { join } from 'path';
 import { UsageError, parseArgs, str } from './args.js';
 import { HARNESSES, ONBOARD_HARNESSES, detectAgent, isHarness, isOnboardHarness } from '../harness.js';
-import { MODES, SKILL_DIRS, fixBrokenMarkers, install, installState, instructionsFile, isMode, legacyLine, remove, removeLegacy } from './install.js';
+import { MODES, SKILL_DIRS, fixBrokenMarkers, install, installState, instructionsFile, isMode, legacyLine, remove, removeLegacy, vaultRepoFlag } from './install.js';
 import { noVaultMessage, resolveVaultPath } from './resolve-vault.js';
 import { HafezError } from '../types.js';
 import { kindDir, scanVaultDir } from '../vault.js';
-import { ITEMS } from '../surfaces/items.js';
+import { ITEMS, isVaultRepo } from '../surfaces/items.js';
 import { renderBlock } from '../surfaces/surfaces.js';
 import { blockHook } from './block-hook.js';
 const HARNESS_IDS = Object.keys(HARNESSES).join('|');
 const MODE_IDS = MODES.join('|');
 const ONBOARD_USAGE = `Usage:
   hafez onboard
-  hafez onboard --install --mode <${MODE_IDS}> [--harness <${HARNESS_IDS}>] [--confirm]
+  hafez onboard --install --mode <${MODE_IDS}> [--harness <${HARNESS_IDS}>] [--vault-repo <owner>/<repo>] [--confirm]
   hafez onboard --remove [--confirm]
-  hafez onboard --block [--harness <${HARNESS_IDS}>]`;
+  hafez onboard --block [--harness <${HARNESS_IDS}>]
+  hafez onboard --cloud --vault-repo <owner>/<repo>`;
 /** `ctx` is the temp-home seam: tests pass a temporary home and environment;
  * the install functions are given the home, never read it. `vaultFlag` is the
  * global `--vault`; without it the bare form reports on the registered vault.
  * `--block` returns a promise of its render, or of null when it must print nothing. */
 export function cmdOnboard(args, ctx = {}) {
     const { home = homedir(), env = process.env, cwd, vaultFlag } = ctx;
-    const { flags, positionals } = parseArgs(args, { install: 'boolean', remove: 'boolean', block: 'boolean', mode: 'string', harness: 'string', confirm: 'boolean' }, ONBOARD_USAGE);
+    const { flags, positionals } = parseArgs(args, { install: 'boolean', remove: 'boolean', block: 'boolean', cloud: 'boolean', mode: 'string', harness: 'string', 'vault-repo': 'string', confirm: 'boolean' }, ONBOARD_USAGE);
     const fail = (why) => {
         throw new UsageError(`${why}\n${ONBOARD_USAGE}`);
     };
@@ -43,9 +46,22 @@ export function cmdOnboard(args, ctx = {}) {
         fail(`Unexpected argument: ${positionals[0]}`);
     const mode = str(flags.mode);
     const harnessFlag = str(flags.harness);
+    const vaultRepo = str(flags['vault-repo']);
     const confirm = flags.confirm === true;
     if (flags.install && flags.remove)
         fail('--install and --remove are separate commands');
+    if (vaultRepo !== undefined && !isVaultRepo(vaultRepo))
+        fail(`--vault-repo takes the vault's GitHub repo as <owner>/<repo>, got: ${vaultRepo}`);
+    if (vaultRepo !== undefined && !flags.cloud && !flags.install)
+        fail('--vault-repo goes with --cloud or --install');
+    if (flags.cloud) {
+        if (flags.install || flags.remove || flags.block || mode !== undefined || harnessFlag !== undefined || confirm) {
+            fail('--cloud takes only --vault-repo: it prints the setup script and writes nothing');
+        }
+        if (vaultRepo === undefined)
+            return fail('--cloud needs --vault-repo <owner>/<repo>, the vault\'s GitHub repo');
+        return ITEMS.cloudSetup.render({ vaultRepo });
+    }
     if (flags.block) {
         if (flags.install || flags.remove || mode !== undefined || confirm)
             fail('--block takes only --harness: it prints the Block and writes nothing');
@@ -67,7 +83,11 @@ export function cmdOnboard(args, ctx = {}) {
         if (!isHarness(harness)) {
             return fail(harnessFlag === undefined ? `No harness detected: pass --harness <${HARNESS_IDS}>` : `Unknown harness: ${harnessFlag}`);
         }
-        return install({ home, harness, mode, confirm });
+        // The cloud Block's rule is Claude Code's: cloud sessions attach repos there.
+        if (vaultRepo !== undefined && (mode !== 'always-on' || harness !== 'claude-code')) {
+            fail('--vault-repo is for a Claude Code cloud container: --mode always-on --harness claude-code');
+        }
+        return install({ home, harness, mode, confirm, vaultRepo });
     }
     if (mode !== undefined || harnessFlag !== undefined || confirm)
         fail('--mode, --harness and --confirm go with --install, --remove or --block');
@@ -149,7 +169,8 @@ export function renderOnboard({ home, harness, vault }) {
     const teaching = (m) => ITEMS.teachingLines.render({ harness, mode: m });
     const line2 = (m) => ITEMS.teachingLines.render({ harness, mode: m, line2Only: true });
     const instructionsRel = `~/${instructionsFile(home, instructions)}`;
-    const block = `\`\`\`\`\n${renderBlock()}\`\`\`\``;
+    // A cloud Block stays one: its install line and Block keep the vault repo.
+    const block = `\`\`\`\`\n${renderBlock(state.vaultRepo)}\`\`\`\``;
     const showBlock = `show the user the Block below word for word, not a summary, say it goes into ${instructionsRel} between two marker lines and nothing else in that file changes, and get a yes. Then run:`;
     const status = [
         `Vault: ${vault} (${plural(entities, 'entity', 'entities')}, ${plural(knowledge, 'knowledge note', 'knowledge notes')})`,
@@ -194,7 +215,7 @@ export function renderOnboard({ home, harness, vault }) {
                 ...(state.legacy === null ? [] : [`${removeLegacy(instructionsRel, state.legacy)} Do this before either install below.`, '']),
                 `Always-on: ${showBlock}`,
                 '',
-                'hafez onboard --install --mode always-on',
+                `hafez onboard --install --mode always-on${vaultRepoFlag(state.vaultRepo)}`,
                 '',
                 'Invoke-only: no file of theirs is edited. Run:',
                 '',

package/dist/cli/upgrade.js

@@ -29,12 +29,12 @@ import { dirname, join } from 'path';
 import { fileURLToPath } from 'url';
 import { UsageError, helpIfAsked } from './args.js';
 import { HARNESSES, detectAgent, isHarness } from '../harness.js';
-import { checkInstall, fixBrokenMarkers, legacyLine, removeLegacy } from './install.js';
+import { checkInstall, fixBrokenMarkers, legacyLine, removeLegacy, vaultRepoFlag } from './install.js';
 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 — ' +
@@ -179,7 +179,7 @@ function blockSteps({ blocks, skills }, upgrading, env) {
         const targets = upgrading ? blocks : blocks.filter(blockDrift);
         return (targets.length > 0 ? targets : skillsOnly).map(b => ({
             kind: 'command',
-            text: `hafez onboard --install --mode always-on --harness ${b.harness}`,
+            text: `hafez onboard --install --mode always-on --harness ${b.harness}${vaultRepoFlag(b.vaultRepo)}`,
         }));
     }
     const harness = detectAgent(env);
@@ -192,7 +192,8 @@ function blockSteps({ blocks, skills }, upgrading, env) {
 }
 /** The action list, in execution order. Every command is built from static
  * constants; the only interpolated values are the regex-validated version,
- * the quoted package root, and harness ids from the HARNESSES table. */
+ * the quoted package root, harness ids from the HARNESSES table, and a cloud
+ * Block's vault repo, which `findRegion` reads only when it passes `isVaultRepo`. */
 function deriveSteps(state, ctx) {
     const steps = [];
     let alternativeInstall = null;

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,10 +1,17 @@
 /** 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
  * now"), and any explicit instant must anchor to the same local day boundary
  * the stamps and query comparisons use. Relative forms (`7.days.ago`) are
  * already local and pass through untouched.
+ *
+ * The offset is spelled out: without one git applies its own idea of the
+ * local zone, and Git for Windows ignores an IANA `TZ` that Node honours,
+ * so the two disagreed about where the day starts.
  */
 export declare function normalizeSinceDate(since: string): string;

package/dist/dates.js

@@ -15,13 +15,33 @@ 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
  * now"), and any explicit instant must anchor to the same local day boundary
  * the stamps and query comparisons use. Relative forms (`7.days.ago`) are
  * already local and pass through untouched.
+ *
+ * The offset is spelled out: without one git applies its own idea of the
+ * local zone, and Git for Windows ignores an IANA `TZ` that Node honours,
+ * so the two disagreed about where the day starts.
  */
 export function normalizeSinceDate(since) {
-    return /^\d{4}-\d{2}-\d{2}$/.test(since) ? `${since}T00:00:00` : since;
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(since);
+    if (!m)
+        return since;
+    // The day's first instant: 01:00 where a DST jump skips midnight.
+    const start = new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3]));
+    const offset = -start.getTimezoneOffset();
+    const zone = `${offset < 0 ? '-' : '+'}${pad(Math.floor(Math.abs(offset) / 60))}${pad(Math.abs(offset) % 60)}`;
+    return `${localDay(start)}T${pad(start.getHours())}:${pad(start.getMinutes())}:00${zone}`;
 }

package/dist/db.d.ts

@@ -1,9 +1,10 @@
+import { type VaultKind } from './vault.js';
 import { type VaultIndexRow } from './knowledge-index.js';
-import type { SearchResult, VaultStats, QueryResult, KnowledgeQueryResult, UnifiedResult, EntityQueryOpts, KnowledgeQueryOpts, UnifiedQueryOpts, SortField } from './types.js';
-export declare const SCHEMA_VERSION = "11";
+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: 'entity' | 'knowledge';
+    kind: VaultKind;
     name: string;
     type: string | null;
     status: string | null;
@@ -26,6 +27,9 @@ interface IndexItem {
     last_session_date: string | null;
     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[];
@@ -33,14 +37,20 @@ 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;
-    upsertFromFile(slug: string, kind: 'entity' | 'knowledge'): 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;
-    search(query: string, kind?: 'entity' | 'knowledge' | 'all'): SearchResult[];
+    search(query: string, kind?: SearchKind): SearchResult[];
     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[];
@@ -58,13 +68,30 @@ export interface HafezIndex {
         items: KnowledgeQueryResult[];
         total: number;
     };
+    querySessions(opts?: SessionQueryOpts): {
+        items: SessionQueryResult[];
+        total: number;
+    };
     queryUnified(opts?: UnifiedQueryOpts): {
         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 {
-    kind?: 'entity' | 'knowledge' | 'all';
+    kind?: VaultKind | 'all';
     status?: string;
     type?: string;
     subtype?: string;
@@ -79,15 +106,25 @@ export interface QueryOpts {
     createdSince?: string;
     createdBefore?: string;
     tags?: string[];
-    sort_by?: 'last_touched' | 'created' | 'name' | 'staleness' | 'last_reinforced' | 'reinforcement_count';
+    sort_by?: SortField;
     sort_order?: 'asc' | 'desc';
     limit?: number;
     offset?: number;
 }
 /** @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
@@ -96,11 +133,14 @@ export declare function createIndex(vaultPath: string, opts: {
  * Asserted against the CLI's flag matrix in query-surface.test.ts. */
 export declare const ENTITY_ONLY_OPTS: readonly ["filter", "type", "parent"];
 export declare const KNOWLEDGE_ONLY_OPTS: readonly ["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 declare const SESSION_REJECTED_OPTS: readonly ["filter", "type", "parent", "confidence", "subtype", "domain", "tags"];
 /** Every opt any branch might carry, flattened. Only the unified read uses it,
  * and only to check: the checks must see an opt the caller's own type forbids,
  * because an untyped caller can still send it. */
 export type UnmappableCheckOpts = Omit<EntityQueryOpts, 'sort_by'> & Omit<KnowledgeQueryOpts, 'sort_by'> & {
-    kind?: 'entity' | 'knowledge' | 'all';
+    kind?: VaultKind | 'all';
     sort_by?: SortField;
 };
 export {};