Add source bundle validation and inspection

docs/internal/bundle.md

@@ -0,0 +1,39 @@
+# 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: 1`
+- `id`
+- `digest`
+- `created`
+- non-empty `files`
+
+Each file requires `path`, `sha256`, and `size`. Digests must use lowercase `sha256:<64 hex>` format. `created` must parse as RFC3339.
+
+## Validation
+
+Bundle validation checks source path safety, duplicate file paths, reserved paths, file existence, regular-file type, file size, per-file SHA-256, and the top-level bundle digest.
+
+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.
+
+## Boundaries
+
+Bundle code uses `internal/storage` and does not import local, SSH, or S3 adapters. CLI local path support is wired in `internal/app`.
+
+## Tests
+
+Before changing bundle behavior, inspect tests under `internal/bundle`.