eric/distributor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 7 Wiki Activity

Document internal component contracts

Browse Source
This commit is contained in:
Eric Rakestraw
2026-05-31 04:06:48 +00:00
parent eac73a79a1
commit 93c22884b0
8 changed files with 225 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files

14
docs/internal/bundle.md
View File

@@ -32,10 +32,22 @@ The bundle digest is SHA-256 of a deterministic JSON array of file records in ma
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 local, SSH, or S3 adapters. CLI local path support is wired in `internal/app`.
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.json` is 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.