# Sync And Firehose Primitives

Potable now includes the core building blocks needed to implement
`com.atproto.sync.subscribeRepos`-style replay and streaming in host services.

Potable intentionally stops at library primitives. Network transport, auth, and
service-level policies stay in the host application.

## Modules

- `Potable.Sync.CommitEnvelope`
  - canonical commit event structure
  - normalizes repo commit metadata for storage and wire encoding
  - encodes firehose-style `#commit` maps with base64 CAR payloads
- `Potable.EventLog`
  - behaviour for durable, cursorable, replayable commit logs
- `Potable.EventLog.Memory`
  - in-memory reference adapter for tests/dev harnesses
- `Potable.Sync.Cursors`
  - cursor wire codec (`integer <-> string`)
- `Potable.Sync.CAR`
  - builds CAR payloads for commit replay (commit + reachable MST + records)

## Integration Pattern

1. Build commit envelope from a validated repo commit.
2. Generate replay CAR bytes for that commit.
3. Append envelope to an event-log adapter.
4. Serve replay/stream from cursor by reading event-log batches.
5. Emit wire events from `CommitEnvelope.to_firehose_event/1`.

## Storage Requirements For Production

Production adapters implementing `Potable.EventLog` should provide:

- monotonic sequence assignment
- durable persistence
- replay by cursor in ascending order
- bounded query controls (`limit`, optional filtering implemented by host app)
- retention policy and pruning strategy

## Deliberate Non-Goals

Potable does not ship:

- websocket or HTTP server endpoints
- subscription auth/ACL policy
- global relay fan-in logic
- feed/appview projection services

Those layers are intentionally left to applications that embed Potable.