hafez 2.1.0 → 2.3.0

package/dist/db.js

@@ -2,13 +2,15 @@ import Database from 'better-sqlite3';
 import { createHash } from 'crypto';
 import { readFileSync, statSync, existsSync, unlinkSync } from 'fs';
 import { join, basename } from 'path';
-import { parseFilePath, scanVaultDir, kindDir, INDEXED_KINDS } from './vault.js';
+import { parseFilePath, scanVaultDir, kindDir, INDEXED_KINDS, MUTABLE_KINDS } from './vault.js';
 import { ensureLocalExclude } from './knowledge-index.js';
 import { WIKI_LINK_RE, documentForFile } from './document.js';
-import { ENTITY_STATUSES, ENTITY_TYPES, CONFIDENCE_LEVELS, VALID_SUBTYPES, DEFAULT_KNOWLEDGE_SUBTYPE } from './contracts.js';
+import { ENTITY_STATUSES, ENTITY_TYPES, CONFIDENCE_LEVELS, VALID_SUBTYPES, DEFAULT_KNOWLEDGE_SUBTYPE, GRAPH_LAYERS, GRAPH_NOTE_RELATIONS, SYNTHETIC_LAYERS } from './contracts.js';
+import { GRAPH_ROW_FIELDS } from './graph/fields.js';
 import { HafezError } from './types.js';
 import { STOPWORDS } from './stopwords.js';
-import { ENTITY_AGE_DAYS_SQL, ENTITY_STALE_SQL } from './stale.js';
+import { closestSlugs } from './closest.js';
+import { ENTITY_AGE_DAYS_SQL, ENTITY_STALE_SQL, DEFAULT_STALENESS_DAYS, actionAge } from './stale.js';
 import { localDay } from './dates.js';
 // Bump this when indexing logic changes to force a full rebuild.
 // v5: wiki link harvesting (mention relations), parent link indexing, relation filter on queries.
@@ -23,8 +25,10 @@ import { localDay } from './dates.js';
 //     rows (REPLACE never fired the delete trigger) and must be rebuilt, not reused.
 // v11: next_action and the searchable body store action text with its
 //     added-date stamp stripped.
+// v12: sessions are indexed (#35); session_date column.
+// v13: action_added column, the open actions' added days (the Graph's stale-action count, #271).
 // Existing instances will fully rebuild the index on first access after upgrade.
-export const SCHEMA_VERSION = '11';
+export const SCHEMA_VERSION = '13';
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS items (
   slug               TEXT PRIMARY KEY,
@@ -50,7 +54,9 @@ CREATE TABLE IF NOT EXISTS items (
   session_log_count  INTEGER DEFAULT 0,
   last_session_date  TEXT,
   last_session_type  TEXT,
-  last_session_summary TEXT
+  last_session_summary TEXT,
+  session_date       TEXT,
+  action_added       TEXT
 );
 
 CREATE TABLE IF NOT EXISTS links (
@@ -100,8 +106,14 @@ const SORT_COL_MAP = {
     staleness: 'i.staleness_days',
     reinforcement_count: 'i.reinforcement_count',
     last_reinforced: 'i.last_reinforced',
+    session_date: 'i.session_date',
+};
+/** Sort fields one branch cannot honour: the column is NULL for its rows. */
+const SORT_REJECTS = {
+    entity: new Set(['reinforcement_count', 'last_reinforced', 'session_date']),
+    knowledge: new Set(['session_date']),
+    session: new Set(['reinforcement_count', 'last_reinforced', 'last_touched', 'staleness']),
 };
-const KNOWLEDGE_ONLY_SORTS = new Set(['reinforcement_count', 'last_reinforced']);
 const SORT_FIELDS = Object.keys(SORT_COL_MAP);
 const SORT_ORDERS = ['asc', 'desc'];
 const QUERY_FILTERS = [...ENTITY_STATUSES, 'all', 'stale', 'capture'];
@@ -163,12 +175,18 @@ function queryItemsFn(db, opts) {
         conditions.push('i.kind = @kind');
         params.kind = opts.kind;
     }
+    else if (!opts.kind) {
+        // Unset is the working set. Sessions are a record of what happened, not
+        // a thing being worked on, and each one names every entity it touched:
+        // in the default view they would crowd out the note being looked for.
+        conditions.push("i.kind != 'session'");
+    }
     if (opts.status) {
-        // Status is an entity attribute — knowledge rows are indexed with a NULL
+        // Status is an entity attribute — other kinds are indexed with a NULL
         // status. In a kind-unset (unified) query the status filter narrows the
         // entity side only; applying it to every row is what made `query --kind
         // all` (filter defaults to active) return entities and nothing else.
-        conditions.push(opts.kind === 'entity' ? 'i.status = @status' : "(i.kind = 'knowledge' OR i.status = @status)");
+        conditions.push(opts.kind === 'entity' ? 'i.status = @status' : "(i.kind != 'entity' OR i.status = @status)");
         params.status = opts.status;
     }
     if (opts.type) {
@@ -212,12 +230,14 @@ function queryItemsFn(db, opts) {
     if (opts.filter === 'capture') {
         conditions.push("i.type = 'capture'");
     }
+    // A session's one day is its session date: the window reads it where an
+    // entity or plan has last_touched.
     if (opts.since) {
-        conditions.push('i.last_touched >= @since');
+        conditions.push('COALESCE(i.last_touched, i.session_date) >= @since');
         params.since = opts.since;
     }
     if (opts.before) {
-        conditions.push('i.last_touched <= @before');
+        conditions.push('COALESCE(i.last_touched, i.session_date) <= @before');
         params.before = opts.before;
     }
     if (opts.createdSince) {
@@ -242,12 +262,12 @@ function queryItemsFn(db, opts) {
     assertSortOrder(opts.sort_order);
     assertCount(opts.limit, 'limit');
     assertCount(opts.offset, 'offset');
-    let sortCol = 'i.last_touched';
+    let sortCol = opts.kind === 'session' ? 'i.session_date' : 'i.last_touched';
     if (opts.sort_by) {
         // Same rule as the unmappable opts, one code path over: a sort field the
         // branch cannot honour is rejected, not quietly swapped for recency.
-        if (KNOWLEDGE_ONLY_SORTS.has(opts.sort_by) && opts.kind === 'entity') {
-            outOfScope('sort_by', opts.sort_by, 'entity');
+        if (opts.kind && opts.kind !== 'all' && SORT_REJECTS[opts.kind].has(opts.sort_by)) {
+            outOfScope('sort_by', opts.sort_by, opts.kind);
         }
         if (SORT_COL_MAP[opts.sort_by])
             sortCol = SORT_COL_MAP[opts.sort_by];
@@ -280,7 +300,7 @@ function queryItemsFn(db, opts) {
                       i.confidence, i.reinforcement_count, i.last_reinforced,
                       i.created, i.last_touched, i.subtype,
                       i.description, i.resource, i.brief, i.session_log_count, i.last_session_date,
-                      i.last_session_type, i.last_session_summary
+                      i.last_session_type, i.last_session_summary, i.session_date
                FROM items i ${where}
                ORDER BY ${sortCol} ${sortOrder}${limitClause}`;
     const rows = db.prepare(sql).all(params);
@@ -306,13 +326,25 @@ function indexEntriesFn(db) {
         domain: getDomains.all(row.slug).map(d => d.target),
     }));
 }
+function graphRowsFn(db) {
+    return {
+        items: db.prepare(`SELECT slug, kind, name, type, status, subtype, confidence, last_touched, description,
+              next_action_count, staleness_days, action_added, (${ENTITY_STALE_SQL}) AS stale
+       FROM items i ORDER BY slug`).all({ today: localDay() }),
+        links: db.prepare('SELECT source, target, relation FROM links ORDER BY source, target, relation').all(),
+    };
+}
 function searchFn(db, query, kind) {
     const { fts: ftsQuery, terms } = sanitizeFtsQuery(query);
     if (!ftsQuery)
         return [];
-    let kindFilter = '';
+    // Same rule as queryItemsFn: unset is the working set, `all` is literal.
+    let kindFilter = "AND i.kind != 'session'";
     const params = { query: ftsQuery };
-    if (kind && kind !== 'all') {
+    if (kind === 'all') {
+        kindFilter = '';
+    }
+    else if (kind) {
         kindFilter = 'AND i.kind = @kind';
         params.kind = kind;
     }
@@ -415,6 +447,7 @@ export function __setAfterScanHook(fn) { afterScanHook = fn; }
 export function createIndex(vaultPath, opts) {
     const dbPath = join(vaultPath, '.hafez.db');
     const isReadOnly = opts?.readonly ?? false;
+    const sync = opts?.sync ?? 'read';
     if (isReadOnly) {
         if (!existsSync(dbPath))
             return null;
@@ -463,11 +496,12 @@ export function createIndex(vaultPath, opts) {
             search: (q, k) => searchFn(db, q, k),
             getStats: () => getStatsFn(db),
             indexEntries: () => indexEntriesFn(db),
+            graphRows: () => graphRowsFn(db),
             close: () => { try {
                 db.close();
             }
             catch { } },
-        });
+        }, sync);
     }
     // --- Write-capable path ---
     // The db files are a disposable local cache — keep them out of the user's
@@ -553,11 +587,13 @@ export function createIndex(vaultPath, opts) {
     INSERT INTO items
       (slug, kind, name, type, status, parent, next_action, next_action_count, staleness_days,
        confidence, reinforcement_count, last_reinforced, created, last_touched, body, file_hash, subtype,
-       description, resource, brief, session_log_count, last_session_date, last_session_type, last_session_summary)
+       description, resource, brief, session_log_count, last_session_date, last_session_type, last_session_summary,
+       session_date, action_added)
     VALUES
       (@slug, @kind, @name, @type, @status, @parent, @next_action, @next_action_count, @staleness_days,
        @confidence, @reinforcement_count, @last_reinforced, @created, @last_touched, @body, @file_hash, @subtype,
-       @description, @resource, @brief, @session_log_count, @last_session_date, @last_session_type, @last_session_summary)
+       @description, @resource, @brief, @session_log_count, @last_session_date, @last_session_type, @last_session_summary,
+       @session_date, @action_added)
   `);
     const deleteItemStmt = db.prepare('DELETE FROM items WHERE slug = ?');
     const deleteLinksStmt = db.prepare('DELETE FROM links WHERE source = ?');
@@ -620,6 +656,11 @@ export function createIndex(vaultPath, opts) {
             last_session_date: lastLog?.date ?? null,
             last_session_type: lastLog?.type ?? null,
             last_session_summary: lastLog?.summary?.slice(0, 300) ?? null,
+            // A session note's one day; the created stamp when digest gave none.
+            session_date: kind === 'session' ? (fm['session-date'] ?? fm.created) : null,
+            action_added: kind === 'entity'
+                ? JSON.stringify(doc.getActionItems(body).flatMap(a => a.handle === undefined ? [] : [a.added]))
+                : null,
         };
         // Replace item and rebuild links. Delete-then-insert keeps the FTS index
         // trigger-consistent for externally changed files (hand edit, git pull),
@@ -657,12 +698,12 @@ export function createIndex(vaultPath, opts) {
         const linkRe = new RegExp(WIKI_LINK_RE.source, 'g');
         while ((wikiMatch = linkRe.exec(authoredBody)) !== null) {
             const targetSlug = wikiMatch[1];
-            // Check if target file exists on disk (not in index — target may not be indexed yet)
-            const targetEntityPath = join(vaultPath, kindDir('entity'), `${targetSlug}.md`);
-            const targetKnowledgePath = join(vaultPath, kindDir('knowledge'), `${targetSlug}.md`);
+            // Check if target file exists on disk (not in index — target may not be
+            // indexed yet), in every indexed dir — the same set the rebuild's
+            // knownSlugs covers, so a mention links the same way on either path.
             const targetExists = knownSlugs
                 ? knownSlugs.has(targetSlug)
-                : existsSync(targetEntityPath) || existsSync(targetKnowledgePath);
+                : INDEXED_KINDS.some(k => existsSync(join(vaultPath, kindDir(k), `${targetSlug}.md`)));
             if (targetExists) {
                 insertLinkStmt.run(slug, targetSlug, 'mention');
             }
@@ -675,17 +716,15 @@ export function createIndex(vaultPath, opts) {
         db.exec('DELETE FROM links');
         // Collect all vault slugs for wiki link target validation
         const allVaultSlugs = new Set();
-        for (const file of scanVaultDir(join(vaultPath, kindDir('entity')))) {
-            allVaultSlugs.add(basename(file, '.md'));
-        }
-        for (const file of scanVaultDir(join(vaultPath, kindDir('knowledge')))) {
-            allVaultSlugs.add(basename(file, '.md'));
-        }
-        for (const file of scanVaultDir(join(vaultPath, kindDir('entity')))) {
-            indexFile(file, 'entity', allVaultSlugs);
+        for (const kind of INDEXED_KINDS) {
+            for (const file of scanVaultDir(join(vaultPath, kindDir(kind)))) {
+                allVaultSlugs.add(basename(file, '.md'));
+            }
         }
-        for (const file of scanVaultDir(join(vaultPath, kindDir('knowledge')))) {
-            indexFile(file, 'knowledge', allVaultSlugs);
+        for (const kind of INDEXED_KINDS) {
+            for (const file of scanVaultDir(join(vaultPath, kindDir(kind)))) {
+                indexFile(file, kind, allVaultSlugs);
+            }
         }
         db.prepare("INSERT OR REPLACE INTO meta (key, value) VALUES ('last_sync', ?)")
             .run(scanStart.toString());
@@ -762,17 +801,34 @@ export function createIndex(vaultPath, opts) {
         search: (q, k) => searchFn(db, q, k),
         getStats: () => getStatsFn(db),
         indexEntries: () => indexEntriesFn(db),
+        graphRows: () => graphRowsFn(db),
         close: () => db.close(),
-    });
+    }, sync);
 }
-function withReadSurface(core) {
+function withReadSurface(core, sync) {
+    // Any sync catches the index up, a caller's own included; from then on the
+    // index stays current with this process's writes (the Spine indexes them).
+    let caughtUp = false;
+    const syncIfStale = () => { core.syncIfStale(); caughtUp = true; };
+    const syncForRead = () => {
+        if (sync === 'read' || (sync === 'once' && !caughtUp))
+            syncIfStale();
+    };
+    const synced = (fn) => (...args) => {
+        syncForRead();
+        return fn(...args);
+    };
     const index = {
         ...core,
-        queryEntities: (opts) => queryEntitiesFn(index, opts),
-        queryChildren: (parentSlug) => queryEntitiesFn(index, { parent: parentSlug }),
-        queryRelatedTo: (slug, relation) => queryRelatedToFn(index, slug, relation),
-        queryKnowledge: (opts) => queryKnowledgeFn(index, opts),
-        queryUnified: (opts) => queryUnifiedFn(index, opts),
+        syncIfStale,
+        syncForRead,
+        queryEntities: synced((opts) => queryEntitiesFn(index, opts)),
+        queryChildren: synced((parentSlug) => queryEntitiesFn(index, { parent: parentSlug })),
+        queryRelatedTo: synced((slug, relation) => queryRelatedToFn(index, slug, relation)),
+        queryKnowledge: synced((opts) => queryKnowledgeFn(index, opts)),
+        querySessions: synced((opts) => querySessionsFn(index, opts)),
+        queryUnified: synced((opts) => queryUnifiedFn(index, opts)),
+        queryGraph: synced((opts) => queryGraphFn(index, opts)),
     };
     return index;
 }
@@ -812,6 +868,23 @@ function toKnowledgeResult(slug, row) {
         last_touched: row.last_touched ?? null,
     };
 }
+function toSessionResult(slug, row) {
+    return {
+        slug,
+        name: row.name,
+        session_date: row.session_date,
+        created: row.created,
+        related: row.related ?? [],
+    };
+}
+/** One row of any kind, shaped for its kind. */
+function toUnifiedResult(i) {
+    if (i.kind === 'entity')
+        return { ...toQueryResult(i.slug, i), kind: 'entity' };
+    if (i.kind === 'session')
+        return { ...toSessionResult(i.slug, i), kind: 'session' };
+    return { ...toKnowledgeResult(i.slug, i), kind: 'knowledge' };
+}
 const STATUS_FILTERS = new Set(ENTITY_STATUSES);
 function mapEntityFilterOpts(qopts, opts) {
     if (opts?.filter && STATUS_FILTERS.has(opts.filter))
@@ -867,11 +940,16 @@ function validateEntityFilterOpts(opts) {
  * Asserted against the CLI's flag matrix in query-surface.test.ts. */
 export const ENTITY_ONLY_OPTS = ['filter', 'type', 'parent'];
 export const KNOWLEDGE_ONLY_OPTS = ['confidence', 'subtype'];
+/** What a session query cannot map: both sides' opts, and the two every
+ * other kind shares — a session note carries no domain and no tags. */
+export const SESSION_REJECTED_OPTS = [...ENTITY_ONLY_OPTS, ...KNOWLEDGE_ONLY_OPTS, 'domain', 'tags'];
 /** The one sentence both scope rejections speak — opts here, sort fields in
  * queryItemsFn — so a caller sees the same shape whichever one they hit. */
 function outOfScope(label, name, branch) {
-    const belongsTo = branch === 'entity' ? 'knowledge notes only' : 'entities only';
-    throw new HafezError('VALIDATION_FAILED', `Invalid ${label} for a ${branch} query: "${name}" — ${belongsTo}. Use kind: 'all' to query both.`);
+    const belongsTo = branch === 'entity' ? 'knowledge notes only'
+        : branch === 'knowledge' ? 'entities only'
+            : 'entities and knowledge notes only';
+    throw new HafezError('VALIDATION_FAILED', `Invalid ${label} for a ${branch} query: "${name}" — ${belongsTo}. Use kind: 'all' to query every kind.`);
 }
 function rejectUnmappableOpts(opts, reject, branch) {
     if (!opts)
@@ -887,7 +965,6 @@ function validateKnowledgeFilterOpts(opts) {
     assertEnum(opts?.subtype, VALID_SUBTYPES, 'subtype');
 }
 function queryEntitiesFn(index, opts) {
-    index.syncIfStale();
     validateEntityFilterOpts(opts);
     // Was validateKnowledgeFilterOpts — it checked the *value* of an opt this
     // branch then discarded, so a valid-looking one returned unfiltered.
@@ -901,18 +978,12 @@ function queryEntitiesFn(index, opts) {
     const { items, total } = index.queryItems(qopts);
     return { items: items.map(i => toQueryResult(i.slug, i)), total };
 }
+/** Every kind: the sessions that touched an entity are the look back from it. */
 function queryRelatedToFn(index, slug, relation) {
-    index.syncIfStale();
-    const { items, total } = index.queryItems({ relatedTo: slug, relation });
-    return {
-        items: items.map(i => i.kind === 'entity'
-            ? { ...toQueryResult(i.slug, i), kind: 'entity' }
-            : { ...toKnowledgeResult(i.slug, i), kind: 'knowledge' }),
-        total,
-    };
+    const { items, total } = index.queryItems({ kind: 'all', relatedTo: slug, relation });
+    return { items: items.map(toUnifiedResult), total };
 }
 function queryKnowledgeFn(index, opts) {
-    index.syncIfStale();
     validateKnowledgeFilterOpts(opts);
     rejectUnmappableOpts(opts, ENTITY_ONLY_OPTS, 'knowledge');
     validateTimeOpts(opts);
@@ -924,14 +995,23 @@ function queryKnowledgeFn(index, opts) {
     const { items, total } = index.queryItems(qopts);
     return { items: items.map(i => toKnowledgeResult(i.slug, i)), total };
 }
+function querySessionsFn(index, opts) {
+    rejectUnmappableOpts(opts, SESSION_REJECTED_OPTS, 'session');
+    validateTimeOpts(opts);
+    validateListOpts(opts);
+    const qopts = { kind: 'session' };
+    mapTimeOpts(qopts, opts);
+    mapListOpts(qopts, opts);
+    const { items, total } = index.queryItems(qopts);
+    return { items: items.map(i => toSessionResult(i.slug, i)), total };
+}
 function queryUnifiedFn(index, opts) {
-    index.syncIfStale();
     // The public type is a union discriminated on `kind`, so an out-of-scope opt
     // is a compile error. The runtime still has to see every opt to reject it —
     // an untyped caller (JS, JSON over MCP) reaches here regardless — so widen
     // once, here, and let the checks below speak for both.
     const o = opts;
-    assertEnum(o?.kind, ['entity', 'knowledge', 'all'], 'kind');
+    assertEnum(o?.kind, ['entity', 'knowledge', 'session', 'all'], 'kind');
     validateEntityFilterOpts(o);
     validateKnowledgeFilterOpts(o);
     // Only `kind: 'all'` (or unset) maps both sides. `kind` also narrows this
@@ -943,24 +1023,130 @@ function queryUnifiedFn(index, opts) {
         rejectUnmappableOpts(o, KNOWLEDGE_ONLY_OPTS, 'entity');
     if (o?.kind === 'knowledge')
         rejectUnmappableOpts(o, ENTITY_ONLY_OPTS, 'knowledge');
+    if (o?.kind === 'session')
+        rejectUnmappableOpts(o, SESSION_REJECTED_OPTS, 'session');
     validateTimeOpts(o);
     validateListOpts(o);
-    const qopts = {};
-    if (o?.kind && o.kind !== 'all')
-        qopts.kind = o.kind;
-    // When kind is 'all' or unset, no kind filter — both entities and knowledge are returned
+    // Unset is the working set (entity + knowledge); 'all' reaches every kind.
+    const qopts = { kind: o?.kind };
     mapEntityFilterOpts(qopts, o);
     mapKnowledgeFilterOpts(qopts, o);
     mapTimeOpts(qopts, o);
     mapListOpts(qopts, o);
     const result = index.queryItems(qopts);
-    const items = result.items.map(i => {
-        if (i.kind === 'entity') {
-            return { ...toQueryResult(i.slug, i), kind: 'entity' };
+    return { items: result.items.map(toUnifiedResult), total: result.total };
+}
+/** The Graph's node kinds by default: the working set, entities and knowledge. */
+const GRAPH_KINDS = new Set(MUTABLE_KINDS);
+const GRAPH_RELATIONS = new Set(GRAPH_NOTE_RELATIONS);
+/** The opts graph() applies; any other is rejected, never dropped. */
+const GRAPH_OPTS = ['layers'];
+/** The layers whose nodes are synthetic: one per distinct value, `<layer>:<value>`. */
+const SYNTHETIC = new Set(SYNTHETIC_LAYERS);
+function queryGraphFn(index, opts) {
+    for (const [name, value] of Object.entries(opts ?? {})) {
+        if (value !== undefined && !GRAPH_OPTS.includes(name)) {
+            throw new HafezError('VALIDATION_FAILED', `Invalid opt for a graph query: "${name}"`);
         }
-        else {
-            return { ...toKnowledgeResult(i.slug, i), kind: 'knowledge' };
+    }
+    const given = opts?.layers ?? [];
+    if (!Array.isArray(given) || given.some(l => !GRAPH_LAYERS.includes(l))) {
+        throw new HafezError('VALIDATION_FAILED', `Invalid graph layers: ${JSON.stringify(given)}. Valid values: ${GRAPH_LAYERS.join(', ')}.`);
+    }
+    const layers = new Set(given);
+    const { items, links } = index.graphRows();
+    const nodes = [];
+    for (const i of items) {
+        if (!GRAPH_KINDS.has(i.kind) && !(i.kind === 'session' && layers.has('session')))
+            continue;
+        const node = { id: i.slug, kind: i.kind, name: i.name };
+        // The index's columns are plain strings; what it stores there for a
+        // note is the frontmatter's validated enum value.
+        for (const key of GRAPH_ROW_FIELDS)
+            if (i[key] != null)
+                Object.assign(node, { [key]: i[key] });
+        if (i.kind === 'entity')
+            Object.assign(node, entitySignals(i));
+        nodes.push(node);
+    }
+    markUnlinked(nodes, links);
+    // An edge needs both ends on the graph: a missing note, or a session, tag or
+    // domain outside its layer, is no node. Related is one edge per unordered
+    // pair (ADR 0002); a legacy one-way edge is emitted once, as written.
+    const ids = new Set(nodes.map(n => n.id));
+    // A Session's only edges are the `related` it names: the Entities it touched.
+    const sessions = new Set(nodes.filter(n => n.kind === 'session').map(n => n.id));
+    const pairs = new Set();
+    const edges = [];
+    // A tag or domain node exists for each value a node carries; its id cannot
+    // collide with a slug, which never holds `:`.
+    const layerNodes = new Map();
+    for (const l of links) {
+        if (layers.has(l.relation) && SYNTHETIC.has(l.relation)) {
+            if (!ids.has(l.source) || sessions.has(l.source))
+                continue;
+            const id = `${l.relation}:${l.target}`;
+            if (!layerNodes.has(id))
+                layerNodes.set(id, { id, kind: l.relation, name: l.target });
+            edges.push({ source: l.source, target: id, relation: l.relation });
+            continue;
         }
-    });
-    return { items, total: result.total };
+        if (!GRAPH_RELATIONS.has(l.relation) || !ids.has(l.source) || !ids.has(l.target))
+            continue;
+        if (sessions.has(l.target) || (sessions.has(l.source) && l.relation !== 'related'))
+            continue;
+        if (l.relation === 'related') {
+            const pair = [l.source, l.target].sort().join('\n');
+            if (pairs.has(pair))
+                continue;
+            pairs.add(pair);
+        }
+        edges.push({ source: l.source, target: l.target, relation: l.relation });
+    }
+    nodes.push(...[...layerNodes.values()].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)));
+    return { nodes, edges };
+}
+/** What an Entity node carries of its state (#271): every Entity its effective
+ * staleness-days; an active or paused one its open actions and stale-action
+ * count too (#277: the sidebar's Paused rows count them), and an active one
+ * its Stale flag. A done Entity carries no action signal. */
+function entitySignals(i) {
+    const staleness_days = i.staleness_days ?? DEFAULT_STALENESS_DAYS;
+    if (i.status !== 'active' && i.status !== 'paused')
+        return { staleness_days };
+    const today = localDay();
+    const added = JSON.parse(i.action_added ?? '[]');
+    return {
+        open_actions: i.next_action_count,
+        ...(i.status === 'active' && { stale: i.stale === 1 }),
+        stale_actions: added.filter(day => actionAge(day, staleness_days, today).stale).length,
+        staleness_days,
+    };
+}
+/** Mark each Unlinked note (CONTEXT: no Parent, Related or Wiki-link edge to
+ * another Entity or Knowledge note, either way; tags and Sessions do not
+ * count) and give it `best`, the slug its placing line names: the closest
+ * linked note (src/closest.ts, which weighs each linked note's name and
+ * description) to the Unlinked note's name, else to its description; the
+ * same kind when one matches, else any kind; none when nothing matches. */
+function markUnlinked(nodes, links) {
+    const notes = new Map(nodes.filter(n => n.kind === 'entity' || n.kind === 'knowledge').map(n => [n.id, n]));
+    const linked = new Set();
+    for (const l of links) {
+        if (!GRAPH_RELATIONS.has(l.relation) || l.source === l.target || !notes.has(l.source) || !notes.has(l.target))
+            continue;
+        linked.add(l.source);
+        linked.add(l.target);
+    }
+    const candidates = [...notes.values()].filter(n => linked.has(n.id))
+        .map(n => ({ kind: n.kind, slug: n.id, name: n.name, description: n.description ?? null }));
+    const closest = (n, among) => closestSlugs(n.name, among)[0] ?? (n.description ? closestSlugs(n.description, among)[0] : undefined);
+    for (const n of notes.values()) {
+        if (linked.has(n.id))
+            continue;
+        n.unlinked = true;
+        const best = closest(n, candidates.filter(c => c.kind === n.kind)) ?? closest(n, candidates);
+        if (best !== undefined)
+            n.best = best;
+    }
 }

package/dist/digest.js

@@ -67,18 +67,22 @@ export function digest(input, entitySlugs, knowledgeSlugs = new Set()) {
         ops.push({ op: 'update', slug, fields });
     }
     // 2. Session note
-    const noteBody = buildSessionNoteBody(input, touched);
     const related = touched;
     // Typechecked against the Op Spec's session-create schema so digest output
     // can never silently diverge from what batch validation accepts.
+    // A blank decision is dropped here: the Op Spec takes non-empty text only,
+    // and one blank line must not fail the whole save. The name hash below still
+    // reads the raw input, so the slug a save before this derived is unchanged.
+    const decisions = input.decisions.map(d => d.trim()).filter(Boolean);
     const noteFields = {
-        synthesis: noteBody,
+        synthesis: input.narrative.trim(),
         'session-date': input.session_date,
-        ...(related.length > 0 ? { related } : {}),
+        ...(decisions.length > 0 ? { decisions } : {}),
+        ...(related.length > 0 ? { related, entities_touched: touched } : {}),
     };
-    // Named by the session date and its note, so a second save of the same
-    // session derives the same slug and batch skips it as a duplicate.
-    const noteName = `Session ${input.session_date} ${createHash('sha256').update(noteBody).digest('hex').slice(0, 8)}`;
+    // Named by the session date and its whole content, so a second save of the
+    // same session derives the same slug and batch skips it as a duplicate.
+    const noteName = `Session ${input.session_date} ${createHash('sha256').update(sessionIdentity(input, touched)).digest('hex').slice(0, 8)}`;
     ops.push({ op: 'create', kind: 'session', name: noteName, fields: noteFields });
     return ops;
 }
@@ -90,7 +94,10 @@ function buildSessionLogSummary(input) {
     }
     return parts.join(' | ');
 }
-function buildSessionNoteBody(input, touched) {
+/** What the session note's name hashes: narrative, decisions and touched
+ * slugs, in the text the note body held before its sections were split
+ * (#210), so a session saved before then is still skipped when saved again. */
+function sessionIdentity(input, touched) {
     const lines = [input.narrative.trim()];
     if (input.decisions.length > 0) {
         lines.push('');

package/dist/document.d.ts

@@ -1,4 +1,5 @@
 import { type SessionLogEntry, type SessionLogType } from './types.js';
+export declare const ACTION_RE: RegExp;
 /** The action text without its trailing added-date stamp, if any. */
 export declare function stripActionStamp(text: string): string;
 /** The day an action's stamp names; null when the line is undated. */
@@ -45,6 +46,7 @@ export declare function firstNonEmptyLine(s: string | null | undefined): string;
  * every consumer (Related coverage, mention harvesting, export) sees the bare slug.
  * Non-global — wrap with `new RegExp(WIKI_LINK_RE.source, 'g')` for iteration. */
 export declare const WIKI_LINK_RE: RegExp;
+export declare function escapeRegex(s: string): string;
 /** What documentFor needs to know about a file to bind its section set.
  *
  * KIND is the whole context — deliberately no type/subtype narrowing. A file

package/dist/document.js

@@ -16,7 +16,7 @@ import { localDay } from './dates.js';
 // One checkbox line of Next Actions, tested line by line. `m` so a CRLF
 // line's trailing \r is not taken as action text.
 const OPEN_ACTION_RE = /^- \[ \] (.+)$/m;
-const ACTION_RE = /^- \[([ xX])\] (.+)$/m;
+export const ACTION_RE = /^- \[([ xX])\] (.+)$/m;
 // --- Next-action added-date stamp ---
 // Adding an action stamps its line `(added YYYY-MM-DD)` with the local day
 // (Apply does the stamping — every add path goes through it). The stamp is
@@ -109,7 +109,7 @@ export function firstNonEmptyLine(s) {
  * every consumer (Related coverage, mention harvesting, export) sees the bare slug.
  * Non-global — wrap with `new RegExp(WIKI_LINK_RE.source, 'g')` for iteration. */
 export const WIKI_LINK_RE = /\[\[\s*([^\]|]+?)\s*(?:\|\s*([^\]]+?)\s*)?\]\]/;
-function escapeRegex(s) {
+export function escapeRegex(s) {
     return s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 /**

package/dist/git.d.ts

@@ -1,4 +1,4 @@
-import { type GitConfig, type ChangelogEntry, type Journal } from './types.js';
+import { type GitConfig, type ChangelogEntry, type FileChange, type Journal } from './types.js';
 /**
  * Bidirectional sync: pull remote changes, push local commits.
  * All work must be committed before calling — no file save/restore needed.
@@ -8,7 +8,7 @@ export declare function gitSync(vaultPath: string): Promise<{
     pushed: boolean;
     remote: boolean;
 }>;
-export declare function gitChangelog(vaultPath: string, since: string): Promise<ChangelogEntry[]>;
+export declare function gitChangelog(vaultPath: string, since: string, limit?: number): Promise<ChangelogEntry[]>;
 /**
  * Latest git time per file (repo-relative, forward-slash paths). Used to
  * break day-granularity frontmatter ties in stats recents. `modified` maps
@@ -16,6 +16,17 @@ export declare function gitChangelog(vaultPath: string, since: string): Promise<
  * Files with no history (not yet committed) are absent from the map.
  */
 export declare function gitFileTimes(vaultPath: string, mode: 'modified' | 'added'): Promise<Map<string, string>>;
+/**
+ * The Journal's changesSince: HEAD as the cursor, and the indexed-dir files
+ * whose content differs between `from` and HEAD. A diff between two points,
+ * not a walk of the commits in between, so the status is the net one: a file
+ * made and removed inside the span is not there. core.quotePath off keeps
+ * non-ASCII paths (legitimate slugs) unquoted.
+ */
+export declare function gitChangesSince(vaultPath: string, from?: string): Promise<{
+    cursor: string;
+    files: FileChange[];
+}>;
 export declare function gitCommitAndPush(vaultPath: string, files: string[], message: string, config?: GitConfig): Promise<void>;
 /**
  * The production Journal (see CONTEXT.md): vault persistence backed by git.