2.1 KiB
Bundles
Purpose
internal/bundle parses, discovers, and validates source bundles through the storage interface.
Inputs and outputs
Input is a backend-rooted directory tree containing one or more manifest.json files. Output is a deterministic list of validated bundles with relative bundle paths and normalized manifest data.
Manifest behavior
The source manifest requires:
schema_version: 1iddigestcreated- non-empty
files
Each file requires path, sha256, and size. Digests must use lowercase sha256:<64 hex> format. created must parse as RFC3339.
Validation
ValidateManifest owns normalized source manifest semantics: schema version, id, digest format, timestamp presence, file list presence, source path safety, duplicate file paths, reserved paths, file digest format, non-negative file sizes, and the top-level bundle digest.
Storage-backed bundle validation additionally checks file existence, regular-file type, file size, and per-file SHA-256.
The bundle digest is SHA-256 of a deterministic JSON array of file records in manifest order with fields path, sha256, and size.
Discovery
Discovery walks a storage backend beneath a source root, finds manifest.json files, sorts bundle paths lexically, and rejects nested manifests.
Failure behavior
Manifest parsing and validation fail before destination planning. Storage-backed validation fails when listed files are missing, are not regular files, have unexpected sizes, have unexpected SHA-256 digests, or when a source bundle includes unsafe or reserved paths.
Boundaries
Bundle code uses internal/storage and does not import concrete adapters. CLI local path support is wired in internal/app.
Tests
Before changing bundle behavior, inspect tests under internal/bundle.
Invariants
manifest.jsonis the only source bundle contract.- Source file paths must stay relative to the bundle root.
- The top-level bundle digest is derived from manifest file records in order.
- Discovery order is lexical and deterministic.
- Nested manifests are rejected.