mirror of
https://github.com/Heretek-AI/AetherTable.git
synced 2026-10-12 02:02:28 +00:00
docs: honesty sync to post-loop-2 reality (iteration 92)
Counts verified against tree: cargo 461/21, pytest 1035 collected (1006 pass/29 skip), vitest 407/33 + relay 66/4. Feature claims grep-verified before writing; stale spell-enrichment figure corrected 73→82 by running enrich_compendium directly. All documented commands resolve as written. Co-Authored-By: Claude <[email protected]>
This commit is contained in:
John Smith
@@ -51,7 +51,9 @@ PYTHONPATH=python pytest python/tests -v
|
||||
|
||||
### Client Build & Typecheck
|
||||
```bash
|
||||
cd client && npm run build
|
||||
cd client && npm run build # tsc typecheck + vite build
|
||||
npm run test # Vitest unit suite (407 tests across 33 files)
|
||||
npx vitest run --config vitest.relay.config.mjs # relay unit suite (66 tests in scripts/__tests__)
|
||||
```
|
||||
|
||||
### Generate SRD Compendiums from Markdown
|
||||
@@ -63,8 +65,8 @@ PYTHONPATH=python python3 -m vtt_orchestrator.compendium.srd_importer
|
||||
|
||||
## 4. Codebase Navigation Map
|
||||
|
||||
* **`crates/vtt-core/`**: D&D 5e SRD 5.1 rules, 15 conditions, attack & saving throw resolvers, concentration checks, death save state machine, 4-tier task resolution.
|
||||
* **`crates/vtt-spatial/`**: Bresenham LoS raycasting, half/three-quarters/total cover, A* pathfinding.
|
||||
* **`crates/vtt-core/`**: D&D 5e SRD 5.1 rules, 15 conditions, attack & saving throw resolvers, concentration checks, death save state machine, dice notation parsing (`kh`/`kl`, `ro` reroll-once, exploding), opportunity attacks with Disengage suppression, Ready actions with structured `ReadiedTrigger`s, inspiration lifecycle, hit-dice short rests, and the exhaustion ladder.
|
||||
* **`crates/vtt-spatial/`**: Bresenham LoS raycasting, half/three-quarters/total cover, lighting zones & vision modes, visibility polygons (`visibility.rs`), A* pathfinding.
|
||||
* **`crates/vtt-wfc/`**: Wave Function Collapse procedural map & dungeon synthesis.
|
||||
* **`crates/vtt-crdt-sync/`**: Real-time Yjs CRDT relay server (default transport via HMAC-authenticated upgrade; falls back to the engine LWW relay).
|
||||
* **`crates/vtt-scripting/`**: Sandboxed Rhai and Wasmtime execution engines with an absolute 1,000,000-fuel ceiling (`MAX_FUEL_CEILING`; client-requested limits are clamped, never raised) and a max-operation cap on Rhai.
|
||||
|
||||
@@ -14,14 +14,14 @@ This repository contains the **AI-Native Virtual Tabletop (VTT)** system. Use th
|
||||
### Rust Engine (`crates/`)
|
||||
```bash
|
||||
cargo build --workspace
|
||||
cargo test --workspace # 235 tests across 18 suites
|
||||
cargo test --workspace # 461 tests across 21 suites
|
||||
cargo test -p vtt-core --test srd_rules_tests
|
||||
```
|
||||
|
||||
### Python Orchestrator (`python/`)
|
||||
```bash
|
||||
# Run pytest with PYTHONPATH
|
||||
PYTHONPATH=python pytest python/tests -v # ~580 collected tests (engine-live and live-LLM suites skip when unset)
|
||||
PYTHONPATH=python pytest python/tests -v # 1035 collected (1006 pass, 29 skip; engine-live and live-LLM suites skip when unset)
|
||||
|
||||
# Run a specific test module
|
||||
PYTHONPATH=python pytest python/tests/test_srd_importer.py -k test_srd_spell_parser
|
||||
@@ -33,7 +33,8 @@ cd client
|
||||
npm install
|
||||
npm run build # Typechecks via tsc and runs vite build (typically well under 15s)
|
||||
npm run dev # Starts Vite dev server on http://localhost:3000
|
||||
npm run test # Vitest unit suite (69 tests across 4 files)
|
||||
npm run test # Vitest unit suite (407 tests across 33 files)
|
||||
npx vitest run --config vitest.relay.config.mjs # relay unit suite (66 tests in scripts/__tests__)
|
||||
```
|
||||
|
||||
---
|
||||
@@ -63,8 +64,8 @@ npm run test # Vitest unit suite (69 tests across 4 files)
|
||||
## 🛡️ Invariant Checklists
|
||||
|
||||
Before finalizing changes:
|
||||
- [ ] All Rust crates compile cleanly with 0 errors; `cargo test --workspace` passes (235 tests across 18 suites).
|
||||
- [ ] `PYTHONPATH=python pytest python/tests` passes (~580 collected tests; the engine-live and live-LLM suites skip when unset).
|
||||
- [ ] `cd client && npm run test` passes (69 Vitest tests across 4 files).
|
||||
- [ ] All Rust crates compile cleanly with 0 errors; `cargo test --workspace` passes (461 tests across 21 suites).
|
||||
- [ ] `PYTHONPATH=python pytest python/tests` passes (1035 collected tests; the engine-live and live-LLM suites skip when unset).
|
||||
- [ ] `cd client && npm run test` passes (407 Vitest tests across 33 files), plus the relay suite (`npx vitest run --config vitest.relay.config.mjs`, 66 tests).
|
||||
- [ ] Synthetic playtest benchmark achieves MCR ≥ 98.5%, HCI ≥ 0.95, AFPR ≤ 1.5%, auditor recall ≥ 95% (`./scripts/run_all_benchmarks.sh`).
|
||||
- [ ] `cd client && npm run build` completes in under 15s with zero TypeScript diagnostics.
|
||||
|
||||
@@ -165,9 +165,9 @@ Gates enforced by `scripts/run_all_benchmarks.sh` and CI:
|
||||
| **Hallucination & Continuity Index (HCI)** | $\ge 0.95$ |
|
||||
| **Auditor False-Positive Rate (AFPR)** | $\le 1.5\%$ |
|
||||
| **Auditor Recall** (lethal-narrative probes) | $\ge 95\%$ |
|
||||
| **Rust Test Suite** (`cargo test --workspace`) | all pass (235 tests) |
|
||||
| **Python Test Suite** (`PYTHONPATH=python pytest python/tests`) | all pass (~580 collected; engine-live and live-LLM suites gate/skip when unset) |
|
||||
| **Client Unit Tests** (`npx vitest run`) | all pass (69 tests) |
|
||||
| **Rust Test Suite** (`cargo test --workspace`) | all pass (461 tests) |
|
||||
| **Python Test Suite** (`PYTHONPATH=python pytest python/tests`) | all pass (1035 collected; 1006 pass, 29 skip — engine-live and live-LLM suites gate/skip when unset) |
|
||||
| **Client Unit Tests** (`npx vitest run`) | all pass (407 tests across 33 files; plus the relay suite via `vitest.relay.config.mjs`, 66 tests) |
|
||||
| **Client Production Build** (`npm run build`) | zero TypeScript errors |
|
||||
|
||||
Latest full local run (2026-08-24, `./scripts/run_all_benchmarks.sh`, 200 turns against a live engine): MCR 100%, HCI 1.00, AFPR 0.0%, auditor recall 100% (15/15 probes), trust-boundary probes 7/7 rejected; measured latency SLA: rules 0.39ms p50, spatial ~0.35ms, intent keyword 1.10ms. These are synthetic self-play results against a scripted playtester; they are not a claim about arbitrary homebrew content.
|
||||
@@ -178,7 +178,9 @@ Latest full local run (2026-08-24, `./scripts/run_all_benchmarks.sh`, 200 turns
|
||||
|
||||
**Real and exercised today:**
|
||||
- **Engine-authoritative rules**: server-side attack/cast/move/death-save resolution in `vtt-core` with ids-only payloads (`deny_unknown_fields`), action budgets, condition lifecycle timers, spell slot deduction, concentration checks, reaction stack, and safety rewind with full state replay.
|
||||
- **Full SRD combat maneuver suite**: grapple/shove contested checks with reach and economy gates, two-weapon fighting, and the Help action — wired end-to-end through engine, gateway, and client (with rewind on contested-action failure).
|
||||
- **Full SRD combat maneuver suite**: grapple/shove contested checks with reach and economy gates, two-weapon fighting, the Help action, opportunity attacks (with Disengage suppression), and Ready actions with structured triggers (`ReadiedTrigger` variants; trigger resolution stays GM-adjudicated) — wired end-to-end through engine, gateway, and client (with rewind on contested-action failure).
|
||||
- **Player-facing resource systems**: inspiration (award/spend lifecycle wired on the wire), hit-dice short rests, and the 6-level exhaustion ladder in `vtt-core`.
|
||||
- **Dice notation**: `kh`/`kl` keep-drop, `ro` reroll-once, and exploding dice parsed in `vtt-core/src/dice.rs` (unit-tested in `dice_notation_tests.rs`).
|
||||
- **RBAC at every tier**: role claims in gateway tokens (legacy no-role tokens default to Player), entity ownership enforcement, spectator restrictions, fog-layer ownership, owner-or-GM guards on privileged session routes, GM-only monster spawns, and **wire-level relay RBAC** — hidden tokens, spectator ingress, private fog, and role-projected initial-state snapshots enforced inside the Rust WS relay.
|
||||
- **WFC dungeons**: real solver with reseed retries, wildcard sockets, flood-fill single-region guarantee, deterministic dressing — and a client studio that generates real maps through an engine proxy (no fabricated previews).
|
||||
- **AI orchestrator with live LLM support**: tool-calling agent (`agents/tool_agent.py`) plus streaming narrative against any OpenAI-compatible endpoint configured via `.env` (`LLM_API`/`LLM_KEY`/`LLM_MODEL`); audited-before-yield streaming with honest degradation when no key is present, plus an opt-in live-LLM test suite.
|
||||
@@ -187,15 +189,19 @@ Latest full local run (2026-08-24, `./scripts/run_all_benchmarks.sh`, 200 turns
|
||||
- **Handouts & campaign autosave**: role-enforced handout persistence (create/read/update with owner + role checks) and GM campaign autosave from live engine state, both fail-closed on auth.
|
||||
- **CRDT sync**: Yjs is the default transport via an HMAC-authenticated relay upgrade, with automatic fallback to the engine LWW relay; atmosphere state syncs over the same relay with client-side LWW convergence.
|
||||
- **WebRTC video & voice** via PeerJS (lobby-scoped mesh with real `<video>` tiles and honest connection-failure states), Silero VAD capture, HRTF positional audio bound to board tokens.
|
||||
- **Client quality gates**: vitest unit suite over deterministic pure modules (69 tests: SRD character math tables, encounter XP budgets, viewport sync, atmospheres), plus real engine-state-driven boss health bar / initiative HUD, spellbook casts via the engine slot pipeline, encounter builder on live compendium data, Roll20 import, and compendium search.
|
||||
- **Spatial audio, fog-of-war rendering, initiative tracking, exhaustion conditions**, lobbies (create/join-by-code/host-only launch), character persistence with RBAC-owned deploy, and engine-side request rate limiting (60s sliding window buckets: script 10/min, action 120/min, read 600/min; `/health`, `/metrics` and `/ws` unmetered).
|
||||
- **Client quality gates**: vitest unit suite (407 tests across 33 files) covering SRD character math tables, encounter XP budgets, viewport sync, atmospheres, transport/auth gates, wizard state, concentration/opportunity/help-ready state modules, and streamer view DOM behavior; plus real engine-state-driven boss health bar / initiative HUD, spellbook casts via the engine slot pipeline, encounter builder on live compendium data, Roll20 import, and compendium search.
|
||||
- **Vision modes, lighting zones & visibility polygons**: per-token vision modes and lighting-zone state in the engine, polygon visibility computation in `vtt-spatial/src/visibility.rs`, rendered client-side via raycast lighting.
|
||||
- **Loot containers & autosave policies**: WFC-placed loot containers surfaced through the gateway, and configurable GM campaign autosave policies (verified by `test_autosave_policy.py`).
|
||||
- **Campaign wizard & streamer view**: multi-step campaign wizard modal with persisted client-side wizard state, plus a streamer HUD view with opt-in browser-Whisper speech-to-text (`BrowserWhisperTranscriber`, off unless explicitly enabled).
|
||||
- **Compendium RAG**: optional fastembed-backed semantic retrieval over the compendium (`lore/compendium_rag.py`), degraded honestly when embeddings are unavailable.
|
||||
- **Spatial audio, fog-of-war rendering, initiative tracking**, lobbies (create/join-by-code/host-only launch), character persistence with RBAC-owned deploy, and engine-side request rate limiting (60s sliding window buckets: script 10/min, action 120/min, read 600/min; `/health`, `/metrics` and `/ws` unmetered).
|
||||
|
||||
**Known limitations (documented, not hidden):**
|
||||
- Quest routes (`POST /api/v1/quest/generate`, `GET /api/v1/quest/active`, `POST /api/v1/quest/concordia-negotiate`) have **no server-side auth dependency**, unlike handouts/autosave; generated quest graphs also live only in gateway process memory and do not survive a restart.
|
||||
- Relay fan-out is per-frame role-filtered (`broadcast_if`), not per-seat projected — hidden-token movement deltas go to GM peers as a class, not recomputed per recipient.
|
||||
- The relay applies **no role/ownership validation to atmosphere writes**; atmosphere converges by client-side LWW only.
|
||||
- The video mesh has **no TURN/STUN configured** (default PeerJS signaling/ICE); symmetric-NAT pairs may fail to connect — failures surface honestly but are not fixed.
|
||||
- Compendium spell-damage coverage is conservative: 73 of 352 spells enriched; the rest warn instead of guessing.
|
||||
- Compendium spell-damage coverage is conservative: 82 of 352 spells enriched (up from a 73-spell baseline); warned or no-damage spells stay field-free instead of guessing.
|
||||
- Rate-limit buckets are process-local (no distributed limiter).
|
||||
- The rule-version preference chosen in the campaign wizard is **not persisted server-side**; it is client-held metadata.
|
||||
- If every WFC synthesis attempt contradicts, generation falls back to an open walled box.
|
||||
@@ -214,6 +220,7 @@ Latest full local run (2026-08-24, `./scripts/run_all_benchmarks.sh`, 200 turns
|
||||
│ ├── srd_5_1_classes.json # 6 SRD 5.1 Classes
|
||||
│ ├── srd_5_1_equipment.json # 15 Weapons, Armors & Magic Items
|
||||
│ ├── srd_5_1_rules.json # 15 Conditions, Cover & Resting
|
||||
│ ├── srd_5_1_tiles.json # 3 WFC Tile Definitions
|
||||
│ ├── srd_5_2_*.json # SRD 5.2 spells, monsters, feats, origins, magic items, animals, glossary
|
||||
│ └── sample_adventure.vttbundle # Importable sample campaign bundle
|
||||
├── crates/ # Authoritative Rust Workspace
|
||||
@@ -239,7 +246,9 @@ Latest full local run (2026-08-24, `./scripts/run_all_benchmarks.sh`, 200 turns
|
||||
├── client/ # Presentation Layer (Vite + React 18 + Tailwind)
|
||||
│ ├── src/
|
||||
│ │ ├── components/ # UI Modals, Radars, Studios & Tabletop View
|
||||
│ │ ├── render/ # Positional 3D Audio & WebRTC Mesh Managers
|
||||
│ │ ├── render/ # Positional 3D Audio, WebRTC Mesh & Raycast Lighting Managers
|
||||
│ │ ├── api/ # Engine/Gateway Clients & Deterministic State Modules
|
||||
│ │ ├── sync/ # Yjs CRDT Transport & Speech Ledger Clients
|
||||
│ │ └── App.tsx # Main Application Shell
|
||||
└── scripts/
|
||||
└── run_all_benchmarks.sh # Unified Multi-Service Benchmark Suite
|
||||
|
||||
Reference in New Issue
Block a user