@lite-fsm/entities 0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2023 AlexanderGureev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PERFORMANCE.md

@@ -0,0 +1,537 @@
+# Производительность `@lite-fsm/entities`
+
+Документ фиксирует базовый профиль производительности и очередь работ для приближения публичного `@lite-fsm/entities` к ручному SoA baseline.
+
+## Базовый замер
+
+Команда:
+
+```bash
+pnpm run bench:entities:record -- --runs 5 --label codex-baseline-2026-06-14 --include gate,diagnostics
+```
+
+Артефакты:
+
+- `.bench/entities/codex-baseline-2026-06-14.json`
+- `.bench/entities/codex-baseline-2026-06-14.md`
+
+Окружение:
+
+- Дата: `2026-06-14T16:46:13.766Z`
+- Git: `4c7cd65fffbf`, branch `entities`, status `clean`
+- Node: `v24.16.0`
+- OS: `darwin/arm64`
+- CPU: `Apple M1 Max`, 10 cores
+- Package manager: `pnpm/10.33.0`
+
+## Gate summary
+
+| Сценарий | Строки | SoA median | entities median | Ratio | Бюджет | Статус |
+| --- | ---: | ---: | ---: | ---: | ---: | --- |
+| `movement update` | 10 000 | 0.046ms | 0.226ms | 4.87x | 1.50x | fail |
+| `movement update` | 50 000 | 0.232ms | 1.075ms | 4.62x | 1.50x | fail |
+| `projectile lifetime update` | 10 000 | 0.036ms | 0.202ms | 5.65x | 1.50x | fail |
+| `projectile lifetime update` | 50 000 | 0.179ms | 0.978ms | 5.44x | 1.50x | fail |
+| `despawnOn cleanup` | 10 000 | 0.055ms | 2.406ms | 43.91x | 2.00x | fail |
+| `despawnOn cleanup` | 50 000 | 0.277ms | 20.521ms | 74.65x | 2.00x | fail |
+| `sprite sync reaction` | 10 000 | 0.075ms | 1.506ms | 20.04x | 2.00x | fail |
+| `sprite sync reaction` | 50 000 | 0.491ms | 8.310ms | 16.58x | 2.00x | fail |
+
+Важные предупреждения стабильности:
+
+- `despawnOn cleanup / 50 000` имеет высокий разброс entity median: `27.8%`.
+- Diagnostics `despawnOn cleanup / 50 000 / public manager.transition` имеет высокий разброс: `24.4%`.
+- Несколько baseline на `10 000` строк ниже `0.050ms`; для них ratio чувствителен к шуму таймера.
+
+## Historical diagnostics summary
+
+Этот раздел фиксирует legacy synthetic diagnostics из базового record 2026-06-14. После `transition-trace-baseline` эти данные не являются источником production attribution и не используются как strict gate для следующих оптимизаций. Текущий workflow использует `gate` для budget check и `trace` для attribution реального `manager.transition(...)`.
+
+| Сценарий | Строки | raw SoA | semantic SoA | raw entity kernel | public transition |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| `movement update` | 10 000 | 0.015ms | 0.048ms | 0.189ms | 0.220ms |
+| `movement update` | 50 000 | 0.074ms | 0.244ms | 0.954ms | 1.077ms |
+| `projectile lifetime update` | 10 000 | 0.007ms | 0.039ms | 0.178ms | 0.206ms |
+| `projectile lifetime update` | 50 000 | 0.032ms | 0.193ms | 0.886ms | 0.996ms |
+| `despawnOn cleanup` | 10 000 | 0.028ms | 0.055ms | 0.212ms | 2.667ms |
+| `despawnOn cleanup` | 50 000 | 0.141ms | 0.280ms | 1.421ms | 22.694ms |
+| `sprite sync reaction` | 10 000 | 0.025ms | 0.064ms | 1.047ms | 1.482ms |
+| `sprite sync reaction` | 50 000 | 0.123ms | 0.334ms | 8.052ms | 8.300ms |
+
+Вывод по слоям:
+
+- Для reducer-only сценариев основная цена уже внутри `raw entity kernel`: `movement 50k` имеет `0.954ms` против `0.244ms` semantic SoA, `projectile 50k` имеет `0.886ms` против `0.193ms`.
+- Для `sprite sync reaction` почти весь разрыв находится в entity kernel и reaction scope: `8.052ms` raw entity kernel против `0.334ms` semantic SoA на `50k`.
+- Для `despawnOn cleanup` публичный путь резко дороже диагностического kernel: `22.694ms` против `1.421ms` на `50k`. Это главный источник выигрыша и главный источник нестабильности.
+- Общий `manager.transition` добавляет небольшой постоянный overhead в reducer-only сценариях: примерно `0.03ms` на `10k` и `0.11-0.12ms` на `50k`. Это не первый источник оптимизации.
+
+## Устройство текущего hot path
+
+`entitiesPlugin` регистрирует storage runtime `entityStorageRuntime`, route meta `entityId`, hook `beforeReduce` для spawn staging и manager extension `manager.entities()`.
+
+На каждый `manager.transition` core создает dispatch context, `runtime: Map`, route, `touched: Set`, проходит storage `prepareAction`, `beforeReduce`, `reduce`, `commit`, `reactions`, `effects` и subscribers. Для `entities` это приводит к следующей цепочке:
+
+1. `prepareEntityTransaction` создает transaction на каждый dispatch.
+2. `stageSpawnAction` при spawn-событии запускает recipe, валидирует specs и payload.
+3. `reduceEntityBucket` выполняет spawn lifecycle, cleanup, public event routing, reducers, повторный cleanup.
+4. `collectEntityPublicReducerBatches` для unscoped событий выбирает state buckets по `acceptStateBucketsByEventCode`.
+5. `reduceAcceptedBatch` применяет transition table, создает `self`, вызывает reducer, затем отдельными проходами валидирует state, обновляет row versions, планирует effects/reactions/despawn/terminal cleanup и обновляет state buckets.
+6. `commit` восстанавливает public slices.
+7. `runEntityReactions` собирает scoped entries, создает scoped deps и выполняет reactions.
+
+Сильные стороны текущей модели:
+
+- Данные контекста уже лежат в SoA колонках.
+- Unscoped routing не сканирует все `presence`; он использует state buckets.
+- Public state slice отделен от тяжелых колонок и обновляется через lightweight object.
+
+Основная проблема: generic lifecycle pipeline выполняет много проходов, проверок, allocations и cleanup-операций даже для простых событий вида `active -> active`.
+
+## Приоритеты оптимизации
+
+Разделы 1-3 фиксируют исторические итерации до появления trace baseline. Команды с `--include gate,diagnostics` в этих разделах оставлены как provenance старых artifacts; для следующих оптимизаций использовать workflow `gate,trace` из раздела `Итог trace baseline` и финального порядка работ.
+
+### 1. Ускорить `despawnOn cleanup`
+
+Ожидаемый максимальный выигрыш: самый высокий. Текущий gate на `50k`: `20.521ms`, `74.65x` к SoA. Diagnostics public: `22.694ms`, `165.86x` к raw SoA. Сценарий также нестабилен.
+
+Затронутые места:
+
+- `packages/entities/src/runtime/reduce.ts`: `scheduleDespawnOnRows`, cleanup plan, `flushEntityLifecycleCleanup`.
+- `packages/entities/src/runtime/state.ts`: `removeActorRowOwnership`, `removeActorRowsForStore`, `removeEntityRecords`.
+- `packages/entities/src/runtime/transaction.ts`: `scheduleEntityDespawn`, `consumeScheduledDespawns`.
+
+Контракт решения:
+
+1. Fast path удаляет строки без observable `ENTITY_DESPAWNED` work. Observable work — accepted `ENTITY_DESPAWNED` transition и reducer или `reactions.ENTITY_DESPAWNED`; state `effects` целевого состояния не являются cleanup contract.
+2. Cleanup строит план удаления и удаляет строки батчами по store через `removeActorRowsForStore`.
+3. `publicSlice`, `store.version` и `entityStore.version` обновляются один раз на затронутый batch.
+4. Контракт колонок удалённых строк: публичное чтение корректно только через `has(entity) === true`; runtime не обязан очищать колонки удаленной строки в hot path, а `dehydrate()` должен сериализовать удалённые слоты через defaults из `initialContext`.
+5. `despawnScheduled` использует переиспользуемый scratch runtime с очисткой только затронутых индексов.
+
+Критерий приемки:
+
+- `despawnOn cleanup / 50 000` должен сначала приблизиться к `raw entity kernel` уровня `1-2ms`, затем к `semantic SoA` уровня `0.3-0.6ms`.
+- RSD для `despawnOn cleanup / 50 000` должен опуститься ниже `15%`.
+- После изменения запускать `pnpm run bench:entities:record -- --runs 5 --label after-despawn-cleanup --include gate,diagnostics` и сравнивать с baseline.
+
+### Итог problem 1: despawnOn cleanup
+
+Команда:
+
+```bash
+pnpm run bench:entities:record -- --runs 5 --label after-despawn-cleanup --include gate,diagnostics
+pnpm run bench:entities:compare -- .bench/entities/codex-baseline-2026-06-14.json .bench/entities/after-despawn-cleanup.json
+```
+
+Артефакты:
+
+- [`after-despawn-cleanup.json`](../../.bench/entities/after-despawn-cleanup.json)
+- [`after-despawn-cleanup.md`](../../.bench/entities/after-despawn-cleanup.md)
+- [`after-despawn-cleanup-vs-codex-baseline-2026-06-14.md`](../../.bench/entities/after-despawn-cleanup-vs-codex-baseline-2026-06-14.md)
+
+Окружение итогового record: `2026-06-14T19:02:30.226Z`, Git `9f092b7109fd`, branch `entities`, status `dirty`, Node `v24.16.0`, CPU `Apple M1 Max`, package manager `pnpm/10.33.0`.
+
+| Сценарий | Строки | Baseline median | After median | Ratio к SoA до | Ratio к SoA после | Ускорение | RSD after |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| `despawnOn cleanup` | 10 000 | 2.406ms | 0.241ms | 43.91x | 4.43x | 2.166ms (90.0%) | 11.7% |
+| `despawnOn cleanup` | 50 000 | 20.521ms | 1.098ms | 74.65x | 3.99x | 19.423ms (94.6%) | 0.9% |
+
+Итог: первый целевой диапазон `1-2ms` для `despawnOn cleanup / 50 000` достигнут: gate median `1.098ms`. RSD gate-сценария `50 000` ниже порога `15%` (`0.9%`). Соседние gate-сценарии не получили регрессий больше `10%`: compare не показывает ни одного public entity median regression выше порога.
+
+Diagnostics после обновления fixture содержит cleanup breakdown:
+
+| Фаза / слой | 10 000 median | 50 000 median | RSD 50 000 |
+| --- | ---: | ---: | ---: |
+| `schedule despawn` | 0.015ms | 0.073ms | 1.4% |
+| `despawn lifecycle plan` | 0.006ms | 0.010ms | 15.5% |
+| `batch remove actor rows` | 0.005ms | 0.007ms | 9.9% |
+| `remove entity records` | 0.005ms | 0.013ms | 14.1% |
+| `public commit` | 0.000ms | 0.001ms | 55.6% |
+| `raw entity kernel` | 0.196ms | 1.647ms | 1.4% |
+| `public manager.transition` | 0.247ms | 1.086ms | 1.1% |
+
+Вывод по problem 1: public cleanup path теперь близок к primary reducer path и проходит первый целевой диапазон. Batch cleanup phases сами по себе занимают малую часть времени; основная стоимость остается в полном reducer/kernel проходе по активному bucket. Diagnostics `raw entity kernel / 50 000` стал медленнее baseline из-за более точной batch-removal модели fixture, но gate public scenarios не регрессировали больше `10%`.
+
+Следующие приоритеты:
+
+1. Двигать `despawnOn cleanup / 50 000` от первого диапазона `1-2ms` к следующему диапазону `0.3-0.6ms`: сейчас лимитирующий слой — общий reducer/kernel проход.
+2. Профилировать `raw entity kernel` cleanup после перехода fixture на batch-removal модель, чтобы отделить цену полного bucket scan от цены удаления `128` строк.
+3. Сохранять контракт колонок удалённых строк: чтение только через `has(entity)`, snapshot sanitation через defaults, без возврата очистки колонок в hot path.
+
+### 2. Ускорить reaction scope и `sprite sync reaction`
+
+Ожидаемый выигрыш: очень высокий. Текущий gate на `50k`: `8.310ms`, `16.58x` к SoA. Diagnostics показывают, что почти вся цена уже в `raw entity kernel`: `8.052ms` против `0.334ms` semantic SoA.
+
+Затронутые места:
+
+- `packages/entities/src/runtime/transaction.ts`: `scheduleEntityReactionBatch` копирует `indices`.
+- `packages/entities/src/runtime/reactions.ts`: `collectReactionScopeEntries`, `createReactionDeps`, `runReactionBatch`.
+- `packages/entities/src/runtime/access.ts`: `createScopedEntitySelf`, `createScopedEntityAccess`.
+
+Что исправлять:
+
+1. Убрать обязательное `indices.slice()` для reaction batch. Нужен стабильный batch view или scratch ownership, который не копирует `50k` индексов для каждого события.
+2. Не строить `entries: CapturedEntityScopeEntry[]` и `Map` для всего batch, если reaction использует только `self.indices` и колонки. Сейчас `createScopedEntitySelf` создает `Map` по всем entries, что дорого на `50k`.
+3. Разделить быстрый scoped self для reactions и строгий diagnostic self. В production hot path `has(entity)` и `entityId(entity)` могут опираться на generation arrays и scope marker без построения `Map`.
+4. Не копировать user deps через `{ ...ctx.manager.getDependencies() }` и серию `delete` на каждый reaction. Нужен заранее нормализованный deps object или wrapper с предсказуемой формой.
+5. Кешировать `entities().get("movementActor")` view на уровне reaction deps, не создавать лишний scoped access wrapper при каждом batch, если scope не требует строгой dev-проверки.
+
+Критерий приемки:
+
+- `sprite sync reaction / 50 000 / raw entity kernel` должен опуститься с `8.052ms` хотя бы ниже `2ms` первым шагом.
+- Public `sprite sync reaction / 50 000` должен следовать за kernel и не добавлять больше `0.3ms`.
+- Поведение scoped `self.has`, `self.entityId`, `entities().get` должно остаться покрытым runtime tests.
+
+### Итог problem 2: reaction scope и sprite sync reaction
+
+Команды:
+
+```bash
+pnpm run bench:entities:record -- --runs 5 --label after-reaction-scope --include gate,diagnostics
+pnpm run bench:entities:compare -- .bench/entities/after-despawn-cleanup.json .bench/entities/after-reaction-scope.json
+pnpm run bench:entities:compare -- .bench/entities/codex-baseline-2026-06-14.json .bench/entities/after-reaction-scope.json
+```
+
+Артефакты:
+
+- [`after-reaction-scope.json`](../../.bench/entities/after-reaction-scope.json)
+- [`after-reaction-scope.md`](../../.bench/entities/after-reaction-scope.md)
+- [`after-reaction-scope-vs-after-despawn-cleanup.md`](../../.bench/entities/after-reaction-scope-vs-after-despawn-cleanup.md)
+- [`after-reaction-scope-vs-codex-baseline-2026-06-14.md`](../../.bench/entities/after-reaction-scope-vs-codex-baseline-2026-06-14.md)
+
+Окружение итогового record: `2026-06-14T20:53:31.896Z`, Git `ff6c39838767`, branch `entities`, status `dirty`, Node `v24.16.0`, CPU `Apple M1 Max`, package manager `pnpm/10.33.0`.
+
+Gate `sprite sync reaction` относительно `after-despawn-cleanup`:
+
+| Сценарий | Строки | Baseline median | After median | Ratio до | Ratio после | Ускорение | RSD after |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| `sprite sync reaction` | 10 000 | 1.507ms | 0.893ms | 19.26x | 12.33x | 0.614ms (40.7%) | 2.2% |
+| `sprite sync reaction` | 50 000 | 8.259ms | 4.792ms | 16.85x | 9.77x | 3.467ms (42.0%) | 5.0% |
+
+Diagnostics `sprite sync reaction` относительно `after-despawn-cleanup`:
+
+| Слой | Строки | Baseline median | After median | Ratio к raw SoA до | Ratio к raw SoA после | Ускорение | RSD after |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
+| `semantic SoA baseline` | 10 000 | 0.064ms | 0.065ms | 2.62x | 2.58x | -0.001ms (-1.5%) | 13.7% |
+| `raw entity kernel` | 10 000 | 1.001ms | 0.430ms | 41.06x | 17.61x | 0.571ms (57.1%) | 7.0% |
+| `public manager.transition` | 10 000 | 1.447ms | 0.904ms | 59.45x | 36.66x | 0.543ms (37.5%) | 1.1% |
+| `semantic SoA baseline` | 50 000 | 0.328ms | 0.336ms | 2.64x | 2.70x | -0.009ms (-2.6%) | 1.9% |
+| `raw entity kernel` | 50 000 | 7.916ms | 2.346ms | 63.17x | 18.87x | 5.570ms (70.4%) | 1.1% |
+| `public manager.transition` | 50 000 | 7.941ms | 4.753ms | 65.18x | 38.65x | 3.188ms (40.1%) | 2.4% |
+
+Breakdown `sprite sync reaction / 50 000` после reaction scope:
+
+| Фаза / слой | Median | RSD after |
+| --- | ---: | ---: |
+| `reduce entity batches` | 1.681ms | 0.8% |
+| `schedule reaction batch` | 0.000ms | 10.0% |
+| `collect reaction scope` | 0.433ms | 2.5% |
+| `create reaction deps` | 0.000ms | 16.9% |
+| `run user reaction` | 0.094ms | 0.5% |
+| `raw entity kernel` | 2.346ms | 1.1% |
+| `public manager.transition` | 4.753ms | 2.4% |
+
+Итог: problem 2 дал сильное ускорение reaction scope, но first gate не достигнут. `sprite sync reaction / 50 000 / raw entity kernel` остается выше порога `2ms` (`2.346ms`), а `public manager.transition` добавляет к kernel `2.407ms`, что выше лимита `0.3ms`. Stretch gate также не достигнут: kernel выше `1ms`, public ratio `9.77x` далек от бюджета `2.00x`.
+
+Breakdown показывает, что основная оставшаяся цена находится в общем reducer pipeline и public path: `reduce entity batches` занимает `1.681ms`, public overhead поверх kernel — `2.407ms`. Собственный reaction scope слой больше не доминирует: `collect reaction scope` занимает `0.433ms`, `run user reaction` — `0.094ms`, scheduling и deps creation находятся на уровне таймера.
+
+Соседние gate-сценарии не прошли порог регрессии относительно `after-despawn-cleanup`: `movement update` замедлился на `13.0%` / `13.2%`, `projectile lifetime update` — на `12.9%` / `14.6%` для `10 000` / `50 000` строк. `despawnOn cleanup` остался ниже порога (`6.4%` / `5.9%`). Diagnostics raw entity kernel для `movement` и `projectile` при этом изменился в пределах `0.2%`, поэтому основная регрессия видна в public path.
+
+### 3. Сократить generic overhead `reduceAcceptedBatch` для простого `active -> active`
+
+Ожидаемый выигрыш: высокий для всех reducer-only сценариев. Текущий raw entity kernel на `50k` примерно в `4-5x` медленнее semantic SoA: `movement` `0.954ms` против `0.244ms`, `projectile` `0.886ms` против `0.193ms`.
+
+Затронутые места reducer layer:
+
+- `packages/entities/src/runtime/reduce.ts`: `resolveTransitionTarget`, `applyDefaultTransitions`, `postProcessAcceptedRows`, `markActorRowsTouched`, `scheduleEnteredStateEffects`, `updateActorStateBuckets`.
+- `packages/entities/src/runtime/compile.ts`: compile-time metadata для event/store fast path.
+- `packages/entities/src/runtime/state.ts`: stable reducer self cache, `getActorReducerSelf`, `refreshActorPublicSlice`.
+
+Что исправлять:
+
+1. Компилировать per-event reduce plan. Для события с одним принимающим state и identity transition (`active -> active`) не нужно записывать `prevStateCode` и `stateCode` для каждой строки до reducer.
+2. Если template не имеет effects, terminal states, `despawnOn` и reactions для event, не запускать соответствующие проходы по всем accepted rows.
+3. Не выполнять `updateActorStateBuckets` для identity transition, пока reducer явно не записал другой `stateCode`. Нужен дешевый способ определить state writes: отдельный dirty list, explicit helper или compile-time режим для reducer-only templates.
+4. Создавать `self` со стабильной формой один раз на store и менять только `indices`.
+5. Объединить проходы post-processing там, где они остаются обязательными: validation, rowVersion, effects/despawn/terminal scan могут быть одним циклом.
+
+Критерий приемки:
+
+- `movement update / 50 000 / raw entity kernel` должен опуститься ниже `0.5ms` первым шагом.
+- `projectile lifetime update / 50 000 / raw entity kernel` должен опуститься ниже `0.5ms` первым шагом.
+- Gate reducer-only должен двигаться от `4.6-5.4x` к бюджету `1.5x`.
+
+### Итог problem 3: reducer layer
+
+Команды:
+
+```bash
+pnpm run bench:entities:record -- --runs 1 --label reducer-layer-smoke --include gate,diagnostics --row-counts 1000
+pnpm run bench:entities:record -- --runs 3 --label after-reducer-layer --include gate,diagnostics
+pnpm run bench:entities:compare -- .bench/entities/after-reaction-scope.json .bench/entities/after-reducer-layer.json
+pnpm run bench:entities:compare -- .bench/entities/codex-baseline-2026-06-14.json .bench/entities/after-reducer-layer.json
+```
+
+Артефакты:
+
+- [`after-reducer-layer.json`](../../.bench/entities/after-reducer-layer.json)
+- [`after-reducer-layer.md`](../../.bench/entities/after-reducer-layer.md)
+- [`after-reducer-layer-vs-after-reaction-scope.md`](../../.bench/entities/after-reducer-layer-vs-after-reaction-scope.md)
+- [`after-reducer-layer-vs-codex-baseline-2026-06-14.md`](../../.bench/entities/after-reducer-layer-vs-codex-baseline-2026-06-14.md)
+
+Окружение итогового record: `2026-06-14T22:36:11.015Z`, Git `6924c1ba6c38`, branch `entities`, status `dirty`, Node `v24.16.0`, CPU `Apple M1 Max`, package manager `pnpm/10.33.0`.
+
+Gate относительно `after-reaction-scope`:
+
+| Сценарий | Строки | Before median | After median | Ratio после | Изменение | RSD after |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| `movement update` | 10 000 | 0.254ms | 0.101ms | 2.19x | -60.0% | 5.5% |
+| `movement update` | 50 000 | 1.286ms | 0.471ms | 2.04x | -63.4% | 1.9% |
+| `projectile lifetime update` | 10 000 | 0.236ms | 0.086ms | 2.42x | -63.3% | 3.9% |
+| `projectile lifetime update` | 50 000 | 1.171ms | 0.411ms | 2.28x | -64.9% | 5.6% |
+| `despawnOn cleanup` | 10 000 | 0.256ms | 0.130ms | 2.35x | -49.3% | 7.5% |
+| `despawnOn cleanup` | 50 000 | 1.163ms | 0.508ms | 1.81x | -56.3% | 1.9% |
+| `sprite sync reaction` | 10 000 | 0.893ms | 0.589ms | 7.55x | -34.0% | 0.5% |
+| `sprite sync reaction` | 50 000 | 4.792ms | 3.093ms | 6.32x | -35.5% | 5.2% |
+
+Соседних gate-регрессий выше `10%` относительно `after-reaction-scope` нет: все public gate median ускорились. От исходного `codex-baseline-2026-06-14` итог также быстрее во всех gate-сценариях: `movement 50 000` на `56.2%`, `projectile 50 000` на `57.9%`, `despawnOn cleanup 50 000` на `97.5%`, `sprite sync reaction 50 000` на `62.8%`.
+
+Diagnostics reducer layers для `50 000` строк:
+
+| Слой | `movement update` | RSD | `projectile lifetime update` | RSD | `sprite sync reaction` | RSD |
+| --- | ---: | ---: | ---: | ---: | ---: | ---: |
+| `collect/default transitions` | 0.116ms | 1.1% | 0.115ms | 0.5% | 0.232ms | 0.6% |
+| `create reducer self` | 0.000ms | 7.2% | 0.000ms | 6.3% | 0.000ms | 0.8% |
+| `run user reducer` | 0.211ms | 45.0% | 0.122ms | 1.5% | 0.191ms | 0.1% |
+| `validate final states` | 0.110ms | 0.8% | 0.106ms | 0.8% | 0.211ms | 1.2% |
+| `mark rows/public slice` | 0.048ms | 8.2% | 0.048ms | 8.3% | 0.096ms | 0.2% |
+| `schedule lifecycle work` | 0.174ms | 5.5% | 0.174ms | 4.1% | 0.346ms | 0.5% |
+| `update state buckets` | 0.065ms | 15.5% | 0.067ms | 15.0% | 0.131ms | 0.2% |
+| `reduce entity batches` | n/a | n/a | n/a | n/a | 1.374ms | 10.4% |
+| `raw entity kernel` | 0.888ms | 1.2% | 0.810ms | 0.4% | 2.173ms | 7.0% |
+| `public manager.transition` | 0.480ms | 2.7% | 0.407ms | 0.7% | 3.073ms | 6.3% |
+
+Public overhead над diagnostics `raw entity kernel` для `50 000` строк:
+
+| Сценарий | `raw entity kernel` | `public manager.transition` | Public minus kernel | Ratio public/kernel |
+| --- | ---: | ---: | ---: | ---: |
+| `movement update` | 0.888ms | 0.480ms | -0.408ms | 0.54x |
+| `projectile lifetime update` | 0.810ms | 0.407ms | -0.403ms | 0.50x |
+| `despawnOn cleanup` | 0.850ms | 0.517ms | -0.332ms | 0.61x |
+| `sprite sync reaction` | 2.173ms | 3.073ms | 0.900ms | 1.41x |
+
+Отрицательный overhead в reducer-only и cleanup строках означает, что diagnostics `raw entity kernel` продолжает моделировать более общий internal kernel и завышает стоимость относительно production `manager.transition` после reducer layer. Поэтому strict критерий `raw entity kernel < 0.5ms` не считается закрытым по diagnostics fixture: `movement` показывает `0.888ms`, `projectile` показывает `0.810ms`. При этом production gate для тех же `50 000` строк уже ниже `0.5ms`: `movement` `0.471ms`, `projectile` `0.411ms`.
+
+Итог first gate: достигнут частично. Reducer-only production path прошел первый временной порог `0.5ms` для `50 000` строк, и соседних public gate-регрессий нет. Полный first gate не закрыт: `sprite sync reaction / 50 000 / reduce entity batches` остается выше `1.0ms` (`1.374ms`), `sprite sync reaction / 50 000 / raw entity kernel` остается выше `2.0ms` (`2.173ms`), а diagnostics `raw entity kernel` для reducer-only сценариев требует обновления модели перед использованием как strict gate.
+
+Остаточные риски для problem 5:
+
+1. Public ratio reducer-only еще выше бюджета `1.50x`: `movement 50 000` имеет `2.04x`, `projectile 50 000` имеет `2.28x`.
+2. `sprite sync reaction / 50 000` ускорился до `3.093ms`, но остается далек от бюджета `2.00x`: `6.32x` к SoA.
+3. Для `sprite sync reaction / 50 000` public overhead над diagnostics kernel составляет `0.900ms`, поэтому core/bucket overhead и reaction/public path остаются отдельной областью problem 5.
+4. Diagnostics fixture нужно синхронизировать с новым reducer fast path: сейчас production public path быстрее modeled `raw entity kernel` для reducer-only сценариев.
+
+### Итог trace baseline
+
+Команды:
+
+```bash
+pnpm run bench:entities:record -- --runs 5 --label transition-trace-baseline --include gate,trace --row-counts 50000
+pnpm run bench:entities:compare -- .bench/entities/transition-trace-baseline.json .bench/entities/transition-trace-baseline.json
+```
+
+Артефакты:
+
+- [`transition-trace-baseline.json`](../../.bench/entities/transition-trace-baseline.json)
+- [`transition-trace-baseline.md`](../../.bench/entities/transition-trace-baseline.md)
+
+Trace измеряет реальный public path `manager.transition(...)` на production dist и использует те же composition runners, что gate. Включенный collector добавляет собственный overhead, поэтому абсолютные `Trace total` отделены от значений gate. `traceTotal / gateEntityMedian` — guard качества instrumentation: значение выше `2.00x` требует проверки разметки, но не является performance budget. Основной budget check остается за gate; trace является attribution-отчетом для выбора следующего шага оптимизации.
+
+Начиная с этого baseline, `raw entity kernel` из legacy diagnostics не используется для выбора следующего шага и не считается production truth. Старые diagnostics artifacts сохраняются только для исторического сравнения.
+
+Gate `50 000`:
+
+| Сценарий | SoA median | entities median | Ratio | Бюджет | Статус | RSD |
+| --- | ---: | ---: | ---: | ---: | --- | ---: |
+| `movement update` | 0.250ms | 0.832ms | 3.39x | 1.50x | fail | 32.5% |
+| `projectile lifetime update` | 0.181ms | 0.404ms | 2.27x | 1.50x | fail | 32.9% |
+| `despawnOn cleanup` | 0.276ms | 0.512ms | 1.86x | 2.00x | fail | 1.9% |
+| `sprite sync reaction` | 0.320ms | 3.723ms | 11.70x | 2.00x | fail | 5.2% |
+
+Trace totals:
+
+| Сценарий | Trace total | Gate entities median | `traceTotal / gateEntityMedian` | Transitions | RSD |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| `movement update` | 0.819ms | 0.832ms | 0.98x | 750 | 1.0% |
+| `projectile lifetime update` | 0.413ms | 0.404ms | 1.02x | 750 | 0.7% |
+| `despawnOn cleanup` | 0.510ms | 0.512ms | 0.99x | 750 | 1.3% |
+| `sprite sync reaction` | 3.529ms | 3.723ms | 0.95x | 750 | 4.8% |
+
+Предупреждений `traceTotal / gateEntityMedian > 2.00x` нет. Высокий RSD у reducer-only gate-сценариев относится к budget report data и не меняет trace attribution semantics.
+
+Top core phases:
+
+| Сценарий | Фазы |
+| --- | --- |
+| `movement update` | `core.rootReducer` 0.805ms (98.5%); `core.commit.total` 0.003ms (0.3%); `core.prepareAction.total` 0.002ms (0.2%) |
+| `projectile lifetime update` | `core.rootReducer` 0.402ms (97.5%); `core.commit.total` 0.002ms (0.5%); `core.prepareAction.total` 0.002ms (0.4%) |
+| `despawnOn cleanup` | `core.rootReducer` 0.477ms (93.6%); `core.prepareAction.total` 0.009ms (1.7%); `core.createDispatch` 0.005ms (0.9%) |
+| `sprite sync reaction` | `core.reactions.total` 2.369ms (67.3%); `core.rootReducer` 1.095ms (31.7%); `core.commit.total` 0.007ms (0.2%) |
+
+Top entities phases:
+
+| Сценарий | Фазы |
+| --- | --- |
+| `movement update` | `entities.reduce.total` 0.803ms (100.0%); `entities.reduce.publicBatch.total` 0.801ms (99.8%); `entities.reduce.publicBatch.userReducer` 0.523ms (65.4%); `entities.reduce.publicBatch.postProcess` 0.239ms (29.9%) |
+| `projectile lifetime update` | `entities.reduce.total` 0.400ms (99.9%); `entities.reduce.publicBatch.total` 0.398ms (99.7%); `entities.reduce.publicBatch.postProcess` 0.239ms (60.0%); `entities.reduce.publicBatch.userReducer` 0.122ms (30.7%) |
+| `despawnOn cleanup` | `entities.reduce.total` 0.470ms (99.9%); `entities.reduce.publicBatch.total` 0.448ms (95.7%); `entities.reduce.publicBatch.postProcess` 0.278ms (62.1%); `entities.reduce.publicBatch.userReducer` 0.131ms (29.2%) |
+| `sprite sync reaction` | `entities.reactions.total` 2.367ms (99.9%); `entities.reactions.user` 1.701ms (74.0%); `entities.reduce.total` 1.090ms (100.0%); `entities.reduce.publicBatch.total` 1.087ms (99.7%); `entities.reactions.captureScope` 0.586ms (23.9%) |
+
+Residual unattributed time:
+
+| Сценарий | Core residual | Entities reduce residual | Entities reactions residual |
+| --- | ---: | ---: | ---: |
+| `movement update` | 0.002ms (0.2%) | 0.001ms (0.1%) | 0.000ms |
+| `projectile lifetime update` | 0.002ms (0.4%) | 0.001ms (0.1%) | 0.000ms |
+| `despawnOn cleanup` | 0.004ms (0.8%) | 0.001ms (0.3%) | 0.000ms |
+| `sprite sync reaction` | 0.003ms (0.1%) | 0.001ms (0.1%) | 0.045ms (1.9%) |
+
+Основной кандидат для следующего optimization ТЗ — `sprite sync reaction / 50 000`: gate ratio `11.70x`, а trace показывает `core.reactions.total` 2.369ms и внутри него `entities.reactions.user` 1.701ms. Следующий шаг должен разбирать public reaction path и scoped access/deps work в `entities.reactions.user`; `entities.reactions.captureScope` 0.586ms и `entities.reduce.publicBatch.total` 1.087ms остаются соседними вторичными целями.
+
+### Итог unit composition benchmark
+
+Команда:
+
+```bash
+pnpm run bench:entities:record -- --runs 3 --label unit-composition-baseline --include gate,trace --row-counts 50000
+```
+
+Артефакты:
+
+- [`unit-composition-baseline.json`](../../.bench/entities/unit-composition-baseline.json)
+- [`unit-composition-baseline.md`](../../.bench/entities/unit-composition-baseline.md)
+
+Окружение record: `2026-06-15T13:29:56.184Z`, Git `381ee5e0f982`, branch `entities`, status `dirty`, Node `v24.16.0`, CPU `Apple M1 Max`, package manager `pnpm/10.33.0`.
+
+Активный composition benchmark заменяет узкий `sprite sync reaction` на `unit frame composition`: entity `unit` содержит `movementActor`, `spriteSyncActor`, `healthActor` и `targetingActor`. `healthActor` имеет state effect, который читает `getState()`, scoped `entities().get("movementActor")` и `entities().get("targetingActor")`, затем пишет агрегат во внешний `world` adapter через deps. Поэтому этот record не является прямым сравнением со старым `sprite sync reaction`; старые значения выше остаются историческим baseline для reaction-only сценария.
+
+Gate `50 000`:
+
+| Сценарий | SoA median | entities median | Ratio | Бюджет | Статус | RSD |
+| --- | ---: | ---: | ---: | ---: | --- | ---: |
+| `movement update` | 0.236ms | 0.285ms | 1.21x | 1.50x | pass | 3.8% |
+| `projectile lifetime update` | 0.180ms | 0.218ms | 1.22x | 1.50x | fail | 49.5% |
+| `despawnOn cleanup` | 0.277ms | 0.421ms | 1.51x | 2.00x | fail | 2.6% |
+| `unit frame composition` | 1.121ms | 10.269ms | 9.26x | 2.00x | fail | 6.7% |
+
+Trace totals:
+
+| Сценарий | Trace total | Gate entities median | `traceTotal / gateEntityMedian` | Transitions | RSD |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| `movement update` | 0.293ms | 0.285ms | 1.03x | 450 | 0.7% |
+| `projectile lifetime update` | 0.227ms | 0.218ms | 1.04x | 450 | 1.2% |
+| `despawnOn cleanup` | 0.420ms | 0.421ms | 1.00x | 450 | 1.4% |
+| `unit frame composition` | 10.465ms | 10.269ms | 1.02x | 450 | 1.3% |
+
+Trace для `unit frame composition / 50 000`:
+
+| Фаза | Median | Share |
+| --- | ---: | ---: |
+| `core.effects.total` | 6.406ms | 61.7% от transition |
+| `core.rootReducer` | 3.210ms | 31.1% от transition |
+| `core.reactions.total` | 0.682ms | 6.5% от transition |
+| `entities.effects.resolve` | 2.046ms | 99.9% от parent |
+| `entities.effects.invoke` | 4.300ms | 99.8% от parent |
+| `entities.reduce.publicBatch.total` | 2.957ms | 93.1% от `entities.reduce.total` |
+| `entities.reactions.user` | 0.620ms | 91.6% от `entities.reactions.total` |
+
+Trace coverage для нового сценария закрывает attribution: `core top-level` 100.0%, `entities reduce` 99.9%, `entities reactions` 99.7%, `entities effects` 99.8%. Предупреждений `traceTotal / gateEntityMedian > 2.00x` нет.
+
+Вывод: новый пример лучше отражает реальный игровой unit, но смещает главный hot spot с reaction-only пути на effects path. Основной кандидат для следующего optimization ТЗ — `unit frame composition / 50 000`: `core.effects.total` занимает `6.406ms`, из них `entities.effects.invoke` `4.300ms`, а `entities.effects.resolve` `2.046ms`. Это включает capture scope для effect, создание scoped access/self и пользовательский effect, который читает root state, две entity views и пишет во внешний adapter. Вторичные цели — `entities.reduce.publicBatch.total` `2.957ms` для четырех actor batches и `entities.reactions.user` `0.620ms`.
+
+Остаточные риски record:
+
+1. `projectile lifetime update` имеет высокий разброс gate median `49.5%`: median ratio ниже бюджета, но один из трех runs провалил per-run gate.
+2. `despawnOn cleanup` имеет median ratio ниже бюджета (`1.51x` против `2.00x`), но record status остался `fail` из-за per-run gate.
+3. Бюджет `unit frame composition` пока не является приемочным production budget: он фиксирует новый более реалистичный baseline для будущих оптимизаций effects path.
+
+### 4. Уменьшить validation overhead в spawn path
+
+Ожидаемый выигрыш: средний для текущего измеряемого `TICK`, высокий для реальных workloads со spawn/despawn. Bulk commit, пакетный reserve и payload scope уже вынесены в `spawn-commit.ts`; оставшийся кандидат — validation/staging до physical commit.
+
+Затронутые места:
+
+- `packages/entities/src/runtime/transaction.ts`: `validateSpawnSpec`, `validateActorPayload`, `stageSpawnAction`.
+- `packages/entities/src/runtime/spawn-commit.ts`: planning, reserve, physical commit и payload scope.
+
+Что исправлять:
+
+1. Предкомпилировать spawn schema validators по template, чтобы не делать `Object.entries(schema)` и повторные проверки формы на каждую строку.
+2. Сохранить текущие duplicate id и payload diagnostics без переноса validation в commit phase.
+3. Не менять public spawn recipe API и schema descriptors.
+
+Критерий приемки:
+
+- Добавить отдельный gate/trace scenario для timed spawn batch.
+- Не ухудшить `movement update`, `projectile lifetime update` и bulk spawn benchmark на `50k`.
+
+### 5. Снизить постоянный overhead `manager.transition` для bucket storage
+
+Ожидаемый выигрыш: средний-низкий до исправления entity kernel, но важный для достижения бюджета `1.5x`.
+
+Затронутые места:
+
+- `packages/core/src/runtime/kernel/createMachineManagerFactory.ts`: `createDispatch`, `coreTransition`, hook phases.
+- `packages/core/src/runtime/kernel/bucketRuntime.ts`: `prepareAction`, `beforeReduce`, `reduce`, `commit`, `runReactions`, `runEffects`.
+- `packages/entities/src/runtime/storage.ts`: `prepareAction`, `commit`, `effects`, `reactions`.
+
+Что исправлять:
+
+1. Сократить создание readonly action views и spread-объектов в bucket runtime на hot path.
+2. Не проходить пустые hook/interceptor phases, если registry заранее знает, что callbacks отсутствуют.
+3. Для bucket storage с одним активным runtime рассмотреть прямой reduce path без лишних loops по пустым buckets.
+4. Не создавать `Map` в dispatch runtime, если ни один plugin/storage не использует runtime slots. Для `entities` slot нужен, но можно заменить на специализированный carrier или переиспользуемый объект внутри одного transition.
+
+Критерий приемки:
+
+- Gate reducer-only `50k` должен приближаться к бюджету `1.50x` без регрессий соседних сценариев больше `10%`.
+- Trace должен показать снижение постоянных core/bucket фаз (`core.createDispatch`, `core.prepareAction.total`, `core.commit.total`, hooks и bucket phases) для reducer-only сценариев.
+- Legacy diagnostics `raw entity kernel` не используется как strict gate или источник production attribution.
+- Изменения core должны проходить общий `pnpm run test`, `pnpm run test:types`, `pnpm run check-types`.
+
+### 6. Уточнить trace breakdown перед крупными изменениями
+
+Ожидаемый выигрыш: непрямой. Нужен, чтобы не оптимизировать по неверной гипотезе.
+
+Что добавить:
+
+1. Дополнительные trace phases для cleanup и reactions, если текущая детализация не объясняет изменение gate.
+2. Timed spawn scenario в gate/trace workflow, где spawn входит в measured участок.
+3. Allocation counters для hot scenarios, хотя бы retained heap plus operation count.
+4. Если нужен synthetic calibration benchmark, оформить его отдельной legacy-командой и не включать в optimization gates.
+
+Критерий приемки:
+
+- Trace должен объяснять не менее `80%` времени `despawnOn cleanup / public transition` и `sprite sync reaction / public transition`.
+- Существующие gate таблицы должны остаться сопоставимыми с текущим baseline.
+
+## Рекомендуемый порядок работ
+
+Актуальный порядок идет от `unit-composition-baseline`, потому что активный benchmark теперь измеряет более реалистичный игровой unit composition, а не только reaction-only путь.
+
+1. Entity effects path для `unit frame composition`: уменьшить `entities.effects.invoke` и `entities.effects.resolve`, особенно capture scope, scoped access/self creation и user effect с `getState()`/`entities()` reads.
+2. `reduceAcceptedBatch` для multi-actor unit frame: снизить `entities.reduce.publicBatch.total` при четырех actor batches без регрессий reducer-only сценариев.
+3. Reaction user path: сохранить прошлые улучшения `sprite` reaction и дальше снижать `entities.reactions.user` в составе `unit frame composition`.
+4. Spawn/lifecycle allocation: validators, payload arrays, capacity reservation, отдельный timed spawn scenario.
+5. Core bucket overhead: убрать пустые phases и лишние action views после стабилизации entity-specific hot spots.
+6. Benchmark breakdown: при необходимости добавить более детальные effect phases для capture scope, deps/self creation и user callback.
+
+После каждого пункта сохранять отдельный record:
+
+```bash
+pnpm run bench:entities:record -- --runs 5 --label <short-name> --include gate,trace --row-counts 50000
+pnpm run bench:entities:compare -- .bench/entities/unit-composition-baseline.json .bench/entities/<short-name>.json
+```
+
+Отчет считать успешным для этапа только если целевой сценарий ускорился, соседние сценарии не получили регрессию больше `10%`, `traceTotal / gateEntityMedian` остался ниже `2.00x`, а новые runtime контракты покрыты тестами.