distributor/docs/internal/bundle.md

# Source Bundle Internals

Audience: developers and LLM coding agents changing `internal/bundle`.

## Purpose

`internal/bundle` discovers and validates source bundles through the storage abstraction. It adapts the public producer-facing source manifest contract from `pkg/bundle` to local, SSH/SFTP, S3-compatible, and test storage backends.

## Inputs And Outputs

Inputs are a context, a `storage.Backend`, and a source-root prefix or bundle root path. Outputs are sorted `Bundle` records containing the source-root-relative bundle path and validated manifest.

## Boundaries

`internal/bundle` delegates manifest parsing, digest calculation, source path validation, and manifest validation to `pkg/bundle`. It does not publish files, inspect destination state, choose pipelines, or know concrete backend implementations.

The external source bundle file-format contract is documented in `docs/integrations/source-bundle.md`.

## Config Fields Used

The package does not read config directly. App workflows pass it storage backends that were opened from configured source fields.

## Adapters Used

The package depends only on `internal/storage.Backend`. Concrete local, SSH/SFTP, S3-compatible, and fake backends are hidden behind that interface.

## State And Manifest Behavior

Discovery walks recursively under the source root, finds entries whose basename is `manifest.json`, converts each manifest path to a bundle root, sorts roots, rejects nested bundle roots, and validates each bundle.

Validation reads `manifest.json`, parses it, stats each manifest-listed file, requires regular files, verifies file sizes, reads file bytes, checks per-file SHA-256 digests, and recomputes the bundle digest.

## Skip And Resume Behavior

The package has no skip or resume state. Each call performs discovery or validation from the supplied backend state.

## Failure Behavior

Failures include invalid storage prefixes, missing manifests, parse errors, nested manifests, unsafe manifest paths, non-regular files, size mismatches, digest mismatches, backend stat/read errors, and no discovered bundles.

## Tests To Inspect

- `internal/bundle/*_test.go`
- `pkg/bundle/*_test.go`
- `internal/storage/fake/*_test.go`

## Architectural Invariants

- Source manifest semantics remain owned by `pkg/bundle`.
- Discovery order is deterministic.
- Nested manifests are rejected before returning bundles.
- Source paths stay clean, relative, slash-separated, and confined to the backend root.
- Concrete adapters never leak into bundle validation logic.