prepared release

AGENTS.md

@@ -0,0 +1,104 @@
+# AGENTS.md
+
+These instructions apply to the entire Frid workspace.
+
+## Project role
+
+Frid is shared networking infrastructure. `federation-net` is the generic
+transport; `music-dht` is the distributed music-directory overlay used by
+Furumi applications. Treat public APIs, persisted state, hash derivations, and
+wire formats as compatibility-sensitive.
+
+Read `ARCHITECTURE.md` before changing protocols, routing, persistence,
+rendezvous, tickets, identity, or record derivation.
+
+## Required checks
+
+The workspace uses Rust edition 2024 and Rust 1.91 or newer.
+
+```bash
+cargo fmt --all -- --check
+cargo check --workspace --all-targets --all-features
+cargo clippy --workspace --all-targets --all-features -- -D warnings
+cargo test --workspace
+```
+
+Integration tests open real sockets and establish iroh connections. If a
+restricted environment prevents socket binding or discovery, rerun them with
+the required permission and report the limitation; do not weaken or delete the
+tests.
+
+## Compatibility
+
+Do not change these without an explicit migration/versioning decision:
+
+- ALPN byte strings;
+- transport, DHT, device-sync, catalog, or ticket versions;
+- `NetworkId`, `SchemaId`, `NodeId`, `ItemId`, or `DhtKey` derivation domains;
+- postcard/serde wire enum layouts;
+- content-ID normalization;
+- SQLite schema or identity-key encoding;
+- public re-exports from either crate.
+
+Postcard is not self-describing. Adding a field to a serialized type can be a
+breaking wire change even when serde would accept the Rust source change.
+
+## Layer boundaries
+
+- `federation-net` owns identity, iroh endpoints, handshake, tickets,
+  rendezvous, typed framing, event backpressure, and generic byte streams.
+- `federation-net` must not acquire music, catalog, playlist, or application
+  authorization logic.
+- `music-dht` owns Kademlia routing, requests, records, replication, search,
+  content lookup, and its persistence abstraction.
+- Rich catalogs, audio, and device sync use dedicated ALPN stream protocols;
+  do not push bulk data through the typed DHT event channel.
+- Applications own policy: knowing a network ID or discovering a peer is not
+  proof of authorization.
+
+## Async and concurrency
+
+- Never hold a mutex guard across `.await`.
+- Keep SQLite and blocking filesystem work off Tokio reactor threads.
+- Bound channels, request maps, batches, frames, and peer-provided collections.
+- Make shutdown idempotent and ensure background tasks cannot retain event
+  senders indefinitely.
+- Preserve request peer-matching so a response from the wrong peer cannot
+  resolve another peer's request.
+- Use dial backoff and bounded lookup work for dead contacts.
+
+## DHT behavior
+
+- Routing uses stable node IDs and XOR distance; do not replace derivation or
+  ordering as a cosmetic refactor.
+- Validate that a record belongs under the key on which it was received.
+- Owners advance revisions; replicas do not rewrite ownership.
+- Tombstones must beat active records at the same or older revision.
+- TTL refresh, expiry, and republish behavior must remain deterministic.
+- `sync_library` is declarative and idempotent: unchanged items stay stable,
+  changed items advance, and removed items are tombstoned.
+- Search may return partial results when peers fail, but lookup must terminate.
+
+## Tests
+
+Add unit tests beside deterministic routing, framing, validation, storage, and
+merge logic. Use integration tests for behavior that depends on authenticated
+connections, handshakes, streams, disconnects, or multi-node lookup.
+
+Tests must use temporary directories and isolated network/schema IDs. Never
+use a developer identity, repository `tmp/` state, fixed public network, or
+real application database as a fixture.
+
+For protocol changes, test both rejection of incompatible peers and the
+intended compatible path. For input-bound changes, test the limit and the first
+value beyond it.
+
+## Documentation and packaging
+
+- Keep crate-level rustdoc and README examples compiling.
+- Root documentation describes the workspace; crate READMEs describe their
+  public API and operational model.
+- Do not describe Mainline-DHT rendezvous as private or as authorization.
+- Keep demo crates `publish = false`.
+- Published packages must include the WTFPL version 2 license text.
+- Update `ARCHITECTURE.md` when changing a protocol boundary or invariant.