hafez 1.3.0 → 1.4.0

package/dist/batch-ops.d.ts

@@ -1,5 +1,5 @@
 import { z } from 'zod';
-import type { BatchOperation, CreateEntityFields, CreateKnowledgeFields, SessionLogEntry, UpdateFields } from './types.js';
+import type { BatchOperation, CreateEntityFields, CreateKnowledgeFields, KnowledgeSubtype, SessionLogEntry, UpdateFields } from './types.js';
 export declare const SessionLogSchema: z.ZodObject<{
     type: z.ZodEnum<{
         [x: string]: string;
@@ -59,6 +59,9 @@ export declare const CreateKnowledgeFieldsSchema: z.ZodObject<{
     subtype: z.ZodOptional<z.ZodEnum<{
         [x: string]: string;
     }>>;
+    status: z.ZodOptional<z.ZodEnum<{
+        [x: string]: string;
+    }>>;
     synthesis: z.ZodOptional<z.ZodString>;
     insight: z.ZodOptional<z.ZodString>;
     description: z.ZodOptional<z.ZodString>;
@@ -142,21 +145,33 @@ export declare const BatchOperationSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
         knowledge: "knowledge";
     }>;
 }, z.core.$strict>], "op">;
+/** 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 declare function normalizeAliases<T>(op: T): T;
+/** normalizeAliases over a payload — the form the Spine and dry-run use. */
+export declare function normalizeOperations(operations: BatchOperation[]): BatchOperation[];
+/** What a slug resolves to. `subtype` is carried for knowledge so ops that
+ * gate on the plan/insight distinction see it for files already on disk AND
+ * for notes created earlier in the same batch. */
+export interface ResolvedTarget {
+    kind: 'entity' | 'knowledge';
+    type: string;
+    subtype?: KnowledgeSubtype;
+}
 /** Vault context handed to each spec's semantic check by validateBatchCore.
  * Simulation-aware: creates earlier in the batch count as existing. */
 export interface OpCheckContext {
-    resolve(slug: string): {
-        kind: 'entity' | 'knowledge';
-        type: string;
-    } | null;
+    resolve(slug: string): ResolvedTarget | null;
     existsAnywhere(slug: string): boolean;
     sessionExists(slug: string): boolean;
-    simulate(slug: string, info: {
-        kind: 'entity' | 'knowledge';
-        type: string;
-    }): void;
+    simulate(slug: string, info: ResolvedTarget): void;
     simulateSession(slug: string): void;
-    validateKindFields(kind: 'entity' | 'knowledge', fields: UpdateFields): void;
+    /** Kind gating is subtype-aware for knowledge: a plan carries `status`,
+     * an insight does not (see contracts.SUBTYPE_STATUSES). */
+    validateKindFields(kind: 'entity' | 'knowledge', fields: UpdateFields, subtype?: KnowledgeSubtype): void;
     validateSessionLogEntry(entry: SessionLogEntry): string[];
     buildEntityFrontmatter(name: string, fields: CreateEntityFields): void;
     buildKnowledgeFrontmatter(name: string, fields: CreateKnowledgeFields): void;
@@ -166,7 +181,31 @@ export interface OpCheckResult {
     errors: string[];
     created?: boolean;
     warning?: string;
+    /** Error class of the primary failure, when it maps to a specific
+     * HafezError code. The Spine uses it so single-op callers keep NOT_FOUND /
+     * SLUG_EXISTS semantics (and their exit codes) through spec validation;
+     * batch-level failures stay VALIDATION_FAILED regardless. */
+    primaryCode?: 'NOT_FOUND' | 'SLUG_EXISTS';
 }
+/** The one source of the missing-slug error text — specs and the Spine's
+ * shape-failure precedence rule (validateBatchCore) must not drift apart. */
+export declare function notFoundError(slug: string): string;
+/** 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 declare function opErrorLine(index: number, op: string, slug: string, message: string): string;
+/** 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 declare function batchInvalidHeader(invalidCount: number, total: number): string;
+/** 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 declare function duplicateSessionWarning(slug: string): string;
 export interface OpSpec {
     /** Stable identifier used by `schema <name>` and the op catalog. */
     name: string;
@@ -175,13 +214,257 @@ export interface OpSpec {
     schema: z.ZodType;
     description: string;
     /** Optional fields force-included in the generated example payload. */
-    exampleInclude: string[];
+    exampleInclude: readonly string[];
     check(op: any, ctx: OpCheckContext): OpCheckResult;
 }
-export declare const OP_SPECS: OpSpec[];
+declare const OP_SPEC_ROWS: readonly [{
+    readonly name: "update";
+    readonly op: "update";
+    readonly schema: z.ZodObject<{
+        op: z.ZodLiteral<"update">;
+        slug: z.ZodString;
+        fields: z.ZodObject<{
+            status: z.ZodOptional<z.ZodEnum<{
+                [x: string]: string;
+            }>>;
+            current_state: z.ZodOptional<z.ZodString>;
+            session_log: z.ZodOptional<z.ZodObject<{
+                type: z.ZodEnum<{
+                    [x: string]: string;
+                }>;
+                summary: z.ZodString;
+                body: z.ZodOptional<z.ZodString>;
+                agent: z.ZodString;
+            }, z.core.$strict>>;
+            brief: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            add_action: z.ZodOptional<z.ZodString>;
+            add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            complete_action: z.ZodOptional<z.ZodString>;
+            remove_action: z.ZodOptional<z.ZodString>;
+            clear_actions: z.ZodOptional<z.ZodBoolean>;
+            description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            resource: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+            domain: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            confidence: z.ZodOptional<z.ZodEnum<{
+                [x: string]: string;
+            }>>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            related: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            synthesis: z.ZodOptional<z.ZodString>;
+            insight: z.ZodOptional<z.ZodString>;
+            add_evidence: z.ZodOptional<z.ZodString>;
+            add_source: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    readonly 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.";
+    readonly exampleInclude: readonly ["status"];
+    readonly check: (op: Extract<BatchOperation, {
+        op: "update";
+    }>, ctx: OpCheckContext) => {
+        slug: string;
+        errors: string[];
+        primaryCode: "SLUG_EXISTS" | "NOT_FOUND" | undefined;
+    };
+}, {
+    readonly name: "create-entity";
+    readonly op: "create";
+    readonly kind: "entity";
+    readonly schema: z.ZodObject<{
+        op: z.ZodLiteral<"create">;
+        kind: z.ZodLiteral<"entity">;
+        name: z.ZodString;
+        fields: z.ZodObject<{
+            type: z.ZodEnum<{
+                [x: string]: string;
+            }>;
+            purpose: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            resource: z.ZodOptional<z.ZodString>;
+            domain: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            parent: z.ZodOptional<z.ZodString>;
+            related: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            brief: z.ZodOptional<z.ZodString>;
+            add_action: z.ZodOptional<z.ZodString>;
+            add_actions: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+    }, z.core.$strict>;
+    readonly description: "Create a new entity (capture / entity / project). A field whose section the chosen type lacks is rejected, never dropped — `purpose` needs type project.";
+    readonly exampleInclude: readonly ["type"];
+    readonly check: (op: Extract<BatchOperation, {
+        op: "create";
+        kind: "entity";
+    }>, ctx: OpCheckContext) => {
+        slug: string;
+        errors: string[];
+        created: boolean;
+        primaryCode: "SLUG_EXISTS" | "NOT_FOUND" | undefined;
+    };
+}, {
+    readonly name: "create-knowledge";
+    readonly op: "create";
+    readonly kind: "knowledge";
+    readonly schema: z.ZodObject<{
+        op: z.ZodLiteral<"create">;
+        kind: z.ZodLiteral<"knowledge">;
+        name: z.ZodString;
+        fields: z.ZodOptional<z.ZodObject<{
+            subtype: z.ZodOptional<z.ZodEnum<{
+                [x: string]: string;
+            }>>;
+            status: z.ZodOptional<z.ZodEnum<{
+                [x: string]: string;
+            }>>;
+            synthesis: z.ZodOptional<z.ZodString>;
+            insight: z.ZodOptional<z.ZodString>;
+            description: z.ZodOptional<z.ZodString>;
+            domain: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            related: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            tags: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            'session-date': z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    readonly 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.";
+    readonly exampleInclude: readonly ["subtype", "synthesis"];
+    readonly check: (op: Extract<BatchOperation, {
+        op: "create";
+        kind: "knowledge";
+    }>, ctx: OpCheckContext) => {
+        slug: string;
+        errors: string[];
+        created: boolean;
+        primaryCode: "SLUG_EXISTS" | "NOT_FOUND" | undefined;
+    };
+}, {
+    readonly name: "create-session";
+    readonly op: "create";
+    readonly kind: "session";
+    readonly schema: z.ZodObject<{
+        op: z.ZodLiteral<"create">;
+        kind: z.ZodLiteral<"session">;
+        name: z.ZodString;
+        fields: z.ZodOptional<z.ZodObject<{
+            synthesis: z.ZodOptional<z.ZodString>;
+            insight: z.ZodOptional<z.ZodString>;
+            related: z.ZodOptional<z.ZodArray<z.ZodString>>;
+            'session-date': z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>;
+    readonly description: "Create a new session note linked to an entity. `insight` is an alias for `synthesis` (ignored when `synthesis` is also given).";
+    readonly exampleInclude: readonly ["synthesis"];
+    readonly check: (op: Extract<BatchOperation, {
+        op: "create";
+        kind: "session";
+    }>, ctx: OpCheckContext) => {
+        slug: string;
+        errors: never[];
+        warning: string;
+        created?: undefined;
+    } | {
+        slug: string;
+        errors: never[];
+        created: true;
+        warning?: undefined;
+    };
+}, {
+    readonly name: "capture";
+    readonly op: "capture";
+    readonly schema: z.ZodObject<{
+        op: z.ZodLiteral<"capture">;
+        name: z.ZodString;
+        notes: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>;
+    readonly description: "Quick capture — a raw inbox item with no structure required.";
+    readonly exampleInclude: readonly ["notes"];
+    readonly check: (op: Extract<BatchOperation, {
+        op: "capture";
+    }>, ctx: OpCheckContext) => {
+        slug: string;
+        errors: string[];
+        created: boolean;
+        primaryCode: "SLUG_EXISTS" | "NOT_FOUND" | undefined;
+    };
+}, {
+    readonly name: "link";
+    readonly op: "link";
+    readonly schema: z.ZodObject<{
+        op: z.ZodLiteral<"link">;
+        slug: z.ZodString;
+        target: z.ZodString;
+        relation: z.ZodEnum<{
+            parent: "parent";
+            related: "related";
+        }>;
+    }, z.core.$strict>;
+    readonly description: "Add a parent or related link between two entities.";
+    readonly exampleInclude: readonly [];
+    readonly check: (op: Extract<BatchOperation, {
+        op: "link";
+    }>, ctx: OpCheckContext) => {
+        slug: string;
+        errors: string[];
+        primaryCode: "SLUG_EXISTS" | "NOT_FOUND" | undefined;
+    };
+}, {
+    readonly name: "unlink";
+    readonly op: "unlink";
+    readonly schema: z.ZodObject<{
+        op: z.ZodLiteral<"unlink">;
+        slug: z.ZodString;
+        target: z.ZodString;
+        relation: z.ZodEnum<{
+            parent: "parent";
+            related: "related";
+        }>;
+    }, z.core.$strict>;
+    readonly description: "Remove a parent or related link between two entities.";
+    readonly exampleInclude: readonly [];
+    readonly check: (op: Extract<BatchOperation, {
+        op: "unlink";
+    }>, ctx: OpCheckContext) => {
+        slug: string;
+        errors: string[];
+        primaryCode: "SLUG_EXISTS" | "NOT_FOUND" | undefined;
+    };
+}, {
+    readonly name: "promote";
+    readonly op: "promote";
+    readonly schema: z.ZodObject<{
+        op: z.ZodLiteral<"promote">;
+        slug: z.ZodString;
+        target: z.ZodEnum<{
+            entity: "entity";
+            project: "project";
+            knowledge: "knowledge";
+        }>;
+    }, z.core.$strict>;
+    readonly description: "Promote a capture to entity/project/knowledge, or an entity to project.";
+    readonly exampleInclude: readonly [];
+    readonly check: (op: Extract<BatchOperation, {
+        op: "promote";
+    }>, ctx: OpCheckContext) => {
+        slug: string;
+        errors: string[];
+        primaryCode: "SLUG_EXISTS" | "NOT_FOUND" | undefined;
+    };
+}];
+/** Every op the table defines. The Apply table (src/apply.ts) is keyed by this
+ * union, so a spec row added here without an apply arm fails to build. */
+export type OpSpecName = (typeof OP_SPEC_ROWS)[number]['name'];
+export declare const OP_SPECS: readonly (OpSpec & {
+    name: OpSpecName;
+})[];
 /** Find the spec for a (shape-valid) operation. */
-export declare function specFor(op: BatchOperation): OpSpec;
+export declare function specFor(op: BatchOperation): OpSpec & {
+    name: OpSpecName;
+};
 /** Op names for error text ("expected one of […]") — derived, never hardcoded. */
 export declare function validOpNames(): string[];
+/** 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 declare function slugBearingOpNames(): string[];
 /** Create kinds for error text — derived from the table. */
 export declare function validCreateKinds(): string[];
+export {};