# Portable Audit Pack Compatibility Mapping

Status: Draft frozen for implementation handoff (2026-02-10).

## Purpose
Map current StellaOps evidence bundle contracts to the portable audit pack profile so writer/reader implementations use one required field model.

## Canonical contract source
- Manifest schema: `docs/modules/evidence-locker/schemas/portable-audit-pack-manifest.v1.schema.json`
- Profile contract: `docs/modules/evidence-locker/portable-audit-pack-contract.md`

## Required field mapping
| Portable field | Existing source contract | Notes |
| --- | --- | --- |
| `spec_version` | `bundle.manifest.schema.json` `manifestVersion` | Portable uses fixed `1.0`. |
| `artifact.digest.sha256` | `evidence-bundle-v1.md` subject digest | Required, lowercase hex without `sha256:` prefix in manifest payload fields. |
| `files[*].sha256` | `checksums.schema.json` + bundle manifest entries | Portable stores per-file metadata directly in `files` map. |
| `digests.canonical_bom_sha256` | `stellaops-evidence-pack.v1.schema.json` digest fields | New explicit top-level binding for BOM canonical bytes. |
| `digests.dsse_payload_digest.sha256` | `attestation-contract.md` producer bundle digest linkage | Required preimage binding for DSSE payload verification. |
| `rekor.tile_refs[]` | `attestor/transparency.md` + Rekor receipt inputs | Portable requires deterministic path references under `rekor/`. |
| `rekor.root_hash` | Attestor checkpoint verification contract | Captured at inclusion checkpoint used by offline verifier. |
| `verifiers.pubkeys[]` | Existing key bundle references | Portable manifest contains verifier key references used by CLI/offline verifier. |

## Legacy bundle compatibility
- Legacy `evidence-bundle-<id>.tar.gz` and `portable-bundle-v1.tgz` remain valid for existing tooling.
- Portable audit pack profile is additive and must not reinterpret legacy fields silently.
- Readers should apply this precedence:
  1. If `spec_version` exists and equals `1.0`, validate against portable schema.
  2. Else if `manifestVersion` exists, validate against legacy `bundle.manifest.schema.json`.
  3. Else fail closed with `ERR_MANIFEST_PROFILE_UNKNOWN`.

## Writer/reader alignment rules
- Writers MUST populate every required portable field in schema v1.
- Readers MUST reject packs missing any required portable field.
- Writers/readers MUST share the same portable schema artifact ID and hash in release notes.

## Migration notes
- Maintain both parsers during transition.
- Export paths should emit explicit profile indicator in logs and operator output.
- Verification output should identify which profile was validated.