peaks-loop 3.1.2 → 4.0.0-beta.2

package/dist/src/services/sediment/pool-read.d.ts

@@ -0,0 +1,20 @@
+import type { IndexFile } from "./types.js";
+export declare class POOL_READ_ERROR extends Error {
+}
+/** Pure read of the in-memory pool index (Critical #2 fix).
+ *
+ *  CONTRACT: this function is a READ-ONLY computation. It MUST NOT
+ *  write `index.json` (or any other file) as a side-effect. The
+ *  "self-heal" property of rewriting index.json when it goes stale
+ *  belongs to `rebuildIndexFromFs`, not here. List / search / recent /
+ *  add-* verbs that need to mutate the on-disk cache should call
+ *  `rebuildIndexFromFs` explicitly.
+ *
+ *  Edge case: if the pool root does not yet exist, this returns an
+ *  empty index WITHOUT creating the directory. Callers that need a
+ *  materialized root should use `rebuildIndexFromFs` or `mkdirSync`
+ *  themselves.
+ */
+export declare function readPool({ home }: {
+    home: string;
+}): IndexFile;

package/dist/src/services/sediment/pool-read.js

@@ -0,0 +1,73 @@
+import { readdirSync, readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolveUserBeesDir, resolveSegmentsDir } from "./pool-paths.js";
+import { lintManifest } from "./manifest-lint.js";
+export class POOL_READ_ERROR extends Error {
+}
+function readJsonIfExists(p) {
+    if (!existsSync(p))
+        return null;
+    return JSON.parse(readFileSync(p, "utf-8"));
+}
+function readBeeDir(home, name) {
+    const dir = join(resolveUserBeesDir({ home }), name);
+    const manifestPath = join(dir, "manifest.json");
+    const m = readJsonIfExists(manifestPath);
+    if (!m)
+        return null;
+    const r = lintManifest(m);
+    if (!r.ok)
+        return null;
+    return {
+        name: m.name,
+        kind: "bee",
+        path: `bees/${name}`,
+        source: m.source,
+        promotion_status: m.promotion_status,
+        segments: m.segments.map((s) => s.name),
+    };
+}
+function readSegmentDir(home, name) {
+    const dir = join(resolveSegmentsDir({ home }), name);
+    if (!existsSync(dir))
+        return null;
+    return {
+        name, kind: "segment", path: `segments/${name}`, source: "user", promotion_status: "stable",
+    };
+}
+/** Pure read of the in-memory pool index (Critical #2 fix).
+ *
+ *  CONTRACT: this function is a READ-ONLY computation. It MUST NOT
+ *  write `index.json` (or any other file) as a side-effect. The
+ *  "self-heal" property of rewriting index.json when it goes stale
+ *  belongs to `rebuildIndexFromFs`, not here. List / search / recent /
+ *  add-* verbs that need to mutate the on-disk cache should call
+ *  `rebuildIndexFromFs` explicitly.
+ *
+ *  Edge case: if the pool root does not yet exist, this returns an
+ *  empty index WITHOUT creating the directory. Callers that need a
+ *  materialized root should use `rebuildIndexFromFs` or `mkdirSync`
+ *  themselves.
+ */
+export function readPool({ home }) {
+    const entries = [];
+    const beesDir = resolveUserBeesDir({ home });
+    if (existsSync(beesDir)) {
+        for (const ent of readdirSync(beesDir, { withFileTypes: true })) {
+            if (!ent.isDirectory())
+                continue;
+            entries.push(...[readBeeDir(home, ent.name)].filter((e) => e !== null));
+        }
+    }
+    const segsDir = resolveSegmentsDir({ home });
+    if (existsSync(segsDir)) {
+        for (const ent of readdirSync(segsDir, { withFileTypes: true })) {
+            if (!ent.isDirectory())
+                continue;
+            entries.push(...[readSegmentDir(home, ent.name)].filter((e) => e !== null));
+        }
+    }
+    const idx = { schemaVersion: "peaks.pool/1", generatedAt: new Date().toISOString(), entries };
+    // Note: NO writeFileSync here. See Critical #2 fix.
+    return idx;
+}

package/dist/src/services/sediment/pool-rebuild-index.d.ts

@@ -0,0 +1,15 @@
+import type { IndexFile } from "./types.js";
+/**
+ * Rebuilds index.json from on-disk manifests/segments and writes the result.
+ *
+ * After the Critical #2 fix, `readPool` is a pure read (no filesystem
+ * side-effects). `rebuildIndexFromFs` is the single writer of
+ * `index.json`: it materializes the pool root if needed, walks the
+ * filesystem to build the in-memory index via `readPool`, and persists
+ * the result. Callers that need the on-disk cache up-to-date should
+ * call this function (or one of the add-* / rebuild-index CLI verbs
+ * which call it internally).
+ */
+export declare function rebuildIndexFromFs({ home }: {
+    home: string;
+}): IndexFile;

package/dist/src/services/sediment/pool-rebuild-index.js

@@ -0,0 +1,28 @@
+import { writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolvePoolRoot } from "./pool-paths.js";
+import { readPool } from "./pool-read.js";
+/**
+ * Rebuilds index.json from on-disk manifests/segments and writes the result.
+ *
+ * After the Critical #2 fix, `readPool` is a pure read (no filesystem
+ * side-effects). `rebuildIndexFromFs` is the single writer of
+ * `index.json`: it materializes the pool root if needed, walks the
+ * filesystem to build the in-memory index via `readPool`, and persists
+ * the result. Callers that need the on-disk cache up-to-date should
+ * call this function (or one of the add-* / rebuild-index CLI verbs
+ * which call it internally).
+ */
+export function rebuildIndexFromFs({ home }) {
+    const root = resolvePoolRoot({ home });
+    if (!existsSync(root))
+        mkdirSync(root, { recursive: true });
+    const idx = readPool({ home });
+    // Trailing newline: POSIX-friendly (`cat`, `git diff`, log tailers all
+    // expect a final \n). The Minor #14 review confirmed we keep the current
+    // behavior rather than drop it — both are JSON-valid but the trailing
+    // newline matches the convention used by every other peaks-*.json file
+    // in the project (manifest.json, segment.json, etc.).
+    writeFileSync(join(root, "index.json"), JSON.stringify(idx, null, 2) + "\n");
+    return idx;
+}

package/dist/src/services/sediment/pool-write.d.ts

@@ -0,0 +1,14 @@
+import type { BeeManifest } from "./types.js";
+/**
+ * Atomically writes a BeeManifest to <home>/.peaks/skills/bees/<name>/manifest.json.
+ *
+ * Defense in depth:
+ *  - re-validates the manifest via lintManifestStrict (zod) before any FS work
+ *  - refuses to write under any path segment equal to ".system" (soft-protection)
+ *
+ * Atomicity is achieved via write-to-tmp + renameSync so readers either see the
+ * old file or the fully-written new file, never a half-written one.
+ */
+export declare function writeBeeManifest({ home }: {
+    home: string;
+}, m: BeeManifest): void;

package/dist/src/services/sediment/pool-write.js

@@ -0,0 +1,25 @@
+import { writeFileSync, mkdirSync, renameSync } from "node:fs";
+import { join } from "node:path";
+import { assertNotSystemPath, resolveUserBeeDir } from "./pool-paths.js";
+import { lintManifestStrict } from "./manifest-lint.js";
+/**
+ * Atomically writes a BeeManifest to <home>/.peaks/skills/bees/<name>/manifest.json.
+ *
+ * Defense in depth:
+ *  - re-validates the manifest via lintManifestStrict (zod) before any FS work
+ *  - refuses to write under any path segment equal to ".system" (soft-protection)
+ *
+ * Atomicity is achieved via write-to-tmp + renameSync so readers either see the
+ * old file or the fully-written new file, never a half-written one.
+ */
+export function writeBeeManifest({ home }, m) {
+    const validated = lintManifestStrict(m);
+    const dir = resolveUserBeeDir({ home }, validated.name);
+    assertNotSystemPath(dir);
+    mkdirSync(dir, { recursive: true });
+    const file = join(dir, "manifest.json");
+    assertNotSystemPath(file);
+    const tmp = file + ".tmp";
+    writeFileSync(tmp, JSON.stringify(validated, null, 2) + "\n");
+    renameSync(tmp, file);
+}

package/dist/src/services/sediment/promotion-gate.d.ts

@@ -0,0 +1,12 @@
+import type { BeeManifest } from "./types.js";
+export interface GateInputs {
+    humanApproved: boolean;
+    smokeTestPresent: boolean;
+}
+export interface GateResult {
+    ok: boolean;
+    failedSubconditions: string[];
+}
+export declare function evaluateGate({ home }: {
+    home: string;
+}, m: BeeManifest, inputs: GateInputs): GateResult;

package/dist/src/services/sediment/promotion-gate.js

@@ -0,0 +1,20 @@
+import { readFileSync, existsSync } from "node:fs";
+import { join } from "node:path";
+import { resolveUserBeeDir } from "./pool-paths.js";
+export function evaluateGate({ home }, m, inputs) {
+    if (m.source === "system") {
+        return { ok: true, failedSubconditions: [] };
+    }
+    const failed = [];
+    const rsPath = join(resolveUserBeeDir({ home }, m.name), "run-state.json");
+    const cycles = existsSync(rsPath)
+        ? JSON.parse(readFileSync(rsPath, "utf-8")).cycles
+        : 0;
+    if (cycles < m.promotion.minCycles)
+        failed.push("minCycles");
+    if (inputs.smokeTestPresent !== m.promotion.requiresSmokeTest)
+        failed.push("smokeTest");
+    if (m.promotion.requiresHumanApproval && !inputs.humanApproved)
+        failed.push("humanApproval");
+    return { ok: failed.length === 0, failedSubconditions: failed };
+}

package/dist/src/services/sediment/types.d.ts

@@ -0,0 +1,52 @@
+export type Source = "system" | "user";
+export type PromotionStatus = "candidate" | "stable" | "retired" | "system-stable";
+export interface Param {
+    name: string;
+    type: "string" | "number" | "boolean" | "json";
+    required: boolean;
+}
+export interface SegmentRef {
+    name: string;
+    inputs: Param[];
+    outputs: Param[];
+    sideEffects: string[];
+}
+export interface SkillEnvelopeRef {
+    path: string;
+    kind: "file" | "dir" | "script";
+}
+export interface SkillEnvelope {
+    preamble: string;
+    refs: SkillEnvelopeRef[];
+}
+export interface PromotionGate {
+    minCycles: number;
+    requiresHumanApproval: boolean;
+    requiresSmokeTest: boolean;
+    retireOnMissesInRow?: number;
+}
+export interface BeeManifest {
+    schemaVersion: "peaks.bee/1";
+    name: string;
+    source: Source;
+    promotion_status: PromotionStatus;
+    description: string;
+    segments: SegmentRef[];
+    entrypoint: SkillEnvelope;
+    promotion: PromotionGate;
+    createdBy: "human" | "llm";
+    lastTouchedAt: string;
+}
+export interface IndexEntry {
+    name: string;
+    kind: "bee" | "segment";
+    path: string;
+    source: Source;
+    promotion_status: PromotionStatus;
+    segments?: string[];
+}
+export interface IndexFile {
+    schemaVersion: "peaks.pool/1";
+    generatedAt: string;
+    entries: IndexEntry[];
+}

package/dist/src/services/sediment/types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/services/session/binding-store.d.ts

@@ -107,7 +107,7 @@ export declare function writeBinding(projectRoot: string, binding: Binding): voi
  * This is the D2 Claude-instance-level binding primitive — a single
  * Claude instance keeps one sid across multiple peaks-* skill
  * activations; binding.instances[<sid>].roles accumulates the skill
- * names (peaks-solo → peaks-rd → peaks-qa in the same Claude run).
+ * names (peaks-code → peaks-rd → peaks-qa in the same Claude run).
  *
  * The caller is responsible for actually creating the session dir via
  * `initWorkspace` and storing per-session meta via `setSessionMeta`.

package/dist/src/services/session/binding-store.js

@@ -192,7 +192,7 @@ export function writeBinding(projectRoot, binding) {
  * This is the D2 Claude-instance-level binding primitive — a single
  * Claude instance keeps one sid across multiple peaks-* skill
  * activations; binding.instances[<sid>].roles accumulates the skill
- * names (peaks-solo → peaks-rd → peaks-qa in the same Claude run).
+ * names (peaks-code → peaks-rd → peaks-qa in the same Claude run).
  *
  * The caller is responsible for actually creating the session dir via
  * `initWorkspace` and storing per-session meta via `setSessionMeta`.

package/dist/src/services/session/caller-id-types.d.ts

@@ -28,7 +28,7 @@ export interface CallerBinding {
     createdAt: string;
     /** ISO 8601 timestamp; bumped on every `peaks <cmd>` that touches the binding. */
     lastActivityAt: string;
-    /** Last skill that touched this binding, e.g. "peaks-solo". */
+    /** Last skill that touched this binding, e.g. "peaks-code". */
     skill: string;
     /** Last mode, e.g. "full-auto". */
     mode: string;

package/dist/src/services/session/session-manager.d.ts

@@ -120,7 +120,7 @@ export declare function getSessionId(projectRoot: string): string | null;
  * caller is operating on a user-supplied `--project` flag
  * and the binding may have been written by a CLI invocation
  * that was running from inside the project dir (the common
- * peaks-solo / peaks-sop scenario). Other modules depend
+ * peaks-code / peaks-sop scenario). Other modules depend
  * on the strict-equality semantics of `getSessionId` (the
  * "no binding" fallback path is part of their contract),
  * so this variant is opt-in.

package/dist/src/services/session/session-manager.js

@@ -399,7 +399,7 @@ export function getSessionId(projectRoot) {
  * caller is operating on a user-supplied `--project` flag
  * and the binding may have been written by a CLI invocation
  * that was running from inside the project dir (the common
- * peaks-solo / peaks-sop scenario). Other modules depend
+ * peaks-code / peaks-sop scenario). Other modules depend
  * on the strict-equality semantics of `getSessionId` (the
  * "no binding" fallback path is part of their contract),
  * so this variant is opt-in.

package/dist/src/services/signal/cancel-handler.js

@@ -1,7 +1,7 @@
 /**
  * Slice #009 / G5 RL-9 — user cancel must dispose in-flight dispatch records.
  *
- * When Solo's main loop receives SIGINT (Ctrl-C) or the user runs
+ * When Code's main loop receives SIGINT (Ctrl-C) or the user runs
  * `peaks workflow cancel --rid <rid>`, the loop MUST mark in-flight
  * dispatch records as `outcome: "cancelled"` + `disposed: true` +
  * `disposedAt: now()` BEFORE exiting.
@@ -10,8 +10,8 @@
  * `completedAt: null`. Those are the ones that the LLM got a toolCall
  * for but did not (yet) confirm completion.
  *
- * This module is the helper Solo calls. The wiring (signal listener,
- * cancel command side-effect) is the Solo main loop's responsibility;
+ * This module is the helper Code calls. The wiring (signal listener,
+ * cancel command side-effect) is the Code main loop's responsibility;
  * this module is the pure data operation.
  */
 import { existsSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';

package/dist/src/services/skill/resume-detector.js

@@ -1,8 +1,8 @@
 /**
- * Peaks-Loop Solo Step 0.7 — Resume-mode detector.
+ * Peaks-Loop Code Step 0.7 — Resume-mode detector.
  *
  * Mirrors the classification table in
- * `skills/peaks-solo/SKILL.md` "Peaks-Loop Step 0.7: Detect unfinished work
+ * `skills/peaks-code/SKILL.md` "Peaks-Loop Step 0.7: Detect unfinished work
  * and offer resume". The function is a pure read of session artifacts;
  * it performs no side effects and is safe to call from hooks, scripts,
  * and skills.

package/dist/src/services/skill/skill-scheduler.d.ts

@@ -2,7 +2,7 @@
  * G6 — skill-level heartbeat scheduler config.
  *
  * Slice 2026-06-07-sub-agent-dispatch-decouple (G6): the SKILL.md front
- * matter for a Dispatcher (peaks-solo / peaks-rd / peaks-qa) can opt
+ * matter for a Dispatcher (peaks-code / peaks-rd / peaks-qa) can opt
  * into a non-default heartbeat interval by including a line like:
  *
  *   heartbeatIntervalSec: 15

package/dist/src/services/skill/skill-scheduler.js

@@ -2,7 +2,7 @@
  * G6 — skill-level heartbeat scheduler config.
  *
  * Slice 2026-06-07-sub-agent-dispatch-decouple (G6): the SKILL.md front
- * matter for a Dispatcher (peaks-solo / peaks-rd / peaks-qa) can opt
+ * matter for a Dispatcher (peaks-code / peaks-rd / peaks-qa) can opt
  * into a non-default heartbeat interval by including a line like:
  *
  *   heartbeatIntervalSec: 15

package/dist/src/services/skillhub/release-diff.d.ts

@@ -0,0 +1,18 @@
+import type Database from "better-sqlite3";
+export interface ReleaseDiff {
+    added: string[];
+    removed: string[];
+    modified: string[];
+}
+/**
+ * Compare two releases of the same bee and report which file paths were
+ * added, removed, or had their content (sha256) changed.
+ *
+ * Throws `VERSION_NOT_FOUND` if either (bee_name, version) tuple is missing.
+ */
+export declare function releaseDiff({ db, beeName, fromVersion, toVersion, }: {
+    db: Database.Database;
+    beeName: string;
+    fromVersion: string;
+    toVersion: string;
+}): ReleaseDiff;

package/dist/src/services/skillhub/release-diff.js

@@ -0,0 +1,38 @@
+/**
+ * Compare two releases of the same bee and report which file paths were
+ * added, removed, or had their content (sha256) changed.
+ *
+ * Throws `VERSION_NOT_FOUND` if either (bee_name, version) tuple is missing.
+ */
+export function releaseDiff({ db, beeName, fromVersion, toVersion, }) {
+    const aRow = db
+        .prepare("SELECT id FROM bee_release WHERE bee_name = ? AND version = ?")
+        .get(beeName, fromVersion);
+    const bRow = db
+        .prepare("SELECT id FROM bee_release WHERE bee_name = ? AND version = ?")
+        .get(beeName, toVersion);
+    if (!aRow || !bRow)
+        throw new Error("VERSION_NOT_FOUND");
+    const a = aRow.id;
+    const b = bRow.id;
+    const aFiles = new Map(db
+        .prepare("SELECT path, sha256 FROM bee_file WHERE release_id = ?")
+        .all(a).map((r) => [r.path, r.sha256]));
+    const bFiles = new Map(db
+        .prepare("SELECT path, sha256 FROM bee_file WHERE release_id = ?")
+        .all(b).map((r) => [r.path, r.sha256]));
+    const added = [];
+    const removed = [];
+    const modified = [];
+    for (const [p, sha] of bFiles) {
+        if (!aFiles.has(p))
+            added.push(p);
+        else if (aFiles.get(p) !== sha)
+            modified.push(p);
+    }
+    for (const [p] of aFiles) {
+        if (!bFiles.has(p))
+            removed.push(p);
+    }
+    return { added, removed, modified };
+}

package/dist/src/services/skillhub/release-export.d.ts

@@ -0,0 +1,8 @@
+import type Database from "better-sqlite3";
+export declare function exportRelease({ db, blobsDir, beeName, version, outPath, }: {
+    db: Database.Database;
+    blobsDir: string;
+    beeName: string;
+    version: string;
+    outPath: string;
+}): void;

package/dist/src/services/skillhub/release-export.js

@@ -0,0 +1,31 @@
+import { mkdirSync, writeFileSync, readFileSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { runTar } from "./tar-runtime.js";
+export function exportRelease({ db, blobsDir, beeName, version, outPath, }) {
+    const id = db
+        .prepare("SELECT id FROM bee_release WHERE bee_name = ? AND version = ?")
+        .get(beeName, version)?.id;
+    if (!id)
+        throw new Error("VERSION_NOT_FOUND");
+    const manifestRows = db.prepare("SELECT * FROM bee_manifest WHERE release_id = ?").all(id);
+    const segRows = db.prepare("SELECT * FROM bee_segment_ref WHERE release_id = ?").all(id);
+    const fileRows = db
+        .prepare("SELECT * FROM bee_file WHERE release_id = ?")
+        .all(id);
+    const changeRows = db.prepare("SELECT * FROM bee_change WHERE release_id = ?").all(id);
+    const stageDir = join(outPath + ".stage");
+    mkdirSync(stageDir, { recursive: true });
+    writeFileSync(join(stageDir, "manifest.json"), JSON.stringify({ bee_name: beeName, version, manifestRows, segRows, fileRows, changeRows }, null, 2));
+    mkdirSync(join(stageDir, "blobs"), { recursive: true });
+    for (const f of fileRows) {
+        const src = join(blobsDir, f.sha256.slice(0, 2), f.sha256);
+        const dest = join(stageDir, "blobs", f.sha256);
+        writeFileSync(dest, readFileSync(src));
+    }
+    try {
+        runTar(["-czf", outPath, "-C", stageDir, "."]);
+    }
+    finally {
+        rmSync(stageDir, { recursive: true, force: true });
+    }
+}

package/dist/src/services/skillhub/release-gc-blobs.d.ts

@@ -0,0 +1,13 @@
+import type Database from "better-sqlite3";
+/**
+ * Garbage-collect content-addressed blobs under `blobsDir/<aa>/<sha>` that
+ * no `bee_file` row currently references.
+ *
+ * @param dryRun if true, list removed SHAs without deleting files.
+ * @returns the list of removed SHA names.
+ */
+export declare function gcBlobs({ db, blobsDir, dryRun, }: {
+    db: Database.Database;
+    blobsDir: string;
+    dryRun: boolean;
+}): string[];

package/dist/src/services/skillhub/release-gc-blobs.js

@@ -0,0 +1,32 @@
+import { readdirSync, rmSync, existsSync, statSync } from "node:fs";
+import { join } from "node:path";
+/**
+ * Garbage-collect content-addressed blobs under `blobsDir/<aa>/<sha>` that
+ * no `bee_file` row currently references.
+ *
+ * @param dryRun if true, list removed SHAs without deleting files.
+ * @returns the list of removed SHA names.
+ */
+export function gcBlobs({ db, blobsDir, dryRun, }) {
+    const refs = new Set(db.prepare("SELECT DISTINCT sha256 FROM bee_file").all().map((r) => r.sha256));
+    const removed = [];
+    if (!existsSync(blobsDir))
+        return removed;
+    for (const sub of readdirSync(blobsDir)) {
+        const subDir = join(blobsDir, sub);
+        if (!statSync(subDir).isDirectory())
+            continue;
+        for (const sha of readdirSync(subDir)) {
+            if (refs.has(sha))
+                continue;
+            const p = join(subDir, sha);
+            if (dryRun) {
+                removed.push(sha);
+                continue;
+            }
+            rmSync(p);
+            removed.push(sha);
+        }
+    }
+    return removed;
+}

package/dist/src/services/skillhub/release-import.d.ts

@@ -0,0 +1,7 @@
+import type Database from "better-sqlite3";
+export declare function importRelease({ db, blobsDir, inPath, asName, }: {
+    db: Database.Database;
+    blobsDir: string;
+    inPath: string;
+    asName?: string;
+}): void;

package/dist/src/services/skillhub/release-import.js

@@ -0,0 +1,59 @@
+import { readFileSync, mkdirSync, writeFileSync, existsSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { assertNotSystemPath } from "../sediment/pool-paths.js";
+import { runTar } from "./tar-runtime.js";
+export function importRelease({ db, blobsDir, inPath, asName, }) {
+    const stageDir = inPath + ".extract";
+    if (existsSync(stageDir))
+        rmSync(stageDir, { recursive: true, force: true });
+    mkdirSync(stageDir, { recursive: true });
+    let extractOk = false;
+    try {
+        runTar(["-xzf", inPath, "-C", stageDir]);
+        extractOk = true;
+    }
+    finally {
+        if (!extractOk)
+            rmSync(stageDir, { recursive: true, force: true });
+    }
+    // ExportPayload (defined in ./types.ts) is the structural contract
+    // shared with release-export.ts, which writes the same JSON shape
+    // into <stageDir>/manifest.json. Minor #13: replace the previous
+    // inline anonymous type so producer and consumer stay in lock-step.
+    const payload = JSON.parse(readFileSync(join(stageDir, "manifest.json"), "utf-8"));
+    const beeName = asName ?? payload.bee_name;
+    assertNotSystemPath(beeName);
+    // Always check collision (the asName path previously skipped it and
+    // fell through to a UNIQUE-constraint mid-INSERT failure). Whether
+    // the user gave an explicit asName or relied on payload.bee_name, a
+    // pre-existing row must be reported cleanly.
+    if (db.prepare("SELECT 1 FROM bee_release WHERE bee_name = ?").get(beeName)) {
+        throw new Error("IMPORT_NAME_COLLIDES");
+    }
+    // Copy blobs
+    for (const f of payload.fileRows) {
+        const dest = join(blobsDir, f.sha256.slice(0, 2));
+        mkdirSync(dest, { recursive: true });
+        writeFileSync(join(dest, f.sha256), readFileSync(join(stageDir, "blobs", f.sha256)));
+    }
+    // Re-insert rows: pick a new release id, mirror payload rows
+    const tx = db.transaction(() => {
+        const ins = db.prepare(`INSERT INTO bee_release (bee_name, version, source, archived_at, archived_by, user_intent_raw, description, parent_version, changelog) VALUES (?, ?, 'user', ?, 'user', ?, ?, ?, ?)`);
+        const id = ins.run(beeName, payload.version, new Date().toISOString(), null, null, null, null).lastInsertRowid;
+        db.prepare(`INSERT OR REPLACE INTO bee_release_pointer (bee_name, latest_version, released_at) VALUES (?, ?, ?)`).run(beeName, payload.version, new Date().toISOString());
+        for (const m of payload.manifestRows) {
+            db.prepare(`INSERT INTO bee_manifest (release_id, schema_version, description, segments_json, entrypoint_preamble, promotion, min_cycles, requires_human, requires_smoke, retire_on_misses) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(id, m.schema_version, m.description, m.segments_json, m.entrypoint_preamble, m.promotion, m.min_cycles, m.requires_human, m.requires_smoke, m.retire_on_misses);
+        }
+        for (const s of payload.segRows) {
+            db.prepare(`INSERT INTO bee_segment_ref (release_id, segment_name, inputs_json, outputs_json, side_effects) VALUES (?, ?, ?, ?, ?)`).run(id, s.segment_name, s.inputs_json, s.outputs_json, s.side_effects);
+        }
+        for (const f of payload.fileRows) {
+            db.prepare(`INSERT INTO bee_file (release_id, owner_kind, owner_name, path, kind, size_bytes, sha256, blob_path) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(id, f.owner_kind, beeName, f.path, f.kind, f.size_bytes, f.sha256, f.blob_path);
+        }
+        for (const c of payload.changeRows) {
+            db.prepare(`INSERT INTO bee_change (release_id, change_kind, target_kind, target_name, detail) VALUES (?, ?, ?, ?, ?)`).run(id, c.change_kind, c.target_kind, c.target_name, c.detail);
+        }
+    });
+    tx();
+    rmSync(stageDir, { recursive: true, force: true });
+}

package/dist/src/services/skillhub/release-retain.d.ts

@@ -0,0 +1,23 @@
+import type Database from "better-sqlite3";
+import type { BeeManifest } from "../sediment/types.js";
+/** Compute the sha256 hash and byte length of a single file. */
+export declare function sha256OfFile(p: string): {
+    sha: string;
+    bytes: number;
+};
+/** Copy a file into the content-addressed blob store under `blobsDir/<aa>/<sha>`
+ *  if not already present, and return the relative blob_path used by `bee_file`. */
+export declare function ensureBlob(blobsDir: string, sha: string, srcPath: string): string;
+export declare function walk(root: string, base?: string): Generator<{
+    abs: string;
+    rel: string;
+}>;
+export declare function retainRelease({ db, blobsDir, scratchDir, manifest, version: explicitVersion, parentVersion, changelog, }: {
+    db: Database.Database;
+    blobsDir: string;
+    scratchDir: string;
+    manifest: BeeManifest;
+    version?: string;
+    parentVersion?: string;
+    changelog?: string;
+}): number;