Initial Commit

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

@@ -0,0 +1,159 @@
+# OpenSpec Change: enterprise-gaming-crafting
+
+- **Change ID**: enterprise-gaming-crafting
+- **Package**: `@suaveplan/crafting`
+- **Category**: gaming/narrative
+- **Target path**: `gaming/narrative/crafting`
+- **Status**: PROPOSED
+- **Date**: 2026-04-24
+- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/crafting.md`
+
+---
+
+## Summary
+
+Deliver `@suaveplan/crafting` on the genesis branch from scratch at enterprise quality. The package provides recipe-based crafting with stations, material requirements, quality tiers, and crafting queues. A `RecipeRegistry` holds typed `RecipeDefinition` objects; `CraftingStation` manages a per-station craft queue with concurrent slot limits and duration timers; `QualityCalculator` computes output quality from input material quality and skill level. Genesis adds Zod recipe schemas, structured errors, OTel craft counter, injectable clock, 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:^`) | `CraftingError`; `CRAFT.*` codes |
+| `@suaveplan/types` (`workspace:^`) | `Clock`, `IdGenerator` |
+| `@suaveplan/events` (`workspace:^`) | `craft:started`, `craft:complete`, `craft:failed` events |
+| `zod` (`catalog:forms`) | `RecipeDefinition` schema |
+| `@opentelemetry/api` (`catalog:observability`) | Craft completion counter |
+
+---
+
+## Public API surface
+
+```ts
+type QualityTier = 'poor' | 'normal' | 'fine' | 'superior' | 'masterwork'
+
+interface Ingredient {
+  itemId: string
+  quantity: number
+  qualityMin?: QualityTier
+}
+
+interface RecipeDefinition {
+  id: string
+  name: string
+  stationType: string
+  ingredients: Ingredient[]
+  outputItemId: string
+  outputQuantity: number
+  craftTime: number        // seconds
+  skillRequired?: number   // 0–100
+  outputQualityBase?: QualityTier
+}
+
+function createRecipeRegistry(): RecipeRegistry
+interface RecipeRegistry {
+  register(recipe: RecipeDefinition): void
+  get(id: string): RecipeDefinition | undefined
+  listByStation(stationType: string): RecipeDefinition[]
+}
+
+function createCraftingStation(options: StationOptions): CraftingStation
+
+interface StationOptions {
+  type: string
+  maxSlots?: number        // concurrent crafts, default 1
+  clock?: Clock
+  registry: RecipeRegistry
+}
+
+interface CraftingStation {
+  canCraft(recipeId: string, inventory: Map<string, number>): boolean
+  startCraft(recipeId: string, inventory: Map<string, number>, skill?: number): CraftJob
+  tick(dt: number): CompletedCraft[]
+  getQueue(): CraftJob[]
+  cancelJob(jobId: string): void
+}
+
+interface CraftJob {
+  jobId: string
+  recipeId: string
+  startedAt: number
+  duration: number
+  skill: number
+}
+
+interface CompletedCraft {
+  jobId: string
+  recipeId: string
+  outputItemId: string
+  quantity: number
+  quality: QualityTier
+}
+```
+
+### Error codes
+
+```ts
+type CraftErrorCode =
+  | 'CRAFT_RECIPE_NOT_FOUND'
+  | 'CRAFT_MISSING_INGREDIENTS'
+  | 'CRAFT_STATION_FULL'
+  | 'CRAFT_SKILL_TOO_LOW'
+  | 'CRAFT_JOB_NOT_FOUND'
+```
+
+---
+
+## New additions for genesis
+
+1. **Quality calculator** — output quality = base + skill bonus; `masterwork` requires skill ≥ 90.
+2. **Concurrent slot queue** — `maxSlots` allows parallel crafting at upgraded stations.
+3. **Ingredient quality minimum** — recipe can require `qualityMin`; fails if inventory item below tier.
+
+---
+
+## File layout
+
+```text
+gaming/narrative/crafting/
+  package.json
+  tsconfig.json
+  vitest.config.ts
+  src/
+    index.ts
+    error-codes.ts
+    constants/index.ts
+    types/common.ts
+    types/common.md
+    core/
+      recipe-registry/
+        recipe-registry.ts
+        recipe-registry.md
+        recipe-registry.test.ts
+        index.ts
+      crafting-station/
+        crafting-station.ts
+        crafting-station.md
+        crafting-station.types.ts
+        crafting-station.test.ts
+        index.ts
+    utils/
+      quality-calculator.ts
+      quality-calculator.md
+      quality-calculator.test.ts
+  tests/
+    integration.test.ts
+```
+
+---
+
+## Impact
+
+**Downstream**: `@suaveplan/react-crafting` displays station queue and recipe list. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`.