# Events

Commit Intelligence consumes Code Parser output streams and publishes commit analysis results. All messages use Redis Streams with a single `payload` field containing JSON.

Stream name constants live in `internal/contracts/events/streams.go`. Optional prefix via `REDIS_STREAM_PREFIX` (e.g. `staging` → `staging.graph.delta.ready`).

## Consumed Streams

| Stream | Event type | Handler |
| --- | --- | --- |
| `graph.artifact.ready` | `GraphArtifactReadyEvent` | Validate → log → ACK (no analysis in v1) |
| `graph.delta.ready` | `GraphDeltaReadyEvent` | Validate → load delta from Mongo → analyze → persist → publish `commit.analysis.ready` |

Consumer group: `commit-intelligence-service` (`internal/redis/consumer.go`, overridable via `CONSUMER_GROUP` / `REDIS_STREAM_GROUP`).

### Input artifact URIs (TW-94)

Code Parser publishes `mongo://graph_deltas/{delta_id}` on `graph.delta.ready`. Commit Intelligence loads deltas from `DELTAS_MONGODB_DATABASE.graph_deltas` (default `adpilot_code_parser`).

`file://` URIs remain supported via `FilesystemReader` for unit tests only.

## Produced Streams

| Stream | Event type | When |
| --- | --- | --- |
| `commit.analysis.ready` | `CommitAnalysisReadyEvent` | After Mongo upsert to `commit_analyses` succeeds |

Publish order: **persist → publish**. Transient Mongo or publish failures leave the Redis message pending for retry; max retries move the message to `{stream}.dlq`.

## Redis consumer semantics (TW-94)

| Outcome | Action |
| --- | --- |
| Handler success | `XACK` |
| Permanent skip (bad JSON, validation fail, idempotent duplicate) | `XACK` |
| Transient failure (Mongo load/save, analyze, publish) | No ACK — message stays pending |
| Max retries exceeded | `XADD` to `{stream}.dlq` + `XACK` |

`XAUTOCLAIM` reclaims stale pending messages per stream.

## Contract Source

Local packages under `internal/contracts/` (wire-compatible with Code Parser):

| Package | Purpose |
| --- | --- |
| `internal/contracts/metadata/` | v1 envelope |
| `internal/contracts/events/` | Event structs, constructors, stream constants |
| `internal/contracts/graph/` | Graph IR (`Artifact`, `Delta`, …) |
| `internal/contracts/validate/` | Event validation |
| `internal/contracts/errors/` | Validation error types |

Use `New*Event()` constructors to populate the envelope automatically.