docs: add current developer feature index

2026-08-13 00:26:55 +02:00
parent 149e043f86
commit 9872b986b6
21 changed files with 1296 additions and 45 deletions
@@ -0,0 +1,101 @@
+# Feature slice: tests, quality, and performance evidence
+
+The project uses deterministic headless scenarios, GUT unit tests, formatting/
+lint checks, and reviewed benchmark ledgers. Tests are part of the architecture:
+they prove authority boundaries, conservation, migration, parity, and
+deterministic continuation.
+
+## Quality gate
+
+Run from the repository root:
+
+```bash
+./tools/quality.sh --changed   # fast iteration
+./tools/quality.sh             # full gate before commit
+git diff --check
+```
+
+The gate currently runs Godot 4.7 platform/import checks, `gdformat`,
+`gdlint`, headless project checks, standalone scenarios, GUT, and a dedicated
+Compatibility presentation smoke. It uses an isolated Godot profile under
+`logs/quality/godot_profile`. On macOS, Godot's certificate-store diagnostic,
+Terrain3D interpolation deprecation, and the exact known dummy-shader exit
+diagnostic are classified by the gate; new error classes must not be hidden.
+
+## Scenario families
+
+| Concern | Representative tests |
+| --- | --- |
+| Definitions and packs | `content_catalog_test`, `simulation_definitions_test`, `test_activity_content_catalog_contract` |
+| Targets and interaction parity | `world_target_registry_test`, `context_scoped_world_targets_test`, `resource_node_player_parity_test`, `test_activity_action_command_service` |
+| Economy and resources | `food_storage_loop_test`, `resource_regrowth_test`, `animal_food_delivery_test` |
+| Animals and enemies | `animal_definition_contract_test`, `animal_pair_vertical_slice_test`, `test_combatant_factory`, `conflict_war_system_test` |
+| Events and social facts | `test_world_event_store`, `test_social_foundations`, `witnessed_knowledge_consequence_test`, `relationship_consequence_test` |
+| Situations and dialogue | `test_situation_system`, `emergent_jajce_slice_test`, `conversation_domain_test`, `dialogue_manager_conversation_presenter_test`, `dialogue_mode_controller_test` |
+| Save/migration | `test_emergent_state_validation`, `simulation_state_serialization_test`, `save_slot_persistence_test`, `test_commitment_lifecycle_service` |
+| Regional records | `test_regional_world_state`, `test_regional_scheduler`, `test_regional_caravan_service`, `test_regional_chunked_persistence`, `test_regional_chunked_file_store` |
+| Presentation | `jajce_world_scaffold_test`, `jajce_presentation_quality_test`, `jajce_runtime_integration_test`, `test_presentation_relevance_policy`, `creature_visual_path_retry_test` |
+
+When a change affects state, target selection, saves, navigation reachability,
+player/NPC parity, deterministic continuation, or a fact-representing UI,
+extend a scenario rather than relying on a parser/lint pass.
+
+## Benchmark runners
+
+```bash
+# local simulation population/history fixture
+godot --headless --path "$PWD" \
+  --script res://tools/benchmark_simulation_scaling.gd
+
+# loaded finite-resource spatial discovery
+godot --headless --path "$PWD" \
+  --script res://tools/benchmark_loaded_resource_discovery.gd
+
+# regional records and scheduler (20 caravans / 50k cohorts)
+godot --headless --path "$PWD" \
+  --script res://tools/benchmark_regional_scale.gd
+```
+
+Reviewed reports live in `docs/benchmarks/` beside machine-readable JSON. A
+benchmark must record seed, Godot version, host label, workload/schema ID,
+sample count, warmup, simulated ticks, checksums, and exclusions. Structural
+headless measurements cannot be presented as rendered frame-time claims.
+
+## Determinism and conservation checklist
+
+For a new system, add tests for:
+
+- same seed/run produces the same canonical checksum;
+- save/load at the important boundary continues identically;
+- execution budgets `{1, 8, unlimited}` preserve order and result where a
+  scheduler is involved;
+- loaded, unloaded, and load/unload presentation produce identical authority;
+- people, cargo, inventory, storage, unique items, and event IDs conserve;
+- stale offers, duplicate IDs, unknown definitions, forged facts, and scope
+  mismatches fail without partial mutation;
+- important identities remain pinned through relevance/aggregation decisions.
+
+## Current evidence and gaps
+
+The current full suite passes 154/154 tests with 2,047 assertions. Baseline 03
+measures 600 full-fidelity data-only NPC/combatant records at about 90.6 ticks/s
+on the reviewed development host. The regional baseline proves the target
+record counts and scheduler parity. Neither measures a complete regional
+economy or weak-PC rendering.
+
+The next performance evidence should capture High and Low at a fixed gameplay
+camera on a named weak-PC reference: p50/p95/p99 CPU/GPU frame time, draw calls,
+primitives, memory/VRAM, active detailed visuals, and navigation queue depth.
+Keep those measurements in a reviewed ledger instead of adding brittle hardware
+limits to CI.
+
+## Test authoring conventions
+
+- Use stable IDs and fixed seeds.
+- Prefer exact assertions over prose or frame timing.
+- Make test fixtures isolate duplicate stable-ID registries and world scopes.
+- Use fake presenters for semantic dialogue; reserve plugin/parser tests for the
+  adapter boundary.
+- Keep benchmark fixtures independent of production managers unless the test is
+  explicitly an integration proof.
+- Run focused tests while editing, then the full gate before committing.