# Evidence Bundle v1 Contract (2025-11-19)

## Scope
Frozen contract for Evidence Bundle v1 covering AdvisoryAI/Concelier/Excititor evidence exports used by air-gap and attestation flows.

## Artefact layout
- Tarball name: `evidence-bundle-<id>.tar.gz`
- Manifest (required): `manifest.json`
- Payloads (required): `observations.ndjson`, `linksets.ndjson`
- Optional: `timeline.ndjson` (time anchors), `transparency.json` (Rekor UUID or skip_reason)
- Hash list: `hashes.sha256` (sha256 of each file)

### manifest.json fields
```json
{
  "bundle_id": "evidence-bundle-m0",
  "version": "1.0.0",
  "created": "2025-11-19T00:00:00Z",
  "tenant": "demo",
  "scope": "vex",
  "inputs": ["sha256:payload-obs", "sha256:payload-linksets"],
  "aoc": {"guardrails": true, "details": ["schema:frozen:1.0", "limits:chunk:max=2000"]}
}
```

### observations.ndjson (sample record)
```json
{"observationId":"obs-ossl-001","advisoryId":"CVE-2024-1234","component":"pkg:deb/openssl@1.1.1w","source":"nvd","fetchedAt":"2025-11-18T12:00:00Z"}
```

### linksets.ndjson (sample record)
```json
{"linksetId":"lnm-ossl-001","advisoryId":"CVE-2024-1234","components":["pkg:deb/openssl@1.1.1w"],"normalized":true,"createdAt":"2025-11-18T12:05:00Z"}
```

### transparency.json (optional)
```json
{"rekor_uuid": null, "skip_reason": "offline"}
```

## Determinism rules
- All timestamps must be UTC RFC3339.
- Ordering: sort NDJSON by `advisoryId`, then `component`, ascending.
- Hashes: compute sha256 on raw file bytes; record in `hashes.sha256` and in manifest `inputs`.
- Tenant must be lowercase; include in manifest and any attestation subject claims.

## Example bundle (sample)
- Path: `docs/samples/evidence-bundle/evidence-bundle-m0.tar.gz`
- SHA256: `$(cat docs/samples/evidence-bundle/evidence-bundle-m0.tar.gz.sha256 | awk '{print $1}')`
- Contains sample manifest/observations/linksets/transparency per above.

## Attestation linkage
- See `attestation-scope-note.md` for required claims.
- Subject digest should reference the tarball sha256; include `bundle_id` and `tenant`.

## Change log
- 2025-11-19: v1 frozen (initial publication). Add real sample tarball + hashes once produced.