Repository navigation
authority.md compliance audit: 4-round codebase review #249
Description
Goal
Audit the codebase against docs/authority.md to confirm:
- Code respects data ownership boundaries (GPU-authoritative vs CPU-authoritative vs CPU-only)
- No system reads throttled readback as a hard gameplay gate
- Combat target validation follows the practical pattern (candidate -> resolve -> validate)
- No GPU readback feedback loops (read + write same field in same frame)
- Buffer sizing uses correct constants (MAX_ENTITIES, not MAX_NPC_COUNT for slot-indexed buffers)
- EntityMap methods used correctly for live counts (not GpuSlotPool.alive() for type-specific counts)
Modeled after #247 (k8s.md audit) and #248 (performance.md audit).
Rounds
Round 1: Inventory
- Catalog every site that reads from GpuReadState (positions, combat_targets, health, factions, threat_counts)
- Catalog every site that writes to GPU upload buffers
- List all buffer sizing constants and their usage (MAX_ENTITIES, MAX_NPC_COUNT, MAX_BUILDINGS)
- Identify all combat target validation paths
- List all EntityMap count/iteration usage (npc_count, building_count, iter_npcs, alive)
Round 2: Violation detection
- For each GpuReadState read site, verify it follows the staleness rules:
- Always-on readbacks (positions, combat_targets, health): used as geometry/heuristic only?
- Throttled readbacks (factions, threat_counts): never used as hard validity gates?
- For each combat target path, verify the 4-step practical pattern (read candidate -> resolve in EntityMap -> validate faction from ECS -> use GPU only for geometry)
- Check for feedback loops: any system that reads GPU readback AND writes back to the same GPU field
- Verify buffer sizing: all slot-indexed buffers use MAX_ENTITIES, not MAX_NPC_COUNT
- Verify count usage: gameplay logic uses EntityMap.npc_count()/building_count(), not GpuSlotPool.alive()
Round 3: Fixes
- Fix any authority violations found in Round 2
- Add regression tests for each fix
- Update authority.md if any new data ownership patterns were discovered
Round 4: Verification and compliance table
- Re-read authority.md and confirm all sections are current
- Verify all readback sites comply with staleness budget
- Confirm no feedback loops remain
- Produce a system-level compliance table and post it as a comment on this issue
The compliance table must cover every system that touches GPU readback or authority-sensitive data:
| System | Reads | Writes | Authority Rule | Status |
|--------|-------|--------|---------------|--------|
| damage_system | GpuReadState.combat_targets | Health (ECS) | candidate-only, revalidate in ECS | pass/fail |
| gpu_position_readback | GpuReadState.positions | AtDestination (ECS) | geometry-only, always-on | pass/fail |
| resolve_movement_system | MovementIntents | SetTarget (GPU) | CPU-authoritative goals | pass/fail |
| build_visual_upload | ECS sprites/colors | NpcVisualBuffers | render-only, never in compute | pass/fail |
| sync_readback_ranges | GPU buffers | GpuReadState | buffer sizing = MAX_ENTITIES | pass/fail |
| ... | ... | ... | ... | ... |
Each row = one system. Status = pass (compliant), fail (violation found), or fixed (was violation, now resolved in Round 3).
Final sign-off only after every row is pass or fixed.
Acceptance Criteria
- Round 1: all GpuReadState read sites, GPU write sites, buffer sizing, combat paths, and EntityMap usage inventoried with file:line refs
- Round 2: every read site checked against ownership rules, every combat path checked against practical pattern, no feedback loops, correct buffer sizing
- Round 3: violations fixed with regression tests, authority.md updated if needed
- Round 4: compliance table posted as issue comment with every system showing pass or fixed
- Compliance verified against docs/authority.md, docs/k8s.md, docs/performance.md
Critical Docs
docs/authority.md-- primary audit targetdocs/k8s.md-- cross-reference for entity architecturedocs/performance.md-- cross-reference for hot-path readback patterns
Activity
fix: remove dead throttled faction readback fallback in attack_system (…
abix- commentedon Mar 21, 2026
Claude
Round 4: System-Level Compliance Table
gpu_position_readbackGpuReadState.positionsPositionECS (read-model),NpcFlags.at_destinationresolve_movement_systemGpuReadState.positionsSetTarget(CPU→GPUgoals[])attack_system(NPC)GpuReadState.combat_targets,positionsCombatState,AttackTimerECSbuilding_tower_system(towers)GpuReadState.combat_targets,positionsdecision_systemGpuReadState.positions,threat_countsActivitytransitionsarrival_systemGpuReadState.positionsActivity,CarriedLootpathfinding_systemGpuReadState.positionsPathRequestqueuedamage_system/process_proj_hitsGpuReadState.positionsHealthECS,DamageMsghealth_systemGpuReadState.positionsHealthECS, despawnai_player decisionGpuReadState.threat_countssync_readback_rangesGpuSlotPool.count()(direct)setup_readback_buffersbuild_visual_uploadNpcVisualBuffersGpuReadState.positions,health,threat_countsextract_npc_dataHealth,Faction,SpeedcomponentsFixed in Round 3:
attack_systemcombat.rs:485referencedgpu_state.factions(throttled, 60-frame stale). While unreachable (target_npc is always Some after None/dead filter), the code risked becoming active if flow changed.Acceptance criteria:
attack_system_uses_ecs_faction_not_gpu_readback), authority.md unchanged (no new patterns discovered)Open: Tests compile-verified via
cargo checkbut cannot link in k3s (no libalsa). Test execution needs local verification — the regression test logic is straightforward (stale same-faction GPU data should not suppress combat).Next: Human merges PR #250, test execution confirmed locally.
PR: https://github.com/abix-/endless/pull/250
fix: remove dead throttled faction readback fallback in attack_system (…