hafez 1.3.0 → 2.0.0

package/dist/contracts.js

@@ -1,24 +1,48 @@
+// --- Canonical enum tuples (single source of truth) ---
+// Every consumer (file validators, the Op Spec table, help renderer, and the
+// enum unions in types.ts) imports these — no other file may declare local
+// copies, and the contracts below are built out of them rather than beside
+// them.
+export const ENTITY_TYPES = ['capture', 'entity', 'project'];
+export const ENTITY_STATUSES = ['active', 'paused', 'done'];
+export const SESSION_LOG_TYPES = ['progress', 'decision', 'blocker', 'research'];
+export const CONFIDENCE_LEVELS = ['observation', 'pattern', 'principle'];
+// 'insight' is the subtype (frontmatter classification), 'Synthesis' is the section heading.
+// The rename was insight→synthesis for the section/field only; the subtype stays 'insight'.
+export const VALID_SUBTYPES = ['insight', 'plan'];
+/** The item frontmatter contract, shared by all three item types — they
+ * differ in sections and lifecycle, never in which fields are mandatory.
+ * schema.validateEntityFrontmatter enforces exactly this list (parity test in
+ * tests/contracts.test.ts). */
+const ITEM_REQUIRED = ['name', 'type', 'status', 'created', 'last-touched'];
+/** Optional frontmatter for the types that can sit in a hierarchy. A capture
+ * has not been triaged yet, so it carries neither links nor staleness. */
+const ITEM_OPTIONAL = ['domain', 'parent', 'related', 'tags', 'staleness-days'];
 const CAPTURE = {
     type: 'capture',
     description: 'Quick capture. A link, a thought, a bug report. No structure required — just get it in.',
     kind: 'item',
-    requiredFields: ['name', 'type', 'status', 'created', 'last-touched'],
+    requiredFields: ITEM_REQUIRED,
     optionalFields: ['domain', 'tags'],
-    validStatuses: ['active', 'done'],
+    // A capture is triage-stage: it is either open or dealt with, never paused.
+    validStatuses: ENTITY_STATUSES.filter(s => s !== 'paused'),
     defaultSections: ['Notes'],
     // Brief/Next Actions: the CLI never type-gated setBrief/addNextAction, so captures
     // carrying a delivery brief and actions are established practice — the contract
-    // follows observed behaviour (decided 2026-07-19).
-    optionalSections: ['Session Log', 'Brief', 'Next Actions'],
+    // follows observed behaviour (decided 2026-07-19). Current State likewise:
+    // update --current-state is kind-gated, not type-gated, so captures can carry
+    // it — omitting it here made the heading non-structural under the per-type
+    // Document binding and a later Brief rewrite silently deleted the section.
+    optionalSections: ['Session Log', 'Brief', 'Next Actions', 'Current State'],
     canPromoteTo: ['entity', 'project', 'knowledge'],
 };
 const ENTITY = {
     type: 'entity',
     description: 'Tracked work with substance. A bug, feature, decision, or task. The atomic unit of work.',
     kind: 'item',
-    requiredFields: ['name', 'type', 'status', 'created', 'last-touched'],
-    optionalFields: ['domain', 'parent', 'related', 'tags', 'staleness-days'],
-    validStatuses: ['active', 'paused', 'done'],
+    requiredFields: ITEM_REQUIRED,
+    optionalFields: ITEM_OPTIONAL,
+    validStatuses: [...ENTITY_STATUSES],
     defaultSections: ['Context', 'Session Log'],
     optionalSections: ['Brief', 'Next Actions', 'Current State'],
     canPromoteTo: ['project'],
@@ -27,9 +51,9 @@ const PROJECT = {
     type: 'project',
     description: 'Scoped effort with goals and deliverables. Can have children. Can be finite or perpetual.',
     kind: 'item',
-    requiredFields: ['name', 'type', 'status', 'created', 'last-touched'],
-    optionalFields: ['domain', 'parent', 'related', 'tags', 'staleness-days'],
-    validStatuses: ['active', 'paused', 'done'],
+    requiredFields: ITEM_REQUIRED,
+    optionalFields: ITEM_OPTIONAL,
+    validStatuses: [...ENTITY_STATUSES],
     defaultSections: ['Purpose', 'Goals', 'Session Log'],
     optionalSections: ['Brief', 'Next Actions', 'Current State', 'Open Questions'],
     canPromoteTo: [],
@@ -58,22 +82,26 @@ export function getContract(type) {
         throw new Error(`Unknown type: ${type}. Valid types: ${Object.keys(CONTRACT_MAP).join(', ')}`);
     return contract;
 }
-export function hasCapability(type, section) {
+/** Every section a type's contract declares, default and optional alike —
+ * the one place the two lists are concatenated (sectionsFor and hasCapability
+ * both answer from it). */
+function contractSections(type) {
     const contract = getContract(type);
-    return contract.defaultSections.includes(section) || contract.optionalSections.includes(section);
+    return [...contract.defaultSections, ...contract.optionalSections];
 }
-// --- Canonical enum tuples (single source of truth) ---
-// Every consumer (file validators, the Op Spec table, help renderer) imports
-// these — no other file may declare local copies.
-export const ENTITY_TYPES = ['capture', 'entity', 'project'];
-export const ENTITY_STATUSES = ['active', 'paused', 'done'];
-export const SESSION_LOG_TYPES = ['progress', 'decision', 'blocker', 'research'];
-export const CONFIDENCE_LEVELS = ['observation', 'pattern', 'principle'];
-// 'insight' is the subtype (frontmatter classification), 'Synthesis' is the section heading.
-// The rename was insight→synthesis for the section/field only; the subtype stays 'insight'.
-export const VALID_SUBTYPES = ['insight', 'plan'];
+export function hasCapability(type, section) {
+    return contractSections(type).includes(section);
+}
+/** A knowledge note with no persisted subtype is an insight — the one place
+ * that default lives. Every consumer (templates, index rows, exports) reads
+ * it from here so classification can't drift between surfaces. */
+export const DEFAULT_KNOWLEDGE_SUBTYPE = 'insight';
 // --- Alias table ---
-// Declared-alias fields that parseBatchInput normalizes to their canonical name.
+// Declared-alias fields, keyed by the op path they may appear on and mapped to
+// their canonical name. The Op Spec layer (normalizeAliases in batch-ops.ts)
+// normalizes them once, before validation, so every entry point applies the same
+// canonical op; an op path absent from this table (create.entity.fields.insight)
+// is the kind gate — the strict shape rejects the alias there.
 // schema-introspect cannot infer these from Zod alone (both are declared .optional()),
 // so rendering code reads this table to strip aliased keys from user-facing output.
 export const ALIAS_KEYS = {
@@ -91,3 +119,100 @@ export const APPEND_ONLY_SECTIONS = new Set(['Evidence', 'Sources']);
 /** Session-file sections. Sessions have no TypeContract (they are not typed
  * entities), but their headings are still structural for Document splitting. */
 export const SESSION_SECTIONS = ['Summary', 'Entities Touched', 'Decisions'];
+/** Statuses a plan-subtype knowledge note may carry. Plans are tracked work
+ * with a lifecycle; the file validator and the mutation gate read this one
+ * tuple so they cannot drift. */
+export const PLAN_STATUSES = ['active', 'done'];
+/** Statuses by knowledge subtype. An empty list means `status` is not part of
+ * that subtype's contract at all — mutations setting it are rejected. */
+export const SUBTYPE_STATUSES = {
+    insight: [],
+    plan: PLAN_STATUSES,
+};
+/** Sections a document of this shape can carry — the one answer to "would
+ * text written into section X survive on this document?". */
+export function sectionsFor(target) {
+    if (target.kind === 'knowledge') {
+        return [...SUBTYPE_SECTIONS[target.subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE]];
+    }
+    return contractSections(target.type);
+}
+/** Statuses this document may carry. Empty ⇒ `status` is not a field of its
+ * contract, so setting it is a validation error. */
+export function statusesFor(target) {
+    return target.kind === 'knowledge'
+        ? SUBTYPE_STATUSES[target.subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE]
+        : getContract(target.type).validStatuses;
+}
+/** Create-op fields that write their text into a named body section. The
+ * chosen template decides whether that section exists; when it doesn't, the
+ * text has nowhere to land, so the op is rejected (see `unreachableFields`).
+ * Update-op content fields are absent on purpose — `setSection` /
+ * `appendToSection` create a missing section, so update never loses text. */
+export const CREATE_FIELD_SECTIONS = {
+    purpose: 'Purpose',
+    notes: 'Notes',
+    brief: 'Brief',
+    add_action: 'Next Actions',
+    add_actions: 'Next Actions',
+    synthesis: 'Synthesis',
+};
+/** Fields present in `fields` whose target section this document cannot hold.
+ * Policy is reject-never-route: text is never silently dropped and never
+ * redirected into a section the caller did not name. */
+export function unreachableFields(target, fields) {
+    const available = new Set(sectionsFor(target));
+    return Object.entries(CREATE_FIELD_SECTIONS)
+        .filter(([field, section]) => fields[field] !== undefined && !available.has(section))
+        .map(([field, section]) => ({ field, section }));
+}
+/** Human label for a target, used in every gate's error text. */
+export function describeTarget(target) {
+    return target.kind === 'entity'
+        ? `type '${target.type}'`
+        : `knowledge subtype '${target.subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE}'`;
+}
+export function footerForm(target) {
+    if (target.kind === 'knowledge')
+        return target.subtype ?? DEFAULT_KNOWLEDGE_SUBTYPE;
+    return target.type === 'capture' ? 'capture' : 'entity';
+}
+/** The update fields each Footer names, in the order it names them. Every
+ * other field that contract's update accepts is in WRITE_LINE_OMITS with its
+ * reason; drift check 3 (tests/read-footer.test.ts) holds the two together
+ * against the Op Spec update shape and the kind gate. */
+export const WRITE_LINE_FIELDS = {
+    entity: ['session_log', 'complete_action', 'remove_action', 'add_actions', 'brief', 'current_state', 'related', 'parent'],
+    insight: ['add_evidence', 'add_source', 'synthesis', 'confidence', 'domain', 'related'],
+    plan: ['status', 'domain', 'related'],
+};
+const SET_AT_CREATE = 'set at create, rarely rewritten; `hafez schema update` has it';
+const INSIGHT_ALIAS = 'an alias of synthesis';
+const PLAN_BODY = 'a plan\'s body is Goal, Steps and Dependencies, which no op writes';
+/** Update fields a contract accepts that its Footer leaves out, and why. */
+export const WRITE_LINE_OMITS = {
+    entity: {
+        status: 'a lifecycle change, not a write-back: the `hafez` skill\'s rare ops carry the status line',
+        agent: 'detected from the Harness; the override is never shown',
+        add_action: 'the one-line form of add_actions, written by the same flag',
+        clear_actions: 'drops lines unseen; the Footer drops one line by its Handle',
+        description: SET_AT_CREATE,
+        resource: SET_AT_CREATE,
+        domain: SET_AT_CREATE,
+        tags: SET_AT_CREATE,
+    },
+    insight: {
+        insight: INSIGHT_ALIAS,
+        description: SET_AT_CREATE,
+        tags: SET_AT_CREATE,
+    },
+    plan: {
+        synthesis: PLAN_BODY,
+        add_evidence: PLAN_BODY,
+        add_source: PLAN_BODY,
+        insight: INSIGHT_ALIAS,
+        confidence: 'an insight matures by confidence; a plan moves by status',
+        description: SET_AT_CREATE,
+        tags: SET_AT_CREATE,
+    },
+};

package/dist/dates.d.ts

@@ -0,0 +1,10 @@
+/** The local calendar day as YYYY-MM-DD. The single source of "today". */
+export declare function localDay(d?: Date): string;
+/**
+ * Bare YYYY-MM-DD → local midnight, for git's approxidate. A date-only
+ * `--since` is otherwise filled with the *current* time of day ("since right
+ * now"), and any explicit instant must anchor to the same local day boundary
+ * the stamps and query comparisons use. Relative forms (`7.days.ago`) are
+ * already local and pass through untouched.
+ */
+export declare function normalizeSinceDate(since: string): string;

package/dist/dates.js

@@ -0,0 +1,27 @@
+// src/dates.ts
+// The vault's one calendar-day convention: the LOCAL day.
+//
+// A hafez vault is personal — "today" means the user's today, so every
+// surface that names a day (created / last-touched / session-log stamping,
+// the dates `query --since/--before` compare against, and the `--since` the
+// changelog hands to git) resolves to the local calendar day. Deriving
+// stamps from UTC while comparing against local-midnight boundaries made the
+// same date mean different days: west of UTC after ~13:00 local, a fresh
+// entity was stamped with tomorrow.
+function pad(n) {
+    return String(n).padStart(2, '0');
+}
+/** The local calendar day as YYYY-MM-DD. The single source of "today". */
+export function localDay(d = new Date()) {
+    return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
+}
+/**
+ * Bare YYYY-MM-DD → local midnight, for git's approxidate. A date-only
+ * `--since` is otherwise filled with the *current* time of day ("since right
+ * now"), and any explicit instant must anchor to the same local day boundary
+ * the stamps and query comparisons use. Relative forms (`7.days.ago`) are
+ * already local and pass through untouched.
+ */
+export function normalizeSinceDate(since) {
+    return /^\d{4}-\d{2}-\d{2}$/.test(since) ? `${since}T00:00:00` : since;
+}

package/dist/db.d.ts

@@ -1,5 +1,6 @@
-import type { SearchResult, VaultStats } from './types.js';
-export declare const SCHEMA_VERSION = "7";
+import { type VaultIndexRow } from './knowledge-index.js';
+import type { SearchResult, VaultStats, QueryResult, KnowledgeQueryResult, UnifiedResult, EntityQueryOpts, KnowledgeQueryOpts, UnifiedQueryOpts, SortField } from './types.js';
+export declare const SCHEMA_VERSION = "11";
 interface IndexItem {
     slug: string;
     kind: 'entity' | 'knowledge';
@@ -38,7 +39,29 @@ export interface HafezIndex {
     queryItems(opts: QueryOpts): IndexQueryResult;
     search(query: string, kind?: 'entity' | 'knowledge' | 'all'): SearchResult[];
     getStats(): VaultStats;
+    /** Every indexed document, in the shape index.md is rendered from. */
+    indexEntries(): VaultIndexRow[];
     close(): void;
+    queryEntities(opts?: EntityQueryOpts): {
+        items: QueryResult[];
+        total: number;
+    };
+    queryChildren(parentSlug: string): {
+        items: QueryResult[];
+        total: number;
+    };
+    queryRelatedTo(slug: string, relation?: string): {
+        items: UnifiedResult[];
+        total: number;
+    };
+    queryKnowledge(opts?: KnowledgeQueryOpts): {
+        items: KnowledgeQueryResult[];
+        total: number;
+    };
+    queryUnified(opts?: UnifiedQueryOpts): {
+        items: UnifiedResult[];
+        total: number;
+    };
 }
 export interface QueryOpts {
     kind?: 'entity' | 'knowledge' | 'all';
@@ -61,8 +84,23 @@ export interface QueryOpts {
     limit?: number;
     offset?: number;
 }
+/** @internal */
+export declare function __setAfterScanHook(fn: (() => void) | null): void;
 export declare function createIndex(vaultPath: string): HafezIndex;
 export declare function createIndex(vaultPath: string, opts: {
     readonly: true;
 }): HafezIndex | null;
+/** Opts a branch cannot map into SQL. Declared per branch and rejected on
+ * sight: the CLI has rejected these since 43124ba, but the rule lived only
+ * there, so a library caller got the silent drop the CLI had already closed.
+ * Asserted against the CLI's flag matrix in query-surface.test.ts. */
+export declare const ENTITY_ONLY_OPTS: readonly ["filter", "type", "parent"];
+export declare const KNOWLEDGE_ONLY_OPTS: readonly ["confidence", "subtype"];
+/** Every opt any branch might carry, flattened. Only the unified read uses it,
+ * and only to check: the checks must see an opt the caller's own type forbids,
+ * because an untyped caller can still send it. */
+export type UnmappableCheckOpts = Omit<EntityQueryOpts, 'sort_by'> & Omit<KnowledgeQueryOpts, 'sort_by'> & {
+    kind?: 'entity' | 'knowledge' | 'all';
+    sort_by?: SortField;
+};
 export {};