1  # AGENTS.md + CLAUDE.md
  2  
  3  ## Session Initialization
  4  
  5  **IMPORTANT**: When starting any session, immediately:
  6  1. Enter the Nix environment if not already in the shell: `nix develop`
  7  3. Read `.claude/skills/aura-quick-ref/SKILL.md` for enhanced context
  8  
  9  ## Project Overview
 10  
 11  Aura is a threshold identity and encrypted storage platform built on relational security principles. It uses threshold cryptography and social recovery to eliminate the traditional choice between trusting a single device or a centralized entity.
 12  
 13  **Architecture**: Choreographic programming with session types for coordinating distributed protocols. Uses algebraic effects for modular runtime composition. The `docs/` directory is the **primary, authoritative spec**; `work/` is non-authoritative scratch and may be removed.
 14  See `docs/001_system_architecture.md` and `docs/999_project_structure.md` for the latest crate breakdown.
 15  
 16  ## Development Setup
 17  
 18  **Required**: Nix with flakes enabled
 19  
 20  ```bash
 21  nix develop                           # Enter development shell
 22  # OR
 23  echo "use flake" > .envrc && direnv allow  # Auto-activate with direnv
 24  ```
 25  
 26  All commands below must be run within `nix develop`.
 27  
 28  ## Common Commands
 29  
 30  ### Build & Check
 31  - `just build` - Build all crates
 32  - `just check` - Check without building
 33  - `just fmt` - Format code
 34  - `just fmt-check` - Check formatting
 35  - `just clippy` - Lint (warnings as errors)
 36  
 37  ### Hermetic Builds (crate2nix)
 38  - `nix build` - Build with hermetic Nix (reproducible)
 39  - `nix build .#aura-terminal` - Build specific package
 40  - `nix run` - Run aura CLI hermetically
 41  - `nix flake check` - Run hermetic tests
 42  - `crate2nix generate` - Regenerate Cargo.nix after dependency changes
 43  
 44  ### Testing
 45  - `just test` - Run all tests (preferred)
 46  - `just test-crate <name>` - Test specific crate
 47  - `just ci-dry-run` - Local CI checks (format, lint, test)
 48  - `just smoke-test` - Phase 0 integration tests
 49  - `cargo test --workspace -- --nocapture` - Tests with output
 50  
 51  ### Development Workflow
 52  - `just watch` - Rebuild on changes
 53  - `just watch-test` - Retest on changes
 54  - `just clean` - Clean artifacts
 55  - `just docs` - Generate documentation
 56  
 57  ### Phase 0 Demo
 58  - `just init-account` - Initialize 2-of-3 threshold account
 59  - `just status` - Show account status
 60  
 61  ## Architecture Essentials
 62  
 63  ### 8-Layer Architecture
 64  
 65  The codebase follows a strict 8-layer architecture with zero circular dependencies:
 66  
 67  1. **Foundation** (`aura-core`): Effect traits (crypto, network, storage, unified time system, journal, console, random, transport), domain types (`AuthorityId`, `ContextId`, `SessionId`, `FlowBudget`), cryptographic utilities (FROST, merkle trees), semilattice traits, unified errors (`AuraError`), and reliability utilities. Other crates depend on `aura-core`, but it depends on none of them.
 68  
 69  2. **Specification** (Domain Crates + `aura-mpst` + `aura-macros`):
 70     - Domain crates (`aura-journal`, `aura-authorization`, `aura-signature`, `aura-store`, `aura-transport`): CRDT domains, capability systems, transport semantics. `aura-journal` now exposes fact-based journals and reduction pipelines (`docs/102_journal.md`, `docs/111_maintenance.md`).
 71     - `aura-mpst`: Session type runtime with guard extensions and leakage tracking (`LeakageTracker`).
 72     - `aura-macros`: Choreography DSL parser/annotation extractor (`guard_capability`, `flow_cost`, `journal_facts`, `leak`) that emits rumpsteak projections.
 73  
 74  3. **Implementation** (`aura-effects` + `aura-composition`): Stateless, single-party handlers (`aura-effects`) and handler composition infrastructure (`aura-composition`). Production handlers implement core effect traits (crypto, network, storage, randomness, console, etc.). Mock/test handlers are in `aura-testkit`.
 75     - **Unified encryption-at-rest**: `aura-effects::EncryptedStorage` wraps `StorageEffects` and persists the master key via `SecureStorageEffects` (Keychain/TPM/Keystore; filesystem fallback during bring-up). Application code should not implement ad-hoc storage encryption (e.g., `LocalStore`).
 76  
 77  4. **Orchestration** (`aura-protocol` + `aura-guards`, `aura-consensus`, `aura-amp`, `aura-anti-entropy`): Multi-party coordination and guard infrastructure: handler adapters, CrdtCoordinator, GuardChain (CapGuard → FlowGuard → JournalCoupler), Consensus runtime, AMP orchestration, anti-entropy/snapshot helpers.
 78  
 79  5. **Feature/Protocol** (`aura-authentication`, `aura-chat`, `aura-invitation`, `aura-recovery`, `aura-relational`, `aura-rendezvous`, `aura-social`, `aura-sync`): End-to-end protocol crates (auth, secure messaging, guardian recovery, rendezvous, social topology, storage, etc.) built atop the orchestration layer. `aura-frost` is deprecated; FROST primitives live in `aura-core::crypto::tree_signing`.
 80  
 81  6. **Runtime Composition** (`aura-agent`, `aura-simulator`, `aura-app`): Runtime assembly of effect systems (agent), deterministic simulation (simulator), and portable application core (app). `aura-agent` now owns the effect registry/builder infrastructure; `aura-protocol` no longer exports the legacy registry. `aura-app` provides the platform-agnostic business logic consumed by all frontends.
 82  
 83  7. **User Interface** (`aura-terminal`): Terminal-based CLI and TUI entry points. Imports only from `aura-app` (never `aura-agent` directly). Uses `AppCore` as the unified backend interface for all operations. Exposes scenario/admin/recovery/invitation flows plus authority/context inspection commands.
 84  
 85  8. **Testing & Tools** (`aura-testkit`, `aura-quint`): Shared fixtures, simulation harnesses, property tests, Quint interop.
 86  
 87  ### Layer 5 Conventions
 88  - Each Layer 5 crate includes `ARCHITECTURE.md` describing facts, invariants, and operation categories.
 89  - Each Layer 5 crate exposes `OPERATION_CATEGORIES` mapping operations to A/B/C classes.
 90  - Runtime-owned caches (e.g., invitation/rendezvous descriptors) must live in Layer 6 handlers.
 91  - Layer 5 facts use versioned binary encoding (bincode) with JSON fallback for debug; bump per-crate schema constants on breaking changes.
 92  - FactKey helper types are required for reducers/views to avoid ad-hoc key drift.
 93  - Ceremony facts include optional `trace_id` for correlation (typically set to the ceremony id).
 94  
 95  **Where does my code go?** See the docs under `docs/001_system_architecture.md` and `docs/100_authority_and_identity.md` for the latest authority-centric guidance.
 96  
 97  ## Architecture Essentials (Authority Model)
 98  
 99  Aura now models identity via opaque authorities (`AuthorityId`) and relational contexts (`ContextId`). Key points:
100  
101  - commitment tree updates and device membership are expressed as fact-based AttestedOps (`aura-journal/src/fact.rs`). No graph-based `journal_ops` remain.
102  - Relational contexts (guardian bindings, recovery grants, rendezvous receipts) live in their own journals (`docs/103_relational_contexts.md`).
103  - Aura Consensus is the sole strong-agreement mechanism (`docs/104_consensus.md`). Fast path + fallback gossip integrate with the guard chain.
104  - Guard chain sequence: `AuthorizationEffects` (Biscuit/capabilities) → `FlowBudgetEffects` (charge-before-send) → `LeakageEffects` (`docs/003_information_flow_contract.md`) → `JournalEffects` (fact commit) → `TransportEffects`.
105  - Flow budgets: only the `spent` counters are facts; limits are derived at runtime from Biscuit + policy.
106  - **Hybrid journal model**: fact journal (join) + capability frontier (meet) combined as `JournalState` for effects/runtime use.
107  - **Transaction Model**: Database operations coordinate via two orthogonal dimensions: (1) Authority Scope (Single vs Cross-authority) and (2) Agreement Level (Monotone/CRDT vs Consensus). Monotone operations use CRDT merge (0 RTT). Non-monotone operations use consensus (1-3 RTT). Cross-authority operations work with both. Consensus is NOT linearizable - use session types for operation sequencing. See `docs/113_database.md` §8.
108  
109  ## Threshold Lifecycle Taxonomy
110  
111  Aura separates **key generation** from **agreement/finality**:
112  - **K1**: Local/Single‑Signer (no DKG)
113  - **K2**: Dealer‑Based DKG (trusted coordinator)
114  - **K3**: Quorum/BFT‑DKG (consensus‑finalized transcript)
115  
116  Agreement modes are orthogonal:
117  - **A1**: Provisional (usable immediately, not final)
118  - **A2**: Coordinator Soft‑Safe (bounded divergence + convergence cert)
119  - **A3**: Consensus‑Finalized (unique, durable, non‑forkable)
120  
121  Leader selection and pipelining are **orthogonal optimizations**, not agreement modes. Fast paths (A1/A2) must be explicitly marked provisional and superseded by A3 for durable shared state.
122  
123  ## Distributed Systems Contract
124  
125  See `docs/004_distributed_systems_contract.md` for the distributed-systems guarantees (safety, liveness, partial synchrony assumptions, latency expectations, adversarial models, and monitoring guidance).
126  
127  ## Information Flow / Privacy
128  
129  Reference `docs/003_information_flow_contract.md` for the unified flow-budget/metadata-leakage contract. Key notes:
130  - Charge-before-send invariant enforced by FlowGuard + JournalCoupler.
131  - Receipts propagate via relational contexts (`docs/108_transport_and_information_flow.md`).
132  - Leakage budgets tracked via `LeakageEffects` and choreography annotations.
133  
134  ## Authorization Systems
135  
136  1. **Traditional Capability Semantics** (`aura-authorization`): Meet-semilattice capability evaluation for local checks.
137  2. **Biscuit Tokens** (`aura-authorization/src/biscuit/`, `aura-guards/src/authorization.rs`): Cryptographically verifiable, attenuated tokens.
138  3. **Guard Integration**: `aura-guards::{CapGuard, FlowGuard, JournalCoupler, LeakageTracker}` enforce Biscuit/policy requirements, flow budgets, journal commits, and leakage budgets per message.
139  
140  ## Unified Time System
141  
142  Aura uses a unified `TimeStamp` with domain-specific traits; legacy `TimeEffects`/chrono use is forbidden in application code.
143  
144  1. **PhysicalTimeEffects** (`aura-core/src/effects/time.rs`): Wall-clock time for timestamps, expiration, cooldowns, receipts.
145  2. **LogicalClockEffects**: Vector + Lamport clocks for causal ordering (CRDT/session happens-before).
146  3. **OrderClockEffects**: Privacy-preserving total ordering tokens with no temporal meaning.
147  4. **TimeAttestationEffects**: Optional provenance/consensus proof wrapper around `TimeStamp` when attested time is required.
148  
149  **TimeStamp Variants** (`aura-core/src/time.rs`):
150  - `PhysicalClock(PhysicalTime)`: ms since UNIX epoch + optional uncertainty
151  - `LogicalClock(LogicalTime)`: vector + Lamport clocks for causality  
152  - `OrderClock(OrderTime)`: Opaque 32-byte tokens for deterministic ordering without leakage
153  - `Range(RangeTime)`: Validity windows/constraints (compose with PhysicalClock)
154  
155  **Key Principles**:
156  - Domain separation: choose Physical/Logical/Order/Range based on semantics
157  - Privacy: OrderClock leaks no timing; provenance is orthogonal via attestation
158  - Effect integration: all time access via traits; no direct `SystemTime::now()`/chrono outside handlers
159  - Explicit ordering: use `TimeStamp::compare(policy)` for cross-domain comparisons
160  
161  ## Documentation Map
162  
163  - Core overview: `docs/000_project_overview.md`
164  - Theoretical model: `docs/002_theoretical_model.md`
165  - Architecture: `docs/001_system_architecture.md`
166  - Privacy: `docs/003_information_flow_contract.md`
167  - Distributed systems contract: `docs/004_distributed_systems_contract.md`
168  - Authority/Relational identity: `docs/100_authority_and_identity.md`, `docs/103_relational_contexts.md`
169  - Consensus & BFT-DKG: `docs/104_consensus.md`
170  - Transport/receipts: `docs/108_transport_and_information_flow.md`, `docs/110_rendezvous.md`
171  - AMP messaging: `docs/112_amp.md`
172  - Developer guides: `docs/107_mpst_and_choreography.md`, `docs/106_effect_system_and_runtime.md`
173  - Cryptography & VSS: `docs/116_crypto.md`
174  - Key rotation ceremonies: `docs/118_key_rotation_ceremonies.md`
175  - Reference: `docs/999_project_structure.md`
176  
177  ## Agent Quick Reference
178  
179  ### "Where does my code go?" Decision Tree
180  - **Single-party stateless operation** → `aura-effects`
181  - **Multi-party coordination** → `aura-protocol` + Layer 4 subcrates (`aura-guards`, `aura-consensus`, `aura-amp`, `aura-anti-entropy`)
182  - **Domain-specific logic** → Domain crate (`aura-journal`, etc.)
183  - **Domain service handler (stateless)** → Domain crate `*FactService` (e.g., `aura-chat::ChatFactService`)
184  - **RwLock wrapper service** → `aura-agent/src/handlers/*_service.rs`
185  - **Complete end-to-end protocol** → Feature crate (e.g., `aura-authentication`; `aura-frost` deprecated)
186  - **Effect trait definition** → `aura-core`
187  - **Mock/test handlers** → `aura-testkit`
188  
189  ### Common Development Tasks → Docs
190  - **Adding new effect trait**: `docs/106_effect_system_and_runtime.md` → `docs/805_development_patterns.md`
191  - **Building choreography**: `docs/107_mpst_and_choreography.md` → `docs/803_coordination_guide.md`
192  - **Understanding authorities**: `docs/100_authority_and_identity.md` → `docs/102_journal.md`
193  - **Debugging architecture**: `docs/999_project_structure.md` + `just check-arch`
194  - **Implementing consensus**: `docs/104_consensus.md` → `crates/aura-consensus/src/consensus/`
195  - **Working with journals**: `docs/102_journal.md` → `aura-journal/src/`
196  - **Creating recovery flows**: `docs/103_relational_contexts.md` → `aura-recovery/`
197  
198  ### Architecture Compliance Checklist
199  - [ ] Layer dependencies flow downward only (see dependency graph in `docs/999_project_structure.md`)
200  - [ ] Effect traits defined in `aura-core` only
201  - [ ] Infrastructure effects implemented in `aura-effects`
202  - [ ] Application effects in domain crates
203  - [ ] No direct impure function usage outside effect implementations
204  - [ ] All async functions propagate `EffectContext`
205  - [ ] Production handlers are stateless, test handlers in `aura-testkit`
206  
207  ### Layer-Based Development Workflow
208  - **Working on Layer 1 (Foundation)?** Read: `docs/106_effect_system_and_runtime.md`
209  - **Working on Layer 2 (Domains)?** Read: Domain-specific docs (`docs/100-112`)
210  - **Working on Layer 3 (Effects)?** Read: `docs/805_development_patterns.md`
211  - **Working on Layer 4 (Protocols)?** Read: `docs/107_mpst_and_choreography.md`
212  - **Working on Layer 5 (Features)?** Read: `docs/803_coordination_guide.md`
213  - **Working on Layer 6 (Runtime)?** Read: `aura-agent/` and `aura-simulator/`
214  - **Working on Layer 7 (Terminal)?** Read: `aura-terminal/` + `aura-app/` + scenario docs
215  - **Working on Layer 8 (Testing)?** Read: `docs/805_testing_guide.md`
216  
217  ### Task-Oriented Crate Selection
218  
219  #### "I'm implementing..."
220  - **A new hash function** → `aura-core` (pure function) + `aura-effects` (if OS integration needed)
221  - **Cryptographic operations** → Use effect traits; see `docs/116_crypto.md` for layer rules
222  - **FROST primitives** → `aura-core::crypto::tree_signing`; `aura-frost` deprecated
223  - **Guardian recovery flow** → `aura-recovery`
224  - **Journal fact validation** → `aura-journal`
225  - **Network transport** → `aura-transport` (abstractions) + `aura-effects` (TCP implementation)
226  - **CLI command** → `aura-terminal`
227  - **Test scenario** → `aura-testkit`
228  - **Choreography protocol** → Feature crate + `aura-mpst`
229  - **Authorization logic** → `aura-authorization`
230  - **Social topology/relay selection** → `aura-social`
231  - **Quint specification** → `verification/quint/` + `docs/807_verification_guide.md`
232  - **Generative test** → `aura-simulator/src/quint/` + `docs/809_generative_testing_guide.md`
233  
234  #### "I need to understand..."
235  - **How authorities work** → `docs/100_authority_and_identity.md`
236  - **How consensus works** → `docs/104_consensus.md`
237  - **How effects compose** → `docs/106_effect_system_and_runtime.md`
238  - **How protocols are designed** → `docs/107_mpst_and_choreography.md`
239  - **How the guard chain works** → `docs/001_system_architecture.md` (sections 2.1-2.3)
240  - **How crypto architecture works** → `docs/116_crypto.md` + `just check-arch --crypto`
241  - **How journals work** → `docs/102_journal.md`
242  - **How the query system works** → `docs/113_database.md` (Datalog queries, isolation levels, statistics)
243  - **How testing works** → `docs/805_testing_guide.md` + `docs/806_simulation_guide.md`
244  - **How to write tests** → `docs/805_testing_guide.md`
245  - **How privacy and flow budgets work** → `docs/003_information_flow_contract.md`
246  - **How distributed system guarantees work** → `docs/004_distributed_systems_contract.md`
247  - **How commitment trees work** → `docs/101_accounts_and_commitment_tree.md`
248  - **How relational contexts work** → `docs/103_relational_contexts.md`
249  - **How transport and receipts work** → `docs/108_transport_and_information_flow.md`
250  - **How rendezvous and peer discovery work** → `docs/110_rendezvous.md`
251  - **How social topology and homes work** → `docs/114_social_architecture.md`
252  - **How state reduction works** → `docs/120_state_reduction.md`
253  - **How the mathematical model works** → `docs/002_theoretical_model.md`
254  - **How identifiers and boundaries work** → `docs/105_identifiers_and_boundaries.md`
255  - **How authorization and capabilities work** → `docs/109_authorization.md`
256  - **How Biscuit tokens work** → `docs/109_authorization.md` + `aura-authorization/src/biscuit/`
257  - **How to get started as a new developer** → `docs/801_hello_world_guide.md`
258  - **How core systems work together** → `docs/802_core_systems_guide.md`
259  - **How to design advanced protocols** → `docs/804_advanced_coordination_guide.md`
260  - **How simulation works** → `docs/806_simulation_guide.md`
261  - **How verification works** → `docs/807_verification_guide.md` (Quint specs + Lean proofs)
262  - **How generative testing works** → `docs/809_generative_testing_guide.md`
263  - **How maintenance and OTA updates work** → `docs/808_maintenance_guide.md` + `docs/111_maintenance.md`
264  - **How development patterns work** → `docs/805_development_patterns.md`
265  - **The project's goals and constraints** → `docs/000_project_overview.md`
266  
267  ## Legacy Cleanup Status
268  
269  - Graph-based `journal_ops` directory removed; guard/tests now track fact deltas.
270  - `DeviceMetadata`/`DeviceType`/`DeviceRegistry` removed - device information now derived from `LeafNode` in commitment tree (`aura-core/src/tree/types.rs`). Device views are obtained via `TreeEffects::get_current_state()`.
271  
272  ## Usage Efficiency Guidelines
273  
274  To conserve agent usage, prefer:
275  - Specific file paths over broad searches when known
276  - Targeted grep patterns over reading entire files
277  - Architecture compliance (`just check-arch`) before complex refactoring
278  - Quick reference skills over re-reading documentation
279  - Batch operations and parallel tool calls when possible
280  - Use `.claude/skills/` for project-specific knowledge
281  - Note: `work/` is ignored; do not commit files from this directory