peaks-loop 4.0.0-beta.2 → 4.0.0-beta.4

package/dist/src/services/loop/loop-release-types.js

@@ -0,0 +1,162 @@
+import { z } from "zod";
+/**
+ * LoopRelease — spec §4.1 (Loop Engineering Asset).
+ *
+ * M1 scope was the §4.1 fields. M3 (this slice) ADDS the share /
+ * desktop extension fields from §4.1 / §7A:
+ *   - shareable              (boolean, default true)
+ *   - share_excluded_paths   (string[], default [])
+ *   - desktop_visible        (boolean, default true)
+ *   - export_bundle_format   ('peaks.bundle/1', CLI-written constant)
+ *
+ * The four M3 fields are added with `.default(...)` so an in-memory
+ * object built from a pre-M3 snapshot still parses after the
+ * migration runs. NO enforcement on `shareable=false` is added in M3
+ * — the schema-only addition is the contract; full export /
+ * desktop enforcement lands in M7 (see plan
+ * m3-bee-release-extension.md and spec §7A).
+ *
+ * Field semantics — see the spec for full prose. Highlights:
+ *
+ *   - `id` is the stable kebab-case loop id; the storage key.
+ *   - `schema_version` is the constant literal `"peaks.loop/1"`; a
+ *     schema-version bump requires a new table / new enum case and a
+ *     migration — never edit this literal in place.
+ *   - `lifecycle_status` is `candidate` / `stable` / `retired`; the
+ *     default on first crystallization is `candidate`. LLMs cannot
+ *     auto-promote to `stable` (see spec §5.6).
+ *   - `linked_bees` is a denormalized pointer list of bee ids; the
+ *     authoritative loop↔bee relations live in `loop_bee_relation`
+ *     (M2). Keeping it here matches the spec §4.1 row shape and lets
+ *     M1 readers iterate the loop without an extra join.
+ *   - `success_criteria` / `evaluator_policy` are NL strings, not
+ *     machine-checked predicates; the evaluator definitions live in
+ *     the M4 evolution layer.
+ *   - `share_excluded_paths` is a JSON-encoded TEXT column at the
+ *     SQLite layer; the Zod schema accepts a string[] and the store
+ *     does the JSON.stringify/parse boundary work. Matches the
+ *     existing `loop_release` style (success_criteria_json, …).
+ *   - `export_bundle_format` is pinned to the literal
+ *     `"peaks.bundle/1"` per the spec §7A.2 contract — no other
+ *     value is accepted in this schema version.
+ */
+export const LoopReleaseLifecycleStatusSchema = z.enum([
+    "candidate",
+    "stable",
+    "retired",
+]);
+/**
+ * The M3 share / desktop extension fields, listed for code-search /
+ * lint discoverability. They are now part of the schema (with safe
+ * defaults) — see `LoopReleaseM3ExtensionSchema` below.
+ *
+ *   - shareable: defaults to true.
+ *   - share_excluded_paths: string[] (defaults to []).
+ *   - desktop_visible: defaults to true.
+ *   - export_bundle_format: constant "peaks.bundle/1" (CLI-written).
+ */
+export const LOOP_RELEASE_M3_FIELDS = [
+    "shareable",
+    "share_excluded_paths",
+    "desktop_visible",
+    "export_bundle_format",
+];
+/**
+ * M3 share / desktop extension schema. Added to `LoopReleaseInputSchema`
+ * via `.extend(...)` so existing callers that omit these fields still
+ * parse — the Zod defaults below supply the spec values
+ * (true / [] / true / "peaks.bundle/1").
+ *
+ * `export_bundle_format` is pinned to a literal per spec §7A.2: the
+ * CLI is the only writer and only `"peaks.bundle/1"` is accepted. A
+ * schema-version bump is required to introduce another value.
+ */
+export const LoopReleaseM3ExtensionSchema = z.object({
+    shareable: z.boolean().default(true),
+    share_excluded_paths: z
+        .array(z.string().min(1).max(4096))
+        .default([]),
+    desktop_visible: z.boolean().default(true),
+    export_bundle_format: z
+        .literal("peaks.bundle/1")
+        .default("peaks.bundle/1"),
+});
+/**
+ * Zod schema for the create payload (LoopReleaseInput). Mirrors the
+ * §4.1 row shape; `schema_version` is defaulted (clients cannot
+ * override it) and `created_at` is not part of the input — the store
+ * stamps it from the server clock.
+ */
+export const LoopReleaseInputSchema = z
+    .object({
+    id: z
+        .string()
+        .min(1)
+        .max(64)
+        .regex(/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/, {
+        message: "id must be kebab-case starting with a lowercase letter (e.g. loop-onboarding-research)",
+    }),
+    name: z.string().min(1).max(200),
+    scenario: z.string().trim().min(1).max(4000),
+    trigger_policy: z.string().trim().min(1).max(2000),
+    success_criteria: z
+        .array(z.string().trim().min(1).max(1000))
+        .min(1, "success_criteria must list at least one declarative criterion"),
+    interaction_policy: z
+        .string()
+        .trim()
+        .min(1, "interaction_policy must declare human-NL-choice-only semantics")
+        .max(2000),
+    feedback_policy: z.string().trim().min(1).max(2000),
+    evolution_policy: z.string().trim().min(1).max(2000),
+    evaluator_policy: z.array(z.string().trim().min(1).max(1000)).min(1),
+    linked_bees: z.array(z.string().min(1).max(64)).default([]),
+    run_history: z.array(z.string().min(1).max(128)).default([]),
+    crystallization_evidence: z.array(z.string().min(1).max(128)).default([]),
+    lifecycle_status: LoopReleaseLifecycleStatusSchema,
+    version: z
+        .string()
+        .regex(/^\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?$/, {
+        message: "version must be a semver string (e.g. 0.1.0)",
+    }),
+})
+    .extend(LoopReleaseM3ExtensionSchema.shape);
+/**
+ * Full Zod schema for a LoopRelease row as persisted. Differs from the
+ * input schema only in that `schema_version` is exposed (and defaulted
+ * to the fixed literal). The literal constraint still rejects any
+ * client-supplied value other than `"peaks.loop/1"`; the default
+ * means omitting the key is fine and the output always carries the
+ * constant.
+ *
+ * We expose this as the canonical "row schema" used by lint and
+ * service.create/read paths.
+ */
+export const LoopReleaseSchema = LoopReleaseInputSchema.extend({
+    schema_version: z
+        .literal("peaks.loop/1")
+        .default("peaks.loop/1"),
+});
+/**
+ * Convenience: strict-parse an unknown payload into a LoopRelease row.
+ * Throws ZodError on failure. This is the public validation boundary.
+ */
+export function parseLoopRelease(input) {
+    return LoopReleaseSchema.parse(input);
+}
+/**
+ * Convenience: safe-parse that returns a Result-like shape so callers
+ * (CLI layer in M5) can render findings without try/catch noise.
+ */
+export function safeParseLoopRelease(input) {
+    const r = LoopReleaseSchema.safeParse(input);
+    if (r.success)
+        return { ok: true, row: r.data };
+    return {
+        ok: false,
+        findings: r.error.issues.map((i) => ({
+            path: i.path.join("."),
+            message: i.message,
+        })),
+    };
+}

package/dist/src/services/share/bundle-reader.d.ts

@@ -0,0 +1,100 @@
+/**
+ * bundle-reader.ts — readBundle(inPath) (spec §7A.2).
+ *
+ * M7 / spec §7A.2 / §10 RL-9 / acceptance AC-25 / AC-26.
+ *
+ * Reads a `peaks.bundle/1` tar.gz and lands the contained release
+ * on the local SkillHub. The reader is the symmetrical counterpart
+ * of `bundle-writer.ts` — same layout, same content-addressed
+ * blobs/, but with three hard guards:
+ *
+ *   1. `format_version_major !== 1` is a HARD block. The reader
+ *      throws `SHARE_BUNDLE_MAJOR_VERSION_MISMATCH` before any
+ *      SQL side-effect. (Major-version bumps are reserved for
+ *      breaking schema changes; the receiver is not assumed to
+ *      know how to translate.)
+ *   2. `format_version_minor` mismatch is a non-fatal warn (the
+ *      reader collects it as a warning on the return envelope).
+ *   3. The imported release ALWAYS lands as `candidate`. The
+ *      reader refuses to write any other status; the receiver
+ *      MUST run an independent evaluation before promoting the
+ *      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.
+ */
+import type Database from "better-sqlite3";
+import { SHARE_BUNDLE_ERROR_CODES, type PeaksBundleKind } from "./bundle-types.js";
+/**
+ * Thrown when `format_version_major !== 1`. This is the explicit
+ * HARD block per spec §7A.2 (major mismatch).
+ */
+export declare class BundleMajorVersionMismatchError extends Error {
+    readonly code: typeof SHARE_BUNDLE_ERROR_CODES.MAJOR_VERSION_MISMATCH;
+    readonly receivedMajor: number;
+    constructor(receivedMajor: number);
+}
+/**
+ * Thrown when the schema-versions mapping is missing or carries
+ * non-canonical literals.
+ */
+export declare class BundleSchemaVersionsMismatchError extends Error {
+    readonly code: typeof SHARE_BUNDLE_ERROR_CODES.SCHEMA_VERSIONS_MISMATCH;
+    readonly received: Record<string, unknown> | undefined;
+    constructor(received: Record<string, unknown> | undefined);
+}
+/**
+ * Thrown when the caller asks to land as anything other than
+ * `candidate` (the only allowed target status).
+ */
+export declare class BundleImportToStableForbiddenError extends Error {
+    readonly code: typeof SHARE_BUNDLE_ERROR_CODES.IMPORT_TO_STABLE_FORBIDDEN;
+    constructor(receivedStatus: string);
+}
+/**
+ * Thrown when the bundle tarball is malformed (no manifest.json,
+ * bad JSON, etc.). Distinct from a ZodError so the CLI can map
+ * to a single BUNDLE_MALFORMED code.
+ */
+export declare class BundleMalformedError extends Error {
+    readonly code: typeof SHARE_BUNDLE_ERROR_CODES.BUNDLE_MALFORMED;
+    constructor(message: string);
+}
+export type ReadBundleArgs = {
+    db: Database.Database;
+    /** Blobs root for content-addressed file write-back. */
+    blobsDir: string;
+    /** Input `.tar.gz` bundle path. */
+    inPath: string;
+    /**
+     * Optional rename for the anchor asset on import. For `loop`
+     * bundles this is the loop id to overwrite the source id; for
+     * `bee` bundles this is the `--as` bee name.
+     */
+    asName?: string;
+};
+/**
+ * Successful read result. The reader lands the bundle as a
+ * `candidate` regardless of any other lifecycle status on the
+ * source — this is the hard import rule per spec §7A.2 / AC-25.
+ */
+export type ReadBundleResult = {
+    /** Anchor asset id actually written. */
+    assetId: string | number;
+    kind: PeaksBundleKind;
+    /** Always `candidate` — the reader does not honor any other status. */
+    importedAs: "candidate";
+    /** Non-fatal warnings (e.g. minor-version mismatch). */
+    warnings: string[];
+    /** Count of crystallization_event rows imported. */
+    evidenceBriefCount: number;
+};
+export declare function readBundle(args: ReadBundleArgs): ReadBundleResult;