@series-inc/rundot-syncplay 5.23.0-beta.7

package/README.md

@@ -0,0 +1,610 @@
+# RUN Syncplay
+
+Offline-first deterministic multiplayer engine for RUN.game. You author a
+**deterministic** game (`defineSyncplayGame`, `DeterministicSystem`,
+`DeterministicRandom`) and Syncplay runs it — input authority, prediction, and
+rollback — with no game-specific server logic.
+
+This package is intentionally standalone. It does not depend on Venus MP,
+Cloud Run, React Three Fiber, Rapier, Firebase, or the SDK bridge.
+
+## Preview Status
+
+This is a headless engine and certification package. It is designed to prove
+deterministic simulation behavior from the CLI before renderer integration is
+added, and to hand deploy-check artifacts to Venus backend upload/room-server
+validation when a room bundle opts in.
+
+Production matchmaking, ticket UX, client connection flows, and R3F renderer
+proof are not part of this package yet. The current production-facing Venus MP
+changes validate uploaded deterministic room proof metadata and pass normalized
+proof into room startup; they do not add new matchmaking or client connection
+semantics.
+
+## Testing
+
+`test:core` is the confidence surface. It runs the behavioral suites that pin
+the engine's observable multiplayer behavior — authority room, offline/session
+wire, snapshot late-join, crash restore, latency/loss convergence,
+replay-verified scoring, bot backfill, time-sync pacing, match logs,
+spectators, synctest, instant replay, session promotion, and pause/resume —
+and it is the PR gate: `ci-syncplay.yml` runs `npm run build` + `npm run
+test:core` on every PR that touches `packages/syncplay/`.
+
+The other subsystem test files (physics, navigation, animation, bots, schema,
+and similar) were reduced to determinism + rollback tripwires: same inputs
+twice must produce identical checksums, and snapshot → advance → restore →
+resimulate must match the uninterrupted run. They are regression alarms, not
+coverage suites; their per-subsystem (near-)100% coverage shards were removed,
+and the remaining `coverage:package:*` shards cover the core modules only.
+
+The netcode surface has its own behavioral suites: `pumpPaced` pacing with
+ping-adaptive input delay and client `netStats`, desync detection/response,
+match logs via `matchLog`, spectator support, and `runSyncplaySynctest` for
+creators. See `docs/syncplay-netcode-observability.md`,
+`docs/syncplay-replay-verified-leaderboards.md`, and
+`docs/syncplay-wire-format.md`.
+
+The deterministic deploy check (`project:deploy-check` /
+`project:deploy-check-verify`) is an internal-consistency **receipt** — it
+proves the bundle it describes is the bundle that was checked — not a
+cryptographic signature or provenance proof
+(see `.plans/deterministic-multiplayer-branch-cleanup.md`).
+
+CI lanes:
+
+- `ci-syncplay.yml` — PR gate: build + `test:core` on engine changes.
+- `ci-syncplay-services.yml` — mp-room-server deterministic room/gateway tests
+  plus the SDK syncplay bridge tests.
+- `ops-syncplay-nightly.yml` — cross-VM replay verification in Chromium and
+  WebKit, plus the 128-player/100k-frame stress soak
+  (`certify:deterministic-stress`).
+
+Heavier local lanes: `npm run verify:deterministic-backend` (repo root) after
+touching the Venus upload/runtime integration, and `npm run test:certification`
++ `npm run certify:standalone-complete` before a deterministic engine release.
+The full certification path intentionally includes 128-player and 100k-frame
+stress runs; keep it out of ordinary PR auto-testing.
+
+## Current Surface
+
+```ts
+import {
+  createSyncplayGameRuntime,
+  createSyncplayClient,
+  createDeterministicR3fAdapter,
+  verifyDeterministicReplay,
+} from '@series-inc/rundot-syncplay/browser';
+import { createDeterministicAuthorityServer } from '@series-inc/rundot-syncplay/node';
+import { rundotSyncplayPlugin } from '@series-inc/rundot-syncplay/tools';
+```
+
+The SDK bridge re-exports a browser-safe subset for games that already depend on
+`@series-inc/rundot-game-sdk`:
+
+```ts
+import {
+  createSyncplayGameRuntime,
+  createSyncplayClient,
+  createDeterministicR3fAdapter,
+  verifyDeterministicReplay,
+} from '@series-inc/rundot-game-sdk/syncplay/browser';
+import { createDeterministicAuthorityServer } from '@series-inc/rundot-game-sdk/syncplay/node';
+```
+
+Implemented:
+
+- Fixed-tick offline runner.
+- 1 to 128 local input slots.
+- Replay export and Node replay verification.
+- Metrics-only replay mode for long performance runs.
+- Bounded snapshots and restore-to-frame.
+- Deterministic RNG, RNG forking, and fixed-point math helpers.
+- Deterministic collection helpers for stable sorted keys, stable indexed maps,
+  and seeded shuffles.
+- Deterministic frame timer helpers for frame/ms conversion, cooldown counters,
+  and scheduled frame events.
+- Public ECS-lite world API with stable entity IDs, component add/remove,
+  singleton state, deterministic queries, snapshot/restore, and checksums.
+- Runtime guard opt-in for blocked globals during simulation.
+- Static checker CLI and Vite-compatible no-dependency plugin/config helpers,
+  including diagnostics for random/time/timers/I/O, unordered iteration, random
+  sort comparators, render-object mutation, and uncertified physics stepping.
+- AST-backed deterministic static analysis using TypeScript syntax trees, with
+  regex scanning retained only as a parser-unavailable fallback.
+- SDK-shaped offline runtime helper that exposes frame subscriptions, replay
+  export, schema-backed checksums, and no server dependency.
+- Stable game-facing browser names for the offline runtime, R3F adapter, replay
+  verification, and multiplayer client facade.
+- Stable node/server name for an in-process local authority server facade over
+  the local authority runtime.
+- Stable multiplayer facade methods for normalized scalar input submission,
+  command-channel submission, command polling, command timeline snapshots,
+  reconnect, late join, spectator state, bot-controlled slot metadata, and
+  checksum convergence.
+- Stable authority certification artifact export plus a verifier that replays
+  recorded lifecycle/input history and recomputes snapshot, command timeline,
+  and checksum evidence for CLI certification.
+- Render-only r3f-compatible adapter that emits frozen predicted/verified frame
+  props, provides normalized input bindings, and blocks render subscribers from
+  mutating checksummed session state.
+- Render-only interpolation helpers and immutable debug overlay data for
+  predicted frame, verified frame, checksum, and correction count.
+- SDK test-app r3f visual sample that renders Fixed Arena frame props through
+  React Three Fiber and verifies deterministic status, r3f metrics, and a
+  visible non-empty WebGL canvas with Playwright.
+- Full SDK subpath export at
+  `@series-inc/rundot-game-sdk/syncplay`, verified by SDK Jest
+  tests, `build:sdk`, and built `dist` import checks.
+- Curated creator subpath export at
+  `@series-inc/rundot-game-sdk/syncplay/creator` for
+  browser-safe offline runtime, descriptors, commands, schema artifacts, and
+  replay verification without Node tooling, local servers, certification labs,
+  render adapters, or engine internals.
+- Manifest-driven H5 creator entrypoint certification that requires game code
+  to import the safe `/creator` runtime surface and rejects broad SDK, Node,
+  tooling, lab, certification, r3f, and internal runtime imports before release
+  evidence is written.
+- H5 browser release proof that opens the built `dist/index.html`, steps the
+  starter app through its deterministic UI, and records frame, score, checksum,
+  and `index.html` hash evidence alongside browser replay verification.
+- Deterministic project release bundle manifests that inventory release
+  evidence, project manifests, certification artifacts, replay bundles, browser
+  proofs, and recursive `dist/` files with byte counts and checksums, plus a
+  fail-closed bundle verifier for creator CI, deploy tooling, and Venus upload
+  proof validation.
+- Local mock network adapter over the protocol lab with delay/loss/duplicate
+  settings, rollback metrics, and deterministic replay artifact export.
+- Local WebSocket harness with `/health`, `/protocol`, CLI server/client
+  commands, result comparison against the in-memory protocol lab, and a
+  Node-only SDK subpath so browser bundles stay free of Node `http`/`crypto`.
+- `lab:venus-mp-budget` compatibility gate for current Venus MP defaults
+  (`ROOM_DEFAULT_MAX_PLAYERS=10`, 30 msg/s, 16 KB messages) and explicit
+  128-player adapter settings.
+- `mp-room-server` worker-harness compatibility test that runs a deterministic
+  room bundle through `RoomManager`, the worker sandbox, room broadcast, and
+  `StateStore.save` without Firestore or Venus MP gateway dependencies.
+- `mp-room-server` WebSocket gateway compatibility test that authenticates
+  single-use `TicketStore` tickets, joins real `/ws` clients, sends
+  deterministic input, broadcasts `rdm:confirmed`, and verifies persisted
+  checksum state.
+- POST `/tickets` compatibility test that mocks Firebase token/profile
+  dependencies, mints deterministic-room tickets over HTTP, uses those tickets
+  on the real `/ws` gateway, and verifies deterministic confirmation plus
+  persisted checksum state.
+- In-memory rollback protocol lab with delay, duplication, reordering, loss,
+  disconnect/reconnect, resend, retry cancellation, and desync injection.
+- Late join, asymmetric latency, input-delay sweeps, deterministic bot slots,
+  and actual bundled input delivery in the protocol lab.
+- Protocol lab game adapters for the synthetic lab shape and Counter Duel.
+- `lab:netcode` 128-player measurement wrapper for input-minimal,
+  moderate-state, and command-burst shapes, with RTT/jitter/loss mapping,
+  payload estimates, event metrics, and pass/warn/fail classification.
+- `lab:prediction-culling` local-area AOI lab with predicted/verified execution
+  checksums, restore/resim proof, visible-correction metrics, and hidden
+  authoritative interaction failures.
+- Descriptor validation for deterministic input/state/event/asset/config/system
+  schemas with stable replay identity ids.
+- Descriptor artifact helpers, descriptor-backed replay inspection, and
+  `schema:dump` for schema-aware input/state/command serialization,
+  deserialization, canonicalization, replay metadata, cooked asset manifests,
+  checksums, and frame dumps.
+- `schema:types` TypeScript interface generation for descriptor-declared input,
+  state, commands, event payloads, event unions, replay metadata, cooked asset
+  manifests, replay identity constants, default input factories, and stable
+  serializer helpers.
+- Rollback-safe event timeline primitives for predicted, confirmed, canceled,
+  and verified-only view events.
+- Stable JSON report emission for protocol rollback lab runs.
+- Manifest-driven `certify` CLI orchestrator for the v1 deterministic
+  multiplayer certification suite, with stable per-fixture JSON artifacts,
+  deterministic budget gates, required Node replay verification, and optional
+  browser replay groups kept outside the offline core gate.
+- `certify:v1` includes a fixed-foundation fixture with stable golden checksums
+  for fixed math, fixed collision vectors, seeded RNG, frame timers, scheduled
+  frame events, stable maps/sets, and deterministic shuffles.
+- `certify:v1` includes a protocol-matrix fixture for delay/jitter, loss,
+  duplicates, reordering, reconnect, late join, asymmetric latency, input
+  delay, bot slots, command bursts, expected desync artifacts, and frame-model
+  rollback/correction metrics.
+- `certify:v1` includes static-analysis, schema-tooling, event-callbacks,
+  built-in physics, and prediction-culling fixtures so existing deterministic
+  authoring, replay/debug, callback, physics, and AOI behavior is validated from
+  one offline CLI command.
+- Descriptor replay identity includes command-channel schema IDs and
+  prototype/entity-template schema IDs, and `certify:v1` verifies those identity
+  fields through the schema-tooling fixture.
+- `certify:v1` includes an external-physics policy gate that keeps
+  `rapier2d-compat` blocked from checksummed gameplay until its snapshot,
+  restore, query-order, callback, snapshot-hash, and version-identity gates pass.
+- `certify:v1` includes headless ECS-lite, KCC-lite, projectile/hitscan,
+  bot-replacement, and genre-like 128-player top-down bot workload fixtures
+  before any r3f, Venus MP, or browser dependency enters the verification path.
+- `certify:v1` includes deterministic grid navigation/pathfinding with stable
+  query order, unreachable-target detection, slot-ordered avoidance, rollback
+  equality, and checksum convergence.
+- Public deterministic navigation primitives for cooked graph assets, stable
+  A*, region disabling, dynamic blockers, off-mesh links, flow fields, tilemap
+  graph cooking, deterministic avoidance ordering, and rollback-equivalent
+  agent stepping.
+- Public deterministic bot primitives for typed stable blackboards, HFSM,
+  Behavior Tree, Utility selection, deterministic bot asset cooking, mixed-style
+  simulation, rollback equivalence, and 128-player bot replacement metrics.
+- `certify:v1` includes headless reference-sample category coverage for
+  asteroids-basic, platform-shooter-2d, simple-fps, twin-stick-shooter,
+  arena-brawler, racer-25d, and turn-flow-mini-golf mechanics.
+- Protocol reports include bounded predicted/confirmed/canceled event timeline
+  summaries.
+- Replay verification first-mismatch diagnostics, replay frame inspect,
+  checksum explain tables, and replay diff CLI commands for lab replay frame
+  dumps.
+- `certify:v2 -- --profile chaos` fixture coverage for locally provable
+  multiplayer failure modes: resync snapshot-tail recovery, disconnect
+  recovery, rollback buffer boundaries, hostile protocol rejection, command
+  idempotency, event exactly-once semantics, replay identity failures, random
+  rollback, tick catch-up guards, asset/config mismatches, physics/movement
+  rollback boundaries, and 128-player command-burst chaos.
+- Fixed-point collision primitives and a Fixed Arena package-local example with
+  128-player replay verification and render projection output.
+- `lab:physics-cert` built-in fixed physics certification for fixed-arena and
+  128-slot load shapes with snapshot/restore, stable collision/query ordering,
+  and timing metrics.
+- `lab:physics-cert -- --engine rapier2d-compat` certification for
+  `@dimforge/rapier2d-compat@0.19.3`; the current pinned cert reproduces
+  snapshot/restore nondeterminism, so Rapier remains render/prototype-only for
+  checksummed gameplay.
+- Public deterministic 2D physics primitives for static/dynamic/kinematic AABB
+  bodies, sensors/triggers, enter/stay/exit callbacks, layer masks,
+  deterministic AABB and ray queries, material response, simple fixed/distance/
+  spring/motor constraints, rollback-equivalent stepping, and budget metrics.
+- Public deterministic movement primitives for KCC-like slopes, steps, ledges,
+  moving platforms, elevators, one-way platforms, wall slides, jump buffering,
+  coyote time, top-down acceleration/drag/sliding, nav steering, quantized FPS
+  aim, deterministic recoil, lag-compensated target rewind, and rollback
+  equivalence.
+- Public headless sample-scene fixtures for Asteroids, Simple FPS, Twin Stick,
+  Platform Shooter, Arena Brawler, Vehicle, Mini Golf, Waiting Room, Boat/Water,
+  and Animator mechanics, each with named counters, rollback-equivalent
+  checksums, and CLI-certified mechanic invariants.
+- Counter Duel package-local example with replay verification and event output.
+
+## Commands
+
+```bash
+npm test
+npm run build
+
+npm run project:scaffold -- ./deterministic-game --name "Arena Test"
+npm run project:certify -- ./deterministic-game/syncplay.project.json --require descriptor,assets,config,replay-runtime,static-determinism --frames 32 --out-dir ./deterministic-game/artifacts/deterministic --json ./deterministic-game/artifacts/deterministic/project-certification.json
+npm run project:summary -- ./deterministic-game/artifacts/deterministic/project-certification.json --out ./deterministic-game/artifacts/deterministic/project-certification-summary.md --json ./deterministic-game/artifacts/deterministic/project-certification-summary.json
+npm run project:preflight -- ./deterministic-game/syncplay.project.json --certification ./deterministic-game/artifacts/deterministic/project-certification.json --summary ./deterministic-game/artifacts/deterministic/project-certification-summary.md --dist ./deterministic-game/dist --out ./deterministic-game/artifacts/deterministic/project-preflight.md --json ./deterministic-game/artifacts/deterministic/project-preflight.json
+npm run project:check -- ./deterministic-game/syncplay.project.json --require descriptor,assets,config,replay-runtime,static-determinism --frames 32 --out-dir ./deterministic-game/artifacts/deterministic --dist ./deterministic-game/dist --out ./deterministic-game/artifacts/deterministic/project-check.md --json ./deterministic-game/artifacts/deterministic/project-check.json --junit ./deterministic-game/artifacts/deterministic/project-check.xml --release-json ./deterministic-game/artifacts/deterministic/project-release-evidence.json
+npm run project:release-verify -- ./deterministic-game/artifacts/deterministic/project-release-evidence.json --json ./deterministic-game/artifacts/deterministic/project-release-verification.json
+npm run project:release-bundle -- ./deterministic-game/artifacts/deterministic/project-release-evidence.json --json ./deterministic-game/artifacts/deterministic/project-release-bundle.json
+npm run project:release-bundle-verify -- ./deterministic-game/artifacts/deterministic/project-release-bundle.json --out ./deterministic-game/artifacts/deterministic/project-release-bundle-verification.md --json ./deterministic-game/artifacts/deterministic/project-release-bundle-verification.json --junit ./deterministic-game/artifacts/deterministic/project-release-bundle-verification.xml
+npm run project:release-bundle-schema -- --json artifacts/reports/project-release-bundle-schema.json
+npm run project:deploy-check -- ./deterministic-game/syncplay.project.json --bundle ./deterministic-game/artifacts/deterministic/project-release-bundle.json --out ./deterministic-game/artifacts/deterministic/project-deploy-check.md --json ./deterministic-game/artifacts/deterministic/project-deploy-check.json --junit ./deterministic-game/artifacts/deterministic/project-deploy-check.xml
+npm run project:deploy-check-verify -- ./deterministic-game/artifacts/deterministic/project-deploy-check.json --out ./deterministic-game/artifacts/deterministic/project-deploy-check-verification.md --json ./deterministic-game/artifacts/deterministic/project-deploy-check-verification.json --junit ./deterministic-game/artifacts/deterministic/project-deploy-check-verification.xml
+npm run project:ci-workflow -- --out .github/workflows/syncplay-ci.yml --json artifacts/reports/project-ci-workflow.json
+npm run project:scaffold -- ./deterministic-h5 --name "H5 Arena" --template h5 --sdk-version ^0.8.0 --deterministic-version ^0.3.0
+npm run project:check -- ./deterministic-h5/syncplay.project.json --require descriptor,assets,config,replay-runtime,creator-boundary,static-determinism --frames 32 --out-dir ./deterministic-h5/artifacts/deterministic --dist ./deterministic-h5/dist --out ./deterministic-h5/artifacts/deterministic/project-check-browser.md --json ./deterministic-h5/artifacts/deterministic/project-check-browser.json --junit ./deterministic-h5/artifacts/deterministic/project-check-browser.xml --release-json ./deterministic-h5/artifacts/deterministic/project-release-evidence-browser.json --browser-runtime chromium --browser-json ./deterministic-h5/artifacts/deterministic/project-browser-proof-chromium.json
+npm run project:release-verify -- ./deterministic-h5/artifacts/deterministic/project-release-evidence-browser.json --require-browser-proof --json ./deterministic-h5/artifacts/deterministic/project-release-verification-browser.json
+npm run project:release-bundle -- ./deterministic-h5/artifacts/deterministic/project-release-evidence-browser.json --require-browser-proof --json ./deterministic-h5/artifacts/deterministic/project-release-bundle-browser.json
+npm run project:release-bundle-verify -- ./deterministic-h5/artifacts/deterministic/project-release-bundle-browser.json --out ./deterministic-h5/artifacts/deterministic/project-release-bundle-verification-browser.md --json ./deterministic-h5/artifacts/deterministic/project-release-bundle-verification-browser.json --junit ./deterministic-h5/artifacts/deterministic/project-release-bundle-verification-browser.xml
+npm run project:deploy-check -- ./deterministic-h5/syncplay.project.json --require-browser-proof --bundle ./deterministic-h5/artifacts/deterministic/project-release-bundle-browser.json --out ./deterministic-h5/artifacts/deterministic/project-deploy-check.md --json ./deterministic-h5/artifacts/deterministic/project-deploy-check.json --junit ./deterministic-h5/artifacts/deterministic/project-deploy-check.xml
+npm run project:deploy-check-verify -- ./deterministic-h5/artifacts/deterministic/project-deploy-check.json --out ./deterministic-h5/artifacts/deterministic/project-deploy-check-verification.md --json ./deterministic-h5/artifacts/deterministic/project-deploy-check-verification.json --junit ./deterministic-h5/artifacts/deterministic/project-deploy-check-verification.xml
+npm run project:doctor -- ./deterministic-h5/syncplay.project.json --require-browser-proof --json ./deterministic-h5/artifacts/deterministic/project-doctor-ci.json --junit ./deterministic-h5/artifacts/deterministic/project-doctor-ci.xml
+npm run --prefix ./deterministic-h5 build
+npm run project:scaffold -- ./deterministic-systems --name "Systems Test" --template systems
+npm run project:certify -- ./deterministic-systems/syncplay.project.json --require all --frames 12 --agents 4 --slots 1,2 --out-dir ./deterministic-systems/artifacts/deterministic --json ./deterministic-systems/artifacts/deterministic/project-certification-full.json
+npm run project:summary -- ./deterministic-systems/artifacts/deterministic/project-certification-full.json --out ./deterministic-systems/artifacts/deterministic/project-certification-summary.md --json ./deterministic-systems/artifacts/deterministic/project-certification-summary.json
+npm run project:certify -- ./deterministic-game/syncplay.project.json --require all --frames 128 --agents 128 --out-dir ./deterministic-game/artifacts/deterministic --json ./deterministic-game/artifacts/deterministic/project-certification-full.json
+npm run certify:v1
+npm run certify:v1 -- --json artifacts/certification/suite.json
+npm run certify:v2 -- --profile required-full --json artifacts/certification/v2-full.json
+npm run certify:v2 -- --profile chaos --json artifacts/certification/chaos.json --junit artifacts/certification/chaos.xml
+npm run certify:v2 -- --profile chaos --filter resync --json artifacts/certification/chaos-resync.json
+npm run certify:v2 -- --profile chaos --filter hostile --json artifacts/certification/chaos-hostile.json
+npm run certify:v2 -- --profile chaos --filter rollback-boundary --json artifacts/certification/chaos-rollback-boundary.json
+npm run certify:v2 -- --profile chaos --filter replay-identity --json artifacts/certification/chaos-replay-identity.json
+npm run certify:v2 -- --profile chaos --filter commands --json artifacts/certification/chaos-commands.json
+npm run certify:v2 -- --profile chaos --filter events --json artifacts/certification/chaos-events.json
+npm run certify:v2 -- --profile chaos --filter input-policy --json artifacts/certification/chaos-input-policy.json
+npm run certify:v2 -- --profile chaos --filter network --json artifacts/certification/chaos-network.json
+npm run certify:v2 -- --profile chaos --filter random --json artifacts/certification/chaos-random.json
+npm run certify:v2 -- --profile chaos --filter tick --json artifacts/certification/chaos-tick.json
+npm run certify:v2 -- --profile chaos --filter assets --json artifacts/certification/chaos-assets.json
+npm run certify:v2 -- --profile chaos --filter physics --json artifacts/certification/chaos-physics.json
+npm run certify:v2 -- --profile chaos --filter movement --json artifacts/certification/chaos-movement.json
+npm run certify:v2 -- --profile chaos --filter scale-128 --json artifacts/certification/chaos-scale-128.json
+npm run certify:v2 -- --profile chaos --explain-fixture resync.snapshot-tail
+npm run static:determinism -- --json artifacts/certification/static-determinism.json --junit artifacts/certification/static-determinism.xml
+npm run test:pack-smoke
+npm run certify:standalone-complete
+npm run certify:engine-complete -- --players 128 --frames 5000 --seed 71 --json artifacts/certification/engine-complete.json --junit artifacts/certification/engine-complete.xml
+npm run benchmark:engine-complete -- --players 128 --frames 100000 --seed 71 --enforce-thresholds --json artifacts/certification/engine-complete-stress.json --junit artifacts/certification/engine-complete-stress.xml
+npm run certify:v2 -- --profile required-full --players 128 --frames 1000 --seed 71 --json artifacts/certification/engine-parity-required-full.json --junit artifacts/certification/engine-parity-required-full.xml
+npm run benchmark:engine-parity -- --profile stress --players 128 --frames 100000 --seed 71 --json artifacts/certification/engine-parity-stress-100k.json --junit artifacts/certification/engine-parity-stress-100k.xml
+npm run report:engine-parity-matrix:certified
+npm run static:determinism -- --json artifacts/certification/static-engine-current.json
+npm run certify:v2 -- --runtime chromium --filter browser-boundary --json artifacts/certification/engine-parity-v2-browser-runtime.json
+npm run certify:v2 -- --stress --filter performance-128 --frames 1000 --json artifacts/certification/engine-parity-v2-stress-shortcut.json
+npm run report:diff -- artifacts/certification/engine-parity-required-full.json artifacts/certification/engine-parity-stress-100k.json --max-differences 20 --json artifacts/certification/engine-parity-benchmark-diff.json
+npm run check -- tests/fixtures/pass --strict
+{ npm run check -- tests/fixtures/fail --strict; test "$?" -eq 1; }
+
+npm run lab:offline-replay -- --players 128 --frames 100000 --seed 3
+npm run lab:offline-replay -- --players 4 --frames 1000 --seed 7 --out artifacts/replays/browser-p4-seed7.json
+npm run lab:replay-inspect -- artifacts/replays/browser-p4-seed7.json --frame 120 --explain-checksum --out artifacts/reports/browser-p4-frame120.json
+{ npm run lab:replay-diff -- artifacts/replays/lab-p4-seed11.json artifacts/replays/lab-p4-seed12.json --frame 60 --max-differences 20 --json; test "$?" -eq 1; }
+npm run build
+npm run lab:replay-verify-browser -- artifacts/replays/browser-p4-seed7.json --runtime chromium
+npm run lab:replay-verify-browser -- artifacts/replays/browser-p4-seed7.json --runtime webkit
+npm run lab:protocol-rollback -- --players 128 --frames 1000 --seed 19 --min-delay 1 --max-delay 8 --duplicate-permille 100 --loss-permille 100 --resend-interval 9 --max-resend-attempts 14 --disconnect-start 100 --disconnect-end 130
+npm run lab:protocol-rollback -- --players 8 --frames 300 --seed 47 --min-delay 1 --max-delay 6 --bundle-size 5 --json artifacts/reports/protocol-p8.json
+npm run lab:protocol-rollback -- --players 4 --frames 120 --seed 57 --min-delay 1 --max-delay 5 --duplicate-permille 100 --event-timeline-limit 3
+npm run lab:protocol-rollback -- --game counter-duel --players 4 --frames 300 --seed 53 --min-delay 1 --max-delay 7 --duplicate-permille 100 --json artifacts/reports/counter-duel-protocol-p4.json
+npm run lab:netcode -- --shape input-minimal --players 128 --hz 10 --frames 1000 --rtt 200 --jitter 100 --loss 2 --duplicate-permille 100 --event-timeline-limit 0 --json artifacts/reports/netcode-p128-input-minimal.json
+npm run lab:netcode -- --shape moderate-state --players 128 --hz 10 --frames 1000 --rtt 200 --jitter 100 --loss 2 --duplicate-permille 100 --event-timeline-limit 0 --json artifacts/reports/netcode-p128-moderate-state.json
+npm run lab:netcode -- --shape command-bursts --players 128 --hz 10 --frames 1000 --rtt 200 --jitter 100 --loss 2 --duplicate-permille 100 --event-timeline-limit 0 --json artifacts/reports/netcode-p128-command-bursts.json
+npm run lab:prediction-culling -- --mode off --players 128 --objects-per-player 8 --frames 1000 --seed 19 --radius 180 --json artifacts/reports/prediction-culling-off-p128.json
+npm run lab:prediction-culling -- --mode local-area --players 128 --objects-per-player 8 --frames 1000 --seed 19 --radius 180 --json artifacts/reports/prediction-culling-local-area-p128.json
+npm run lab:netcode -- --shape moderate-state --players 128 --hz 10 --frames 1000 --rtt 200 --jitter 100 --loss 2 --duplicate-permille 100 --prediction-culling local-area --objects-per-player 8 --prediction-radius 180 --event-timeline-limit 0 --json artifacts/reports/netcode-p128-moderate-state-culling.json
+npm run lab:local-ws-server -- --port 9301 &
+server_pid=$!
+trap 'kill $server_pid' EXIT
+npm run lab:wait-for-url -- --url http://127.0.0.1:9301/health --timeout-ms 10000
+npm run lab:ws-adapter-test -- --url ws://127.0.0.1:9301/protocol --players 4 --frames 120 --seed 17 --min-delay 1 --max-delay 5 --loss-permille 10 --duplicate-permille 100
+npm run lab:r3f-render-adapter -- --players 4 --frames 120 --seed 9
+{ npm run lab:venus-mp-budget -- --players 128 --hz 30 --frames-per-message 1 --max-players 10 --json; test "$?" -eq 1; }
+npm run lab:venus-mp-budget -- --players 128 --hz 30 --frames-per-message 3 --max-players 128 --json
+npm run lab:physics-cert -- --engine builtin-fixed --shape fixed-arena --players 8 --frames 1000 --seed 7 --snapshot-every 1 --json artifacts/reports/physics-builtin-fixed-arena-p8.json
+npm run lab:physics-cert -- --engine builtin-fixed --shape slot-load --players 128 --frames 1000 --seed 11 --snapshot-every 8 --json artifacts/reports/physics-builtin-slot-load-p128.json
+{ npm run lab:physics-cert -- --engine rapier2d-compat --shape fixed-arena --players 4 --frames 60 --seed 17 --snapshot-every 2 --json artifacts/reports/physics-rapier2d-compat-known-fail.json; test "$?" -eq 1; }
+npm run lab:number -- --mode fixed-q16 --frames 100000 --seed 7
+npm run lab:number-browser -- --mode fixed-q16 --frames 100000 --seed 7 --runtime chromium --json artifacts/certification/number-fixed-q16-chromium.json
+npm run lab:number-browser -- --mode integer --frames 100000 --seed 7 --runtime chromium --json artifacts/certification/number-integer-chromium.json
+npm run lab:number-browser -- --mode fixed-q16 --frames 100000 --seed 7 --runtime webkit --json artifacts/certification/number-fixed-q16-webkit.json
+npm run lab:number-browser -- --mode integer --frames 100000 --seed 7 --runtime webkit --json artifacts/certification/number-integer-webkit.json
+npm run lab:replay-verify-browser -- artifacts/replays/browser-p4-seed7.json --runtime chromium --playwright-module /tmp/rdm-missing-playwright --json artifacts/certification/browser-replay-skip-proof.json
+npm run lab:number-browser -- --mode fixed-q16 --frames 10 --seed 7 --runtime chromium --playwright-module /tmp/rdm-missing-playwright --json artifacts/certification/number-browser-skip-proof.json
+npm run example:counter-duel -- --players 4 --frames 300 --seed 3 --verify --out artifacts/replays/counter-duel-p4.json --json artifacts/reports/counter-duel-p4.json
+npm run example:fixed-arena -- --players 128 --frames 240 --seed 19 --verify --out artifacts/replays/fixed-arena-p128.json --json artifacts/reports/fixed-arena-p128.json
+npm run schema:validate -- tests/fixtures/descriptors/pass
+npm run schema:dump -- tests/fixtures/descriptors/pass/counter-duel.json --state tests/fixtures/descriptors/state/counter-duel-state.json --frame 42 --out artifacts/reports/counter-duel-schema-frame42.json
+npm run schema:types -- tests/fixtures/descriptors/pass/counter-duel.json --name CounterDuel --out artifacts/reports/counter-duel-types.ts
+npm run schema:binary -- tests/fixtures/descriptors/pass/counter-duel.json --name CounterDuel --out artifacts/reports/counter-duel-binary.ts --json artifacts/reports/counter-duel-binary.json
+cd ../../server/mp-room-server && npm run build
+cd ../../server/mp-room-server && npm test -- --run src/rooms/deterministicMultiplayerRoom.integration.test.ts
+cd ../../server/mp-room-server && npm test -- --run src/routes/deterministicTicketsGateway.integration.test.ts
+```
+
+Generated project scaffolds include a `.gitignore` for `node_modules/`, `dist/`,
+and generated `artifacts/`; keep certification/release evidence with CI logs
+unless your project has a separate artifact archive policy.
+
+## Report Schema
+
+All CLI reports are stable JSON intended for terminal review and CI parsing.
+Certification reports include `schemaVersion`, `result`, `failures`, category or
+fixture records, invariant maps, metrics, checksums, and profile/seed/frame
+identity. Replay reports include aggregate file/frame/checksum counts plus
+per-file mismatch records. Asset-cook reports include per-file expected/actual
+outcomes, stable asset DB hashes, schema hashes, dependency hashes, lookup
+hashes, stable dependency ordering, stable recook checks, prototype-spawn
+checks, and stale manifest rejection checks.
+
+TypeScript report types are exported for certification, chaos certification,
+Engine-parity certification, protocol rollback reports, replay inspect/diff
+reports, asset cooking, static determinism suppressions, and generic report
+diffs. Use `report:diff` for category-level artifact regression review and
+`lab:replay-diff` for frame-level replay state diffs.
+
+## Asset Cooking
+
+`cook:syncplay-assets -- --verify fixtures/assets --json <path>` cooks every
+valid asset fixture and expects every invalid fixture to fail. The command proves
+byte-stable recooking under reordered source assets, stable asset DB and lookup
+hashes, stable schema hashes, stable dependency hashes, deterministic dependency
+ordering, prototype spawn identity, duplicate ID rejection, unresolved reference
+rejection, unquantized float rejection, schema mismatch rejection,
+nondeterministic dependency rejection, stale engine rejection, and stale asset
+database hash rejection.
+
+Runtime code can call `cookDeterministicAssets`,
+`materializePrototypeEntities`, and `assertAssetManifestMatches` directly. Asset
+manifests should be treated as replay identity inputs: changing the asset DB
+hash or deterministic asset engine version invalidates old replays unless a
+migration explicitly maps the old identity to the new one.
+
+## Replay Debugging
+
+`replay:verify` verifies single replay files or directories, supports frame
+ranges, emits aggregate and per-file mismatch counts, and returns first-mismatch
+diagnostics. `lab:offline-replay` can export small replay artifacts for browser
+or debugger use and refuses oversized materialized transcripts; use metrics-only
+long runs for 128-player/100,000-frame stress proofs. `lab:replay-inspect`
+dumps a stable frame state, and `lab:replay-diff` emits capped state-path
+differences between two replay frames.
+
+Snapshot-tail reconstruction is covered by chaos certification for late
+spectator, killcam, and resync-style workflows. Corrupted replay fixtures under
+`fixtures/replays/corrupt` are expected failures and must stay deterministic.
+
+## Static Determinism
+
+`static:determinism` runs the static checker against known-good package fixtures
+and known-bad fixtures, writes JSON and JUnit, and fails if package source emits
+strict errors or if known-bad fixtures stop failing. Diagnostics include
+remediation text. Valid suppressions must use
+`// rdm-ignore-next-line <rule-id>: <reason>` and are reported with file, line,
+rule, and reason; invalid suppressions are errors.
+
+The checker covers host random/time, timers, async simulation work, I/O,
+unordered object iteration, random sort comparators, render-object mutation,
+uncertified physics stepping, and descriptor-declared state-field access.
+
+## Browser Certification
+
+Browser replay and number labs run through Playwright when the requested browser
+runtime is available. Chromium pass artifacts are required when Chromium is
+installed; WebKit writes either a pass artifact or an explicit skip artifact.
+Standalone provisioning can pass `--playwright-module`; missing tooling writes
+clean skip artifacts instead of fabricating checksum or value matches.
+
+The optional browser profile checks package and SDK-facing browser-safe exports
+for Node-only module imports, filesystem APIs, local server APIs, and
+certification-only APIs. Node WebSocket helpers remain available only through
+the `./node` subpath. V2 certification accepts `--runtime node|chromium|webkit`
+and records the selected runtime in the suite and category reports; actual
+browser execution remains in the browser replay and number lab commands.
+
+## Performance And Stress
+
+`benchmark:engine-parity` emits diffable 128-player metrics for input-minimal,
+moderate-state, protocol, bot, projectile/sample, replay, and performance
+workloads. Timing thresholds are reported but non-blocking unless
+`--enforce-thresholds` is set. The opt-in stress profile supports
+100,000-frame/128-player runs and fails on desync, missing rollback history, or
+corrupted replay output. `certify:v2 -- --stress` is a shortcut for selecting
+the stress profile when no explicit `--profile` is provided.
+
+Use the generated benchmark and stress artifacts with `report:diff` to review
+regressions from the terminal. Long stress runs should stay opt-in for local and
+CI workflows unless a separate CI policy requires them.
+
+Use `certify:standalone-complete` to refresh the standalone proof contract in
+the required order. It regenerates `engine-complete`,
+`engine-complete-stress`, `engine-parity-required-full`,
+`engine-parity-stress-100k`, the evidence-backed parity matrix, and the static
+determinism audit. Use `report:engine-parity-matrix:certified` after refreshing
+individual artifacts manually; it loads evidence from
+`artifacts/certification`, enforces zero required CLI-verifiable gaps, and
+writes the canonical `engine-parity-matrix.json` artifact consumed by
+`static:determinism`.
+
+## Parity Claims
+
+The parity claim is standalone, headless, CLI-verifiable deterministic
+multiplayer parity for the locally provable deterministic engine engine capabilities:
+rollback, replay, fixed numerics, deterministic authoring checks, asset
+cooking, protocol delay/fault handling, browser runtime parity, and 128-player
+stress readiness.
+
+This does not include Venus MP integration, production backend certification,
+or renderer/r3f parity. Working with third-party game engines is not a goal. Navigation
+and bot parity are headless exported runtime primitives, not external engine
+project importers, visual editors, production cloud services, or polished
+creator-facing sample scenes.
+
+## Chaos Certification
+
+The chaos profile is CLI-only and standalone. It does not use Venus MP, Cloud
+Run, Firebase, r3f, browser rendering, or production room servers. It is meant
+to prove rollback/resync protocol behavior before external adapters make
+failures harder to isolate.
+
+Chaos fixtures are nested under the normal `certify:v2` report model as a
+single `chaos` category. Each fixture has a stable `fixtureId`, `category`,
+`expectedResult`, seed, players, frames, network model, invariant map, metrics,
+artifact path, checksum, and result. `expected-failure` means the fixture passes
+only when the bad input, corrupted replay, evicted rollback history, or config
+mismatch is detected deterministically.
+
+Fixture categories are `resync`, `hostile`, `rollback-boundary`,
+`replay-identity`, `commands`, `events`, `input-policy`, `network`, `random`,
+`tick`, `assets`, `physics`, `movement`, and `scale-128`. Use `--filter` with
+any category or fixture id to run a focused subset. Use `--explain-fixture` to
+print what a fixture proves, its expected result mode, artifact path, and pass
+invariants.
+
+`static:determinism` remains the prerequisite source-text lint proof for chaos
+certification. The chaos profile intentionally focuses on runtime protocol,
+replay, rollback, and asset/config behavior rather than duplicating static
+analysis.
+
+Use `report:diff` for benchmark, certification, and chaos JSON artifacts. It
+compares stable report JSON by path, emits capped differences, and exits
+nonzero when reports differ. Use `lab:replay-diff` for frame-level replay state
+diffs.
+
+## r3f Boundary
+
+r3f is a view layer for this package. Simulation state remains plain
+checksummed data, the r3f adapter projects a frozen render frame, and React
+components render that frame without mutating session state.
+
+Input should be captured in DOM/r3f/UI code, normalized through
+`bindInput(slot, normalize)`, and submitted as descriptor-shaped deterministic
+input before the next fixed tick. React render timing, Three.js objects,
+materials, vectors, and interpolation floats stay outside replay checksums.
+
+## Known Gaps
+
+- Browser replay verification passes locally in Chromium and WebKit for the lab
+  replay when Playwright browser runtimes are available. The optional browser
+  profile also checks that package and SDK-facing browser-safe exports exclude
+  Node-only modules, local servers, filesystem APIs, and certification-only APIs.
+  Browser replay and browser number labs accept `--playwright-module` for
+  standalone provisioning tests and emit explicit skip artifacts when Playwright
+  is unavailable.
+  Package-local fixtures under `fixtures/assets`, `fixtures/replays`,
+  `fixtures/static`, and `fixtures/browser-safe` are the reusable corpus for
+  asset cooking, replay verification, static determinism, and browser-boundary
+  certification.
+  `tests/apps/android-webview-deterministic` currently provides an Android
+  WebView APK harness, but Android emulator/logcat verification is not part of
+  the required local proof set.
+- Vite plugin/config helpers intentionally use structural Vite-compatible types
+  instead of importing Vite, so creator projects can gate builds without a Vite
+  peer dependency from the deterministic package.
+- Static checker can optionally load a descriptor and fail strict mode for
+  undeclared `state.foo`/`state["foo"]` references in simulation code.
+- Schema descriptors validate shape and identity, produce schema-aware
+  serializers/deserializers and frame dumps, and generate TypeScript types plus
+  default input factories. `schema:binary` emits separate descriptor-derived
+  binary serializer source with an embedded schema hash and round-trip proof.
+- Replay inspect/diff and `verifyReplayWithDescriptor` support descriptor-backed
+  arbitrary game replays when the caller supplies the game step/default input.
+- Protocol rollback reports include bounded event timeline summaries, and
+  generic r3f/audio/UI/custom effect consumers can read frozen event payloads.
+- The r3f-compatible adapter is verified as a render boundary, Fixed Arena
+  exports a creator-facing r3f reference view model, and the SDK test-app
+  renders that view in a visual sample.
+- Prediction culling is a local AOI execution lab, not a production-optimized
+  partial resimulation scheduler yet.
+- Reference sample certification is headless mechanics coverage, not polished
+  creator-facing r3f sample scenes yet.
+- Sample-scene fixtures expose reusable headless mechanics counters for CLI
+  certification. They are not polished game templates, rendered examples, or
+  creator-facing r3f scenes yet.
+- Navigation primitives include cooked graph assets, A*, regions, blockers,
+  off-mesh links, flow fields, tilemap graphs, and deterministic agent stepping.
+  They do not yet include deterministic navmesh import/baking from DCC or r3f
+  scene geometry.
+- Bot primitives include typed blackboards, HFSM, Behavior Tree, Utility
+  selection, deterministic asset hashes, and rollback tests. They do not yet
+  include a visual bot authoring editor or creator-facing bot asset pipeline.
+- Movement primitives cover the CLI-verifiable mechanics needed by platformer,
+  top-down, simple-FPS, and 3D KCC fixtures, including rollback-safe capsule
+  movement, slopes, steps, moving platforms, and physics queries. They do not
+  yet include authored r3f scene collision import or visual controller tooling.
+- `mp-room-server` compatibility currently proves worker harness and
+  `RoomManager` behavior, direct `TicketStore` `/ws` auth, and mocked-auth
+  POST `/tickets` ticket minting. SDK transport compatibility proves public
+  `WsMultiplayerApi` deterministic input/confirmation traffic plus forced
+  reconnect with a fresh ticket. Gateway negative-path coverage proves expired
+  tickets, unauthenticated deterministic messages, auth timeout, stale socket
+  replacement, and server pre-timeout reconnect instructions. When Firebase
+  Auth and Firestore emulators are configured, the optional Firebase integration
+  test covers Auth ID-token verification and Firestore `profiles/{uid}` lookup
+  through the same POST `/tickets` and `/ws` deterministic gateway path.
+- Built-in fixed physics certification includes package-local 2D/2.5D and 3D
+  deterministic worlds with sensors/triggers, queries, layer masks, callbacks,
+  constraints, CCD helpers, boxes, spheres, capsules, mesh static bounds,
+  deterministic angular state, and 128/512/2048-body stress samples. Remaining
+  limits are production-grade stacked rigid-body solving, visual collision
+  authoring/import, and replacing external physics engines; Rapier cert
+  currently fails with `knownIssueRapier910=reproduced`,
+  `uninterruptedChecksum=916fe725ae2e3215`, and
+  `restoredChecksum=9e42622842bffff6`.