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

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

type CraftErrorCode =
  | 'CRAFT_RECIPE_NOT_FOUND'
  | 'CRAFT_MISSING_INGREDIENTS'
  | 'CRAFT_STATION_FULL'
  | 'CRAFT_SKILL_TOO_LOW'
  | 'CRAFT_JOB_NOT_FOUND'

New additions for genesis

Quality calculator — output quality = base + skill bonus; masterwork requires skill ≥ 90.
Concurrent slot queue — maxSlots allows parallel crafting at upgraded stations.
Ingredient quality minimum — recipe can require qualityMin; fails if inventory item below tier.

File layout

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.

4.1 KiB Raw Blame History Unescape Escape