Initial Commit

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

@@ -0,0 +1,181 @@
+# OpenSpec Change: enterprise-gaming-fauna
+
+- **Change ID**: enterprise-gaming-fauna
+- **Package**: `@suaveplan/fauna`
+- **Category**: gaming/ai
+- **Target path**: `gaming/ai/fauna`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/fauna.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/fauna` on the genesis branch from scratch at enterprise quality. The package provides wildlife AI with herding behavior (Reynolds boids), predator-prey state machines, territorial zones, and taming mechanics. `HerdSimulator` runs separation/alignment/cohesion forces for a group of fauna instances; `PredatorPreyFsm` manages hunt/flee/rest state transitions; `TerritoryZone` defines a radius around a home position that triggers defend behavior when intruders enter; `TamingManager` tracks taming progress and trust state. Genesis adds Zod species definition schemas, structured errors, OTel population gauge, injectable clock and RNG, 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:^`) | `FaunaError`; `FAUNA.*` codes |
+| `@suaveplan/types` (`workspace:^`) | `Clock`, `Rng` |
+| `@suaveplan/events` (`workspace:^`) | `fauna:hunt`, `fauna:flee`, `fauna:tamed` events |
+| `@suaveplan/npc` (`workspace:^`) | `SpawnPool` extended for wildlife instances |
+| `@suaveplan/spatial-hash` (`workspace:^`) | Neighbor queries for boid steering |
+| `zod` (`catalog:forms`) | `SpeciesDefinition` schema |
+| `@opentelemetry/api` (`catalog:observability`) | Herd size gauge, hunt counter |
+
+---
+
+## Public API surface
+
+```ts
+interface SpeciesDefinition {
+  id: string
+  name: string
+  role: 'prey' | 'predator' | 'neutral'
+  maxSpeed: number
+  perception: number       // detection radius (meters)
+  territory?: number       // home territory radius
+  herds?: boolean
+  canBeTamed?: boolean
+  tamingDifficulty?: number   // 1–10
+}
+
+// Boid herding
+function createHerdSimulator(options: HerdOptions): HerdSimulator
+
+interface HerdOptions {
+  separationRadius: number
+  alignmentRadius: number
+  cohesionRadius: number
+  separationWeight?: number
+  alignmentWeight?: number
+  cohesionWeight?: number
+  spatialHash?: SpatialHash3D
+}
+
+interface HerdSimulator {
+  update(agents: HerdAgent[], dt: number): HerdUpdate[]
+}
+
+interface HerdAgent {
+  id: string
+  position: Vec3
+  velocity: Vec3
+}
+
+interface HerdUpdate {
+  id: string
+  steering: Vec3    // force to add to velocity
+}
+
+// Predator-prey FSM
+type FaunaState = 'rest' | 'wander' | 'alert' | 'hunt' | 'flee' | 'defend'
+
+function createPredatorPreyFsm(def: SpeciesDefinition, clock?: Clock): PredatorPreyFsm
+
+interface PredatorPreyFsm {
+  update(context: FaunaContext): FaunaState
+  readonly state: FaunaState
+}
+
+interface FaunaContext {
+  nearbyPrey: string[]
+  nearbyPredators: string[]
+  nearbyPlayers: string[]
+  distanceToHome?: number
+  health: number
+  hungerLevel: number    // 0–1
+}
+
+// Taming
+function createTamingManager(clock?: Clock): TamingManager
+
+interface TamingManager {
+  startTaming(playerId: string, faunaId: string, difficulty: number): void
+  applyTamingAction(playerId: string, faunaId: string, action: TamingAction): TamingResult
+  getProgress(playerId: string, faunaId: string): number   // 0–1
+  isTamed(faunaId: string): boolean
+}
+
+type TamingAction = 'feed' | 'pet' | 'speak' | 'bribe'
+
+interface TamingResult {
+  progress: number
+  tamed: boolean
+  failed: boolean
+}
+```
+
+### Error codes
+
+```ts
+type FaunaErrorCode =
+  | 'FAUNA_SPECIES_NOT_FOUND'
+  | 'FAUNA_NOT_TAMEABLE'
+  | 'FAUNA_TAMING_FAILED'
+  | 'FAUNA_TERRITORY_INVALID'
+```
+
+---
+
+## New additions for genesis
+
+1. **Boid steering** — separation/alignment/cohesion using `@suaveplan/spatial-hash` neighbor queries.
+2. **Hunger drive** — `hungerLevel` escalates over time (injectable clock); at threshold, switches FSM to `hunt`.
+3. **Taming trust decay** — idle taming sessions lose progress over time; `feed`/`pet` actions advance faster at low fear.
+4. **OTel** — `fauna.herd_size` gauge; `fauna.hunts_total` counter; `fauna.tamed_total` counter.
+
+---
+
+## File layout
+
+```text
+gaming/ai/fauna/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    error-codes.ts
+    constants/index.ts
+    types/common.ts
+    types/common.md
+    core/
+      herd-simulator/
+        herd-simulator.ts
+        herd-simulator.md
+        herd-simulator.types.ts
+        herd-simulator.test.ts
+        index.ts
+      predator-prey-fsm/
+        predator-prey-fsm.ts
+        predator-prey-fsm.md
+        predator-prey-fsm.types.ts
+        predator-prey-fsm.test.ts
+        index.ts
+      taming-manager/
+        taming-manager.ts
+        taming-manager.md
+        taming-manager.types.ts
+        taming-manager.test.ts
+        index.ts
+  tests/
+    integration.test.ts
+```
+
+---
+
+## Impact
+
+**Downstream**: `@suaveplan/r3f-npc` renders fauna instances using the same pipeline as NPCs. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/npc`, `@suaveplan/spatial-hash`.