hafez 1.3.0 → 2.0.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 ---
@@ -13,61 +17,87 @@ import { HafezError } from './types.js';
 // Every z.object(...) is .strict() — unknown keys become `unrecognized_keys` issues
 // (not silently dropped), which is load-bearing for the error-formatter's did-you-mean
 // hints and for catching typos like `{"kind": "parent"}` on a link op.
+// 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');
+// A list field (domain, tags, related) takes a string[] or, like the CLI's
+// list flags (`--domain "a,b"`), one comma string. The split is the one rule
+// for both paths — the CLI's `splitList` calls it — so `"a, b"` is the same
+// two values everywhere (#33).
+export const splitCommaList = (value) => value.split(',').map(s => s.trim()).filter(Boolean);
+const stringList = z.preprocess(v => typeof v === 'string' ? splitCommaList(v) : v, z.array(z.string()));
 export const SessionLogSchema = z.object({
     type: z.enum([...SESSION_LOG_TYPES]),
     summary: z.string(),
-    body: z.string().optional(),
+    body: nonEmptyText.optional(),
     agent: z.string(),
 }).strict();
 export const UpdateFieldsSchema = z.object({
     status: z.enum([...ENTITY_STATUSES]).optional(),
-    current_state: z.string().optional(),
+    current_state: nonEmptyText.optional(),
     session_log: SessionLogSchema.optional(),
+    agent: nonEmptyText.optional(), // entity-only; names the agent on the added session log entry
     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(),
+    parent: z.string().optional(), // entity-only; the slug must exist, no cycle
     // Knowledge metadata
     description: z.string().nullable().optional(),
     resource: z.string().nullable().optional(),
-    domain: z.array(z.string()).optional(),
+    domain: stringList.optional(),
     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(),
+    tags: stringList.optional(),
+    related: stringList.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(),
+    domain: stringList.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(),
+    related: stringList.optional(),
+    tags: stringList.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(),
+    confidence: z.enum([...CONFIDENCE_LEVELS]).optional(),
+    synthesis: nonEmptyText.optional(),
+    insight: nonEmptyText.optional(),
     description: z.string().optional(),
-    domain: z.array(z.string()).optional(),
-    related: z.array(z.string()).optional(),
-    tags: z.array(z.string()).optional(),
+    domain: stringList.optional(),
+    related: stringList.optional(),
+    tags: stringList.optional(),
     'session-date': z.string().optional(),
 }).strict();
 export const CreateSessionFieldsSchema = z.object({
-    synthesis: z.string().optional(),
-    insight: z.string().optional(),
-    related: z.array(z.string()).optional(),
+    synthesis: nonEmptyText.optional(),
+    insight: nonEmptyText.optional(),
+    related: stringList.optional(),
     'session-date': z.string().optional(),
 }).strict();
 const CreateEntityBranch = z.object({
@@ -88,6 +118,16 @@ const CreateSessionBranch = z.object({
     name: z.string(),
     fields: CreateSessionFieldsSchema.optional(),
 }).strict();
+/** Update fields the mechanised session log neither counts nor names:
+ * ticking a box is not history worth an entry, and `agent` only names it. */
+const UNLOGGED_FIELDS = new Set(['add_action', 'add_actions', 'complete_action', 'remove_action', 'clear_actions', 'agent']);
+/** The fields an update's mechanised session log entry names — empty when
+ * the update earns none. Shared by the update check (which rejects an
+ * `agent` with no entry to name) and the Apply update arm (which writes it). */
+export function loggedFields(fields) {
+    return Object.keys(fields)
+        .filter(f => fields[f] !== undefined && !UNLOGGED_FIELDS.has(f));
+}
 const UpdateBranch = z.object({
     op: z.literal('update'),
     slug: z.string(),
@@ -115,6 +155,12 @@ const PromoteBranch = z.object({
     slug: z.string(),
     target: z.enum(['entity', 'project', 'knowledge']),
 }).strict();
+// No `kind`: the slug alone says what is being deleted, the same as
+// `hafez delete <slug>`. The check resolves it and rejects an entity.
+const DeleteBranch = z.object({
+    op: z.literal('delete'),
+    slug: z.string(),
+}).strict();
 // Nested discriminated union: outer on `op`, inner on `kind` for create branch.
 // A flat `discriminatedUnion('op', [...])` cannot work because three branches share
 // op=create — Zod requires unique discriminator values per branch and throws at
@@ -133,31 +179,184 @@ export const BatchOperationSchema = z.discriminatedUnion('op', [
     LinkBranch,
     UnlinkBranch,
     PromoteBranch,
+    DeleteBranch,
 ]);
+// --- 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;
+}
+/** The link fields an update payload sets, or null when it sets none. */
+function linkFieldsOf(fields) {
+    const links = {};
+    if (fields.parent !== undefined)
+        links.parent = fields.parent;
+    if (fields.related !== undefined)
+        links.related = fields.related;
+    return Object.keys(links).length > 0 ? links : null;
+}
+/** The parent chain `slug → parent → … → slug` that giving `slug` this
+ * parent closes, or null when the chain ends or loops without `slug`.
+ * Shared by the Op Spec checks (against the simulated batch) and
+ * `validateVault` (against the files). */
+export function parentCycle(slug, parent, parentOf) {
+    const path = [slug];
+    const seen = new Set(path);
+    for (let p = parent; p !== undefined; p = parentOf(p)) {
+        path.push(p);
+        if (p === slug)
+            return path;
+        if (seen.has(p))
+            return null;
+        seen.add(p);
+    }
+    return null;
+}
+function parentCycleError(slug, parent, ctx) {
+    const cycle = parentCycle(slug, parent, s => ctx.linksOf(s).parent);
+    return cycle ? `Parent '${parent}' would make a cycle: ${cycle.join(' → ')}` : null;
+}
+// `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, …). Next Actions fields compose within one op as prune, tick, add: `clear_actions` → `remove_action` → `complete_action` → `add_action(s)` — queries match the list as it was before the op (two queries naming one line is an error), added lines land last, so `clear_actions` + `add_actions` rebuilds the list; `clear_actions` with a query field is rejected. Lines leaving the list (removed, cleared, pruned with an emptied section, ticked past nine, oldest first) move to the entity\'s archive log. A Handle of an open action (as `read` shows it, or any longer or shorter prefix of four or more hex that names only that line) names that line; anything else is a case-insensitive substring of the text. `parent` sets the parent link (entity-only; the slug must exist, and the parent chain must not lead back to the entity). `insight` is an alias for `synthesis` (knowledge-only; ignored when `synthesis` is also given). An entity update with no `session_log` gets a `progress` entry naming the fields written, unless its only fields are action fields; `agent` names the agent on it (entity-only, detected from the Harness when absent, rejected alongside `session_log`). 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);
                 }
             }
+            // Statically contradictory: clear_actions runs first and empties the
+            // list, so any query in the same op would fail at apply time with a
+            // misleading "No matching action". Reject here, where the message can
+            // say why and land beside the batch's other errors. Entity targets
+            // only — on a knowledge note validateKindFields has already rejected
+            // the fields themselves, and a second error about their order is noise.
+            if (target?.kind === 'entity' && op.fields.clear_actions) {
+                const queries = ['remove_action', 'complete_action'].filter(f => op.fields[f] !== undefined);
+                if (queries.length > 0) {
+                    errors.push(`clear_actions empties the list before ${queries.join(' and ')} would run — drop the clear or use a separate op`);
+                }
+            }
+            // `agent` names the entry the Spine adds; with nothing added it would be
+            // dropped. Entity targets only — on a knowledge note validateKindFields
+            // has already rejected it as entity-only.
+            if (target?.kind === 'entity' && op.fields.agent !== undefined) {
+                if (op.fields.session_log) {
+                    errors.push('agent names the session log entry added when session_log is absent — with session_log, set session_log.agent instead');
+                }
+                else if (loggedFields(op.fields).length === 0) {
+                    errors.push('agent names the session log entry, and an update of action fields alone writes none — drop agent');
+                }
+            }
             if (op.fields.session_log) {
                 const logErrors = ctx.validateSessionLogEntry(op.fields.session_log);
                 if (logErrors.length > 0)
@@ -169,7 +368,21 @@ export const OP_SPECS = [
                         errors.push(`Related slug '${r}' does not exist`);
                 }
             }
-            return { slug: op.slug, errors };
+            if (op.fields.parent !== undefined) {
+                if (!ctx.existsAnywhere(op.fields.parent))
+                    errors.push(`Parent '${op.fields.parent}' does not exist`);
+                else if (target?.kind === 'entity') {
+                    const cycle = parentCycleError(op.slug, op.fields.parent, ctx);
+                    if (cycle)
+                        errors.push(cycle);
+                }
+            }
+            if (target) {
+                const links = linkFieldsOf(op.fields);
+                if (links)
+                    ctx.simulateLinks(op.slug, { ...ctx.linksOf(op.slug), ...links });
+            }
+            return { slug: op.slug, errors, primaryCode };
         },
     },
     {
@@ -177,21 +390,15 @@ 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));
+            if (!primaryCode)
+                ctx.simulateLinks(slug, { parent: op.fields.parent, related: op.fields.related });
+            return { slug, errors, created: errors.length === 0, primaryCode };
         },
     },
     {
@@ -199,21 +406,15 @@ 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). `confidence` defaults to observation. `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 || {})));
+            if (!primaryCode)
+                ctx.simulateLinks(slug, { related: op.fields?.related });
+            return { slug, errors, created: errors.length === 0, primaryCode };
         },
     },
     {
@@ -221,12 +422,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 +442,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 +454,25 @@ 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 };
+            else if (!primaryCode && op.relation === 'parent') {
+                const cycle = parentCycleError(op.slug, op.target, ctx);
+                if (cycle)
+                    errors.push(cycle);
+            }
+            if (!primaryCode) {
+                const links = ctx.linksOf(op.slug);
+                ctx.simulateLinks(op.slug, op.relation === 'parent'
+                    ? { ...links, parent: op.target }
+                    : { ...links, related: [...(links.related ?? []).filter(r => r !== op.target), op.target] });
+            }
+            return { slug: op.slug, errors, primaryCode };
         },
     },
     {
@@ -270,9 +483,18 @@ 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';
+            }
+            else {
+                const links = ctx.linksOf(op.slug);
+                ctx.simulateLinks(op.slug, op.relation === 'parent'
+                    ? { ...links, parent: links.parent === op.target ? undefined : links.parent }
+                    : { ...links, related: links.related?.filter(r => r !== op.target) });
+            }
+            return { slug: op.slug, errors, primaryCode };
         },
     },
     {
@@ -283,9 +505,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 {
@@ -295,16 +520,56 @@ export const OP_SPECS = [
                     }
                     else {
                         ctx.simulate(op.slug, op.target === 'knowledge' ? { kind: 'knowledge', type: 'knowledge' } : { kind: 'entity', type: op.target });
+                        // A promoted knowledge note keeps related but not parent.
+                        if (op.target === 'knowledge')
+                            ctx.simulateLinks(op.slug, { related: ctx.linksOf(op.slug).related });
                     }
                 }
                 catch (err) {
                     pushErr(errors, err);
                 }
             }
-            return { slug: op.slug, errors };
+            return { slug: op.slug, errors, primaryCode };
+        },
+    },
+    {
+        name: 'delete',
+        op: 'delete',
+        schema: DeleteBranch,
+        description: 'Delete a knowledge or session note. An entity is never deleted — retire it with `hafez update <slug> --status done`. Rejected while another entity or knowledge note links to the note (parent/related): unlink or re-point those first — an earlier op in the same batch counts.',
+        exampleInclude: [],
+        addressesSessions: true,
+        check(op, ctx) {
+            const errors = [];
+            let primaryCode;
+            const target = ctx.resolve(op.slug);
+            const session = ctx.sessionExists(op.slug);
+            if (target?.kind === 'entity') {
+                errors.push(`'${op.slug}' is an entity (${target.type}) — an entity is never deleted; retire it with \`hafez update ${op.slug} --status done\``);
+            }
+            else if (target && session) {
+                errors.push(`'${op.slug}' is ambiguous — it names both a knowledge note and a session note, and delete will not guess which`);
+            }
+            else if (!target && !session) {
+                errors.push(notFoundError(op.slug));
+                primaryCode = 'NOT_FOUND';
+            }
+            else {
+                // Only knowledge can be linked to: a parent/related slug must name an
+                // entity or knowledge note, never a session.
+                const referrers = target ? ctx.referrers(op.slug) : [];
+                if (referrers.length > 0) {
+                    errors.push(`'${op.slug}' is still linked from ${referrers.join(', ')} (parent/related) — unlink or re-point those first; an earlier op in the same batch counts`);
+                }
+                else {
+                    ctx.simulateDelete(op.slug, target ? 'knowledge' : 'session');
+                }
+            }
+            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 +581,23 @@ 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))];
+}
+/** Slug-bearing ops whose slug may name a session note — a missing entity
+ * or knowledge note alone is not NOT_FOUND for them. */
+export function sessionAddressingOpNames() {
+    return OP_SPECS.filter(s => s.addressesSessions).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);