peaks-loop 3.1.2 → 4.0.0-beta.10

package/dist/services/skill/skill-search-service.d.ts

@@ -0,0 +1,88 @@
+/**
+ * peaks skill search — service-layer primitive for S0 of the
+ * 4.0.0-beta.5 peaks-solo dispatcher release.
+ *
+ * Spec: docs/superpowers/specs/2026-07-08-peaks-solo-dispatcher-design.md §3.2
+ * Plan: docs/superpowers/plans/2026-07-08-peaks-solo-dispatcher/s0-skill-search-cli.md
+ *
+ * This service is the single source of truth for skill pool retrieval
+ * and is reused by the `peaks skill search` CLI. It is intentionally
+ * pure (synchronous frontmatter parse + substring scoring) so the
+ * dispatcher (`peaks-solo`, S1) can call it without paying for any
+ * async I/O during the triage decision flow.
+ *
+ * v1 scope (locked, see plan §"Match rules (v1)"):
+ *   - --query: case-insensitive substring match on description + triggers
+ *   - --tag:   case-insensitive exact match on `metadata.tags`
+ *   - --domain: exact match on `metadata.domain` (locked enum)
+ *   - All three compose with AND; at least one filter is required
+ *   - No match → `[]` (not error, not null)
+ *   - --limit truncates to the top N by matchScore desc
+ *
+ * Out of v1 scope (deferred, see plan §"Goal"): fuzzy / FTS5 / semantic
+ * matching, ML-based ranking, pagination, i18n, caching.
+ */
+import { z } from 'zod';
+import { skillsDir } from '../../shared/paths.js';
+export declare const SkillSearchInputSchema: z.ZodEffects<z.ZodObject<{
+    query: z.ZodOptional<z.ZodString>;
+    tag: z.ZodOptional<z.ZodString>;
+    domain: z.ZodOptional<z.ZodEnum<["code", "content", "doctor", "research", "triage", "sop", "audit", "final-review", "resume", "status", "test", "ide", "slice-decompose", "issue-fix-orchestrator", "perf-audit", "security-audit", "reviewer"]>>;
+    limit: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+}, "strip", z.ZodTypeAny, {
+    limit: number;
+    query?: string | undefined;
+    tag?: string | undefined;
+    domain?: "code" | "status" | "content" | "test" | "doctor" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+}, {
+    limit?: number | undefined;
+    query?: string | undefined;
+    tag?: string | undefined;
+    domain?: "code" | "status" | "content" | "test" | "doctor" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+}>, {
+    limit: number;
+    query?: string | undefined;
+    tag?: string | undefined;
+    domain?: "code" | "status" | "content" | "test" | "doctor" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+}, {
+    limit?: number | undefined;
+    query?: string | undefined;
+    tag?: string | undefined;
+    domain?: "code" | "status" | "content" | "test" | "doctor" | "resume" | "ide" | "research" | "triage" | "sop" | "audit" | "final-review" | "slice-decompose" | "issue-fix-orchestrator" | "perf-audit" | "security-audit" | "reviewer" | undefined;
+}>;
+export type SkillSearchInput = z.input<typeof SkillSearchInputSchema>;
+export declare const SkillSearchResultSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    triggers: z.ZodArray<z.ZodString, "many">;
+    tags: z.ZodArray<z.ZodString, "many">;
+    domain: z.ZodString;
+    matchScore: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    name: string;
+    description: string;
+    domain: string;
+    triggers: string[];
+    tags: string[];
+    matchScore: number;
+}, {
+    name: string;
+    description: string;
+    domain: string;
+    triggers: string[];
+    tags: string[];
+    matchScore: number;
+}>;
+export type SkillSearchResult = z.infer<typeof SkillSearchResultSchema>;
+/**
+ * Search the in-tree skill pool. Validates `input` against
+ * `SkillSearchInputSchema`; the schema's refine rejects empty input
+ * with a ZodError, which is the contract test U-7 / I-3 rely on.
+ *
+ * @param input  One of `query | tag | domain` is required.
+ *               All provided filters compose with AND.
+ * @returns      Matching skills sorted by matchScore desc, name asc.
+ *               Empty array (not error, not null) when nothing matches.
+ */
+export declare function searchSkills(rawInput: SkillSearchInput): Promise<SkillSearchResult[]>;
+export { skillsDir as __skillsDirForTests };

package/dist/services/skill/skill-search-service.js

@@ -0,0 +1,228 @@
+/**
+ * peaks skill search — service-layer primitive for S0 of the
+ * 4.0.0-beta.5 peaks-solo dispatcher release.
+ *
+ * Spec: docs/superpowers/specs/2026-07-08-peaks-solo-dispatcher-design.md §3.2
+ * Plan: docs/superpowers/plans/2026-07-08-peaks-solo-dispatcher/s0-skill-search-cli.md
+ *
+ * This service is the single source of truth for skill pool retrieval
+ * and is reused by the `peaks skill search` CLI. It is intentionally
+ * pure (synchronous frontmatter parse + substring scoring) so the
+ * dispatcher (`peaks-solo`, S1) can call it without paying for any
+ * async I/O during the triage decision flow.
+ *
+ * v1 scope (locked, see plan §"Match rules (v1)"):
+ *   - --query: case-insensitive substring match on description + triggers
+ *   - --tag:   case-insensitive exact match on `metadata.tags`
+ *   - --domain: exact match on `metadata.domain` (locked enum)
+ *   - All three compose with AND; at least one filter is required
+ *   - No match → `[]` (not error, not null)
+ *   - --limit truncates to the top N by matchScore desc
+ *
+ * Out of v1 scope (deferred, see plan §"Goal"): fuzzy / FTS5 / semantic
+ * matching, ML-based ranking, pagination, i18n, caching.
+ */
+import { z } from 'zod';
+import { listSkills } from '../skills/skill-registry.js';
+import { parseFrontmatter } from '../../shared/frontmatter.js';
+import { readText } from '../../shared/fs.js';
+import { skillsDir } from '../../shared/paths.js';
+const SKILL_DOMAINS = [
+    'code',
+    'content',
+    'doctor',
+    'research',
+    'triage',
+    'sop',
+    'audit',
+    'final-review',
+    'resume',
+    'status',
+    'test',
+    'ide',
+    'slice-decompose',
+    'issue-fix-orchestrator',
+    'perf-audit',
+    'security-audit',
+    'reviewer'
+];
+export const SkillSearchInputSchema = z
+    .object({
+    query: z.string().min(1).max(500).optional(),
+    tag: z.string().min(1).max(100).optional(),
+    domain: z.enum(SKILL_DOMAINS).optional(),
+    limit: z.number().int().min(1).max(100).optional().default(20)
+})
+    .refine((v) => v.query !== undefined || v.tag !== undefined || v.domain !== undefined, { message: 'At least one of --query / --tag / --domain is required' });
+export const SkillSearchResultSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    triggers: z.array(z.string()),
+    tags: z.array(z.string()),
+    domain: z.string(),
+    matchScore: z.number().min(0).max(1)
+});
+/**
+ * Extract trigger phrases from a skill description. The convention is
+ * `Triggers on \`/x\`, "y", "z".` at the end of the description
+ * (or anywhere within). v1 parses quoted/back-tick tokens after the
+ * "Triggers on" marker. When the marker is missing, the trigger set
+ * is empty (description-only matching still works).
+ */
+function extractTriggers(description) {
+    const lower = description.toLowerCase();
+    const marker = 'triggers on';
+    const idx = lower.indexOf(marker);
+    if (idx === -1)
+        return [];
+    const after = description.slice(idx + marker.length);
+    // Stop at the first period that ends the trigger clause.
+    // Heuristic: take everything up to the next `.` that is followed by
+    // whitespace + capital letter, or end-of-string.
+    const stopMatch = /\.\s+[A-Z]|\.\s*$/.exec(after);
+    const clause = stopMatch ? after.slice(0, stopMatch.index + 1) : after;
+    // Extract every quoted/back-tick token.
+    const tokenRegex = /[`"']([^`"']+)[`"']/g;
+    const out = [];
+    let m;
+    while ((m = tokenRegex.exec(clause)) !== null) {
+        if (m[1] !== undefined)
+            out.push(m[1]);
+    }
+    return out;
+}
+/**
+ * Parse metadata tags / domain from the raw SKILL.md frontmatter.
+ * `parseFrontmatter()` flattens nested YAML mapping into dotted keys,
+ * so `metadata.tags: a, b` becomes a single string we split on `, `.
+ * The existing `skill-registry` already calls `parseFrontmatter` but
+ * does not surface the metadata block, so we re-parse the file.
+ *
+ * R8 mitigation: if the file is missing, malformed, or unreadable we
+ * return empty tags + domain so the search itself can still proceed
+ * with description-only matching. The malformed-file warning is
+ * already emitted by the registry layer (`loadSkillRegistry`'s
+ * `failures[]` channel); this function is best-effort metadata.
+ */
+async function parseMetadata(skillPath) {
+    try {
+        const raw = await readText(skillPath);
+        const fm = parseFrontmatter(raw);
+        const tagsRaw = fm['metadata.tags'] ?? '';
+        const tags = tagsRaw
+            .split(',')
+            .map((t) => t.trim())
+            .filter((t) => t.length > 0);
+        const domain = (fm['metadata.domain'] ?? '').trim();
+        return { tags, domain };
+    }
+    catch {
+        return { tags: [], domain: '' };
+    }
+}
+async function loadEnrichedSkills() {
+    const skills = await listSkills();
+    return Promise.all(skills.map(async (s) => {
+        const meta = await parseMetadata(s.skillPath);
+        return {
+            name: s.name,
+            description: s.description,
+            triggers: extractTriggers(s.description),
+            tags: meta.tags,
+            domain: meta.domain,
+            skillPath: s.skillPath
+        };
+    }));
+}
+/**
+ * Substring match score for a single (skill, query) pair.
+ *
+ * matchScore = 0.5 * (query_hits_in_description / description_length_words)
+ *            + 0.5 * (query_hits_in_triggers / triggers_count)
+ *            clamped to [0, 1]
+ *
+ * "hits" = number of occurrences of the query substring (lowercased)
+ * in the lowercased target. Length is normalized as word count (so a
+ * 1-word description that matches returns the full 0.5 contribution).
+ */
+function scoreQuery(query, description, triggers) {
+    const q = query.toLowerCase();
+    const desc = description.toLowerCase();
+    const descHits = countOccurrences(desc, q);
+    const descWords = Math.max(1, desc.split(/\s+/).filter((w) => w.length > 0).length);
+    const descContribution = Math.min(1, descHits / descWords);
+    const triggersJoined = triggers.map((t) => t.toLowerCase()).join(' | ');
+    const trigHits = countOccurrences(triggersJoined, q);
+    const trigCount = Math.max(1, triggers.length);
+    const trigContribution = Math.min(1, trigHits / trigCount);
+    const raw = 0.5 * descContribution + 0.5 * trigContribution;
+    // Clamp to [0, 1] and round to 4 decimals to keep envelope tidy.
+    return Math.round(Math.max(0, Math.min(1, raw)) * 10_000) / 10_000;
+}
+function countOccurrences(haystack, needle) {
+    if (needle.length === 0)
+        return 0;
+    let count = 0;
+    let pos = 0;
+    while (pos <= haystack.length) {
+        const next = haystack.indexOf(needle, pos);
+        if (next === -1)
+            break;
+        count += 1;
+        pos = next + needle.length;
+    }
+    return count;
+}
+/**
+ * Search the in-tree skill pool. Validates `input` against
+ * `SkillSearchInputSchema`; the schema's refine rejects empty input
+ * with a ZodError, which is the contract test U-7 / I-3 rely on.
+ *
+ * @param input  One of `query | tag | domain` is required.
+ *               All provided filters compose with AND.
+ * @returns      Matching skills sorted by matchScore desc, name asc.
+ *               Empty array (not error, not null) when nothing matches.
+ */
+export async function searchSkills(rawInput) {
+    const input = SkillSearchInputSchema.parse(rawInput);
+    const skills = await loadEnrichedSkills();
+    const filtered = skills.filter((skill) => {
+        if (input.tag !== undefined) {
+            const wanted = input.tag.toLowerCase();
+            const has = skill.tags.some((t) => t.toLowerCase() === wanted);
+            if (!has)
+                return false;
+        }
+        if (input.domain !== undefined) {
+            if (skill.domain.toLowerCase() !== input.domain.toLowerCase())
+                return false;
+        }
+        if (input.query !== undefined) {
+            const q = input.query.toLowerCase();
+            const inDesc = skill.description.toLowerCase().includes(q);
+            const inTrig = skill.triggers.some((t) => t.toLowerCase().includes(q));
+            if (!inDesc && !inTrig)
+                return false;
+        }
+        return true;
+    });
+    const scored = filtered.map((skill) => ({
+        name: skill.name,
+        description: skill.description,
+        triggers: skill.triggers,
+        tags: skill.tags,
+        domain: skill.domain,
+        matchScore: input.query !== undefined
+            ? scoreQuery(input.query, skill.description, skill.triggers)
+            : 1
+    }));
+    scored.sort((a, b) => {
+        if (b.matchScore !== a.matchScore)
+            return b.matchScore - a.matchScore;
+        return a.name.localeCompare(b.name);
+    });
+    return scored.slice(0, input.limit);
+}
+// Re-export `skillsDir` only for tests that want to assert on-disk I/O
+// behavior end-to-end. Not part of the public CLI surface.
+export { skillsDir as __skillsDirForTests };

package/dist/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/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/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/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/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/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/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/services/skillhub/release-import.js

@@ -0,0 +1,64 @@
+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.
+    // M3 / spec §4.2: the new `shareable` and `desktop_visible` columns
+    // are written with their spec defaults (true). Future import
+    // payloads may carry these explicitly (M7 bundle format); until
+    // then M3 keeps defaulting on the insert path so existing call
+    // sites stay source-compatible.
+    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, shareable, desktop_visible) VALUES (?, ?, 'user', ?, 'user', ?, ?, ?, ?, 1, 1)`);
+        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/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;

package/dist/services/skillhub/release-retain.js

@@ -0,0 +1,94 @@
+import { createHash } from "node:crypto";
+import { readFileSync, readdirSync, writeFileSync, mkdirSync, existsSync } from "node:fs";
+import { join, relative } from "node:path";
+/** Compute the sha256 hash and byte length of a single file. */
+export function sha256OfFile(p) {
+    const buf = readFileSync(p);
+    return { sha: createHash("sha256").update(buf).digest("hex"), bytes: buf.length };
+}
+/** 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 function ensureBlob(blobsDir, sha, srcPath) {
+    const dir = join(blobsDir, sha.slice(0, 2));
+    const dest = join(dir, sha);
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    if (!existsSync(dest))
+        writeFileSync(dest, readFileSync(srcPath));
+    return `blobs/${sha.slice(0, 2)}/${sha}`;
+}
+export function* walk(root, base = root) {
+    for (const ent of readdirSync(base, { withFileTypes: true })) {
+        const abs = join(base, ent.name);
+        if (ent.isDirectory())
+            yield* walk(root, abs);
+        else {
+            const relPosix = relative(root, abs).split(/[\\/]/).join("/");
+            yield { abs, rel: relPosix };
+        }
+    }
+}
+function warnOverflow(column, length) {
+    // Soft warning, no truncation: the spec does not mandate truncation,
+    // but a stale over-16KB row would silently break downstream readers
+    // that assume <16KB. Surface it for ops review.
+    // eslint-disable-next-line no-console
+    console.warn(`[release-retain] WARN: column ${column} overflowed 16KB guard (${length} bytes) — review and consider truncation`);
+}
+/**
+ * Defensive 16KB check: if the value would exceed SQLite's
+ * recommended 16KB single-column limit, log a warning. Not a hard
+ * error — we let SQLite handle overflow. The columns covered are the
+ * four TEXT columns previously unchecked: bee_manifest.segments_json,
+ * bee_segment_ref.inputs_json, bee_segment_ref.outputs_json,
+ * bee_segment_ref.side_effects.
+ */
+function checkOverflow({ table, col }, value) {
+    const len = Buffer.byteLength(value, "utf-8");
+    if (len > 16 * 1024)
+        warnOverflow(`${table}.${col}`, len);
+}
+export function retainRelease({ db, blobsDir, scratchDir, manifest, version: explicitVersion, parentVersion, changelog, }) {
+    const version = explicitVersion ?? "0.1.0";
+    const tx = db.transaction(() => {
+        // M3 / spec §4.2: `shareable` and `desktop_visible` are written
+        // with their spec defaults (true). M7 will add a CLI flag to
+        // override on retain; M3 keeps the defaulting on the insert path
+        // so existing call sites stay source-compatible. The two new
+        // columns were added by migration 004-loop-bee-extension.sql.
+        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', ?, ?, ?, ?, ?, ?, 1, 1)`);
+        const info = ins.run(manifest.name, version, new Date().toISOString(), "llm", null, manifest.description, parentVersion ?? null, changelog ?? null);
+        const id = info.lastInsertRowid;
+        db.prepare(`INSERT OR REPLACE INTO bee_release_pointer (bee_name, latest_version, released_at) VALUES (?, ?, ?)`).run(manifest.name, version, new Date().toISOString());
+        for (const s of manifest.segments) {
+            const inputsJson = JSON.stringify(s.inputs);
+            const outputsJson = JSON.stringify(s.outputs);
+            const sideEffectsStr = s.sideEffects.join(",");
+            checkOverflow({ table: "bee_segment_ref", col: "inputs_json" }, inputsJson);
+            checkOverflow({ table: "bee_segment_ref", col: "outputs_json" }, outputsJson);
+            checkOverflow({ table: "bee_segment_ref", col: "side_effects" }, sideEffectsStr);
+            db.prepare(`INSERT INTO bee_segment_ref (release_id, segment_name, inputs_json, outputs_json, side_effects) VALUES (?, ?, ?, ?, ?)`).run(id, s.name, inputsJson, outputsJson, sideEffectsStr);
+        }
+        // Also guard the manifest-level JSON column that holds the segment
+        // name list (can exceed 16KB if a bee advertises thousands of
+        // segments).
+        const segmentsJson = JSON.stringify(manifest.segments.map((s) => s.name));
+        checkOverflow({ table: "bee_manifest", col: "segments_json" }, segmentsJson);
+        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, manifest.schemaVersion, manifest.description, segmentsJson, manifest.entrypoint.preamble, manifest.promotion_status, manifest.promotion.minCycles, manifest.promotion.requiresHumanApproval ? 1 : 0, manifest.promotion.requiresSmokeTest ? 1 : 0, manifest.promotion.retireOnMissesInRow ?? null);
+        const insFile = db.prepare(`INSERT INTO bee_file (release_id, owner_kind, owner_name, path, kind, size_bytes, sha256, blob_path) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`);
+        for (const f of walk(scratchDir)) {
+            const { sha, bytes } = sha256OfFile(f.abs);
+            const blobPath = ensureBlob(blobsDir, sha, f.abs);
+            const kind = f.rel.endsWith(".md")
+                ? "markdown"
+                : f.rel.startsWith("scripts/")
+                    ? "script"
+                    : f.rel.startsWith("references/")
+                        ? "reference"
+                        : "other";
+            insFile.run(id, "bee", manifest.name, f.rel, kind, bytes, sha, blobPath);
+        }
+        return id;
+    });
+    return tx();
+}