Module project_bundle 

The BRPROJ project export/import bundle format (tar + JSON MANIFEST + per-member SHA-256). Dependency-light + testable in every build; the driver that fills it is feature-gated. The BRPROJ project export/import bundle — the on-disk format a project export writes and a project import reads.

A bundle is a plain tar whose FIRST entry is a JSON MANIFEST describing every other member, followed by the per-engine payloads:

MANIFEST                               magic "BRPROJ" | format_version | created_at | data_only | members[]
kv.brkvdump                            the control-plane KV logical slice (kv_dump::export_to_bytes bytes)
sql/<db>.pgc                           a streamed Postgres dump (pg_dump custom/plain)
libsql/<project>/<site>/<db>.sqlite    a VACUUM INTO snapshot of a libsql database
blobs/<...>                            blob-store objects

Discipline borrowed from boatramp_core::kv_dump: a loud magic (BRPROJ) and an explicit format version the reader refuses if unknown (never misreads a foreign/newer file), plus a per-member SHA-256 checksum the reader VERIFIES on extraction (byte-integrity, not a size check) — so a truncated/corrupt bundle is caught before a single row is restored.

The writer takes members already staged on disk (the multi-GB pg_dump stream lands in a staging file via run_ephemeral’s streaming sink, the libsql VACUUM INTO writes a file, the KV slice + blobs are staged too), so each member is appended with a known size — correctness over the PAX unknown-length streaming form, and the staging keeps memory bounded regardless of dump size. All IO is synchronous (the tar crate is sync); the async driver calls it from a blocking task.

Structs

Manifest

The bundle MANIFEST — the first tar entry, describing the whole bundle.

ManifestMember

One member described in the MANIFEST.

PgMemberInfo

SQL-dump provenance for a PgDump/MysqlDump member: the detected server version, the client image used to produce (and required to restore) it, and the schema-ledger fingerprint for the import schema-skew check. (Field named pg historically; it carries MySQL provenance too — the engine is the member’s MemberKind.)

SourceInfo

What the bundle was exported from.

StagedMember

A member staged on disk, ready to be appended to a bundle.

Enums

BundleError

A project-bundle error.

MemberKind

Which engine a bundle member came from.

Constants

BUNDLE_FORMAT_VERSION

The bundle FORMAT version. Bumped only on an incompatible change; a reader refuses an unknown version rather than misreading it.

BUNDLE_MAGIC

The bundle magic — carried in the MANIFEST so a stray/foreign tar is rejected loud.

IDENTITY_MEMBER_PATH

The identity transport-container’s tar-entry path (--include-identity only): the passphrase-wrapped KEK, produced by boatramp_server::envelope::transport_wrap.

KV_MEMBER_PATH

The control-plane KV slice’s tar-entry path (the kv_dump::export_to_bytes bytes).

MANIFEST_PATH

The manifest’s tar-entry path — MUST be the first entry in the bundle.

Functions

extract_and_verify

Extract every member of bundle into out_dir, VERIFYING each member’s SHA-256 against the MANIFEST as it streams (byte-integrity). Refuses a member the manifest does not describe, and a manifest member the bundle does not contain. Returns the validated MANIFEST. Member files land at out_dir/<member.path>.

read_manifest

Read + validate the MANIFEST (the first tar entry) from bundle, without extracting any member.

write_bundle

Write a bundle at out from members already staged on disk: compute each member’s size + SHA-256, build + validate the MANIFEST, then write the tar with the MANIFEST first and every member streamed from its staging file (bounded memory). Returns the MANIFEST that was written.