# history-audit: SCD2 Change-History Audit Trail Service

## PURPOSE
Jacqueline Cheong explains why Artie's history tables are genuinely useful: training
models on historical data, debugging, and auditing — "you want to know hey, something
changed, which person on my team came in and what did they change." `history-audit` is
a small integration service built on SQLAlchemy and httpx that ingests pipeline
change events, stores them as an append-only SCD Type 2 history table, and forwards
each event to a downstream warehouse sink over HTTP.

## WHY THIS MATTERS
The history-table feature was the one every customer said no to, then 40% turned on
six months later — because the value only showed up once teams had history to query.
This service implements that exact dual purpose: an immutable per-row history
(`valid_from`, `valid_to`, `is_current`, `op`) plus an actor-attributed audit trail
that answers "who changed what, when." It also demonstrates reliable outbound
delivery to a warehouse — you must not drop or duplicate events.

## HOW TO BUILD
1. Define a `ChangeEvent` model: `table`, `pk`, `op`, `actor`, `ts`, `payload`.
2. On insert, close the previous open row for that `pk` (`valid_to = ts`,
   `is_current = False`) and append the new open row — all in one transaction.
3. Expose `POST /events` to accept a CDC/audit event and `GET /history/{table}/{pk}`
   to return the full version chain.
4. Push each accepted event to the sink with `httpx.Client`, using an idempotency key
   so retries don't double-write.
5. Add a `GET /audit/{actor}` view for compliance queries.

```python
session.add(ChangeEvent(table=t, pk=pk, op="UPDATE", actor=actor, ts=ts))
# close prior version, open the new one -> SCD Type 2
```

## WHEN TO USE IN PRODUCTION
Use it for compliance/audit trails, ML feature backfills, debugging "what changed"
incidents, and any workflow where downstream systems need full row history. Pair it
with a warehouse sink for analytics. Do NOT use it where only the latest row matters
and storage/write volume is expensive — SCD2 multiplies rows by change count. This
skeleton uses a local SQLite engine; swap the URL for Postgres in real deployments.

## HOW IT HELPS STUDENTS
You practise ORM modeling, transactional correctness, idempotent HTTP integration and
SCD Type 2 data design — the exact skills behind Artie's flagship feature and every
audit-trail system in regulated industries.

## STARTER CODE
`starter/main.py` defines the SQLAlchemy models, an idempotent httpx sink stub and an
SCD2 `record_event` function with `# TODO` markers for the transaction and error paths.
