[M1-PROF-01] Profiler core: always-on counters, snapshot, per-run report, --prof-out

[offdev]

Implements M1-PROF-01 · Profiler core (cheap counters) from roadmap/M1-heartbeat.md (FR-11.1, FR-11.2; PRD §15.1 DBG-008; AGENTS CORE-001, PERF-003, DBG-004). Depends M1-SYS-03 + M1-ECS-06 (done).

What

• Profiler (src/laige-sim/include/laige/sim/profiler.h + profiler.cpp): the always-on counters with fixed storage and no allocation after init — tick/frame time rolling windows (512/256 samples, M0-CORE-08 Histogram; O(1) allocation-free record(), drops the oldest, totalRecorded() keeps counting), the FR-11.1 render/network counter fields (0 in headless M1 — the fields exist; M2/M3 feed them), and the cold snapshot() / snapshot(world) (world-pulled fields: entity total/alive/capacity, sim alloc count = World::archetypeStats().totalReservations (M1-ECS-03 pool accounting, target 0), system count — pulled cold, never copied; the per-system M1-SYS-03 windows stay in World, pulled only in the report). Move-only; moved-from = stopped (records no-op, empty snapshot); setEnabled (disabled = one branch, no recording).
• Reports (FR-11.1 file export): formatProfileSummaryLine (the CLI one-liner), formatProfileText (greppable text form), formatProfileJson (version 1 schema — n==0 windows render n=0 / JSON null, never NaN), writeProfile (truncating write, no partial file on failure, Result<u64, ErrorCode>).
• GameLoop: Options::profiler (non-owning); runOneTick times the tick body (the frame's beginFrame + one runSystems dispatch) with the M0-CORE-08 TimeIt and records on success only (a failed tick is neither counted nor recorded); null/disabled = one branch (DBG-004).
• Engine: owns the profiler (created in Engine::create — engine setup, not run setup, so the "exactly three one-shot allocations per run" claim stays true; released in the ordered shutdown after the world). runFrames adds the frame feed (two clock reads + one ring write per frame, excluding the pacing sleep; first frame not recorded; failed frames not recorded). Per-run report: startProfileReport(path) (EVERY build — diagnostics, not replay state), written at the END of the run on EVERY path (a zero-tick run writes a zero-tick report, CORE-008); a write failure does not fail the run (sticky profileReportStatus(), profiler/report_write_failed); profileStats() = the last run's cached snapshot (the world is released in shutdown); structured profiler/* events (NFR-13.3 5-field grammar).
• laige-run: --prof-out <report> + the always-printed laige-run profile: … one-line summary on stdout — the byte-stable status=ok line is untouched (separate line; laige_run_smoke's PASS_REGULAR_EXPRESSION stays valid). A report write failure leaves the run status=ok and exits 2.
• Docs in the same change: docs/api/profiler.md (new — full contract, counter table, report schemas, Performance, misuse), engine.md, game_loop.md, docs/README.md, src/laige-sim/README.md, docs/debugging/README.md, tools/README.md; baseline docs/benchmarks/baselines/m1-profiler-cost.md (full AGENTS §12 metadata + verbatim runs).
• Roadmap: M1-heartbeat checkbox [x]; Progress Board M1 20 → 21 (total 38 → 39) + one Change Log line; laige-api.json regenerated.

The 1% disabled-cost gate (CORE-001, DBG-004)

ProfilerCost suite: ON vs OFF over 10k-entity ticks (2000 ticks/run, best-of-2 per arm, warm-up discarded), measured with a test-side TimeIt+Histogram in both arms (cancels in the ratio). Measured on the canonical Debug g++ tree:

profiler-cost on_p50=0.557288 off_p50=0.555746 overhead_pct=0.277465

+0.28% — well inside the 1% gate; the suite asserts the bound on every non-instrumented tree, every CI run (the CI linux-gcc / linux-clang P0 jobs). The gate is scoped to non-sanitizer trees (LAIGE_ALLOC_COUNTER, the zero-allocation probe's precedent): the first ASan CI run measured 1.46% — sanitizer instrumentation inflates the profiler's fixed per-tick cost (extra clock reads + the ring write's shadow bookkeeping) disproportionately, so a sanitizer-tree number would measure the instrumentation, not the profiler (recorded in the baseline doc). The sanitizer trees instead verify the profiler's safety properties (leak-free ASan run, race-free TSan run).

Verification

• Canonical g++ tree: zero warnings; full ctest 89/89 (new profiler entry; api-real-tree + determinism-lint-real-tree green — the raw double tokens carry LAIGE-DETERM-EXCEPTION: G-R8 wall-clock diagnostic markers per the M1-SYS-03 precedent; laige_run_smoke byte-stable line intact).
• laige-run --prof-out smoke: profile summary line on stdout + valid version-1 JSON report on disk (counters, windows, world fields, per-system windows).
• Cross-trees: build-asan, build-clang, build-release, build-tsan (TSan halt_on_error=1 on profiler), build-shared — all built zero-warning, full ctest green.
• tools/laige-include-lint OK (43 source files, 1/10 vendored deps).
• Record path zero-allocation: profiler-zeroalloc ticks=1000 allocs=0 (non-sanitizer trees).

Unverified: MSVC/AppleClang compile proof (CI-only, the house precedent); the M2 overlay surface and the M3 net-byte feed (later steps by design).