hafez 2.2.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.
@@ -24,8 +26,9 @@ import { localDay } from './dates.js';
 // 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 = '12';
+export const SCHEMA_VERSION = '13';
 const SCHEMA = `
 CREATE TABLE IF NOT EXISTS items (
   slug               TEXT PRIMARY KEY,
@@ -52,7 +55,8 @@ CREATE TABLE IF NOT EXISTS items (
   last_session_date  TEXT,
   last_session_type  TEXT,
   last_session_summary TEXT,
-  session_date       TEXT
+  session_date       TEXT,
+  action_added       TEXT
 );
 
 CREATE TABLE IF NOT EXISTS links (
@@ -322,6 +326,14 @@ 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)
@@ -435,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;
@@ -483,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
@@ -574,12 +588,12 @@ export function createIndex(vaultPath, opts) {
       (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,
-       session_date)
+       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,
-       @session_date)
+       @session_date, @action_added)
   `);
     const deleteItemStmt = db.prepare('DELETE FROM items WHERE slug = ?');
     const deleteLinksStmt = db.prepare('DELETE FROM links WHERE source = ?');
@@ -644,6 +658,9 @@ export function createIndex(vaultPath, opts) {
             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),
@@ -784,18 +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),
-        querySessions: (opts) => querySessionsFn(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;
 }
@@ -932,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.
@@ -948,12 +980,10 @@ function queryEntitiesFn(index, opts) {
 }
 /** 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({ 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);
@@ -966,7 +996,6 @@ function queryKnowledgeFn(index, opts) {
     return { items: items.map(i => toKnowledgeResult(i.slug, i)), total };
 }
 function querySessionsFn(index, opts) {
-    index.syncIfStale();
     rejectUnmappableOpts(opts, SESSION_REJECTED_OPTS, 'session');
     validateTimeOpts(opts);
     validateListOpts(opts);
@@ -977,7 +1006,6 @@ function querySessionsFn(index, opts) {
     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
@@ -1008,3 +1036,117 @@ function queryUnifiedFn(index, opts) {
     const result = index.queryItems(qopts);
     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}"`);
+        }
+    }
+    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;
+        }
+        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.

package/dist/git.js

@@ -451,7 +451,7 @@ function gitReadFailed(err) {
     const lines = (err instanceof Error ? err.message : String(err)).split('\n').map(l => l.trim()).filter(Boolean);
     return new HafezError('GIT_READ_FAILED', `git read failed: ${lines[0] ?? 'unknown error'}`, lines);
 }
-export async function gitChangelog(vaultPath, since) {
+export async function gitChangelog(vaultPath, since, limit) {
     const git = vaultGit(vaultPath);
     // Bare dates become local midnight — the same calendar-day boundary the
     // vault stamps and query comparisons use (see dates.ts).
@@ -459,7 +459,7 @@ export async function gitChangelog(vaultPath, since) {
     let output;
     try {
         output = await git.raw([
-            'log', `--since=${normalizedSince}`, '--name-status',
+            'log', ...(since ? [`--since=${normalizedSince}`] : []), ...(limit === undefined ? [] : [`--max-count=${limit}`]), '--name-status',
             '--pretty=format:%H|%aI|%s', '--', ...INDEXED_DIR_PATHSPECS,
         ]);
     }
@@ -479,7 +479,7 @@ export async function gitChangelog(vaultPath, since) {
         const headerMatch = lines[0].match(/^([0-9a-f]+)\|(.+?)\|(.*)$/);
         if (!headerMatch)
             continue;
-        const [, , timestamp, commit_message] = headerMatch;
+        const [, commit, timestamp, commit_message] = headerMatch;
         for (let i = 1; i < lines.length; i++) {
             for (const { path: filePath, operation } of parseNameStatusLine(lines[i])) {
                 // Only vault documents — scaffold files (.gitkeep) live in the same
@@ -489,7 +489,7 @@ export async function gitChangelog(vaultPath, since) {
                 const classified = classifyIndexedRelPath(filePath);
                 if (!classified)
                     continue;
-                entries.push({ slug: classified.slug, kind: classified.kind, operation, timestamp, commit_message });
+                entries.push({ slug: classified.slug, kind: classified.kind, operation, timestamp, commit_message, commit });
             }
         }
     }
@@ -528,6 +528,47 @@ export async function gitFileTimes(vaultPath, mode) {
     }
     return times;
 }
+const CHANGE_OPS = { created: 'create', updated: 'update', deleted: 'delete' };
+/**
+ * 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 async function gitChangesSince(vaultPath, from) {
+    const git = vaultGit(vaultPath);
+    let cursor;
+    try {
+        cursor = (await git.raw(['log', '-1', '--format=%H'])).trim();
+    }
+    catch (err) {
+        if (isNoHistory(err))
+            return { cursor: '', files: [] };
+        throw gitReadFailed(err);
+    }
+    if (from === undefined || from === cursor)
+        return { cursor, files: [] };
+    const files = [];
+    try {
+        if (from === '') {
+            const listed = await git.raw(['-c', 'core.quotePath=false', 'ls-tree', '-r', '--name-only', cursor, '--', ...INDEXED_DIR_PATHSPECS]);
+            for (const path of listed.split('\n').filter(Boolean))
+                files.push({ path, op: 'create' });
+        }
+        else {
+            const diff = await git.raw(['-c', 'core.quotePath=false', 'diff', '--name-status', from, cursor, '--', ...INDEXED_DIR_PATHSPECS]);
+            for (const line of diff.split('\n')) {
+                for (const { path, operation } of parseNameStatusLine(line))
+                    files.push({ path, op: CHANGE_OPS[operation] });
+            }
+        }
+    }
+    catch (err) {
+        throw gitReadFailed(err);
+    }
+    return { cursor, files };
+}
 export async function gitCommitAndPush(vaultPath, files, message, config = {}) {
     const git = vaultGit(vaultPath);
     // If a previous run crashed mid-rebase/merge, the repo is stuck.
@@ -601,7 +642,8 @@ export function createGitJournal(vaultPath, config = {}) {
             }
         },
         sync: () => gitSync(vaultPath),
-        changelog: (since) => gitChangelog(vaultPath, since),
+        changelog: (since, limit) => gitChangelog(vaultPath, since, limit),
         fileTimes: (mode) => gitFileTimes(vaultPath, mode),
+        changesSince: (from) => gitChangesSince(vaultPath, from),
     };
 }

package/dist/graph/activity.d.ts

@@ -0,0 +1,5 @@
+import type { ActivityRow, Hafez } from '../types.js';
+/** How many rows `/activity` lists. */
+export declare const ACTIVITY_ROWS = 20;
+/** `names` maps a slug to the name its node carries now. */
+export declare function activity(os: Hafez, names: Map<string, string>): Promise<ActivityRow[]>;

package/dist/graph/activity.js

@@ -0,0 +1,70 @@
+import { parseSessionLog } from '../document.js';
+import { localDay } from '../dates.js';
+import { kindDir, noteAtRelPath } from '../vault.js';
+/** How many rows `/activity` lists. */
+export const ACTIVITY_ROWS = 20;
+/** How many of the newest commits are read first: a history read costs
+ * ~25 ms a commit on drvfs, so the whole history is never read at once.
+ * While those collapse into fewer rows, twice as many are read, until the
+ * rows are full or a read covers fewer commits than it asked for (the
+ * history's end). */
+const COMMITS_READ = 50;
+const OP = { created: 'create', updated: 'update', deleted: 'delete' };
+/** `names` maps a slug to the name its node carries now. */
+export async function activity(os, names) {
+    for (let commits = COMMITS_READ;; commits *= 2) {
+        const entries = await os.changelog('', commits);
+        const { rows, full } = collapse(entries, names);
+        // The commits the read covered, counted by hash: every note commit lists
+        // at least one entry (a commit touching no note under a note dir, the
+        // scaffold's .gitkeep, is the history's first).
+        if (full || new Set(entries.map(e => e.commit)).size < commits)
+            return withAgents(os, rows);
+    }
+}
+/** The changelog's entries as rows, newest first; `full` once a row past the
+ * last has begun, so the last row's run of writes is known to be whole. */
+function collapse(entries, names) {
+    const rows = [];
+    for (const e of entries) {
+        // The changelog lists every file under a kind dir, an archive log
+        // (`entities/archive/<slug>-log.md`) too; the Layout says which are notes.
+        if (!noteAtRelPath(`${kindDir(e.kind)}/${e.slug}.md`))
+            continue;
+        const op = OP[e.operation];
+        const last = rows[rows.length - 1];
+        if (last?.slug === e.slug) {
+            // A promote deletes and creates the note in one commit: one write, and
+            // the create is what happened to it.
+            if (last.commit === e.commit && (last.op === 'delete') !== (op === 'delete')) {
+                if (op !== 'delete' && last.count === 1)
+                    Object.assign(last, { op, kind: e.kind });
+            }
+            else {
+                last.count++;
+                last.commit = e.commit;
+            }
+            continue;
+        }
+        if (rows.length === ACTIVITY_ROWS)
+            return { rows, full: true };
+        rows.push({ slug: e.slug, kind: e.kind, op, timestamp: e.timestamp, name: names.get(e.slug) ?? e.slug, count: 1, commit: e.commit });
+    }
+    return { rows, full: false };
+}
+/** Each Entity row with the agent its Session Log records for the write's day. */
+function withAgents(os, rows) {
+    return Promise.all(rows.map(async ({ commit: _, ...row }) => {
+        const agent = row.kind === 'entity' && row.op !== 'delete' ? await agentOf(os, row.slug, localDay(new Date(row.timestamp))) : undefined;
+        return agent ? { ...row, agent } : row;
+    }));
+}
+/** The agent of the Entity's newest Session Log entry dated `day`. */
+async function agentOf(os, slug, day) {
+    try {
+        return parseSessionLog((await os.read(slug, 'full')).body).find(entry => entry.date === day)?.agent;
+    }
+    catch {
+        return undefined; // gone since: nothing to read the agent from
+    }
+}