peaks-loop 4.0.0-beta.6 → 4.0.0-beta.8

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

@@ -1,397 +0,0 @@
-import { z, ZodError } from "zod";
-import { CrystallizationEventSchema, EvidenceBriefSchema, } from "./crystallization-types.js";
-import { BriefSectionError } from "./evidence-brief-builder.js";
-import { CRYSTALLIZATION_SCHEMA_VERSION, ensureCrystallizationEventTable, getCrystallizationEvent, listCrystallizationEvents, newCrystallizationId, updateCrystallizationEventStatus, } from "./crystallization-store.js";
-import { insertLoopRelease } from "../loop/loop-release-store.js";
-import { LoopReleaseSchema } from "../loop/loop-release-types.js";
-import { insertLoopBeeRelation } from "../loop/loop-bee-relation-store.js";
-import { LoopBeeRelationSchema, } from "../loop/loop-bee-relation-types.js";
-/**
- * CrystallizationService — spec §5 (post-run crystallization)
- * + §4.5 + §4.7 + §10 RL-2 / RL-3 / RL-7.
- *
- * Hard rules enforced at THIS layer (defense in depth; the Zod
- * schemas above and the brief refine guard add the second wall):
- *
- *   - AC-4 / RL-2: a crystallization_event is written only when the
- *     candidate task has `task_status === 'completed'` AND
- *     `gates_passed === true` AND `evidence_collected === true`.
- *     Any pre-run attempt (status !== 'completed') is rejected
- *     with `CRYSTALLIZATION_PRE_RUN`. This is the pre-run block
- *     enforced by AC-4, AC-5, AC-6, AC-15, AC-16, AC-17 of the M5
- *     slice.
- *   - AC-6 / RL-3: writing a (loop_release, main_bee_release,
- *     loop_bee_relation) pair happens in a SINGLE TRANSACTION. The
- *     brief persist on crystallization_event also lives inside
- *     the same transaction (the brief is the durable evidence;
- *     dropping either side would break consistency).
- *   - AC-7 / RL-1: this layer never asks the user to hand-author
- *     JSON / manifest / CLI verb; all inputs are typed payloads
- *     the LLM submits on the user's behalf.
- *   - AC-15 / RL-7: the brief is mandatory; the
- *     `EvidenceBriefSchema.refine` guard rejects partial briefs
- *     at the parse boundary.
- *   - AC-16 / RL-7: the brief has all 4 sections
- *     (what_happened / why_it_matters / what_learned /
- *     what_action). The service throws `BriefSectionError` if the
- *     payload fails the guard.
- *
- * Sub-domain error codes:
- *
- *   - CRYSTALLIZATION_PRE_RUN: task_status / gates_passed /
- *     evidence_collected precondition failed.
- *   - CRYSTALLIZATION_INVALID_TASK_STATE: a task input field is
- *     malformed (e.g. unknown task_status).
- *   - MISSING_BRIEF_SECTION: a brief is missing at least one of
- *     its 4 sections (raised from the evidence-brief-builder
- *     refine; surfaced as-is by the service).
- *   - CRYSTALLIZATION_TX_FAILED: a transaction-side effect failed
- *     (FK constraint, duplicate key, …). The service re-raises
- *     richer domain errors first; this is the catch-all for
- *     unexpected SQL errors.
- */
-/* ---------------------------------------------------------------------- */
-/* Pre-run task gate — AC-4 / RL-2                                        */
-/* ---------------------------------------------------------------------- */
-export const CRYSTALLIZATION_TASK_STATUSES = [
-    "completed",
-    "in_progress",
-    "scratch",
-    "blocked",
-    "failed",
-];
-/**
- * The pre-run task state the service requires. Crystallization is
- * GATED on these three flags. The validator rejects any input that
- * does not match. Adding a new flag means a schema-version bump; for
- * now the three are required.
- */
-export const CrystallizationTaskStateSchema = z.object({
-    task_id: z.string().trim().min(1).max(256),
-    task_status: z.literal("completed", {
-        errorMap: () => ({
-            message: "task_status must be 'completed' for crystallization (AC-4 / RL-2)",
-        }),
-    }),
-    gates_passed: z.literal(true, {
-        errorMap: () => ({
-            message: "gates_passed must be true for crystallization (AC-4 / RL-2)",
-        }),
-    }),
-    evidence_collected: z.literal(true, {
-        errorMap: () => ({
-            message: "evidence_collected must be true for crystallization (AC-4 / RL-2)",
-        }),
-    }),
-});
-export class CrystallizationIntegrityError extends Error {
-    code;
-    findings;
-    constructor(code, message, findings = []) {
-        super(message);
-        this.name = "CrystallizationIntegrityError";
-        this.code = code;
-        this.findings = findings;
-    }
-}
-/**
- * Minimum bee_release payload the service needs to create a main bee
- * alongside a loop. The full bee_release schema (see
- * `src/services/skillhub/release-retain.ts`) carries manifest rows,
- * segment refs, file rows, etc.; M5 only writes the bee_release header
- * + a single bee_manifest row sufficient to keep the 4.x FK
- * constraints green. Full bee retaining lands in a future slice.
- *
- * Schema definition is hoisted above the interface so the typed
- * interface can reference the inferred Zod type without forward-
- * reference gymnastics.
- */
-const BeeNameSchema = z
-    .string()
-    .trim()
-    .min(1, "bee_name is required")
-    .max(200)
-    .regex(/^[a-z0-9][a-z0-9._-]*$/, {
-    message: "bee_name must be kebab-/snake-case starting with a lowercase letter or digit",
-});
-const BeeCrystallizeInputSchema = z.object({
-    bee_name: BeeNameSchema,
-    version: z
-        .string()
-        .regex(/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/, {
-        message: "version must be a semver string (e.g. 0.1.0)",
-    }),
-    description: z.string().trim().min(1).max(4000),
-    user_intent_raw: z.string().trim().max(4000).optional(),
-    parent_version: z.string().trim().max(64).optional(),
-    changelog: z.string().trim().max(8000).optional(),
-});
-/**
- * Service interface for the post-run crystallization flow.
- */
-export class CrystallizationService {
-    db;
-    constructor(db) {
-        this.db = db;
-        // Idempotent — safe to call on every constructor invocation; the
-        // openStateDb pipeline already applied the SQL migration, but a
-        // caller-built DB (e.g. tests) needs this.
-        ensureCrystallizationEventTable(this.db);
-    }
-    /**
-     * Read a CrystallizationEvent by id.
-     */
-    read(id) {
-        return getCrystallizationEvent(this.db, id);
-    }
-    /**
-     * List events. Filter by lifecycle_status and/or the FK pointer
-     * columns. When no filters are supplied, lists ALL events
-     * (newest-first).
-     */
-    list(opts = {}) {
-        return listCrystallizationEvents(this.db, opts);
-    }
-    /**
-     * Update a crystallization event's lifecycle_status. Always allowed
-     * (no schema-version gate). Returns the updated row or undefined if
-     * the id is absent.
-     *
-     * A `stable` transition is the natural post-crystallization state;
-     * the service does NOT enforce user-confirmation here (per spec
-     * §5.6 promotion happens on a separate `peaks loop promote` path).
-     * `retired` is the dispose path (`peaks asset dispose`).
-     */
-    updateStatus(id, next) {
-        return updateCrystallizationEventStatus(this.db, id, next);
-    }
-    /**
-     * Pre-run gate: throws if any of `task_status`, `gates_passed`,
-     * `evidence_collected` is not as required. Called from
-     * `crystallize` BEFORE the transaction begins.
-     *
-     * Reachable as a public method so the CLI / tests can probe the
-     * gate in isolation.
-     */
-    assertReady(task) {
-        let parsed;
-        try {
-            parsed = CrystallizationTaskStateSchema.parse(task);
-        }
-        catch (err) {
-            if (err instanceof ZodError) {
-                const findings = err.issues.map((i) => ({
-                    path: i.path.join("."),
-                    message: i.message,
-                }));
-                const first = err.issues[0];
-                throw new CrystallizationIntegrityError("CRYSTALLIZATION_PRE_RUN", `pre-run gate failed: ${first?.message ?? "invalid task state"}`, findings);
-            }
-            throw err;
-        }
-        // Defense in depth — re-assert at the service boundary.
-        if (parsed.task_status !== "completed" ||
-            parsed.gates_passed !== true ||
-            parsed.evidence_collected !== true) {
-            throw new CrystallizationIntegrityError("CRYSTALLIZATION_PRE_RUN", "pre-run gate failed: task must be completed with gates_passed=true AND evidence_collected=true (AC-4 / RL-2)", [
-                {
-                    path: "task",
-                    message: "task_status must equal 'completed' and gates_passed and evidence_collected must both be true",
-                },
-            ]);
-        }
-        return parsed;
-    }
-    /**
-     * Run the post-run crystallization flow.
-     *
-     * Steps (all in ONE better-sqlite3 transaction, atomic):
-     *
-     *   1. Pre-run gate (task must be completed / gates_passed /
-     *      evidence_collected).
-     *   2. Re-validate the 4-section brief (EvidenceBriefSchema.parse,
-     *      EvidenceBriefSchema.refine).
-     *   3. Insert loop_release.
-     *   4. Insert bee_release header (+ a single bee_manifest row to
-     *      keep the 4.x FK contract).
-     *   5. Insert loop_bee_relation row with role='main'.
-     *   6. Insert crystallization_event with the brief persisted.
-     *
-     * Returns the four ids + the new loop's lifecycle_status. On any
-     * failure the transaction is rolled back and the partial rows
-     * disappear.
-     *
-     * Throws:
-     *   - CrystallizationIntegrityError(CRYSTALLIZATION_PRE_RUN) on
-     *     the pre-run gate.
-     *   - BriefSectionError or ZodError if the brief is malformed;
-     *     surfaced as
-     *     CrystallizationIntegrityError(MISSING_BRIEF_SECTION).
-     *   - CrystallizationIntegrityError(CRYSTALLIZATION_TX_FAILED)
-     *     on any SQL transaction failure.
-     */
-    crystallize(payload) {
-        const task = this.assertReady(payload.task);
-        // Re-validate the 4-section brief up-front; the schema refines
-        // guard rejects partial briefs. This is the AC-15 / AC-16 / AC-17
-        // gate.
-        let brief;
-        try {
-            brief = payload.evidence_brief;
-            // Defensive re-parse even though the input is typed; ensures
-            // `parse()` runs the .refine() guard.
-            EvidenceBriefSchema.parse(brief);
-        }
-        catch (err) {
-            if (err instanceof ZodError || err instanceof BriefSectionError) {
-                const findings = err instanceof ZodError
-                    ? err.issues.map((i) => ({
-                        path: i.path.join("."),
-                        message: i.message,
-                    }))
-                    : err.findings;
-                throw new CrystallizationIntegrityError("MISSING_BRIEF_SECTION", "evidence_brief is missing at least one of the 4 required sections (spec §4.7 / RL-7)", [...findings]);
-            }
-            throw err;
-        }
-        // Re-validate loop_input via Zod so a hand-crafted caller input
-        // cannot bypass the schema. (M8 dogfood follow-up.)
-        const loopRow = LoopReleaseSchema.parse(payload.loop_input);
-        // Re-validate bee_input.
-        const beeRow = BeeCrystallizeInputSchema.parse(payload.bee_input);
-        // Loop-bee relation input (the relation's `reason` is the NL
-        // account the LLM authored). We validate the shape WITHOUT
-        // bee_release_id (which is filled in by the bee insert below),
-        // then validate the final tuple after the SQL writes.
-        const relationInputShape = LoopBeeRelationSchema.omit({
-            id: true,
-            created_at: true,
-            bee_release_id: true,
-        }).parse({
-            loop_release_id: loopRow.id,
-            role: "main",
-            reason: payload.bee_relation_reason,
-        });
-        const eventId = newCrystallizationId();
-        const eventCreatedAt = new Date().toISOString();
-        let loopReleaseId = loopRow.id;
-        let beeReleaseId = -1;
-        let relationId = -1;
-        let eventPersistedId = eventId;
-        const tx = this.db.transaction(() => {
-            // 1. Insert loop_release.
-            insertLoopRelease(this.db, loopRow);
-            // 2. Insert bee_release header. The existing
-            // `retainRelease` adds segment_ref / file / change rows; the
-            // minimal crystallization write here only opens the bee_release
-            // header row + a bee_manifest row. Future slices can promote
-            // the bee retain path to a richer flow.
-            const beeInsert = this.db.prepare(`INSERT INTO bee_release (
-           bee_name, version, source, archived_at, archived_by,
-           user_intent_raw, description, parent_version, changelog,
-           shareable, desktop_visible
-         ) VALUES (?, ?, 'user', ?, ?, ?, ?, ?, ?, 1, 1)`);
-            const beeInfo = beeInsert.run(beeRow.bee_name, beeRow.version, eventCreatedAt, "llm", beeRow.user_intent_raw ?? null, beeRow.description, beeRow.parent_version ?? null, beeRow.changelog ?? null);
-            beeReleaseId = Number(beeInfo.lastInsertRowid);
-            // Update the bee_release_pointer row so the latest version is
-            // discoverable via list tooling.
-            this.db
-                .prepare(`INSERT OR REPLACE INTO bee_release_pointer (bee_name, latest_version, released_at) VALUES (?, ?, ?)`)
-                .run(beeRow.bee_name, beeRow.version, eventCreatedAt);
-            // 3. Insert bee_manifest stub. Mirrors `retainRelease` minimum
-            // surface: promotion = 'candidate', requires_human = 0,
-            // requires_smoke = 0. Min-cycles left NULL.
-            this.db
-                .prepare(`INSERT INTO bee_manifest (
-             release_id, schema_version, description, segments_json,
-             entrypoint_preamble, promotion, min_cycles,
-             requires_human, requires_smoke, retire_on_misses
-           ) VALUES (?, ?, ?, '[]', '', 'candidate', NULL, 0, 0, NULL)`)
-                .run(beeReleaseId, "peaks.bee/1", beeRow.description);
-            // 4. Insert the loop_bee_relation row (FKs now valid). Re-parse
-            // through the input schema so the bee_release_id is validated
-            // too — defense in depth. `id` is autoincrement (not in input).
-            const fullRelation = LoopBeeRelationSchema.omit({
-                id: true,
-                created_at: true,
-            }).parse({
-                loop_release_id: relationInputShape.loop_release_id,
-                bee_release_id: beeReleaseId,
-                role: relationInputShape.role,
-                reason: relationInputShape.reason,
-                schema_version: "peaks.loop-bee-relation/1",
-            });
-            const relationRow = insertLoopBeeRelation(this.db, fullRelation);
-            relationId = relationRow.id;
-            // 5. Persist the crystallization_event row with the brief inline
-            // (the brief is the durable evidence — AC-17).
-            const eventInput = {
-                trigger: payload.trigger,
-                evidence_brief: brief,
-                evidence_bullets: payload.evidence_bullets ?? [],
-                source_trace_pointers: payload.source_trace_pointers ?? [],
-                evaluator_summary: payload.evaluator_summary ?? "",
-                user_decision_summary: payload.user_decision_summary ?? "",
-                created_loop_release_id: loopReleaseId,
-                created_bee_release_id: beeReleaseId,
-                // updated_* are not set on a CREATE crystallization; they will
-                // be set on future UPDATE crystallizations.
-                lifecycle_status: "candidate",
-            };
-            const persisted = insertCrystallizationEventRaw(this.db, eventInput, eventId, eventCreatedAt);
-            eventPersistedId = persisted.id;
-        });
-        try {
-            tx();
-        }
-        catch (err) {
-            // Map known SQLite constraint errors to friendlier codes; raise
-            // CrystallizationIntegrityError so the CLI can render the JSON
-            // envelope.
-            if (err instanceof CrystallizationIntegrityError ||
-                err instanceof BriefSectionError) {
-                throw err;
-            }
-            const message = err instanceof Error ? err.message : String(err);
-            throw new CrystallizationIntegrityError("CRYSTALLIZATION_TX_FAILED", `crystallization transaction failed: ${message}`, [
-                {
-                    path: "tx",
-                    message: "transaction rolled back; verify loop/bee ids are unique and FK targets exist",
-                },
-            ]);
-        }
-        // Silence the unused-variable lint; the parsed task is the source
-        // of truth at the entry boundary.
-        void task;
-        return {
-            loop_release_id: loopReleaseId,
-            bee_release_id: beeReleaseId,
-            loop_bee_relation_id: relationId,
-            crystallization_event_id: eventPersistedId,
-            loop_release_lifecycle_status: "candidate",
-        };
-    }
-}
-/* ---------------------------------------------------------------------- */
-/* Internal: thin writer that injects the deterministic eventId +         */
-/*           created_at so the crystallization flow can land all rows in  */
-/*           one tx before any non-idempotent residue lands.              */
-/* ---------------------------------------------------------------------- */
-function insertCrystallizationEventRaw(db, row, id, createdAt) {
-    const persisted = CrystallizationEventSchema.parse({
-        ...row,
-        id,
-        schema_version: CRYSTALLIZATION_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;
-}

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

@@ -1,75 +0,0 @@
-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

@@ -1,193 +0,0 @@
-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 };