/** * 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": , * "bee_release": , * "related_bee_releases": Array, * "loop_bee_relations": Array, * "evidence_briefs": Array, * "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 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.ZodObject<{ format_constant: z.ZodLiteral<"peaks.bundle/1">; format_version_major: z.ZodLiteral<1>; format_version_minor: z.ZodDefault; 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">; }, z.core.$strict>; kind: z.ZodEnum<{ loop: "loop"; bee: "bee"; }>; loop_release: z.ZodOptional; bee_release: z.ZodOptional; related_bee_releases: z.ZodDefault>; loop_bee_relations: z.ZodDefault>; evidence_briefs: z.ZodDefault>; exclusion_manifest: z.ZodObject<{ private_run_state: z.ZodLiteral<"excluded">; personal_memory: z.ZodLiteral<"excluded">; state_db_rows: z.ZodLiteral<"excluded">; }, z.core.$strict>; }, z.core.$strict>; export type BundleManifest = z.infer; /** * 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"; }; export * from './bundle-format-constants.js';