hafez 1.3.0 → 2.0.0

package/dist/digest.js

@@ -1,9 +1,13 @@
 // src/digest.ts
+import { createHash } from 'crypto';
 import { z } from 'zod';
+import { HafezError } from './types.js';
+import { detectAgent } from './harness.js';
+import { ITEMS } from './surfaces/items.js';
 // --- Schema ---
 export const DigestInputSchema = z.object({
     entities_touched: z.array(z.string())
-        .describe('Slugs of entities worked on. Each gets a session log entry; the session note links them all. Unknown slugs warn on stderr and are omitted.'),
+        .describe('Slugs of entities worked on. Each gets a session log entry; the session note links them all. An unknown slug fails the digest and is named.'),
     decisions: z.array(z.string())
         .describe('Key decisions made this session (may be empty). Recorded in the session note.')
         .default([]),
@@ -12,8 +16,8 @@ export const DigestInputSchema = z.object({
     session_date: z.string().regex(/^\d{4}-\d{2}-\d{2}$/, 'Must be YYYY-MM-DD')
         .describe('Session date, YYYY-MM-DD.'),
     agent: z.string()
-        .describe('Agent identifier recorded in session logs.')
-        .default('claude'),
+        .describe('Agent identifier recorded in session logs. Detected from the Harness when absent.')
+        .optional(),
 });
 /**
  * Validate and parse raw digest input from stdin.
@@ -39,27 +43,32 @@ export function parseDigestInput(raw) {
 /**
  * Convert session context into a hafez batch payload.
  * Pure function — no file I/O, no vault access.
- * Unknown slugs in entities_touched are silently omitted (caller should warn).
+ * An unknown slug in entities_touched is a NOT_FOUND naming it (and only the
+ * unknown ones), never a session log that points nowhere. A knowledge slug is
+ * known: the note links it, but a session log is entity-only.
  */
-export function digest(input, existingSlugs, now = new Date()) {
+export function digest(input, entitySlugs, knowledgeSlugs = new Set()) {
+    const touched = [...new Set(input.entities_touched)];
+    const unknown = touched.filter(s => !entitySlugs.has(s) && !knowledgeSlugs.has(s));
+    if (unknown.length > 0)
+        throw new HafezError('NOT_FOUND', ITEMS.unknownSlugAtSave.render(unknown));
     const ops = [];
-    // 1. Session log updates for each known slug
-    const knownTouched = input.entities_touched.filter(s => existingSlugs.has(s));
-    for (const slug of knownTouched) {
+    const agent = input.agent || detectAgent();
+    // 1. Session log updates for each touched entity
+    for (const slug of touched.filter(s => entitySlugs.has(s))) {
         const sessionLogSummary = buildSessionLogSummary(input);
         const fields = {
             session_log: {
                 type: 'progress',
                 summary: sessionLogSummary,
-                agent: input.agent,
+                agent,
             },
         };
         ops.push({ op: 'update', slug, fields });
     }
-    // 2. Session note — built from known slugs only, so unknown slugs never
-    //    leak into the note body (the schema promises they are omitted).
-    const noteBody = buildSessionNoteBody(input, knownTouched);
-    const related = knownTouched;
+    // 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.
     const noteFields = {
@@ -67,7 +76,9 @@ export function digest(input, existingSlugs, now = new Date()) {
         'session-date': input.session_date,
         ...(related.length > 0 ? { related } : {}),
     };
-    const noteName = `Session ${input.session_date} ${now.toISOString().slice(11, 19)}`;
+    // 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)}`;
     ops.push({ op: 'create', kind: 'session', name: noteName, fields: noteFields });
     return ops;
 }
@@ -79,7 +90,7 @@ function buildSessionLogSummary(input) {
     }
     return parts.join(' | ');
 }
-function buildSessionNoteBody(input, knownTouched) {
+function buildSessionNoteBody(input, touched) {
     const lines = [input.narrative.trim()];
     if (input.decisions.length > 0) {
         lines.push('');
@@ -88,9 +99,9 @@ function buildSessionNoteBody(input, knownTouched) {
             lines.push(`- ${d}`);
         }
     }
-    if (knownTouched.length > 0) {
+    if (touched.length > 0) {
         lines.push('');
-        lines.push(`**Entities touched:** ${knownTouched.join(', ')}`);
+        lines.push(`**Entities touched:** ${touched.join(', ')}`);
     }
     return lines.join('\n');
 }

package/dist/document.d.ts

@@ -1,96 +1,151 @@
-import type { SessionLogEntry, SessionLogType } from './types.js';
-/**
- * Known structural section headings in Hafez entities, knowledge notes, and
- * session files. Derived from contracts.ts (defaultSections + optionalSections
- * + session sections) plus auto-generated sections not tracked in contracts
- * (Related). Only these are treated as section boundaries. Any other `## `
- * heading inside section content (e.g. in a brief or session log) is
- * preserved as-is.
- */
-export declare const STRUCTURAL_SECTIONS: Set<string>;
-/**
- * Find the next structural `## Heading` boundary after a given position.
- * Skips `## ` headings that are not known structural sections (content headings).
- * Returns the index of the `\n` before the `## `, or -1 if no structural heading found.
- */
-export declare function findNextStructuralHeading(body: string, from: number): number;
-/**
- * Find a ## Heading section and its content.
- * Returns { start, headingEnd, end, content } or null if not found.
- * Matches heading exactly (e.g. "## Brief" won't match "## Briefing").
- * Trailing whitespace on the heading line is tolerated — the splitter's
- * boundary tokenizer trims headings, so anything it treats as a boundary
- * must also be findable here (a hand-edited `## Session Log ` otherwise
- * gets a duplicate section and archival never fires).
- * Only treats known structural headings as section boundaries -- content
- * inside a section may contain arbitrary `## ` headings without corruption.
- */
-export declare function findSection(body: string, heading: string): {
-    start: number;
-    headingEnd: number;
-    end: number;
-    content: string;
-} | null;
-export interface DocSection {
-    heading: string;
-    content: string;
-}
-/**
- * Split a body into preamble + structural sections. Non-structural `## `
- * headings stay inside the enclosing section's content — sections are
- * atomic units of authored content, never split at user headings.
- * Headings and content come back trimmed; reassemble with
- * `## ${heading}\n\n${content}` joined by blank lines.
- */
-export declare function splitStructural(body: string): {
-    preamble: string;
-    sections: DocSection[];
+import { type SessionLogEntry, type SessionLogType } from './types.js';
+/** 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. */
+export declare function actionAdded(text: string): string | null;
+/** Stamp an action with its added date; text that already ends in a stamp is
+ * returned as is, so a carried-over line is never double-stamped. */
+export declare function stampAction(text: string, day: string): string;
+/** One checkbox line of Next Actions as a reader sees it: unstamped text, and
+ * a Handle and added day (null when undated) when the line is open. */
+export type ActionItem = {
+    handle: string;
+    text: string;
+    added: string | null;
+} | {
+    handle?: undefined;
+    text: string;
 };
-/**
- * Replace a structural section's content, or create the section: before
- * `insertBefore` when that section exists, at EOF otherwise.
- */
-export declare function setSection(body: string, heading: string, content: string, insertBefore?: string): string;
-/** Append content at the end of a structural section (creating it at EOF if absent). */
-export declare function appendToSection(body: string, heading: string, content: string): string;
-/** Insert a formatted session-log entry newest-first (creating the section at EOF if absent). */
-export declare function prependSessionLogEntry(body: string, entry: string): string;
-/** Body up to the real Session Log section — the `summary` read depth. */
-export declare function bodyBeforeSessionLog(body: string): string;
+/** The open action a query named: its line's position within the Next
+ * Actions section, and its unstamped text. Editing by position rather than
+ * re-matching the text keeps a Handle-named line unambiguous when its text
+ * is a substring of another line's, or a duplicate of one. */
+export interface ActionMatch {
+    line: number;
+    text: string;
+}
 export declare function parseSessionLogHeading(line: string): {
     date: string;
     agent: string;
     type: SessionLogType;
 } | null;
 export declare function formatSessionLogEntry(entry: SessionLogEntry): string;
-/** Entries inside the real Session Log section only — entry-shaped lines
- * elsewhere in the body (e.g. quoted in a Brief) do not count. */
-export declare function countSessionLogEntries(body: string): number;
+/**
+ * Split a Session Log section's content into raw entry blocks, each beginning
+ * with a parseable entry heading. Non-entry text before the first heading is
+ * not an entry and is dropped. Document owns entry block splitting — merge's
+ * dedup/sort policy stays in merge.ts.
+ */
+export declare function splitLogEntries(content: string): string[];
+export declare function firstNonEmptyLine(s: string | null | undefined): string;
+/** The one wiki-link syntax the vault recognizes: [[slug]] or
+ * [[slug|display text]] — slug in group 1, display text in group 2.
+ * Padding inside the brackets is Obsidian-idiomatic ([[ slug ]], [[slug | Label]])
+ * and is absorbed by the pattern, so both captures come out already trimmed —
+ * 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;
+/** 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
+ * can legitimately carry sections outside its current type's contract (a
+ * promote race merged in a capture's Notes, a plan-shaped note never had its
+ * subtype persisted, a hand edit added Open Questions to a plain entity), and
+ * a narrower binding demotes those headings to non-structural text that the
+ * next section rewrite silently deletes. The kind-level union makes every
+ * same-kind heading a boundary, so no same-kind section is ever swallowed;
+ * the cost is that a same-kind heading quoted at line start inside a section
+ * strands as its own section on rewrite — visible and recoverable, unlike
+ * deletion. Cross-KIND headings (a session-only ## Decisions quoted in an
+ * entity Brief) are still not boundaries. */
+export interface DocContext {
+    kind: 'entity' | 'knowledge' | 'session';
+}
+/** The structural set a context binds — exposed for introspection and the
+ * contract-coverage tests; runtime consumers go through documentFor. */
+export declare function structuralSectionsFor(ctx: DocContext): ReadonlySet<string>;
+/** The Document operations bound to one file's structural section set. */
+export declare function documentFor(ctx: DocContext): Doc;
+/** Bind from a parsed vault file — kind from Layout. */
+export declare function documentForFile(parsed: {
+    kind: 'entity' | 'knowledge' | 'session';
+}): Doc;
+export interface DocSection {
+    heading: string;
+    content: string;
+}
+export interface Doc {
+    findNextStructuralHeading(body: string, from: number): number;
+    findSection(body: string, heading: string): {
+        start: number;
+        headingEnd: number;
+        end: number;
+        content: string;
+    } | null;
+    splitStructural(body: string): {
+        preamble: string;
+        sections: DocSection[];
+    };
+    setSection(body: string, heading: string, content: string, insertBefore?: string): string;
+    appendToSection(body: string, heading: string, content: string): string;
+    renameSection(body: string, from: string, to: string): string;
+    ensureSection(body: string, heading: string, opts?: {
+        after?: string;
+    }): string;
+    prependSessionLogEntry(body: string, entry: string): string;
+    bodyBeforeSessionLog(body: string): string;
+    countSessionLogEntries(body: string): number;
+    parseSessionLog(body: string): Array<{
+        date: string;
+        agent: string;
+        type: SessionLogType;
+        summary: string;
+    }>;
+    extractOldestSessionLogEntry(body: string): {
+        entry: string;
+        remaining: string;
+    } | null;
+    getBrief(body: string): string | null;
+    setBrief(body: string, content: string): string;
+    removeBrief(body: string): string;
+    getNextActions(body: string): string[];
+    getActionItems(body: string): ActionItem[];
+    renderActionHandles(body: string, mark?: (added: string | null) => string): string;
+    addNextAction(body: string, action: string): string;
+    matchNextAction(body: string, query: string): ActionMatch;
+    completeNextAction(body: string, action: string | ActionMatch): {
+        matched: string;
+        body: string;
+    };
+    removeNextAction(body: string, action: string | ActionMatch): {
+        matched: string;
+        line: string;
+        body: string;
+    };
+    actionLines(body: string): string[];
+    extractOldestTickedActions(body: string, keep: number): {
+        lines: string[];
+        body: string;
+    };
+    pruneNextActions(body: string): string;
+    clearNextActions(body: string): string;
+    stripNextActionStamps(body: string): string;
+    syncRelatedSection(body: string, frontmatter: {
+        parent?: string;
+        related?: string[];
+    }): string;
+}
+export declare function getBrief(body: string): string | null;
+export declare function getNextActions(body: string): string[];
+export declare function getActionItems(body: string): ActionItem[];
+export declare function renderActionHandles(body: string, mark?: (added: string | null) => string): string;
 export declare function parseSessionLog(body: string): Array<{
     date: string;
     agent: string;
     type: SessionLogType;
     summary: string;
 }>;
-export declare function extractOldestSessionLogEntry(body: string): {
-    entry: string;
-    remaining: string;
-} | null;
-export declare function getBrief(body: string): string | null;
-export declare function setBrief(body: string, content: string): string;
-export declare function removeBrief(body: string): string;
-export declare function getNextActions(body: string): string[];
-export declare function addNextAction(body: string, action: string): string;
-export declare function completeNextAction(body: string, query: string): {
-    matched: string;
-    body: string;
-};
-export declare function removeNextAction(body: string, query: string): {
-    matched: string;
-    body: string;
-};
-export declare function clearNextActions(body: string): string;
-export declare function firstNonEmptyLine(s: string | null | undefined): string;
+export declare function countSessionLogEntries(body: string): number;
 /**
  * One-line summary for a doc: frontmatter description first, then the first
  * non-empty line of the kind's primary section (entity: Brief; knowledge:
@@ -98,11 +153,3 @@ export declare function firstNonEmptyLine(s: string | null | undefined): string;
  * Shared by the vault index and the OKF export so the two surfaces agree.
  */
 export declare function deriveSummary(kind: 'entity' | 'knowledge' | 'session', fm: Record<string, any>, body: string): string;
-/** The one wiki-link syntax the vault recognizes: [[slug]] or
- * [[slug|display text]] — slug in group 1, display text in group 2.
- * Non-global — wrap with `new RegExp(WIKI_LINK_RE.source, 'g')` for iteration. */
-export declare const WIKI_LINK_RE: RegExp;
-export declare function syncRelatedSection(body: string, frontmatter: {
-    parent?: string;
-    related?: string[];
-}): string;