Refactor code structure for improved readability and maintainability; removed redundant code blocks and optimized function calls.

docs/modules/evidence-locker/attestation-scope-note.md

@@ -0,0 +1,37 @@
+# Evidence Locker Attestation Scope Note (v1) — 2025-11-19
+
+## Scope & Coverage
+- Predicates: `in-toto Provenance` (DSSE-wrapped) with claims for bundle inputs, normalization pipeline version, tenant scope, and content hashes; optional `Rekor` transparency pointer when online.
+- Artefacts covered: Evidence Bundle v1 payloads (observations, linksets, normalization diffs) and mirror bundle manifest hash when present.
+- Tenancy: tenant-id is lowercased, required, and included in subject, claims, and DSSE `_type` to keep air-gap parity.
+- Transparency: if Rekor unavailable (air-gap), include `transparency.skip_reason` = `offline` and signed local timeline anchor.
+
+## Required claims (PromotionAttestationBuilder input)
+- `subject.digest` (sha256 of bundle tar) and `subject.name` (bundle_id).
+- `bundle.created` (UTC RFC3339) and `bundle.version` (semantic).
+- `pipeline.version` (build ID or git SHA) and `pipeline.inputs` (hashes of observation/linkset payloads).
+- `tenant` (lowercase) and `scope` (advisory | vex | policy | mixed).
+- `evidence_bundle` (path/doi) and `transparency` (rekor UUID or skip reason).
+- `aoc.guardrails` (boolean) and `aoc.details` (list of enforced checks).
+
+## Example builder payload
+```json
+{
+  "subject": {"name": "evidence-bundle-m0", "digest": "sha256:REPLACE"},
+  "bundle": {"id": "evidence-bundle-m0", "version": "1.0.0", "created": "2025-11-19T00:00:00Z"},
+  "pipeline": {"version": "git:abcd1234", "inputs": ["sha256:payload-hash-1", "sha256:payload-hash-2"]},
+  "tenant": "demo",
+  "scope": "vex",
+  "evidence_bundle": "out/evidence/bundles/evidence-bundle-m0.tar.gz",
+  "transparency": {"rekor_uuid": null, "skip_reason": "offline"},
+  "aoc": {"guardrails": true, "details": ["schema:frozen:1.0", "limits:chunk:max=2000"]}
+}
+```
+
+## Placement
+- File: `docs/modules/evidence-locker/attestation-scope-note.md` (this document).
+- Reference in Evidence Bundle changelog and sprint `Execution Log` when updated.
+
+## Next steps
+- Swap placeholder digest values with real bundle hash after MIRROR-CRT-56-001 emits artefact.
+- Attach this note to Concelier/Excititor attestation tasks (CONCELIER-ATTEST-73-001/002, EXCITITOR-ATTEST-73-001/002).

docs/modules/evidence-locker/evidence-bundle-v1.md

@@ -0,0 +1,57 @@
+# 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.