peaks-loop 3.1.2 → 4.0.0-beta.10

package/dist/services/job/job-progress-store.js

@@ -0,0 +1,70 @@
+/**
+ * v3.1.2 — On-disk slice progress mirror.
+ *
+ * After each `peaks job checkpoint --state done`, the orchestrator writes
+ * `.peaks/_runtime/<sessionId>/job/<jid>/progress.json` so the next LLM
+ * turn (after compact or resume) can read it before any Bash call lands.
+ *
+ * Shape (schemaVersion 1):
+ *   {
+ *     jobId, done, total, currentSlice, lastCommitSha, updatedAt
+ *   }
+ *
+ * The `peaks code gate-step-08` hook reads this file in its case-1 path
+ * (job-shape.json says isJob=true) and surfaces `Next: slice #N+1 of M
+ * (<currentSlice>)` to stdout. The LLM cannot "wake up cold" — the
+ * next-slice context is mechanically injected on every Bash call.
+ *
+ * Karpathy §2 (Simplicity First): ~50 lines, single-purpose writer +
+ * reader. Schema is zod-validated on read so a stale on-disk copy
+ * from an earlier peaks-loop release fails loud (no silent fallback).
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { z } from 'zod';
+export const JOB_PROGRESS_SCHEMA_VERSION = 1;
+export const JobProgressSchema = z.object({
+    schemaVersion: z.literal(JOB_PROGRESS_SCHEMA_VERSION),
+    jobId: z.string(),
+    done: z.number().int().nonnegative(),
+    total: z.number().int().positive(),
+    currentSlice: z.string(),
+    lastCommitSha: z.string().nullable(),
+    updatedAt: z.string().datetime()
+});
+export function writeJobProgress(projectRoot, sessionId, input) {
+    const dir = join(projectRoot, '.peaks', '_runtime', sessionId, 'job', input.jobId);
+    mkdirSync(dir, { recursive: true });
+    const record = {
+        schemaVersion: JOB_PROGRESS_SCHEMA_VERSION,
+        jobId: input.jobId,
+        done: input.done,
+        total: input.total,
+        currentSlice: input.currentSlice,
+        lastCommitSha: input.lastCommitSha,
+        updatedAt: input.updatedAt ?? new Date().toISOString()
+    };
+    const path = join(dir, 'progress.json');
+    writeFileSync(path, JSON.stringify(record, null, 2) + '\n', 'utf8');
+    return record;
+}
+export function readJobProgress(projectRoot, sessionId, jobId) {
+    const path = join(projectRoot, '.peaks', '_runtime', sessionId, 'job', jobId, 'progress.json');
+    if (!existsSync(path)) {
+        throw new Error(`JobProgressStore: no progress for ${jobId} at ${path}`);
+    }
+    const raw = readFileSync(path, 'utf8');
+    return JobProgressSchema.parse(JSON.parse(raw));
+}
+export function tryReadJobProgress(projectRoot, sessionId, jobId) {
+    const path = join(projectRoot, '.peaks', '_runtime', sessionId, 'job', jobId, 'progress.json');
+    if (!existsSync(path))
+        return null;
+    try {
+        const raw = readFileSync(path, 'utf8');
+        return JobProgressSchema.parse(JSON.parse(raw));
+    }
+    catch { // TODO(g2): legacy silent catch — grace: 1 minor release (v2.14.0)
+        return null;
+    }
+}

package/dist/services/job/job-resource-snapshot.js

@@ -0,0 +1,75 @@
+import os from 'node:os';
+import { readdirSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Collects a coarse-grained snapshot of host + project resources.
+ * Numeric ranges are clamped to zod's domain — out-of-range values are clamped, not thrown,
+ * so callers can decide what to do.
+ */
+export function collectResourceSnapshot(jobDir) {
+    const cpus = os.cpus();
+    const loadAvg = (os.loadavg()[0] ?? 0) / (cpus.length || 1);
+    const cpuPercent = Math.max(0, Math.min(100, loadAvg * 100));
+    const totalMemMb = os.totalmem() / 1024 / 1024;
+    const freeMemMb = os.freemem() / 1024 / 1024;
+    const usedMemMb = Math.max(0, totalMemMb - freeMemMb);
+    const memMb = Math.round(usedMemMb);
+    const diskMb = dirSizeMb(jobDir);
+    // contextRatio is best-effort: pull from the same env-var the v2.13.0 auto-compact uses.
+    const envVal = process.env.CLAUDE_CONTEXT_USAGE_PERCENT;
+    const contextRatio = envVal ? Math.max(0, Math.min(1, Number(envVal) / 100)) : 0;
+    return {
+        capturedAt: new Date().toISOString(),
+        cpuPercent,
+        memMb,
+        diskMb,
+        contextRatio,
+    };
+}
+// Non-enumerable internal attachment for test-time access via
+// `collectResourceSnapshot.dirSizeMb`. NOT a public export — keeps
+// the prod module surface clean per PRD while still allowing
+// targeted AC-1/AC-2/AC-3 unit tests to drive `dirSizeMb` directly.
+Object.defineProperty(collectResourceSnapshot, 'dirSizeMb', {
+    value: dirSizeMb,
+    enumerable: false,
+    writable: false,
+    configurable: false,
+});
+/**
+ * Best-effort, non-recursive size of one directory level, in rounded megabytes.
+ *
+ * - Missing directory → 0.
+ * - Per-entry stat failures (race with deletion, EBUSY on Windows) → silently skipped.
+ * - When `opts.maxEntries` > 0 and the directory has more entries than the cap,
+ *   the returned value is a partial sum (a lower bound), and no further `stat`
+ *   calls are issued past the cap. Callers must treat the value as a lower bound.
+ * - `opts.maxEntries` defaults to 0 (unbounded, legacy behaviour).
+ *
+ * NOTE: when maxEntries > 0 and the directory contains more entries than the
+ * cap, this is a partial sum. Callers must treat the value as a lower bound.
+ */
+function dirSizeMb(dir, opts) {
+    const cap = opts?.maxEntries ?? 0;
+    let total = 0;
+    let index = 0;
+    try {
+        for (const name of readdirSync(dir)) {
+            if (cap > 0 && index >= cap)
+                break;
+            try {
+                total += statSync(join(dir, name)).size;
+            }
+            catch (e) {
+                // best-effort: missing entries (race with deletion) are silently skipped
+                void e;
+            }
+            index++;
+        }
+    }
+    catch (e) {
+        // best-effort: missing dir is treated as 0 bytes
+        void e;
+    }
+    return Math.round(total / 1024 / 1024);
+}

package/dist/services/loop/loop-bee-relation-service.d.ts

@@ -0,0 +1,107 @@
+import type Database from "better-sqlite3";
+import { ZodError } from "zod";
+import { type LoopBeeRelation, type LoopBeeRelationInput, type LoopBeeRelationRole } from "./loop-bee-relation-types.js";
+/**
+ * Domain error thrown by LoopBeeRelationService when an invariant is
+ * violated. The error code is machine-readable; the message is
+ * NL-friendly. The CLI layer (M5) maps these into user-facing prompts.
+ */
+export type LoopBeeRelationIntegrityErrorCode = "LOOP_RETIRED" | "DUP_RELATION" | "TWO_MAIN_BEES" | "FK_LOOP_NOT_FOUND" | "FK_BEE_NOT_FOUND";
+export declare class LoopBeeRelationIntegrityError extends Error {
+    readonly code: LoopBeeRelationIntegrityErrorCode;
+    readonly findings: ReadonlyArray<{
+        path: string;
+        message: string;
+    }>;
+    constructor(code: LoopBeeRelationIntegrityErrorCode, message: string, findings?: ReadonlyArray<{
+        path: string;
+        message: string;
+    }>);
+}
+/**
+ * LoopBeeRelationService — thin service over the loop_bee_relation
+ * store. M2 keeps the surface narrow: create / listByLoop / listByBee /
+ * updateRole / remove. Promotion, evaluation, and crystallization
+ * flows land in later slices.
+ *
+ * Integrity rules enforced here (spec §4.6 + RL-3):
+ *
+ *   1. The referenced loop_release row must exist (FK to loop_release.id).
+ *      — enforced at DB level (FK constraint).
+ *      — surfaced as FK_LOOP_NOT_FOUND for friendlier errors.
+ *
+ *   2. The referenced bee_release row must exist (FK to bee_release.id).
+ *      — enforced at DB level (FK constraint).
+ *      — surfaced as FK_BEE_NOT_FOUND for friendlier errors.
+ *
+ *   3. Cannot relate a bee to a retired loop.
+ *      — enforced in service by checking loop_release.lifecycle_status.
+ *      — Throws LoopBeeRelationIntegrityError(LOOP_RETIRED).
+ *
+ *   4. A loop cannot have two `main` bees.
+ *      — enforced at DB level via partial unique index.
+ *      — surfaced as TWO_MAIN_BEES for friendlier errors.
+ *
+ *   5. (loop_release_id, bee_release_id) must be unique per row.
+ *      — enforced at DB level (UNIQUE).
+ *      — surfaced as DUP_RELATION for friendlier errors.
+ *
+ * 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 LoopReleaseService pattern.
+ *
+ * All write paths re-validate the input via the Zod schema, mirroring
+ * the boundary-check discipline used elsewhere.
+ */
+export declare class LoopBeeRelationService {
+    private readonly db;
+    constructor(db: Database.Database);
+    /**
+     * Persist a new LoopBeeRelation row.
+     *
+     * Throws:
+     *   - ZodError if the input fails schema validation.
+     *   - LoopBeeRelationIntegrityError(LOOP_RETIRED) if the loop's
+     *     lifecycle_status is "retired".
+     *   - LoopBeeRelationIntegrityError(FK_LOOP_NOT_FOUND) if the loop
+     *     row does not exist.
+     *   - LoopBeeRelationIntegrityError(FK_BEE_NOT_FOUND) if the bee
+     *     row does not exist.
+     *   - LoopBeeRelationIntegrityError(DUP_RELATION) if a relation
+     *     for the same (loop, bee) already exists.
+     *   - LoopBeeRelationIntegrityError(TWO_MAIN_BEES) if a `main` row
+     *     already exists for the loop.
+     */
+    create(input: LoopBeeRelationInput): LoopBeeRelation;
+    /** Read a LoopBeeRelation row by id; returns undefined if absent. */
+    read(id: number): LoopBeeRelation | undefined;
+    /**
+     * List relations for a given loop. Filter by `role` when supplied.
+     */
+    listByLoop(opts: {
+        loop_release_id: string;
+        role?: LoopBeeRelationRole;
+    }): LoopBeeRelation[];
+    /**
+     * List relations for a given bee. Filter by `role` when supplied.
+     */
+    listByBee(opts: {
+        bee_release_id: number;
+        role?: LoopBeeRelationRole;
+    }): LoopBeeRelation[];
+    /**
+     * Update the role of an existing relation. The storage-level partial
+     * unique index on `main` re-asserts "at most one main per loop" if
+     * the new role is `main`. Returns the updated row or undefined if
+     * the id is absent.
+     */
+    updateRole(id: number, newRole: LoopBeeRelationRole): LoopBeeRelation | undefined;
+    /** Remove a relation by id. Returns true if a row was deleted. */
+    remove(id: number): boolean;
+}
+/**
+ * Convenience: re-export the Zod error class guard so callers can do
+ * `if (err instanceof ZodError)`. Avoids forcing every caller to import
+ * zod directly.
+ */
+export declare function isZodError(err: unknown): err is ZodError;

package/dist/services/loop/loop-bee-relation-service.js

@@ -0,0 +1,211 @@
+import { ZodError } from "zod";
+import { LoopBeeRelationSchema, } from "./loop-bee-relation-types.js";
+import { ensureLoopBeeRelationTable, insertLoopBeeRelation, listLoopBeeRelationsByLoop, listLoopBeeRelationsByBee, updateLoopBeeRelationRole, removeLoopBeeRelation, getLoopBeeRelation, } from "./loop-bee-relation-store.js";
+export class LoopBeeRelationIntegrityError extends Error {
+    code;
+    findings;
+    constructor(code, message, findings = []) {
+        super(message);
+        this.name = "LoopBeeRelationIntegrityError";
+        this.code = code;
+        this.findings = findings;
+    }
+}
+/**
+ * LoopBeeRelationService — thin service over the loop_bee_relation
+ * store. M2 keeps the surface narrow: create / listByLoop / listByBee /
+ * updateRole / remove. Promotion, evaluation, and crystallization
+ * flows land in later slices.
+ *
+ * Integrity rules enforced here (spec §4.6 + RL-3):
+ *
+ *   1. The referenced loop_release row must exist (FK to loop_release.id).
+ *      — enforced at DB level (FK constraint).
+ *      — surfaced as FK_LOOP_NOT_FOUND for friendlier errors.
+ *
+ *   2. The referenced bee_release row must exist (FK to bee_release.id).
+ *      — enforced at DB level (FK constraint).
+ *      — surfaced as FK_BEE_NOT_FOUND for friendlier errors.
+ *
+ *   3. Cannot relate a bee to a retired loop.
+ *      — enforced in service by checking loop_release.lifecycle_status.
+ *      — Throws LoopBeeRelationIntegrityError(LOOP_RETIRED).
+ *
+ *   4. A loop cannot have two `main` bees.
+ *      — enforced at DB level via partial unique index.
+ *      — surfaced as TWO_MAIN_BEES for friendlier errors.
+ *
+ *   5. (loop_release_id, bee_release_id) must be unique per row.
+ *      — enforced at DB level (UNIQUE).
+ *      — surfaced as DUP_RELATION for friendlier errors.
+ *
+ * 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 LoopReleaseService pattern.
+ *
+ * All write paths re-validate the input via the Zod schema, mirroring
+ * the boundary-check discipline used elsewhere.
+ */
+export class LoopBeeRelationService {
+    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.
+        ensureLoopBeeRelationTable(this.db);
+    }
+    /**
+     * Persist a new LoopBeeRelation row.
+     *
+     * Throws:
+     *   - ZodError if the input fails schema validation.
+     *   - LoopBeeRelationIntegrityError(LOOP_RETIRED) if the loop's
+     *     lifecycle_status is "retired".
+     *   - LoopBeeRelationIntegrityError(FK_LOOP_NOT_FOUND) if the loop
+     *     row does not exist.
+     *   - LoopBeeRelationIntegrityError(FK_BEE_NOT_FOUND) if the bee
+     *     row does not exist.
+     *   - LoopBeeRelationIntegrityError(DUP_RELATION) if a relation
+     *     for the same (loop, bee) already exists.
+     *   - LoopBeeRelationIntegrityError(TWO_MAIN_BEES) if a `main` row
+     *     already exists for the loop.
+     */
+    create(input) {
+        const parsed = LoopBeeRelationSchema.omit({
+            id: true,
+            created_at: true,
+        }).parse(input);
+        // (a) Verify the loop_release row exists and is not retired.
+        const loopRow = this.db
+            .prepare("SELECT lifecycle_status FROM loop_release WHERE id = ?")
+            .get(parsed.loop_release_id);
+        if (!loopRow) {
+            throw new LoopBeeRelationIntegrityError("FK_LOOP_NOT_FOUND", `loop_release row '${parsed.loop_release_id}' does not exist`, [{ path: "loop_release_id", message: "loop_release row not found" }]);
+        }
+        if (loopRow.lifecycle_status === "retired") {
+            throw new LoopBeeRelationIntegrityError("LOOP_RETIRED", `cannot relate bee to retired loop '${parsed.loop_release_id}'`, [
+                {
+                    path: "loop_release_id",
+                    message: "loop_release.lifecycle_status is 'retired'; retirement severs new relations",
+                },
+            ]);
+        }
+        // (b) Verify the bee_release row exists.
+        const beeRow = this.db
+            .prepare("SELECT id FROM bee_release WHERE id = ?")
+            .get(parsed.bee_release_id);
+        if (!beeRow) {
+            throw new LoopBeeRelationIntegrityError("FK_BEE_NOT_FOUND", `bee_release row ${parsed.bee_release_id} does not exist`, [
+                {
+                    path: "bee_release_id",
+                    message: "bee_release row not found",
+                },
+            ]);
+        }
+        // (c) Insert; the storage-layer partial unique index will raise
+        // SQLITE_CONSTRAINT if (a) another `main` row exists for this
+        // loop, or (b) the same (loop, bee) pair already exists. Map those
+        // to friendly error codes.
+        try {
+            return insertLoopBeeRelation(this.db, parsed);
+        }
+        catch (err) {
+            const code = typeof err === "object" && err !== null && "code" in err
+                ? err.code
+                : undefined;
+            // Partial unique index on (loop_release_id) WHERE role='main'.
+            // better-sqlite3 surfaces this as SQLITE_CONSTRAINT_UNIQUE with
+            // a message naming only `loop_bee_relation.loop_release_id`
+            // (the column the partial index covers), NOT the index name.
+            // It is distinguished from the (loop_release_id, bee_release_id)
+            // composite UNIQUE violation by the absence of bee_release_id
+            // in the message.
+            if (code === "SQLITE_CONSTRAINT_UNIQUE") {
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg.includes("loop_bee_relation.bee_release_id")) {
+                    // Composite UNIQUE(loop_release_id, bee_release_id).
+                    throw new LoopBeeRelationIntegrityError("DUP_RELATION", `relation between loop '${parsed.loop_release_id}' and bee ${parsed.bee_release_id} already exists`, [
+                        {
+                            path: "loop_release_id,bee_release_id",
+                            message: "duplicate relation",
+                        },
+                    ]);
+                }
+                // Otherwise: partial unique index on (loop_release_id) WHERE role='main'.
+                throw new LoopBeeRelationIntegrityError("TWO_MAIN_BEES", `loop '${parsed.loop_release_id}' already has a main bee`, [
+                    {
+                        path: "role",
+                        message: "at most one main bee per loop; promote / retire the existing main first",
+                    },
+                ]);
+            }
+            // FK violations from better-sqlite3 (foreign_keys = ON).
+            if (code === "SQLITE_CONSTRAINT_FOREIGNKEY") {
+                // Distinguish by re-checking which row is missing; the friendly
+                // pre-check above should have caught these, but defense in depth.
+                const loopStill = this.db
+                    .prepare("SELECT 1 FROM loop_release WHERE id = ?")
+                    .get(parsed.loop_release_id);
+                if (!loopStill) {
+                    throw new LoopBeeRelationIntegrityError("FK_LOOP_NOT_FOUND", `loop_release row '${parsed.loop_release_id}' does not exist`, [{ path: "loop_release_id", message: "FK violation" }]);
+                }
+                throw new LoopBeeRelationIntegrityError("FK_BEE_NOT_FOUND", `bee_release row ${parsed.bee_release_id} does not exist`, [{ path: "bee_release_id", message: "FK violation" }]);
+            }
+            // Re-throw unexpected errors unchanged.
+            throw err;
+        }
+    }
+    /** Read a LoopBeeRelation row by id; returns undefined if absent. */
+    read(id) {
+        return getLoopBeeRelation(this.db, id);
+    }
+    /**
+     * List relations for a given loop. Filter by `role` when supplied.
+     */
+    listByLoop(opts) {
+        return listLoopBeeRelationsByLoop(this.db, opts.loop_release_id, opts.role);
+    }
+    /**
+     * List relations for a given bee. Filter by `role` when supplied.
+     */
+    listByBee(opts) {
+        return listLoopBeeRelationsByBee(this.db, opts.bee_release_id, opts.role);
+    }
+    /**
+     * Update the role of an existing relation. The storage-level partial
+     * unique index on `main` re-asserts "at most one main per loop" if
+     * the new role is `main`. Returns the updated row or undefined if
+     * the id is absent.
+     */
+    updateRole(id, newRole) {
+        // The TS type already enforces the four-value union. Try update;
+        // if partial unique index trips, raise friendly error.
+        try {
+            return updateLoopBeeRelationRole(this.db, id, newRole);
+        }
+        catch (err) {
+            const code = typeof err === "object" && err !== null && "code" in err
+                ? err.code
+                : undefined;
+            if (code === "SQLITE_CONSTRAINT_UNIQUE") {
+                const existing = getLoopBeeRelation(this.db, id);
+                const loopId = existing?.loop_release_id ?? "<unknown>";
+                throw new LoopBeeRelationIntegrityError("TWO_MAIN_BEES", `loop '${loopId}' already has a main bee`, [{ path: "role", message: "at most one main bee per loop" }]);
+            }
+            throw err;
+        }
+    }
+    /** Remove a relation by id. Returns true if a row was deleted. */
+    remove(id) {
+        return removeLoopBeeRelation(this.db, id);
+    }
+}
+/**
+ * Convenience: re-export the Zod error class guard so callers can do
+ * `if (err instanceof ZodError)`. Avoids forcing every caller to import
+ * zod directly.
+ */
+export function isZodError(err) {
+    return err instanceof ZodError;
+}

package/dist/services/loop/loop-bee-relation-store.d.ts

@@ -0,0 +1,53 @@
+import type Database from "better-sqlite3";
+import type { LoopBeeRelation, LoopBeeRelationRole } from "./loop-bee-relation-types.js";
+/**
+ * Low-level SQLite access for the `loop_bee_relation` table. The
+ * migration is registered with the existing `openStateDb()` pipeline
+ * via `src/services/skillhub/migrations/003-loop-bee-relation.sql`
+ * (it applies every `*.sql` file in lexicographic order). The function
+ * `ensureLoopBeeRelationTable` below is a belt-and-suspenders re-applier
+ * for callers that pass a database they built themselves (e.g. tests).
+ *
+ * Defense in depth:
+ *   - FK constraints enforce loop_release and bee_release referential
+ *     integrity (better-sqlite3 + foreign_keys = ON).
+ *   - Partial unique index `WHERE role = 'main'` enforces "at most one
+ *     main bee per loop" at the storage layer (the service layer adds
+ *     a friendlier error path on top).
+ *   - UNIQUE (loop_release_id, bee_release_id) prevents accidental
+ *     duplicate relations between the same loop and same bee release.
+ *   - The migration does NOT touch any 4.x `bee_release` column (AC-3).
+ *   - Lifecycle_status check on loop_release is NOT a DB-level constraint
+ *     (the retirement rule is enforced in the service layer — see
+ *     `LoopBeeRelationService.create`) so the DB stays decoupled from
+ *     cross-table policies that need richer error reporting.
+ */
+/**
+ * Re-apply the loop_bee_relation table migration against an already-open
+ * database. Used by tests that build their own DB without the
+ * openStateDb pipeline. Idempotent.
+ */
+export declare function ensureLoopBeeRelationTable(db: Database.Database): void;
+/**
+ * Insert a LoopBeeRelation row. The row's `schema_version` is taken from
+ * the input (must equal `peaks.loop-bee-relation/1`); `id` and
+ * `created_at` are stamped here, so callers cannot backdate a row.
+ *
+ * Idempotent in the UNIQUE sense — re-inserting the same
+ * (loop_release_id, bee_release_id) pair throws a UNIQUE-constraint
+ * error; inserting two `main` rows for the same loop throws a partial
+ * unique index error.
+ *
+ * Returns the persisted row (with `id` filled in).
+ */
+export declare function insertLoopBeeRelation(db: Database.Database, row: Omit<LoopBeeRelation, "id" | "created_at">): LoopBeeRelation;
+/** Read a single LoopBeeRelation row by id; returns undefined if absent. */
+export declare function getLoopBeeRelation(db: Database.Database, id: number): LoopBeeRelation | undefined;
+/** List LoopBeeRelation rows for a given loop_release_id (optionally filtered by role). */
+export declare function listLoopBeeRelationsByLoop(db: Database.Database, loop_release_id: string, role?: LoopBeeRelationRole): LoopBeeRelation[];
+/** List LoopBeeRelation rows for a given bee_release_id (optionally filtered by role). */
+export declare function listLoopBeeRelationsByBee(db: Database.Database, bee_release_id: number, role?: LoopBeeRelationRole): LoopBeeRelation[];
+/** Update the role of an existing relation. Returns the new row, or undefined if absent. */
+export declare function updateLoopBeeRelationRole(db: Database.Database, id: number, newRole: LoopBeeRelationRole): LoopBeeRelation | undefined;
+/** Remove a LoopBeeRelation row by id. Returns true if a row was deleted. */
+export declare function removeLoopBeeRelation(db: Database.Database, id: number): boolean;

package/dist/services/loop/loop-bee-relation-store.js

@@ -0,0 +1,130 @@
+/**
+ * Low-level SQLite access for the `loop_bee_relation` table. The
+ * migration is registered with the existing `openStateDb()` pipeline
+ * via `src/services/skillhub/migrations/003-loop-bee-relation.sql`
+ * (it applies every `*.sql` file in lexicographic order). The function
+ * `ensureLoopBeeRelationTable` below is a belt-and-suspenders re-applier
+ * for callers that pass a database they built themselves (e.g. tests).
+ *
+ * Defense in depth:
+ *   - FK constraints enforce loop_release and bee_release referential
+ *     integrity (better-sqlite3 + foreign_keys = ON).
+ *   - Partial unique index `WHERE role = 'main'` enforces "at most one
+ *     main bee per loop" at the storage layer (the service layer adds
+ *     a friendlier error path on top).
+ *   - UNIQUE (loop_release_id, bee_release_id) prevents accidental
+ *     duplicate relations between the same loop and same bee release.
+ *   - The migration does NOT touch any 4.x `bee_release` column (AC-3).
+ *   - Lifecycle_status check on loop_release is NOT a DB-level constraint
+ *     (the retirement rule is enforced in the service layer — see
+ *     `LoopBeeRelationService.create`) so the DB stays decoupled from
+ *     cross-table policies that need richer error reporting.
+ */
+/**
+ * Re-apply the loop_bee_relation table migration against an already-open
+ * database. Used by tests that build their own DB without the
+ * openStateDb pipeline. Idempotent.
+ */
+export function ensureLoopBeeRelationTable(db) {
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS loop_bee_relation (
+      id                INTEGER PRIMARY KEY AUTOINCREMENT,
+      loop_release_id   TEXT NOT NULL REFERENCES loop_release(id) ON DELETE CASCADE,
+      bee_release_id    INTEGER NOT NULL REFERENCES bee_release(id) ON DELETE CASCADE,
+      role              TEXT NOT NULL CHECK (role IN ('main','supporting','candidate','retired')),
+      reason            TEXT NOT NULL,
+      schema_version    TEXT NOT NULL CHECK (schema_version = 'peaks.loop-bee-relation/1'),
+      created_at        TEXT NOT NULL,
+      UNIQUE(loop_release_id, bee_release_id)
+    );
+    CREATE INDEX IF NOT EXISTS idx_loop_bee_relation_loop_id ON loop_bee_relation(loop_release_id);
+    CREATE INDEX IF NOT EXISTS idx_loop_bee_relation_bee_id ON loop_bee_relation(bee_release_id);
+    CREATE INDEX IF NOT EXISTS idx_loop_bee_relation_loop_role ON loop_bee_relation(loop_release_id, role);
+    -- Partial unique index: at most one main bee per loop. SQLite supports
+    -- partial indexes; this is the storage-level enforcement of the
+    -- "exactly one main" invariant. Multiple supporting / candidate /
+    -- retired rows per loop remain allowed.
+    CREATE UNIQUE INDEX IF NOT EXISTS idx_loop_bee_relation_one_main_per_loop
+      ON loop_bee_relation(loop_release_id) WHERE role = 'main';
+  `);
+}
+function rowToLoopBeeRelation(row) {
+    return {
+        id: row.id,
+        loop_release_id: row.loop_release_id,
+        bee_release_id: row.bee_release_id,
+        role: row.role,
+        reason: row.reason,
+        schema_version: row.schema_version,
+        created_at: row.created_at,
+    };
+}
+/**
+ * Insert a LoopBeeRelation row. The row's `schema_version` is taken from
+ * the input (must equal `peaks.loop-bee-relation/1`); `id` and
+ * `created_at` are stamped here, so callers cannot backdate a row.
+ *
+ * Idempotent in the UNIQUE sense — re-inserting the same
+ * (loop_release_id, bee_release_id) pair throws a UNIQUE-constraint
+ * error; inserting two `main` rows for the same loop throws a partial
+ * unique index error.
+ *
+ * Returns the persisted row (with `id` filled in).
+ */
+export function insertLoopBeeRelation(db, row) {
+    const createdAt = new Date().toISOString();
+    const stmt = db.prepare(`INSERT INTO loop_bee_relation (
+       loop_release_id, bee_release_id, role, reason, schema_version, created_at
+     ) VALUES (?, ?, ?, ?, ?, ?)`);
+    const info = stmt.run(row.loop_release_id, row.bee_release_id, row.role, row.reason, row.schema_version, createdAt);
+    return {
+        id: Number(info.lastInsertRowid),
+        loop_release_id: row.loop_release_id,
+        bee_release_id: row.bee_release_id,
+        role: row.role,
+        reason: row.reason,
+        schema_version: row.schema_version,
+        created_at: createdAt,
+    };
+}
+/** Read a single LoopBeeRelation row by id; returns undefined if absent. */
+export function getLoopBeeRelation(db, id) {
+    const row = db
+        .prepare("SELECT * FROM loop_bee_relation WHERE id = ?")
+        .get(id);
+    if (!row)
+        return undefined;
+    return rowToLoopBeeRelation(row);
+}
+/** List LoopBeeRelation rows for a given loop_release_id (optionally filtered by role). */
+export function listLoopBeeRelationsByLoop(db, loop_release_id, role) {
+    const sql = role === undefined
+        ? "SELECT * FROM loop_bee_relation WHERE loop_release_id = ? ORDER BY id ASC"
+        : "SELECT * FROM loop_bee_relation WHERE loop_release_id = ? AND role = ? ORDER BY id ASC";
+    const params = role === undefined ? [loop_release_id] : [loop_release_id, role];
+    const rows = db.prepare(sql).all(...params);
+    return rows.map(rowToLoopBeeRelation);
+}
+/** List LoopBeeRelation rows for a given bee_release_id (optionally filtered by role). */
+export function listLoopBeeRelationsByBee(db, bee_release_id, role) {
+    const sql = role === undefined
+        ? "SELECT * FROM loop_bee_relation WHERE bee_release_id = ? ORDER BY id ASC"
+        : "SELECT * FROM loop_bee_relation WHERE bee_release_id = ? AND role = ? ORDER BY id ASC";
+    const params = role === undefined ? [bee_release_id] : [bee_release_id, role];
+    const rows = db.prepare(sql).all(...params);
+    return rows.map(rowToLoopBeeRelation);
+}
+/** Update the role of an existing relation. Returns the new row, or undefined if absent. */
+export function updateLoopBeeRelationRole(db, id, newRole) {
+    const stmt = db.prepare("UPDATE loop_bee_relation SET role = ? WHERE id = ?");
+    const info = stmt.run(newRole, id);
+    if (info.changes === 0)
+        return undefined;
+    return getLoopBeeRelation(db, id);
+}
+/** Remove a LoopBeeRelation row by id. Returns true if a row was deleted. */
+export function removeLoopBeeRelation(db, id) {
+    const stmt = db.prepare("DELETE FROM loop_bee_relation WHERE id = ?");
+    const info = stmt.run(id);
+    return info.changes > 0;
+}