Update documentation relating to the public packages and http_upload API

pkg/bundle/doc.go

@@ -1,9 +1,104 @@
 // Package bundle provides producer-facing helpers for distributor source
-// bundle manifests.
+// bundles.
 //
-// A source bundle is a local directory containing a manifest.json file and the
-// files listed by that manifest. This package owns the public manifest model,
-// digest calculation, path validation, manifest parsing, manifest building,
-// local bundle writing, and local bundle validation used by Go producer
-// applications.
+// 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