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

package/dist/src/services/share/bundle-writer.js

@@ -0,0 +1,429 @@
+/**
+ * bundle-writer.ts — writeBundle(loopOrBeeId, outPath) (spec §7A.2).
+ *
+ * M7 / spec §7A.2 / §10 RL-9.
+ *
+ * Writes a `peaks.bundle/1` tar.gz that captures:
+ *
+ *   - One anchor asset: a loop_release (kind='loop') OR a single
+ *     bee_release (kind='bee'). A loop bundle additionally carries
+ *     related_bee_releases (all loop↔bee relations resolved) and
+ *     loop_bee_relations rows.
+ *   - All evidence_briefs (crystallization_event rows) that
+ *     reference the anchor (created_loop_release_id /
+ *     updated_loop_release_id / created_bee_release_id /
+ *     updated_bee_release_id).
+ *
+ * Hard rules enforced at THIS layer:
+ *
+ *   - The source release MUST have `shareable !== false`. A
+ *     `shareable=false` source THROWS
+ *     `SHARE_BUNDLE_NOT_SHAREABLE` BEFORE the tarball is written.
+ *     The CLI layer is the canonical gate (per spec §7A.2 /
+ *     §10 RL-9); the writer enforces the same gate at the
+ *     service boundary for defense in depth.
+ *   - The bundle NEVER captures private run_state, the personal
+ *     `.peaks/memory/personal/` directory, or raw `state.db`
+ *     rows. The exclusion is declared in the manifest's
+ *     `exclusion_manifest` field; physically, the writer only
+ *     pulls rows from the structured tables.
+ *   - The bundle is a tarball whose root contains `manifest.json`,
+ *     `relations.json`, `evidence_briefs/*.json`, and
+ *     `blobs/<sha256>` content-addressed blobs (mirroring the
+ *     SkillHub release pattern).
+ *
+ * The writer runs `tar -czf <outPath> -C <stageDir> .` exactly the
+ * same way `release-export.ts` does — same layout, same tar
+ * invocation, so the `bundle-reader.ts` symmetrical side can
+ * extract via `runTar(['-xzf', inPath, '-C', stageDir])` with no
+ * extra plumbing.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync, rmSync, } from "node:fs";
+import { join } from "node:path";
+import { runTar } from "../skillhub/tar-runtime.js";
+import { PEAKS_BUNDLE_DEFAULT_MINOR_VERSION, PEAKS_BUNDLE_FORMAT_CONSTANT, PEAKS_BUNDLE_FORMAT_VERSION_MAJOR, PEAKS_BUNDLE_SCHEMA_VERSIONS, SHARE_BUNDLE_ERROR_CODES, } from "./bundle-types.js";
+/* ---------------------------------------------------------------------- */
+/* Hard-block errors                                                        */
+/* ---------------------------------------------------------------------- */
+/**
+ * Thrown when the source release has `shareable === false`. The
+ * writer throws BEFORE any tarball work; the CLI layer surfaces
+ * `code = SHARE_BUNDLE_NOT_SHAREABLE`.
+ */
+export class BundleNotShareableError extends Error {
+    code;
+    constructor(message) {
+        super(message);
+        this.name = "BundleNotShareableError";
+        this.code = SHARE_BUNDLE_ERROR_CODES.NOT_SHAREABLE;
+    }
+}
+/**
+ * Thrown when the writer cannot locate the source asset (loop id
+ * not present in `loop_release`, or bee_release.id not present).
+ * Includes both `LOOP_NOT_FOUND` and `BEE_NOT_FOUND` flavors —
+ * both fall under `BUNDLE_ASSET_NOT_FOUND` for the CLI envelope.
+ */
+export class BundleAssetNotFoundError extends Error {
+    code;
+    assetKind;
+    assetId;
+    constructor(assetKind, assetId) {
+        super(`${assetKind} asset not found for id='${String(assetId)}'`);
+        this.name = "BundleAssetNotFoundError";
+        this.code = "BUNDLE_ASSET_NOT_FOUND";
+        this.assetKind = assetKind;
+        this.assetId = assetId;
+    }
+}
+/* ---------------------------------------------------------------------- */
+/* Manifest builder                                                         */
+/* ---------------------------------------------------------------------- */
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Internal: extract a serialized LoopRelease row ready for the
+ * bundle manifest. The writer does NOT validate with
+ * `LoopReleaseSchema` at write time — the source row was already
+ * validated when it was written to the DB; the reader validates
+ * on the way back in.
+ */
+function readLoopReleaseRow(db, id) {
+    const row = db.prepare("SELECT * FROM loop_release WHERE id = ?").get(id);
+    if (!row)
+        return undefined;
+    // Re-shape SQLite 0/1 INTEGER convention to JS boolean; keep
+    // JSON-shaped columns as their parsed-text representation so the
+    // JSON.stringify round-trip preserves fidelity.
+    return {
+        id: row.id,
+        name: row.name,
+        scenario: row.scenario,
+        trigger_policy: row.trigger_policy,
+        success_criteria: JSON.parse(String(row.success_criteria_json ?? "[]")),
+        interaction_policy: row.interaction_policy,
+        feedback_policy: row.feedback_policy,
+        evolution_policy: row.evolution_policy,
+        evaluator_policy: JSON.parse(String(row.evaluator_policy_json ?? "[]")),
+        linked_bees: JSON.parse(String(row.linked_bees_json ?? "[]")),
+        run_history: JSON.parse(String(row.run_history_json ?? "[]")),
+        crystallization_evidence: JSON.parse(String(row.crystallization_evidence_json ?? "[]")),
+        lifecycle_status: row.lifecycle_status,
+        version: row.version,
+        schema_version: row.schema_version,
+        archived_at: row.archived_at,
+        shareable: row.shareable === 1,
+        share_excluded_paths: JSON.parse(String(row.share_excluded_paths ?? "[]")),
+        desktop_visible: row.desktop_visible === 1,
+        export_bundle_format: row.export_bundle_format,
+    };
+}
+/**
+ * Internal: read a single `bee_release` row + its relations/segments/files
+ * for the bundle manifest. Mirrors the existing
+ * `src/services/skillhub/release-export.ts` shape — the writer
+ * includes `bee_release`, plus the inline manifest/segment/file/change
+ * rows so the receiver can re-materialize the full bee.
+ */
+function readBeeReleaseBundle(db, id) {
+    const release = db
+        .prepare("SELECT * FROM bee_release WHERE id = ?")
+        .get(id);
+    if (!release)
+        return undefined;
+    const manifest = db
+        .prepare("SELECT * FROM bee_manifest WHERE release_id = ?")
+        .get(id);
+    const segments = db
+        .prepare("SELECT * FROM bee_segment_ref WHERE release_id = ?")
+        .all(id);
+    const files = db
+        .prepare("SELECT * FROM bee_file WHERE release_id = ?")
+        .all(id);
+    const changes = db
+        .prepare("SELECT * FROM bee_change WHERE release_id = ?")
+        .all(id);
+    return {
+        bee_release: release,
+        manifest,
+        segments,
+        files,
+        changes,
+    };
+}
+/**
+ * Internal: read loop_bee_relation rows for a given loop.
+ */
+function readLoopBeeRelationsForLoop(db, loopId) {
+    return db
+        .prepare("SELECT * FROM loop_bee_relation WHERE loop_release_id = ? ORDER BY id ASC")
+        .all(loopId);
+}
+/**
+ * Internal: read loop_bee_relation rows for a given bee.
+ */
+function readLoopBeeRelationsForBee(db, beeReleaseId) {
+    return db
+        .prepare("SELECT * FROM loop_bee_relation WHERE bee_release_id = ? ORDER BY id ASC")
+        .all(beeReleaseId);
+}
+/**
+ * Internal: read evidence briefs (crystallization_event rows) that
+ * reference a given loop / bee. Includes both created_* and
+ * updated_* FK pointers so any crystallization event that touched
+ * the asset is captured.
+ */
+function readEvidenceBriefsForAsset(db, refs) {
+    const wheres = [];
+    const params = [];
+    if (refs.loopId !== undefined) {
+        wheres.push("created_loop_release_id = ?");
+        params.push(refs.loopId);
+        wheres.push("updated_loop_release_id = ?");
+        params.push(refs.loopId);
+    }
+    if (refs.beeReleaseId !== undefined) {
+        wheres.push("created_bee_release_id = ?");
+        params.push(refs.beeReleaseId);
+        wheres.push("updated_bee_release_id = ?");
+        params.push(refs.beeReleaseId);
+    }
+    if (wheres.length === 0)
+        return [];
+    const whereSql = wheres.join(" OR ");
+    const rows = db
+        .prepare(`SELECT * FROM crystallization_event WHERE ${whereSql} ORDER BY created_at DESC`)
+        .all(...params);
+    return rows.map((row) => ({
+        id: row.id,
+        trigger: row.trigger,
+        evidence_brief: JSON.parse(String(row.evidence_brief_json ?? "{}")),
+        evidence_bullets: JSON.parse(String(row.evidence_bullets_json ?? "[]")),
+        source_trace_pointers: JSON.parse(String(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,
+    }));
+}
+/* eslint-enable @typescript-eslint/no-explicit-any */
+/* ---------------------------------------------------------------------- */
+/* Main entrypoint                                                           */
+/* ---------------------------------------------------------------------- */
+/**
+ * Write a `peaks.bundle/1` tar.gz to `outPath`. The bundle
+ * captures ONE anchor asset (`loop` or `bee`) plus its relations,
+ * supporting bees (loop kind only), and evidence briefs.
+ *
+ * Hard blocks raised at THIS layer:
+ *
+ *   - `BundleNotShareableError`: the source has `shareable === false`.
+ *   - `BundleAssetNotFoundError`: the source id was not present in the table.
+ *
+ * On success the call returns the resolved asset id and kind; the
+ * CLI layer uses this to render a one-line status.
+ */
+export function writeBundle(args) {
+    const { db, blobsDir, outPath } = args;
+    if (args.kind === "loop") {
+        return writeLoopBundle({
+            db,
+            blobsDir,
+            loopId: String(args.id),
+            outPath,
+        });
+    }
+    return writeBeeBundle({
+        db,
+        blobsDir,
+        beeReleaseId: typeof args.id === "number" ? args.id : Number(args.id),
+        outPath,
+    });
+}
+/* ---------------------------------------------------------------------- */
+/* Loop bundle writer                                                        */
+/* ---------------------------------------------------------------------- */
+function writeLoopBundle(args) {
+    const loopRow = args.db
+        .prepare("SELECT * FROM loop_release WHERE id = ?")
+        .get(args.loopId);
+    if (!loopRow)
+        throw new BundleAssetNotFoundError("loop", args.loopId);
+    // spec §7A.2 hard block: shareable=false blocks the export at the
+    // CLI layer. We re-enforce at the writer for defense in depth.
+    if (loopRow.shareable === 0) {
+        throw new BundleNotShareableError(`loop_release '${args.loopId}' has shareable=false; bundles cannot be exported for non-shareable assets (spec §7A.2)`);
+    }
+    const loop = readLoopReleaseRow(args.db, args.loopId);
+    if (!loop)
+        throw new BundleAssetNotFoundError("loop", args.loopId);
+    const relations = readLoopBeeRelationsForLoop(args.db, args.loopId);
+    const relatedBees = [];
+    const blobHashes = new Set();
+    for (const rel of relations) {
+        const beeId = Number(rel.bee_release_id);
+        const bee = readBeeReleaseBundle(args.db, beeId);
+        if (bee) {
+            relatedBees.push(bee);
+            // Pull every content-addressed sha256 across all bee_files rows.
+            for (const f of bee.files) {
+                const sha = String(f.sha256 ?? "");
+                if (sha)
+                    blobHashes.add(sha);
+            }
+        }
+    }
+    const evidenceBriefs = readEvidenceBriefsForAsset(args.db, {
+        loopId: args.loopId,
+    });
+    const manifest = {
+        format_constant: PEAKS_BUNDLE_FORMAT_CONSTANT,
+        format_version_major: PEAKS_BUNDLE_FORMAT_VERSION_MAJOR,
+        format_version_minor: PEAKS_BUNDLE_DEFAULT_MINOR_VERSION,
+        schema_versions: {
+            loop: PEAKS_BUNDLE_SCHEMA_VERSIONS.loop,
+            bee: PEAKS_BUNDLE_SCHEMA_VERSIONS.bee,
+            loop_bee_relation: PEAKS_BUNDLE_SCHEMA_VERSIONS.loop_bee_relation,
+            crystallization: PEAKS_BUNDLE_SCHEMA_VERSIONS.crystallization,
+        },
+        kind: "loop",
+        loop_release: loop,
+        bee_release: undefined,
+        related_bee_releases: relatedBees,
+        loop_bee_relations: relations,
+        evidence_briefs: evidenceBriefs,
+        exclusion_manifest: {
+            private_run_state: "excluded",
+            personal_memory: "excluded",
+            state_db_rows: "excluded",
+        },
+    };
+    runStageTarball({
+        outPath: args.outPath,
+        blobsDir: args.blobsDir,
+        blobHashes,
+        manifest,
+    });
+    return { outPath: args.outPath, kind: "loop", assetId: args.loopId };
+}
+/* ---------------------------------------------------------------------- */
+/* Bee bundle writer                                                         */
+/* ---------------------------------------------------------------------- */
+function writeBeeBundle(args) {
+    const releaseRow = args.db
+        .prepare("SELECT * FROM bee_release WHERE id = ?")
+        .get(args.beeReleaseId);
+    if (!releaseRow)
+        throw new BundleAssetNotFoundError("bee", args.beeReleaseId);
+    // spec §7A.2 hard block: same as loop kind.
+    if (releaseRow.shareable === 0) {
+        throw new BundleNotShareableError(`bee_release id='${args.beeReleaseId}' has shareable=false; bundles cannot be exported for non-shareable assets (spec §7A.2)`);
+    }
+    const bee = readBeeReleaseBundle(args.db, args.beeReleaseId);
+    if (!bee)
+        throw new BundleAssetNotFoundError("bee", args.beeReleaseId);
+    const relations = readLoopBeeRelationsForBee(args.db, args.beeReleaseId);
+    const evidenceBriefs = readEvidenceBriefsForAsset(args.db, {
+        beeReleaseId: args.beeReleaseId,
+    });
+    const blobHashes = new Set();
+    for (const f of bee.files) {
+        const sha = String(f.sha256 ?? "");
+        if (sha)
+            blobHashes.add(sha);
+    }
+    const manifest = {
+        format_constant: PEAKS_BUNDLE_FORMAT_CONSTANT,
+        format_version_major: PEAKS_BUNDLE_FORMAT_VERSION_MAJOR,
+        format_version_minor: PEAKS_BUNDLE_DEFAULT_MINOR_VERSION,
+        schema_versions: {
+            loop: PEAKS_BUNDLE_SCHEMA_VERSIONS.loop,
+            bee: PEAKS_BUNDLE_SCHEMA_VERSIONS.bee,
+            loop_bee_relation: PEAKS_BUNDLE_SCHEMA_VERSIONS.loop_bee_relation,
+            crystallization: PEAKS_BUNDLE_SCHEMA_VERSIONS.crystallization,
+        },
+        kind: "bee",
+        loop_release: undefined,
+        bee_release: bee,
+        related_bee_releases: [],
+        loop_bee_relations: relations,
+        evidence_briefs: evidenceBriefs,
+        exclusion_manifest: {
+            private_run_state: "excluded",
+            personal_memory: "excluded",
+            state_db_rows: "excluded",
+        },
+    };
+    runStageTarball({
+        outPath: args.outPath,
+        blobsDir: args.blobsDir,
+        blobHashes,
+        manifest,
+    });
+    return { outPath: args.outPath, kind: "bee", assetId: args.beeReleaseId };
+}
+/* ---------------------------------------------------------------------- */
+/* Stage tarball — write the directory, then tar.gz it.                     */
+/* ---------------------------------------------------------------------- */
+function runStageTarball(args) {
+    const { outPath, blobsDir, blobHashes, manifest } = args;
+    const stageDir = outPath + ".stage";
+    if (existsSync(stageDir))
+        rmSync(stageDir, { recursive: true, force: true });
+    mkdirSync(stageDir, { recursive: true });
+    let tarOk = false;
+    try {
+        writeFileSync(join(stageDir, "manifest.json"), JSON.stringify(manifest, null, 2));
+        mkdirSync(join(stageDir, "evidence_briefs"), { recursive: true });
+        for (const brief of manifest.evidence_briefs) {
+            const id = String(brief.id ?? Math.random().toString(16).slice(2));
+            writeFileSync(join(stageDir, "evidence_briefs", `${id}.json`), JSON.stringify(brief, null, 2));
+        }
+        writeFileSync(join(stageDir, "relations.json"), JSON.stringify({
+            loop_bee_relations: manifest.loop_bee_relations,
+            related_bee_releases: manifest.related_bee_releases,
+        }, null, 2));
+        // Copy content-addressed blobs (only ones the bundle actually
+        // references). The reader's blob re-materialisation
+        // (see bundle-reader.ts) uses the same content-addressed
+        // `blobs/<sha256>` layout as the existing SkillHub hashing.
+        if (blobHashes.size > 0) {
+            mkdirSync(join(stageDir, "blobs"), { recursive: true });
+            for (const sha of blobHashes) {
+                const src = join(blobsDir, sha.slice(0, 2), sha);
+                if (!existsSync(src))
+                    continue;
+                writeFileSync(join(stageDir, "blobs", sha), readFileSync(src));
+            }
+        }
+        // Write EVALUATION_REQUIRED.md — a marker that signals the
+        // receiver to run an independent evaluation before any durable
+        // change. Spec §7A.2 hard rules (5th bullet).
+        writeFileSync(join(stageDir, "EVALUATION_REQUIRED.md"), [
+            "# EVALUATION_REQUIRED",
+            "",
+            "The receiver MUST run an independent evaluation before",
+            "any durable change to this loop / bee. Bundles always",
+            "import as `candidate`; promotion to `stable` requires",
+            "an `evolution_evaluation` row with an",
+            "`independent_scorer_verdict` (spec §7A.2 / §10 RL-9).",
+            "",
+        ].join("\n"));
+        runTar(["-czf", outPath, "-C", stageDir, "."]);
+        tarOk = true;
+    }
+    finally {
+        if (existsSync(stageDir) && !tarOk) {
+            rmSync(stageDir, { recursive: true, force: true });
+        }
+        // Always remove the stage dir after tar succeeds too — the
+        // bundle lives entirely on disk at outPath.
+        if (tarOk && existsSync(stageDir)) {
+            rmSync(stageDir, { recursive: true, force: true });
+        }
+    }
+}

package/dist/src/services/share/run-state-contract.d.ts

@@ -0,0 +1,133 @@
+/**
+ * run-state-contract.ts — locked read-only shape for the desktop
+ * client (spec §7A.3 / §10 RL-9).
+ *
+ * The desktop client observes an in-flight bee through a single
+ * JSON file. This module locks the shape so the desktop can render
+ * progress without holding a lock on the asset:
+ *
+ *   {
+ *     bee_id:                    string,
+ *     status:                    "running" | "paused" | "done" | "failed" | "blocked",
+ *     current_step:              string,
+ *     started_at:                ISO8601 string,
+ *     updated_at:                ISO8601 string,
+ *     last_evaluator_verdict:    string | null,
+ *     last_user_choice:          string | null
+ *   }
+ *
+ * Hard rules (spec §7A.3):
+ *   - The contract is read-only for the desktop client. Only the
+ *     running bee (and peaks CLI) may write it.
+ *   - The shape is locked — adding a field is a schema-version
+ *     bump; removing or renaming a field is a breaking change.
+ *
+ * This module exposes:
+ *   - A Zod schema (`RunStateContractSchema`) that validates the
+ *     shape with strict rules (no extra keys, exact enum for
+ *     status).
+ *   - A type alias (`RunStateContract`).
+ *   - A constructor-like factory (for testing / fixtures).
+ *
+ * It does NOT expose any mutation helpers — there are no setters,
+ * because the contract is read-only at the desktop. The running
+ * bee writes the file via the existing dispatch flow; the desktop
+ * client reads via a separate channel.
+ */
+import { z } from "zod";
+/**
+ * The five status values an in-flight bee may report. The
+ * desktop-client UI renders the status badge; only the running bee
+ * transitions between them.
+ */
+export declare const RUN_STATE_STATUSES: readonly ["running", "paused", "done", "failed", "blocked"];
+export type RunStateStatus = (typeof RUN_STATE_STATUSES)[number];
+/**
+ * RunStateContract — the locked read-only shape (spec §7A.3).
+ *
+ * Notes:
+ *   - `bee_id`, `current_step`: non-empty NL strings.
+ *   - `started_at`, `updated_at`: ISO8601; updated_at >= started_at
+ *     is the caller's job (the schema does not check ordering
+ *     because a clock skew between the dispatcher and the receiver
+ *     is a transient runtime issue, not a shape invariant).
+ *   - `last_evaluator_verdict`: optional NL string; null when no
+ *     evaluator has fired yet.
+ *   - `last_user_choice`: optional NL choice summary; null when
+ *     the user has not made a pick yet.
+ *
+ * `.strict()` rejects unknown keys — adding a field is a
+ * schema-version bump, not a quiet extension.
+ */
+export declare const RunStateContractSchema: z.ZodObject<{
+    /** Stable bee id (kebab-case). */
+    bee_id: z.ZodString;
+    /** Current run status (running / paused / done / failed / blocked). */
+    status: z.ZodEnum<["running", "paused", "done", "failed", "blocked"]>;
+    /** Current step name; NL short label. */
+    current_step: z.ZodString;
+    /** ISO8601 timestamp the run started. */
+    started_at: z.ZodString;
+    /** ISO8601 timestamp of the latest update. */
+    updated_at: z.ZodString;
+    /** NL summary of the latest evaluator verdict (or null when none). */
+    last_evaluator_verdict: z.ZodNullable<z.ZodString>;
+    /** NL summary of the latest user choice (or null when none). */
+    last_user_choice: z.ZodNullable<z.ZodString>;
+}, "strict", z.ZodTypeAny, {
+    status: "done" | "failed" | "blocked" | "running" | "paused";
+    bee_id: string;
+    current_step: string;
+    started_at: string;
+    updated_at: string;
+    last_evaluator_verdict: string | null;
+    last_user_choice: string | null;
+}, {
+    status: "done" | "failed" | "blocked" | "running" | "paused";
+    bee_id: string;
+    current_step: string;
+    started_at: string;
+    updated_at: string;
+    last_evaluator_verdict: string | null;
+    last_user_choice: string | null;
+}>;
+export type RunStateContract = z.infer<typeof RunStateContractSchema>;
+/**
+ * Strict-parse an unknown value as a RunStateContract. Throws
+ * `ZodError` on failure. The desktop client uses this at the read
+ * boundary; the running bee writes the file via the existing
+ * dispatch flow (separate write path).
+ */
+export declare function parseRunStateContract(input: unknown): RunStateContract;
+/**
+ * Safe-parse twin — same Result-like envelope shape used elsewhere.
+ */
+export declare function safeParseRunStateContract(input: unknown): {
+    ok: true;
+    contract: RunStateContract;
+} | {
+    ok: false;
+    findings: Array<{
+        path: string;
+        message: string;
+    }>;
+};
+/**
+ * Server-side factory used by the dispatch flow to write the file.
+ * This helper is exported for testing purposes; the desktop client
+ * is read-only and SHOULD NOT call this.
+ *
+ * The function returns a brand-new `RunStateContract` value; it
+ * does NOT mutate any external state. Persistence is the caller's
+ * responsibility (the dispatch flow writes a JSON file at a
+ * well-known path under `.peaks/_runtime/<sid>/<role>/`).
+ */
+export declare function buildRunState(args: {
+    bee_id: string;
+    status: RunStateStatus;
+    current_step: string;
+    started_at: string;
+    updated_at: string;
+    last_evaluator_verdict?: string | null;
+    last_user_choice?: string | null;
+}): RunStateContract;