peaks-loop 4.0.0-beta.8 → 4.0.1

package/dist/services/skillhub/migrations/006-crystallization-event.sql

@@ -0,0 +1,92 @@
+-- 006-crystallization-event.sql — M5 / spec §4.5 / §4.7 / §5 / §7.2
+-- Adds the `crystallization_event` table for the post-run
+-- crystallization layer. Non-breaking: this migration does NOT
+-- touch any pre-existing table. The new table lives alongside the
+-- existing skillhub schema (see 001-initial.sql, 002-loop-release.sql,
+-- 003-loop-bee-relation.sql, 004-loop-bee-extension.sql,
+-- 005-evolution-evaluation.sql).
+--
+-- The table stores the durable evidence of a crystallization event:
+--   - trigger                          (user_explicit | llm_suggested |
+--                                       success_default_prompt |
+--                                       similar_task_recurrence)
+--   - evidence_brief                   (JSON: 4 sections)
+--       * what_happened                (1-2 sentence factual account)
+--       * why_it_matters               (1-2 sentence explanation)
+--       * what_learned                 (1-2 sentence learning)
+--       * what_action                  (1 sentence recommended action)
+--   - source_trace_pointers            (JSON array of workflow trace ids)
+--   - evaluator_summary                (short NL summary from scorers)
+--   - user_decision_summary            (NL account of the user choice)
+--   - created_loop_release_id          (FK to loop_release, optional)
+--   - updated_loop_release_id          (FK to loop_release, optional)
+--   - created_bee_release_id           (FK to bee_release, optional)
+--   - updated_bee_release_id           (FK to bee_release, optional)
+--   - lifecycle_status                 (candidate | stable | retired;
+--                                       the EVENT's status, distinct
+--                                       from the loop_release status).
+--
+-- The four-section brief (spec §4.7 / §10 RL-7) is required at the
+-- service layer; the DB stores whatever JSON the service persists. A
+-- schema-version bump can introduce a CHECK shape constraint on the
+-- brief in a future migration; the service layer is the authoritative
+-- guard today.
+--
+-- Schema versioning: every new table carries `schema_version` pinned
+-- to the literal `peaks.crystallization/1` via CHECK constraint.
+--
+-- All JSON-shaped payloads (brief, source_trace_pointers, bullets)
+-- are stored as TEXT and parsed at the store / Zod boundary —
+-- same convention as the existing tables; no big JSON BLOB at the
+-- SQLite layer.
+
+CREATE TABLE IF NOT EXISTS crystallization_event (
+  id                          TEXT PRIMARY KEY,
+  trigger                     TEXT NOT NULL CHECK (trigger IN (
+                                'user_explicit',
+                                'llm_suggested',
+                                'success_default_prompt',
+                                'similar_task_recurrence'
+                              )),
+  -- The 4-section brief. The shape guard (all four sections present)
+  -- is enforced at the service layer (CrystallizationService); the
+  -- DB stores whatever the service persists. See spec §4.7 / §10 RL-7.
+  evidence_brief_json         TEXT NOT NULL,
+  evidence_bullets_json       TEXT NOT NULL DEFAULT '[]',
+  source_trace_pointers_json  TEXT NOT NULL DEFAULT '[]',
+  evaluator_summary           TEXT NOT NULL DEFAULT '',
+  user_decision_summary       TEXT NOT NULL DEFAULT '',
+  created_loop_release_id     TEXT REFERENCES loop_release(id) ON DELETE SET NULL,
+  updated_loop_release_id     TEXT REFERENCES loop_release(id) ON DELETE SET NULL,
+  created_bee_release_id      INTEGER REFERENCES bee_release(id) ON DELETE SET NULL,
+  updated_bee_release_id      INTEGER REFERENCES bee_release(id) ON DELETE SET NULL,
+  -- The EVENT's lifecycle (independent of any created/updated asset).
+  -- 'candidate' after crystallization; 'stable' after user-confirmed
+  -- promotion; 'retired' after explicit dispose. Mirrors the loop
+  -- status union (spec §4.1) without a 1:1 identity — these are
+  -- orthogonal lifecycles.
+  lifecycle_status            TEXT NOT NULL DEFAULT 'candidate'
+                                CHECK (lifecycle_status IN ('candidate','stable','retired')),
+  schema_version              TEXT NOT NULL CHECK (schema_version = 'peaks.crystallization/1'),
+  created_at                  TEXT NOT NULL,
+  CHECK (length(id) > 0),
+  -- Defense in depth on the brief shape: at least one of the four
+  -- keys must be present in the JSON object. SQLite JSON1 (>= 3.38)
+  -- supports json_extract; we keep the check loose (length > 2 to
+  -- rule out '{}') so older SQLite still accepts the row, and rely
+  -- on the service-layer guard for the strict 4-section rule.
+  CHECK (length(evidence_brief_json) >= 2)
+);
+
+CREATE INDEX IF NOT EXISTS idx_crystallization_event_created_loop
+  ON crystallization_event(created_loop_release_id);
+CREATE INDEX IF NOT EXISTS idx_crystallization_event_updated_loop
+  ON crystallization_event(updated_loop_release_id);
+CREATE INDEX IF NOT EXISTS idx_crystallization_event_created_bee
+  ON crystallization_event(created_bee_release_id);
+CREATE INDEX IF NOT EXISTS idx_crystallization_event_updated_bee
+  ON crystallization_event(updated_bee_release_id);
+CREATE INDEX IF NOT EXISTS idx_crystallization_event_lifecycle
+  ON crystallization_event(lifecycle_status);
+CREATE INDEX IF NOT EXISTS idx_crystallization_event_created_at
+  ON crystallization_event(created_at);

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();
+}

package/dist/services/skillhub/sqlite-store.d.ts

@@ -0,0 +1,22 @@
+import Database from "better-sqlite3";
+/**
+ * Open (or create) a SkillHub state database at the given path.
+ *
+ * Behavior:
+ *   - Creates the parent directory if it does not exist.
+ *   - Enables WAL journal mode and foreign-key enforcement.
+ *   - Applies every `migrations/*.sql` file in lexicographic order.
+ *     Migrations must be idempotent (CREATE TABLE IF NOT EXISTS, etc.).
+ *
+ * The migrations directory lives next to this source file at build time;
+ * we resolve it via `import.meta.url` so the lookup survives vitest ESM
+ * (where `__dirname` is undefined). Migration files are discovered by
+ * globbing (`*.sql`) and sorted lexicographically so future
+ * `002-…`, `003-…` additions are picked up automatically.
+ */
+export declare function openStateDb(path: string): Database.Database;
+/**
+ * Return the user-defined table names present in `db` (excluding SQLite
+ * system tables such as `sqlite_sequence`).
+ */
+export declare function listTables(db: Database.Database): string[];

package/dist/services/skillhub/sqlite-store.js

@@ -0,0 +1,63 @@
+import Database from "better-sqlite3";
+import { readFileSync, readdirSync, existsSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+/**
+ * Open (or create) a SkillHub state database at the given path.
+ *
+ * Behavior:
+ *   - Creates the parent directory if it does not exist.
+ *   - Enables WAL journal mode and foreign-key enforcement.
+ *   - Applies every `migrations/*.sql` file in lexicographic order.
+ *     Migrations must be idempotent (CREATE TABLE IF NOT EXISTS, etc.).
+ *
+ * The migrations directory lives next to this source file at build time;
+ * we resolve it via `import.meta.url` so the lookup survives vitest ESM
+ * (where `__dirname` is undefined). Migration files are discovered by
+ * globbing (`*.sql`) and sorted lexicographically so future
+ * `002-…`, `003-…` additions are picked up automatically.
+ */
+export function openStateDb(path) {
+    const parent = dirname(path);
+    if (!existsSync(parent))
+        mkdirSync(parent, { recursive: true });
+    const db = new Database(path);
+    db.pragma("journal_mode = WAL");
+    db.pragma("foreign_keys = ON");
+    const here = dirname(fileURLToPath(import.meta.url));
+    const migrationsDir = join(here, "migrations");
+    if (existsSync(migrationsDir)) {
+        const files = readdirSync(migrationsDir).filter((f) => f.endsWith(".sql")).sort();
+        for (const f of files) {
+            const sql = readFileSync(join(migrationsDir, f), "utf-8");
+            try {
+                db.exec(sql);
+            }
+            catch (err) {
+                // Tolerate idempotent re-runs of `ALTER TABLE ... ADD COLUMN`
+                // migrations (e.g. 004-loop-bee-extension). The migration
+                // files themselves are NOT idempotent (SQLite has no
+                // `ALTER TABLE ADD COLUMN IF NOT EXISTS`); the runner is
+                // made idempotent here so the same state.db can be opened
+                // by multiple CLI processes within one workflow.
+                const msg = err instanceof Error ? err.message : String(err);
+                if (msg.includes("duplicate column name") ||
+                    msg.includes("already exists")) {
+                    continue;
+                }
+                throw err;
+            }
+        }
+    }
+    return db;
+}
+/**
+ * Return the user-defined table names present in `db` (excluding SQLite
+ * system tables such as `sqlite_sequence`).
+ */
+export function listTables(db) {
+    const rows = db
+        .prepare("SELECT name FROM sqlite_master WHERE type='table' AND name NOT LIKE 'sqlite_%'")
+        .all();
+    return rows.map((r) => r.name);
+}

package/dist/services/skillhub/tar-runtime.d.ts

@@ -0,0 +1,21 @@
+/** Thrown when no usable tar binary can be located. */
+export declare class TAR_NOT_FOUND extends Error {
+    constructor(msg: string);
+}
+/**
+ * Run `tar <args...>` in a cross-platform way.
+ *
+ * Args MUST be `["-czf", outPath, "-C", stageDir, "."]` style (no
+ * shell quoting needed because we use execFileSync, not execSync).
+ *
+ * After the Critical #3 fix:
+ *   - Honors PEAKS_TAR_BIN / TAR env vars.
+ *   - On Windows, tries C:\Windows\System32\tar.exe first; falls back
+ *     to PATH lookup if it's missing.
+ *   - Accumulates tar's stderr and re-throws it on non-zero exit so
+ *     operators can see WHY tar failed (path typo, permission, corrupt
+ *     stage dir, etc.) instead of swallowing it.
+ *
+ * Throws `TAR_NOT_FOUND` when the binary cannot be located.
+ */
+export declare function runTar(args: string[]): void;

package/dist/services/skillhub/tar-runtime.js

@@ -0,0 +1,91 @@
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+/** Thrown when no usable tar binary can be located. */
+export class TAR_NOT_FOUND extends Error {
+    constructor(msg) {
+        super(`TAR_NOT_FOUND: ${msg}`);
+        this.name = "TAR_NOT_FOUND";
+    }
+}
+/**
+ * Resolve a tar binary path, in priority order:
+ *   1. process.env.PEAKS_TAR_BIN  (explicit override; honored unconditionally)
+ *   2. process.env.TAR            (POSIX convention, honored if set)
+ *   3. On Windows: C:\Windows\System32\tar.exe (bsdtar — accepts
+ *      Windows-style paths verbatim, unlike git-bash GNU tar)
+ *   4. PATH lookup: "tar" (delegates to the platform default)
+ *
+ * Throws `TAR_NOT_FOUND` when none of the candidates exist (Windows
+ * file-system check) or no override is set (POSIX). On POSIX we
+ * always trust PATH; tar is in base images 99.9% of the time. On
+ * Windows we explicitly stat each candidate so a missing
+ * C:\Windows\System32\tar.exe falls through to PATH instead of
+ * throwing an opaque spawn-ENOENT.
+ */
+function resolveTarBin() {
+    const envOverride = process.env.PEAKS_TAR_BIN;
+    if (envOverride && envOverride.length > 0)
+        return envOverride;
+    const envTar = process.env.TAR;
+    if (envTar && envTar.length > 0)
+        return envTar;
+    if (process.platform === "win32") {
+        const systemTar = "C:\\Windows\\System32\\tar.exe";
+        if (existsSync(systemTar))
+            return systemTar;
+        // Fall through to PATH lookup below — many dev setups install tar
+        // under Git for Windows or WindowsApps rather than System32.
+    }
+    // PATH lookup. We can't stat `tar` directly (it's a name, not a path),
+    // so we trust the resolution to execFileSync and surface a clean
+    // TAR_NOT_FOUND error from the caller if it fails.
+    return "tar";
+}
+/**
+ * Run `tar <args...>` in a cross-platform way.
+ *
+ * Args MUST be `["-czf", outPath, "-C", stageDir, "."]` style (no
+ * shell quoting needed because we use execFileSync, not execSync).
+ *
+ * After the Critical #3 fix:
+ *   - Honors PEAKS_TAR_BIN / TAR env vars.
+ *   - On Windows, tries C:\Windows\System32\tar.exe first; falls back
+ *     to PATH lookup if it's missing.
+ *   - Accumulates tar's stderr and re-throws it on non-zero exit so
+ *     operators can see WHY tar failed (path typo, permission, corrupt
+ *     stage dir, etc.) instead of swallowing it.
+ *
+ * Throws `TAR_NOT_FOUND` when the binary cannot be located.
+ */
+export function runTar(args) {
+    const cmd = resolveTarBin();
+    try {
+        execFileSync(cmd, args, {
+            stdio: ["ignore", "ignore", "pipe"],
+            // Surface stderr text rather than dumping a Buffer at the caller.
+            // execFileSync with stdio: ["ignore","ignore","pipe"] captures the
+            // stderr stream into the Error's `.stderr` Buffer when the child
+            // exits non-zero.
+        });
+    }
+    catch (e) {
+        // Distinguish "binary not found" from "binary ran but failed".
+        if (e && typeof e === "object" && "code" in e) {
+            const code = e.code;
+            if (code === "ENOENT") {
+                throw new TAR_NOT_FOUND(`tar binary not found (cmd="${cmd}"). Set PEAKS_TAR_BIN to override, or install tar (Windows: bsdtar is bundled with Windows 10+).`);
+            }
+        }
+        // Non-zero exit from tar itself — re-throw with stderr text.
+        const stderr = e?.stderr;
+        const stderrText = stderr instanceof Buffer
+            ? stderr.toString("utf-8")
+            : typeof stderr === "string"
+                ? stderr
+                : "";
+        const baseMsg = e instanceof Error ? e.message : typeof e === "string" ? e : String(e);
+        const wrapped = new Error(`tar exited non-zero (cmd="${cmd}"): ${baseMsg}${stderrText ? `\ntar stderr:\n${stderrText.trimEnd()}` : ""}`);
+        wrapped.cause = e;
+        throw wrapped;
+    }
+}