peaks-loop 4.0.0-beta → 4.0.0-beta.3

package/dist/src/services/share/bundle-types.js

@@ -0,0 +1,318 @@
+/**
+ * peaks.bundle/1 — share-bundle format contract (spec §7A.2).
+ *
+ * M7 / spec §7A.2 / §10 RL-9.
+ *
+ * A bundle is a self-describing tar.gz whose root manifest
+ * (manifest.json) declares the format constant, the major/minor
+ * format version, the schema_version of every contained asset, the
+ * assets themselves (loop_release + related bee_release rows), the
+ * relation rows, and the evidence briefs that back the assets. The
+ * bundle excludes private run_state, `.peaks/memory/personal/`, and
+ * raw `state.db` rows.
+ *
+ * Hard rules enforced at THIS layer:
+ *
+ *   - The literal constant `format_constant = "peaks.bundle/1"` is
+ *     set inside the manifest at write time. The CLI is the only
+ *     writer; a future format change is signaled by bumping the
+ *     major field and shipping a new writer.
+ *   - `format_version_major = 1` is required for any current
+ *     receiver. A major-version mismatch is a HARD block at read
+ *     time (the reader throws and refuses to import).
+ *   - `format_version_minor` is informational; a major-compatible
+ *     minor bump emits a non-fatal warning at read time.
+ *   - `schema_versions` carries the canonical asset schema literal
+ *     for each emitted asset: `peaks.loop/1`, `peaks.bee/1`, plus
+ *     the cross-cutting `peaks.loop-bee-relation/1` and
+ *     `peaks.crystallization/1`. The reader uses the values to
+ *     inform a version-mismatch warning.
+ *
+ * The schema is intentionally permissive on the manifests (the
+ * manifest sub-objects are typed as `unknown` so each asset kind
+ * can validate with its own Zod schema at the service layer); the
+ * hard invariants (format constant, format_version_major, the
+ * schema_versions keys, and the inclusion/exclusion rules) are
+ * enforced here at the format boundary.
+ *
+ * On-the-wire shape (the rendered `manifest.json`):
+ *
+ *   {
+ *     "format_constant":          "peaks.bundle/1",
+ *     "format_version_major":     1,
+ *     "format_version_minor":     0,
+ *     "schema_versions": {
+ *        "loop":              "peaks.loop/1",
+ *        "bee":               "peaks.bee/1",
+ *        "loop_bee_relation": "peaks.loop-bee-relation/1",
+ *        "crystallization":   "peaks.crystallization/1"
+ *     },
+ *     "kind":               "loop" | "bee",
+ *     "loop_release":       <LoopRelease row or omitted for bee kind>,
+ *     "bee_release":        <BeeRelease row or omitted for loop kind>,
+ *     "related_bee_releases": Array<BeeRelease row>,
+ *     "loop_bee_relations":   Array<LoopBeeRelation row>,
+ *     "evidence_briefs":    Array<CrystallizationEvent row>,
+ *     "exclusion_manifest": { "private_run_state": "excluded",
+ *                            "personal_memory":    "excluded",
+ *                            "state_db_rows":      "excluded" }
+ *   }
+ *
+ * Excludes (spec §7A.2 hard rules): private run_state, anything
+ * under `.peaks/memory/personal/`, raw `state.db` rows.
+ */
+import { z } from "zod";
+/* ---------------------------------------------------------------------- */
+/* Format constant + version                                                */
+/* ---------------------------------------------------------------------- */
+/**
+ * The on-the-wire format constant, pinned to the literal
+ * `"peaks.bundle/1"`. The CLI is the only writer — see `bundle-writer.ts`.
+ * A future format change requires a major-version bump + a new writer.
+ */
+export const PEAKS_BUNDLE_FORMAT_CONSTANT = "peaks.bundle/1";
+/**
+ * The required `format_version_major` for any current receiver.
+ * Bumped only on a breaking schema change. The reader throws when
+ * the manifest declares any value other than `1`.
+ */
+export const PEAKS_BUNDLE_FORMAT_VERSION_MAJOR = 1;
+/**
+ * Default `format_version_minor`. Major-compatible minor bumps emit
+ * a soft warning at read time; they never block.
+ */
+export const PEAKS_BUNDLE_DEFAULT_MINOR_VERSION = 0;
+/* ---------------------------------------------------------------------- */
+/* Schema-version cross-reference (per asset table)                         */
+/* ---------------------------------------------------------------------- */
+/**
+ * The cross-cutting schema literals a bundle is allowed to declare.
+ * Each value must match the canonical Zod `literal(...)` literal in
+ * the corresponding type module. Used for the
+ * `SchemaVersionsMapping` enumeration below.
+ */
+export const PEAKS_BUNDLE_SCHEMA_VERSIONS = {
+    loop: "peaks.loop/1",
+    bee: "peaks.bee/1",
+    loop_bee_relation: "peaks.loop-bee-relation/1",
+    crystallization: "peaks.crystallization/1",
+};
+/* ---------------------------------------------------------------------- */
+/* Schema-versions mapping — spec §7A.2                                     */
+/* ---------------------------------------------------------------------- */
+/**
+ * Schema-versions mapping. The writer writes the canonical literal
+ * for each asset kind it includes; the reader checks every key for
+ * presence (and that the value matches the canonical literal).
+ *
+ * `.strict()` refuses unknown keys; `.refine(...)` enforces that
+ * each value matches its canonical literal.
+ */
+export const SchemaVersionsMappingSchema = z
+    .object({
+    loop: z.literal(PEAKS_BUNDLE_SCHEMA_VERSIONS.loop),
+    bee: z.literal(PEAKS_BUNDLE_SCHEMA_VERSIONS.bee),
+    loop_bee_relation: z.literal(PEAKS_BUNDLE_SCHEMA_VERSIONS.loop_bee_relation),
+    crystallization: z.literal(PEAKS_BUNDLE_SCHEMA_VERSIONS.crystallization),
+})
+    .strict();
+/* ---------------------------------------------------------------------- */
+/* Exclusion manifest — the explicit excludes per spec §7A.2               */
+/* ---------------------------------------------------------------------- */
+/**
+ * The bundle explicitly excludes private run-state, the user's
+ * personal memory directory, and raw `state.db` rows. The
+ * `ExclusionManifestSchema` is what the writer stamps into the
+ * manifest; the reader uses it as a self-declaration (the writer is
+ * the only place that can leak those payloads, but the read-time
+ * stamp lets the receiver confirm the source understood the
+ * exclusion rules).
+ */
+export const ExclusionManifestSchema = z
+    .object({
+    private_run_state: z.literal("excluded"),
+    personal_memory: z.literal("excluded"),
+    state_db_rows: z.literal("excluded"),
+})
+    .strict();
+/* ---------------------------------------------------------------------- */
+/* Bundle kind — which asset the bundle is anchored on                     */
+/* ---------------------------------------------------------------------- */
+/**
+ * Bundle kind. A bundle is anchored on exactly one asset: either a
+ * `loop_release` (and its main bee + supporting bees) or a single
+ * `bee_release` (loop-scoped relations may follow but are not
+ * required).
+ */
+export const PEAKS_BUNDLE_KINDS = ["loop", "bee"];
+/* ---------------------------------------------------------------------- */
+/* Bundle manifest schema — the on-the-wire shape                          */
+/* ---------------------------------------------------------------------- */
+/**
+ * The full manifest schema. The asset sub-objects are typed as
+ * `unknown` here; each service layer validates them with the
+ * appropriate per-kind Zod schema (LoopReleaseSchema,
+ * BeeReleaseRow, LoopBeeRelationSchema, CrystallizationEventSchema).
+ *
+ * The hard invariants are enforced HERE:
+ *   - `format_constant = "peaks.bundle/1"` literal.
+ *   - `format_version_major = 1` literal (HARD block at read time
+ *     on mismatch — enforced in `bundle-reader.ts`).
+ *   - `schema_versions` carries every required key with the
+ *     canonical literal.
+ *   - `exclusion_manifest` declares the three hard excludes.
+ */
+export const BundleManifestSchema = z
+    .object({
+    /**
+     * The format constant. Pinned to `"peaks.bundle/1"`. A future
+     * format change is a major bump + a new constant value.
+     */
+    format_constant: z.literal(PEAKS_BUNDLE_FORMAT_CONSTANT),
+    /**
+     * Major version. The reader requires `1`; anything else is a
+     * HARD block. Enforced at the read boundary, not here.
+     */
+    format_version_major: z.literal(PEAKS_BUNDLE_FORMAT_VERSION_MAJOR),
+    /**
+     * Minor version. Defaults to `0`. Major-compatible bumps are a
+     * non-fatal warn at read time.
+     */
+    format_version_minor: z.number().int().min(0).default(PEAKS_BUNDLE_DEFAULT_MINOR_VERSION),
+    /**
+     * Schema-version mapping. Every required key MUST be present
+     * with its canonical literal; unknown keys are rejected by
+     * `.strict()`.
+     */
+    schema_versions: SchemaVersionsMappingSchema,
+    /**
+     * Anchor kind. Decides whether `loop_release` or `bee_release`
+     * is required below.
+     */
+    kind: z.enum(PEAKS_BUNDLE_KINDS),
+    /**
+     * The loop_release row. Required when `kind === "loop"`,
+     * omitted (or absent) when `kind === "bee"`. The writer leaves
+     * it `undefined` for `bee` bundles; the JSON shape is allowed
+     * to omit it.
+     */
+    loop_release: z.unknown().optional(),
+    /**
+     * The bee_release row. Required when `kind === "bee"`,
+     * optional for `kind === "loop"` (a loop bundle may include a
+     * main bee inline). When present, the reader uses the service
+     * layer to re-validate the row shape.
+     */
+    bee_release: z.unknown().optional(),
+    /**
+     * Related bee_release rows for the loop kind (main + supporting
+     * + candidate + retired). Empty for `kind === "bee"`.
+     */
+    related_bee_releases: z.array(z.unknown()).default([]),
+    /**
+     * Loop↔bee relation rows from `loop_bee_relation`. Always
+     * present (possibly empty).
+     */
+    loop_bee_relations: z.array(z.unknown()).default([]),
+    /**
+     * Evidence briefs (crystallization_event rows) that back the
+     * bundle's assets. The receiver uses them to render the
+     * post-import crystallization prompt + a brief for any
+     * subsequent independent evaluation.
+     */
+    evidence_briefs: z.array(z.unknown()).default([]),
+    /**
+     * Exclusion manifest — explicit declarations of the three
+     * hard excludes per spec §7A.2.
+     */
+    exclusion_manifest: ExclusionManifestSchema,
+})
+    .strict()
+    .refine((m) => {
+    // kind === 'loop' implies loop_release is required.
+    if (m.kind === "loop" && m.loop_release === undefined)
+        return false;
+    // kind === 'bee' implies bee_release is required.
+    if (m.kind === "bee" && m.bee_release === undefined)
+        return false;
+    return true;
+}, {
+    message: "bundle manifest is inconsistent: kind='loop' requires loop_release; kind='bee' requires bee_release (spec §7A.2)",
+    path: [],
+});
+/* ---------------------------------------------------------------------- */
+/* Validation helpers                                                      */
+/* ---------------------------------------------------------------------- */
+/**
+ * Strict-parse an unknown value as a BundleManifest. Throws
+ * `z.ZodError` on any failure — including:
+ *   - format_constant !== "peaks.bundle/1"
+ *   - format_version_major !== 1
+ *   - schema_versions missing or carrying non-canonical literals
+ *   - exclusion_manifest missing any of the three hard excludes
+ *   - kind / anchor-mismatch (loop kind without loop_release, etc.)
+ *
+ * Note: a major-version mismatch on its own is NOT a Zod failure
+ * (the literal is enforced at the schema boundary so it is), but
+ * the `bundle-reader.ts` HARD block on major mismatch is layered on
+ * top of this parse for defense in depth (it lets the CLI emit its
+ * own specific error code without catching Zod errors).
+ */
+export function parseBundleManifest(input) {
+    return BundleManifestSchema.parse(input);
+}
+/**
+ * Safe-parse twin of `parseBundleManifest` — returns a Result-like
+ * envelope. Used by the CLI layer so a manifest-validation failure
+ * can be rendered as a structured error code rather than a thrown
+ * `ZodError`.
+ */
+export function safeParseBundleManifest(input) {
+    const r = BundleManifestSchema.safeParse(input);
+    if (r.success)
+        return { ok: true, manifest: r.data };
+    const findings = r.error.issues.map((i) => ({
+        path: i.path.join("."),
+        message: i.message,
+    }));
+    const joined = findings.map((f) => f.path + ":" + f.message).join("|");
+    const code = detectManifestFailureCode(joined);
+    return { ok: false, code, findings };
+}
+function detectManifestFailureCode(joinedIssues) {
+    if (joinedIssues.includes("format_constant")) {
+        return "BUNDLE_FORMAT_CONSTANT_MISMATCH";
+    }
+    if (joinedIssues.includes("format_version_major")) {
+        return "BUNDLE_MAJOR_VERSION_MISMATCH";
+    }
+    if (joinedIssues.includes("schema_versions")) {
+        return "BUNDLE_SCHEMA_VERSIONS_MISMATCH";
+    }
+    if (joinedIssues.includes("exclusion_manifest")) {
+        return "BUNDLE_EXCLUSION_MANIFEST_MISSING";
+    }
+    return "BUNDLE_KIND_ANCHOR_MISMATCH";
+}
+/* ---------------------------------------------------------------------- */
+/* Hard-block error code consts                                              */
+/* ---------------------------------------------------------------------- */
+/**
+ * Error code string consts. Centralised here so the writer + reader
+ * share a single source of truth for error codes; the CLI layer
+ * only needs to render them.
+ */
+export const SHARE_BUNDLE_ERROR_CODES = {
+    /** Major-version mismatch at read time — HARD block. */
+    MAJOR_VERSION_MISMATCH: "SHARE_BUNDLE_MAJOR_VERSION_MISMATCH",
+    /** Schema-version mapping is missing or carries non-canonical literals. */
+    SCHEMA_VERSIONS_MISMATCH: "SHARE_BUNDLE_SCHEMA_VERSIONS_MISMATCH",
+    /** Format constant is not the pinned "peaks.bundle/1". */
+    FORMAT_CONSTANT_MISMATCH: "SHARE_BUNDLE_FORMAT_CONSTANT_MISMATCH",
+    /** Source release has `shareable === false` — HARD block at write time. */
+    NOT_SHAREABLE: "SHARE_BUNDLE_NOT_SHAREABLE",
+    /** Receiver asked to land as `stable` (forbidden — bundles always land as candidate). */
+    IMPORT_TO_STABLE_FORBIDDEN: "SHARE_BUNDLE_IMPORT_TO_STABLE_FORBIDDEN",
+    /** Bundle tarball is malformed (missing manifest, bad payload). */
+    BUNDLE_MALFORMED: "SHARE_BUNDLE_MALFORMED",
+};

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

@@ -0,0 +1,97 @@
+/**
+ * bundle-writer.ts — writeBundle(loopOrBeeId, outPath) (spec §7A.2).
+ *
+ * M7 / spec §7A.2 / §10 RL-9.
+ *
+ * Writes a `peaks.bundle/1` tar.gz that captures:
+ *
+ *   - One anchor asset: a loop_release (kind='loop') OR a single
+ *     bee_release (kind='bee'). A loop bundle additionally carries
+ *     related_bee_releases (all loop↔bee relations resolved) and
+ *     loop_bee_relations rows.
+ *   - All evidence_briefs (crystallization_event rows) that
+ *     reference the anchor (created_loop_release_id /
+ *     updated_loop_release_id / created_bee_release_id /
+ *     updated_bee_release_id).
+ *
+ * Hard rules enforced at THIS layer:
+ *
+ *   - The source release MUST have `shareable !== false`. A
+ *     `shareable=false` source THROWS
+ *     `SHARE_BUNDLE_NOT_SHAREABLE` BEFORE the tarball is written.
+ *     The CLI layer is the canonical gate (per spec §7A.2 /
+ *     §10 RL-9); the writer enforces the same gate at the
+ *     service boundary for defense in depth.
+ *   - The bundle NEVER captures private run_state, the personal
+ *     `.peaks/memory/personal/` directory, or raw `state.db`
+ *     rows. The exclusion is declared in the manifest's
+ *     `exclusion_manifest` field; physically, the writer only
+ *     pulls rows from the structured tables.
+ *   - The bundle is a tarball whose root contains `manifest.json`,
+ *     `relations.json`, `evidence_briefs/*.json`, and
+ *     `blobs/<sha256>` content-addressed blobs (mirroring the
+ *     SkillHub release pattern).
+ *
+ * The writer runs `tar -czf <outPath> -C <stageDir> .` exactly the
+ * same way `release-export.ts` does — same layout, same tar
+ * invocation, so the `bundle-reader.ts` symmetrical side can
+ * extract via `runTar(['-xzf', inPath, '-C', stageDir])` with no
+ * extra plumbing.
+ */
+import type Database from "better-sqlite3";
+import { SHARE_BUNDLE_ERROR_CODES, type PeaksBundleKind } from "./bundle-types.js";
+/**
+ * Inputs to `writeBundle`. `kind` decides which asset table the
+ * `id` resolves against; the writer throws on unknown assets and
+ * on `shareable=false` sources.
+ */
+export type WriteBundleArgs = {
+    db: Database.Database;
+    /** Blobs root for content-addressed file lookup. */
+    blobsDir: string;
+    /** Bundle kind — `loop` or `bee`. */
+    kind: PeaksBundleKind;
+    /** The asset id — loop id (kebab-case) for `kind:'loop'`, integer bee_release.id for `kind:'bee'`. */
+    id: string | number;
+    /** Output `.tar.gz` path. */
+    outPath: string;
+};
+/**
+ * Thrown when the source release has `shareable === false`. The
+ * writer throws BEFORE any tarball work; the CLI layer surfaces
+ * `code = SHARE_BUNDLE_NOT_SHAREABLE`.
+ */
+export declare class BundleNotShareableError extends Error {
+    readonly code: typeof SHARE_BUNDLE_ERROR_CODES.NOT_SHAREABLE;
+    constructor(message: string);
+}
+/**
+ * Thrown when the writer cannot locate the source asset (loop id
+ * not present in `loop_release`, or bee_release.id not present).
+ * Includes both `LOOP_NOT_FOUND` and `BEE_NOT_FOUND` flavors —
+ * both fall under `BUNDLE_ASSET_NOT_FOUND` for the CLI envelope.
+ */
+export declare class BundleAssetNotFoundError extends Error {
+    readonly code: "BUNDLE_ASSET_NOT_FOUND";
+    readonly assetKind: PeaksBundleKind;
+    readonly assetId: string | number;
+    constructor(assetKind: PeaksBundleKind, assetId: string | number);
+}
+/**
+ * Write a `peaks.bundle/1` tar.gz to `outPath`. The bundle
+ * captures ONE anchor asset (`loop` or `bee`) plus its relations,
+ * supporting bees (loop kind only), and evidence briefs.
+ *
+ * Hard blocks raised at THIS layer:
+ *
+ *   - `BundleNotShareableError`: the source has `shareable === false`.
+ *   - `BundleAssetNotFoundError`: the source id was not present in the table.
+ *
+ * On success the call returns the resolved asset id and kind; the
+ * CLI layer uses this to render a one-line status.
+ */
+export declare function writeBundle(args: WriteBundleArgs): {
+    outPath: string;
+    kind: PeaksBundleKind;
+    assetId: string | number;
+};