# 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`