hafez 1.2.0 → 1.4.0

package/dist/batch-ops.d.ts

@@ -0,0 +1,470 @@
+import { z } from 'zod';
+import type { BatchOperation, CreateEntityFields, CreateKnowledgeFields, KnowledgeSubtype, SessionLogEntry, UpdateFields } from './types.js';
+export declare const SessionLogSchema: z.ZodObject<{
+    type: z.ZodEnum<{
+        [x: string]: string;
+    }>;
+    summary: z.ZodString;
+    body: z.ZodOptional<z.ZodString>;
+    agent: z.ZodString;
+}, z.core.$strict>;
+export declare const UpdateFieldsSchema: 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>;
+export declare const CreateEntityFieldsSchema: 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>;
+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>;
+    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>;
+export declare const CreateSessionFieldsSchema: 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>;
+/** What `digest` may put in a session-create op — typechecked against the
+ * schema so the two can never silently diverge again. */
+export type CreateSessionFieldsInput = z.infer<typeof CreateSessionFieldsSchema>;
+export declare const BatchOperationSchema: z.ZodDiscriminatedUnion<[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>, z.ZodObject<{
+    op: z.ZodLiteral<"create">;
+}, z.core.$strip>, z.ZodObject<{
+    op: z.ZodLiteral<"capture">;
+    name: z.ZodString;
+    notes: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"link">;
+    slug: z.ZodString;
+    target: z.ZodString;
+    relation: z.ZodEnum<{
+        parent: "parent";
+        related: "related";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"unlink">;
+    slug: z.ZodString;
+    target: z.ZodString;
+    relation: z.ZodEnum<{
+        parent: "parent";
+        related: "related";
+    }>;
+}, z.core.$strict>, z.ZodObject<{
+    op: z.ZodLiteral<"promote">;
+    slug: z.ZodString;
+    target: z.ZodEnum<{
+        entity: "entity";
+        project: "project";
+        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): ResolvedTarget | null;
+    existsAnywhere(slug: string): boolean;
+    sessionExists(slug: string): boolean;
+    simulate(slug: string, info: ResolvedTarget): void;
+    simulateSession(slug: string): 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;
+}
+export interface OpCheckResult {
+    slug: string;
+    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;
+    op: BatchOperation['op'];
+    kind?: 'entity' | 'knowledge' | 'session';
+    schema: z.ZodType;
+    description: string;
+    /** Optional fields force-included in the generated example payload. */
+    exampleInclude: readonly string[];
+    check(op: any, ctx: OpCheckContext): OpCheckResult;
+}
+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 & {
+    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 {};