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

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

@@ -0,0 +1,299 @@
+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).
+ */
+/* ---------------------------------------------------------------------- */
+/* Trigger — §4.5 / §5.4                                                   */
+/* ---------------------------------------------------------------------- */
+export const CrystallizationTriggerSchema = z.enum([
+    "user_explicit",
+    "llm_suggested",
+    "success_default_prompt",
+    "similar_task_recurrence",
+]);
+export const CRYSTALLIZATION_TRIGGERS = [
+    "user_explicit",
+    "llm_suggested",
+    "success_default_prompt",
+    "similar_task_recurrence",
+];
+/* ---------------------------------------------------------------------- */
+/* Lifecycle status — §5.6 (event-scoped, not asset-scoped)               */
+/* ---------------------------------------------------------------------- */
+export const CrystallizationEventStatusSchema = z.enum([
+    "candidate",
+    "stable",
+    "retired",
+]);
+/* ---------------------------------------------------------------------- */
+/* EvidenceBrief — §4.7 / §10 RL-7. REQUIRED 4-section shape.             */
+/* ---------------------------------------------------------------------- */
+/**
+ * The four brief sections. Spec §4.7 lists them as NL short
+ * sections; the service layer mandates 1-2 sentences (what_action
+ * is a single sentence per the spec). The Zod constraints below
+ * enforce NON-EMPTY strings. The brief-section guard (see
+ * `EvidenceBriefSchema.refine` below) rejects any payload missing
+ * one of the four keys, regardless of section content — it is
+ * the canonical hard gate per spec §10 RL-7.
+ */
+const BriefSectionSchema = z
+    .string()
+    .trim()
+    .min(1, "brief section must be non-empty natural language")
+    .max(4000);
+/**
+ * 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 const EvidenceBriefSchema = z
+    .object({
+    what_happened: BriefSectionSchema,
+    why_it_matters: BriefSectionSchema,
+    what_learned: BriefSectionSchema,
+    what_action: BriefSectionSchema,
+})
+    .strict()
+    .refine((b) => typeof b.what_happened === "string" &&
+    b.what_happened.trim().length > 0 &&
+    typeof b.why_it_matters === "string" &&
+    b.why_it_matters.trim().length > 0 &&
+    typeof b.what_learned === "string" &&
+    b.what_learned.trim().length > 0 &&
+    typeof b.what_action === "string" &&
+    b.what_action.trim().length > 0, {
+    message: "evidence_brief must contain all 4 sections (what_happened, why_it_matters, what_learned, what_action) with non-empty content (spec §4.7 / RL-7)",
+    path: [],
+});
+/**
+ * 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 function hasAllFourBriefSections(brief) {
+    return (typeof brief.what_happened === "string" &&
+        brief.what_happened.trim().length > 0 &&
+        typeof brief.why_it_matters === "string" &&
+        brief.why_it_matters.trim().length > 0 &&
+        typeof brief.what_learned === "string" &&
+        brief.what_learned.trim().length > 0 &&
+        typeof brief.what_action === "string" &&
+        brief.what_action.trim().length > 0);
+}
+/* ---------------------------------------------------------------------- */
+/* CrystallizationEvent — §4.5                                            */
+/* ---------------------------------------------------------------------- */
+/**
+ * Structurally referenced columns: pointers to optional loop_release /
+ * bee_release rows. All four are optional — a crystallization event
+ * may exist for "trace only" / "discard" choices that touch no durable
+ * asset. Set is governed by the service layer's pre-run gate.
+ */
+const OptionalLoopId = z
+    .string()
+    .min(1)
+    .max(64)
+    .regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, {
+    message: "loop_release_id must be kebab-case starting with a lowercase letter",
+})
+    .optional();
+const OptionalBeeId = z
+    .number()
+    .int()
+    .positive()
+    .max(2 ** 31 - 1, "bee_release_id out of 32-bit range")
+    .optional();
+/**
+ * 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 const CrystallizationEventInputSchema = z.object({
+    trigger: CrystallizationTriggerSchema,
+    evidence_brief: EvidenceBriefSchema,
+    evidence_bullets: z
+        .array(z.string().trim().min(1).max(1000))
+        .default([]),
+    source_trace_pointers: z
+        .array(z.string().trim().min(1).max(256))
+        .default([]),
+    evaluator_summary: z
+        .string()
+        .trim()
+        .max(4000)
+        .default(""),
+    user_decision_summary: z
+        .string()
+        .trim()
+        .max(4000)
+        .default(""),
+    created_loop_release_id: OptionalLoopId,
+    updated_loop_release_id: OptionalLoopId,
+    created_bee_release_id: OptionalBeeId,
+    updated_bee_release_id: OptionalBeeId,
+    lifecycle_status: CrystallizationEventStatusSchema.default("candidate"),
+});
+/**
+ * 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 const CrystallizationEventSchema = CrystallizationEventInputSchema.extend({
+    id: z
+        .string()
+        .min(1)
+        .max(128)
+        .regex(/^crys-[0-9a-f]{8,}$/, {
+        message: "id must start with 'crys-' followed by a hex suffix (spec §4.5)",
+    }),
+    schema_version: z
+        .literal("peaks.crystallization/1")
+        .default("peaks.crystallization/1"),
+    created_at: z.string().datetime(),
+});
+/**
+ * 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 function parseCrystallizationEvent(input) {
+    return CrystallizationEventSchema.parse(input);
+}
+/**
+ * Convenience: strict-parse an unknown payload as a standalone
+ * EvidenceBrief. Throws ZodError on failure.
+ */
+export function parseEvidenceBrief(input) {
+    return EvidenceBriefSchema.parse(input);
+}
+/**
+ * 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 function safeParseCrystallizationEvent(input) {
+    const r = CrystallizationEventSchema.safeParse(input);
+    if (r.success)
+        return { ok: true, row: r.data };
+    const findings = r.error.issues.map((i) => ({
+        path: i.path.join("."),
+        message: i.message,
+    }));
+    const isBrief = isBriefSectionFailure(r.error.issues);
+    return isBrief
+        ? { ok: false, code: "MISSING_BRIEF_SECTION", findings }
+        : { ok: false, findings };
+}
+/**
+ * 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 function safeParseEvidenceBrief(input) {
+    const r = EvidenceBriefSchema.safeParse(input);
+    if (r.success)
+        return { ok: true, row: r.data };
+    const findings = r.error.issues.map((i) => ({
+        path: i.path.join("."),
+        message: i.message,
+    }));
+    const isBrief = isBriefSectionFailure(r.error.issues);
+    return isBrief
+        ? { ok: false, code: "MISSING_BRIEF_SECTION", findings }
+        : { ok: false, findings };
+}
+/**
+ * Decide whether a ZodIssue[] is a "brief section" failure: every
+ * issue points at one of the four required keys (the section is
+ * missing, or empty after trim), OR the explicit refine-guard issue
+ * is present. Used by both `safeParseCrystallizationEvent` and
+ * `safeParseEvidenceBrief` so callers see a single
+ * `MISSING_BRIEF_SECTION` code regardless of which Zod boundary
+ * caught the failure.
+ */
+function isBriefSectionFailure(issues) {
+    if (issues.length === 0)
+        return false;
+    // Explicit refine guard (EvidenceBriefSchema.refine message).
+    if (issues.some((i) => i.message.includes("evidence_brief must contain all 4 sections"))) {
+        return true;
+    }
+    // Per-section Zod failures (min(1) on each section key, or
+    // too_small, or invalid_type). Each issue's path will be either
+    // the section key (`what_happened`) OR the parent `evidence_brief`
+    // — Zod reports missing-key issues against the parent object.
+    return issues.every((i) => {
+        const path = i.path.join(".");
+        if (path === "evidence_brief")
+            return true;
+        if (i.path.length >= 2 && i.path[0] === "evidence_brief") {
+            const key = i.path[i.path.length - 1];
+            return (key === "what_happened" ||
+                key === "why_it_matters" ||
+                key === "what_learned" ||
+                key === "what_action");
+        }
+        return (path === "what_happened" ||
+            path === "why_it_matters" ||
+            path === "what_learned" ||
+            path === "what_action");
+    });
+}

package/dist/src/services/crystallization/evidence-brief-builder.d.ts

@@ -0,0 +1,237 @@
+import { z } from "zod";
+import { type EvidenceBrief } from "./crystallization-types.js";
+/**
+ * EvidenceBriefBuilder — spec §4.7 / §10 RL-7.
+ *
+ * The brief is a 4-section natural-language projection that MUST
+ * accompany every user-facing recommendation. The shape guard is
+ * encoded in `EvidenceBriefSchema` (see crystallization-types.ts);
+ * this module is the LLM-side entry point that PRODUCES the brief
+ * from a finished trace + evaluator summary and the validator that
+ * REFUSES to render a recommendation payload without all 4 sections.
+ *
+ * Hard rules (mirrored from spec):
+ *
+ *   1. Every section must be a non-empty NL string (1-2 sentences
+ *      for what_happened / why_it_matters / what_learned; 1
+ *      sentence for what_action). An empty section is a hard
+ *      `MISSING_BRIEF_SECTION` error.
+ *
+ *   2. The build path is lenient on raw prose and strict on the
+ *      final shape — `buildEvidenceBrief` calls
+ *      `EvidenceBriefSchema.parse(...)` so a partial brief throws
+ *      before reaching the database.
+ *
+ *   3. `renderRecommendationPayload` refuses to return a
+ *      recommendation envelope unless the brief passes the 4-section
+ *      guard. This is the CLI's single source of truth for "may I
+ *      show this to the user?".
+ *
+ *   4. The `evaluator_summary` is a separate field on the
+ *      crystallization_event row (spec §4.5) and is NOT part of the
+ *      brief. It feeds the broader recommendation envelope.
+ *
+ * Out of scope (deferred to later slices):
+ *   - LLM-authored brief generation from live trace evidence (M8 dogfood).
+ *   - brief rewrite-on-update semantics.
+ */
+/**
+ * The minimum viable trace shape that the builder needs to render
+ * a brief. The trace is the EVIDENCE; the builder is format-stable
+ * so a future slice can swap in a richer trace source without
+ * editing every caller.
+ */
+export declare const BriefTraceInputSchema: z.ZodObject<{
+    trace_id: z.ZodString;
+    /**
+     * The full NL recap of the run. Required for what_happened.
+     * 1-2 sentences is the spec guidance; the builder does not
+     * truncate, but tests passing multi-paragraph input will be
+     * warned at the Zod boundary (max 4000 chars per section).
+     */
+    what_happened: z.ZodString;
+    /**
+     * The "why this matters" recap. Required for why_it_matters.
+     */
+    why_it_matters: z.ZodString;
+    /**
+     * Failure-mode and preference-extraction recap. Required for
+     * what_learned.
+     */
+    what_learned: z.ZodString;
+    /**
+     * The recommended action. Required for what_action (1
+     * sentence per spec).
+     */
+    what_action: z.ZodString;
+    /**
+     * Optional structured bullets (e.g. "4 phases, 3 gates passed,
+     * 1 evaluator verdict"). Counts are allowed at this layer; the
+     * brief section is the NL primary (RL-7).
+     */
+    bullets: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /**
+     * Source trace ids backing the brief (the column on
+     * crystallization_event spec §4.5).
+     */
+    source_trace_pointers: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    source_trace_pointers: string[];
+    what_happened: string;
+    why_it_matters: string;
+    what_learned: string;
+    what_action: string;
+    trace_id: string;
+    bullets: string[];
+}, {
+    what_happened: string;
+    why_it_matters: string;
+    what_learned: string;
+    what_action: string;
+    trace_id: string;
+    source_trace_pointers?: string[] | undefined;
+    bullets?: string[] | undefined;
+}>;
+export type BriefTraceInput = z.input<typeof BriefTraceInputSchema>;
+/**
+ * The summary emitted by the independent evaluators (spec §4.5
+ * `evaluator_summary` field). Optional for the brief builder — the
+ * brief can be built without it, but a filled evaluator_summary
+ * flows into the recommendation envelope.
+ */
+export declare const EvaluatorSummarySchema: z.ZodObject<{
+    one_liner: z.ZodDefault<z.ZodString>;
+    risk_tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    one_liner: string;
+    risk_tags: string[];
+}, {
+    one_liner?: string | undefined;
+    risk_tags?: string[] | undefined;
+}>;
+export type EvaluatorSummary = z.input<typeof EvaluatorSummarySchema>;
+export declare const RecommendationPayloadSchema: z.ZodObject<{
+    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;
+    }>;
+    bullets: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    source_trace_pointers: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    evaluator_summary: z.ZodDefault<z.ZodObject<{
+        one_liner: z.ZodDefault<z.ZodString>;
+        risk_tags: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        one_liner: string;
+        risk_tags: string[];
+    }, {
+        one_liner?: string | undefined;
+        risk_tags?: string[] | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    source_trace_pointers: string[];
+    evaluator_summary: {
+        one_liner: string;
+        risk_tags: string[];
+    };
+    bullets: string[];
+    brief: {
+        what_happened: string;
+        why_it_matters: string;
+        what_learned: string;
+        what_action: string;
+    };
+}, {
+    brief: {
+        what_happened: string;
+        why_it_matters: string;
+        what_learned: string;
+        what_action: string;
+    };
+    source_trace_pointers?: string[] | undefined;
+    evaluator_summary?: {
+        one_liner?: string | undefined;
+        risk_tags?: string[] | undefined;
+    } | undefined;
+    bullets?: string[] | undefined;
+}>;
+export type RecommendationPayload = z.infer<typeof RecommendationPayloadSchema>;
+export declare class BriefSectionError extends Error {
+    readonly code: "MISSING_BRIEF_SECTION";
+    readonly findings: ReadonlyArray<{
+        path: string;
+        message: string;
+    }>;
+    constructor(message: string, findings?: ReadonlyArray<{
+        path: string;
+        message: string;
+    }>);
+}
+/**
+ * Build a 4-section EvidenceBrief from a finished trace recap.
+ *
+ * The function is STRICT: it parses the input trace through
+ * `BriefTraceInputSchema`, then parses the assembled brief through
+ * `EvidenceBriefSchema`. Any missing section throws
+ * `BriefSectionError(MISSING_BRIEF_SECTION)` — the same code that
+ * `safeParseEvidenceBrief` returns — so a single error code is the
+ * user-facing signal for "brief incomplete, do not render".
+ *
+ * Brief-section related ZodErrors (e.g. `min(1)` on a section) are
+ * translated to `BriefSectionError` so callers only handle one
+ * shape of failure. Non-section ZodErrors (e.g. invalid `trace_id`)
+ * are re-raised unchanged.
+ *
+ * NOTE: callers who already have raw NL strings can also call
+ * `parseEvidenceBrief` directly; this function is the opinionated
+ * shape for trace -> brief.
+ */
+export declare function buildEvidenceBrief(trace: BriefTraceInput, evaluatorSummary?: EvaluatorSummary): EvidenceBrief;
+/**
+ * Render the user-facing recommendation envelope (brief + bullets +
+ * trace pointers + evaluator summary). The function refuses to
+ * return a payload unless ALL 4 brief sections are present — this
+ * is the single CLI-facing gate per spec §10 RL-7.
+ *
+ * On success, returns the validated `RecommendationPayload`. On a
+ * missing-section brief, throws `BriefSectionError`.
+ */
+export declare function renderRecommendationPayload(trace: BriefTraceInput, evaluatorSummary?: EvaluatorSummary): RecommendationPayload;
+/**
+ * Convenience: validate an arbitrary unknown payload AS IF it were a
+ * recommendation envelope. Returns a Result-like shape so the CLI can
+ * render a structured MISSING_BRIEF_SECTION error without try/catch
+ * noise.
+ */
+export declare function safeRenderRecommendationPayload(input: unknown): {
+    ok: true;
+    payload: RecommendationPayload;
+} | {
+    ok: false;
+    code?: "MISSING_BRIEF_SECTION";
+    findings: Array<{
+        path: string;
+        message: string;
+    }>;
+};