peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/loop/loop-release-service.js

@@ -0,0 +1,66 @@
+import { LoopReleaseSchema, } from "./loop-release-types.js";
+import { ensureLoopReleaseTable, insertLoopRelease, getLoopRelease, listLoopReleasesByStatus, searchLoopReleasesByScenario, } from "./loop-release-store.js";
+/**
+ * Thin service wrapper around the loop_release store. M1 keeps the
+ * surface tiny on purpose: create / read / list / search. Promotion,
+ * retirement, evaluation, and the `loop_bee_relation` joins are
+ * deliberately deferred to M2 / M4 / M5 — shipping them here would
+ * lock in an interface that the ratchet has not yet ratified.
+ *
+ * The constructor takes an open better-sqlite3 database (the existing
+ * `peaks state` boundary) so callers do not have to thread a path
+ * through this layer; this matches the `retainRelease` pattern in
+ * `src/services/skillhub/release-retain.ts`.
+ *
+ * All write paths re-validate the input via the Zod schema, mirroring
+ * the boundary-check discipline used elsewhere (e.g.
+ * `lintManifestStrict` in `src/services/sediment/manifest-lint.ts`).
+ */
+export class LoopReleaseService {
+    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.
+        ensureLoopReleaseTable(this.db);
+    }
+    /**
+     * Persist a new LoopRelease row. Re-validates the input via the
+     * Zod schema; throws ZodError on failure.
+     */
+    create(input) {
+        const row = LoopReleaseSchema.parse(input);
+        insertLoopRelease(this.db, row);
+        return row;
+    }
+    /** Read a LoopRelease row by id; returns undefined if absent. */
+    read(id) {
+        return getLoopRelease(this.db, id);
+    }
+    /**
+     * List LoopRelease rows. Filter by `status` when supplied; without
+     * it, returns ALL rows (across `candidate` / `stable` / `retired`).
+     * Sort is newest-first by `archived_at`.
+     */
+    list(opts = {}) {
+        if (opts.status)
+            return listLoopReleasesByStatus(this.db, opts.status);
+        const all = ["candidate", "stable", "retired"];
+        const out = [];
+        for (const s of all)
+            out.push(...listLoopReleasesByStatus(this.db, s));
+        return out;
+    }
+    /**
+     * Search LoopRelease rows whose `scenario` contains the query
+     * string (case-insensitive substring match via LIKE). Filter by
+     * `status` to scope the search.
+     */
+    search(opts) {
+        const hits = searchLoopReleasesByScenario(this.db, opts.query);
+        if (!opts.status)
+            return hits;
+        return hits.filter((r) => r.lifecycle_status === opts.status);
+    }
+}

package/dist/services/loop/loop-release-store.d.ts

@@ -0,0 +1,55 @@
+import type Database from "better-sqlite3";
+import type { LoopRelease, LoopReleaseLifecycleStatus } from "./loop-release-types.js";
+/**
+ * Low-level SQLite access for the `loop_release` table. The
+ * migration is registered with the existing `openStateDb()` pipeline
+ * via `src/services/skillhub/migrations/002-loop-release.sql` and
+ * `004-loop-bee-extension.sql` (it applies every `*.sql` file in
+ * lexicographic order). The function `ensureLoopReleaseTable` 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 M3 migration (`004-loop-bee-extension.sql`) is non-breaking:
+ *     it only adds new columns with DEFAULTs and does NOT touch any
+ *     pre-existing column on `bee_release` (AC-3).
+ */
+/**
+ * Re-apply the loop_release table migration against an already-open
+ * database. Used by tests that build their own DB without the openStateDb
+ * pipeline. Idempotent.
+ *
+ * M3: the CREATE here now includes the four share / desktop extension
+ * columns from migration 004 (`shareable`, `share_excluded_paths`,
+ * `desktop_visible`, `export_bundle_format`). For an existing M2-era
+ * database, the migration runner will already have applied 004 and
+ * the columns will exist; for a freshly-built DB via this helper the
+ * columns are baked in. Either way the schema converges.
+ */
+export declare function ensureLoopReleaseTable(db: Database.Database): void;
+/**
+ * Insert a LoopRelease row. The row's `schema_version` is taken from
+ * the input (must equal `peaks.loop/1`); `archived_at` is stamped
+ * from the server clock here, so callers cannot backdate a row.
+ *
+ * Idempotent in the table sense (UNIQUE on `id`) — re-inserting the
+ * same id throws a UNIQUE-constraint error; callers wanting upsert
+ * semantics should use a separate path (M5 / crystallization event).
+ */
+export declare function insertLoopRelease(db: Database.Database, row: LoopRelease): void;
+/** Read a single LoopRelease row by id; returns undefined if absent. */
+export declare function getLoopRelease(db: Database.Database, id: string): LoopRelease | undefined;
+/** List LoopRelease rows filtered by lifecycle_status. */
+export declare function listLoopReleasesByStatus(db: Database.Database, status: LoopReleaseLifecycleStatus): LoopRelease[];
+/**
+ * Search LoopRelease rows whose `scenario` contains the query string.
+ * M1 uses a case-insensitive LIKE; FTS5 promotion is deferred. The
+ * query is treated as a literal substring (no regex, no SQL
+ * injection surface) — it is escaped via parameter binding.
+ */
+export declare function searchLoopReleasesByScenario(db: Database.Database, query: string): LoopRelease[];

package/dist/services/loop/loop-release-store.js

@@ -0,0 +1,134 @@
+/**
+ * Low-level SQLite access for the `loop_release` table. The
+ * migration is registered with the existing `openStateDb()` pipeline
+ * via `src/services/skillhub/migrations/002-loop-release.sql` and
+ * `004-loop-bee-extension.sql` (it applies every `*.sql` file in
+ * lexicographic order). The function `ensureLoopReleaseTable` 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 M3 migration (`004-loop-bee-extension.sql`) is non-breaking:
+ *     it only adds new columns with DEFAULTs and does NOT touch any
+ *     pre-existing column on `bee_release` (AC-3).
+ */
+/**
+ * Re-apply the loop_release table migration against an already-open
+ * database. Used by tests that build their own DB without the openStateDb
+ * pipeline. Idempotent.
+ *
+ * M3: the CREATE here now includes the four share / desktop extension
+ * columns from migration 004 (`shareable`, `share_excluded_paths`,
+ * `desktop_visible`, `export_bundle_format`). For an existing M2-era
+ * database, the migration runner will already have applied 004 and
+ * the columns will exist; for a freshly-built DB via this helper the
+ * columns are baked in. Either way the schema converges.
+ */
+export function ensureLoopReleaseTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS loop_release (
+      id                       TEXT PRIMARY KEY,
+      name                     TEXT NOT NULL,
+      scenario                 TEXT NOT NULL,
+      trigger_policy           TEXT NOT NULL,
+      success_criteria_json    TEXT NOT NULL,
+      interaction_policy       TEXT NOT NULL,
+      feedback_policy          TEXT NOT NULL,
+      evolution_policy         TEXT NOT NULL,
+      evaluator_policy_json    TEXT NOT NULL,
+      linked_bees_json         TEXT NOT NULL DEFAULT '[]',
+      run_history_json         TEXT NOT NULL DEFAULT '[]',
+      crystallization_evidence_json TEXT NOT NULL DEFAULT '[]',
+      lifecycle_status         TEXT NOT NULL CHECK (lifecycle_status IN ('candidate','stable','retired')),
+      version                  TEXT NOT NULL,
+      schema_version           TEXT NOT NULL CHECK (schema_version = 'peaks.loop/1'),
+      archived_at              TEXT NOT NULL,
+      shareable                INTEGER NOT NULL DEFAULT 1 CHECK (shareable IN (0, 1)),
+      share_excluded_paths     TEXT NOT NULL DEFAULT '[]',
+      desktop_visible          INTEGER NOT NULL DEFAULT 1 CHECK (desktop_visible IN (0, 1)),
+      export_bundle_format     TEXT NOT NULL DEFAULT 'peaks.bundle/1' CHECK (export_bundle_format = 'peaks.bundle/1')
+    );
+    CREATE INDEX IF NOT EXISTS idx_loop_release_lifecycle_status ON loop_release(lifecycle_status);
+    CREATE INDEX IF NOT EXISTS idx_loop_release_scenario ON loop_release(scenario);
+  `);
+}
+function rowToLoopRelease(row) {
+    return {
+        id: row.id,
+        name: row.name,
+        scenario: row.scenario,
+        trigger_policy: row.trigger_policy,
+        success_criteria: JSON.parse(row.success_criteria_json),
+        interaction_policy: row.interaction_policy,
+        feedback_policy: row.feedback_policy,
+        evolution_policy: row.evolution_policy,
+        evaluator_policy: JSON.parse(row.evaluator_policy_json),
+        linked_bees: JSON.parse(row.linked_bees_json),
+        run_history: JSON.parse(row.run_history_json),
+        crystallization_evidence: JSON.parse(row.crystallization_evidence_json),
+        lifecycle_status: row.lifecycle_status,
+        version: row.version,
+        schema_version: row.schema_version,
+        // M3: coerce the SQLite 0/1 INTEGER convention to JS boolean, and
+        // parse the JSON-encoded path list at the boundary.
+        shareable: row.shareable === 1,
+        share_excluded_paths: JSON.parse(row.share_excluded_paths),
+        desktop_visible: row.desktop_visible === 1,
+        export_bundle_format: row.export_bundle_format,
+    };
+}
+/**
+ * Insert a LoopRelease row. The row's `schema_version` is taken from
+ * the input (must equal `peaks.loop/1`); `archived_at` is stamped
+ * from the server clock here, so callers cannot backdate a row.
+ *
+ * Idempotent in the table sense (UNIQUE on `id`) — re-inserting the
+ * same id throws a UNIQUE-constraint error; callers wanting upsert
+ * semantics should use a separate path (M5 / crystallization event).
+ */
+export function insertLoopRelease(db, row) {
+    const stmt = db.prepare(`INSERT INTO loop_release (
+       id, name, scenario, trigger_policy,
+       success_criteria_json, interaction_policy, feedback_policy, evolution_policy,
+       evaluator_policy_json, linked_bees_json, run_history_json, crystallization_evidence_json,
+       lifecycle_status, version, schema_version, archived_at,
+       shareable, share_excluded_paths, desktop_visible, export_bundle_format
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`);
+    stmt.run(row.id, row.name, row.scenario, row.trigger_policy, JSON.stringify(row.success_criteria), row.interaction_policy, row.feedback_policy, row.evolution_policy, JSON.stringify(row.evaluator_policy), JSON.stringify(row.linked_bees), JSON.stringify(row.run_history), JSON.stringify(row.crystallization_evidence), row.lifecycle_status, row.version, row.schema_version, new Date().toISOString(), 
+    // M3: serialize the booleans to the SQLite 0/1 convention.
+    row.shareable ? 1 : 0, JSON.stringify(row.share_excluded_paths), row.desktop_visible ? 1 : 0, row.export_bundle_format);
+}
+/** Read a single LoopRelease row by id; returns undefined if absent. */
+export function getLoopRelease(db, id) {
+    const row = db
+        .prepare("SELECT * FROM loop_release WHERE id = ?")
+        .get(id);
+    if (!row)
+        return undefined;
+    return rowToLoopRelease(row);
+}
+/** List LoopRelease rows filtered by lifecycle_status. */
+export function listLoopReleasesByStatus(db, status) {
+    const rows = db
+        .prepare("SELECT * FROM loop_release WHERE lifecycle_status = ? ORDER BY archived_at DESC, id ASC")
+        .all(status);
+    return rows.map(rowToLoopRelease);
+}
+/**
+ * Search LoopRelease rows whose `scenario` contains the query string.
+ * M1 uses a case-insensitive LIKE; FTS5 promotion is deferred. The
+ * query is treated as a literal substring (no regex, no SQL
+ * injection surface) — it is escaped via parameter binding.
+ */
+export function searchLoopReleasesByScenario(db, query) {
+    const like = `%${query}%`;
+    const rows = db
+        .prepare("SELECT * FROM loop_release WHERE scenario LIKE ? COLLATE NOCASE ORDER BY archived_at DESC, id ASC")
+        .all(like);
+    return rows.map(rowToLoopRelease);
+}

package/dist/services/loop/loop-release-types.d.ts

@@ -0,0 +1,250 @@
+import { z } from "zod";
+/**
+ * LoopRelease — spec §4.1 (Loop Engineering Asset).
+ *
+ * M1 scope was the §4.1 fields. M3 (this slice) ADDS the share /
+ * desktop extension fields from §4.1 / §7A:
+ *   - shareable              (boolean, default true)
+ *   - share_excluded_paths   (string[], default [])
+ *   - desktop_visible        (boolean, default true)
+ *   - export_bundle_format   ('peaks.bundle/1', CLI-written constant)
+ *
+ * The four M3 fields are added with `.default(...)` so an in-memory
+ * object built from a pre-M3 snapshot still parses after the
+ * migration runs. NO enforcement on `shareable=false` is added in M3
+ * — the schema-only addition is the contract; full export /
+ * desktop enforcement lands in M7 (see plan
+ * m3-bee-release-extension.md and spec §7A).
+ *
+ * Field semantics — see the spec for full prose. Highlights:
+ *
+ *   - `id` is the stable kebab-case loop id; the storage key.
+ *   - `schema_version` is the constant literal `"peaks.loop/1"`; a
+ *     schema-version bump requires a new table / new enum case and a
+ *     migration — never edit this literal in place.
+ *   - `lifecycle_status` is `candidate` / `stable` / `retired`; the
+ *     default on first crystallization is `candidate`. LLMs cannot
+ *     auto-promote to `stable` (see spec §5.6).
+ *   - `linked_bees` is a denormalized pointer list of bee ids; the
+ *     authoritative loop↔bee relations live in `loop_bee_relation`
+ *     (M2). Keeping it here matches the spec §4.1 row shape and lets
+ *     M1 readers iterate the loop without an extra join.
+ *   - `success_criteria` / `evaluator_policy` are NL strings, not
+ *     machine-checked predicates; the evaluator definitions live in
+ *     the M4 evolution layer.
+ *   - `share_excluded_paths` is a JSON-encoded TEXT column at the
+ *     SQLite layer; the Zod schema accepts a string[] and the store
+ *     does the JSON.stringify/parse boundary work. Matches the
+ *     existing `loop_release` style (success_criteria_json, …).
+ *   - `export_bundle_format` is pinned to the literal
+ *     `"peaks.bundle/1"` per the spec §7A.2 contract — no other
+ *     value is accepted in this schema version.
+ */
+export declare const LoopReleaseLifecycleStatusSchema: z.ZodEnum<["candidate", "stable", "retired"]>;
+export type LoopReleaseLifecycleStatus = z.infer<typeof LoopReleaseLifecycleStatusSchema>;
+/**
+ * The M3 share / desktop extension fields, listed for code-search /
+ * lint discoverability. They are now part of the schema (with safe
+ * defaults) — see `LoopReleaseM3ExtensionSchema` below.
+ *
+ *   - shareable: defaults to true.
+ *   - share_excluded_paths: string[] (defaults to []).
+ *   - desktop_visible: defaults to true.
+ *   - export_bundle_format: constant "peaks.bundle/1" (CLI-written).
+ */
+export declare const LOOP_RELEASE_M3_FIELDS: readonly ["shareable", "share_excluded_paths", "desktop_visible", "export_bundle_format"];
+/**
+ * M3 share / desktop extension schema. Added to `LoopReleaseInputSchema`
+ * via `.extend(...)` so existing callers that omit these fields still
+ * parse — the Zod defaults below supply the spec values
+ * (true / [] / true / "peaks.bundle/1").
+ *
+ * `export_bundle_format` is pinned to a literal per spec §7A.2: the
+ * CLI is the only writer and only `"peaks.bundle/1"` is accepted. A
+ * schema-version bump is required to introduce another value.
+ */
+export declare const LoopReleaseM3ExtensionSchema: z.ZodObject<{
+    shareable: z.ZodDefault<z.ZodBoolean>;
+    share_excluded_paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    desktop_visible: z.ZodDefault<z.ZodBoolean>;
+    export_bundle_format: z.ZodDefault<z.ZodLiteral<"peaks.bundle/1">>;
+}, "strip", z.ZodTypeAny, {
+    shareable: boolean;
+    share_excluded_paths: string[];
+    desktop_visible: boolean;
+    export_bundle_format: "peaks.bundle/1";
+}, {
+    shareable?: boolean | undefined;
+    share_excluded_paths?: string[] | undefined;
+    desktop_visible?: boolean | undefined;
+    export_bundle_format?: "peaks.bundle/1" | undefined;
+}>;
+/** Convenience type for the M3 share / desktop subset. */
+export type LoopReleaseM3Extension = z.infer<typeof LoopReleaseM3ExtensionSchema>;
+/**
+ * Zod schema for the create payload (LoopReleaseInput). Mirrors the
+ * §4.1 row shape; `schema_version` is defaulted (clients cannot
+ * override it) and `created_at` is not part of the input — the store
+ * stamps it from the server clock.
+ */
+export declare const LoopReleaseInputSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    scenario: z.ZodString;
+    trigger_policy: z.ZodString;
+    success_criteria: z.ZodArray<z.ZodString, "many">;
+    interaction_policy: z.ZodString;
+    feedback_policy: z.ZodString;
+    evolution_policy: z.ZodString;
+    evaluator_policy: z.ZodArray<z.ZodString, "many">;
+    linked_bees: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    run_history: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    crystallization_evidence: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    lifecycle_status: z.ZodEnum<["candidate", "stable", "retired"]>;
+    version: z.ZodString;
+} & {
+    shareable: z.ZodDefault<z.ZodBoolean>;
+    share_excluded_paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    desktop_visible: z.ZodDefault<z.ZodBoolean>;
+    export_bundle_format: z.ZodDefault<z.ZodLiteral<"peaks.bundle/1">>;
+}, "strip", z.ZodTypeAny, {
+    version: string;
+    name: string;
+    lifecycle_status: "candidate" | "stable" | "retired";
+    id: string;
+    shareable: boolean;
+    share_excluded_paths: string[];
+    desktop_visible: boolean;
+    export_bundle_format: "peaks.bundle/1";
+    scenario: string;
+    trigger_policy: string;
+    success_criteria: string[];
+    interaction_policy: string;
+    feedback_policy: string;
+    evolution_policy: string;
+    evaluator_policy: string[];
+    linked_bees: string[];
+    run_history: string[];
+    crystallization_evidence: string[];
+}, {
+    version: string;
+    name: string;
+    lifecycle_status: "candidate" | "stable" | "retired";
+    id: string;
+    scenario: string;
+    trigger_policy: string;
+    success_criteria: string[];
+    interaction_policy: string;
+    feedback_policy: string;
+    evolution_policy: string;
+    evaluator_policy: string[];
+    shareable?: boolean | undefined;
+    share_excluded_paths?: string[] | undefined;
+    desktop_visible?: boolean | undefined;
+    export_bundle_format?: "peaks.bundle/1" | undefined;
+    linked_bees?: string[] | undefined;
+    run_history?: string[] | undefined;
+    crystallization_evidence?: string[] | undefined;
+}>;
+/**
+ * `LoopReleaseInput` is the *input* shape clients supply: defaulted
+ * fields (linked_bees / run_history / crystallization_evidence) are
+ * optional here. We use `z.input` (not `z.infer`) so the inferred
+ * type matches the create-call signature; the parsed output type —
+ * with all defaulted fields filled — is `LoopRelease`.
+ */
+export type LoopReleaseInput = z.input<typeof LoopReleaseInputSchema>;
+/**
+ * Full Zod schema for a LoopRelease row as persisted. Differs from the
+ * input schema only in that `schema_version` is exposed (and defaulted
+ * to the fixed literal). The literal constraint still rejects any
+ * client-supplied value other than `"peaks.loop/1"`; the default
+ * means omitting the key is fine and the output always carries the
+ * constant.
+ *
+ * We expose this as the canonical "row schema" used by lint and
+ * service.create/read paths.
+ */
+export declare const LoopReleaseSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    scenario: z.ZodString;
+    trigger_policy: z.ZodString;
+    success_criteria: z.ZodArray<z.ZodString, "many">;
+    interaction_policy: z.ZodString;
+    feedback_policy: z.ZodString;
+    evolution_policy: z.ZodString;
+    evaluator_policy: z.ZodArray<z.ZodString, "many">;
+    linked_bees: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    run_history: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    crystallization_evidence: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    lifecycle_status: z.ZodEnum<["candidate", "stable", "retired"]>;
+    version: z.ZodString;
+} & {
+    shareable: z.ZodDefault<z.ZodBoolean>;
+    share_excluded_paths: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    desktop_visible: z.ZodDefault<z.ZodBoolean>;
+    export_bundle_format: z.ZodDefault<z.ZodLiteral<"peaks.bundle/1">>;
+} & {
+    schema_version: z.ZodDefault<z.ZodLiteral<"peaks.loop/1">>;
+}, "strip", z.ZodTypeAny, {
+    schema_version: "peaks.loop/1";
+    version: string;
+    name: string;
+    lifecycle_status: "candidate" | "stable" | "retired";
+    id: string;
+    shareable: boolean;
+    share_excluded_paths: string[];
+    desktop_visible: boolean;
+    export_bundle_format: "peaks.bundle/1";
+    scenario: string;
+    trigger_policy: string;
+    success_criteria: string[];
+    interaction_policy: string;
+    feedback_policy: string;
+    evolution_policy: string;
+    evaluator_policy: string[];
+    linked_bees: string[];
+    run_history: string[];
+    crystallization_evidence: string[];
+}, {
+    version: string;
+    name: string;
+    lifecycle_status: "candidate" | "stable" | "retired";
+    id: string;
+    scenario: string;
+    trigger_policy: string;
+    success_criteria: string[];
+    interaction_policy: string;
+    feedback_policy: string;
+    evolution_policy: string;
+    evaluator_policy: string[];
+    schema_version?: "peaks.loop/1" | undefined;
+    shareable?: boolean | undefined;
+    share_excluded_paths?: string[] | undefined;
+    desktop_visible?: boolean | undefined;
+    export_bundle_format?: "peaks.bundle/1" | undefined;
+    linked_bees?: string[] | undefined;
+    run_history?: string[] | undefined;
+    crystallization_evidence?: string[] | undefined;
+}>;
+export type LoopRelease = z.infer<typeof LoopReleaseSchema>;
+/**
+ * Convenience: strict-parse an unknown payload into a LoopRelease row.
+ * Throws ZodError on failure. This is the public validation boundary.
+ */
+export declare function parseLoopRelease(input: unknown): LoopRelease;
+/**
+ * Convenience: safe-parse that returns a Result-like shape so callers
+ * (CLI layer in M5) can render findings without try/catch noise.
+ */
+export declare function safeParseLoopRelease(input: unknown): {
+    ok: true;
+    row: LoopRelease;
+} | {
+    ok: false;
+    findings: Array<{
+        path: string;
+        message: string;
+    }>;
+};

package/dist/services/loop/loop-release-types.js

@@ -0,0 +1,162 @@
+import { z } from "zod";
+/**
+ * LoopRelease — spec §4.1 (Loop Engineering Asset).
+ *
+ * M1 scope was the §4.1 fields. M3 (this slice) ADDS the share /
+ * desktop extension fields from §4.1 / §7A:
+ *   - shareable              (boolean, default true)
+ *   - share_excluded_paths   (string[], default [])
+ *   - desktop_visible        (boolean, default true)
+ *   - export_bundle_format   ('peaks.bundle/1', CLI-written constant)
+ *
+ * The four M3 fields are added with `.default(...)` so an in-memory
+ * object built from a pre-M3 snapshot still parses after the
+ * migration runs. NO enforcement on `shareable=false` is added in M3
+ * — the schema-only addition is the contract; full export /
+ * desktop enforcement lands in M7 (see plan
+ * m3-bee-release-extension.md and spec §7A).
+ *
+ * Field semantics — see the spec for full prose. Highlights:
+ *
+ *   - `id` is the stable kebab-case loop id; the storage key.
+ *   - `schema_version` is the constant literal `"peaks.loop/1"`; a
+ *     schema-version bump requires a new table / new enum case and a
+ *     migration — never edit this literal in place.
+ *   - `lifecycle_status` is `candidate` / `stable` / `retired`; the
+ *     default on first crystallization is `candidate`. LLMs cannot
+ *     auto-promote to `stable` (see spec §5.6).
+ *   - `linked_bees` is a denormalized pointer list of bee ids; the
+ *     authoritative loop↔bee relations live in `loop_bee_relation`
+ *     (M2). Keeping it here matches the spec §4.1 row shape and lets
+ *     M1 readers iterate the loop without an extra join.
+ *   - `success_criteria` / `evaluator_policy` are NL strings, not
+ *     machine-checked predicates; the evaluator definitions live in
+ *     the M4 evolution layer.
+ *   - `share_excluded_paths` is a JSON-encoded TEXT column at the
+ *     SQLite layer; the Zod schema accepts a string[] and the store
+ *     does the JSON.stringify/parse boundary work. Matches the
+ *     existing `loop_release` style (success_criteria_json, …).
+ *   - `export_bundle_format` is pinned to the literal
+ *     `"peaks.bundle/1"` per the spec §7A.2 contract — no other
+ *     value is accepted in this schema version.
+ */
+export const LoopReleaseLifecycleStatusSchema = z.enum([
+    "candidate",
+    "stable",
+    "retired",
+]);
+/**
+ * The M3 share / desktop extension fields, listed for code-search /
+ * lint discoverability. They are now part of the schema (with safe
+ * defaults) — see `LoopReleaseM3ExtensionSchema` below.
+ *
+ *   - shareable: defaults to true.
+ *   - share_excluded_paths: string[] (defaults to []).
+ *   - desktop_visible: defaults to true.
+ *   - export_bundle_format: constant "peaks.bundle/1" (CLI-written).
+ */
+export const LOOP_RELEASE_M3_FIELDS = [
+    "shareable",
+    "share_excluded_paths",
+    "desktop_visible",
+    "export_bundle_format",
+];
+/**
+ * M3 share / desktop extension schema. Added to `LoopReleaseInputSchema`
+ * via `.extend(...)` so existing callers that omit these fields still
+ * parse — the Zod defaults below supply the spec values
+ * (true / [] / true / "peaks.bundle/1").
+ *
+ * `export_bundle_format` is pinned to a literal per spec §7A.2: the
+ * CLI is the only writer and only `"peaks.bundle/1"` is accepted. A
+ * schema-version bump is required to introduce another value.
+ */
+export const LoopReleaseM3ExtensionSchema = z.object({
+    shareable: z.boolean().default(true),
+    share_excluded_paths: z
+        .array(z.string().min(1).max(4096))
+        .default([]),
+    desktop_visible: z.boolean().default(true),
+    export_bundle_format: z
+        .literal("peaks.bundle/1")
+        .default("peaks.bundle/1"),
+});
+/**
+ * Zod schema for the create payload (LoopReleaseInput). Mirrors the
+ * §4.1 row shape; `schema_version` is defaulted (clients cannot
+ * override it) and `created_at` is not part of the input — the store
+ * stamps it from the server clock.
+ */
+export const LoopReleaseInputSchema = z
+    .object({
+    id: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, {
+        message: "id must be kebab-case starting with a lowercase letter (e.g. loop-onboarding-research)",
+    }),
+    name: z.string().min(1).max(200),
+    scenario: z.string().trim().min(1).max(4000),
+    trigger_policy: z.string().trim().min(1).max(2000),
+    success_criteria: z
+        .array(z.string().trim().min(1).max(1000))
+        .min(1, "success_criteria must list at least one declarative criterion"),
+    interaction_policy: z
+        .string()
+        .trim()
+        .min(1, "interaction_policy must declare human-NL-choice-only semantics")
+        .max(2000),
+    feedback_policy: z.string().trim().min(1).max(2000),
+    evolution_policy: z.string().trim().min(1).max(2000),
+    evaluator_policy: z.array(z.string().trim().min(1).max(1000)).min(1),
+    linked_bees: z.array(z.string().min(1).max(64)).default([]),
+    run_history: z.array(z.string().min(1).max(128)).default([]),
+    crystallization_evidence: z.array(z.string().min(1).max(128)).default([]),
+    lifecycle_status: LoopReleaseLifecycleStatusSchema,
+    version: z
+        .string()
+        .regex(/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/, {
+        message: "version must be a semver string (e.g. 0.1.0)",
+    }),
+})
+    .extend(LoopReleaseM3ExtensionSchema.shape);
+/**
+ * Full Zod schema for a LoopRelease row as persisted. Differs from the
+ * input schema only in that `schema_version` is exposed (and defaulted
+ * to the fixed literal). The literal constraint still rejects any
+ * client-supplied value other than `"peaks.loop/1"`; the default
+ * means omitting the key is fine and the output always carries the
+ * constant.
+ *
+ * We expose this as the canonical "row schema" used by lint and
+ * service.create/read paths.
+ */
+export const LoopReleaseSchema = LoopReleaseInputSchema.extend({
+    schema_version: z
+        .literal("peaks.loop/1")
+        .default("peaks.loop/1"),
+});
+/**
+ * Convenience: strict-parse an unknown payload into a LoopRelease row.
+ * Throws ZodError on failure. This is the public validation boundary.
+ */
+export function parseLoopRelease(input) {
+    return LoopReleaseSchema.parse(input);
+}
+/**
+ * Convenience: safe-parse that returns a Result-like shape so callers
+ * (CLI layer in M5) can render findings without try/catch noise.
+ */
+export function safeParseLoopRelease(input) {
+    const r = LoopReleaseSchema.safeParse(input);
+    if (r.success)
+        return { ok: true, row: r.data };
+    return {
+        ok: false,
+        findings: r.error.issues.map((i) => ({
+            path: i.path.join("."),
+            message: i.message,
+        })),
+    };
+}