R2D2-MERIDIAN/crates/AGENTS.md

crates/ — Rust Workspace

Purpose

Every Rust crate in the product: the relay and its supporting libraries, the agent surface (ACP harness, agent, dev MCP), the client/interop binaries, and the shared tooling crates. This is the authoritative implementation of the Nostr protocol surface — clients (desktop/, REMAPPING/meridian-web/, REMAPPING/meridian-mobile/) consume it.

Ownership

Root Cargo.toml defines the workspace. desktop/src-tauri is a separate workspace and is not covered here (see desktop/src-tauri/AGENTS.md).

Crate	Role
meridian-relay	WebSocket relay server — main entry point; also hosts git smart HTTP and huddle audio
meridian-core	Core types, event verification, filter matching, kind registry
meridian-db	Postgres event store, data access layer, embedded migrator
meridian-auth	Authentication and authorization (NIP-42)
meridian-pubsub	Cross-pod event bus — the EventBus seam and its Redis/Dragonfly, Zenoh and shadow backends (the latter two behind the off-by-default zenoh feature), fan-out, and the trust profile ladder. Presence is no longer on the bus: it is Redis state, read through the manager's state_pool on every backend
meridian-search	Community-scoped Postgres FTS over the events.search_tsv generated column
meridian-test-db	dev-dependency only. The one test-database resolver (no fallback) and the fail-closed guard that refuses DROP against a database that has not proved it is disposable
meridian-audit	Tamper-evident per-community hash-chain audit log, keyed (community_id, seq)
meridian-media	Media storage, validation, thumbnails — library only; Axum handlers live in meridian-relay
meridian-relay-mesh	Pod-to-pod QUIC mesh within one deployment (one iroh endpoint per relay runtime). Not federation: MeshMembership::apply_ready_records admits a peer only when its relay_pubkey equals this deployment's own, so two independent relays can never mesh (meridian-fxj6)
meridian-push-gateway	Stateful, capability-gated APNs last hop for NIP-PL
meridian-control-plane	Hosted-community control plane — sessions, Nostr identity binding, community provisioning via the relay operator API. Has its own AGENTS.md
meridian-conformance	Runtime trace schema + replay checker for docs/spec/MultiTenantRelay.tla. check_trace/check_step have no call sites outside this crate's own tests — the relay emits no traces into it, so it verifies fixtures, not the running system (meridian-hoos)
meridian-acp	ACP harness bridging events to AI agents (pool, queue, relay bridge)
meridian-agent	Minimal ACP-compliant agent (non-streaming, tool-calls-as-output)
meridian-dev-mcp	Developer MCP server — shell + file-edit tools for meridian-agent
meridian-persona	Agent persona packs
meridian-workflow	Channel-scoped YAML-as-code workflow engine (evalexpr conditions)
meridian-pair-relay	Ephemeral sidecar relay for NIP-AB device pairing (kind 24134 matching)
meridian-pairing-cli	CLI for NIP-AB pairing interop testing
git-sign-nostr	Sign git objects with a Nostr key
git-credential-nostr	Git credential helper for Nostr-authed push/fetch
meridian-cli	Agent-first CLI (meridian)
meridian-sdk	Typed Nostr event builders
meridian-admin	Operator CLI for relay administration
meridian-ws-client	Shared NIP-42 WebSocket client (connect, auth, publish)
meridian-openapi	Vendored Scalar renderer + the reference page both HTTP services serve. Has its own AGENTS.md
meridian-test-client	Integration test client and E2E suite
meridian-harness	All-in-one harness bundling ACP, agent, and dev MCP

Local Contracts

• Kinds are declared before they are handled. Add the integer to meridian-core/src/kind.rs, then implement handling in meridian-relay. No crate may invent a kind integer locally.
• Channel scoping uses h tags (NIP-29 group tag), never e tags. Filters and queries inside a channel must scope on h.
• Prefer a new event kind over a new HTTP endpoint. The HTTP surface is reserved for Blossom media, webhooks, git smart HTTP, NIP-11/NIP-05, health probes, and the generic bridge (POST /events, /query, /count).
• No unsafe. No exceptions.
• No new unwrap() / expect() in production paths — use ? and a real error type. Tests may unwrap.
• New public API carries doc comments. Crate-level //! docs state the mental model; keep them true when behavior changes.
• Library crates stay framework-free where they already are (e.g. meridian-media has no Axum dependency) — put handlers in meridian-relay.

Work Guidance

• Agent-facing operations belong in meridian-cli first (subcommand + client.rs wiring), not in a new relay endpoint.
• Thread counters (reply_count, descendant_count) are materialized on the thread root; any new reply-insert path must maintain them — copy an existing reply handler.
• Keep workflow conditions simple and testable; meridian-workflow evaluates them with evalexpr.
• Reference the NIPs when shaping protocol work: https://github.com/nostr-protocol/nips. Repo-local extensions live in docs/nips/.

Verification

just fmt-check          # cargo fmt --all -- --check
just clippy             # cargo clippy --workspace --all-targets -- -D warnings
just test-unit          # no infrastructure required
just test               # full suite — needs Postgres + Redis (scripts/run-tests.sh)

just test is required when touching meridian-relay, meridian-db, or meridian-auth. Clippy passing does not mean fmt passes — run both.

Child STELLAR Index

• meridian-core/AGENTS.md — kind registry, event verification, filter matching, shared types
• meridian-relay/AGENTS.md — relay server: connection lifecycle, handlers, HTTP API surface
• meridian-db/AGENTS.md — Postgres data access, partitioning, replica fence, embedded migrator
• meridian-acp/AGENTS.md — ACP harness: pool, queue, relay bridge, setup mode
• meridian-agent/AGENTS.md — minimal ACP agent: providers, MCP wiring, handoff
• meridian-cli/AGENTS.md — agent-first CLI contracts (output shapes, exit codes, flags)
• meridian-control-plane/AGENTS.md — hosted-community provisioning: sign-in, identity binding, ownership
• meridian-openapi/AGENTS.md — vendored Scalar renderer and the API reference pages it serves
• meridian-test-client/AGENTS.md — integration + E2E suite

Crates without a child doc are governed by this file.