Initial Commit

openspec/archive/2026-05-19-enterprise-gaming-ecs/tasks.md

@@ -0,0 +1,64 @@
+# Tasks: enterprise-gaming-ecs
+
+## Phase 1 — Scaffold
+
+- [ ] Create `gaming/engine/ecs/` with `package.json` (`@suaveplan/ecs`, version `0.1.0`, `sideEffects: false`)
+- [ ] Add `tsconfig.json` extending `@suaveplan/typescript-config/library.json`
+- [ ] Add `vitest.config.ts` using `createTestConfig()`
+- [ ] Wire `bunx turbo lint typecheck test` in turbo pipeline
+
+## Phase 2 — Error codes & constants
+
+- [ ] Implement `src/error-codes.ts` — `EcsError extends SuaveplanError`, `defineCodes` for `ECS.*` codes
+- [ ] Implement `src/constants/index.ts` — `DEFAULT_MAX_ENTITIES`, `ROOT_ARCHETYPE_MASK`
+
+## Phase 3 — Types
+
+- [ ] Implement `src/types/common.ts` — `Entity`, `ComponentType`, `ComponentDescriptor<T>`, `QueryMask`, `QueryResult`, `System`, `WorldOptions`, `Archetype`
+- [ ] Write `src/types/common.md`
+
+## Phase 4 — Component registry
+
+- [ ] Implement `src/core/component/component.ts` — `defineComponent<T>()`, auto-incrementing type IDs
+- [ ] Write tests and docs
+
+## Phase 5 — Archetype store
+
+- [ ] Implement `src/core/archetype/archetype.ts` — `bigint` mask, entity roster, typed array storage for numeric components
+- [ ] Write tests and docs
+
+## Phase 6 — Query engine
+
+- [ ] Implement `src/core/query/query.ts` — `buildQueryMask()`, `matchArchetype()`, `QueryResult` with `forEach`
+- [ ] Property-based test: query result = exhaustive entity scan filtered by component membership
+
+## Phase 7 — System registry
+
+- [ ] Implement `src/core/system/system.ts` — `SystemRegistry` with ordered update loop, `registerSystem`, `unregisterSystem`
+- [ ] Write tests and docs
+
+## Phase 8 — World
+
+- [ ] Implement `src/core/world/world.ts` — `createWorld()`, spawn/despawn, component add/remove, tick with AbortSignal, OTel spans
+- [ ] Wire `@suaveplan/events` entity lifecycle events
+- [ ] Write tests and docs
+
+## Phase 9 — Utils
+
+- [ ] Implement `src/utils/bitset.ts` — `maskFromTypes()`, `maskHasAll()`, `maskHasNone()`, `maskHasAny()`
+- [ ] Write tests
+
+## Phase 10 — Integration & property tests
+
+- [ ] `tests/integration.test.ts` — full ECS loop: spawn entities, add components, query, system update, despawn
+- [ ] `tests/property.test.ts` — fast-check: entity count monotonicity, archetype mask algebra, query consistency
+
+## Phase 11 — Benchmark
+
+- [ ] `src/__benchmarks__/ecs.bench.ts` — 10k spawn, 100k query iteration, 60fps tick with 10 systems
+
+## Phase 12 — Pre-publish gate
+
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/ecs` green
+- [ ] `bunx turbo test:coverage --filter=@suaveplan/ecs` — 100% on all touched modules
+- [ ] Publish: `bun scripts/publish.ts --package @suaveplan/ecs`