peaks-loop 4.0.16 → 4.0.18

package/dist/services/share/bundle-reader.js

@@ -21,15 +21,12 @@
  *      imported release to `stable` (AC-26 — peaks loop promote
  *      reads evolution_evaluation rows).
  *
- * The reader is also the integration point for AC-26 — the loop
- * promote path (which lives in a future slice / CLI command) checks
- * `evolution_evaluation.independent_scorer_verdict` before allowing
- * a candidate → stable transition; this slice does not add a new
- * `peaks loop promote` because `peaks asset crystallize` already
- * enforces the brief-section + pre-run gates and creates the
- * initial `candidate` row. The integration test for AC-26 verifies
- * that a freshly imported bundle has no `evolution_evaluation`
- * row and that promotion therefore cannot proceed.
+ * Slice 4 (PRD-002b): split the four high-cohort functions
+ * (readBundle 15, importLoopBundle 20, materialiseRelatedBees 28,
+ * importBeeBundle arrow 38) into small helpers with table dispatch
+ * for kind routing and early-return for guard paths. Public API
+ * (readBundle, ReadBundleArgs, ReadBundleResult, the four error
+ * classes) is preserved verbatim.
  */
 import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync, rmSync, } from "node:fs";
 import { join } from "node:path";
@@ -93,6 +90,71 @@ export class BundleMalformedError extends Error {
     }
 }
 /* ---------------------------------------------------------------------- */
+/* Stage helpers (slice 4)                                                  */
+/* ---------------------------------------------------------------------- */
+/** SHA-256 content-hash filename pattern. */
+const SHA256_RE = /^[0-9a-f]{64}$/;
+/** Coerce a possibly-unknown value to a string lifecycle status, defaulting to "candidate". */
+function readSourceLifecycle(release) {
+    return typeof release.lifecycle_status === "string"
+        ? release.lifecycle_status
+        : "candidate";
+}
+/**
+ * Enforce the AC-25 hard rule: bundles always land as `candidate`;
+ * any other source status is refused. Layered at every import site
+ * for defense in depth.
+ */
+function enforceImportAsCandidate(status) {
+    if (status !== "candidate") {
+        throw new BundleImportToStableForbiddenError(status);
+    }
+}
+/** Coerce an unknown value to a boolean-ish 0/1 column value. */
+function bool01(value, defaultValue) {
+    if (value === undefined)
+        return defaultValue;
+    return value ? 1 : 0;
+}
+/** Coerce an unknown value to a string column value (empty string default). */
+function str(value, defaultValue = "") {
+    return typeof value === "string" ? value : defaultValue;
+}
+/** Coerce an unknown value to a string-or-null column value. */
+function strOrNull(value) {
+    return typeof value === "string" ? value : null;
+}
+/** Coerce an unknown value to a JSON-stringified column value. */
+function jsonArr(value) {
+    return JSON.stringify(value ?? []);
+}
+/** Coerce an unknown value to an ISO-8601 string (now() default). */
+function isoOrNow(value) {
+    return typeof value === "string" ? value : new Date().toISOString();
+}
+/** Now as an ISO string. */
+function nowIso() {
+    return new Date().toISOString();
+}
+/** Safe directory listing (returns [] on error). */
+function readDirEntries(dir) {
+    try {
+        return readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+}
+/** Read and JSON.parse a file, throwing BundleMalformedError on parse failure. */
+function readJsonOrThrow(path) {
+    try {
+        return JSON.parse(readFileSync(path, "utf-8"));
+    }
+    catch (err) {
+        throw new BundleMalformedError(`manifest.json could not be parsed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/* ---------------------------------------------------------------------- */
 /* Main entrypoint                                                           */
 /* ---------------------------------------------------------------------- */
 export function readBundle(args) {
@@ -101,77 +163,77 @@ export function readBundle(args) {
         throw new BundleMalformedError(`bundle file not found at '${inPath}'`);
     }
     const stageDir = inPath + ".extract";
-    if (existsSync(stageDir))
-        rmSync(stageDir, { recursive: true, force: true });
-    mkdirSync(stageDir, { recursive: true });
-    let extractOk = false;
+    resetStageDir(stageDir);
     try {
         runTar(["-xzf", inPath, "-C", stageDir]);
-        extractOk = true;
+        const manifest = loadStageManifest(stageDir);
+        materialiseBlobs(stageDir, blobsDir);
+        const assetId = KIND_IMPORTERS[manifest.kind](db, manifest, blobsDir, args.asName);
+        return buildReadResult(manifest, assetId);
     }
     finally {
-        if (!extractOk)
+        if (existsSync(stageDir))
             rmSync(stageDir, { recursive: true, force: true });
     }
-    try {
-        const manifestPath = join(stageDir, "manifest.json");
-        if (!existsSync(manifestPath)) {
-            throw new BundleMalformedError("bundle is missing manifest.json (writer is required to emit it)");
-        }
-        let rawManifest;
-        try {
-            rawManifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
-        }
-        catch (err) {
-            throw new BundleMalformedError(`manifest.json could not be parsed: ${err instanceof Error ? err.message : String(err)}`);
-        }
-        const manifest = parseManifest(rawManifest);
-        // Re-materialise content-addressed blobs regardless of kind —
-        // the layout (`blobs/<sha256>`) is identical for both.
-        const blobsStageDir = join(stageDir, "blobs");
-        if (existsSync(blobsStageDir)) {
-            mkdirSync(blobsDir, { recursive: true });
-            const blobsOut = blobsDir;
-            for (const fname of readDirEntries(blobsStageDir)) {
-                const src = join(blobsStageDir, fname);
-                if (!fname.match(/^[0-9a-f]{64}$/))
-                    continue;
-                const destDir = join(blobsOut, fname.slice(0, 2));
-                mkdirSync(destDir, { recursive: true });
-                const destPath = join(destDir, fname);
-                if (!existsSync(destPath)) {
-                    writeFileSync(destPath, readFileSync(src));
-                }
-            }
-        }
-        if (manifest.kind === "loop") {
-            const assetId = importLoopBundle(db, manifest, args.asName);
-            return {
-                assetId,
-                kind: "loop",
-                importedAs: "candidate",
-                warnings: manifest.format_version_minor === 0 ? [] : [
-                    `minor-version=${manifest.format_version_minor}; supported but flagging for awareness`,
-                ],
-                evidenceBriefCount: manifest.evidence_briefs.length,
-            };
-        }
-        const beeId = importBeeBundle(db, manifest, blobsDir, args.asName);
-        return {
-            assetId: beeId,
-            kind: "bee",
-            importedAs: "candidate",
-            warnings: manifest.format_version_minor === 0 ? [] : [
-                `minor-version=${manifest.format_version_minor}; supported but flagging for awareness`,
-            ],
-            evidenceBriefCount: manifest.evidence_briefs.length,
-        };
+}
+/**
+ * Clean any prior extract dir, then recreate it. Split out of
+ * readBundle so the main orchestrator stays branch-light.
+ */
+function resetStageDir(stageDir) {
+    if (existsSync(stageDir))
+        rmSync(stageDir, { recursive: true, force: true });
+    mkdirSync(stageDir, { recursive: true });
+}
+/**
+ * Read and parse the staged manifest.json, raising a
+ * BundleMalformedError if the file is missing.
+ */
+function loadStageManifest(stageDir) {
+    const manifestPath = join(stageDir, "manifest.json");
+    if (!existsSync(manifestPath)) {
+        throw new BundleMalformedError("bundle is missing manifest.json (writer is required to emit it)");
     }
-    finally {
-        if (existsSync(stageDir))
-            rmSync(stageDir, { recursive: true, force: true });
+    return parseManifest(readJsonOrThrow(manifestPath));
+}
+/**
+ * Re-materialise content-addressed blobs regardless of kind —
+ * the layout (`blobs/<sha256>`) is identical for both.
+ */
+function materialiseBlobs(stageDir, blobsDir) {
+    const blobsStageDir = join(stageDir, "blobs");
+    if (!existsSync(blobsStageDir))
+        return;
+    mkdirSync(blobsDir, { recursive: true });
+    for (const fname of readDirEntries(blobsStageDir)) {
+        if (!fname.match(SHA256_RE))
+            continue;
+        const destDir = join(blobsDir, fname.slice(0, 2));
+        mkdirSync(destDir, { recursive: true });
+        const destPath = join(destDir, fname);
+        if (existsSync(destPath))
+            continue;
+        writeFileSync(destPath, readFileSync(join(blobsStageDir, fname)));
     }
 }
+/**
+ * Build the read-result envelope, including the minor-version
+ * warning if the bundle is not on the default minor.
+ */
+function buildReadResult(manifest, assetId) {
+    const warnings = manifest.format_version_minor === 0
+        ? []
+        : [
+            `minor-version=${manifest.format_version_minor}; supported but flagging for awareness`,
+        ];
+    return {
+        assetId,
+        kind: manifest.kind,
+        importedAs: "candidate",
+        warnings,
+        evidenceBriefCount: manifest.evidence_briefs.length,
+    };
+}
 /* ---------------------------------------------------------------------- */
 /* Manifest parsing — enforces the major-version hard block                  */
 /* ---------------------------------------------------------------------- */
@@ -218,6 +280,10 @@ function parseManifest(raw) {
         throw err;
     }
 }
+const KIND_IMPORTERS = {
+    loop: (db, manifest, _blobsDir, asName) => importLoopBundle(db, manifest, asName),
+    bee: (db, manifest, blobsDir, asName) => importBeeBundle(db, manifest, blobsDir, asName),
+};
 /* ---------------------------------------------------------------------- */
 /* Loop import                                                              */
 /* ---------------------------------------------------------------------- */
@@ -226,87 +292,85 @@ function importLoopBundle(db, manifest, asName) {
     const srcId = String(srcLoop.id ?? "");
     if (!srcId)
         throw new BundleMalformedError("loop_release is missing id");
+    const srcStatus = readSourceLifecycle(srcLoop);
+    enforceImportAsCandidate(srcStatus);
     const targetId = asName ?? srcId;
-    // Hard-block per spec §7A.2 / AC-25: bundles MAY ONLY land as
-    // candidate. A non-candidate source lifecycle is REFUSED; we
-    // never silently coerce away a stable / retired source.
-    const srcStatus = typeof srcLoop.lifecycle_status === "string"
-        ? srcLoop.lifecycle_status
-        : "candidate";
-    if (srcStatus !== "candidate") {
-        throw new BundleImportToStableForbiddenError(srcStatus);
-    }
-    // The reader always lands as candidate — the source's lifecycle
-    // status is silently overridden (spec §7A.2 hard rule).
-    const loopRow = {
+    const loopRow = buildLoopRow(srcLoop, targetId);
+    enforceImportAsCandidate(loopRow.lifecycle_status);
+    // First materialise related bee_release rows. The bundle's
+    // loop_bee_relations reference these bee ids; re-stamping the
+    // relations before the bee rows land would FK-constraint fail
+    // on the receiver.
+    const beeIdMap = materialiseRelatedBees(db, manifest.related_bee_releases);
+    const tx = db.transaction(() => {
+        insertLoopReleaseRow(db, loopRow);
+        insertLoopBeeRelations(db, manifest, beeIdMap, targetId);
+    });
+    tx();
+    return targetId;
+}
+/**
+ * Pure mapping from a raw loop_release row to the column-shape
+ * the receiver writes to `loop_release`. Split out so the SQL
+ * INSERT can stay isolated.
+ */
+function buildLoopRow(srcLoop, targetId) {
+    return {
         id: targetId,
         name: srcLoop.name,
         scenario: srcLoop.scenario,
         trigger_policy: srcLoop.trigger_policy,
-        success_criteria_json: JSON.stringify(srcLoop.success_criteria ?? []),
+        success_criteria_json: jsonArr(srcLoop.success_criteria),
         interaction_policy: srcLoop.interaction_policy,
         feedback_policy: srcLoop.feedback_policy,
         evolution_policy: srcLoop.evolution_policy,
-        evaluator_policy_json: JSON.stringify(srcLoop.evaluator_policy ?? []),
-        linked_bees_json: JSON.stringify(srcLoop.linked_bees ?? []),
-        run_history_json: JSON.stringify(srcLoop.run_history ?? []),
-        crystallization_evidence_json: JSON.stringify(srcLoop.crystallization_evidence ?? []),
+        evaluator_policy_json: jsonArr(srcLoop.evaluator_policy),
+        linked_bees_json: jsonArr(srcLoop.linked_bees),
+        run_history_json: jsonArr(srcLoop.run_history),
+        crystallization_evidence_json: jsonArr(srcLoop.crystallization_evidence),
+        // The reader always lands as candidate — the source's lifecycle
+        // status is silently overridden (spec §7A.2 hard rule).
         lifecycle_status: "candidate",
         version: srcLoop.version,
-        schema_version: srcLoop.schema_version ?? PEAKS_BUNDLE_SCHEMA_VERSIONS.loop,
-        archived_at: typeof srcLoop.archived_at === "string"
-            ? srcLoop.archived_at
-            : new Date().toISOString(),
-        shareable: srcLoop.shareable === undefined ? 1 : srcLoop.shareable ? 1 : 0,
-        share_excluded_paths: JSON.stringify(srcLoop.share_excluded_paths ?? []),
-        desktop_visible: srcLoop.desktop_visible === undefined
-            ? 1
-            : srcLoop.desktop_visible
-                ? 1
-                : 0,
+        schema_version: typeof srcLoop.schema_version === "string" && srcLoop.schema_version.length > 0
+            ? srcLoop.schema_version
+            : PEAKS_BUNDLE_SCHEMA_VERSIONS.loop,
+        archived_at: isoOrNow(srcLoop.archived_at),
+        shareable: bool01(srcLoop.shareable, 1),
+        share_excluded_paths: jsonArr(srcLoop.share_excluded_paths),
+        desktop_visible: bool01(srcLoop.desktop_visible, 1),
         export_bundle_format: typeof srcLoop.export_bundle_format === "string"
             ? srcLoop.export_bundle_format
             : "peaks.bundle/1",
     };
-    // Defense-in-depth: refuse if lifecycle was anything other than
-    // candidate. (The schema parse above already pinned the constant,
-    // but we layer this so any future schema relaxation cannot
-    // bypass the import-to-candidate rule.)
-    if (loopRow.lifecycle_status !== "candidate") {
-        throw new BundleImportToStableForbiddenError(loopRow.lifecycle_status);
+}
+const LOOP_RELEASE_COLUMNS = [
+    "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",
+];
+/** Insert one loop_release row (or replace on conflict). */
+function insertLoopReleaseRow(db, row) {
+    const placeholders = LOOP_RELEASE_COLUMNS.map(() => "?").join(", ");
+    db.prepare(`INSERT OR REPLACE INTO loop_release (${LOOP_RELEASE_COLUMNS.join(", ")}) VALUES (${placeholders})`).run(...LOOP_RELEASE_COLUMNS.map((c) => row[c]));
+}
+/**
+ * Re-stamp relations (preserving source row content, but the
+ * loop_id is rewritten if `asName` was supplied).
+ */
+function insertLoopBeeRelations(db, manifest, beeIdMap, loopReleaseId) {
+    const stmt = db.prepare(`INSERT OR REPLACE INTO loop_bee_relation (
+       loop_release_id, bee_release_id, role, reason, schema_version, created_at
+     ) VALUES (?, ?, ?, ?, ?, ?)`);
+    for (const rel of manifest.loop_bee_relations) {
+        const r = rel;
+        const originalBeeId = Number(r.bee_release_id);
+        const newBeeId = beeIdMap.get(originalBeeId) ?? originalBeeId;
+        stmt.run(loopReleaseId, newBeeId, str(r.role), str(r.reason), str(r.schema_version, PEAKS_BUNDLE_SCHEMA_VERSIONS.loop_bee_relation), isoOrNow(r.created_at));
     }
-    // First materialise related bee_release rows. The bundle's
-    // loop_bee_relations reference these bee ids; re-stamping the
-    // relations before the bee rows land would FK-constraint fail
-    // on the receiver.
-    const beeIdMap = materialiseRelatedBees(db, manifest.related_bee_releases);
-    const tx = db.transaction(() => {
-        db.prepare(`INSERT OR REPLACE 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 (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`).run(loopRow.id, loopRow.name, loopRow.scenario, loopRow.trigger_policy, loopRow.success_criteria_json, loopRow.interaction_policy, loopRow.feedback_policy, loopRow.evolution_policy, loopRow.evaluator_policy_json, loopRow.linked_bees_json, loopRow.run_history_json, loopRow.crystallization_evidence_json, loopRow.lifecycle_status, loopRow.version, loopRow.schema_version, loopRow.archived_at, loopRow.shareable, loopRow.share_excluded_paths, loopRow.desktop_visible, loopRow.export_bundle_format);
-        // Re-stamp relations (preserving source row content, but the
-        // loop_id is rewritten if `asName` was supplied).
-        for (const rel of manifest.loop_bee_relations) {
-            const r = rel;
-            const originalBeeId = Number(r.bee_release_id);
-            const newBeeId = beeIdMap.get(originalBeeId) ?? originalBeeId;
-            db.prepare(`INSERT OR REPLACE INTO loop_bee_relation (
-           loop_release_id, bee_release_id, role, reason, schema_version, created_at
-         ) VALUES (?, ?, ?, ?, ?, ?)`).run(asName ?? String(r.loop_release_id), newBeeId, String(r.role), String(r.reason ?? ""), String(r.schema_version ?? PEAKS_BUNDLE_SCHEMA_VERSIONS.loop_bee_relation), typeof r.created_at === "string"
-                ? r.created_at
-                : new Date().toISOString());
-        }
-    });
-    tx();
-    return targetId;
 }
-/* ---------------------------------------------------------------------- */
-/* Related-bees materialisation                                            */
-/* ---------------------------------------------------------------------- */
 /**
  * Materialise the related_bee_releases rows in `db`. Returns a map
  * from source bee_release.id → new bee_release.id so the loop /
@@ -323,112 +387,122 @@ function materialiseRelatedBees(db, relatedBees) {
     if (relatedBees.length === 0)
         return map;
     for (const raw of relatedBees) {
-        const obj = raw;
-        const release = obj.bee_release ?? {};
-        const srcId = Number(release.id);
-        if (!Number.isInteger(srcId) || srcId <= 0)
-            continue;
-        const beeName = String(release.bee_name ?? "");
-        if (!beeName)
-            continue;
-        // Honour the same non-candidate hard rule at the bee row.
-        const srcStatus = typeof release.lifecycle_status === "string"
-            ? release.lifecycle_status
-            : "candidate";
-        if (srcStatus !== "candidate") {
-            throw new BundleImportToStableForbiddenError(srcStatus);
-        }
-        // Pre-existing receiver-side bee with the same name → keep its id.
-        const existing = db
-            .prepare("SELECT id FROM bee_release WHERE bee_name = ?")
-            .get(beeName);
-        let newId;
-        if (existing) {
-            newId = existing.id;
-        }
-        else {
-            const ins = db.prepare(`INSERT INTO bee_release (
-           bee_name, version, source, archived_at, archived_by, user_intent_raw,
-           description, parent_version, changelog, shareable, desktop_visible
-         ) VALUES (?, ?, 'user', ?, 'user', ?, ?, ?, ?, ?, ?)`);
-            const info = ins.run(beeName, String(release.version ?? "0.0.0"), new Date().toISOString(), release.user_intent_raw ?? null, release.description ?? null, release.parent_version ?? null, release.changelog ?? null, release.shareable === false ? 0 : 1, release.desktop_visible === false ? 0 : 1);
-            newId = Number(info.lastInsertRowid);
-            if (obj.manifest) {
-                const m = obj.manifest;
-                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(newId, String(m.schema_version ?? "peaks.bee/1"), String(m.description ?? ""), JSON.stringify(m.segments_json ?? []), m.entrypoint_preamble ?? null, String(m.promotion ?? "manual"), m.min_cycles ?? null, m.requires_human === undefined ? 1 : Number(m.requires_human), m.requires_smoke === undefined ? 1 : Number(m.requires_smoke), m.retire_on_misses ?? null);
-            }
-        }
-        map.set(srcId, newId);
+        const entry = raw;
+        const inserted = materialiseSingleRelatedBee(db, entry);
+        if (inserted !== null)
+            map.set(inserted.srcId, inserted.newId);
     }
     return map;
 }
+/**
+ * Materialise one related bee. Returns null if the entry is not
+ * importable (missing id or bee_name). Otherwise returns the
+ * src→new id pair so the caller can record it in the redirect map.
+ */
+function materialiseSingleRelatedBee(db, entry) {
+    const release = entry.bee_release ?? {};
+    const srcId = Number(release.id);
+    if (!Number.isInteger(srcId) || srcId <= 0)
+        return null;
+    const beeName = String(release.bee_name ?? "");
+    if (!beeName)
+        return null;
+    // Honour the same non-candidate hard rule at the bee row.
+    enforceImportAsCandidate(readSourceLifecycle(release));
+    // Pre-existing receiver-side bee with the same name → keep its id.
+    const existing = db
+        .prepare("SELECT id FROM bee_release WHERE bee_name = ?")
+        .get(beeName);
+    if (existing)
+        return { srcId, newId: existing.id };
+    return { srcId, newId: insertNewRelatedBee(db, release, entry.manifest) };
+}
+function insertNewRelatedBee(db, release, manifest) {
+    const info = db
+        .prepare(`INSERT INTO bee_release (
+         bee_name, version, source, archived_at, archived_by, user_intent_raw,
+         description, parent_version, changelog, shareable, desktop_visible
+       ) VALUES (?, ?, 'user', ?, 'user', ?, ?, ?, ?, ?, ?)`)
+        .run(String(release.bee_name ?? ""), String(release.version ?? "0.0.0"), nowIso(), release.user_intent_raw ?? null, release.description ?? null, release.parent_version ?? null, release.changelog ?? null, release.shareable === false ? 0 : 1, release.desktop_visible === false ? 0 : 1);
+    const newId = Number(info.lastInsertRowid);
+    if (manifest)
+        insertBeeManifestRow(db, newId, manifest);
+    return newId;
+}
 /* ---------------------------------------------------------------------- */
 /* Bee import                                                                */
 /* ---------------------------------------------------------------------- */
 function importBeeBundle(db, manifest, _blobsDir, asName) {
-    if (!manifest.bee_release) {
+    const beeObj = manifest.bee_release;
+    if (!beeObj) {
         throw new BundleMalformedError("bee_release payload missing from bee bundle");
     }
-    const beeObj = manifest.bee_release;
     const release = beeObj.bee_release;
     const newBeeName = asName ?? String(release.bee_name ?? "");
     if (!newBeeName)
         throw new BundleMalformedError("bee_release.bee_name missing");
     // Same hard rule: any non-candidate import is refused. The reader
     // does not honor --as-stable switches.
-    const srcStatus = typeof release.lifecycle_status === "string"
-        ? release.lifecycle_status
-        : "candidate";
-    if (srcStatus !== "candidate") {
-        throw new BundleImportToStableForbiddenError(srcStatus);
-    }
-    let newId = -1;
+    enforceImportAsCandidate(readSourceLifecycle(release));
     const tx = db.transaction(() => {
-        const ins = db.prepare(`INSERT INTO bee_release (
+        const newId = insertAnchorBeeRelease(db, release, newBeeName);
+        if (beeObj.manifest)
+            insertBeeManifestRow(db, newId, beeObj.manifest);
+        insertBeeSegmentRows(db, newId, beeObj.segments ?? []);
+        insertBeeFileRows(db, newId, newBeeName, beeObj.files ?? []);
+        insertBeeChangeRows(db, newId, beeObj.changes ?? []);
+        return newId;
+    });
+    return tx();
+}
+/** Insert the anchor bee_release row for a `bee` bundle and return its new id. */
+function insertAnchorBeeRelease(db, release, beeName) {
+    const info = db
+        .prepare(`INSERT INTO bee_release (
          bee_name, version, source, archived_at, archived_by, user_intent_raw,
          description, parent_version, changelog, shareable, desktop_visible
-       ) VALUES (?, ?, 'user', ?, 'user', ?, ?, ?, ?, ?, ?)`);
-        const info = ins.run(newBeeName, String(release.version ?? "0.0.0"), new Date().toISOString(), release.user_intent_raw ?? null, release.description ?? null, release.parent_version ?? null, release.changelog ?? null, release.shareable === false ? 0 : 1, release.desktop_visible === false ? 0 : 1);
-        newId = Number(info.lastInsertRowid);
-        if (beeObj.manifest) {
-            const m = beeObj.manifest;
-            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(newId, String(m.schema_version ?? "peaks.bee/1"), String(m.description ?? ""), JSON.stringify(m.segments_json ?? []), m.entrypoint_preamble ?? null, String(m.promotion ?? "manual"), m.min_cycles ?? null, m.requires_human === undefined ? 1 : Number(m.requires_human), m.requires_smoke === undefined ? 1 : Number(m.requires_smoke), m.retire_on_misses ?? null);
-        }
-        for (const s of beeObj.segments ?? []) {
-            db.prepare(`INSERT INTO bee_segment_ref (
-           release_id, segment_name, inputs_json, outputs_json, side_effects
-         ) VALUES (?, ?, ?, ?, ?)`).run(newId, String(s.segment_name ?? ""), s.inputs_json ?? null, s.outputs_json ?? null, s.side_effects ?? null);
-        }
-        for (const f of beeObj.files ?? []) {
-            db.prepare(`INSERT INTO bee_file (
-           release_id, owner_kind, owner_name, path, kind, size_bytes, sha256, blob_path
-         ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`).run(newId, String(f.owner_kind ?? "bee"), newBeeName, String(f.path ?? ""), String(f.kind ?? "other"), Number(f.size_bytes ?? 0), String(f.sha256 ?? ""), String(f.blob_path ?? ""));
-        }
-        for (const c of beeObj.changes ?? []) {
-            db.prepare(`INSERT INTO bee_change (
-           release_id, change_kind, target_kind, target_name, detail
-         ) VALUES (?, ?, ?, ?, ?)`).run(newId, String(c.change_kind ?? ""), String(c.target_kind ?? ""), String(c.target_name ?? ""), c.detail ?? null);
-        }
-    });
-    tx();
-    return newId;
+       ) VALUES (?, ?, 'user', ?, 'user', ?, ?, ?, ?, ?, ?)`)
+        .run(beeName, String(release.version ?? "0.0.0"), nowIso(), release.user_intent_raw ?? null, release.description ?? null, release.parent_version ?? null, release.changelog ?? null, release.shareable === false ? 0 : 1, release.desktop_visible === false ? 0 : 1);
+    return Number(info.lastInsertRowid);
 }
-/* ---------------------------------------------------------------------- */
-/* Utility                                                                  */
-/* ---------------------------------------------------------------------- */
-function readDirEntries(dir) {
-    try {
-        return readdirSync(dir);
+/** Insert one bee_manifest row. */
+function insertBeeManifestRow(db, releaseId, manifest) {
+    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(releaseId, String(manifest.schema_version ?? "peaks.bee/1"), String(manifest.description ?? ""), JSON.stringify(manifest.segments_json ?? []), strOrNull(manifest.entrypoint_preamble), String(manifest.promotion ?? "manual"), manifest.min_cycles ?? null, manifest.requires_human === undefined ? 1 : Number(manifest.requires_human), manifest.requires_smoke === undefined ? 1 : Number(manifest.requires_smoke), manifest.retire_on_misses ?? null);
+}
+/** Insert bee_segment_ref rows. */
+function insertBeeSegmentRows(db, releaseId, segments) {
+    if (segments.length === 0)
+        return;
+    const stmt = db.prepare(`INSERT INTO bee_segment_ref (
+       release_id, segment_name, inputs_json, outputs_json, side_effects
+     ) VALUES (?, ?, ?, ?, ?)`);
+    for (const s of segments) {
+        stmt.run(releaseId, String(s.segment_name ?? ""), strOrNull(s.inputs_json), strOrNull(s.outputs_json), strOrNull(s.side_effects));
     }
-    catch {
-        return [];
+}
+/** Insert bee_file rows. */
+function insertBeeFileRows(db, releaseId, beeName, files) {
+    if (files.length === 0)
+        return;
+    const stmt = db.prepare(`INSERT INTO bee_file (
+       release_id, owner_kind, owner_name, path, kind, size_bytes, sha256, blob_path
+     ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+    for (const f of files) {
+        stmt.run(releaseId, String(f.owner_kind ?? "bee"), beeName, String(f.path ?? ""), String(f.kind ?? "other"), Number(f.size_bytes ?? 0), String(f.sha256 ?? ""), String(f.blob_path ?? ""));
+    }
+}
+/** Insert bee_change rows. */
+function insertBeeChangeRows(db, releaseId, changes) {
+    if (changes.length === 0)
+        return;
+    const stmt = db.prepare(`INSERT INTO bee_change (
+       release_id, change_kind, target_kind, target_name, detail
+     ) VALUES (?, ?, ?, ?, ?)`);
+    for (const c of changes) {
+        stmt.run(releaseId, String(c.change_kind ?? ""), String(c.target_kind ?? ""), String(c.target_name ?? ""), strOrNull(c.detail));
     }
 }

package/dist/services/skills/hooks-settings-service.d.ts

@@ -129,6 +129,39 @@ export type PeaksHookEntry = {
     command: string;
     event: string;
 };
+/**
+ * Compute the per-IDE peaks hook entries to merge into the settings file.
+ * Replaces the slice #1 hardcoded `PEAKS_HOOK_ENTRIES` constant; the constant
+ * remains exported (computed for claude-code) for backward compat.
+ *
+ * Slice #013 (`--no-progress` flag): when `skipProgress` is true, the
+ * progress-start entry is omitted from the returned list. Install with this
+ * flag will (a) NOT emit the progress hook entry, and (b) will idempotently
+ * remove any previously-installed progress entry (sentinel-based merge).
+ *
+ * Slice #014 (refactor — full removal): only the gate-enforce entry is
+ * ever emitted. The `skipProgress` parameter is kept for API stability
+ * but is a no-op — the returned list is always single-entry. The progress
+ * entry's sentinel is included in the legacy sentinel set so uninstall
+ * can find + remove any stale progress-start entry that an older
+ * `peaks hooks install` may have written before this slice.
+ *
+ * Slice 2026-08-06-session-outer-cache: a SessionStart outer-cache primer
+ * entry is appended for Claude Code only (SessionStart is a Claude-Code-
+ * specific event key today).
+ */
+/**
+ * Slice 2026-08-06-codegate-vendor-neutral — code-gate hook entry.
+ * Vendor-neutral command (`peaks code-gate --json`); the CLI adapter
+ * lives in `src/cli/commands/code-gate-command.ts` and the decision
+ * logic lives in `src/services/hooks/pre-tool-code-gate.ts`. The
+ * shell-script sibling (`src/services/hooks/pre-tool-code-gate.sh`)
+ * encodes the same logic for non-Node harnesses.
+ */
+export declare const HOOK_CODE_GATE_SENTINEL = "peaks code-gate";
+export declare const HOOK_CODE_GATE_MATCHER = "Edit|Write|MultiEdit";
+export declare const HOOK_CODE_GATE_EVENT = "PreToolUse";
+export declare const HOOK_CODE_GATE_COMMAND = "peaks code-gate --json";
 /**
  * The set of Skills whose use is denied at the IDE permissions layer for
  * every `peaks hooks install` call. Each entry is the namespace-qualified