Bundles

Purpose and authority boundary

Bundles provide a portable verification boundary around already authoritative records. They do not create Protocol, Workflow, Provenance, report, or artifact authority. Verification resolves those owners inward and compares complete identity; a syntactically valid digest or manifest field is not sufficient.

Identity rule: the canonical manifest and exact embedded bytes are verified content. ZIP order, compression, timestamps, archive bytes, transport headers, and local extraction paths are not scientific bundle identity.

Two supported manifest generations

• v1 / 1.0.0: ReviewBundleManifest binds approved Protocol, optional verified Workflow and Provenance, artifact entries, required schemas, shared identity, and unresolved candidates. BundleVerifier returns structured errors/warnings and verified artifacts.
• v2 / 2.0.0: VerifiedReviewBundleV2 supports FE-06 exact workspace-cut/report/source-generation bindings, embedded inventory entries, and explicit external references. It is additive; v1 remains historical and supported.

Source: NexusScholar.Bundles. Core decisions: ADR 0009, ADR 0020, and the FE-06 contract in ADR 0033.

Key types and services

• ReviewBundleManifest, BundleProtocolBinding, BundleWorkflowBinding, BundleProvenanceBinding, and BundleArtifactEntry model v1.
• IBundleAuthorityResolver supplies complete verified Protocol, Workflow, and Provenance records to v1 verification.
• BundleArtifactPath normalizes portable logical paths and rejects path traversal.
• ReviewBundleV2Authority creates verified v2 manifests; ReviewBundleV2CanonicalCodec strictly round-trips their bytes.
• BundleV2EmbeddedEntry binds ordinal, logical path, size, raw-byte digest, role, and source generation.
• BundleV2ExternalEntry makes missing bytes explicit with reference kind/locator, availability note, and optional expected digest.
• ReviewBundleV2Verifier compares canonical manifest bytes against exact observed inventory and returns stable findings plus an inventory digest.

Verification flow

parse untrusted manifest
  → enforce exact schema and canonical bytes
  → resolve complete source authorities
  → validate safe, unique logical paths
  → compare declared and observed inventory exactly
  → recompute every embedded size and raw-byte digest
  → reject missing, extra, altered, mis-scoped, or foreign entries
  → return verification result; never partial authority

External references never masquerade as embedded content. v2 permits only explicit locator schemes, rejects file paths, user-info, credential-like values, and foreign source generations, and reports IsSelfContained = false when any external entry remains.

Deterministic identity rules

Manifests use scope bundle-manifest. Embedded content uses raw-artifact-bytes. Source/report/workspace-cut digests carry explicit scopes. Manifest arrays use contract-defined deterministic ordering; v2 entry ordinals and logical paths are closed and unique. The inventory digest is a canonical digest over observed path, size, and byte digest—not the digest of an archive container.

Failure and refusal behavior

v1 produces stable findings for invalid/stale manifest, unsupported schema, unsafe/duplicate paths, missing artifact, size/checksum mismatch, destructive overwrite, and invalid Protocol/Workflow/Provenance binding. v2 adds noncanonical manifest, missing/extra inventory, altered artifact, mis-scoped digest, duplicate entry, foreign generation, and invalid external reference. Verification is all-or-nothing; no failed import is committed.

Tests and evidence

BundleTests and BundleV2Tests cover authority resolution, exact inventory, paths, altered bytes, external locators, and strict codecs. BundleFixtureTests and FE-06 release fixtures replay portable cases. Release closure is recorded in FE-06 Completion Evidence.

Dependencies, extension points, and nonclaims

Bundles is an outward verifier and depends inward on Kernel, Shared, Protocol, Workflow, and Provenance; none of those owners depends back on Bundles. New bundle semantics require a schema version. New entry/reference kinds require explicit scoping and threat-model tests.

The module does not claim archive-format identity, signatures, encryption, malware safety, long-term preservation certification, remote availability, legal redistribution, cloud sync, submission-package conformance, PRISMA certification, or broad PHP/blueprint compatibility.