hafez 2.1.0 → 2.3.0

package/dist/types.d.ts

@@ -1,4 +1,4 @@
-import type { ENTITY_TYPES, ENTITY_STATUSES, CONFIDENCE_LEVELS, SESSION_LOG_TYPES, VALID_SUBTYPES, PLAN_STATUSES } from './contracts.js';
+import type { ENTITY_TYPES, ENTITY_STATUSES, CONFIDENCE_LEVELS, SESSION_LOG_TYPES, VALID_SUBTYPES, PLAN_STATUSES, GRAPH_LAYERS, SYNTHETIC_LAYERS, GRAPH_NOTE_RELATIONS, CHANGE_OPS } from './contracts.js';
 export type EntityType = typeof ENTITY_TYPES[number];
 export type EntityStatus = typeof ENTITY_STATUSES[number];
 export type ConfidenceLevel = typeof CONFIDENCE_LEVELS[number];
@@ -9,12 +9,22 @@ export type LinkRelation = 'parent' | 'related';
 export type KnowledgeSubtype = typeof VALID_SUBTYPES[number];
 /** Plans are the one knowledge subtype with a lifecycle (see PLAN_STATUSES). */
 export type PlanStatus = typeof PLAN_STATUSES[number];
+/** The kinds of note the Vault holds, one directory each (the Layout,
+ * vault.ts, re-exports it). Declared here so this file imports no module
+ * with runtime dependencies: the graph page's bundle reads its types. */
+export type VaultKind = 'entity' | 'knowledge' | 'session';
 /** Sort fields, and the two an entity query cannot honour — reinforcement
  * lives on knowledge notes only. Asking for one on the entity branch is a
  * validation error, not a silent fall back to recency, so the entity opts
  * type declares only what that branch can actually sort by. */
-export type SortField = 'last_touched' | 'created' | 'name' | 'staleness' | 'last_reinforced' | 'reinforcement_count';
-export type EntitySortField = Exclude<SortField, 'last_reinforced' | 'reinforcement_count'>;
+export type SortField = 'last_touched' | 'created' | 'name' | 'staleness' | 'last_reinforced' | 'reinforcement_count' | 'session_date';
+export type EntitySortField = Exclude<SortField, 'last_reinforced' | 'reinforcement_count' | 'session_date'>;
+export type KnowledgeSortField = Exclude<SortField, 'session_date'>;
+/** A session note carries only its dates and its name. */
+export type SessionSortField = 'session_date' | 'created' | 'name';
+/** What `search` reaches. Unset is the working set, entity + knowledge;
+ * `all` is literal, sessions included. */
+export type SearchKind = 'entity' | 'knowledge' | 'session' | 'all';
 export interface EntityQueryOpts {
     filter?: QueryFilter;
     type?: EntityType;
@@ -39,14 +49,28 @@ export interface KnowledgeQueryOpts {
     createdSince?: string;
     createdBefore?: string;
     tags?: string[];
-    sort_by?: SortField;
+    sort_by?: KnowledgeSortField;
+    sort_order?: 'asc' | 'desc';
+    limit?: number;
+    offset?: number;
+}
+/** Sessions carry no status, domain or tags: the time window (`since`/`before`
+ * against `session-date`), sort and paging are all a session query takes. */
+export interface SessionQueryOpts {
+    since?: string;
+    before?: string;
+    createdSince?: string;
+    createdBefore?: string;
+    sort_by?: SessionSortField;
     sort_order?: 'asc' | 'desc';
     limit?: number;
     offset?: number;
 }
 /** `kind: 'all'` (or unset): reaches both sides, so it takes opts from both
  * and can honour every sort field. Status filters narrow the entity side only
- * — knowledge notes carry no status and are never excluded by one. */
+ * — knowledge notes carry no status and are never excluded by one. Unset
+ * is the working set, entity + knowledge; `all` is literal and reaches the
+ * sessions too. */
 export interface AllQueryOpts extends Omit<EntityQueryOpts, 'sort_by'> {
     kind?: 'all';
     confidence?: ConfidenceLevel;
@@ -63,6 +87,8 @@ export type UnifiedQueryOpts = AllQueryOpts | (EntityQueryOpts & {
     kind: 'entity';
 }) | (KnowledgeQueryOpts & {
     kind: 'knowledge';
+}) | (SessionQueryOpts & {
+    kind: 'session';
 });
 export interface EntityFrontmatter {
     name: string;
@@ -114,11 +140,8 @@ export type ParsedVaultFile = {
     frontmatter: SessionFrontmatter;
     body: string;
 };
-/** What read() returns: the indexed arms of ParsedVaultFile (a session slug is
- * never resolvable through read()), so consumers narrow on `kind`. */
-export type ParsedFile = Extract<ParsedVaultFile, {
-    kind: 'entity' | 'knowledge';
-}>;
+/** What read() returns: any vault file, so consumers narrow on `kind`. */
+export type ParsedFile = ParsedVaultFile;
 export interface SessionLogEntry {
     type: SessionLogType;
     summary: string;
@@ -189,6 +212,14 @@ export interface CreateKnowledgeFields {
     tags?: string[];
     'session-date'?: string;
 }
+export interface CreateSessionFields {
+    synthesis?: string;
+    insight?: string;
+    related?: string[];
+    'session-date'?: string;
+    decisions?: string[];
+    entities_touched?: string[];
+}
 export interface QueryResult {
     slug: string;
     name: string;
@@ -221,10 +252,19 @@ export interface KnowledgeQueryResult {
     last_reinforced: string | null;
     last_touched: string | null;
 }
+export interface SessionQueryResult {
+    slug: string;
+    name: string;
+    session_date: string;
+    created: string;
+    related: string[];
+}
 export type UnifiedResult = (QueryResult & {
     kind: 'entity';
 }) | (KnowledgeQueryResult & {
     kind: 'knowledge';
+}) | (SessionQueryResult & {
+    kind: 'session';
 });
 export interface ValidationIssue {
     slug: string;
@@ -237,10 +277,100 @@ export interface ValidationReport {
     missing_fields: ValidationIssue[];
     total_entities: number;
     total_knowledge: number;
+    total_sessions: number;
+}
+/** Check (i): an unsplit prefix family on an entity, from the family module. */
+export interface HealthWorkstream {
+    entity: string;
+    prefix: string;
+    open_actions: number;
+}
+/** Check (ii): a name recurring in `units` units of one entity across `days`. */
+export interface HealthRecurringName {
+    entity: string;
+    term: string;
+    units: number;
+    days: string[];
+}
+/** Check (iv): `hits` of the parent's log entries dated on or after the
+ * child's `created` (`entries` of them) name the child. */
+export interface HealthLeak {
+    parent: string;
+    child: string;
+    relation: 'parent' | 'related';
+    hits: number;
+    entries: number;
+}
+/** Check (iii): `from`'s `related` names `to`, a note of the same kind,
+ * whose `related` does not name `from`. Check (v): `from`'s body mentions
+ * `[[to]]`, a note of the same kind, with no `related` edge either way.
+ * Neither lists a parent and its child: parent subsumes related. */
+export interface HealthEdge {
+    from: string;
+    to: string;
+}
+/** Check (vi): the knowledge note `note`, created on `day` and related to
+ * `entity`, shares `share` (0..1) of the summary tokens of a `decision`
+ * entry of that day on the entity. */
+export interface HealthRestatedDecision {
+    day: string;
+    entity: string;
+    note: string;
+    share: number;
+    summary: string;
+}
+export interface HealthReport {
+    workstreams: HealthWorkstream[];
+    recurring_names: HealthRecurringName[];
+    leakage: HealthLeak[];
+    one_way_edges: HealthEdge[];
+    unlinked_mentions: HealthEdge[];
+    restated_decisions: HealthRestatedDecision[];
+}
+export type GraphLayer = typeof GRAPH_LAYERS[number];
+export type SyntheticLayer = typeof SYNTHETIC_LAYERS[number];
+export interface GraphNode {
+    /** The slug; `tag:<t>` / `domain:<d>` for a layer node (a slug never holds `:`). */
+    id: string;
+    kind: VaultKind | SyntheticLayer;
+    name: string;
+    type?: EntityType;
+    status?: EntityStatus;
+    subtype?: KnowledgeSubtype;
+    confidence?: ConfidenceLevel;
+    last_touched?: string;
+    description?: string;
+    /** An active or paused Entity's open Next Actions. */
+    open_actions?: number;
+    /** An active Entity untouched past its staleness-days: the index's stale rule. */
+    stale?: boolean;
+    /** An active or paused Entity's open actions the Stale rule marks, undated ones included. */
+    stale_actions?: number;
+    /** Every Entity's effective staleness-days: its own, else 14. */
+    staleness_days?: number;
+    /** An Entity or Knowledge note with no Parent, Related or Wiki-link edge either way. */
+    unlinked?: true;
+    /** On an Unlinked note: the closest other linked note by name and description,
+     * the same kind when one matches; absent when none does. */
+    best?: string;
+}
+export interface GraphEdge {
+    source: string;
+    target: string;
+    relation: typeof GRAPH_NOTE_RELATIONS[number] | SyntheticLayer;
+}
+export interface Graph {
+    nodes: GraphNode[];
+    edges: GraphEdge[];
+}
+/** Any other opt is rejected, never dropped. */
+export interface GraphOpts {
+    /** Optional layers added to the default graph; they combine. */
+    layers?: GraphLayer[];
 }
 export interface SearchResult {
     slug: string;
-    kind: 'entity' | 'knowledge';
+    kind: 'entity' | 'knowledge' | 'session';
     name: string;
     snippet: string;
     type?: EntityType;
@@ -275,10 +405,52 @@ export interface VaultStats {
 }
 export interface ChangelogEntry {
     slug: string;
-    kind: 'entity' | 'knowledge';
+    kind: 'entity' | 'knowledge' | 'session';
     operation: 'created' | 'updated' | 'deleted';
     timestamp: string;
     commit_message: string;
+    /** The commit's hash: what tells the entries of one commit from another's. */
+    commit: string;
+}
+/** What a write did to a note, as history tells it. */
+export type ChangeOp = typeof CHANGE_OPS[number];
+/** A file history changed between two points, as the Journal names it:
+ * vault-relative and '/'-separated, any file (Layout decides which are notes). */
+export interface FileChange {
+    path: string;
+    op: ChangeOp;
+}
+/** A note created, updated or deleted since a cursor (`changesSince`). */
+export interface NoteChange {
+    slug: string;
+    kind: VaultKind;
+    op: ChangeOp;
+}
+/** What the graph server's `/events` pushes, one per poll that found
+ * changes (src/graph/live.ts); the page reads it too. */
+export interface CommitEvent {
+    type: 'commit';
+    changes: NoteChange[];
+}
+/** One row of the graph server's `/activity` (#278): a note's run of
+ * consecutive writes, newest first. `op`, `kind` and `timestamp` are the
+ * newest write's; `name` is the slug once the note is gone; `agent` is the
+ * agent of the Entity's newest Session Log entry dated the write's local day,
+ * absent where the Vault records none. */
+export interface ActivityRow {
+    slug: string;
+    kind: VaultKind;
+    op: ChangeOp;
+    timestamp: string;
+    name: string;
+    count: number;
+    agent?: string;
+}
+export interface ChangesSince {
+    /** The history point now: pass it back to get what changed after it.
+     * Empty when the Vault has no history yet. */
+    cursor: string;
+    changes: NoteChange[];
 }
 export interface BatchResult {
     op: string;
@@ -313,7 +485,7 @@ export type BatchOperation = {
     op: 'create';
     kind: 'session';
     name: string;
-    fields?: CreateKnowledgeFields;
+    fields?: CreateSessionFields;
 } | {
     op: 'capture';
     name: string;
@@ -355,7 +527,7 @@ export interface BatchValidationReport {
     valid: boolean;
     operations: BatchOpValidation[];
 }
-export type HafezErrorCode = 'NOT_FOUND' | 'SLUG_EXISTS' | 'VALIDATION_FAILED' | 'GIT_PUSH_FAILED' | 'GIT_COMMIT_FAILED' | 'VAULT_LOCKED';
+export type HafezErrorCode = 'NOT_FOUND' | 'SLUG_EXISTS' | 'VALIDATION_FAILED' | 'GIT_PUSH_FAILED' | 'GIT_COMMIT_FAILED' | 'GIT_READ_FAILED' | 'VAULT_LOCKED';
 export declare class HafezError extends Error {
     code: HafezErrorCode;
     details?: string[] | undefined;
@@ -366,14 +538,17 @@ export interface GitConfig {
 }
 /**
  * The persistence seam (see CONTEXT.md: Journal) — everything core needs
- * from the history layer behind vault mutations. Git satisfies it in
- * production (src/git.ts); tests may inject an in-memory adapter.
+ * from the history layer: the commit behind every vault mutation, sync, and
+ * the history reads (changelog, file times, the changes since a cursor). Git
+ * satisfies it in production (src/git.ts); tests may inject an in-memory
+ * adapter.
  */
 export interface Journal {
-    /** Persist one logical change: stage written+deleted paths (vault-relative)
-     * and commit under message. Must clean up its own partial state (e.g.
-     * staged files) before rethrowing on a commit-stage failure; a push-stage
-     * failure surfaces as GIT_PUSH_FAILED with the commit kept. */
+    /** Persist one logical change: stage written+deleted paths (vault-relative,
+     * '/'-separated on every platform) and commit under message. Must clean up
+     * its own partial state (e.g. staged files) before rethrowing on a
+     * commit-stage failure; a push-stage failure surfaces as GIT_PUSH_FAILED
+     * with the commit kept. */
     commit(written: string[], deleted: string[], message: string): Promise<void>;
     /** Bidirectional sync with the remote, if any. */
     sync(): Promise<{
@@ -381,10 +556,23 @@ export interface Journal {
         pushed: boolean;
         remote: boolean;
     }>;
-    /** History-derived changelog for entities/ and knowledge/ since a date. */
-    changelog(since: string): Promise<ChangelogEntry[]>;
-    /** Newest history timestamp per vault file (modified = any change, added = creation). */
+    /** History-derived changelog for the indexed dirs since a date ('' = all
+     * history), newest first; `limit` reads only the newest that many commits.
+     * Empty when the repo has no commits; any other git failure throws `GIT_READ_FAILED`. */
+    changelog(since: string, limit?: number): Promise<ChangelogEntry[]>;
+    /** Newest history timestamp per vault file (modified = any change, added = creation).
+     * Empty when the repo has no commits; any other git failure throws `GIT_READ_FAILED`. */
     fileTimes(mode: 'modified' | 'added'): Promise<Map<string, string>>;
+    /** The history point now (`cursor`, '' before the first commit) and the
+     * indexed-dir files whose content differs between `from` and it, each with
+     * its net status across the whole span (a rename is a delete and a
+     * create). `from` unset: the cursor only, no files; `from` '': every file
+     * in history now is a create. An unknown `from` or any other git failure
+     * throws `GIT_READ_FAILED`. */
+    changesSince(from?: string): Promise<{
+        cursor: string;
+        files: FileChange[];
+    }>;
 }
 export interface HafezConfig {
     vaultPath: string;
@@ -432,9 +620,35 @@ export interface Hafez {
         items: KnowledgeQueryResult[];
         total: number;
     }>;
+    query_sessions(opts?: SessionQueryOpts): Promise<{
+        items: SessionQueryResult[];
+        total: number;
+    }>;
+    /** An entity's archived log entries (`entities/archive/<slug>-log.md`), as
+     * written; null when it has none. Read from disk, never indexed: the
+     * archive is reached from its entity on purpose, never found by search. */
+    archive(slug: string): Promise<string | null>;
     validate(): Promise<ValidationReport>;
-    search(query: string, kind?: 'entity' | 'knowledge' | 'all'): Promise<SearchResult[]>;
+    /** The Health pass: what placement would change, from the files on disk
+     * (never the index); applies nothing. */
+    health(): Promise<HealthReport>;
+    search(query: string, kind?: SearchKind): Promise<SearchResult[]>;
+    /** The Vault's structure: Entity and Knowledge nodes, Parent, Related (one
+     * per unordered pair) and Wiki-link edges among them; `layers` adds tag,
+     * domain and Session nodes with their edges. */
+    graph(opts?: GraphOpts): Promise<Graph>;
     rebuildIndex(): Promise<void>;
     stats(): Promise<VaultStats>;
-    changelog(since: string): Promise<ChangelogEntry[]>;
+    /** The changes since a date ('' = all history), newest first; `limit`
+     * reads only the newest that many commits, a positive whole number
+     * (anything else is VALIDATION_FAILED). */
+    changelog(since: string, limit?: number): Promise<ChangelogEntry[]>;
+    /** The notes created, updated or deleted since `cursor`, from history, and
+     * the cursor to pass next time. No cursor: the current cursor and no
+     * changes, so a follower starts from now. */
+    changesSince(cursor?: string): Promise<ChangesSince>;
+    /** Release the SQLite index handle. Idempotent; the next call that needs
+     * the index reopens it. Call before deleting the vault: Windows cannot
+     * remove a directory holding an open file. */
+    close(): void;
 }

package/dist/validate.js

@@ -1,29 +1,42 @@
 import { join, basename } from 'path';
-import { parseFilePath, scanVaultDir, kindDir, vaultFileExists } from './vault.js';
-import { validateEntityFrontmatter, validateKnowledgeFrontmatter } from './schema.js';
+import { parseFilePath, scanVaultDir, kindDir, findReadableFile } from './vault.js';
+import { validateEntityFrontmatter, validateKnowledgeFrontmatter, validateSessionFrontmatter } from './schema.js';
 import { parentCycle } from './batch-ops.js';
+const FRONTMATTER_CHECKS = {
+    entity: validateEntityFrontmatter,
+    knowledge: validateKnowledgeFrontmatter,
+    session: validateSessionFrontmatter,
+};
 /** The vault integrity scan. Deliberately independent of the SQLite index:
  * this is the one operation that does not trust the index, so it reads the
  * files directly. Re-implementing it as an index query was considered and
  * rejected — an integrity checker that reads the index is checking the
  * index's model of the vault, not the vault. */
 export function validateVault(vaultPath) {
-    const exists = (slug) => vaultFileExists(vaultPath, slug);
+    // Any readable file satisfies a link: an invalid slug definitionally does
+    // not exist, and must report as missing rather than crash.
+    const exists = (slug) => { try {
+        return findReadableFile(vaultPath, slug) !== null;
+    }
+    catch {
+        return false;
+    } };
     const report = {
         broken_slugs: [],
         orphaned_knowledge: [],
         missing_fields: [],
         total_entities: 0,
         total_knowledge: 0,
+        total_sessions: 0,
     };
-    const knowledgeSlugs = new Set();
+    const knowledgeRelated = new Map();
     const referencedKnowledge = new Set();
     const parents = new Map();
-    // Scan entities
-    const entDir = join(vaultPath, kindDir('entity'));
-    {
-        const files = scanVaultDir(entDir);
-        report.total_entities = files.length;
+    // One scan per kind: parse, the kind's frontmatter check, then every
+    // `related` must exist. What a kind adds on top (parent, the orphan
+    // bookkeeping) is in `each`.
+    function scan(kind, each) {
+        const files = scanVaultDir(join(vaultPath, kindDir(kind)));
         for (const filePath of files) {
             const slug = basename(filePath, '.md');
             let fm;
@@ -34,24 +47,29 @@ export function validateVault(vaultPath) {
                 report.missing_fields.push({ slug, field: '', issue: 'failed to parse frontmatter' });
                 continue;
             }
-            const errors = validateEntityFrontmatter(fm);
-            for (const e of errors)
+            for (const e of FRONTMATTER_CHECKS[kind](fm))
                 report.missing_fields.push({ slug, field: '', issue: e });
-            if (fm.parent) {
-                parents.set(slug, fm.parent);
-                if (!exists(fm.parent))
-                    report.broken_slugs.push({ slug, field: 'parent', issue: `parent '${fm.parent}' does not exist` });
-            }
             if (fm.related && Array.isArray(fm.related)) {
                 for (const r of fm.related) {
                     if (!exists(r))
                         report.broken_slugs.push({ slug, field: 'related', issue: `related '${r}' does not exist` });
-                    // Track referenced knowledge
-                    referencedKnowledge.add(r);
                 }
             }
+            each(slug, fm);
         }
+        return files.length;
     }
+    report.total_entities = scan('entity', (slug, fm) => {
+        if (fm.parent) {
+            parents.set(slug, fm.parent);
+            if (!exists(fm.parent))
+                report.broken_slugs.push({ slug, field: 'parent', issue: `parent '${fm.parent}' does not exist` });
+        }
+        // Track referenced knowledge
+        if (Array.isArray(fm.related))
+            for (const r of fm.related)
+                referencedKnowledge.add(r);
+    });
     // Parent cycles: reported once each, under the first member found
     const inCycle = new Set();
     for (const [slug, parent] of parents) {
@@ -64,46 +82,16 @@ export function validateVault(vaultPath) {
             inCycle.add(s);
         report.broken_slugs.push({ slug, field: 'parent', issue: `parent cycle: ${cycle.join(' → ')}` });
     }
-    // Scan knowledge
-    const knDir = join(vaultPath, kindDir('knowledge'));
-    {
-        const files = scanVaultDir(knDir);
-        report.total_knowledge = files.length;
-        for (const filePath of files) {
-            const slug = basename(filePath, '.md');
-            knowledgeSlugs.add(slug);
-            let fm;
-            try {
-                fm = parseFilePath(filePath).frontmatter;
-            }
-            catch {
-                report.missing_fields.push({ slug, field: '', issue: 'failed to parse frontmatter' });
-                continue;
-            }
-            const errors = validateKnowledgeFrontmatter(fm);
-            for (const e of errors)
-                report.missing_fields.push({ slug, field: '', issue: e });
-            if (fm.related && Array.isArray(fm.related)) {
-                for (const r of fm.related) {
-                    if (!exists(r))
-                        report.broken_slugs.push({ slug, field: 'related', issue: `related '${r}' does not exist` });
-                }
-            }
-        }
-    }
+    report.total_knowledge = scan('knowledge', (slug, fm) => {
+        knowledgeRelated.set(slug, Array.isArray(fm.related) ? fm.related.length : 0);
+    });
+    // A session with no related is never an orphan — a session that touched
+    // nothing is legitimate.
+    report.total_sessions = scan('session', () => { });
     // Find orphaned knowledge: no related, and not referenced by any entity
-    for (const slug of knowledgeSlugs) {
-        let fm;
-        try {
-            fm = parseFilePath(join(knDir, `${slug}.md`)).frontmatter;
-        }
-        catch {
-            continue; // already reported above
-        }
-        const hasRelated = fm.related && Array.isArray(fm.related) && fm.related.length > 0;
-        if (!hasRelated && !referencedKnowledge.has(slug)) {
+    for (const [slug, related] of knowledgeRelated) {
+        if (related === 0 && !referencedKnowledge.has(slug))
             report.orphaned_knowledge.push(slug);
-        }
     }
     return report;
 }

package/dist/vault.d.ts

@@ -1,21 +1,32 @@
-import type { ParsedVaultFile } from './types.js';
+import type { ParsedVaultFile, VaultKind } from './types.js';
 export declare function slugify(name: string): string;
-export type VaultKind = 'entity' | 'knowledge' | 'session';
-/** Kinds that live in the SQLite read index (sessions are files-and-git only). */
-export declare const INDEXED_KINDS: ReadonlyArray<'entity' | 'knowledge'>;
+export type { VaultKind };
+/** Kinds that live in the SQLite read index: every kind. Sessions joined in
+ * #35 — before that they were files-and-git only, for no recorded reason. */
+export declare const INDEXED_KINDS: ReadonlyArray<VaultKind>;
+/** The two kinds a mutation can address. A session note is written once and
+ * read; `update`, `link`, `promote` never resolve one. */
+export declare const MUTABLE_KINDS: ReadonlyArray<'entity' | 'knowledge'>;
 /** Vault directory for a kind, relative to the vault root. */
 export declare function kindDir(kind: VaultKind): string;
 /** A vault content file: anything a sync/merge must treat semantically. */
 export declare const VAULT_FILE_RE: RegExp;
-/** True for vault-relative paths whose kind lives in the read index. */
-export declare function isIndexedRelPath(relPath: string): boolean;
+/** True for vault-relative paths of a mutable kind — what index.md shows. */
+export declare function isMutableRelPath(relPath: string): boolean;
 /** History pathspecs covering the indexed dirs (changelog, file times). */
 export declare const INDEXED_DIR_PATHSPECS: ReadonlyArray<string>;
 /** Classify a vault-relative path into an indexed kind + slug; null outside
  * the indexed dirs (sessions, non-vault files). Nested paths keep their
  * historical shape: entities/archive/x-log.md → entity 'archive/x-log'. */
 export declare function classifyIndexedRelPath(relPath: string): {
-    kind: 'entity' | 'knowledge';
+    kind: VaultKind;
+    slug: string;
+} | null;
+/** The note a vault-relative ('/'-separated) path is, or null: the files
+ * scanVaultDir lists — a non-dot `.md` directly in a kind dir. Archive logs,
+ * scaffold files and anything outside the kind dirs are not notes. */
+export declare function noteAtRelPath(relPath: string): {
+    kind: VaultKind;
     slug: string;
 } | null;
 /** All .md files directly in dir — non-recursive (archive/ subdirs are
@@ -25,9 +36,18 @@ export declare function scanVaultDir(dirPath: string): string[];
 /** Where an entity's overflow session-log entries are archived. */
 export declare function archiveLogPath(vaultPath: string, slug: string): string;
 export declare function resolveFilePath(vaultPath: string, slug: string, kind: VaultKind): string;
-/** The file a slug names, or null — entities are resolved before knowledge,
- * the one resolution order every operation sees. */
+/** The inverse of resolveFilePath / archiveLogPath: a vault file as the
+ * Journal names it — vault-relative and '/'-separated on every platform.
+ * Everything downstream compares these lists as POSIX paths: stageablePaths
+ * (src/git.ts) keeps an absent path only if `git ls-files` echoes it back,
+ * always with '/', so a '\' deletion was dropped and never staged; and the
+ * index.md gate (isMutableRelPath) never matched a '\' path (#187). */
+export declare function vaultRel(vaultPath: string, filePath: string): string;
+/** The mutable file a slug names, or null — entities are resolved before
+ * knowledge, the one resolution order every mutation sees. */
 export declare function findVaultFile(vaultPath: string, slug: string): string | null;
+/** The file `read` resolves: the mutable kinds first, then a session note. */
+export declare function findReadableFile(vaultPath: string, slug: string): string | null;
 /** Does this slug name a vault file? An invalid slug definitionally doesn't
  * exist — reference checks (create parent/related, link targets, validate)
  * must report "does not exist", not crash. validate() in particular exists to