# @pgpmjs/bundle

The pgpm **migration bundle** — the portable, content-addressed artifact layer on top of `@pgpmjs/ast`. A `MigrationBundle` is a deterministic snapshot of a pgpm module (plan, control, ordered changes, per-change/whole-bundle sha256 digests) plus optional provenance: the "shipping container" for a database migration. - `createBundle` / `bundleFromModule` — build a bundle from a module AST. - `writeBundleFile` / `readBundleFile` — JSON serialization on the wire. - `materializeBundle` — expand a bundle back into a deployable module directory. - `verifyBundle` — recompute digests and localize any tamper/mismatch. - `transpileBundle` — produce a namespaced bundle (caller supplies the SQL AST rewrite). - `diffBundles` / `reconcilePlan` — structural diff and ordered revert/deploy plan. ## The bundle envelope The **bundle envelope** is how you ship a database the way you ship a product: the whole thing — its structure (a `MigrationBundle`), its row data, its fixtures — as one sealed, versioned, tamper-evident package. Like a shipping container: standardized, stackable, verifiable at every port. The bundle is the schema; the envelope is the whole shipment. ```ts import { bundleFromModule, createEnvelope, verifyEnvelope, materializeEnvelope } from '@pgpmjs/bundle'; const envelope = createEnvelope({ version: '1.0.0', // caller-assigned artifact version schema: bundleFromModule(moduleDir), // required: the MigrationBundle data: [{ name: 'source-plane-data', deploy, revert, verify }], // e.g. from @pgpmjs/export fixtures: [{ name: 'seed-roles', deploy }], provenance: { sourceDatabase, sliceSpec } // lineage; recorded but excluded from the digest }); verifyEnvelope(envelope); // { issues: [], schemaIssues: [] } materializeEnvelope(envelope, outDir); // deterministic, tar-friendly directory layout ``` - **Manifest** — identity (`name`, `version`), a contents inventory with per-part sha256 digests, and source lineage (`provenance`). - **Merkle content digest** — the envelope digest covers the ordered part digests; the schema part's digest is the bundle's own manifest digest, so the chain extends down through every change and script. Flip one byte anywhere and `verifyEnvelope` localizes it. - **Payload-agnostic parts** — each data/fixtures part is a named deploy/revert/verify SQL triplet produced by the caller (e.g. the `@pgpmjs/export` data-dump builders); the envelope never generates SQL, it digests, ships, and verifies it. - **Serialization** — one JSON artifact (`writeEnvelopeFile` / `readEnvelopeFile`) or a deterministic directory (`materializeEnvelope` / `envelopeFromDirectory`): ``` envelope.json # manifest only schema/pgpm-bundle.json # the schema MigrationBundle artifact data//{deploy,revert,verify}.sql fixtures//{deploy,revert,verify}.sql ``` This package is pure (no database, no deploy engine). The deployment glue — `applyBundle` and `applyEnvelope`, which drive `PgpmMigrate` — lives in `@pgpmjs/core`. See the `pgpm-migration-bundle` skill for the full model.