audit-stream

Append-only governance event stream for the Kinetic Gain portfolio. Hash-chained for tamper-evidence, Server-Sent Events for live tailing, REST for queries. The cross-cutting telemetry layer every other portfolio repo can produce into.

                                       ┌─────────────────────┐
                                       │     audit-stream    │
                                       │                     │
   procurement-decision-api ──events──▶│   POST /events      │
   policy-as-code-engine    ──events──▶│   GET  /events?…    │
   data-contract-registry   ──events──▶│   GET  /stream  ◀──── live tail (SSE)
   aeo-validator-service    ──events──▶│   GET  /verify       │
   incident-correlation-rs  ──events──▶│   GET  /stats        │
   hash-attestation-rs      ──events──▶│                     │
   feature-flag-rs          ──events──▶│ chain: prev_hash ──▶ hash  ──▶ next.prev_hash ──▶ …
   request-shadow-rs        ──events──▶│                     │
                                       └─────────────────────┘

Why

Across the portfolio, "something governance-shaped happened" is the recurring event: a Decision Card was drafted, a policy bundle denied a request, a data contract was promoted, a watch detected drift, an attestation failed. Each repo already logs these — but to its own logs, in its own shape, with its own retention.

audit-stream is the shared event spine. One schema, one chain, one SSE socket, one REST query interface. Operators see the whole portfolio's behavior in a single place; auditors get a tamper-evident record by construction.

Endpoints

Event envelope

{
  "event_id": 42,
  "timestamp": "2026-05-15T03:14:15+00:00",
  "kind": "watch_drifted",
  "source": "aeo-validator-service",
  "payload": { "watch_id": "abc123", "added_fields": ["claims"] },
  "prev_hash": "9a3f…",
  "hash":      "b7d1…"
}

event_id is monotonic; the store assigns it. prev_hash is the previous event's hash (or 64 zeros for event #1). hash is SHA-256 over the canonical JSON of every other field — sorted keys, no whitespace.

Event kinds (v0.1)

Adding kinds is a Literal-only change; producers and verifiers stay backwards-compatible if you keep the canonical-hash construction stable.

Tamper-evidence

/verify rewalks the chain top-to-bottom and reports:

{
  "valid": false,
  "checked": 5,
  "first_break_at": 6,
  "reason": "hash mismatch at event #6"
}

Operators can wire a periodic verify into their on-call alerting; a valid: false result is one of the most useful red lights a governance stack can produce.

Live tail

GET /stream is a Server-Sent Events endpoint. Each event the store appends becomes one SSE message:

event: watch_drifted
id: 42
data: {"event_id":42,"timestamp":"2026-05-15T03:14:15+00:00", …}

Tail it with curl -N http://localhost:8093/stream, or wire it into a dashboard (e.g. a EventSource in browser JS, or httpx-sse in Python).

Quick start

pip install audit-stream
audit-stream            # binds 0.0.0.0:8093

# in another shell
curl -X POST http://localhost:8093/events \
  -H 'Content-Type: application/json' \
  -d '{"kind":"decision_card_drafted","source":"procurement-decision-api","payload":{"decision_id":"DEC-001"}}'

Composes with

• procurement-decision-api · policy-as-code-engine · data-contract-registry · aeo-validator-service · incident-correlation-rs · hash-attestation-rs · feature-flag-rs · request-shadow-rs — any of these can POST /events to produce a record of their own governance moments.

Tests

pip install -e ".[dev]"
ruff check src tests && ruff format --check src tests
mypy src
pytest -v

CI matrix runs Python 3.11 / 3.12 / 3.13.

License

MIT. See LICENSE.