# Tasks — enterprise-ecs

> Every checkbox MUST reflect work actually done in this change. Retroactive ticking is forbidden (`openspec/AGENTS.md` §13).

## 1. Spec authoring

- [x] 1.1 Read `../suaveplan/enterprise/ecs.md` end-to-end
- [x] 1.2 Confirm `openspec/specs/ecs/spec.md` does not yet exist (fresh capability)
- [x] 1.3 Read `openspec/AGENTS.md` §13 + §14
- [x] 1.4 Draft `proposal.md` from `openspec/templates/proposal.md`
- [x] 1.5 Fill `## Source mapping` — every requirement cites a line range or is in the "no source line" table
- [x] 1.6 Draft `specs/ecs/spec.md` from `openspec/templates/spec-delta.md`
- [x] 1.7 Every requirement carries a `**Verified by:**` line naming concrete `it(...)` titles

## 2. Implementation

- [x] 2.1 `packages/games/ecs/package.json` — `@suaveplan/ecs@0.1.0`, `sideEffects: false`, deps `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/opentelemetry`, `tslib`, `zod`
- [x] 2.2 `tsconfig.lib.json` + `vite.config.ts` + `vitest.config.ts` + `tests/setup/polyfills.ts`
- [x] 2.3 `src/errors/ecs-error.ts` — `EcsError extends SuaveplanError` + `ECS_CODES` registry
- [x] 2.4 `src/types/ecs.types.ts` — `Entity`, `ComponentId`, `ComponentSchema<T>`, `ArchetypeId`, `QueryDescriptor`, `SystemDefinition`, `SystemPhase`, `SystemContext`, `SystemExecuteFn`, `WorldApi`, `WorldEventMap`, `EntitySnapshot`, `WorldSnapshot`
- [x] 2.5 `src/bitset/bitset.ts` — `Uint32Array`-backed `BitSet` with operators and iterator
- [x] 2.6 `src/component-registry/component-registry.ts`
- [x] 2.7 `src/entity-pool/entity-pool.ts`
- [x] 2.8 `src/archetype/archetype.ts`
- [x] 2.9 `src/query/query.ts` + `defineQuery`
- [x] 2.10 `src/system/system.ts` + `defineSystem` + `SystemScheduler`
- [x] 2.11 `src/schema/schema.ts` — `defineComponent` with optional Zod validator
- [x] 2.12 `src/world/world.ts` — `createWorld`, `World` class, OTel spans/counters/histogram, EventBus events
- [x] 2.13 `src/observability/otel.ts` — counter/histogram/span helpers
- [x] 2.14 `src/schemas/*.ts` — Zod schemas for `WorldSnapshot`, `QueryDescriptor`, `WorldConfig`, `ComponentDescriptor`
- [x] 2.15 `src/index.ts` — explicit-named barrel (no `export *`)
- [x] 2.16 Per-feature `index.ts` barrels with explicit named re-exports

## 3. Tests

- [x] 3.1 `src/bitset/bitset.test.ts` + `src/bitset/bitset.spec-conformance.test.ts`
- [x] 3.2 `src/component-registry/component-registry.test.ts`
- [x] 3.3 `src/entity-pool/entity-pool.test.ts`
- [x] 3.4 `src/archetype/archetype.test.ts`
- [x] 3.5 `src/query/query.test.ts`
- [x] 3.6 `src/system/system.test.ts`
- [x] 3.7 `src/schema/schema.test.ts`
- [x] 3.8 `src/world/world.test.ts` + `src/world/world.spec-conformance.test.ts`
- [x] 3.9 `src/errors/ecs-error.test.ts`
- [x] 3.10 `tests/property.test.ts` (fast-check)
- [x] 3.11 `tests/purity.test.ts` (dist grep guard)
- [x] 3.12 `tests/dep-graph.test.ts` (runtime dep allowlist)
- [x] 3.13 Every `it(...)` carries `{ timeout: 5000 }` (30000 for genuinely async)
- [x] 3.14 All test files import runner primitives from `@suaveplan/testing/runner`

## 4. Documentation

- [x] 4.1 Sibling `.md` for every implementation `.ts` (≥200 words, basic + advanced examples, API reference)
- [x] 4.2 `README.md` linking every co-located `.md` under `## Modules`
- [x] 4.3 Update `CLAUDE.md` package listing to add `ecs` under a `### Games (universal-tier)` section

## 5. Pre-archive 5-gate triple

- [x] 5.1 `bun run check` — Biome 0/0/0 across monorepo
- [x] 5.2 `bunx turbo lint typecheck test --filter=@suaveplan/ecs` — green
- [x] 5.3 `bunx turbo test:coverage --filter=@suaveplan/ecs` — 100/100/100/100
- [x] 5.4 `bun scripts/openspec-conformance.ts @suaveplan/ecs` — exit 0
- [x] 5.5 `bunx turbo build --filter=@suaveplan/ecs` — green

## 6. Pre-archive checklist (AGENTS.md §13)

- [x] 6.1 Generics threaded; `expectTypeOf` on every literal-type claim
- [x] 6.2 Zod schemas wired at every declared boundary (component validators, snapshot restore, query options)
- [x] 6.3 Every `ECS.*` code thrown by ≥1 production path
- [x] 6.4 OTel instruments emitted from production paths; asserted with a real in-memory `MeterProvider`
- [x] 6.5 Lifecycle dedup tested (idempotent `registerComponent`, `addComponent` no-op on existing component)
- [x] 6.6 No `export *` in any feature-module barrel
- [x] 6.7 No direct `vitest` / `bun:test` imports in test files (CLAUDE.md rule 11)
- [x] 6.8 No retroactive ticking — every box reflects work done in this change

## 7. Archive

- [x] 7.1 Fold spec delta into `openspec/specs/ecs/spec.md`
- [x] 7.2 Archive superseded `openspec/changes/enterprise-gaming-ecs/` → `openspec/archive/2026-05-19-enterprise-gaming-ecs/` with a `SUPERSEDED.md` note pointing at this change
- [x] 7.3 Move `openspec/changes/enterprise-ecs/` → `openspec/archive/2026-05-19-enterprise-ecs/`
- [x] 7.4 Refresh `MANIFEST.md` via `bun scripts/folder-reorg/generate-manifest.ts`