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

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

@@ -0,0 +1,392 @@
+/**
+ * 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";
+/**
+ * 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 declare 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 declare 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 declare const PEAKS_BUNDLE_DEFAULT_MINOR_VERSION: 0;
+/**
+ * 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 declare const PEAKS_BUNDLE_SCHEMA_VERSIONS: {
+    readonly loop: "peaks.loop/1";
+    readonly bee: "peaks.bee/1";
+    readonly loop_bee_relation: "peaks.loop-bee-relation/1";
+    readonly crystallization: "peaks.crystallization/1";
+};
+export type PeaksBundleSchemaVersionKey = keyof typeof PEAKS_BUNDLE_SCHEMA_VERSIONS;
+/**
+ * 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 declare const SchemaVersionsMappingSchema: z.ZodObject<{
+    loop: z.ZodLiteral<"peaks.loop/1">;
+    bee: z.ZodLiteral<"peaks.bee/1">;
+    loop_bee_relation: z.ZodLiteral<"peaks.loop-bee-relation/1">;
+    crystallization: z.ZodLiteral<"peaks.crystallization/1">;
+}, "strict", z.ZodTypeAny, {
+    bee: "peaks.bee/1";
+    loop: "peaks.loop/1";
+    loop_bee_relation: "peaks.loop-bee-relation/1";
+    crystallization: "peaks.crystallization/1";
+}, {
+    bee: "peaks.bee/1";
+    loop: "peaks.loop/1";
+    loop_bee_relation: "peaks.loop-bee-relation/1";
+    crystallization: "peaks.crystallization/1";
+}>;
+export type SchemaVersionsMapping = z.infer<typeof SchemaVersionsMappingSchema>;
+/**
+ * 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 declare const ExclusionManifestSchema: z.ZodObject<{
+    private_run_state: z.ZodLiteral<"excluded">;
+    personal_memory: z.ZodLiteral<"excluded">;
+    state_db_rows: z.ZodLiteral<"excluded">;
+}, "strict", z.ZodTypeAny, {
+    private_run_state: "excluded";
+    personal_memory: "excluded";
+    state_db_rows: "excluded";
+}, {
+    private_run_state: "excluded";
+    personal_memory: "excluded";
+    state_db_rows: "excluded";
+}>;
+export type ExclusionManifest = z.infer<typeof ExclusionManifestSchema>;
+/**
+ * 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 declare const PEAKS_BUNDLE_KINDS: readonly ["loop", "bee"];
+export type PeaksBundleKind = (typeof PEAKS_BUNDLE_KINDS)[number];
+/**
+ * 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 declare const BundleManifestSchema: z.ZodEffects<z.ZodObject<{
+    /**
+     * The format constant. Pinned to `"peaks.bundle/1"`. A future
+     * format change is a major bump + a new constant value.
+     */
+    format_constant: z.ZodLiteral<"peaks.bundle/1">;
+    /**
+     * Major version. The reader requires `1`; anything else is a
+     * HARD block. Enforced at the read boundary, not here.
+     */
+    format_version_major: z.ZodLiteral<1>;
+    /**
+     * Minor version. Defaults to `0`. Major-compatible bumps are a
+     * non-fatal warn at read time.
+     */
+    format_version_minor: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Schema-version mapping. Every required key MUST be present
+     * with its canonical literal; unknown keys are rejected by
+     * `.strict()`.
+     */
+    schema_versions: z.ZodObject<{
+        loop: z.ZodLiteral<"peaks.loop/1">;
+        bee: z.ZodLiteral<"peaks.bee/1">;
+        loop_bee_relation: z.ZodLiteral<"peaks.loop-bee-relation/1">;
+        crystallization: z.ZodLiteral<"peaks.crystallization/1">;
+    }, "strict", z.ZodTypeAny, {
+        bee: "peaks.bee/1";
+        loop: "peaks.loop/1";
+        loop_bee_relation: "peaks.loop-bee-relation/1";
+        crystallization: "peaks.crystallization/1";
+    }, {
+        bee: "peaks.bee/1";
+        loop: "peaks.loop/1";
+        loop_bee_relation: "peaks.loop-bee-relation/1";
+        crystallization: "peaks.crystallization/1";
+    }>;
+    /**
+     * Anchor kind. Decides whether `loop_release` or `bee_release`
+     * is required below.
+     */
+    kind: z.ZodEnum<["loop", "bee"]>;
+    /**
+     * 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.ZodOptional<z.ZodUnknown>;
+    /**
+     * 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.ZodOptional<z.ZodUnknown>;
+    /**
+     * Related bee_release rows for the loop kind (main + supporting
+     * + candidate + retired). Empty for `kind === "bee"`.
+     */
+    related_bee_releases: z.ZodDefault<z.ZodArray<z.ZodUnknown, "many">>;
+    /**
+     * Loop↔bee relation rows from `loop_bee_relation`. Always
+     * present (possibly empty).
+     */
+    loop_bee_relations: z.ZodDefault<z.ZodArray<z.ZodUnknown, "many">>;
+    /**
+     * 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.ZodDefault<z.ZodArray<z.ZodUnknown, "many">>;
+    /**
+     * Exclusion manifest — explicit declarations of the three
+     * hard excludes per spec §7A.2.
+     */
+    exclusion_manifest: z.ZodObject<{
+        private_run_state: z.ZodLiteral<"excluded">;
+        personal_memory: z.ZodLiteral<"excluded">;
+        state_db_rows: z.ZodLiteral<"excluded">;
+    }, "strict", z.ZodTypeAny, {
+        private_run_state: "excluded";
+        personal_memory: "excluded";
+        state_db_rows: "excluded";
+    }, {
+        private_run_state: "excluded";
+        personal_memory: "excluded";
+        state_db_rows: "excluded";
+    }>;
+}, "strict", z.ZodTypeAny, {
+    kind: "bee" | "loop";
+    format_constant: "peaks.bundle/1";
+    format_version_major: 1;
+    format_version_minor: number;
+    schema_versions: {
+        bee: "peaks.bee/1";
+        loop: "peaks.loop/1";
+        loop_bee_relation: "peaks.loop-bee-relation/1";
+        crystallization: "peaks.crystallization/1";
+    };
+    related_bee_releases: unknown[];
+    loop_bee_relations: unknown[];
+    evidence_briefs: unknown[];
+    exclusion_manifest: {
+        private_run_state: "excluded";
+        personal_memory: "excluded";
+        state_db_rows: "excluded";
+    };
+    loop_release?: unknown;
+    bee_release?: unknown;
+}, {
+    kind: "bee" | "loop";
+    format_constant: "peaks.bundle/1";
+    format_version_major: 1;
+    schema_versions: {
+        bee: "peaks.bee/1";
+        loop: "peaks.loop/1";
+        loop_bee_relation: "peaks.loop-bee-relation/1";
+        crystallization: "peaks.crystallization/1";
+    };
+    exclusion_manifest: {
+        private_run_state: "excluded";
+        personal_memory: "excluded";
+        state_db_rows: "excluded";
+    };
+    format_version_minor?: number | undefined;
+    loop_release?: unknown;
+    bee_release?: unknown;
+    related_bee_releases?: unknown[] | undefined;
+    loop_bee_relations?: unknown[] | undefined;
+    evidence_briefs?: unknown[] | undefined;
+}>, {
+    kind: "bee" | "loop";
+    format_constant: "peaks.bundle/1";
+    format_version_major: 1;
+    format_version_minor: number;
+    schema_versions: {
+        bee: "peaks.bee/1";
+        loop: "peaks.loop/1";
+        loop_bee_relation: "peaks.loop-bee-relation/1";
+        crystallization: "peaks.crystallization/1";
+    };
+    related_bee_releases: unknown[];
+    loop_bee_relations: unknown[];
+    evidence_briefs: unknown[];
+    exclusion_manifest: {
+        private_run_state: "excluded";
+        personal_memory: "excluded";
+        state_db_rows: "excluded";
+    };
+    loop_release?: unknown;
+    bee_release?: unknown;
+}, {
+    kind: "bee" | "loop";
+    format_constant: "peaks.bundle/1";
+    format_version_major: 1;
+    schema_versions: {
+        bee: "peaks.bee/1";
+        loop: "peaks.loop/1";
+        loop_bee_relation: "peaks.loop-bee-relation/1";
+        crystallization: "peaks.crystallization/1";
+    };
+    exclusion_manifest: {
+        private_run_state: "excluded";
+        personal_memory: "excluded";
+        state_db_rows: "excluded";
+    };
+    format_version_minor?: number | undefined;
+    loop_release?: unknown;
+    bee_release?: unknown;
+    related_bee_releases?: unknown[] | undefined;
+    loop_bee_relations?: unknown[] | undefined;
+    evidence_briefs?: unknown[] | undefined;
+}>;
+export type BundleManifest = z.infer<typeof BundleManifestSchema>;
+/**
+ * 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 declare function parseBundleManifest(input: unknown): BundleManifest;
+/**
+ * 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 declare function safeParseBundleManifest(input: unknown): {
+    ok: true;
+    manifest: BundleManifest;
+} | {
+    ok: false;
+    code: "BUNDLE_FORMAT_CONSTANT_MISMATCH" | "BUNDLE_MAJOR_VERSION_MISMATCH" | "BUNDLE_SCHEMA_VERSIONS_MISMATCH" | "BUNDLE_EXCLUSION_MANIFEST_MISSING" | "BUNDLE_KIND_ANCHOR_MISMATCH";
+    findings: Array<{
+        path: string;
+        message: string;
+    }>;
+};
+/**
+ * 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 declare const SHARE_BUNDLE_ERROR_CODES: {
+    /** Major-version mismatch at read time — HARD block. */
+    readonly MAJOR_VERSION_MISMATCH: "SHARE_BUNDLE_MAJOR_VERSION_MISMATCH";
+    /** Schema-version mapping is missing or carries non-canonical literals. */
+    readonly SCHEMA_VERSIONS_MISMATCH: "SHARE_BUNDLE_SCHEMA_VERSIONS_MISMATCH";
+    /** Format constant is not the pinned "peaks.bundle/1". */
+    readonly FORMAT_CONSTANT_MISMATCH: "SHARE_BUNDLE_FORMAT_CONSTANT_MISMATCH";
+    /** Source release has `shareable === false` — HARD block at write time. */
+    readonly NOT_SHAREABLE: "SHARE_BUNDLE_NOT_SHAREABLE";
+    /** Receiver asked to land as `stable` (forbidden — bundles always land as candidate). */
+    readonly IMPORT_TO_STABLE_FORBIDDEN: "SHARE_BUNDLE_IMPORT_TO_STABLE_FORBIDDEN";
+    /** Bundle tarball is malformed (missing manifest, bad payload). */
+    readonly BUNDLE_MALFORMED: "SHARE_BUNDLE_MALFORMED";
+};