hafez 2.2.0 → 2.3.0

package/dist/read-json.d.ts

@@ -0,0 +1,26 @@
+import type { Hafez, ParsedFile, ReadDepth } from './types.js';
+import { type Workstream } from './workstream.js';
+import { type ChildLine, type FooterInput } from './surfaces/items.js';
+/** `read --json`'s object for a note read at `depth`: what the CLI prints and
+ * what the graph server's `/note/:slug` serves. `whole`, its full-depth read
+ * when the caller holds one, saves reading it again. */
+export declare function readJsonOf(os: Hafez, slug: string, depth: ReadDepth, result: ParsedFile, whole?: ParsedFile): Promise<object>;
+/** What hangs off an entity elsewhere: the sessions that touched it (the
+ * look back, #35), its archived log entries (#34), its children (#230) and
+ * the prefix families its own Next Actions carry unsplit against the
+ * entities whose `parent` or `related` names it (#230). Counted at read
+ * time, nothing written. */
+export declare function pointersFor(os: Hafez, slug: string, body: string): Promise<{
+    sessions: {
+        count: number;
+        latest: string | null;
+    };
+    archive_entries: number;
+    children: ChildLine[];
+    workstreams: Workstream[];
+}>;
+/** The Footer for a file read at full depth: its Handle comes from the
+ * whole file. A session note has none: it is never written to. */
+export declare function footerFor(slug: string, result: Exclude<ParsedFile, {
+    kind: 'session';
+}>): FooterInput;

package/dist/read-json.js

@@ -0,0 +1,53 @@
+import { detectAgent } from './harness.js';
+import { getActionItems, parseSessionLogHeading } from './document.js';
+import { agedActions } from './stale.js';
+import { workstreams } from './workstream.js';
+import { CHILDREN_SHOWN, footerOp } from './surfaces/items.js';
+/** `read --json`'s object for a note read at `depth`: what the CLI prints and
+ * what the graph server's `/note/:slug` serves. `whole`, its full-depth read
+ * when the caller holds one, saves reading it again. */
+export async function readJsonOf(os, slug, depth, result, whole) {
+    // A session note is read, never written: no Footer (#35).
+    if (result.kind === 'session')
+        return result;
+    // The Footer and the pointers are the same at every depth: they read the
+    // whole file, not the body this depth shows.
+    const full = (whole ?? (depth === 'full' ? result : await os.read(slug, 'full')));
+    const writes = footerOp(footerFor(slug, full));
+    const pointers = full.kind === 'entity' ? await pointersFor(os, slug, full.body) : null;
+    const json = pointers && { ...pointers, children: pointers.children.slice(0, CHILDREN_SHOWN), children_total: pointers.children.length };
+    // A frontmatter-depth read carries no body, so it has no actions to list.
+    if (result.kind !== 'entity' || depth === 'frontmatter')
+        return { ...result, ...json, writes };
+    return { ...result, actions: agedActions(result.body, result.frontmatter), ...json, writes };
+}
+/** What hangs off an entity elsewhere: the sessions that touched it (the
+ * look back, #35), its archived log entries (#34), its children (#230) and
+ * the prefix families its own Next Actions carry unsplit against the
+ * entities whose `parent` or `related` names it (#230). Counted at read
+ * time, nothing written. */
+export async function pointersFor(os, slug, body) {
+    const relatedTo = (await os.related_to(slug)).items;
+    const sessions = relatedTo.filter((i) => i.kind === 'session');
+    const latest = sessions.reduce((max, s) => (max === null || s.session_date > max ? s.session_date : max), null);
+    const archive = await os.archive(slug);
+    const entries = archive ? archive.split('\n').filter(line => parseSessionLogHeading(line)).length : 0;
+    // The children block (#230): the index's children query, last-touched
+    // descending then slug for a stable order; the renders cap what is shown.
+    const childItems = (await os.children(slug)).items;
+    const children = [...childItems]
+        .sort((a, b) => b.last_touched.localeCompare(a.last_touched) || a.slug.localeCompare(b.slug))
+        .map(c => ({ slug: c.slug, description: c.description, open_actions: c.next_action_count, last_touched: c.last_touched }));
+    const naming = [...childItems, ...relatedTo.filter(i => i.kind === 'entity')];
+    return { sessions: { count: sessions.length, latest }, archive_entries: entries, children, workstreams: workstreams(body, naming) };
+}
+/** The Footer for a file read at full depth: its Handle comes from the
+ * whole file. A session note has none: it is never written to. */
+export function footerFor(slug, result) {
+    return { slug, agent: detectAgent(), ...(result.kind === 'entity'
+            ? {
+                target: { kind: 'entity', type: result.frontmatter.type },
+                handle: getActionItems(result.body).find(a => a.handle)?.handle,
+            }
+            : { target: { kind: 'knowledge', subtype: result.frontmatter.subtype } }) };
+}

package/dist/stale.d.ts

@@ -9,8 +9,8 @@ export interface ActionAge {
 }
 /** The entity side of the rule, as SQL over an index row `i` with `@today`
  * bound to localDay(): whole days from its last-touched day to today.
- * julianday of two bare YYYY-MM-DD days differs by exactly `dayNumber`'s
- * difference, so entities and their actions count the same days. */
+ * julianday of two bare YYYY-MM-DD days differs by exactly `daysBetween`
+ * (src/dates.ts), so entities and their actions count the same days. */
 export declare const ENTITY_AGE_DAYS_SQL = "CAST(julianday(@today) - julianday(i.last_touched) AS INTEGER)";
 /** An entity row is stale when its age is past its threshold, not equal to
  * it — `actionAge`'s rule. */

package/dist/stale.js

@@ -2,19 +2,14 @@
 // Stale (see CONTEXT.md): past the entity's `staleness-days` without
 // movement. An open next action is stale when unticked that long since its
 // added day; an undated one is stale. Ages count local days (src/dates.ts).
-import { localDay } from './dates.js';
+import { daysBetween, localDay } from './dates.js';
 import { getActionItems } from './document.js';
 /** The threshold an entity without `staleness-days` gets. */
 export const DEFAULT_STALENESS_DAYS = 14;
-/** A YYYY-MM-DD day as a whole day count, so differences ignore DST. */
-const dayNumber = (day) => {
-    const [y, m, d] = day.split('-').map(Number);
-    return Date.UTC(y, m - 1, d) / 86_400_000;
-};
 /** The entity side of the rule, as SQL over an index row `i` with `@today`
  * bound to localDay(): whole days from its last-touched day to today.
- * julianday of two bare YYYY-MM-DD days differs by exactly `dayNumber`'s
- * difference, so entities and their actions count the same days. */
+ * julianday of two bare YYYY-MM-DD days differs by exactly `daysBetween`
+ * (src/dates.ts), so entities and their actions count the same days. */
 export const ENTITY_AGE_DAYS_SQL = 'CAST(julianday(@today) - julianday(i.last_touched) AS INTEGER)';
 /** An entity row is stale when its age is past its threshold, not equal to
  * it — `actionAge`'s rule. */
@@ -24,7 +19,7 @@ export const ENTITY_STALE_SQL = `${ENTITY_AGE_DAYS_SQL} > COALESCE(i.staleness_d
 export function actionAge(added, stalenessDays, today = localDay()) {
     if (added === null)
         return { added, age_days: null, stale: true };
-    const age_days = dayNumber(today) - dayNumber(added);
+    const age_days = daysBetween(added, today);
     return { added, age_days, stale: age_days > stalenessDays };
 }
 /** An entity's threshold: its `staleness-days`, else the default. */

package/dist/surfaces/items.d.ts

@@ -1,6 +1,7 @@
 import { type DocTarget, type WriteLineField } from '../contracts.js';
 import { renderActionHandles } from '../document.js';
 import type { ActionAge } from '../stale.js';
+import type { Workstream } from '../workstream.js';
 import type { KnowledgeSubtype, UpdateFields, UpdateResult } from '../types.js';
 import { type OnboardHarness } from '../harness.js';
 import type { Mode } from '../cli/install.js';
@@ -112,6 +113,28 @@ declare function renderArchivePointer({ slug, entries }: {
     slug: string;
     entries: number;
 }): string;
+/** A child as the `read` header shows it. */
+export interface ChildLine {
+    slug: string;
+    description: string | null;
+    open_actions: number;
+    last_touched: string;
+}
+/** How many children the header lists; the rest are one overflow line. */
+export declare const CHILDREN_SHOWN = 5;
+/** The `read` header's children block: the count line (children, open
+ * actions across all of them), one `hafez read` line per child (description,
+ * open count, last-touched day) for the first `CHILDREN_SHOWN`, and the
+ * overflow line naming the query that lists the rest. Children arrive sorted
+ * by last-touched descending. No children: no block. */
+declare function renderChildrenBlock({ slug, children }: {
+    slug: string;
+    children: ChildLine[];
+}): string;
+/** The `read` header's fact line for one unsplit prefix family (#230):
+ * its open-line count and the family, and that no child carries it. A
+ * fact, never a filled create line or a question. */
+declare function renderWorkstreamLine({ prefix, open_actions }: Workstream): string;
 /** The line after an update's success while Stale lines remain on the entity. */
 declare function renderStaleReminder({ handles }: {
     handles: string[];
@@ -186,6 +209,20 @@ export declare const ITEMS: {
             description: string | null;
         }) => string;
     };
+    childrenBlock: {
+        label: string;
+        owner: "readHeader";
+        invokeOnly: string;
+        evidence: string;
+        render: typeof renderChildrenBlock;
+    };
+    workstreamLine: {
+        label: string;
+        owner: "readHeader";
+        invokeOnly: string;
+        evidence: string;
+        render: typeof renderWorkstreamLine;
+    };
     sessionsLine: {
         label: string;
         owner: "readHeader";
@@ -360,6 +397,13 @@ export declare const ITEMS: {
         evidence: string;
         text: string;
     };
+    healthProcedure: {
+        label: string;
+        owner: "hafezSkillBody";
+        invokeOnly: string;
+        evidence: string;
+        text: string;
+    };
     batchShape: {
         label: string;
         owner: "hafezSkillBody";

package/dist/surfaces/items.js

@@ -176,6 +176,35 @@ function renderArchivePointer({ slug, entries }) {
         return '';
     return `archive: ${entries} older log ${entries === 1 ? 'entry' : 'entries'} · hafez read ${slug} --archive`;
 }
+/** How many children the header lists; the rest are one overflow line. */
+export const CHILDREN_SHOWN = 5;
+/** The `read` header's children block: the count line (children, open
+ * actions across all of them), one `hafez read` line per child (description,
+ * open count, last-touched day) for the first `CHILDREN_SHOWN`, and the
+ * overflow line naming the query that lists the rest. Children arrive sorted
+ * by last-touched descending. No children: no block. */
+function renderChildrenBlock({ slug, children }) {
+    if (children.length === 0)
+        return '';
+    const open = children.reduce((sum, c) => sum + c.open_actions, 0);
+    const shown = children.slice(0, CHILDREN_SHOWN);
+    const width = Math.max(...shown.map(c => c.slug.length));
+    const lines = [`children: ${children.length} · ${open} open action${open === 1 ? '' : 's'}`];
+    for (const c of shown) {
+        const facts = [c.description, `${c.open_actions} open`, c.last_touched].filter(Boolean).join(' · ');
+        lines.push(`  hafez read ${c.slug.padEnd(width)}  ${facts}`);
+    }
+    const rest = children.length - shown.length;
+    if (rest > 0)
+        lines.push(`  … and ${rest} more · hafez query --parent ${slug}`);
+    return lines.join('\n');
+}
+/** The `read` header's fact line for one unsplit prefix family (#230):
+ * its open-line count and the family, and that no child carries it. A
+ * fact, never a filled create line or a question. */
+function renderWorkstreamLine({ prefix, open_actions }) {
+    return `workstream: ${open_actions} open action${open_actions === 1 ? '' : 's'} with \`${prefix}\`; no child named it`;
+}
 /** The line after an update's success while Stale lines remain on the entity. */
 function renderStaleReminder({ handles }) {
     const n = handles.length;
@@ -193,7 +222,10 @@ function renderUpdateMisuse(input) {
 }
 const CREATE_TYPES = ['project', 'entity'];
 const RELATIONS = ['parent', 'related'];
-const createEntityLine = (name) => `hafez create entity "${name}" --type ${oneOf(CREATE_TYPES)} --description "<one sentence>" --brief "<where things stand>" --add-action "<next step>"`;
+/** The entity create line, one text everywhere: the Block, the skill body and
+ * the `read` miss. `--parent` carries the placement rule in its placeholder
+ * (#226, #230); at a miss with nothing read the agent drops it. */
+const createEntityLine = (name) => `hafez create entity "${name}" --type ${oneOf(CREATE_TYPES)} --parent <slug you read, or its parent> --description "<one sentence>" --brief "<where things stand>" --add-action "<next step>"`;
 const CREATE_LINES = fence([
     createEntityLine('<name>'),
     `hafez create knowledge "<name>" --synthesis "<the insight>" --confidence ${oneOf(CONFIDENCE_LEVELS)} --related <slug>`,
@@ -305,6 +337,20 @@ export const ITEMS = {
          * in brackets when it has one. */
         render: ({ slug, description }) => description ? `${slug} (${description})` : slug,
     },
+    childrenBlock: {
+        label: 'Children block: the Hub\'s children as read lines',
+        owner: 'readHeader',
+        invokeOnly: 'same',
+        evidence: '#230',
+        render: renderChildrenBlock,
+    },
+    workstreamLine: {
+        label: 'Workstream fact line: an unsplit prefix family',
+        owner: 'readHeader',
+        invokeOnly: 'same',
+        evidence: '#230',
+        render: renderWorkstreamLine,
+    },
     sessionsLine: {
         label: 'Sessions line: the look back from an entity',
         owner: 'readHeader',
@@ -320,14 +366,15 @@ export const ITEMS = {
         render: renderArchivePointer,
     },
     writeTriggers: {
-        label: 'Write triggers: work landed, decision made, insight, weighing, "note this"',
+        label: 'Write triggers: work landed, a split, decision made, a lesson, weighing, "note this"',
         owner: 'block',
         invokeOnly: 'absent',
-        evidence: 'M11, M2, never-ask decision #42, decision-record miss #159',
+        evidence: 'M11, M2, never-ask decision #42, decision-record miss #159; placement #226, #229',
         text: place => [
-            '- Work landed (a commit, a merged PR, CI green): update the entity that owns the work. That is the entity you read, unless the work belongs to another: read that one first. The end of its `read` output shows the command.',
-            '- A decision was made: if the repo keeps its own decisions record, write it there now and give Hafez one line that points at it (`hafez update <slug> --log "decision: <one line>, see decisions.md"`). Otherwise it goes in the save\'s `decisions`.',
-            `- An insight emerged that is useful beyond this repo: create a knowledge note. ${place('knowledgeBoundary')}`,
+            '- Work landed (a commit, a merged PR, CI green): update the entity that owns the work. That is the entity you read; the entity you read has a child that owns it: write there; the work belongs to another: read that one first. The end of its `read` output shows the command.',
+            '- A workstream your own actions or the user already name, too big for one action, gets a Child with that name under the entity you read: create it with `--parent`, move its open actions there (one `update` on the parent: `--remove-action` each, `--log "decision: split <child> out, open actions moved"`), and write there from now on.',
+            '- A decision was made: one `decision` log entry, now, on the entity that owns the work. The repo keeps its own decisions record: write it there and the log entry points at it (`hafez update <slug> --log "decision: <one line>, see decisions.md"`).',
+            `- A lesson that holds without this entity: create a knowledge note; what we chose is a decision entry, not a note. ${place('knowledgeBoundary')}`,
             '- The user says "note this" or "record that": write it.',
             `- You are weighing whether something is worth writing: write it, as knowledge with \`--confidence ${CONFIDENCE_LEVELS[0]}\`.`,
         ].join('\n'),
@@ -390,7 +437,7 @@ export const ITEMS = {
         owner: 'block',
         fallback: 'hafezSkillBody',
         invokeOnly: 'via the skill body',
-        evidence: 'fields: kind/name 18, synthesis 16, subtype 15',
+        evidence: 'fields: kind/name 18, synthesis 16, subtype 15; --parent #230',
         text: CREATE_LINES + '\n\nA plan is `--subtype plan` without `--synthesis`. Cannot tell entity from knowledge: `hafez capture "<name>"`.',
         /** The entity create line for one name: what the `read` miss places. */
         render: createEntityLine,
@@ -506,7 +553,7 @@ export const ITEMS = {
             + '\n\n`search` and `query` reach entities and knowledge notes; `--kind all` adds the session notes, `--kind session` lists them alone, newest first. `hafez read <slug> --archive` prints an entity\'s archived log entries.',
     },
     rareOps: {
-        label: 'Rare ops: promote, link, unlink, status, delete, validate',
+        label: 'Rare ops: promote, link, unlink, status, delete, validate, health',
         owner: 'hafezSkillBody',
         invokeOnly: 'same',
         evidence: 'help decision #49; owner decision #43',
@@ -517,8 +564,20 @@ export const ITEMS = {
             `hafez update <slug> --status ${oneOf(ENTITY_STATUSES)}`,
             'hafez delete <slug>',
             'hafez validate',
+            'hafez health',
         ].join('\n'))
-            + `\n\nA plan's status is \`${PLAN_STATUSES.join('|')}\`. \`delete\` removes a knowledge or session note only; an entity is retired with \`--status done\`.`,
+            + `\n\nA plan's status is \`${PLAN_STATUSES.join('|')}\`. \`delete\` removes a knowledge or session note only; an entity is retired with \`--status done\`. \`health\` lists what placement would change and applies nothing.`,
+    },
+    healthProcedure: {
+        label: 'Health procedure: run with --json, propose by kind, apply nothing unconfirmed',
+        owner: 'hafezSkillBody',
+        invokeOnly: 'same',
+        evidence: '#248; health is agent input, the owner never reads the raw report',
+        text: [
+            'A vault check ("check the vault", "clean up the vault", "what has drifted"): run `hafez health --json` and bring back proposals grouped by kind, never the rows. In a session that read an entity, lead with that entity\'s rows; the rest of the vault as counts.',
+            'One line per kind, with the count: the Workstreams to split (a `create entity … --parent` line each, named as the actions name it); the one-way edges and the unlinked mentions as one `hafez batch` of `link` ops, one commit; the restated decisions and the leakage pairs as a short list for the user to judge, nothing proposed.',
+            'Apply nothing until the user confirms a kind, not even a `link` line that looks safe; then one `batch` per kind.',
+        ].join('\n'),
     },
     batchShape: {
         label: 'Batch shape',

package/dist/surfaces/surfaces.js

@@ -40,7 +40,7 @@ export const SURFACES = {
     },
     hafezSkillDescription: {
         label: '`hafez` skill description',
-        compose: () => 'Hafez vault: the less common operations and the tool itself. Use when the user asks what is in the vault ("what am I working on?", "what\'s stale?"), wants to promote, link, unlink, delete, change a status or validate, or wants to update or reconfigure Hafez ("upgrade hafez", "set up hafez"). Also the reference to read when no Hafez block is in your instructions.',
+        compose: () => 'Hafez vault: the less common operations and the tool itself. Use when the user asks what is in the vault ("what am I working on?", "what\'s stale?"), wants to promote, link, unlink, delete, change a status or validate, asks to check the vault or clean it up, or wants to update or reconfigure Hafez ("upgrade hafez", "set up hafez"). Also the reference to read when no Hafez block is in your instructions.',
     },
     hafezSkillBody: {
         label: '`hafez` skill body',
@@ -68,6 +68,8 @@ export const SURFACES = {
             '',
             place('rareOps'),
             '',
+            place('healthProcedure'),
+            '',
             `${place('batchShape')} Machine-readable shape of any op: \`hafez schema <op>\`, with \`--examples\` for a sample.`,
             '',
             '## The tool itself',

package/dist/templates.d.ts

@@ -11,4 +11,6 @@ export declare function knowledgeBodyTemplate(subtype?: KnowledgeSubtype, fields
  * every other section set, and this renders it. */
 export declare function sessionBodyTemplate(fields?: {
     synthesis?: string;
+    decisions?: string[];
+    entities_touched?: string[];
 }): string;

package/dist/templates.js

@@ -35,5 +35,10 @@ export function knowledgeBodyTemplate(subtype, fields) {
  * structural for Document splitting — so the list lives in contracts with
  * every other section set, and this renders it. */
 export function sessionBodyTemplate(fields) {
-    return render([...SESSION_SECTIONS], { Summary: fields?.synthesis });
+    const bullets = (items) => items?.map(i => `- ${i}`).join('\n');
+    return render([...SESSION_SECTIONS], {
+        Summary: fields?.synthesis,
+        'Entities Touched': bullets(fields?.entities_touched?.map(slug => `[[${slug}]]`)),
+        Decisions: bullets(fields?.decisions),
+    });
 }

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,6 +9,10 @@ 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
@@ -208,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;
@@ -267,6 +279,95 @@ export interface ValidationReport {
     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' | 'session';
@@ -308,6 +409,48 @@ export interface ChangelogEntry {
     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;
@@ -342,7 +485,7 @@ export type BatchOperation = {
     op: 'create';
     kind: 'session';
     name: string;
-    fields?: CreateKnowledgeFields;
+    fields?: CreateSessionFields;
 } | {
     op: 'capture';
     name: string;
@@ -395,8 +538,10 @@ 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,
@@ -411,12 +556,23 @@ export interface Journal {
         pushed: boolean;
         remote: boolean;
     }>;
-    /** History-derived changelog for the indexed dirs since a date. Empty when
-     * the repo has no commits; any other git failure throws `GIT_READ_FAILED`. */
-    changelog(since: string): Promise<ChangelogEntry[]>;
+    /** 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;
@@ -473,10 +629,24 @@ export interface Hafez {
      * archive is reached from its entity on purpose, never found by search. */
     archive(slug: string): Promise<string | null>;
     validate(): Promise<ValidationReport>;
+    /** 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. */

package/dist/vault.d.ts

@@ -1,6 +1,6 @@
-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';
+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>;
@@ -22,6 +22,13 @@ export declare function classifyIndexedRelPath(relPath: string): {
     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
  * invisible by construction) and dotfile-free: dotfile slugs are rejected by
  * resolveFilePath, so listing them would surface files no operation can reach. */