# Potable Overview

Potable is a repository-core library for AT Protocol data structures and
integrity semantics. It intentionally focuses on deterministic data handling
and verifiable content, leaving transport, authorization, and application
policies to the host application.

## Scope

Potable covers:

- Binary/data formats: DAG-CBOR, CID, varint, CAR
- Authenticated history: commit creation and verification
- Ordered key/value index: Merkle Search Tree (MST)
- Repository operations: create/apply/list/get/export/import/verify
- Storage contracts: blockstore and blob storage behaviours

Potable does not cover:

- Network protocols (XRPC, Firehose, federation transport)
- DID document resolution over HTTP
- Handle DNS/TXT resolution
- App-level authorization/moderation/business logic

## Architecture At A Glance

```text
Record Map
   |
   v
DAG-CBOR encode -> bytes -> CID.create_from_bytes
   |                                 |
   +--------------------------+      |
                              v      v
                            BlockStore (CID -> bytes)
                              |
                              v
                        MST node blocks
                              |
                              v
Commit.create (did, data=root, prev, rev, sig)
                              |
                              v
                           new head CID
```

## Core Invariants

- Identical valid inputs produce identical DAG-CBOR bytes.
- CID verification is content-derived (`sha256(bytes)` must match multihash).
- MST listing is lexicographic by key.
- Same final key/value set yields same MST root CID, independent of insertion order.
- Commits are signed over unsigned deterministic bytes.
- Repository export/import preserves verifiable commit and block history.

## Canonical Data Layers

1. Blocks
- Opaque bytes keyed by CID.
- Includes record blocks, MST node blocks, commit blocks.

2. MST
- Ordered mapping of `collection/rkey -> record_cid`.
- Persistent and content-addressed.

3. Commit chain
- Each commit points to MST root + previous commit (except genesis).
- Each commit includes Ed25519 signature.

4. Repository engine
- Applies writes against current head.
- Produces new commit CID.
- Supports reads, listing, integrity verification, and CAR import/export.

## Public Entry Points

- `Potable.Repository` for high-level repo operations
- `Potable.MST` for tree-level operations
- `Potable.Commit` for commit byte handling and signature checks
- `Potable.CAR` for archive boundaries
- `Potable.DagCbor` and `Potable.CID` for codec/addressing internals

## Recommended Reading Order

1. `docs/01_quickstart.md`
2. `docs/02_data_formats.md`
3. `docs/03_mst.md`
4. `docs/04_commits_and_signatures.md`
5. `docs/05_repository_engine.md`
6. `docs/06_storage_backends.md`
7. `docs/07_known_limitations.md`