# Conformance And Interop

This document captures Potable's current interoperability behavior against
atproto repository expectations and rsky fixture data.

## Scope

This pass focused on repository correctness primitives:

- DAG-CBOR link/null handling
- CID parsing and verification strictness
- CAR import robustness
- Repository write semantics and data model gates
- Signature format/malleability controls
- DID/revision-aware verifier resolution
- Blob descriptor and payload integrity checks

Firehose wire transport is intentionally out of scope in Potable itself, but
the core replay primitives are now implemented.

## Implemented Conformance Guards

## 1) DAG-CBOR

- Map `nil` values are now supported (CBOR null).
- Tag-42 CID links require the identity-prefix byte (`0x00`).
- Tag-42 payloads without the prefix fail decode with
  `{:error, :invalid_cid_link_prefix}`.

## 2) CID

- `parse_cid/1` is strict and decode-backed, not prefix-only.
- `to_binary/1` supports CIDv1 base32 (`b...`), CIDv1 base58btc (`z...`), and
  CIDv0 (`Qm...`).
- `verify_bytes/2` returns typed errors for unsupported/malformed multihash
  instead of crashing.

## 3) CAR

- `import/1` and `import_into/2` return typed errors for invalid content.
- CID mismatches return `{:error, {:cid_mismatch, cid}}`.
- Header/section bounds are checked during parsing.

## 4) Repository

- `import_car/2` requires exactly one CAR root.
- `apply_writes/5` enforces operation semantics: create cannot overwrite
  (`{:error, :already_exists}`) and update/delete require existing keys
  (`{:error, :not_found}`).
- collection/rkey validation is enforced.
- record value validation rejects unsupported types (float rejection included).

## 5) Signatures

- ECDSA signing emits compact 64-byte signatures with low-S normalization.
- Verification defaults to strict compact low-S mode.
- Compatibility mode (`allow_malleable_sig: true`) accepts DER/high-S inputs.

## 6) DID-Aware Verification

- `Potable.Repository.verify_repo_with_resolver/4` verifies commit chains with
  DID continuity checks.
- Resolver-driven verifier selection occurs per `(did, rev)`.
- Resolver implementations can encode key rotation and revocation policy.
- `Potable.Identity.StaticResolver` provides deterministic in-memory policy for
  tests and offline validation.

## 7) Blob Conformance

- `Potable.Blob.validate/2` enforces descriptor shape (CID, mime type, size).
- `Potable.Blob.validate_data/2` verifies payload byte-size and CID integrity.
- `Potable.Blob.MemoryStorage` behavior is covered by put/get/exists/delete
  lifecycle tests.

## 8) Interop Regression Harness

A dedicated conformance test suite lives at:

- `potable/test/potable/conformance_regression_test.exs`

It includes:

- rsky fixture import + non-raising verify path checks
- null commit/link decode regressions
- strict CID parse/convert regressions
- CAR typed-error regressions
- repository write-semantics and value-validation regressions

Fixture used:

- `potable/test/fixtures/valid_repo.car` (from rsky test resources)

## 9) Firehose Primitive Coverage

Potable now includes test coverage for the core firehose substrate:

- cursor encoding/decoding (`Potable.Sync.Cursors`)
- commit envelope shape/encoding (`Potable.Sync.CommitEnvelope`)
- commit CAR completeness (`Potable.Sync.CAR`)
- append/replay semantics (`Potable.EventLog.Memory`)

## Remaining Interop Gap

Signature algorithm support is now implemented in Potable (`:ed25519`,
`:es256k`, `:es256`) with server-side key metadata.

The remaining work for full federation-grade interop is operational plumbing:

- production DID document key-resolution policy
- trusted key distribution and rotation policy across services
- deployment-level compatibility policy for mixed legacy repos

There is also a cryptographic interop hardening track:

- continuously verify ES256K/ES256 signature wire-format and low-S behavior
  against rsky/atproto vectors as upstream implementations evolve