cougr-core 1.0.0

# Architecture

High-level overview of how Cougr is organized. For usage, see [README.md](README.md).

## Layers

```
┌─────────────────────────────────────────────┐
│               app::GameApp                   │  Default runtime surface
├───────────┬───────────────┬─────────────────┤
│  ECS      │  Accounts     │  Standards      │  ZK Proofs
├───────────┼───────────────┼─────────────────┼─────────────────┤
│  soroban-sdk 25.1.0  (no_std, WASM)         │
└─────────────────────────────────────────────┘
```

**GameApp** (`src/plugin/mod.rs`) is the default onboarding layer. It owns a `SimpleWorld`,
the scheduler, plugin registration, and runtime resources in one place.

**GameWorld** (`src/game_world.rs`) remains available as a higher-level Beta integration
wrapper for combining ECS, auth, and proof submission, but it is not the primary
learning path for new users.

## ECS

Two storage backends, same `ComponentTrait` interface:

| Backend | File | Strategy | Best for |
|---|---|---|---|
| **SimpleWorld** | `src/simple_world/` | `Map<(EntityId, Symbol), Bytes>` with dual Table/Sparse indexes | General use, small entity counts |
| **ArchetypeWorld** | `src/archetype_world/` | Groups entities by component signature | Large entity counts, batch queries |

Both support typed access (`get_typed<T>`, `set_typed<T>`) and raw access (`get_component`, `add_component`).

Supporting systems:

- **Query cache** (`src/query/`) — version-tagged, invalidates on world mutation
- **Hooks** (`src/hooks.rs`) — callbacks on component add/remove
- **Observers** (`src/observers.rs`) — event-driven reactions
- **Commands** (`src/commands.rs`) — deferred mutations during system execution
- **Scheduler** (`src/scheduler/`) — stage-based, dependency-aware system ordering
- **Change tracker** (`src/change_tracker.rs`) — per-component dirty flags
- **Plugins** (`src/plugin/`) — modular game logic bundles
- **Incremental storage** (`src/incremental/`) — only persist dirty entities

### Component definition

The `impl_component!` macro generates `ComponentTrait` (serialize/deserialize/type symbol) from a struct definition. Supported field types: `i32`, `u32`, `i64`, `u64`, `i128`, `u128`, `u8`, `bool`, `bytes32`.

## ZK Proofs (`src/zk/`)

All ZK operations use Stellar Protocol 25 (X-Ray) host functions — the heavy crypto runs on the host, not in WASM.

- **Groth16** (`groth16.rs`) — proof verification via BN254 pairing
- **BLS12-381** (`bls12_381.rs`) — G1 add/mul/MSM, pairing checks
- **Poseidon2** (`crypto.rs`) — ZK-friendly hashing, behind `hazmat-crypto` feature
- **Merkle trees** (`merkle/`) — SHA256 and Poseidon variants, sparse trees, on-chain proofs
- **Pedersen** (`commitment.rs`) — commitment scheme for hidden state
- **Game circuits** (`circuits.rs`, `traits.rs`) — `GameCircuit` trait + pre-built circuits (Movement, Combat, Inventory, TurnSequence) + `CustomCircuitBuilder`
- **ECS integration** (`components.rs`, `systems.rs`) — `CommitReveal`, `HiddenState`, `ProofSubmission` components with verification systems

## Accounts (`src/accounts/`)

Account abstraction layer with pluggable implementations:

```
CougrAccount (trait)
├── ClassicAccount      — standard Stellar keypair
└── ContractAccount     — smart contract wallet
     ├── SessionStorage — persistent session keys
     ├── RecoveryStorage — guardian-based recovery
     ├── DeviceStorage  — multi-device key management
     └── Secp256r1Storage — WebAuthn/Passkey keys
```

Key traits: `CougrAccount`, `SessionKeyProvider`, `RecoveryProvider`, `MultiDeviceProvider`.

`SessionBuilder` provides a fluent API for constructing scoped session keys. `authorize_with_fallback` handles graceful degradation from session keys to direct authorization.

## Standards (`src/standards/`)

Reusable contract standards for integrations that need explicit operational controls:

- `Ownable` and `Ownable2Step` for owner-managed authority
- `AccessControl` for role-based authorization with delegated admins
- `Pausable` for emergency stops
- `ExecutionGuard` for serialized critical sections
- `RecoveryGuard` for blocking sensitive paths during recovery windows
- `BatchExecutor` for bounded multi-operation flows
- `DelayedExecutionPolicy` for time-delayed operation queues

Each standard instance is keyed by a caller-supplied `Symbol`, which keeps storage deterministic and avoids collisions when a contract composes multiple modules.

## Feature Flags

| Flag | Enables |
|---|---|
| `hazmat-crypto` | Poseidon2 hash, BN254 curve ops (via `soroban-sdk/hazmat-crypto`) |
| `testutils` | `MockAccount`, test helpers (via `soroban-sdk/testutils`) |
| `debug` | Runtime introspection, metrics, state snapshots (`src/debug/`) |

## Build

Release builds are configured with LTO, `opt-level = "z"`, and `overflow-checks = true` to keep artifacts optimized for constrained execution environments.

Primary target: `wasm32v1-none`.