// Package bundle provides producer-facing helpers for distributor source
// bundles.
//
// A source bundle is a local directory containing manifest.json and the files
// listed by that manifest. Producer applications use this package when they
// need to generate manifests, validate bundles locally, or write complete
// bundle directories for distributor to discover, upload, or publish.
//
// # Bundle Contract
//
// The source manifest is the producer-to-distributor contract. It is named by
// ManifestName, currently "manifest.json", and uses SchemaVersion, currently 1.
// A Manifest contains:
//
//   - SchemaVersion: the source manifest schema version.
//   - ID: the producer's stable bundle identifier.
//   - Digest: the canonical digest of the ordered file records.
//   - Created: an RFC3339 timestamp when marshaled to JSON.
//   - Files: an ordered list of ManifestFile records.
//
// Each ManifestFile records a slash-separated bundle-relative Path, a lowercase
// sha256:<64 hex> SHA256 digest, and a byte Size. File order is significant for
// the bundle digest and should be chosen deliberately by the producer. Explicit
// file lists preserve caller order; scan mode sorts by slash-separated path.
//
// # Path Rules
//
// Public bundle paths are always slash-separated and relative to the bundle
// root. ValidateSourcePath rejects empty paths, absolute paths, path traversal,
// dot segments, backslashes, and reserved manifest/state paths. Source files
// must be regular files; symlinks and other special files are rejected.
//
// BuildManifest with Scan true recursively scans Root, includes regular files
// including dotfiles, excludes manifest.json and .distributor.json, rejects
// symlinks, and sorts paths lexically. BuildManifest with Files uses exactly
// the caller-provided paths and preserves their order. Exactly one selection
// mode must be used.
//
// # Manifest Workflows
//
// BuildManifest reads existing files under a local root, calculates each
// ManifestFile, defaults a zero Created value to the current UTC time, calculates
// the bundle digest, and validates the result. WriteManifest writes
// manifest.json and fails if it already exists unless WriteManifestOptions has
// Overwrite set. LoadManifest reads and parses manifest.json. ParseManifest and
// MarshalManifest are useful when an application stores or transmits manifest
// bytes directly; MarshalManifest validates before writing deterministic,
// indented JSON with a trailing newline.
//
// ValidateManifest checks manifest-only semantics, including schema version,
// required fields, path safety, duplicate file paths, digest syntax, file sizes,
// and bundle digest. ValidateBundle checks a supplied Manifest against local
// files under a root, including existence, regular-file type, size, SHA-256
// digest, path safety, and bundle digest.
//
// # Complete Bundle Writing
//
// WriteBundle is the most convenient producer workflow when source files live
// outside the final bundle directory. It copies each BundleFile.SourcePath into
// a staged bundle at BundleFile.Path, builds and writes a compliant manifest,
// validates the staged bundle, and promotes it to WriteBundleOptions.Root.
// Overwrite permits replacement of an existing bundle root using a best-effort
// sibling temporary and backup strategy.
//
// # Digest Helpers
//
// FileDigest returns the sha256:<64 hex> digest for file bytes. BundleDigest
// returns the canonical bundle digest for an ordered []ManifestFile.
// CanonicalFilePayload returns the JSON payload used by BundleDigest, which is
// mainly useful for tests and diagnostics. ValidateDigest checks digest syntax.
//
// Example: build and write a manifest for files already under a bundle root.
//
//	root := "/var/lib/reports/daily-2026-06-06"
//	manifest, err := bundle.BuildManifest(bundle.BuildOptions{
//		Root:  root,
//		ID:    "reports.daily.2026-06-06",
//		Files: []string{"report.md", "summary.txt"},
//	})
//	if err != nil {
//		return err
//	}
//	if err := bundle.WriteManifest(root, manifest, bundle.WriteManifestOptions{}); err != nil {
//		return err
//	}
//	if err := bundle.ValidateBundle(root, manifest); err != nil {
//		return err
//	}
//
// Example: create a complete bundle from producer-generated files.
//
//	manifest, err := bundle.WriteBundle(bundle.WriteBundleOptions{
//		Root: "/var/lib/distributor-source/daily-2026-06-06",
//		ID:   "reports.daily.2026-06-06",
//		Files: []bundle.BundleFile{
//			{SourcePath: "/tmp/report.md", Path: "report.md"},
//			{SourcePath: "/tmp/summary.txt", Path: "summary.txt"},
//		},
//	})
//	if err != nil {
//		return err
//	}
//	_ = manifest
package bundle