[M1-ECS-06] ECS guardrails: G-R3 entity-count thresholds, G-R4 per-frame churn

[offdev]

What this step implements

Roadmap step M1-ECS-06 (roadmap/M1-heartbeat.md): the engine-enforced guardrails G-R3 and G-R4 (PRD §9.3) for the ECS entity storage.

• G-R3 entity-count thresholds. World::create() emits one structured Warn exactly when the live entity count reaches 25% / 50% / 100% of the declared scene budget (integer thresholds capacity * pct / 100; a level whose threshold computes to 0 never fires). A level warns at most once per frame — dipping below and re-crossing within the same frame does not re-warn. Events: ecs/entity_budget_25|50|100.
• G-R4 per-frame component churn. The per-frame add/remove churn (successful addComponent calls, including in-place overwrites; row-detaching removeComponent calls; no-op removes and destroy/clear detaches are not counted) warns when it strictly exceeds World::Options::churnPerFrameBudget (new option, default laige::kDefaultChurnPerFrameBudget = 256; 0 disables the guardrail), at most once per frame. Event: ecs/churn_per_frame.
• Profiler feed (M1-PROF-01). World::beginFrame() drives the per-frame windows (the game loop of M1-LOOP-01 will wire it); World::guardrailStats() returns the GuardrailStats snapshot (level/warn counts, per-frame churn + budget, warn counters).

Message grammar and debug advice

Every guardrail warn's message text is the NFR-13.3 5-field error-grammar line ({code} | {what} | {why} | {fix} | {doc_anchor}), identical in every build. Per PRD §9.3 ("warn (debug: with advice)"), debug builds add the advice as an extra structured field — never as message text, so the grammar stays build-stable. The G-R4 advice is the PRD's: move the churn to a spawn/despawn system (the same advice the iteration-legality rejection points to, docs/api/query.md).

Hot-path cost

Three threshold comparisons per create(), one counter increment plus one comparison per counted add/remove, a handful of stores per beginFrame(). Pure integer bookkeeping, no allocation (PERF-003); the warn paths are cold and their fields construct only when the event is enabled (LOG-003). A zero-allocation test pins the below-threshold window (EcsGuardrails.GuardrailChecksAllocateNothingBelowTheThresholds).

Tests

New EcsGuardrails suite, CTest entry ecs_guardrails (tests/laige-sim/ecs_guardrails_tests.cpp):

• thresholds fire exactly at the documented percentages (25/50/100 for capacity 8), no duplicates, BudgetExhausted at 100% without a repeated warn;
• once-per-level-per-frame dedup (same-frame down-cross + up-cross does not re-warn; a new frame does);
• degenerate thresholds (capacity 2 → 50/100 only; capacity 1 → 100 only; capacity 0 → nothing);
• guardrails fire even without frame bookkeeping (warn-once-per-lifetime degradation);
• churn warns exactly when the budget is strictly exceeded, once per frame, counter reset at frame start, no-op removes uncounted, budget 0 disables;
• NFR-13.3 grammar: message splits into exactly 5 non-empty fields, {code} names the event, {doc_anchor} is docs/api/entity.md#guardrails; debug builds carry the advice field (the churn advice contains "spawn/despawn system"), release builds do not;
• guardrailStats() profiler-feed values across a frame boundary;
• zero-alloc window below all thresholds (non-sanitizer trees; sanitizer trees cover it via leak-free runs).

Two pre-existing logging tests (WorldLogging.StaleAccessWarnsOnce, ArchetypeLogging.ArchetypeBudgetWarnsOnce) updated to count their events by event name: the new guardrail warns are legitimate contents of their sink windows (a capacity-1 world crosses 100%; the 300-capacity scenario crosses 25%/50% and the default churn budget).

laige-api.json regenerated with the 12 new public symbols (kDefaultChurnPerFrameBudget, GuardrailStats + fields, World::Options::churnPerFrameBudget, World::beginFrame, World::guardrailStats); api-real-tree is green.

Verification (all 39 tests green in each tree)

Tree	Result
build (Debug, GCC)	39/39 pass, incl. ecs_guardrails
build-asan (ASan+UBSan)	39/39 pass
build-release (NDEBUG paths)	39/39 pass
build-clang (Clang, Debug)	39/39 pass
build-tsan (TSan)	39/39 pass (one unfiltered-sim flake on the very first run, right after the build finished; 3+ reruns clean — the timing-sensitive churn assertion measures ~81 ns/row vs the 200 floor)
build-shared (NFR-8.9)	sim suites pass

No new error codes, no new dependencies, no ENGINE-RULE-EXCEPTION blocks.