peaks-loop 4.0.0-beta.7 → 4.0.0-beta.8

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

@@ -1,392 +0,0 @@
-/**
- * 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";
-};