hafez 1.3.0 → 1.4.0

package/dist/batch-ops.js

@@ -2,9 +2,13 @@
 // The Op Spec (see CONTEXT.md): one table defining every batch operation —
 // shape (Zod), semantic check, description, and example hints — from which
 // validation, error text, and schema introspection all derive. Adding an op
-// means adding one entry here.
+// means one entry here plus one arm in the Apply table (src/apply.ts), which
+// the compiler enforces: the arm table is keyed by this table's names.
+//
+// Every semantic gate lives here and runs exactly once, in the validate phase.
+// Apply assumes the payload it receives passed these checks.
 import { z } from 'zod';
-import { ENTITY_TYPES, ENTITY_STATUSES, SESSION_LOG_TYPES, CONFIDENCE_LEVELS, VALID_SUBTYPES, getContract, } from './contracts.js';
+import { ALIAS_KEYS, ENTITY_TYPES, ENTITY_STATUSES, SESSION_LOG_TYPES, CONFIDENCE_LEVELS, VALID_SUBTYPES, PLAN_STATUSES, getContract, } from './contracts.js';
 import { slugify } from './vault.js';
 import { HafezError } from './types.js';
 // --- Shapes ---
@@ -19,15 +23,29 @@ export const SessionLogSchema = z.object({
     body: z.string().optional(),
     agent: z.string(),
 }).strict();
+// Body-section text must have text after trimming. An empty or whitespace-only
+// value (an agent expanding an unset variable) used to sail through the shape —
+// on the action/evidence fields it was dropped by a truthiness guard in apply
+// (exit 0, nothing on disk); on the section-setting fields below it was worse,
+// because apply trusts the validate phase and `setSection(body, 'Synthesis',
+// '')` wipes what was already there. Same false-success class the CLI loop
+// closed for the enum flags, once silent and once destructive.
+//
+// The rule: every non-nullable string field that writes body-section text is
+// nonEmptyText. The nullable ones (update's brief/description/resource) are
+// excluded by construction — null is their documented clear signal, and the
+// CLI maps `--brief ""` to it. Trimming also keeps accidental padding out of
+// stored text.
+const nonEmptyText = z.string().trim().min(1, 'must contain text — an empty value is rejected, never silently dropped');
 export const UpdateFieldsSchema = z.object({
     status: z.enum([...ENTITY_STATUSES]).optional(),
-    current_state: z.string().optional(),
+    current_state: nonEmptyText.optional(),
     session_log: SessionLogSchema.optional(),
     brief: z.string().nullable().optional(),
-    add_action: z.string().optional(),
-    add_actions: z.array(z.string()).optional(),
-    complete_action: z.string().optional(),
-    remove_action: z.string().optional(),
+    add_action: nonEmptyText.optional(),
+    add_actions: z.array(nonEmptyText).optional(),
+    complete_action: nonEmptyText.optional(),
+    remove_action: nonEmptyText.optional(),
     clear_actions: z.boolean().optional(),
     // Knowledge metadata
     description: z.string().nullable().optional(),
@@ -36,28 +54,31 @@ export const UpdateFieldsSchema = z.object({
     confidence: z.enum([...CONFIDENCE_LEVELS]).optional(),
     tags: z.array(z.string()).optional(),
     related: z.array(z.string()).optional(),
-    synthesis: z.string().optional(),
-    insight: z.string().optional(), // alias for synthesis (normalized in parseBatchInput)
-    add_evidence: z.string().optional(),
-    add_source: z.string().optional(),
+    synthesis: nonEmptyText.optional(),
+    insight: nonEmptyText.optional(), // alias for synthesis (normalized by normalizeAliases)
+    add_evidence: nonEmptyText.optional(),
+    add_source: nonEmptyText.optional(),
 }).strict();
 export const CreateEntityFieldsSchema = z.object({
     type: z.enum([...ENTITY_TYPES]),
-    purpose: z.string().optional(),
+    purpose: nonEmptyText.optional(),
     description: z.string().optional(),
     resource: z.string().optional(),
     domain: z.array(z.string()).optional(),
     parent: z.string().optional(),
     related: z.array(z.string()).optional(),
     tags: z.array(z.string()).optional(),
-    brief: z.string().optional(),
-    add_action: z.string().optional(),
-    add_actions: z.array(z.string()).optional(),
+    brief: nonEmptyText.optional(),
+    add_action: nonEmptyText.optional(),
+    add_actions: z.array(nonEmptyText).optional(),
 }).strict();
 export const CreateKnowledgeFieldsSchema = z.object({
     subtype: z.enum([...VALID_SUBTYPES]).optional(),
-    synthesis: z.string().optional(),
-    insight: z.string().optional(),
+    // Plan-only: insights have no lifecycle, so the semantic check rejects
+    // status on any other subtype (the shape only pins the allowed values).
+    status: z.enum([...PLAN_STATUSES]).optional(),
+    synthesis: nonEmptyText.optional(),
+    insight: nonEmptyText.optional(),
     description: z.string().optional(),
     domain: z.array(z.string()).optional(),
     related: z.array(z.string()).optional(),
@@ -65,8 +86,8 @@ export const CreateKnowledgeFieldsSchema = z.object({
     'session-date': z.string().optional(),
 }).strict();
 export const CreateSessionFieldsSchema = z.object({
-    synthesis: z.string().optional(),
-    insight: z.string().optional(),
+    synthesis: nonEmptyText.optional(),
+    insight: nonEmptyText.optional(),
     related: z.array(z.string()).optional(),
     'session-date': z.string().optional(),
 }).strict();
@@ -134,25 +155,124 @@ export const BatchOperationSchema = z.discriminatedUnion('op', [
     UnlinkBranch,
     PromoteBranch,
 ]);
+// --- Alias normalization ---
+// The one place a declared alias (contracts.ts ALIAS_KEYS) becomes its canonical
+// field. It runs before validation, so validate and apply both see the canonical
+// op on every entry point — library create/update/batch and CLI batch input
+// alike. Normalizing anywhere else is what made the alias a silent drop: the
+// strict shapes accepted `insight`, nothing rewrote it, and the apply step (which
+// only reads `synthesis`) wrote an empty Synthesis section and reported ok.
+/** ALIAS_KEYS re-keyed by op path prefix: 'update.fields' → [[alias, canonical]]. */
+const ALIASES_BY_PATH = new Map();
+for (const [path, canonical] of Object.entries(ALIAS_KEYS)) {
+    const cut = path.lastIndexOf('.');
+    const prefix = path.slice(0, cut);
+    const list = ALIASES_BY_PATH.get(prefix) ?? [];
+    list.push([path.slice(cut + 1), canonical]);
+    ALIASES_BY_PATH.set(prefix, list);
+}
+/** Canonicalize an operation's declared aliases.
+ *
+ * Precedence when both are present: the canonical field wins and the alias is
+ * dropped. Never mutates the caller's object — an op carrying no alias is
+ * returned as-is. */
+export function normalizeAliases(op) {
+    const o = op;
+    if (!o || typeof o !== 'object' || !o.fields || typeof o.fields !== 'object')
+        return op;
+    const prefix = `${String(o.op)}${o.kind === undefined ? '' : `.${String(o.kind)}`}.fields`;
+    const aliases = ALIASES_BY_PATH.get(prefix);
+    if (!aliases)
+        return op;
+    let fields;
+    for (const [alias, canonical] of aliases) {
+        if (o.fields[alias] === undefined)
+            continue;
+        fields ??= { ...o.fields };
+        if (fields[canonical] === undefined)
+            fields[canonical] = fields[alias];
+        delete fields[alias];
+    }
+    return fields ? { ...o, fields } : op;
+}
+/** normalizeAliases over a payload — the form the Spine and dry-run use. */
+export function normalizeOperations(operations) {
+    return operations.map(op => normalizeAliases(op));
+}
 function pushErr(errors, err) {
     const e = err;
     errors.push(e.details?.length ? `${e.message}: ${e.details.join('; ')}` : e.message);
 }
-export const OP_SPECS = [
+/** The one source of the missing-slug error text — specs and the Spine's
+ * shape-failure precedence rule (validateBatchCore) must not drift apart. */
+export function notFoundError(slug) {
+    return `'${slug}' not found`;
+}
+/** The one op-error line format. Every surface that localises an error to its
+ * op — the validate phase's error list, apply's execution-time failures, and
+ * the CLI's dry-run report — renders it through here, so an agent parsing
+ * `op[i] (op slug): …` sees one shape whichever surface produced it. */
+export function opErrorLine(index, op, slug, message) {
+    return `op[${index}] (${op} ${slug}): ${message}`;
+}
+/** The one "the batch was rejected, nothing landed" header — shared by the
+ * library's validate gate and the CLI's shape-parse gate, which reject the
+ * same payload at different depths and must say so identically. `batch
+ * --dry-run` deliberately words its own header differently: it reports a
+ * hypothetical ("would be applied"), not a refusal. */
+export function batchInvalidHeader(invalidCount, total) {
+    return `Batch failed validation: ${invalidCount} invalid operation${invalidCount === 1 ? '' : 's'} (0 of ${total} applied)`;
+}
+/** The one source of the duplicate-session disposition text. A duplicate
+ * session is not an error — the op is skipped and the batch continues — and
+ * dry-run (spec warning) and apply (BatchResult.warning) report it with this
+ * same sentence so the two can never drift. */
+export function duplicateSessionWarning(slug) {
+    return `session '${slug}' already exists — op skipped (batch continues)`;
+}
+/** The create-style gate, in one place so the invariant can't be re-broken:
+ * a taken slug is a SLUG_EXISTS error and must NOT be simulated (simulating
+ * over an existing slug shadows the real file's kind for later ops in the
+ * batch). The builder runs before the claim — it must see the pre-claim
+ * world so a self-referencing parent still fails. */
+function claimNew(ctx, errors, slug, info, build) {
+    const taken = ctx.existsAnywhere(slug);
+    if (taken)
+        errors.push(`Slug '${slug}' already exists`);
+    if (build) {
+        try {
+            build();
+        }
+        catch (err) {
+            pushErr(errors, err);
+        }
+    }
+    if (!taken)
+        ctx.simulate(slug, info);
+    return taken ? 'SLUG_EXISTS' : undefined;
+}
+// `as const satisfies` rather than a `: OpSpec[]` annotation: it keeps each
+// row's `name` a literal, which is what OpSpecName (and through it the Apply
+// table's key type) is derived from. OP_SPECS below re-exports the rows under
+// the interface, so consumers still read optional fields (`kind`) off them.
+const OP_SPEC_ROWS = [
     {
         name: 'update',
         op: 'update',
         schema: UpdateBranch,
-        description: 'Update an entity or knowledge note (status, brief, next actions, session log, synthesis, …).',
+        description: 'Update an entity or knowledge note (status, brief, next actions, session log, synthesis, …). `insight` is an alias for `synthesis` (knowledge-only; ignored when `synthesis` is also given). On knowledge notes `status` is plan-subtype only (active|done); insights reject it.',
         exampleInclude: ['status'],
         check(op, ctx) {
             const errors = [];
+            let primaryCode;
             const target = ctx.resolve(op.slug);
-            if (!target)
-                errors.push(`'${op.slug}' not found`);
+            if (!target) {
+                errors.push(notFoundError(op.slug));
+                primaryCode = 'NOT_FOUND';
+            }
             else {
                 try {
-                    ctx.validateKindFields(target.kind, op.fields);
+                    ctx.validateKindFields(target.kind, op.fields, target.subtype);
                 }
                 catch (err) {
                     pushErr(errors, err);
@@ -169,7 +289,7 @@ export const OP_SPECS = [
                         errors.push(`Related slug '${r}' does not exist`);
                 }
             }
-            return { slug: op.slug, errors };
+            return { slug: op.slug, errors, primaryCode };
         },
     },
     {
@@ -177,21 +297,13 @@ export const OP_SPECS = [
         op: 'create',
         kind: 'entity',
         schema: CreateEntityBranch,
-        description: 'Create a new entity (capture / entity / project).',
+        description: 'Create a new entity (capture / entity / project). A field whose section the chosen type lacks is rejected, never dropped — `purpose` needs type project.',
         exampleInclude: ['type'],
         check(op, ctx) {
             const errors = [];
             const slug = slugify(op.name);
-            if (ctx.existsAnywhere(slug))
-                errors.push(`Slug '${slug}' already exists`);
-            try {
-                ctx.buildEntityFrontmatter(op.name, op.fields);
-            }
-            catch (err) {
-                pushErr(errors, err);
-            }
-            ctx.simulate(slug, { kind: 'entity', type: op.fields.type });
-            return { slug, errors, created: errors.length === 0 };
+            const primaryCode = claimNew(ctx, errors, slug, { kind: 'entity', type: op.fields.type }, () => ctx.buildEntityFrontmatter(op.name, op.fields));
+            return { slug, errors, created: errors.length === 0, primaryCode };
         },
     },
     {
@@ -199,21 +311,13 @@ export const OP_SPECS = [
         op: 'create',
         kind: 'knowledge',
         schema: CreateKnowledgeBranch,
-        description: 'Create a new knowledge note (insight / plan subtype).',
+        description: 'Create a new knowledge note (insight / plan subtype). `insight` is an alias for `synthesis` (ignored when `synthesis` is also given). `status` (active|done) is plan-only; `synthesis` is insight-only — plan bodies are Goal/Steps/Dependencies, and a field whose section the subtype lacks is rejected, never dropped.',
         exampleInclude: ['subtype', 'synthesis'],
         check(op, ctx) {
             const errors = [];
             const slug = slugify(op.name);
-            if (ctx.existsAnywhere(slug))
-                errors.push(`Slug '${slug}' already exists`);
-            try {
-                ctx.buildKnowledgeFrontmatter(op.name, (op.fields || {}));
-            }
-            catch (err) {
-                pushErr(errors, err);
-            }
-            ctx.simulate(slug, { kind: 'knowledge', type: 'knowledge' });
-            return { slug, errors, created: errors.length === 0 };
+            const primaryCode = claimNew(ctx, errors, slug, { kind: 'knowledge', type: 'knowledge', subtype: op.fields?.subtype }, () => ctx.buildKnowledgeFrontmatter(op.name, (op.fields || {})));
+            return { slug, errors, created: errors.length === 0, primaryCode };
         },
     },
     {
@@ -221,12 +325,12 @@ export const OP_SPECS = [
         op: 'create',
         kind: 'session',
         schema: CreateSessionBranch,
-        description: 'Create a new session note linked to an entity.',
+        description: 'Create a new session note linked to an entity. `insight` is an alias for `synthesis` (ignored when `synthesis` is also given).',
         exampleInclude: ['synthesis'],
         check(op, ctx) {
             const slug = slugify(op.name);
             if (ctx.existsAnywhere(slug) || ctx.sessionExists(slug)) {
-                return { slug, errors: [], warning: `session '${slug}' already exists — op will be skipped (batch continues)` };
+                return { slug, errors: [], warning: duplicateSessionWarning(slug) };
             }
             ctx.simulateSession(slug);
             return { slug, errors: [], created: true };
@@ -241,10 +345,8 @@ export const OP_SPECS = [
         check(op, ctx) {
             const errors = [];
             const slug = slugify(op.name);
-            if (ctx.existsAnywhere(slug))
-                errors.push(`Slug '${slug}' already exists`);
-            ctx.simulate(slug, { kind: 'entity', type: 'capture' });
-            return { slug, errors, created: errors.length === 0 };
+            const primaryCode = claimNew(ctx, errors, slug, { kind: 'entity', type: 'capture' });
+            return { slug, errors, created: errors.length === 0, primaryCode };
         },
     },
     {
@@ -255,11 +357,14 @@ export const OP_SPECS = [
         exampleInclude: [],
         check(op, ctx) {
             const errors = [];
-            if (!ctx.resolve(op.slug))
-                errors.push(`'${op.slug}' not found`);
+            let primaryCode;
+            if (!ctx.resolve(op.slug)) {
+                errors.push(notFoundError(op.slug));
+                primaryCode = 'NOT_FOUND';
+            }
             if (!ctx.existsAnywhere(op.target))
                 errors.push(`Target '${op.target}' does not exist`);
-            return { slug: op.slug, errors };
+            return { slug: op.slug, errors, primaryCode };
         },
     },
     {
@@ -270,9 +375,12 @@ export const OP_SPECS = [
         exampleInclude: [],
         check(op, ctx) {
             const errors = [];
-            if (!ctx.resolve(op.slug))
-                errors.push(`'${op.slug}' not found`);
-            return { slug: op.slug, errors };
+            let primaryCode;
+            if (!ctx.resolve(op.slug)) {
+                errors.push(notFoundError(op.slug));
+                primaryCode = 'NOT_FOUND';
+            }
+            return { slug: op.slug, errors, primaryCode };
         },
     },
     {
@@ -283,9 +391,12 @@ export const OP_SPECS = [
         exampleInclude: [],
         check(op, ctx) {
             const errors = [];
+            let primaryCode;
             const cur = ctx.resolve(op.slug);
-            if (!cur)
-                errors.push(`'${op.slug}' not found`);
+            if (!cur) {
+                errors.push(notFoundError(op.slug));
+                primaryCode = 'NOT_FOUND';
+            }
             else {
                 const currentType = cur.kind === 'knowledge' ? 'knowledge' : cur.type;
                 try {
@@ -301,10 +412,11 @@ export const OP_SPECS = [
                     pushErr(errors, err);
                 }
             }
-            return { slug: op.slug, errors };
+            return { slug: op.slug, errors, primaryCode };
         },
     },
 ];
+export const OP_SPECS = OP_SPEC_ROWS;
 /** Find the spec for a (shape-valid) operation. */
 export function specFor(op) {
     const spec = OP_SPECS.find(s => s.op === op.op && (s.kind === undefined || s.kind === op.kind));
@@ -316,6 +428,18 @@ export function specFor(op) {
 export function validOpNames() {
     return [...new Set(OP_SPECS.map(s => s.op))];
 }
+/** Ops whose payload addresses an existing file by `slug` — derived from the
+ * Zod shapes, so a new slug-bearing op picks up slug-level rules (the
+ * NOT_FOUND precedence on shape failure in validateBatchCore) without a
+ * hand-kept list. */
+export function slugBearingOpNames() {
+    return [...new Set(OP_SPECS
+            .filter(s => {
+            const shape = s.schema.shape;
+            return shape !== undefined && 'slug' in shape;
+        })
+            .map(s => s.op))];
+}
 /** Create kinds for error text — derived from the table. */
 export function validCreateKinds() {
     return OP_SPECS.filter(s => s.op === 'create' && s.kind).map(s => s.kind);

package/dist/cli/args.d.ts

@@ -10,6 +10,10 @@ export interface ParsedArgs {
     positionals: string[];
 }
 export declare function parseArgs(args: string[], spec: FlagSpec, usage: string): ParsedArgs;
-/** Comma-separated list flag → trimmed array (undefined stays undefined). */
+/** The one comma-list parser — every list flag on every command goes through
+ * it. Trims each segment and drops the empty ones, so `"ai, ml"` is two
+ * domains (not `ai` and ` ml`, which no query matches) and `"eng,"` is one
+ * (not one plus an empty string persisted to frontmatter and the index).
+ * undefined stays undefined; an all-empty list is an empty array (a clear). */
 export declare function splitList(value: string | boolean | undefined): string[] | undefined;
 export declare function str(value: string | boolean | undefined): string | undefined;

package/dist/cli/args.js

@@ -38,11 +38,15 @@ export function parseArgs(args, spec, usage) {
     }
     return { flags, positionals };
 }
-/** Comma-separated list flag → trimmed array (undefined stays undefined). */
+/** The one comma-list parser — every list flag on every command goes through
+ * it. Trims each segment and drops the empty ones, so `"ai, ml"` is two
+ * domains (not `ai` and ` ml`, which no query matches) and `"eng,"` is one
+ * (not one plus an empty string persisted to frontmatter and the index).
+ * undefined stays undefined; an all-empty list is an empty array (a clear). */
 export function splitList(value) {
     if (typeof value !== 'string')
         return undefined;
-    return value.split(',').map(s => s.trim());
+    return value.split(',').map(s => s.trim()).filter(Boolean);
 }
 export function str(value) {
     return typeof value === 'string' ? value : undefined;

package/dist/cli/commands.d.ts

@@ -1,11 +1,34 @@
+import { type FlagSpec } from './args.js';
 import type { Hafez, BatchOperation } from '../types.js';
 export interface CommandOpts {
     json?: boolean;
+    /** Resolved vault path — for handlers that read the vault directly
+     * (export) rather than through the Hafez instance. */
+    vaultPath?: string;
 }
 export declare function cmdRead(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
+/** Every flag the query parser accepts, for the branch-support matrix. */
+export declare const QUERY_FLAG_NAMES: string[];
+export type QueryBranch = 'entity' | 'knowledge' | 'all' | 'related-to';
+/** Which flags each kind branch actually applies. A branch that cannot honour
+ * a flag rejects it (below) instead of dropping it: `--kind knowledge --filter
+ * stale` used to return every knowledge note with exit 0, and `--confidence`
+ * never reached an entity query at all. */
+export declare const QUERY_FLAG_SUPPORT: Record<QueryBranch, readonly string[]>;
 export declare function cmdQuery(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdSearch(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
+/** Exported so tests can assert the flag × kind matrix is exhaustive. */
+export declare const CREATE_FLAGS: FlagSpec;
 export declare function cmdCreate(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
+/** Exported so tests can assert the table covers the update schema. */
+export declare const UPDATE_FLAGS: FlagSpec;
+/** Flags the generic loop skips because they are not a field of the update
+ * shape — each is hand-handled in cmdUpdate. */
+export declare const UPDATE_SPECIAL_FLAGS: Set<string>;
+/** Update-shape fields with no flag of their own, and why. The exhaustiveness
+ * test consults this, so a gap here is a stated decision rather than the
+ * silent hole `add_actions` was. */
+export declare const UPDATE_FIELDS_WITHOUT_FLAGS: Record<string, string>;
 export declare function cmdUpdate(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdLink(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdUnlink(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
@@ -19,3 +42,4 @@ export declare function cmdChangelog(os: Hafez, args: string[], opts?: CommandOp
 export declare function parseBatchInput(json: string): BatchOperation[];
 export declare function cmdBatch(os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;
 export declare function cmdDigest(os: Hafez, args: string[], _opts?: CommandOpts): Promise<string>;
+export declare function cmdExport(_os: Hafez, args: string[], opts?: CommandOpts): Promise<string>;