Skip to content

feat(governance): add hash-chained audit logger for predictions#36

Merged
Goldokpa merged 1 commit into
developfrom
feature/governance-audit-logger
May 5, 2026
Merged

feat(governance): add hash-chained audit logger for predictions#36
Goldokpa merged 1 commit into
developfrom
feature/governance-audit-logger

Conversation

@obielin
Copy link
Copy Markdown
Collaborator

@obielin obielin commented May 4, 2026

Summary

  • Adds src/climatevision/governance/audit_logger.py — append-only JSONL audit trail for every model prediction.
  • Each entry records: timestamp, model version, SHA-256 hash of the input payload, output summary stats (mean confidence, positive fraction, threshold), request/user IDs, and a prev_hash linking back through the chain.
  • verify_chain() walks the file from genesis and detects any tampered entry by recomputing the hash and checking the link to its predecessor.
  • Process-safe via an in-memory lock; ready to be wrapped in a filelock for cross-process safety.

Why

Sprint deliverable: "Build audit_logger.py — immutable audit trail for every model version and prediction." Required input for the model governance / compliance documentation track.

Test plan

  • pytest tests/test_audit_logger.py — 6/6 pass
    • first entry chains to genesis hash
    • chain links propagate correctly across multiple entries
    • tampering with any historical row breaks verify_chain()
    • chain resumes correctly across new logger instances pointed at the same file
    • module-level helper writes to the configured default path
    • dict-shaped inputs/outputs (e.g. carbon analytics dicts) are accepted

Notes for reviewers

  • Branched off develop.
  • Hash-link only, not signed. Cryptographic signatures can be layered on later by signing each entry_hash with a release key.

Append-only JSONL audit trail. Each entry records the model version,
SHA-256 hash of the input payload, summary statistics for the output,
and a prev_hash linking back through the chain. verify_chain() walks
the file and detects any tampered entry by recomputing the hash and
checking the link to its predecessor.
@obielin obielin force-pushed the feature/governance-audit-logger branch from 9aae413 to 8ae630d Compare May 5, 2026 22:08
Copy link
Copy Markdown
Collaborator

@femi23 femi23 left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hash-chained JSONL is exactly what I need to point auditors at. The verify_chain() walk plus the genesis-hash anchor means we can detect any tampering down to the byte. Process-safe lock is fine for the API; once we deploy with multiple uvicorn workers we'll wrap calls in a filelock or queue, as you note in the docstring.

Approving.

@Goldokpa Goldokpa merged commit f018cf9 into develop May 5, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants