Initial Commit

openspec/changes/enterprise-gaming-destructibles/proposal.md

@@ -0,0 +1,171 @@
+# OpenSpec Change: enterprise-gaming-destructibles
+
+- **Change ID**: enterprise-gaming-destructibles
+- **Package**: `@suaveplan/destructibles`
+- **Category**: gaming/combat
+- **Target path**: `gaming/combat/destructibles`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/destructibles.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/destructibles` on the genesis branch from scratch at enterprise quality. The package provides a destructible environment system with fracture patterns, debris management, and loot spawning. A `DestructibleObject` holds health state and a `FracturePattern` — a list of named fragment descriptors with relative positions, masses, and spawn probabilities; when health reaches zero, `fracture()` computes which fragments to spawn and what loot to drop. A `DebrisManager` tracks active debris with lifetime timers. Genesis adds Zod schemas, structured errors, OTel destruction counters, and 100% coverage.
+
+---
+
+## Current-state audit (genesis)
+
+Package does not exist on genesis yet — fresh build.
+
+---
+
+## Available workspace deps on genesis
+
+| Package | Role |
+|---|---|
+| `@suaveplan/error` (`workspace:^`) | `DestructiblesError`; `DESTRUCT.*` codes |
+| `@suaveplan/types` (`workspace:^`) | `Clock`, `IdGenerator` |
+| `@suaveplan/events` (`workspace:^`) | `destructible:fracture`, `destructible:debris:expired` events |
+| `@suaveplan/combat` (`workspace:^`) | `DamageEvent` consumed to damage destructibles |
+| `zod` (`catalog:forms`) | `FracturePattern`, `LootTable` schemas |
+| `@opentelemetry/api` (`catalog:observability`) | Fracture event counter |
+
+---
+
+## Public API surface
+
+```ts
+interface FragmentDescriptor {
+  id: string
+  relativePosition: Vec3
+  mass: number
+  spawnProbability: number    // 0–1
+  impulse?: Vec3
+}
+
+interface FracturePattern {
+  fragments: FragmentDescriptor[]
+  debrisLifetime?: number     // seconds; undefined = permanent
+}
+
+interface LootEntry {
+  itemId: string
+  probability: number
+  quantity: [min: number, max: number]
+}
+
+interface LootTable {
+  entries: LootEntry[]
+  rollCount: [min: number, max: number]
+}
+
+function createDestructibleObject(options: DestructibleOptions): DestructibleObject
+
+interface DestructibleOptions {
+  id: string
+  maxHealth: number
+  fracturePattern: FracturePattern
+  lootTable?: LootTable
+  clock?: Clock
+}
+
+interface DestructibleObject {
+  readonly id: string
+  readonly health: number
+  readonly isDestroyed: boolean
+  applyDamage(event: DamageEvent): void
+  fracture(rng: Rng): FractureResult
+  repair(amount?: number): void
+}
+
+interface FractureResult {
+  fragments: SpawnedFragment[]
+  loot: DroppedItem[]
+}
+
+interface SpawnedFragment {
+  id: string
+  position: Vec3
+  impulse: Vec3
+  expiresAt?: number
+}
+
+interface DroppedItem {
+  itemId: string
+  quantity: number
+  position: Vec3
+}
+
+// Debris manager
+function createDebrisManager(options?: DebrisManagerOptions): DebrisManager
+
+interface DebrisManager {
+  add(fragment: SpawnedFragment): void
+  tick(dt: number): ExpiredFragment[]
+  getActive(): SpawnedFragment[]
+  clear(): void
+}
+```
+
+### Error codes
+
+```ts
+type DestructErrorCode =
+  | 'DESTRUCT_OBJECT_NOT_FOUND'
+  | 'DESTRUCT_ALREADY_DESTROYED'
+  | 'DESTRUCT_INVALID_PATTERN'
+  | 'DESTRUCT_LOOT_FAILED'
+```
+
+---
+
+## New additions for genesis
+
+1. **RNG-driven loot rolls** — injectable `Rng` from `@suaveplan/types` for deterministic loot in tests.
+2. **Debris lifetime timer** — `DebrisManager.tick()` returns expired fragments for physics engine cleanup.
+3. **OTel** — `destructible.fractures_total` counter; `destructible.loot_drops_total` counter.
+
+---
+
+## File layout
+
+```text
+gaming/combat/destructibles/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    error-codes.ts
+    constants/index.ts
+    types/common.ts
+    types/common.md
+    core/
+      destructible-object/
+        destructible-object.ts
+        destructible-object.md
+        destructible-object.types.ts
+        destructible-object.test.ts
+        index.ts
+      debris-manager/
+        debris-manager.ts
+        debris-manager.md
+        debris-manager.types.ts
+        debris-manager.test.ts
+        index.ts
+    utils/
+      loot-roller.ts
+      loot-roller.md
+      loot-roller.test.ts
+  tests/
+    integration.test.ts
+```
+
+---
+
+## Impact
+
+**Downstream**: `@suaveplan/r3f-combat` spawns visual fragments from `FractureResult`. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/combat`.

openspec/changes/enterprise-gaming-destructibles/tasks.md

@@ -0,0 +1,45 @@
+# Tasks: enterprise-gaming-destructibles
+
+## 0. Pre-flight (non-negotiable)
+
+- [ ] 0.1 Confirm clean working tree (`git status` reports nothing) and no in-flight worktrees with uncommitted work (`git worktree list` then `git status` in each)
+- [ ] 0.2 If any worktrees exist under `.claude/worktrees/`, account for each one: still-active agent, work-pending-merge, or stale-and-prune. Stale worktrees MUST be removed (`git worktree remove`) before opening a new one — code that has been lost twice on main is the failure mode this guards against.
+- [ ] 0.3 Confirm the package set in `MANIFEST.md` matches `find packages -maxdepth 3 -name package.json` count. Drift here means a prior change archived without regenerating the manifest.
+
+## Phase 1 — Scaffold
+
+- [ ] Create `gaming/combat/destructibles/` (`@suaveplan/destructibles`, `0.1.0`, `sideEffects: false`)
+- [ ] `tsconfig.json`, `vitest.config.ts`
+
+## Phase 2 — Error codes & constants
+
+- [ ] `src/error-codes.ts` + `src/constants/index.ts`
+
+## Phase 3 — Types
+
+- [ ] `src/types/common.ts` + `common.md`
+
+## Phase 4 — Loot roller
+
+- [ ] `src/utils/loot-roller.ts` — probability roll with injectable Rng, quantity range
+- [ ] Tests + docs
+
+## Phase 5 — Destructible object
+
+- [ ] `src/core/destructible-object/destructible-object.ts` — health tracking, fracture trigger, loot drop, OTel
+- [ ] Tests + docs
+
+## Phase 6 — Debris manager
+
+- [ ] `src/core/debris-manager/debris-manager.ts` — add/tick/getActive/clear, lifetime expiry
+- [ ] Tests + docs
+
+## Phase 7 — Integration tests
+
+- [ ] `tests/integration.test.ts` — damage → fracture → loot → debris expiry
+
+## Phase 8 — Pre-publish gate
+
+- [ ] `bunx turbo lint typecheck test --filter=@suaveplan/destructibles` green
+- [ ] 100% coverage
+- [ ] Publish: `bun scripts/publish.ts --package @suaveplan/destructibles`