# agents

ZDS is a Zig AT Protocol PDS. Start from the protocol, then cross-check against
prior implementations.

## references

- specs: <https://atproto.com/specs>
- lexicon rules: <https://atproto.com/specs/lexicon>
- reference PDS: <https://github.com/bluesky-social/atproto/tree/main/packages/pds>
- Tranquil: <https://tangled.org/tranquil.farm/tranquil-pds>
- Pegasus: <https://tangled.org/futur.blue/pegasus>
- local notes: `~/tangled.org/zzstoatzz.io/notes`
- protocol primitives: sibling `zat.dev/zat` repo

Use `zat` for primitives such as syntax, TIDs, DID/handle resolution, JWT,
DAG-CBOR, CAR, MST, repo verification, OAuth helpers, and JSON path helpers.
Do not edit `zat` from this repo unless explicitly asked.

## module map

- `main`, `core`: configuration, logging, syntax wrappers, process setup
- `http`: routing, request parsing, response helpers, CORS
- `auth`: passwords, app tokens, service auth
- `atproto/server`: account, session, service-auth XRPCs
- `atproto/repo`: repo read/write/import/blob XRPCs
- `atproto/sync`: sync reads, event stream, crawl requests
- `atproto/oauth`: OAuth metadata, PAR, authorization, token flow
- `atproto/identity`: DID credentials and PLC operations
- `atproto/proxy`: generic service proxying through `atproto-proxy`
- `storage`: SQLite state, repo commits, MST updates, blobstore metadata
- `internal`: ZDS-local utilities that keep feature code small; use this for
  reusable glue such as CLI parsing, sharded locks, passkey adapters, and JOSE
  compatibility helpers before deciding whether a primitive belongs in `zat`.
- `bench`, `tools`, `justfile`: local smoke tests, admin operations, and
  benchmark entry points. Prefer Just targets for repeatable workflows.

## invariants

- Repo writes preserve `$type == collection`, collection key rules, signed
  commits, MST updates, sync events, and crawler notification.
- Record bodies are decoded from repo blocks; the record index stores current
  CID and metadata, not canonical JSON content.
- Blob metadata is in SQLite; blob bytes live in the configured blobstore.
- Unknown lexicons can be accepted, but are not reported as
  `validationStatus: "valid"` without validation.
- Invite-required deployments must advertise `inviteCodeRequired: true` and
  consume invite codes during account creation.
- Passkeys are stored as account credentials: credential ID, public key,
  signature counter, friendly name, and timestamps. Password login remains
  available unless an explicit account policy changes that.
- App passwords are account-owned credentials. Management requires password
  auth, generated passwords are shown once, and revoking a credential revokes
  active sessions created with it.
- Password sessions are storage-backed token families. Accept session JWTs only
  when their JTI is active, and keep subject/actor/controller fields distinct in
  account-plane audit work.
- OAuth should follow the ATProto OAuth profile and JOSE behavior without
  relaxing stricter repo-signature verification semantics.
- Appview behavior belongs behind the generic proxy path, not in local
  Bluesky-specific route implementations.
- Browser-reported failures require browser request/response evidence.

## checks

Before committing code changes:

```sh
just test
just smoke
git diff --check
zig zen
```

Also run `just smoke-permissioned` when touching `com.atproto.space.*`,
permissioned-data storage, or the `/account/spaces` resident view.

Use `just invite` for admin-minted invite codes. Assume `ZDS_ADMIN_TOKEN` is
set in the repo `.env`; source it before running the target, for example
`set -a; . ./.env; set +a; just invite`. Use `just bench ...` for local
performance probes. Keep commits small. Amend only when asked. Do not revert
user or sibling-repo changes unless asked.