# Export Center Determinism & Rerun Hash Guide

Advisory anchor: `docs/product-advisories/archived/27-Nov-2025-superseded/28-Nov-2025 - Export Center and Reporting Strategy.md` (EC1–EC10).

## EC1 — Signed schemas
- Export profile schema: `docs/modules/export-center/schemas/export-profile.schema.json` (selectors, approvals, quotas).
- Export manifest schema: `docs/modules/export-center/schemas/export-manifest.schema.json` (rerunHash, integrity headers, attestations, quotas/backpressure).
- Both schemas must be signed (DSSE) alongside publication; DSSE envelopes live next to the schema files when generated in CI.

## EC2 — Per-adapter determinism and rerun hash
- JSON adapters: canonical JSONL, sorted keys, zstd level 19; filenames stable (`advisories-<shard>.jsonl.zst`); gzip forbidden.
- Trivy adapters: pin schema version (see `trivy-adapter.md`), normalize namespaces, ordered records by `(namespace, package, vulnerabilityId)`.
- Mirror full: tar with `--sort=name --mtime=@0 --owner=0 --group=0 --numeric-owner`; manifest entries sorted by path; indexes stable.
- Mirror delta: include `baseManifestDigest`, sorted `added`/`removed`, explicit `tombstones`; reject deltas without tombstones for removed entries.
- Rerun hash algorithm: SHA-256 over newline-joined, sorted `contents[*].digest` values; stored in `manifest.rerunHash` and asserted in CI.
- CI harness: `docs/modules/export-center/operations/verify-export-kit.sh` recomputes rerun hash and schema-consistent integrity hints.

## EC3 — DSSE + SLSA attestation with log metadata
- All manifests and provenance files carry DSSE envelopes; provenance must include SLSA v1 builder metadata plus log proof (`kind`, `logId`, `logIndex`, `entryDigest`, `timestamp`).
- Provenance subjects list both `manifests/export.json` and bundle tar/OCI digest; log metadata is mandatory even when transparency uploads are deferred.

## EC4 — Cross-tenant approval flow
- `selectors.tenants` must contain the profile tenant; when selectors include additional tenants or wildcards, `approval.required=true` with `approvedBy` and `ticket` is mandatory (validated by the verify script).

## EC5 — Distribution integrity headers and OCI annotations
- HTTP: `Digest: sha-256=<base64>` derived from bundle digest; `X-Stella-Signature: dsse-b64:<envelope>`; `X-Stella-Immutability: true` for immutable responses.
- OCI: annotations must include `io.stellaops.export.profile`, `io.stellaops.export.run`, `io.stellaops.export.manifest-digest`, `io.stellaops.export.provenance-ref`, and `org.opencontainers.image.ref.name`.

## EC6 — Trivy schema pinning
- Schema compatibility is pinned in `trivy-adapter.md`; CI rejects versions above the pinned set and emits `ERR_EXPORT_UNSUPPORTED_SCHEMA`.
- Mirror/export manifests must record the targeted `schemaVersion` so rerun-hash and consumers can enforce deterministic decoding.

## EC7 — Mirror delta/tombstone rules
- Deltas MUST include tombstones for all removals and a `baseManifestDigest` that matches the referenced baseline; omitted tombstones fail verification.
- `delta.added/removed` are sorted, and `resetBaseline=false` unless explicitly set; consumers apply deltas in order and refuse out-of-order manifests.

## EC8 — Encryption/recipient policy
- Only `age` or `aes-gcm` envelopes; recipients enumerated with `fingerprint` and optional `wrappedKey` in manifest and provenance.
- `strict=true` encrypts everything except manifest/provenance; defaults to `false` to keep discovery metadata plaintext.

## EC9 — Quotas and backpressure
- Manifest `quotas` block captures `maxActiveRuns`, `maxQueuedRuns`, `backpressureMode` (`reject`|`defer`|`throttle`), and optional `cpuThrottlePercent`.
- CI verifies presence of quotas; operators surface `429` with `X-Stella-Quota-*` hints when limits engage.

## EC10 — Offline export kit + verify script
- Fixtures: `src/ExportCenter/__fixtures/export-kit/*` (manifest, manifest.sha256, manifest.dsse, provenance).
- Verifier: `docs/modules/export-center/operations/verify-export-kit.sh`
  - Validates manifest hash against `manifest.sha256`.
  - Recomputes rerun hash.
  - Confirms integrity headers align with OCI annotations.
  - Enforces approval + quota presence for cross-tenant selectors.
  - Confirms provenance references manifest digest and carries log metadata.
- Tar flags for offline kit assembly: `tar --sort=name --mtime=@0 --owner=0 --group=0 --numeric-owner`.

## Quick rerun-hash smoke (uses fixtures)
```bash
./docs/modules/export-center/operations/verify-export-kit.sh src/ExportCenter/__fixtures/export-kit
```