peaks-loop 4.0.0-beta.2 → 4.0.0-beta.3

package/dist/src/services/crystallization/crystallization-store.d.ts

@@ -0,0 +1,75 @@
+import type Database from "better-sqlite3";
+import { type CrystallizationEvent, type CrystallizationEventInput, type CrystallizationEventStatus } from "./crystallization-types.js";
+/**
+ * Low-level SQLite access for the `crystallization_event` table.
+ * The migration is registered with the existing `openStateDb()`
+ * pipeline via
+ * `src/services/skillhub/migrations/006-crystallization-event.sql`
+ * and is applied in lexicographic order alongside the other
+ * skillhub migrations. The function `ensureCrystallizationEventTable`
+ * below is a belt-and-suspenders re-applier for callers that pass a
+ * database they built themselves (e.g. tests).
+ *
+ * Defense in depth:
+ *   - All JSON columns are stored as TEXT and parsed at the
+ *     boundary. No big JSON BLOB at the SQLite layer — the row
+ *     stays small and queryable.
+ *   - The migration is idempotent (CREATE TABLE IF NOT EXISTS,
+ *     CREATE INDEX IF NOT EXISTS) so re-running it is safe.
+ *   - The 4-section brief guard and any other business rule is
+ *     enforced at the SERVICE layer (not the DB); the DB stores
+ *     the persisted, validated row.
+ */
+declare const SCHEMA_VERSION: "peaks.crystallization/1";
+/**
+ * Re-apply the crystallization_event table migration against an
+ * already-open database. Used by tests that build their own DB
+ * without the openStateDb pipeline. Idempotent.
+ */
+export declare function ensureCrystallizationEventTable(db: Database.Database): void;
+/**
+ * Insert a CrystallizationEvent row. The row's `schema_version` is
+ * taken from the input (must equal `peaks.crystallization/1`);
+ * `id` and `created_at` are stamped here so callers cannot backdate
+ * a row.
+ *
+ * The Zod schema (parse boundary) re-asserts the 4-section brief
+ * guard: a missing-section event is rejected before the SQL INSERT.
+ *
+ * Returns the persisted row.
+ */
+export declare function insertCrystallizationEvent(db: Database.Database, row: CrystallizationEventInput): CrystallizationEvent;
+/** Read a single CrystallizationEvent row by id; returns undefined if absent. */
+export declare function getCrystallizationEvent(db: Database.Database, id: string): CrystallizationEvent | undefined;
+/**
+ * List CrystallizationEvent rows. Filter by `lifecycle_status` and/or
+ * any of the optional FK pointers. When ALL filters are omitted, lists
+ * every event (newest-first by `created_at`).
+ */
+export declare function listCrystallizationEvents(db: Database.Database, opts?: {
+    lifecycle_status?: CrystallizationEventStatus;
+    created_loop_release_id?: string;
+    updated_loop_release_id?: string;
+    created_bee_release_id?: number;
+    updated_bee_release_id?: number;
+}): CrystallizationEvent[];
+/**
+ * Update the lifecycle_status of an existing CrystallizationEvent row.
+ * Returns the updated row, or undefined if absent.
+ *
+ * Lifecycle transitions are NOT validated here; the service layer
+ * decides whether `stable` requires a user_confirmation_pointer or
+ * other evidence (mirroring the evolution-store design).
+ */
+export declare function updateCrystallizationEventStatus(db: Database.Database, id: string, next: CrystallizationEventStatus): CrystallizationEvent | undefined;
+/**
+ * Test seam: produce a fresh id for a CrystallizationEvent row.
+ * Format: `crys-<hex>` (12 hex chars). Matches the Zod
+ * `^crys-[0-9a-f]{8,}$` pattern in CrystallizationEventSchema.
+ */
+export declare function newCrystallizationId(): string;
+/**
+ * Test seam: re-export the schema version so the service layer has a
+ * single source of truth.
+ */
+export { SCHEMA_VERSION as CRYSTALLIZATION_SCHEMA_VERSION };

package/dist/src/services/crystallization/crystallization-store.js

@@ -0,0 +1,193 @@
+import { CrystallizationEventSchema, } from "./crystallization-types.js";
+/**
+ * Low-level SQLite access for the `crystallization_event` table.
+ * The migration is registered with the existing `openStateDb()`
+ * pipeline via
+ * `src/services/skillhub/migrations/006-crystallization-event.sql`
+ * and is applied in lexicographic order alongside the other
+ * skillhub migrations. The function `ensureCrystallizationEventTable`
+ * below is a belt-and-suspenders re-applier for callers that pass a
+ * database they built themselves (e.g. tests).
+ *
+ * Defense in depth:
+ *   - All JSON columns are stored as TEXT and parsed at the
+ *     boundary. No big JSON BLOB at the SQLite layer — the row
+ *     stays small and queryable.
+ *   - The migration is idempotent (CREATE TABLE IF NOT EXISTS,
+ *     CREATE INDEX IF NOT EXISTS) so re-running it is safe.
+ *   - The 4-section brief guard and any other business rule is
+ *     enforced at the SERVICE layer (not the DB); the DB stores
+ *     the persisted, validated row.
+ */
+const SCHEMA_VERSION = "peaks.crystallization/1";
+/**
+ * Re-apply the crystallization_event table migration against an
+ * already-open database. Used by tests that build their own DB
+ * without the openStateDb pipeline. Idempotent.
+ */
+export function ensureCrystallizationEventTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS crystallization_event (
+      id                          TEXT PRIMARY KEY,
+      trigger                     TEXT NOT NULL CHECK (trigger IN (
+                                    'user_explicit',
+                                    'llm_suggested',
+                                    'success_default_prompt',
+                                    'similar_task_recurrence'
+                                  )),
+      evidence_brief_json         TEXT NOT NULL,
+      evidence_bullets_json       TEXT NOT NULL DEFAULT '[]',
+      source_trace_pointers_json  TEXT NOT NULL DEFAULT '[]',
+      evaluator_summary           TEXT NOT NULL DEFAULT '',
+      user_decision_summary       TEXT NOT NULL DEFAULT '',
+      created_loop_release_id     TEXT REFERENCES loop_release(id) ON DELETE SET NULL,
+      updated_loop_release_id     TEXT REFERENCES loop_release(id) ON DELETE SET NULL,
+      created_bee_release_id      INTEGER REFERENCES bee_release(id) ON DELETE SET NULL,
+      updated_bee_release_id      INTEGER REFERENCES bee_release(id) ON DELETE SET NULL,
+      lifecycle_status            TEXT NOT NULL DEFAULT 'candidate'
+                                    CHECK (lifecycle_status IN ('candidate','stable','retired')),
+      schema_version              TEXT NOT NULL CHECK (schema_version = 'peaks.crystallization/1'),
+      created_at                  TEXT NOT NULL,
+      CHECK (length(id) > 0),
+      CHECK (length(evidence_brief_json) >= 2)
+    );
+    CREATE INDEX IF NOT EXISTS idx_crystallization_event_created_loop
+      ON crystallization_event(created_loop_release_id);
+    CREATE INDEX IF NOT EXISTS idx_crystallization_event_updated_loop
+      ON crystallization_event(updated_loop_release_id);
+    CREATE INDEX IF NOT EXISTS idx_crystallization_event_created_bee
+      ON crystallization_event(created_bee_release_id);
+    CREATE INDEX IF NOT EXISTS idx_crystallization_event_updated_bee
+      ON crystallization_event(updated_bee_release_id);
+    CREATE INDEX IF NOT EXISTS idx_crystallization_event_lifecycle
+      ON crystallization_event(lifecycle_status);
+    CREATE INDEX IF NOT EXISTS idx_crystallization_event_created_at
+      ON crystallization_event(created_at);
+  `);
+}
+function rowToCrystallizationEvent(row) {
+    return {
+        id: row.id,
+        trigger: row.trigger,
+        evidence_brief: JSON.parse(row.evidence_brief_json),
+        evidence_bullets: JSON.parse(row.evidence_bullets_json),
+        source_trace_pointers: JSON.parse(row.source_trace_pointers_json),
+        evaluator_summary: row.evaluator_summary,
+        user_decision_summary: row.user_decision_summary,
+        created_loop_release_id: row.created_loop_release_id ?? undefined,
+        updated_loop_release_id: row.updated_loop_release_id ?? undefined,
+        created_bee_release_id: row.created_bee_release_id ?? undefined,
+        updated_bee_release_id: row.updated_bee_release_id ?? undefined,
+        lifecycle_status: row.lifecycle_status,
+        schema_version: row.schema_version,
+        created_at: row.created_at,
+    };
+}
+/**
+ * Insert a CrystallizationEvent row. The row's `schema_version` is
+ * taken from the input (must equal `peaks.crystallization/1`);
+ * `id` and `created_at` are stamped here so callers cannot backdate
+ * a row.
+ *
+ * The Zod schema (parse boundary) re-asserts the 4-section brief
+ * guard: a missing-section event is rejected before the SQL INSERT.
+ *
+ * Returns the persisted row.
+ */
+export function insertCrystallizationEvent(db, row) {
+    const id = newCrystallizationId();
+    const createdAt = new Date().toISOString();
+    // Build the persisted row first so the Zod refine guard (brief
+    // must have 4 sections) runs before any SQL side effects.
+    const persisted = CrystallizationEventSchema.parse({
+        ...row,
+        id,
+        schema_version: SCHEMA_VERSION,
+        created_at: createdAt,
+    });
+    const stmt = db.prepare(`INSERT INTO crystallization_event (
+       id, trigger, evidence_brief_json, evidence_bullets_json,
+       source_trace_pointers_json, evaluator_summary,
+       user_decision_summary,
+       created_loop_release_id, updated_loop_release_id,
+       created_bee_release_id, updated_bee_release_id,
+       lifecycle_status, schema_version, created_at
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    stmt.run(persisted.id, persisted.trigger, JSON.stringify(persisted.evidence_brief), JSON.stringify(persisted.evidence_bullets), JSON.stringify(persisted.source_trace_pointers), persisted.evaluator_summary, persisted.user_decision_summary, persisted.created_loop_release_id ?? null, persisted.updated_loop_release_id ?? null, persisted.created_bee_release_id ?? null, persisted.updated_bee_release_id ?? null, persisted.lifecycle_status, persisted.schema_version, persisted.created_at);
+    return persisted;
+}
+/** Read a single CrystallizationEvent row by id; returns undefined if absent. */
+export function getCrystallizationEvent(db, id) {
+    const row = db
+        .prepare("SELECT * FROM crystallization_event WHERE id = ?")
+        .get(id);
+    if (!row)
+        return undefined;
+    return rowToCrystallizationEvent(row);
+}
+/**
+ * List CrystallizationEvent rows. Filter by `lifecycle_status` and/or
+ * any of the optional FK pointers. When ALL filters are omitted, lists
+ * every event (newest-first by `created_at`).
+ */
+export function listCrystallizationEvents(db, opts = {}) {
+    const wheres = [];
+    const params = [];
+    if (opts.lifecycle_status !== undefined) {
+        wheres.push("lifecycle_status = ?");
+        params.push(opts.lifecycle_status);
+    }
+    if (opts.created_loop_release_id !== undefined) {
+        wheres.push("created_loop_release_id = ?");
+        params.push(opts.created_loop_release_id);
+    }
+    if (opts.updated_loop_release_id !== undefined) {
+        wheres.push("updated_loop_release_id = ?");
+        params.push(opts.updated_loop_release_id);
+    }
+    if (opts.created_bee_release_id !== undefined) {
+        wheres.push("created_bee_release_id = ?");
+        params.push(opts.created_bee_release_id);
+    }
+    if (opts.updated_bee_release_id !== undefined) {
+        wheres.push("updated_bee_release_id = ?");
+        params.push(opts.updated_bee_release_id);
+    }
+    let sql = "SELECT * FROM crystallization_event";
+    if (wheres.length > 0)
+        sql += " WHERE " + wheres.join(" AND ");
+    sql += " ORDER BY created_at DESC, id ASC";
+    const rows = db.prepare(sql).all(...params);
+    return rows.map(rowToCrystallizationEvent);
+}
+/**
+ * Update the lifecycle_status of an existing CrystallizationEvent row.
+ * Returns the updated row, or undefined if absent.
+ *
+ * Lifecycle transitions are NOT validated here; the service layer
+ * decides whether `stable` requires a user_confirmation_pointer or
+ * other evidence (mirroring the evolution-store design).
+ */
+export function updateCrystallizationEventStatus(db, id, next) {
+    const existing = getCrystallizationEvent(db, id);
+    if (!existing)
+        return undefined;
+    db.prepare("UPDATE crystallization_event SET lifecycle_status = ? WHERE id = ?").run(next, id);
+    return getCrystallizationEvent(db, id);
+}
+/**
+ * Test seam: produce a fresh id for a CrystallizationEvent row.
+ * Format: `crys-<hex>` (12 hex chars). Matches the Zod
+ * `^crys-[0-9a-f]{8,}$` pattern in CrystallizationEventSchema.
+ */
+export function newCrystallizationId() {
+    const hex = Math.floor(Math.random() * 0x1_000_000_000_000)
+        .toString(16)
+        .padStart(12, "0");
+    return `crys-${hex}`;
+}
+/**
+ * Test seam: re-export the schema version so the service layer has a
+ * single source of truth.
+ */
+export { SCHEMA_VERSION as CRYSTALLIZATION_SCHEMA_VERSION };

package/dist/src/services/crystallization/crystallization-types.d.ts

@@ -0,0 +1,313 @@
+import { z } from "zod";
+/**
+ * CrystallizationEvent — spec §4.5 / §4.7 / §5.
+ *
+ * M5 scope: the crystallization_event table + the 4-section
+ * evidence_brief projection (spec §4.7 / §10 RL-7). Every
+ * user-facing recommendation is gated on the brief being complete;
+ * the schema below enforces the 4-section shape at parse time.
+ *
+ * Hard rules enforced at the boundary (and re-asserted in the
+ * service layer):
+ *
+ *   1. The 4 brief sections (what_happened / why_it_matters /
+ *      what_learned / what_action) are ALL required. A partial
+ *      brief is a hard parse error (`MISSING_BRIEF_SECTION`),
+ *      and `parseCrystallizationEvent` will throw.
+ *   2. The trigger enum mirrors spec §4.5 exactly:
+ *      user_explicit | llm_suggested | success_default_prompt |
+ *      similar_task_recurrence.
+ *   3. The event's own lifecycle_status is ORTHOGONAL to the
+ *      created/updated loop_release.lifecycle_status — the same
+ *      asset can have many crystallization events over its life.
+ *   4. source_trace_pointers are stable ids (the workflow trace
+ *      id space), not path strings — the column is JSON-array of
+ *      strings.
+ *   5. The brief section guard is implemented as a `.refine(...)`
+ *      on the input schema — the canonical 4 keys must be present
+ *      with non-empty values (the spec mandates 1-2 sentences per
+ *      section; an empty string would be a degenerate brief).
+ *
+ * Out of scope (deferred to later slices):
+ *   - cross-event aggregation (loop crystallized N times).
+ *   - brief rewrite-on-update semantics (M8 dogfood).
+ */
+export declare const CrystallizationTriggerSchema: z.ZodEnum<["user_explicit", "llm_suggested", "success_default_prompt", "similar_task_recurrence"]>;
+export type CrystallizationTrigger = z.infer<typeof CrystallizationTriggerSchema>;
+export declare const CRYSTALLIZATION_TRIGGERS: readonly CrystallizationTrigger[];
+export declare const CrystallizationEventStatusSchema: z.ZodEnum<["candidate", "stable", "retired"]>;
+export type CrystallizationEventStatus = z.infer<typeof CrystallizationEventStatusSchema>;
+/**
+ * EvidenceBrief — the 4-section brief (spec §4.7).
+ *
+ * Hard shape invariant: ALL FOUR KEYS must be present at parse
+ * time, with non-empty NL content. The `.refine(...)` guard is
+ * what makes a brief a "brief" — without it, the projection is
+ * not a brief and the recommendation MUST NOT be rendered
+ * (service layer enforces this; Zod makes it a parse-time
+ * guarantee).
+ *
+ * Field semantics:
+ *   - what_happened   — 1-2 sentence factual account of the run.
+ *   - why_it_matters  — 1-2 sentence explanation of why this is
+ *                       worth promoting.
+ *   - what_learned    — 1-2 sentence learning: failure modes
+ *                       encoded, preferences extracted.
+ *   - what_action     — 1-sentence recommended action with
+ *                       rationale.
+ */
+export declare const EvidenceBriefSchema: z.ZodEffects<z.ZodObject<{
+    what_happened: z.ZodString;
+    why_it_matters: z.ZodString;
+    what_learned: z.ZodString;
+    what_action: z.ZodString;
+}, "strict", z.ZodTypeAny, {
+    what_happened: string;
+    why_it_matters: string;
+    what_learned: string;
+    what_action: string;
+}, {
+    what_happened: string;
+    why_it_matters: string;
+    what_learned: string;
+    what_action: string;
+}>, {
+    what_happened: string;
+    why_it_matters: string;
+    what_learned: string;
+    what_action: string;
+}, {
+    what_happened: string;
+    why_it_matters: string;
+    what_learned: string;
+    what_action: string;
+}>;
+export type EvidenceBrief = z.infer<typeof EvidenceBriefSchema>;
+/**
+ * Helper for downstream code that needs to know whether a parsed
+ * brief satisfies the 4-section rule. Useful for the CLI when a
+ * payload arrived from the LLM and the brief-section guard has
+ * already passed — it returns the section count, always 4 here.
+ */
+export declare function hasAllFourBriefSections(brief: EvidenceBrief): boolean;
+/**
+ * Zod schema for the create payload (CrystallizationEventInput).
+ *
+ * Re-validates the evidence_brief inline; calling code may ALSO call
+ * `EvidenceBriefSchema.parse` separately if it builds the brief out
+ * of band. The CrystallizationEvent input schema wires the same
+ * guard so a brief cannot sneak through via a partial-input path.
+ */
+export declare const CrystallizationEventInputSchema: z.ZodObject<{
+    trigger: z.ZodEnum<["user_explicit", "llm_suggested", "success_default_prompt", "similar_task_recurrence"]>;
+    evidence_brief: z.ZodEffects<z.ZodObject<{
+        what_happened: z.ZodString;
+        why_it_matters: z.ZodString;
+        what_learned: z.ZodString;
+        what_action: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        what_happened: string;
+        why_it_matters: string;
+        what_learned: string;
+        what_action: string;
+    }, {
+        what_happened: string;
+        why_it_matters: string;
+        what_learned: string;
+        what_action: string;
+    }>, {
+        what_happened: string;
+        why_it_matters: string;
+        what_learned: string;
+        what_action: string;
+    }, {
+        what_happened: string;
+        why_it_matters: string;
+        what_learned: string;
+        what_action: string;
+    }>;
+    evidence_bullets: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    source_trace_pointers: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    evaluator_summary: z.ZodDefault<z.ZodString>;
+    user_decision_summary: z.ZodDefault<z.ZodString>;
+    created_loop_release_id: z.ZodOptional<z.ZodString>;
+    updated_loop_release_id: z.ZodOptional<z.ZodString>;
+    created_bee_release_id: z.ZodOptional<z.ZodNumber>;
+    updated_bee_release_id: z.ZodOptional<z.ZodNumber>;
+    lifecycle_status: z.ZodDefault<z.ZodEnum<["candidate", "stable", "retired"]>>;
+}, "strip", z.ZodTypeAny, {
+    lifecycle_status: "candidate" | "stable" | "retired";
+    trigger: "user_explicit" | "llm_suggested" | "success_default_prompt" | "similar_task_recurrence";
+    evidence_brief: {
+        what_happened: string;
+        why_it_matters: string;
+        what_learned: string;
+        what_action: string;
+    };
+    evidence_bullets: string[];
+    source_trace_pointers: string[];
+    evaluator_summary: string;
+    user_decision_summary: string;
+    created_loop_release_id?: string | undefined;
+    updated_loop_release_id?: string | undefined;
+    created_bee_release_id?: number | undefined;
+    updated_bee_release_id?: number | undefined;
+}, {
+    trigger: "user_explicit" | "llm_suggested" | "success_default_prompt" | "similar_task_recurrence";
+    evidence_brief: {
+        what_happened: string;
+        why_it_matters: string;
+        what_learned: string;
+        what_action: string;
+    };
+    lifecycle_status?: "candidate" | "stable" | "retired" | undefined;
+    evidence_bullets?: string[] | undefined;
+    source_trace_pointers?: string[] | undefined;
+    evaluator_summary?: string | undefined;
+    user_decision_summary?: string | undefined;
+    created_loop_release_id?: string | undefined;
+    updated_loop_release_id?: string | undefined;
+    created_bee_release_id?: number | undefined;
+    updated_bee_release_id?: number | undefined;
+}>;
+export type CrystallizationEventInput = z.input<typeof CrystallizationEventInputSchema>;
+/**
+ * Full persisted row schema. Adds `id` (the event id) and stamps
+ * `schema_version` to the fixed literal `peaks.crystallization/1`.
+ *
+ * Brief section guard is INHERITED from `EvidenceBriefSchema.refine`
+ * because `EvidenceBriefSchema` is embedded; the service layer still
+ * re-asserts the guard so a hand-crafted row cannot bypass Zod at
+ * the store boundary.
+ */
+export declare const CrystallizationEventSchema: z.ZodObject<{
+    trigger: z.ZodEnum<["user_explicit", "llm_suggested", "success_default_prompt", "similar_task_recurrence"]>;
+    evidence_brief: z.ZodEffects<z.ZodObject<{
+        what_happened: z.ZodString;
+        why_it_matters: z.ZodString;
+        what_learned: z.ZodString;
+        what_action: z.ZodString;
+    }, "strict", z.ZodTypeAny, {
+        what_happened: string;
+        why_it_matters: string;
+        what_learned: string;
+        what_action: string;
+    }, {
+        what_happened: string;
+        why_it_matters: string;
+        what_learned: string;
+        what_action: string;
+    }>, {
+        what_happened: string;
+        why_it_matters: string;
+        what_learned: string;
+        what_action: string;
+    }, {
+        what_happened: string;
+        why_it_matters: string;
+        what_learned: string;
+        what_action: string;
+    }>;
+    evidence_bullets: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    source_trace_pointers: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    evaluator_summary: z.ZodDefault<z.ZodString>;
+    user_decision_summary: z.ZodDefault<z.ZodString>;
+    created_loop_release_id: z.ZodOptional<z.ZodString>;
+    updated_loop_release_id: z.ZodOptional<z.ZodString>;
+    created_bee_release_id: z.ZodOptional<z.ZodNumber>;
+    updated_bee_release_id: z.ZodOptional<z.ZodNumber>;
+    lifecycle_status: z.ZodDefault<z.ZodEnum<["candidate", "stable", "retired"]>>;
+} & {
+    id: z.ZodString;
+    schema_version: z.ZodDefault<z.ZodLiteral<"peaks.crystallization/1">>;
+    created_at: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    schema_version: "peaks.crystallization/1";
+    id: string;
+    lifecycle_status: "candidate" | "stable" | "retired";
+    trigger: "user_explicit" | "llm_suggested" | "success_default_prompt" | "similar_task_recurrence";
+    evidence_brief: {
+        what_happened: string;
+        why_it_matters: string;
+        what_learned: string;
+        what_action: string;
+    };
+    evidence_bullets: string[];
+    source_trace_pointers: string[];
+    evaluator_summary: string;
+    user_decision_summary: string;
+    created_at: string;
+    created_loop_release_id?: string | undefined;
+    updated_loop_release_id?: string | undefined;
+    created_bee_release_id?: number | undefined;
+    updated_bee_release_id?: number | undefined;
+}, {
+    id: string;
+    trigger: "user_explicit" | "llm_suggested" | "success_default_prompt" | "similar_task_recurrence";
+    evidence_brief: {
+        what_happened: string;
+        why_it_matters: string;
+        what_learned: string;
+        what_action: string;
+    };
+    created_at: string;
+    schema_version?: "peaks.crystallization/1" | undefined;
+    lifecycle_status?: "candidate" | "stable" | "retired" | undefined;
+    evidence_bullets?: string[] | undefined;
+    source_trace_pointers?: string[] | undefined;
+    evaluator_summary?: string | undefined;
+    user_decision_summary?: string | undefined;
+    created_loop_release_id?: string | undefined;
+    updated_loop_release_id?: string | undefined;
+    created_bee_release_id?: number | undefined;
+    updated_bee_release_id?: number | undefined;
+}>;
+export type CrystallizationEvent = z.infer<typeof CrystallizationEventSchema>;
+/**
+ * Convenience: strict-parse an unknown payload into a
+ * CrystallizationEvent row. Throws ZodError on failure — including
+ * when the brief is missing a section (the `.refine` guard fires).
+ *
+ * Use this at every parse boundary (CLI input, store insertion).
+ */
+export declare function parseCrystallizationEvent(input: unknown): CrystallizationEvent;
+/**
+ * Convenience: strict-parse an unknown payload as a standalone
+ * EvidenceBrief. Throws ZodError on failure.
+ */
+export declare function parseEvidenceBrief(input: unknown): EvidenceBrief;
+/**
+ * Safe-parse twin of parseCrystallizationEvent. Returns a Result-like
+ * envelope so callers (CLI / tests) can render findings without
+ * try/catch noise. The `code` field is `MISSING_BRIEF_SECTION` when
+ * the brief refine guard trips OR when ANY brief-section key is
+ * missing (spec §10 RL-7) — distinguishes brief failures from
+ * generic validation errors.
+ */
+export declare function safeParseCrystallizationEvent(input: unknown): {
+    ok: true;
+    row: CrystallizationEvent;
+} | {
+    ok: false;
+    code?: "MISSING_BRIEF_SECTION";
+    findings: Array<{
+        path: string;
+        message: string;
+    }>;
+};
+/**
+ * Safe-parse twin of parseEvidenceBrief. Same Result-like envelope
+ * shape; same MISSING_BRIEF_SECTION code mapping (covers both
+ * refine-guard failures and per-section missing/empty failures).
+ */
+export declare function safeParseEvidenceBrief(input: unknown): {
+    ok: true;
+    row: EvidenceBrief;
+} | {
+    ok: false;
+    code?: "MISSING_BRIEF_SECTION";
+    findings: Array<{
+        path: string;
+        message: string;
+    }>;
+};