# Findings Ledger (Vuln Explorer) — Event Model & Replay (Md.XI draft)

> Status: DRAFT — depends on GRAP0101 alignment and security review. Do not publish until hashes and schema cross-checks are complete.

## Scope
- Explain event schema, hashing strategy, Merkle roots, and replay tooling as consumed by Vuln Explorer.
- Align with canonical ledger docs: `docs/modules/findings-ledger/schema.md`, `merkle-anchor-policy.md`, `replay-harness.md`.
- Provide deterministic examples and hash manifests (record in `docs/assets/vuln-explorer/SHA256SUMS`).

## Dependencies
| Input | Status | Notes |
| --- | --- | --- |
| GRAP0101 contract | pending | Confirm field names/identifiers to keep Explorer/ledger in sync. |
| Security review (hashing/attachments) | pending | Required before publication. |
| Replay fixtures | available | See `docs/modules/findings-ledger/replay-harness.md` and `golden-checksums.json`. |

## Event Schema (summary)
- `finding_records` (canonical): includes advisory/VEX/SBOM refs, `policyVersion`, `sourceRunId`, `explainBundleRef`, tenant, artifact identifiers.
- `finding_history`: append-only transitions with actor, scope, justification, timestamps (UTC, ISO-8601), hash-chained.
- `triage_actions`: discrete operator actions (comment, assign, remediation, ticket link) with immutable provenance.
- `remediation_plans`: planned fixes linked to findings; optional due dates and checkpoints.

> See `docs/modules/findings-ledger/schema.md` for authoritative field names; update this section when GRAP0101 finalizes.

## Hashing & Merkle Roots
- Per-event SHA-256 digests; history and actions chained by previous hash to ensure tamper evidence.
- Periodic Merkle roots anchored per tenant + artifact namespace; policy version included in leaf payloads.
- Export bundles carry `manifest.json` + `audit_log.jsonl` with hashes; verify against Merkle roots.

## Replay & Verification
- Replay harness (`replay-harness.md`) replays `finding_history` + `triage_actions` to reconstruct `finding_records` and compare hashes.
- Use `golden-checksums.json` to validate deterministic output; include hash of replay output in `SHA256SUMS` once fixtures copied here.

## Offline/Determinism Notes
- All sample logs/responses added to this doc must have hashes recorded in `docs/assets/vuln-explorer/SHA256SUMS`.
- Use fixed fixture IDs; avoid live timestamps; maintain sorted outputs.

### Hash Capture Checklist (when fixtures are pulled)
- `assets/vuln-explorer/ledger-history.jsonl` (sample history entries)
- `assets/vuln-explorer/ledger-actions.jsonl` (triage actions snippet)
- `assets/vuln-explorer/ledger-replay-output.json` (replay harness output)
- `assets/vuln-explorer/ledger-manifest.json` (export manifest sample)

## Open Items
- Replace schema placeholders once GRAP0101 and security review land.
- Add sample history/action entries and replay verification commands with hashes.
- Document attachment token validation path when security review provides final wording.

_Last updated: 2025-12-05 (UTC)_