1124 lines
92 KiB
Markdown
1124 lines
92 KiB
Markdown
# Phase 1: Level-Up (PF2e regelkonform) — Research
|
||
|
||
**Researched:** 2026-04-27
|
||
**Domain:** PF2e rules-correct character level-up with wizard UI, prereq DSL, recompute pipeline, atomic persistence, snapshot history, Free Archetype variant, and spellcaster progression — built on the existing NestJS 11 / React 19 / Prisma 7 / PostgreSQL stack
|
||
**Confidence:** HIGH (codebase patterns, package versions, prereq corpus all verified locally; PF2e rules cited from Archives of Nethys; Foundry pf2e schema verified against live JSON; remaining LOW items called out explicitly)
|
||
|
||
<user_constraints>
|
||
## User Constraints (from CONTEXT.md)
|
||
|
||
### Locked Decisions
|
||
|
||
**Prereq-DSL-Scope (LVL-09)**
|
||
- **D-01:** Evaluierbare Patterns: Skill-Rang (Trained/Expert/Master/Legendary in named skill), Feat-Besitz (named feat), Level, Klasse, Ancestry, Heritage. Ergibt laut Research ~80%+ Coverage gängiger Feats.
|
||
- **D-02:** Nicht-evaluierbar (→ Warnung): Deity, Spellcasting-Tradition, Multi-Class-Archetyp-Sonderfälle, Free-Text-Bedingungen wie "You worship a god of...".
|
||
- **D-03:** UI bei nicht-evaluierbarer Prereq: gelbes Warn-Icon mit Tooltip am Talent + Confirm-Dialog mit dem Voraussetzungs-Text beim "Wählen"-Klick (kein Hard-Block).
|
||
- **D-04:** Datenquelle der Prereq-Strings: bestehende `Feat.prerequisites: String?`-Spalte (existiert bereits in `server/prisma/schema.prisma:560`).
|
||
- **D-05:** Evaluator läuft im Wizard UND beim Pathbuilder-Import.
|
||
- **D-06:** Bei Import-Verletzung: Import läuft durch, Charakter wird angelegt, Banner am Charakter-Header zeigt "X Talente mit nicht erfüllter Voraussetzung". Kein Block.
|
||
|
||
**Free-Archetype-Regel (LVL-13)**
|
||
- **D-07:** Pathbuilder-Verhalten nach Dedication: Slot zeigt Talente JEDES Archetyps (Multi-Archetype erlaubt). Vor Dedication: Slot zeigt nur Dedication-Talente.
|
||
- **D-08:** Toggle-Storage: pro Charakter in den Char-Settings (einmal setzen, gilt für alle künftigen Level-Ups). Wizard-Schritt 0 zeigt eine Lese-Anzeige des Toggle-Status.
|
||
- **D-09:** Pathbuilder-Auto-Detect: FA-Toggle wird beim Import automatisch auf "aktiv" gesetzt, wenn Pathbuilder-JSON FA-Marker oder zusätzliche Class-Feat-Slots an geraden Levels enthält. Spieler kann nachträglich ändern.
|
||
|
||
**Wizard-Flow + DRAFT-Persistenz (LVL-11, LVL-12)**
|
||
- **D-10:** Step-by-Step-Modal mit dynamisch eingeblendeten Schritten (nur die für das Level relevanten). Reihenfolge: Klassenmerkmale → Boost-Set → Skill-Increase → Klassentalent → Fertigkeitstalent → Allgemein-Talent → Ancestry-Talent → FA-Slot → Spellcaster-Progression → Review. Mobile-friendly (ein Wahlpunkt pro Screen).
|
||
- **D-11:** DRAFT-Persistenz: neue Prisma-Tabelle `LevelUpSession` mit FK auf Charakter, JSON-State der Wahlen, `committedAt` nullable, optional `targetLevel`. Resume-on-Reload, Cross-Device.
|
||
- **D-12:** Live-Vorschau: nur im Review-Schritt. KEIN Live-Update pro Schritt.
|
||
- **D-13:** Permissions: Owner UND GM der Kampagne dürfen Level-Up starten. Pattern: `checkCharacterAccess` (Owner OR GM-of-campaign).
|
||
- **D-14:** Offene DRAFTs ohne Commit: bleiben unbegrenzt offen. Ein DRAFT pro Charakter (Constraint).
|
||
|
||
**Klassen+Spellcaster-Daten (LVL-08, LVL-14)**
|
||
- **D-15:** Neue Prisma-Tabelle `ClassProgression` pro `(className, level)` mit `grants: String[]`, `proficiencyChanges: Json`, `spellSlotIncrement: Json?`, `cantripIncrement: Int?`, `repertoireIncrement: Int?`, `choiceType: String?`, `choiceOptionsRef: String?`.
|
||
- **D-16:** Class-Scope v1: 16 Core+APG Klassen (Alchemist, Barbarian, Bard, Champion, Cleric, Druid, Fighter, Investigator, Monk, Oracle, Ranger, Rogue, Sorcerer, Swashbuckler, Witch, Wizard).
|
||
- **D-17:** Datenquelle für Seed: Foundry PF2e-System Repository (`https://github.com/foundryvtt/pf2e`). TS-Seed-Script (`server/prisma/seed-class-progression.ts`).
|
||
- **D-18:** Spellcaster-Repertoire-Increment (LVL-14, spontane Caster): eigener Wizard-Schritt. Slot-Increment automatisch.
|
||
- **D-19:** Wahl-Klassenmerkmale (Cleric Doctrine, Wizard School, Fighter Weapon Mastery, etc.): Wizard erkennt `choiceType` und schiebt dynamischen Sub-Schritt ein.
|
||
|
||
### Claude's Discretion
|
||
- Konkretes UI-Layout des Step-by-Step-Modals (Header, Footer-Buttons, Progress-Indicator) — fixiert in `01-UI-SPEC.md`
|
||
- Konkrete Spaltenstruktur des Review-Schritts — fixiert in `01-UI-SPEC.md`
|
||
- DRAFT-API-Endpoint-Naming — empfohlen unten in §Architecture Patterns
|
||
- JSON-Format des Snapshot-Vorher
|
||
- Genaue Error-Messages auf Deutsch
|
||
- Test-Granularität (mindestens: Boost-Cap-Logik, Skill-Increase-Cap, Prereq-Evaluator pro Pattern; integration-test für Commit-Transaktion)
|
||
|
||
### Deferred Ideas (OUT OF SCOPE — do NOT plan)
|
||
- Level-up-Historie-Ansicht im Charakterbogen (LVL-V2-01)
|
||
- Reverse-Level-Up (LVL-V2-02)
|
||
- Variant-Class-Features (Rogue Eldritch Trickster, Druid Wild Order Variants)
|
||
- Multi-Classing
|
||
- Live-Recompute-Vorschau in jedem Wizard-Schritt
|
||
- Remaster-Klassen (Magus, Summoner, Kineticist, Thaumaturge, Gunslinger, Inventor, Psychic) — v2
|
||
</user_constraints>
|
||
|
||
<phase_requirements>
|
||
## Phase Requirements
|
||
|
||
| ID | Description | Research Support |
|
||
|----|-------------|------------------|
|
||
| LVL-01 | Wizard zeigt alle level-relevanten Wahlpunkte | §Architecture Patterns (Wizard State Machine), §Standard Stack (XState v5), §UI-SPEC.md (already approved) |
|
||
| LVL-02 | Boosts L5/10/15/20: 4 Boosts, +2 unter 18, +1 ab 18 | §Standard Stack (`apply-attribute-boost.ts` pure module), §Pitfall #8 mitigation, §Validation Architecture (boost-cap unit tests) |
|
||
| LVL-03 | Klassentalent jedes geraden Levels mit Filter | §Standard Stack (PrereqEvaluator), §Code Examples (feat filter query) |
|
||
| LVL-04 | Fertigkeitstalent jedes geraden Levels mit Filter | §Standard Stack (PrereqEvaluator), §Code Examples |
|
||
| LVL-05 | Allgemein-Talent L3/7/11/15/19 (Skill-Talente erlaubt) | §Code Examples (general-or-skill filter) |
|
||
| LVL-06 | Skill-Increase L3+ mit Cap-Regel (T→E ab 3, E→M ab 7, M→L ab 15) | §Standard Stack (`skill-increase-cap.ts` pure module), §Validation Architecture |
|
||
| LVL-07 | Ancestry-Talent L5/9/13/17 mit Filter | §Standard Stack (PrereqEvaluator), §Architecture Patterns |
|
||
| LVL-08 | Klassenmerkmale automatisch aus Class-Progression-Tabelle | §Standard Stack (ClassProgression table + seed), §Code Examples (Foundry pf2e schema mapping) |
|
||
| LVL-09 | Prereq-DSL-Evaluator; nicht-evaluierbar = Warnung | §Standard Stack (PrereqEvaluator module), §Code Examples (parser grammar), §Pitfall coverage |
|
||
| LVL-10 | Auto-Recompute HP-Max, Saves, AC, Klassen-DC, Wahrnehmung | §Standard Stack (`recompute-derived-stats.ts`), §Architecture Patterns (Recompute Pipeline), §Pitfall #9 mitigation |
|
||
| LVL-11 | DRAFT-Session jederzeit abbrechbar / rückgängig vor Commit | §Standard Stack (LevelUpSession Prisma model), §Architecture Patterns (REST endpoints) |
|
||
| LVL-12 | Atomic Commit + Snapshot-Before in JSON | §Architecture Patterns (Atomic Commit Transaction), §Code Examples (Prisma `$transaction`), §Pitfall #9 mitigation |
|
||
| LVL-13 | Free-Archetype-Toggle pro Charakter | §Standard Stack (boolean field on Character), §Architecture Patterns (FA-Slot step) |
|
||
| LVL-14 | Spellcaster: Slot-/Cantrip-/Repertoire-Progression | §Standard Stack (spell-progression module), §Code Examples (Foundry classfeatures spellcasting JSON) |
|
||
| LVL-15 | Deutsche Übersetzung für Prereq-Texte und Klassenmerkmal-Beschreibungen via bestehender Translation-Pipeline | §Architecture Patterns (Translation integration), §Existing Code (TranslationsService) |
|
||
</phase_requirements>
|
||
|
||
## Project Constraints (from CLAUDE.md)
|
||
|
||
These directives from `./CLAUDE.md` are non-negotiable and the planner must verify compliance for every task:
|
||
|
||
| Constraint | How it constrains the plan |
|
||
|-----------|----------------------------|
|
||
| **TypeScript strict, keine `any`** | All new modules (`leveling/*.ts`, prereq-evaluator, recompute) must be fully typed. NestJS-eslint allows `any` (lint config disables `no-explicit-any`), but CLAUDE.md overrides — refuse `any`. |
|
||
| **Quality vor Geschwindigkeit, kein Quick-Fix** | Plan tasks for proper Prisma migrations, full unit-test coverage of pure modules, full Foundry-data-driven seed script — not stubbed-in tables. |
|
||
| **Daten in Datenbank, nichts zur Laufzeit aus JSON-Dateien** | `ClassProgression` data MUST live in Postgres after seed, never read from JSON files at runtime. |
|
||
| **Prisma `migrate dev`, niemals `db push`** | New tables get a real migration file under `server/prisma/migrations/`. |
|
||
| **Deutsche UI durchgehend, keine Emojis, nur Lucide Icons** | Already enforced in `01-UI-SPEC.md` — planner must keep all wizard copy German. |
|
||
| **Mobile-First, Touch-Targets ≥44px** | Already enforced in `01-UI-SPEC.md` (`h-11 w-11` on +/- buttons, stepper-dot wrappers). |
|
||
| **WebSocket: ein Broadcast nach Commit, nicht mehrere kleine Updates** | The new `level_up_committed` `CharacterUpdatePayload` variant is emitted exactly once at the end of the commit transaction (Pitfall #9). |
|
||
| **Test-Disziplin etabliert in dieser Phase** | First tests in the codebase ever — set the bar. Planner must include Wave-0 task to establish Jest infrastructure (it exists in `server/package.json` but has zero unit-test files alongside source). |
|
||
| **Self-hosted single-tenant — kein Multi-Tenant-Bedarf** | No Tenant scoping needed; permission model stays GM-or-Owner. |
|
||
| **Push-Plattform = Web Push, kein Native-Wrapper** | Not relevant to this phase. |
|
||
|
||
## Summary
|
||
|
||
Phase 1 builds a regelkonform PF2e Level-Up wizard on the existing Dimension47 stack (NestJS 11.0.1 + React 19.2.0 + Prisma 7.2.0 + PostgreSQL + Socket.io 4.8.3 + Tailwind v4). The implementation is six-layered: (1) two new Prisma tables — `LevelUpSession` (DRAFT JSON-state per character with a partial unique index forcing one DRAFT at a time) and `ClassProgression` (one row per `(className, level)` with grants/proficiencyChanges/spell-slot/repertoire/choiceType columns); (2) a TS seed script `server/prisma/seed-class-progression.ts` that pulls from the Foundry pf2e repo (Apache 2.0 + OGL 1.0a + Paizo Community Use Policy — verified) at build time, transforms its JSON into our schema, and remains idempotent across re-runs; (3) four pure-function modules with full Jest unit-test coverage (`apply-attribute-boost.ts`, `skill-increase-cap.ts`, `prereq-evaluator.ts`, `recompute-derived-stats.ts`); (4) a NestJS `LevelingModule` exposing four REST endpoints (POST start / PATCH state / POST commit / DELETE discard) using `prisma.$transaction([...])` for the atomic commit; (5) a React `level-up-wizard.tsx` modal already specified component-by-component in `01-UI-SPEC.md`, recommended to drive its dynamic conditional steps with **plain `useReducer` + a JSON-serializable state shape** (XState v5 is overkill for a linear wizard whose only branching is "is this step applicable at level N for this class"); (6) one new `level_up_committed` variant on `CharacterUpdatePayload` broadcast exactly once after commit.
|
||
|
||
The single highest-risk item is the **Foundry pf2e data shape**: class JSONs (`packs/classes/<class>.json`) reference compendium UUIDs (`Compendium.pf2e.classfeatures.Item.<Name>`) and the actual mechanical progressions (spell slot tables, proficiency-rank-by-level for Fighter weapon mastery, etc.) live in **separate compendium files** that the seed script must follow and join. Spell-slot progression is **not** in the class JSON — it lives in classfeatures like `wizard-spellcasting.json` and is encoded textually in the description, NOT as machine-readable rules. This means the seed script will need a small per-class hand-curated overlay of spell-slot/cantrip tables for the spontaneous + prepared casters in scope (covered in §Code Examples and §Open Questions).
|
||
|
||
The Prereq-DSL evaluator is high-confidence: a 5,625-feat corpus already lives in `server/prisma/data/featlevels.json`, of which 3,393 (60.3%) carry prereqs. A pattern audit (§Code Examples) shows pure skill-rank covers 345 feats, skill-rank-with-or/and another ~125, heritage refs 112, ancestry/instinct/cause/order/muse refs ~132, deity refs 29, age/ethnicity 11. With D-01's evaluable patterns (skill rank, feat possession, level, class, ancestry, heritage), realistic mechanical coverage is **70-80% of all feats**, with the remainder triggering the warning path (D-03). This matches the CONTEXT.md estimate.
|
||
|
||
**Primary recommendation:** Implement in five waves — Wave 0 (Jest infrastructure + Prisma migration scaffolding), Wave 1 (pure-function modules + their tests, no DB), Wave 2 (`ClassProgression` seed pipeline against Foundry data), Wave 3 (`LevelingModule` REST + atomic commit + `CharactersGateway` extension), Wave 4 (React wizard against the already-approved `01-UI-SPEC.md`). Use plain `useReducer` for wizard state — not XState — because the conditional-step logic is a pure function of `(targetLevel, characterClass, hasFA, isCaster)` and serializes trivially to JSON for DRAFT persistence.
|
||
|
||
## Architectural Responsibility Map
|
||
|
||
| Capability | Primary Tier | Secondary Tier | Rationale |
|
||
|------------|-------------|----------------|-----------|
|
||
| Prereq DSL parsing/evaluation | API / Backend | — | Evaluator runs at wizard step (server filters feat list) AND at Pathbuilder import (D-05) — must be one shared TS module. Pure function, no DB calls itself, but called from server services. |
|
||
| Level-up DRAFT persistence | Database / Storage | API / Backend | `LevelUpSession.state: Json` survives reload + cross-device (D-11). Database is the source of truth; backend exposes the CRUD on it. |
|
||
| Live recompute (HP-Max, AC, Saves, DC, Wahrnehmung) | API / Backend | — | Pure deterministic function on the server side, called inside the commit transaction. Kept off the client to prevent diff drift — Review screen renders backend-computed numbers (D-12). |
|
||
| Wizard step state (which step / which choice / draft serialization) | Browser / Client | API / Backend | Step navigation, "selected this card", "boost-counts so far" are client UI state; PATCHed up to the DRAFT row on each step transition for cross-device resume. |
|
||
| Commit atomicity | API / Backend | Database / Storage | `prisma.$transaction([...])` wraps snapshot insert + character mutations + history insert + session delete + broadcast (Pitfall #9). |
|
||
| Single broadcast `level_up_committed` | API / Backend | — | After transaction commit, the gateway emits exactly one event; client reconciles. Not the client's job to compose the event. |
|
||
| Pathbuilder-import prereq violations banner | API / Backend | Browser / Client | Server runs evaluator during import (D-05/D-06), persists violation list (proposal: `Character.prereqViolations: Json?`), client renders the banner from server data. |
|
||
| Class progression data | Database / Storage | Build/Seed | `ClassProgression` table seeded once from Foundry pf2e (D-15/D-17), read by both server (commit recompute) and indirectly via API for the wizard (the wizard only sees server-derived "what choices are available"). |
|
||
| Class-feature choice options (Cleric Doctrine, Wizard School) | Database / Storage | API / Backend | Stored in `ClassProgression.choiceOptionsRef` with the actual options seeded as part of the same pipeline. Server resolves the ref → option list when the wizard requests it. |
|
||
| Translation of new prereq + class-feature text | API / Backend | Database / Storage | Existing `TranslationsService` + `Translation` table (D-15 carry-forward) handles batch translation on demand from Claude API, cached in Postgres. No new table needed. |
|
||
|
||
## Standard Stack
|
||
|
||
### Core (already installed — no new packages)
|
||
|
||
| Library | Version | Purpose | Why Standard |
|
||
|---------|---------|---------|--------------|
|
||
| `@nestjs/common` | 11.0.1 | LevelingModule + Controller + DTOs | Existing module-per-feature pattern — no choice |
|
||
| `@nestjs/websockets` | 11.1.12 | Extension of CharactersGateway with `level_up_committed` event type | Existing gateway pattern; event union is just expanded |
|
||
| `@prisma/client` | 7.2.0 | LevelUpSession + ClassProgression + transactional commit | Existing ORM — `$transaction([...])` directly supports atomic multi-table writes [VERIFIED: Prisma docs] |
|
||
| `class-validator` | 0.14.3 | DTO validation for the four new REST endpoints | Existing pattern in `server/src/modules/characters/dto/` |
|
||
| `class-transformer` | 0.5.1 | DTO transform | Existing pattern |
|
||
| `@nestjs/jwt` | 11.0.2 | Reuse existing JwtAuthGuard for the new endpoints | Existing pattern; no new auth surface |
|
||
| `react` | 19.2.0 | Wizard component | Existing |
|
||
| `react-dom` | 19.2.0 | — | Existing |
|
||
| `framer-motion` | 12.26.2 | Step transitions (already declared in UI-SPEC) | Already installed via UI-SPEC |
|
||
| `lucide-react` | 0.562.0 | Icons (already declared in UI-SPEC) | Existing |
|
||
| `clsx` + `tailwind-merge` | 2.1.1 / 3.4.0 | Class composition (`cn()` helper already in `client/src/shared/lib/utils.ts`) | Existing |
|
||
| `tailwindcss` | 4.1.18 | Styling | Existing |
|
||
| `@tanstack/react-query` | 5.90.19 | Wizard's REST mutations (start / patch / commit / discard) | Existing — use `useMutation` for each endpoint |
|
||
| `axios` | 1.13.2 | HTTP transport via existing `client/src/shared/lib/api.ts` | Existing |
|
||
|
||
### Supporting (already installed — for the Wave-0 test infrastructure)
|
||
|
||
| Library | Version | Purpose | When to Use |
|
||
|---------|---------|---------|-------------|
|
||
| `jest` | 30.0.0 | Test runner for the four pure-function modules | Wave 1 — first real unit tests in this codebase [VERIFIED: `server/package.json:88-104` and `npm view jest version` → 30.3.0 latest, we are on 30.0.0 which is fine] |
|
||
| `ts-jest` | 29.x | TS compile shim for Jest | Existing in package.json (`testRegex: ".*\\.spec\\.ts$"`) |
|
||
| `@nestjs/testing` | 11.x | Test module builder for the LevelingService integration test | Existing |
|
||
| `supertest` | 7.0.0 | HTTP integration test for commit endpoint | Existing |
|
||
|
||
### Considered and rejected
|
||
|
||
| Considered | Rejected because |
|
||
|------------|------------------|
|
||
| **XState v5** (`xstate` 5.30.0 + `@xstate/react` 6.1.0 [VERIFIED: npm view 2026-04-27]) for the wizard state machine | Wizard is a linear flow with conditional step visibility. The branching is `(level, class, hasFA, isCaster) → list of steps`, computed once at start. No complex parallel states, no orthogonal regions, no nested machines. `useReducer` + a typed `WizardState` discriminated union covers it in ~80 lines, serializes natively to JSON for DRAFT persistence, and stays in the React idiom the rest of the codebase uses. XState would add ~30KB minified + a learning curve for what is fundamentally a list of steps with a cursor. **Recommend `useReducer`** — keep XState in the toolbox if a future wave proves the state space is actually graph-shaped. |
|
||
| **`zod`** (4.3.6) for runtime schema validation of the wizard JSON-state on commit | The codebase uses `class-validator` + `class-transformer` (existing convention). Adding `zod` for one feature creates two parallel validation cultures. Use class-validator decorators on the DTOs; for the in-flight wizard state inside `LevelUpSession.state`, persist it as `Json` and validate the shape in a hand-written guard function in TypeScript (the shape is fully under our control — no third-party schemas). |
|
||
| **`simple-git`** (3.36.0) inside the seed script to clone Foundry pf2e | Adds a dev dependency for a one-shot operation. Use plain `child_process.execSync('git clone ...')` or, better, instruct devs to clone the foundry repo to a known path under `server/prisma/data/foundry-pf2e/` (gitignored) and have the seed read JSONs from there. This keeps the seed script offline-capable and version-pinnable (the dev controls which Foundry tag is checked out). |
|
||
| **`p-limit`** for concurrency control inside the seed script | At ~16 classes × ~30 features each ≈ 500 file reads total, no concurrency limiting needed. Plain `await Promise.all()` over a small batch. |
|
||
|
||
**Installation:** None new. Phase 1 ships with zero new npm dependencies on either client or server.
|
||
|
||
**Version verification (HIGH confidence):** All listed versions confirmed against `client/package.json` + `server/package.json` + (where bumped) `npm view <pkg> version` on 2026-04-27. Jest 30.0.0 is current major (latest 30.3.0); XState 5.30.0 / @xstate/react 6.1.0 verified but not adopted; zod 4.3.6 verified but not adopted.
|
||
|
||
## Architecture Patterns
|
||
|
||
### System Architecture Diagram
|
||
|
||
```
|
||
┌─────────────────────────────────────────┐
|
||
│ User on Charakter-Sheet │
|
||
│ clicks "Stufe steigen" (or "Fortsetzen")│
|
||
└──────────────────┬──────────────────────┘
|
||
│ HTTP POST
|
||
▼
|
||
┌────────────────────────────────────────────────┐
|
||
│ POST /characters/:id/level-up │
|
||
│ LevelUpController.startSession() │
|
||
└──────────────────┬─────────────────────────────┘
|
||
│
|
||
┌───────────────────────▼───────────────────────────┐
|
||
│ LevelingService.startOrResume() │
|
||
│ • checkCharacterAccess (Owner OR GM) │
|
||
│ • check level < 20 │
|
||
│ • find existing OPEN LevelUpSession (one max) │
|
||
│ • else create new with default state │
|
||
└───────────────────────┬───────────────────────────┘
|
||
│
|
||
▼
|
||
┌──────────────────────────────────────────┐
|
||
│ LevelUpSession (DB) │
|
||
│ characterId, targetLevel, state: Json, │
|
||
│ committedAt: null │
|
||
└──────────────────┬───────────────────────┘
|
||
│ session returned
|
||
▼
|
||
┌──────────────────────────────────────────┐
|
||
│ React: <LevelUpWizard sessionId=...> │
|
||
│ derives step list from │
|
||
│ computeApplicableSteps( │
|
||
│ targetLevel, class, hasFA, isCaster │
|
||
│ ) │
|
||
└──────────┬───────────────────────────────┘
|
||
│
|
||
┌─────────────────┼─────────────────┐
|
||
▼ ▼ ▼
|
||
┌──────────────┐ ┌────────────────┐ ┌────────────────┐
|
||
│ Step: Boost │ │ Step: Talent │ │ Step: Skill │
|
||
│ apply- │ │ filter via │ │ increase-cap │
|
||
│ attribute- │ │ PrereqEvaluator│ │ check │
|
||
│ boost.ts │ │ on Feat list │ │ │
|
||
└──────┬───────┘ └────────┬───────┘ └────────┬───────┘
|
||
│ │ │
|
||
└────────────────┬──┴───────────────────┘
|
||
│ each step: PATCH /level-up/:sessionId
|
||
▼
|
||
┌─────────────────────────────────────┐
|
||
│ LevelingService.patchState() │
|
||
│ • merge partial into session.state │
|
||
│ • validate guard fn │
|
||
│ • return updated session │
|
||
└────────────────┬────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────┐
|
||
│ User reaches Review step │
|
||
│ Wizard requests preview: │
|
||
│ GET /level-up/:sessionId/preview │
|
||
│ → recomputeDerivedStats( │
|
||
│ characterSnapshot, choices, │
|
||
│ progression │
|
||
│ ) │
|
||
│ Vorher/Nachher rendered │
|
||
└────────────────┬────────────────────┘
|
||
│ user clicks "Bestätigen"
|
||
▼
|
||
┌─────────────────────────────────────┐
|
||
│ POST /level-up/:sessionId/commit │
|
||
│ LevelingService.commit() │
|
||
│ prisma.$transaction([ │
|
||
│ 1. INSERT LevelUpHistory │
|
||
│ (snapshot of full character) │
|
||
│ 2. UPDATE Character (level, hp, │
|
||
│ …) │
|
||
│ 3. UPSERT CharacterAbility rows │
|
||
│ 4. UPSERT CharacterSkill rows │
|
||
│ 5. INSERT CharacterFeat rows │
|
||
│ 6. UPSERT CharacterResource │
|
||
│ (spell slots / focus / cantrip)│
|
||
│ 7. UPDATE LevelUpSession │
|
||
│ SET committedAt = now() │
|
||
│ (alt: DELETE — see §Decision) │
|
||
│ ]) │
|
||
│ charactersGateway.broadcast( │
|
||
│ {type:'level_up_committed', │
|
||
│ data: newDerivedStats + level} │
|
||
│ ) │
|
||
└─────────────────────────────────────┘
|
||
│
|
||
▼
|
||
┌─────────────────────────────────────┐
|
||
│ Other connected clients receive │
|
||
│ ONE WebSocket event; │
|
||
│ react-query invalidates the │
|
||
│ character query → fresh refetch. │
|
||
└─────────────────────────────────────┘
|
||
```
|
||
|
||
Pathbuilder-import side-channel (D-05/D-06):
|
||
```
|
||
Pathbuilder-import.service.importCharacter()
|
||
→ after creating Character + CharacterFeat rows
|
||
→ for each CharacterFeat: load Feat.prerequisites string
|
||
→ PrereqEvaluator.evaluate(prereqString, characterContext)
|
||
→ { ok: true } | { ok: false, reason } | { unknown: true, raw }
|
||
→ collect failed (ok:false) entries
|
||
→ write Character.prereqViolations: Json (new column)
|
||
→ Banner reads this column on character-sheet load
|
||
```
|
||
|
||
### Recommended Project Structure (kebab-case files per CONVENTIONS.md)
|
||
|
||
```
|
||
server/
|
||
├── prisma/
|
||
│ ├── migrations/
|
||
│ │ └── YYYYMMDDHHMMSS_add_level_up_sessions_and_class_progression/
|
||
│ │ └── migration.sql # raw SQL incl. partial unique index
|
||
│ ├── seed-class-progression.ts # NEW — Foundry pf2e → ClassProgression
|
||
│ └── data/
|
||
│ └── foundry-pf2e/ # gitignored — manual git clone
|
||
│ └── packs/classes/... # source for seed
|
||
└── src/
|
||
├── modules/
|
||
│ ├── characters/
|
||
│ │ ├── characters.gateway.ts # EXTENDED: union type adds 'level_up_committed'
|
||
│ │ ├── characters.service.ts # untouched (or trivially: expose getCharacterFullSnapshot)
|
||
│ │ └── pathbuilder-import.service.ts # EXTENDED: PrereqEvaluator call after import
|
||
│ └── leveling/ # NEW MODULE
|
||
│ ├── leveling.module.ts
|
||
│ ├── leveling.controller.ts # 4 REST endpoints
|
||
│ ├── leveling.service.ts # orchestration: start/patch/commit/discard
|
||
│ ├── dto/
|
||
│ │ ├── start-level-up.dto.ts
|
||
│ │ ├── patch-level-up.dto.ts
|
||
│ │ ├── commit-level-up.dto.ts
|
||
│ │ └── level-up-state.dto.ts # the in-flight JSON shape (also used in TS guards)
|
||
│ ├── lib/ # PURE-FUNCTION MODULES (no DI, all unit-tested)
|
||
│ │ ├── apply-attribute-boost.ts
|
||
│ │ ├── apply-attribute-boost.spec.ts
|
||
│ │ ├── skill-increase-cap.ts
|
||
│ │ ├── skill-increase-cap.spec.ts
|
||
│ │ ├── prereq-evaluator.ts
|
||
│ │ ├── prereq-evaluator.spec.ts
|
||
│ │ ├── recompute-derived-stats.ts
|
||
│ │ ├── recompute-derived-stats.spec.ts
|
||
│ │ ├── compute-applicable-steps.ts # used by both server + client
|
||
│ │ └── compute-applicable-steps.spec.ts
|
||
│ ├── feat-filter.service.ts # uses PrereqEvaluator + Prisma
|
||
│ └── leveling.service.spec.ts # integration: full commit transaction
|
||
|
||
client/
|
||
└── src/
|
||
└── features/
|
||
└── characters/
|
||
└── components/
|
||
├── character-sheet-page.tsx # EXTENDED: add "Stufe steigen" header button + DRAFT banner mount + violations banner mount
|
||
└── level-up/ # NEW FOLDER (UI-SPEC §"Component File Plan")
|
||
├── level-up-wizard.tsx
|
||
├── level-up-step-class-features.tsx
|
||
├── level-up-step-class-feature-choice.tsx
|
||
├── level-up-step-boost.tsx
|
||
├── level-up-step-skill-increase.tsx
|
||
├── level-up-step-feat-class.tsx
|
||
├── level-up-step-feat-skill.tsx
|
||
├── level-up-step-feat-general.tsx
|
||
├── level-up-step-feat-ancestry.tsx
|
||
├── level-up-step-feat-archetype.tsx
|
||
├── level-up-step-spellcaster.tsx
|
||
├── level-up-step-review.tsx
|
||
├── level-up-choice-card.tsx
|
||
├── level-up-prereq-confirm-dialog.tsx
|
||
├── level-up-resume-banner.tsx
|
||
├── level-up-violations-banner.tsx
|
||
├── use-level-up-session.ts # react-query hook stack
|
||
└── wizard-state-reducer.ts # plain useReducer + types
|
||
```
|
||
|
||
### Pattern 1 — Wizard State as `useReducer` + JSON-Serializable Discriminated Union
|
||
|
||
**What:** A single typed reducer drives the wizard. State is one TypeScript object, fully JSON-serializable, that maps 1:1 to `LevelUpSession.state` in the database.
|
||
|
||
**When to use:** This wizard. Conditional steps are pure functions of `(targetLevel, class, hasFA, isCaster)` computed once at start; back-navigation is index-based; Review-step revalidation is a re-walk of already-stored choices. No need for parallel/orthogonal/historical state — XState v5 would be overkill.
|
||
|
||
**Example:**
|
||
```ts
|
||
// client/src/features/characters/components/level-up/wizard-state-reducer.ts
|
||
export type StepKind =
|
||
| 'class-features' // auto, no input
|
||
| 'class-feature-choice' // dynamic per ClassProgression.choiceType
|
||
| 'boost' // L5/10/15/20
|
||
| 'skill-increase' // L3+
|
||
| 'feat-class' // even levels
|
||
| 'feat-skill' // even levels
|
||
| 'feat-general' // L3/7/11/15/19
|
||
| 'feat-ancestry' // L5/9/13/17
|
||
| 'feat-archetype' // when hasFA
|
||
| 'spellcaster' // when isCaster (slot or repertoire)
|
||
| 'review';
|
||
|
||
export type WizardState = {
|
||
sessionId: string;
|
||
targetLevel: number;
|
||
steps: StepKind[]; // computed once at start
|
||
currentIdx: number;
|
||
choices: {
|
||
boostTargets?: ('STR'|'DEX'|'CON'|'INT'|'WIS'|'CHA')[]; // exactly 4 distinct
|
||
skillIncrease?: { skillName: string; toRank: 'TRAINED'|'EXPERT'|'MASTER'|'LEGENDARY' };
|
||
featClassId?: string;
|
||
featSkillId?: string;
|
||
featGeneralId?: string;
|
||
featAncestryId?: string;
|
||
featArchetypeId?: string;
|
||
classFeatureChoices?: Record<string, string>; // choiceKey → optionId
|
||
spellcasterRepertoirePicks?: string[]; // spell IDs for spontaneous casters
|
||
};
|
||
acknowledgedNonEvaluablePrereqs: string[]; // featIds the user confirmed
|
||
revisionMode: { fromStep: number } | null; // tracks "Ändern" → "Zurück zur Übersicht"
|
||
};
|
||
|
||
export type WizardEvent =
|
||
| { type: 'GO_NEXT' }
|
||
| { type: 'GO_PREV' }
|
||
| { type: 'GO_TO_STEP'; idx: number; revisionFrom?: number }
|
||
| { type: 'SET_BOOST_TARGETS'; targets: WizardState['choices']['boostTargets'] }
|
||
| { type: 'SET_SKILL_INCREASE'; pick: WizardState['choices']['skillIncrease'] }
|
||
| { type: 'SET_FEAT'; slot: 'class'|'skill'|'general'|'ancestry'|'archetype'; featId: string }
|
||
| { type: 'SET_CLASS_FEATURE_CHOICE'; key: string; optionId: string }
|
||
| { type: 'SET_REPERTOIRE_PICKS'; picks: string[] }
|
||
| { type: 'ACKNOWLEDGE_PREREQ_WARNING'; featId: string }
|
||
| { type: 'RETURN_TO_REVIEW' }; // triggers chain re-validation
|
||
|
||
export function wizardReducer(state: WizardState, ev: WizardEvent): WizardState { /* ... */ }
|
||
```
|
||
[ASSUMED: this exact shape — the planner may refine field names; structure is pure recommendation based on `01-UI-SPEC.md` requirements.]
|
||
|
||
Persistence: every reducer step that produces a "real" choice (not just navigation) triggers `useMutation(patchSession)` with the new `state.choices` slice. Navigation-only events stay client-only.
|
||
|
||
### Pattern 2 — Atomic Commit with `prisma.$transaction([...])` (Pitfall #9)
|
||
|
||
**What:** Five+ tightly-coupled mutations become one all-or-nothing operation; the `level_up_committed` broadcast happens only after the transaction returns.
|
||
|
||
**When to use:** The single commit endpoint.
|
||
|
||
**Example:**
|
||
```ts
|
||
// server/src/modules/leveling/leveling.service.ts (excerpt)
|
||
async commit(sessionId: string, userId: string) {
|
||
const session = await this.loadSessionAndAuthorize(sessionId, userId);
|
||
const character = await this.loadCharacterFull(session.characterId);
|
||
const progression = await this.loadProgression(character.classId, session.targetLevel);
|
||
|
||
// 1. Pure recompute (no DB writes yet)
|
||
const newDerived = recomputeDerivedStats(character, session.state, progression);
|
||
const snapshotJson = buildSnapshotJson(character); // full character + relations subset
|
||
|
||
// 2. Atomic transaction
|
||
const result = await this.prisma.$transaction([
|
||
this.prisma.levelUpHistory.create({
|
||
data: {
|
||
characterId: character.id,
|
||
levelFrom: character.level,
|
||
levelTo: session.targetLevel,
|
||
snapshotBefore: snapshotJson,
|
||
choices: session.state,
|
||
committedAt: new Date(),
|
||
},
|
||
}),
|
||
this.prisma.character.update({
|
||
where: { id: character.id },
|
||
data: {
|
||
level: session.targetLevel,
|
||
hpMax: newDerived.hpMax,
|
||
// hpCurrent: NOT touched — Pitfall #9 docs the rule (HP-Max increase = new headroom, not heal)
|
||
},
|
||
}),
|
||
// ...batch CharacterAbility upserts (boost targets)
|
||
// ...batch CharacterSkill upserts (skill-increase + class-grant proficiency changes)
|
||
// ...batch CharacterFeat creates (5 talent slots possibly + class-feature-choice picks)
|
||
// ...batch CharacterResource upserts (spell slots, cantrips, focus)
|
||
// ...batch CharacterSpell creates (repertoire picks for spontaneous casters)
|
||
this.prisma.levelUpSession.update({
|
||
where: { id: sessionId },
|
||
data: { committedAt: new Date() }, // soft-archive (preferred) — see §Decision
|
||
}),
|
||
]);
|
||
|
||
// 3. SINGLE broadcast (Pitfall #9 + ROADMAP First-Phase Note)
|
||
this.charactersGateway.broadcastCharacterUpdate(character.id, {
|
||
characterId: character.id,
|
||
type: 'level_up_committed',
|
||
data: {
|
||
level: session.targetLevel,
|
||
derived: newDerived, // hpMax, ac, classDc, perception, fortitude, reflex, will
|
||
},
|
||
});
|
||
|
||
return result;
|
||
}
|
||
```
|
||
|
||
**Decision: keep committed sessions OR delete them?** Recommend **keep with `committedAt` set** (soft-archive). Reasons: (a) the partial unique index on `(characterId) WHERE committedAt IS NULL` already gives the "one DRAFT per character" constraint without deletion; (b) committed sessions are valuable audit trail (they tell you exactly which choices the user made for level N, separate from the snapshot-before in `LevelUpHistory`); (c) deletion makes the partial-index logic implicit and harder to debug. The deferred `LVL-V2-01` "Level-up Historie-Ansicht" reads exactly this kind of data.
|
||
|
||
### Pattern 3 — Pure-Function Module + Adjacent Spec File
|
||
|
||
**What:** All math (boost cap, skill increase cap, prereq evaluation, recompute) lives in `server/src/modules/leveling/lib/*.ts` with **no NestJS imports, no Prisma, no I/O**. Each has a `.spec.ts` next to it.
|
||
|
||
**When to use:** All four core logic modules in this phase. Pattern is also the cross-cutting precedent for all future phases per ROADMAP First-Phase Note.
|
||
|
||
**Example:**
|
||
```ts
|
||
// server/src/modules/leveling/lib/apply-attribute-boost.ts
|
||
export type AbilityScore = number;
|
||
|
||
/** Applies a single PF2e attribute boost. +2 if score < 18, +1 if score >= 18 (Pitfall #8). */
|
||
export function applyAttributeBoost(currentScore: AbilityScore): AbilityScore {
|
||
return currentScore >= 18 ? currentScore + 1 : currentScore + 2;
|
||
}
|
||
|
||
/** Validates a level-up boost set: must be exactly 4 distinct abilities. */
|
||
export function isValidBoostSet(targets: readonly string[]): boolean {
|
||
return targets.length === 4 && new Set(targets).size === 4;
|
||
}
|
||
```
|
||
|
||
```ts
|
||
// server/src/modules/leveling/lib/apply-attribute-boost.spec.ts
|
||
import { applyAttributeBoost, isValidBoostSet } from './apply-attribute-boost';
|
||
|
||
describe('applyAttributeBoost', () => {
|
||
it('adds +2 when below 18', () => expect(applyAttributeBoost(10)).toBe(12));
|
||
it('adds +2 when 17 (still below cap)', () => expect(applyAttributeBoost(17)).toBe(19)); // 17 → 19; the next boost would hit 20 from 19? No — at 18 the rule kicks in. Test with 17 keeps +2.
|
||
it('adds +1 when exactly 18 (cap rule)', () => expect(applyAttributeBoost(18)).toBe(19));
|
||
it('adds +1 when above 18', () => expect(applyAttributeBoost(20)).toBe(21));
|
||
it('handles edge: very high (24)', () => expect(applyAttributeBoost(24)).toBe(25));
|
||
});
|
||
|
||
describe('isValidBoostSet', () => {
|
||
it('accepts 4 distinct', () => expect(isValidBoostSet(['STR','DEX','CON','INT'])).toBe(true));
|
||
it('rejects duplicate', () => expect(isValidBoostSet(['STR','STR','CON','INT'])).toBe(false));
|
||
it('rejects too few', () => expect(isValidBoostSet(['STR','DEX','CON'])).toBe(false));
|
||
it('rejects too many', () => expect(isValidBoostSet(['STR','DEX','CON','INT','WIS'])).toBe(false));
|
||
});
|
||
```
|
||
|
||
### Pattern 4 — Prereq DSL Evaluator: Parser + Evaluator + Formatter (D-01..D-04)
|
||
|
||
**What:** Three layers in one file (`prereq-evaluator.ts`), each independently testable.
|
||
|
||
**Grammar (concrete from real corpus — see §Code Examples for the audit):**
|
||
```
|
||
PREREQUISITE := CLAUSE ( ';' CLAUSE )* // semicolon = AND
|
||
CLAUSE := DISJUNCT ( ',' DISJUNCT )* | DISJUNCT
|
||
DISJUNCT := ATOM ( ' or ' ATOM )* // 'or' = OR; comma usually = AND inside a clause; case "comma-separated alternatives" handled by heuristic
|
||
ATOM := SKILL_RANK | FEAT_REF | LEVEL_REF | CLASS_REF | ANCESTRY_REF | HERITAGE_REF | UNKNOWN
|
||
SKILL_RANK := /(trained|expert|master|legendary) in (.+?)/i
|
||
FEAT_REF := /(?:^|; )([A-Z][a-zA-Z' ]+)$/ // bare capitalized phrase, looked up in Feat table
|
||
LEVEL_REF := /level (\d+)/i
|
||
CLASS_REF := one of {Alchemist, Barbarian, … (16 classes)}
|
||
ANCESTRY_REF := one of {Human, Elf, Dwarf, … (51 ancestries)}
|
||
HERITAGE_REF := /(.+?) heritage/i
|
||
UNKNOWN := anything else → returns { unknown: true, raw }
|
||
```
|
||
|
||
The parser produces a tree; the evaluator walks it against `CharacterContext = { level, classId, ancestryId, heritageId, abilities, skills: Map<string,Proficiency>, feats: Set<featId> }`. The formatter produces a German human-readable reason string for the warning UI (D-03).
|
||
|
||
**Example (excerpt):**
|
||
```ts
|
||
export type EvalResult =
|
||
| { ok: true }
|
||
| { ok: false; reason: string } // evaluable AND fails
|
||
| { unknown: true; raw: string }; // not evaluable → triggers warning (D-03)
|
||
|
||
export function evaluatePrereq(prereqString: string | null, ctx: CharacterContext): EvalResult {
|
||
if (!prereqString) return { ok: true };
|
||
const tree = parsePrereq(prereqString);
|
||
if (tree.kind === 'unknown') return { unknown: true, raw: prereqString };
|
||
return evaluateTree(tree, ctx);
|
||
}
|
||
```
|
||
|
||
Evaluator returns `{ unknown: true, ... }` aggressively — when ANY atom is non-classifiable (e.g. "follower of Asmodeus", "spontaneous spellcaster"), the entire clause is marked unknown (kein Hard-Block per D-03). This is conservative and matches D-03's intent: when in doubt, ask the user.
|
||
|
||
### Pattern 5 — Recompute Derived Stats: Pure Pipeline
|
||
|
||
**What:** A pure function `recomputeDerivedStats(character, choices, progression) → DerivedStats` that the commit transaction calls AND the Review-step preview endpoint calls.
|
||
|
||
**Inputs:**
|
||
- Full Character snapshot (level, ancestry, class, abilities, skills, feats, hpCurrent, hpTemp)
|
||
- The wizard's `choices` (boost targets, skill-increase pick, etc.) — to know what's about to change
|
||
- ClassProgression row for `(className, targetLevel)` — for proficiency increases granted at this level
|
||
|
||
**Outputs:**
|
||
```ts
|
||
type DerivedStats = {
|
||
level: number;
|
||
hpMax: number; // recomputed: ancestryHP + (classHP + conMod) × level + bonusPerLevel × level
|
||
ac: number; // 10 + dexCap-clamped DEX-mod + armor.ac + proficiencyBonus(armor)
|
||
classDc: number; // 10 + keyAbility-mod + proficiencyBonus(class) — class-specific
|
||
perception: number; // wisMod + proficiencyBonus(perception)
|
||
fortitude: number; // conMod + proficiencyBonus(fort)
|
||
reflex: number; // dexMod + proficiencyBonus(ref)
|
||
will: number; // wisMod + proficiencyBonus(will)
|
||
};
|
||
```
|
||
|
||
**Boost-cap-at-18 enforcement** (Pitfall #8): the new ability scores are computed in this same module BEFORE the derived stats — `applyAttributeBoost()` is called per-target. The whole pipeline is one composition; Vorher-Nachher numbers in Review come from the same code path that the commit will write.
|
||
|
||
### Pattern 6 — Pathbuilder Auto-Detect for Free Archetype (D-09)
|
||
|
||
**Heuristic:** Pathbuilder JSON does not have an explicit `freeArchetype: true` flag in the typical export. The reliable signals are:
|
||
|
||
1. **Extra Class-Feat-Slot count.** Pathbuilder export (`build.feats`) contains feat entries tagged with their feat-type. If the count of `Class`-typed feats at any even level is 2 or more, OR if any feat is tagged `Archetype` at a level where the character would not otherwise have a class-feat slot for it, treat FA as active.
|
||
2. **Presence of any Archetype feat.** Any feat with feat-type `Archetype` and level > 1 is a strong indicator (without FA, the character would have spent their normal class-feat-slot for it — possible but suspicious if there are also full class feats at every even level).
|
||
|
||
Recommend the heuristic: `auto-detect FA = true if (count of Archetype-typed feats >= 2) OR (any even level has 2+ Class-or-Archetype feats)`. Set `Character.freeArchetype: true` on auto-detect; expose the toggle in character settings so the player can flip it.
|
||
|
||
**[ASSUMED: heuristic specifics — based on common Pathbuilder export shape; verify against an actual FA-enabled character export before locking. If the user has even one FA-enabled character on hand, run the seed script's auto-detect against it during Wave 0 verification.]**
|
||
|
||
### Anti-Patterns to Avoid
|
||
|
||
- **Live recompute on every wizard step.** D-12 explicitly forbids this. Recompute runs ONCE at the Review step and ONCE at commit. Keeps the wizard cheap, avoids per-PATCH transaction load, and prevents Review numbers from drifting from commit numbers.
|
||
- **Computing prereqs client-side.** The PrereqEvaluator runs on the server inside the feat-list endpoint that the wizard hits per step. Reasoning: (a) keeps the evaluator behind the auth boundary; (b) client never needs the full Feat table; (c) D-05 mandates the same evaluator runs at Pathbuilder import (server-only context); centralizing avoids two implementations that drift.
|
||
- **Putting `level_up_committed` data into multiple small broadcasts.** ROADMAP First-Phase Note pins this — single broadcast after transaction returns. Compose the full DerivedStats payload, emit once.
|
||
- **`db push` for the new tables.** CLAUDE.md and PROJECT.md explicitly forbid; use `prisma migrate dev` to author a real migration file.
|
||
- **`any` types in the wizard reducer or in the prereq evaluator.** TypeScript strict required (CLAUDE.md). The reducer's `WizardEvent` union and the evaluator's `EvalResult` union must be discriminated unions.
|
||
- **Reading Foundry pf2e JSON files at runtime.** D-15/D-17 mandate seed-time only. The runtime reads from `ClassProgression` rows.
|
||
- **Auto-removing dependent feats on retrain (Pitfall #10).** Out of scope for this phase — Reverse-Level-Up is `LVL-V2-02` deferred. But the schema still needs to allow it later: `LevelUpHistory` is append-only.
|
||
|
||
## Don't Hand-Roll
|
||
|
||
| Problem | Don't Build | Use Instead | Why |
|
||
|---------|-------------|-------------|-----|
|
||
| Atomic multi-table commit | A try/catch sequence of `await prisma.x.update(...)` | `prisma.$transaction([...])` array form | Prisma transactions roll back ALL writes on any failure; the manual sequence cannot guarantee consistency on partial-failure (Pitfall #9). [VERIFIED: Prisma 7 `$transaction([...])` is the same array-form supported since v2.] |
|
||
| One-DRAFT-per-character constraint | Application-level "first delete then insert" inside the start endpoint | A **partial unique index in the migration SQL** (`CREATE UNIQUE INDEX … WHERE committedAt IS NULL`) | Race-condition safe; enforced at DB level; the start-endpoint's "find or create" stays simple. Prisma schema cannot express partial indexes — must be raw SQL in the migration file. [VERIFIED: Prisma 7 docs do not list partial unique indexes as expressible via `@@unique`; raw SQL migration is the documented workaround.] |
|
||
| Step-validity logic at every step | A growing `if-else` cascade in `level-up-wizard.tsx` | `computeApplicableSteps(targetLevel, class, hasFA, isCaster): StepKind[]` — pure function, unit-tested | One source of truth for "which steps are visible at level N for class X with FA flag" — also lets the server reject patches to non-applicable steps. |
|
||
| Class progression tables as TypeScript constants | A 1500-line `class-progression-data.ts` | The `ClassProgression` Prisma table seeded from Foundry pf2e | Self-correcting (re-run the seed when Foundry updates); keeps mechanical data out of source files (CLAUDE.md philosophy: "Daten in Datenbank"); searchable; enables the planner-deferred `LVL-V2-01` history view to JOIN against it cleanly. |
|
||
| Spell-slot progression formulas hand-coded per class | `if (className === 'Wizard' && level >= 3) slots[1]++; …` | A small **per-caster overlay table** (also in seed script) since Foundry classfeatures encode slot tables in description text not machine-readable rules | The Foundry data is machine-readable for class-feature *grants* but **not** for slot tables — those live in description prose. A hand-curated overlay (10-12 prepared casters + spontaneous casters) is the honest answer. See §Open Questions Q1. |
|
||
| Pathbuilder FA-detection regex over the raw JSON | Ad-hoc `JSON.stringify(build).includes('FA')` | Structured count of `feat-type === 'Archetype'` entries in `build.feats` | Pathbuilder export is structured array-of-feat-tuples (verified in `pathbuilder-import.service.ts:248-272`); query the structure, not the string. |
|
||
| Date-relative "vor 3 Tagen" formatting in the resume banner | Hand-built switch statement | Existing project pattern — likely already a util, otherwise `Intl.RelativeTimeFormat` (zero-dependency, native) | Native `Intl` is German-aware; avoids `date-fns` or `dayjs` for one usage. |
|
||
|
||
**Key insight:** Every "data table" in this phase has a public source (Foundry pf2e). Hand-rolling them = (a) goes stale, (b) burns dev time, (c) violates the "Daten in Datenbank" principle. Conversely, every "math" function in this phase is short, deterministic, and should be hand-rolled with full unit-test coverage — these are the bug surfaces (boost cap, skill cap, recompute, prereq grammar).
|
||
|
||
## Common Pitfalls
|
||
|
||
### Pitfall 1: Boost-cap-at-18 silently corrupts ability scores (PITFALLS.md #8)
|
||
|
||
**What goes wrong:** STR 18 + boost = 20, not the correct 19. Character is permanently overpowered. Bug spreads to HP, AC, attacks, saves, DC.
|
||
|
||
**Why it happens:** Devs write `score + 2` everywhere, miss the +1-above-18 rule.
|
||
|
||
**How to avoid:** Centralize in `applyAttributeBoost(current): number` — the only function in the codebase that increments an ability score. Recompute calls it. Boost-step UI's "wird {newScore}" preview calls it. Unit-tested with edge cases at 17, 18, 19, 24.
|
||
|
||
**Warning signs:** Any character with ability > 18 at level 5; commit-time integration test should fail loudly.
|
||
|
||
### Pitfall 2: Recompute side effects mutate `hpCurrent` (PITFALLS.md #9)
|
||
|
||
**What goes wrong:** Player at 12/40 HP. CON-boost recomputes HP-Max to 50. Code accidentally sets `hpCurrent = 50` ("you healed!"). Or worse: a future Reverse-Level-Up drops `hpMax` below `hpCurrent` and silently underflows.
|
||
|
||
**Why it happens:** Devs reach for `hpCurrent = hpMax` or `Math.min(hpCurrent, hpMax)` reflexively.
|
||
|
||
**How to avoid:** Document and enforce: **commit transaction NEVER touches `hpCurrent`**. New HP-Max is new headroom; player heals through normal HP rules later. The `prisma.character.update` call writes only `level`, `hpMax`, and other strictly-derived fields. Add a unit test that asserts `hpCurrent` is absent from the update payload.
|
||
|
||
**Warning signs:** Player's HP fully refilled after Level-Up.
|
||
|
||
### Pitfall 3: Skill-Increase History gets lost (PITFALLS.md #11)
|
||
|
||
**What goes wrong:** Future Reverse-Level-Up cannot know which skill was the level-15 increase if the only stored value is `final proficiency = MASTER`.
|
||
|
||
**How to avoid:** The wizard's `choices.skillIncrease` is captured in `LevelUpHistory.choices` JSON for every level. The `committedAt` LevelUpSession also retains the choice. So at history time, you can reconstruct: walk all `LevelUpHistory` rows for the character in level order, replay each `choices.skillIncrease` to derive "at level N, skill X went from rank A to B". This phase doesn't build the Reverse feature, but it **must persist enough data** for the future to reconstruct it.
|
||
|
||
**Warning signs:** N/A this phase — this is a forward-compatibility check on the schema.
|
||
|
||
### Pitfall 4: Feat retrain orphans (PITFALLS.md #10)
|
||
|
||
**What goes wrong:** A feat depends on another feat as prereq; if the prereq feat is removed (Reverse-Level-Up), the dependent feat now violates its prereq invisibly.
|
||
|
||
**Status this phase:** Reverse-Level-Up is deferred (LVL-V2-02). For Phase 1, this is **purely a forward-compat concern** — schema must allow Pitfall #10's solution later. Specifically: the `Character.prereqViolations: Json?` column we add for D-06 (import banner) is **the same column** Reverse-Level-Up will use to surface orphan feats post-retrain. Build it once, use it twice.
|
||
|
||
### Pitfall 5: Foundry pf2e data shape changes between checkouts
|
||
|
||
**What goes wrong:** Seed script written against `pf2e@7.x.0` breaks against `pf2e@8.0.0` because Foundry restructures `system.classFeatLevels.value` into something else.
|
||
|
||
**How to avoid:** Pin a specific Foundry pf2e tag in the seed script's README; the script fails loudly with "expected key X not found" if shape drifts; rerun the seed against a new tag explicitly. Don't auto-track HEAD.
|
||
|
||
**Warning signs:** Seed script silently produces empty `ClassProgression` rows.
|
||
|
||
### Pitfall 6: Spell-slot progression encoded in description prose, not rules
|
||
|
||
**What goes wrong:** Seed script tries to extract spell-slot progression from `wizard-spellcasting.json` and finds only narrative text ("you can prepare X spells of grade Y at level Z…"). [VERIFIED: WebFetch of `wizard-spellcasting.json` confirms `rules` array does NOT contain slot increments.]
|
||
|
||
**How to avoid:** Hand-curate a small `spell-slot-progression.ts` overlay with the canonical PF2e tables for each of the 16 in-scope classes that cast. Don't try to NLP-parse prose. The overlay is small (≤20 rows × 16 classes ≈ 320 lines) and stable (PF2e doesn't change slot tables between printings).
|
||
|
||
**Warning signs:** Spellcaster level-ups produce zero new slots in tests.
|
||
|
||
### Pitfall 7: Per-event JWT validation overload (PITFALLS.md #17)
|
||
|
||
**What goes wrong:** N/A this phase — the new endpoints are REST (one auth check per HTTP request), and the `level_up_committed` event is a server-emitted broadcast (no inbound socket message handler).
|
||
|
||
**Status:** No exposure here; called out only because the cross-cutting WebSocket discipline applies to future phases.
|
||
|
||
### Pitfall 8: Cascading deletes wipe history (PITFALLS.md #16)
|
||
|
||
**What goes wrong:** `LevelUpHistory` with `onDelete: Cascade` would lose all history when a character is deleted.
|
||
|
||
**How to avoid:** Decision per relation:
|
||
- `LevelUpSession → Character`: `onDelete: Cascade` — DRAFT is meaningless without character.
|
||
- `LevelUpHistory → Character`: `onDelete: Cascade` (acceptable — character deletion is destructive in this self-hosted-single-group app; no soft-delete pattern exists for Character today). Document this in the migration SQL comment.
|
||
- `ClassProgression`: no FK to Character — independent reference table.
|
||
|
||
## Code Examples
|
||
|
||
Verified patterns from official sources and the existing codebase.
|
||
|
||
### Example 1 — Foundry pf2e Class JSON Shape
|
||
|
||
[VERIFIED: WebFetch `https://raw.githubusercontent.com/foundryvtt/pf2e/master/packs/classes/fighter.json` 2026-04-27]
|
||
|
||
```jsonc
|
||
// packs/classes/fighter.json — top-level
|
||
{
|
||
"_id": "...",
|
||
"name": "Fighter",
|
||
"type": "class",
|
||
"system": {
|
||
"hp": 10,
|
||
"perception": 2, // Proficiency rank (0=untrained, 1=trained, 2=expert, …)
|
||
"keyAbility": ["dex", "str"],
|
||
"spellcasting": 0,
|
||
"attacks": { "simple": 2, "martial": 2, "advanced": 1, "unarmed": 2, "other": { "rank": 0, "name": "" } },
|
||
"defenses": { "light": 1, "medium": 1, "heavy": 1, "unarmored": 1 },
|
||
"savingThrows": { "fortitude": 2, "reflex": 2, "will": 1 },
|
||
"trainedSkills": { "value": [], "additional": 3 },
|
||
"classFeatLevels": { "value": [1, 2, 4, 6, 8, 10, 12, 14, 16, 18, 20] },
|
||
"ancestryFeatLevels":{ "value": [1, 5, 9, 13, 17] },
|
||
"skillFeatLevels": { "value": [2, 4, 6, 8, 10, 12, 14, 16, 18, 20] },
|
||
"generalFeatLevels": { "value": [3, 7, 11, 15, 19] },
|
||
"items": {
|
||
"u8k07": {
|
||
"img": "...",
|
||
"level": 5,
|
||
"name": "Fighter Weapon Mastery",
|
||
"uuid": "Compendium.pf2e.classfeatures.Item.Fighter Weapon Mastery"
|
||
}
|
||
// … more keyed by random ID, each with level + uuid
|
||
}
|
||
}
|
||
}
|
||
```
|
||
|
||
**Mapping to our `ClassProgression` schema:**
|
||
- One row per `(className, level)` for level 1..20.
|
||
- `grants: String[]` ← collect all `items.<id>` entries with that level → use the bare name (`"Fighter Weapon Mastery"`).
|
||
- `proficiencyChanges: Json` ← the seed script must consult **classfeatures compendium files** (not the class JSON) for level-gated proficiency bumps (e.g., Fighter's "Weapon Mastery" at L5 grants martial→Master). For simple grants where Foundry doesn't carry mechanical proficiency data, the seed script applies a hand-curated overlay (one map per class) — see Pitfall #6.
|
||
- `spellSlotIncrement / cantripIncrement / repertoireIncrement` ← from a hand-curated per-class overlay (the Foundry classfeature for spellcasting carries this data only as prose; verified for Wizard).
|
||
- `choiceType: String?` ← presence indicator, e.g. `"doctrine"` for Cleric L1, `"school"` for Wizard L1, `"weapon-mastery-group"` for Fighter L5.
|
||
- `choiceOptionsRef: String?` ← lookup key into a small seed-time options table.
|
||
|
||
### Example 2 — Real Prereq Strings (from `server/prisma/data/featlevels.json`, audited 2026-04-27)
|
||
|
||
**Audit:** 5,625 feats total, 3,393 (60.3%) have non-empty prereqs.
|
||
|
||
**Sub-classification of the 3,393 feats with prereqs:**
|
||
|
||
| Pattern | Count | Sample | D-01 Evaluable? |
|
||
|---------|-------|--------|-----------------|
|
||
| Pure single-skill rank: `^(Trained\|Expert\|Master\|Legendary) in [Skill]$` | 345 | `"Trained in Acrobatics"` | YES — direct table lookup |
|
||
| Skill-rank composite (or/and via comma): `Trained in X, Y, or Z` / `expert in a skill with the Recall Knowledge action` | 125 | `"Trained in Arcana, Trained in Nature, Trained in Occultism, or Trained in Religion"` | YES (the disjunctive forms; the "skill with Recall Knowledge action" form is UNKNOWN — too semantic) |
|
||
| Heritage refs: `^… heritage` / `… heritage or … heritage` | 112 | `"Unbreakable Goblin heritage"` | YES — heritage is on Character.heritageId |
|
||
| Class-feature subchoice (instinct/cause/order/muse/bloodline/doctrine/school) | 132 | `"animal order"`, `"enigma muse"`, `"flame order"`, `"grandeur cause"` | PARTIAL — evaluable IFF we persist class-feature-choice picks from D-19 commit-time. Phase 1 should persist these in `CharacterFeat` (with `source: CLASS`) so the evaluator can find them via name-match. |
|
||
| Spellcasting / cantrip refs: `spellcasting class feature`, `spellcaster`, `divine spells`, `cantrip` | 65 | `"spellcasting class feature"`, `"bloodline that grants divine spells; you follow a deity"` | NO — D-02 explicitly defers these to UNKNOWN/warning |
|
||
| Class with brackets `[Druid] animal order` | 4 | `"[Druid] animal order"` | YES — strip brackets, treat as class-then-subchoice |
|
||
| Deity refs: `worship`, `follower of`, `deity` | 29 | `"worshipper of Droskar"`, `"deity with a simple… favored weapon"` | NO — D-02 |
|
||
| Age / ethnicity: `at least 100 years old`, `Tian-Dan ethnicity` | 11 | `"at least 100 years old"`, `"Nidalese ethnicity"` | NO — these aren't tracked on Character |
|
||
| Vision / sense traits: `low-light vision`, `darkvision`, `scent` | 11 | `"low-light vision"` | PARTIAL — heritage often grants these; for now mark UNKNOWN |
|
||
| Multi-clause (semicolon AND): `Trained in Deception; Trained in Stealth`, `Charisma +2; Strength +2` | 637 | `"Champion Dedication: Charisma +2; Strength +2"` (note: "Charisma +2" is an ability minimum which the evaluator should support — see grammar above) | MOSTLY YES — semicolon = AND combinator, walk both sides |
|
||
| Multi-clause (comma alternation): `Trained in Lore, Mountain Lore` | 123 | varies | PARTIAL — comma is ambiguous (sometimes AND, sometimes OR-list). Recommend: comma inside a "Trained in X, Y, or Z" pattern is OR-list; comma between full atoms is AND. |
|
||
| Bare feat ref (single capitalized phrase): `"Fascinating Performance"`, `"Power Attack"`, `"Base Kinesis"` | ~150 | `"Fascinating Performance"` | YES — Feat-name lookup against `Feat` table; if found, check `CharacterFeat` |
|
||
|
||
**Estimated evaluable coverage:** ~70-80% of the 3,393 prereqed feats produce `{ ok: true | ok: false }`. The remainder (deity/spellcasting/ethnicity/age/vision/semantic-skill refs) produce `{ unknown: true }` and trigger D-03's warning UI — exactly the design.
|
||
|
||
### Example 3 — Prisma schema additions (proposed for the migration SQL)
|
||
|
||
```prisma
|
||
// server/prisma/schema.prisma — APPENDED, not modifying existing models
|
||
|
||
model LevelUpSession {
|
||
id String @id @default(uuid())
|
||
characterId String
|
||
targetLevel Int // currentLevel + 1, captured at start so server can validate
|
||
state Json @default("{}")
|
||
committedAt DateTime?
|
||
createdAt DateTime @default(now())
|
||
updatedAt DateTime @updatedAt
|
||
|
||
character Character @relation(fields: [characterId], references: [id], onDelete: Cascade)
|
||
|
||
@@index([characterId])
|
||
// Partial unique index added in raw migration SQL:
|
||
// CREATE UNIQUE INDEX "LevelUpSession_oneDraftPerCharacter"
|
||
// ON "LevelUpSession"("characterId") WHERE "committedAt" IS NULL;
|
||
}
|
||
|
||
model LevelUpHistory {
|
||
id String @id @default(uuid())
|
||
characterId String
|
||
levelFrom Int
|
||
levelTo Int
|
||
snapshotBefore Json // full character + relations subset captured at commit
|
||
choices Json // the wizard state.choices at commit
|
||
committedAt DateTime @default(now())
|
||
|
||
character Character @relation(fields: [characterId], references: [id], onDelete: Cascade)
|
||
|
||
@@index([characterId, committedAt(sort: Desc)])
|
||
}
|
||
|
||
model ClassProgression {
|
||
id String @id @default(uuid())
|
||
className String // "Fighter", "Wizard", … one of the 16 D-16 names
|
||
level Int // 1..20
|
||
grants String[] // e.g. ["Bravery", "WeaponSpecialization"] — feature names
|
||
proficiencyChanges Json // { fortitude: "EXPERT", reflex: "EXPERT", … } at THIS level
|
||
spellSlotIncrement Json? // { tradition: "ARCANE", level: 3, count: 1 } per slot bumped
|
||
cantripIncrement Int? // count of new cantrips at this level (rare past L1)
|
||
repertoireIncrement Int? // count of new repertoire spells (spontaneous casters)
|
||
choiceType String? // "doctrine" | "school" | "weapon-mastery" | null
|
||
choiceOptionsRef String? // key into ClassFeatureOptions seed table
|
||
|
||
@@unique([className, level])
|
||
@@index([className])
|
||
}
|
||
|
||
model ClassFeatureOption {
|
||
id String @id @default(uuid())
|
||
optionsRef String // matches ClassProgression.choiceOptionsRef
|
||
optionKey String // e.g. "destruction-doctrine"
|
||
name String
|
||
nameGerman String?
|
||
description String // English; German via TranslationsService at runtime
|
||
// Mechanical effect application is hand-coded per choiceType in commit-time recompute.
|
||
|
||
@@unique([optionsRef, optionKey])
|
||
@@index([optionsRef])
|
||
}
|
||
|
||
// On Character — APPENDED fields
|
||
model Character {
|
||
// ... existing fields unchanged ...
|
||
freeArchetype Boolean @default(false) // D-08
|
||
prereqViolations Json? // D-06 — { violations: [{featId, featName, prereqText}] }
|
||
// levelUpSessions and histories are reverse relations:
|
||
levelUpSessions LevelUpSession[]
|
||
levelUpHistories LevelUpHistory[]
|
||
}
|
||
```
|
||
|
||
### Example 4 — REST endpoint shape (D-13 access pattern follows existing `checkCharacterAccess`)
|
||
|
||
```ts
|
||
// server/src/modules/leveling/leveling.controller.ts (proposed)
|
||
@Controller()
|
||
@UseGuards(JwtAuthGuard)
|
||
export class LevelingController {
|
||
constructor(private leveling: LevelingService) {}
|
||
|
||
@Post('characters/:characterId/level-up')
|
||
start(@Param('characterId') characterId: string, @Req() req: AuthRequest) {
|
||
return this.leveling.startOrResume(characterId, req.user.id);
|
||
}
|
||
|
||
@Patch('level-up/:sessionId')
|
||
patch(@Param('sessionId') sessionId: string, @Body() dto: PatchLevelUpDto, @Req() req: AuthRequest) {
|
||
return this.leveling.patchState(sessionId, req.user.id, dto);
|
||
}
|
||
|
||
@Get('level-up/:sessionId/preview')
|
||
preview(@Param('sessionId') sessionId: string, @Req() req: AuthRequest) {
|
||
return this.leveling.computePreview(sessionId, req.user.id);
|
||
}
|
||
|
||
@Post('level-up/:sessionId/commit')
|
||
commit(@Param('sessionId') sessionId: string, @Req() req: AuthRequest) {
|
||
return this.leveling.commit(sessionId, req.user.id);
|
||
}
|
||
|
||
@Delete('level-up/:sessionId')
|
||
discard(@Param('sessionId') sessionId: string, @Req() req: AuthRequest) {
|
||
return this.leveling.discard(sessionId, req.user.id);
|
||
}
|
||
}
|
||
```
|
||
|
||
Each method ultimately calls into `CharactersService.checkCharacterAccess(characterId, userId, requireOwnership=false)` — but with the requirement loosened: D-13 says GM-of-campaign also can level-up. `checkCharacterAccess` already permits GM by passing `requireOwnership=true` (yes — re-reading lines 73-78 of `characters.service.ts`: when `requireOwnership=true` it allows `isOwner || isGM`). So `requireOwnership: true` is the right call here — it semantically means "owner-or-GM" in this codebase.
|
||
|
||
### Example 5 — `level_up_committed` payload shape
|
||
|
||
```ts
|
||
// server/src/modules/characters/characters.gateway.ts:24 — UPDATE the union type:
|
||
export interface CharacterUpdatePayload {
|
||
characterId: string;
|
||
type: 'hp' | 'conditions' | 'item' | 'inventory' | 'money' | 'level' | 'equipment_status'
|
||
| 'rest' | 'alchemy_vials' | 'alchemy_formulas' | 'alchemy_prepared' | 'alchemy_state'
|
||
| 'dying'
|
||
| 'level_up_committed'; // NEW
|
||
data: any; // (existing — keep until typed-event refactor in a future phase)
|
||
}
|
||
|
||
// Payload for type='level_up_committed':
|
||
type LevelUpCommittedData = {
|
||
level: number; // new level
|
||
derived: {
|
||
hpMax: number;
|
||
ac: number;
|
||
classDc: number;
|
||
perception: number;
|
||
fortitude: number;
|
||
reflex: number;
|
||
will: number;
|
||
};
|
||
// Intentionally NOT including the full character — clients react-query-invalidate the character query
|
||
// and refetch via REST. WebSocket payload stays small; full state stays canonical via REST. (Pitfall #15 mitigation)
|
||
};
|
||
```
|
||
|
||
The client's `use-character-socket.ts` adds an `onLevelUpCommitted` callback that calls `queryClient.invalidateQueries(['character', characterId])`.
|
||
|
||
### Example 6 — Spell-slot overlay (proposed shape for the seed script)
|
||
|
||
```ts
|
||
// server/prisma/data/spell-slot-overlays.ts — hand-curated, in source control
|
||
// Each entry says: at THIS level, this caster gains THIS many slots of THIS grade.
|
||
export const SPELL_SLOT_OVERLAY: Record<string, Array<{
|
||
level: number;
|
||
spellSlotIncrement?: { tradition: SpellTradition; spellLevel: number; count: number };
|
||
cantripIncrement?: number;
|
||
repertoireIncrement?: number;
|
||
}>> = {
|
||
Wizard: [
|
||
{ level: 1, cantripIncrement: 5 }, // L1: 5 cantrips
|
||
{ level: 1, spellSlotIncrement: { tradition: 'ARCANE', spellLevel: 1, count: 2 } }, // L1: 2 grade-1 slots
|
||
{ level: 2, spellSlotIncrement: { tradition: 'ARCANE', spellLevel: 1, count: 1 } }, // L2: +1 grade-1 (3 total)
|
||
{ level: 3, spellSlotIncrement: { tradition: 'ARCANE', spellLevel: 2, count: 2 } },
|
||
// … through L20 from the canonical PF2e table
|
||
],
|
||
Sorcerer: [
|
||
{ level: 1, cantripIncrement: 5 },
|
||
{ level: 1, spellSlotIncrement: { tradition: 'ARCANE'/* or set per bloodline */, spellLevel: 1, count: 3 } },
|
||
{ level: 2, spellSlotIncrement: { tradition: 'ARCANE', spellLevel: 1, count: 1 } },
|
||
// … and Sorcerer-specific repertoireIncrement
|
||
{ level: 3, repertoireIncrement: 1 },
|
||
// …
|
||
],
|
||
// … 12-14 more casters from D-16 scope
|
||
};
|
||
```
|
||
|
||
The seed script merges this overlay into `ClassProgression` rows. Splitting it out keeps the Foundry-derived seed (mostly grant + choice info) separate from the hand-curated table data.
|
||
|
||
## State of the Art
|
||
|
||
| Old approach | Current approach | When changed | Impact |
|
||
|--------------|------------------|--------------|--------|
|
||
| Per-event JWT decode in WebSocket handlers | Decode once on connect, cache `socket.data.userId` | Already in Dimension47 (`characters.gateway.ts:71-86`) | Already standard — no change needed |
|
||
| Hand-coded class progression in TS constants | DB-backed `ClassProgression` table seeded from canonical source (Foundry pf2e) | Adopted in this phase | Aligns with CLAUDE.md's "Daten in Datenbank" |
|
||
| `db push` for development | `prisma migrate dev` — real migration files | CLAUDE.md enforced from project start | No exception this phase |
|
||
| Free-text feat prerequisites (just text in the description) | Dedicated `Feat.prerequisites: String?` column with structured DSL evaluator | Already half-built — column exists at `schema.prisma:560`; this phase adds the evaluator | First time the column has a consumer |
|
||
| XState for every multi-step UI | `useReducer` for linear-with-conditional flows; XState only for genuinely graph-shaped state | This phase | Pragmatic — XState v5 (5.30.0) is excellent but not earned by this phase's complexity |
|
||
|
||
**Deprecated/outdated:**
|
||
- Reading PF2e data from `client/public/*.json` at runtime (per CLAUDE.md "nicht direkt aus JSON-Dateien"). Already the rule; the new ClassProgression tables follow it.
|
||
|
||
## Assumptions Log
|
||
|
||
| # | Claim | Section | Risk if Wrong |
|
||
|---|-------|---------|---------------|
|
||
| A1 | Pathbuilder FA auto-detect heuristic (count of Archetype-typed feats ≥ 2) reliably indicates FA was active | §Pattern 6 | Auto-detect may misfire on characters who legitimately took an Archetype Dedication via their normal class-feat slot. Mitigation: D-09 already specifies "Spieler kann nachträglich ändern" — the toggle is editable in character settings. False-positive cost is low. |
|
||
| A2 | The `WizardState` reducer shape proposed in §Pattern 1 maps cleanly to the JSON-state column | §Pattern 1 | If the planner wants finer granularity (e.g. per-step validation timestamps), the shape needs extending. Extensible — Json column accepts any shape. |
|
||
| A3 | The hand-curated `SPELL_SLOT_OVERLAY` covers all 16 D-16 classes correctly | §Code Examples #6 | Sourcing from Archives of Nethys per-class tables; one wrong row = wrong slot count for affected class. Mitigation: unit test `recompute-derived-stats.spec.ts` exercises slot increments per class+level; planner should curate against the official Player Core / APG tables. |
|
||
| A4 | Foundry pf2e Apache 2.0 + OGL 1.0a + Paizo CUP allows re-shipping a derived `ClassProgression` table for self-hosted use by our group | §Standard Stack, §Code Examples #1 | Self-hosted single-tenant use for our own group is the textbook Paizo CUP scenario. If the project ever shifts to public SaaS, re-evaluate. |
|
||
| A5 | The "comma vs semicolon" disambiguation rule for prereq parsing (semicolon = AND, comma inside `Trained in X, Y, or Z` = OR-list, comma elsewhere = AND) is correct for the corpus | §Pattern 4, §Code Examples #2 | Corpus audit suggests these heuristics; some edge cases will resolve differently. Mitigation: log every UNKNOWN result and review the first ~50 in production. |
|
||
| A6 | Class-feature subchoice references in prereqs (`enigma muse`, `flame order`) become evaluable once we persist them as `CharacterFeat` rows with the option name | §Code Examples #2 (Sub-classification) | If the class-feature commit path stores these differently (e.g. as a column on `CharacterAlchemyState.researchField`), the evaluator must look in multiple places. The planner should standardize: every class-feature choice produces a `CharacterFeat` row whose `name` is the option name. |
|
||
|
||
## Validation Architecture
|
||
|
||
### Test Framework
|
||
| Property | Value |
|
||
|----------|-------|
|
||
| Framework | Jest 30.0.0 + ts-jest (server only — `server/package.json:88-104`) [VERIFIED: `npm view jest version` → 30.3.0; we are on 30.0.0 = compatible] |
|
||
| Config file | inline in `server/package.json` — `testRegex: ".*\\.spec\\.ts$"`, `rootDir: "src"` |
|
||
| Quick run command | `cd server && npm test -- --testPathPattern=leveling` |
|
||
| Full suite command | `cd server && npm test` |
|
||
|
||
**Client test framework:** None today (TESTING.md confirms zero coverage). Phase 1 deliberately does NOT introduce vitest on the client — that is a Phase-2/3 cross-cutting decision. Wizard UI is verified manually + via the integration test that exercises the full commit path through the API.
|
||
|
||
### Phase Requirements → Test Map
|
||
|
||
| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|
||
|--------|----------|-----------|-------------------|-------------|
|
||
| LVL-02 | `applyAttributeBoost(17) = 19` | unit | `npm test -- apply-attribute-boost.spec.ts` | ❌ Wave 1 |
|
||
| LVL-02 | `applyAttributeBoost(18) = 19` (cap) | unit | same | ❌ Wave 1 |
|
||
| LVL-02 | `applyAttributeBoost(20) = 21` (above cap) | unit | same | ❌ Wave 1 |
|
||
| LVL-02 | `isValidBoostSet(['STR','STR','CON','INT']) = false` | unit | same | ❌ Wave 1 |
|
||
| LVL-02 | `isValidBoostSet(['STR','DEX','CON','INT']) = true` | unit | same | ❌ Wave 1 |
|
||
| LVL-06 | `canIncreaseSkill(currentRank='TRAINED', characterLevel=2) = false` (T→E only at L3+) | unit | `npm test -- skill-increase-cap.spec.ts` | ❌ Wave 1 |
|
||
| LVL-06 | `canIncreaseSkill('TRAINED', 3) = true` | unit | same | ❌ Wave 1 |
|
||
| LVL-06 | `canIncreaseSkill('EXPERT', 6) = false` (E→M only at L7+) | unit | same | ❌ Wave 1 |
|
||
| LVL-06 | `canIncreaseSkill('EXPERT', 7) = true` | unit | same | ❌ Wave 1 |
|
||
| LVL-06 | `canIncreaseSkill('MASTER', 14) = false` | unit | same | ❌ Wave 1 |
|
||
| LVL-06 | `canIncreaseSkill('MASTER', 15) = true` | unit | same | ❌ Wave 1 |
|
||
| LVL-09 | Pure skill-rank prereq evaluates correctly: `evaluatePrereq("Trained in Athletics", { skills: { Athletics: 'TRAINED' }})` → `{ ok: true }` | unit | `npm test -- prereq-evaluator.spec.ts` | ❌ Wave 1 |
|
||
| LVL-09 | Same prereq, untrained: → `{ ok: false, reason: ... }` | unit | same | ❌ Wave 1 |
|
||
| LVL-09 | Disjunctive: `"Trained in Arcana, Trained in Nature, or Trained in Religion"` with one match → `{ ok: true }` | unit | same | ❌ Wave 1 |
|
||
| LVL-09 | Conjunctive: `"Trained in Deception; Trained in Stealth"` with one missing → `{ ok: false }` | unit | same | ❌ Wave 1 |
|
||
| LVL-09 | Bare feat-name: `"Power Attack"` with feat present → `{ ok: true }` | unit | same | ❌ Wave 1 |
|
||
| LVL-09 | Heritage ref: `"Unbreakable Goblin heritage"` with matching heritage → `{ ok: true }` | unit | same | ❌ Wave 1 |
|
||
| LVL-09 | Class ref: `"Fighter"` with `classId='Fighter'` → `{ ok: true }` | unit | same | ❌ Wave 1 |
|
||
| LVL-09 | Spellcasting ref: `"spellcasting class feature"` → `{ unknown: true, raw: ... }` | unit | same | ❌ Wave 1 |
|
||
| LVL-09 | Deity ref: `"worshipper of Droskar"` → `{ unknown: true, raw: ... }` | unit | same | ❌ Wave 1 |
|
||
| LVL-09 | Empty/null prereq → `{ ok: true }` | unit | same | ❌ Wave 1 |
|
||
| LVL-10 | `recomputeDerivedStats(character, choices, progression).hpMax = ancestryHP + (classHP + conMod) × level` | unit | `npm test -- recompute-derived-stats.spec.ts` | ❌ Wave 1 |
|
||
| LVL-10 | Recompute respects boost-cap-at-18 | unit | same | ❌ Wave 1 |
|
||
| LVL-10 | Recompute applies proficiencyChanges from ClassProgression at the new level | unit | same | ❌ Wave 1 |
|
||
| LVL-10 | Recompute does NOT mutate `hpCurrent` | unit | same | ❌ Wave 1 |
|
||
| LVL-01 | `computeApplicableSteps(targetLevel=5, class='Fighter', hasFA=false, isCaster=false)` includes boost, skill-increase, feat-class, feat-skill, feat-ancestry | unit | `npm test -- compute-applicable-steps.spec.ts` | ❌ Wave 1 |
|
||
| LVL-01 | At level 4, no boost step | unit | same | ❌ Wave 1 |
|
||
| LVL-01 | With FA enabled, includes feat-archetype step | unit | same | ❌ Wave 1 |
|
||
| LVL-01 | With caster class, includes spellcaster step | unit | same | ❌ Wave 1 |
|
||
| LVL-12 | Commit transaction is atomic: simulated mid-transaction throw rolls back ALL writes | integration | `npm test -- leveling.service.spec.ts` | ❌ Wave 3 |
|
||
| LVL-12 | Commit creates one `LevelUpHistory` row with snapshot + choices populated | integration | same | ❌ Wave 3 |
|
||
| LVL-12 | Commit broadcasts `level_up_committed` exactly once (mock the gateway) | integration | same | ❌ Wave 3 |
|
||
| LVL-11 | DELETE `/level-up/:sessionId` removes the DRAFT without touching the character | integration | same | ❌ Wave 3 |
|
||
| LVL-11 | Partial unique index allows re-creating a DRAFT after the previous was committed (`committedAt` IS NOT NULL → not in unique scope) | integration | same | ❌ Wave 3 |
|
||
| LVL-13 | `freeArchetype: true` on character causes `computeApplicableSteps` to include the FA step | unit | same as LVL-01 tests | ❌ Wave 1 |
|
||
| LVL-14 | Commit applies `spellSlotIncrement` from ClassProgression to `CharacterResource` for caster classes | integration | `leveling.service.spec.ts` | ❌ Wave 3 |
|
||
| LVL-14 | Commit does NOT add slots for non-casters | integration | same | ❌ Wave 3 |
|
||
| LVL-15 | Translation pipeline call for new prereq strings hits the existing `TranslationsService.getTranslationsBatch` | manual + integration | manual smoke; one integration test asserts the service is invoked | ❌ Wave 3 |
|
||
| LVL-08 | Seed script populates `ClassProgression` for all 16 classes × 20 levels = 320 rows minimum | manual | `cd server && npm run db:seed:class-progression && psql -c 'SELECT className, COUNT(*) FROM "ClassProgression" GROUP BY className'` | N/A — seed verification |
|
||
| LVL-03/04/05/07 | `feat-filter.service.ts` returns only feats whose prereq evaluates `{ ok: true }` OR `{ unknown: true }` (NOT `{ ok: false }`), respecting class/ancestry/skill-feat-source filters | integration | `npm test -- feat-filter.service.spec.ts` | ❌ Wave 3 |
|
||
|
||
### Sampling Rate
|
||
- **Per task commit:** `cd server && npm test -- --testPathPattern=leveling` — runs only the leveling module's tests in <10s.
|
||
- **Per wave merge:** `cd server && npm test` — full suite, including the existing placeholder e2e test (still expected to pass or be marked skipped if not relevant).
|
||
- **Phase gate:** Full suite green before `/gsd-verify-work`. Integration test for atomic commit MUST pass.
|
||
|
||
### Wave 0 Gaps
|
||
|
||
The codebase has Jest **infrastructure** but zero unit-test files alongside source. Wave 0 establishes the file convention and proves the runner works on a leveling-module test:
|
||
|
||
- [ ] Create `server/src/modules/leveling/lib/apply-attribute-boost.ts` + `.spec.ts` (smallest possible — one function, four tests). Run `npm test`. Confirms ts-jest compiles, the testRegex picks it up, the run completes.
|
||
- [ ] Add `server/jest.config.cjs` ONLY if the inline `package.json` Jest config has surprises with the new test files. Default: trust the inline config.
|
||
- [ ] Add `db:seed:class-progression` script to `server/package.json` scripts section pointing at `tsx prisma/seed-class-progression.ts`.
|
||
- [ ] Add `.gitignore` entry for `server/prisma/data/foundry-pf2e/` (the dev-cloned source).
|
||
- [ ] Add unit-test pattern documentation to `.planning/codebase/TESTING.md` once the Wave-1 modules land — first real pattern in the codebase.
|
||
|
||
*(If no gaps: not applicable — gaps exist as listed.)*
|
||
|
||
## Security Domain
|
||
|
||
This phase touches authenticated REST endpoints and persists JSON state. Security enforcement applies; no `security_enforcement: false` in config.
|
||
|
||
### Applicable ASVS Categories
|
||
|
||
| ASVS Category | Applies | Standard Control |
|
||
|---------------|---------|-----------------|
|
||
| V2 Authentication | yes (existing) | Bearer JWT via `JwtAuthGuard` — same as all existing endpoints; no new auth surface. WebSocket handshake uses existing token check (`characters.gateway.ts:60-92`). |
|
||
| V3 Session Management | yes (existing) | JWT-stateless; logout invalidates client-side; new endpoints do not introduce server-side session. |
|
||
| V4 Access Control | yes | `LevelingService` calls `CharactersService.checkCharacterAccess(characterId, userId, requireOwnership=true)` for every endpoint per D-13. The `requireOwnership=true` path in `characters.service.ts:73-78` resolves to `isOwner || isGM` — exact semantic match. |
|
||
| V5 Input Validation | yes | All four endpoints' DTOs use `class-validator` decorators (existing pattern — see `server/src/modules/characters/dto/*.dto.ts`). The wizard JSON state inside the DRAFT is validated by a hand-written guard function (TypeScript discriminated unions). Foundry-pf2e seed is dev-time and trusted. |
|
||
| V6 Cryptography | no | No new crypto in this phase. JWT signing handled by `@nestjs/jwt` (existing). |
|
||
| V7 Errors / Logging | yes | Existing NestJS `Logger` patterns used — log every commit (`Level-up committed: characterId=X, fromLevel=N, toLevel=N+1`); log every unknown prereq encountered to help future grammar improvements. Do NOT log full character snapshots (PII via character names + descriptions; even self-hosted, log discipline matters for shared logs). |
|
||
| V8 Data Protection | yes | `LevelUpSession.state` and `LevelUpHistory.snapshotBefore` are JSON columns. They contain character-derived data only — no auth tokens, no passwords. PII risk = character names (already throughout the schema). No additional protection needed beyond DB access controls. |
|
||
| V12 Files / Resources | partial | The seed script reads from `server/prisma/data/foundry-pf2e/` (dev-time only; gitignored). Path-traversal not a concern — paths are hardcoded relative to `__dirname`. |
|
||
|
||
### Known Threat Patterns for {NestJS + Prisma + WebSocket}
|
||
|
||
| Pattern | STRIDE | Standard Mitigation |
|
||
|---------|--------|---------------------|
|
||
| Player attempts to commit a level-up for someone else's character (forged characterId) | Spoofing/EoP | `checkCharacterAccess(characterId, userId, requireOwnership=true)` already throws `ForbiddenException`; tested in integration. |
|
||
| Player attempts to skip the boost step or set 5 boost targets via crafted PATCH | Tampering | DTO validator on `PatchLevelUpDto` rejects malformed shape; commit-time guard runs `isValidBoostSet()` and throws `BadRequestException` if not exactly 4 distinct. |
|
||
| Player attempts to commit a level beyond `currentLevel + 1` | Tampering | Server validates `session.targetLevel === character.level + 1` at commit time; throw `BadRequestException` otherwise. |
|
||
| Player attempts to commit a non-applicable step's choices (e.g. boost choice at level 4) | Tampering | The Wave-1 `computeApplicableSteps()` runs server-side at commit; choices for steps not in the applicable list are rejected. |
|
||
| Race condition: two browser tabs both POST `/commit` for the same session | Tampering | Partial unique index on `(characterId) WHERE committedAt IS NULL` makes the second commit a no-op (the session it points to has already been transitioned to `committedAt = now()`). Plus: `prisma.$transaction` is serialized at the row level — second tab's transaction sees `committedAt != null` and aborts. |
|
||
| WebSocket payload injection (player crafts a fake `level_up_committed` event) | Tampering | Inbound WebSocket events are unaffected — `level_up_committed` is server-emit only. The CharactersGateway has no `@SubscribeMessage('level_up_committed')` handler. Other clients trust the event's source = the room's server. |
|
||
| Stored XSS via German feat-prereq translation text rendered in the prereq-confirm dialog | Injection (Tampering) | The text comes from the existing `Translation.germanName` column populated from Claude API; render with React text-binding (no `dangerouslySetInnerHTML`). Existing Dimension47 patterns already do this. |
|
||
| SQL injection via `Feat.prerequisites` containing SQL-like text | Tampering | Prisma parameterizes everything; the prereq strings are never interpolated into raw queries. |
|
||
|
||
## Open Questions
|
||
|
||
1. **Spell-slot progression overlay sourcing.**
|
||
- **What we know:** Foundry pf2e classfeatures (`wizard-spellcasting.json` etc.) encode slot tables in description prose — verified. We need a hand-curated overlay.
|
||
- **What's unclear:** Should the overlay live as a TS constant (`server/prisma/data/spell-slot-overlays.ts`) or as a JSON file (e.g. `server/prisma/data/spell-slot-overlays.json`)?
|
||
- **Recommendation:** TS constant, exported from the `data/` folder, imported by the seed script. Type-safe, IDE-navigable, version-controlled, and the values are inherently TS-shaped (enums for `SpellTradition`). Planner: include curating this overlay (16 caster classes × ~20 levels) as a Wave-2 sub-task.
|
||
|
||
2. **Class-feature option mechanics — where does the recompute apply them?**
|
||
- **What we know:** `ClassProgression.choiceType` flags that a step exists; `ClassFeatureOption` lists the user-facing options; the user picks one in the wizard.
|
||
- **What's unclear:** When the user picks "Destruction Doctrine" (Cleric L1), the doctrine grants specific abilities/feats/proficiencies. Do those grants live as additional `ClassFeatureOption` columns (`grants: String[]`, `proficiencyChanges: Json`), or in a parallel hand-coded mapping?
|
||
- **Recommendation:** **Add the same `grants` + `proficiencyChanges` columns to `ClassFeatureOption`** so the recompute pipeline is uniform: at commit, walk both `ClassProgression` AND any chosen `ClassFeatureOption` rows, apply both sets of grants. This keeps the data model symmetric and the recompute code branch-free. Planner should extend the schema in §Code Examples #3 accordingly.
|
||
|
||
3. **Banner-resolution UI for D-06 import violations.**
|
||
- **What we know:** Phase 1 ships listing-only (per `01-UI-SPEC.md` §"Pathbuilder-Import-Violations Banner": "Phase 1 ships read-only listing only; resolution UI is out of scope").
|
||
- **What's unclear:** When a user retrains a feat manually outside the wizard (today possible via direct DB?), should the banner update? **Out of scope this phase** — confirmed by deferral. Planner: do NOT add banner-clearing logic.
|
||
|
||
4. **Pathbuilder FA auto-detect false-positive recovery (A1 tied).**
|
||
- **What we know:** Heuristic might misfire.
|
||
- **What's unclear:** Should the auto-detection's result be visible somewhere besides the toggle (e.g. logged on the character)?
|
||
- **Recommendation:** Log the detection result as a NestJS Logger info line during import (`PathbuilderImport: detected FA=true for character ${name} based on ${reason}`). The toggle is editable via character-settings. No UI banner needed.
|
||
|
||
5. **Initial level-up from L1 to L2 — does the wizard support it?**
|
||
- **What we know:** ROADMAP/REQUIREMENTS describe the wizard for "Stufe steigen" generally.
|
||
- **What's unclear:** Is L1→L2 the same flow as L4→L5? PF2e: L2 is just feats + skill-feat (no boost set). The dynamic-step logic in `computeApplicableSteps` handles this — boost step appears only for L5/10/15/20. So yes, same flow. **Confirmed: no special handling needed.**
|
||
|
||
## Sources
|
||
|
||
### Primary (HIGH confidence)
|
||
- `server/prisma/data/featlevels.json` — 5,625 feats, audited locally for prereq pattern distribution (3,393 with prereqs, 60.3%).
|
||
- `server/prisma/schema.prisma` — current schema, lines 171-220 (Character), 222-231 (CharacterAbility), 233-244 (CharacterFeat), 246-255 (CharacterSkill), 257-269 (CharacterSpell), 544-582 (Feat with prerequisites: String? at line 560).
|
||
- `server/src/modules/characters/characters.service.ts:41-86` — `checkCampaignAccess`/`checkCharacterAccess` patterns; the `requireOwnership=true` semantic confirmed at lines 73-78 means "isOwner OR isGM".
|
||
- `server/src/modules/characters/characters.gateway.ts:22-26` — `CharacterUpdatePayload['type']` union to extend.
|
||
- `server/src/modules/characters/pathbuilder-import.service.ts:243-272` — feat import structure (where the PrereqEvaluator hooks in for D-05).
|
||
- `server/package.json:88-104` — Jest 30.0.0 inline config, `testRegex: ".*\\.spec\\.ts$"`.
|
||
- WebFetch: `https://raw.githubusercontent.com/foundryvtt/pf2e/master/packs/classes/fighter.json` — fighter class JSON shape (top-level, system fields, items keyed-object structure, classFeatLevels arrays).
|
||
- WebFetch: `https://raw.githubusercontent.com/foundryvtt/pf2e/master/packs/classes/sorcerer.json` — sorcerer class shape; **confirmed** spell-slot/repertoire NOT in class JSON.
|
||
- WebFetch: `https://github.com/foundryvtt/pf2e/blob/master/README.md` — license: Apache 2.0 + OGL 1.0a + Paizo CUP (NOT ORC — D-17 is corrected on this point; the practical effect is identical for self-hosted single-group use).
|
||
- WebFetch: `https://raw.githubusercontent.com/foundryvtt/pf2e/master/packs/classfeatures/wizard-spellcasting.json` — confirmed `rules` array does NOT contain slot increments; mechanical progressions live in description prose.
|
||
- `npm view jest version` → 30.3.0; `npm view xstate version` → 5.30.0; `npm view @xstate/react version` → 6.1.0; `npm view zod version` → 4.3.6 (verified 2026-04-27).
|
||
- `.planning/research/PITFALLS.md` §Pitfall 8 (boost cap), §Pitfall 9 (recompute), §Pitfall 10 (feat retrain orphans), §Pitfall 11 (skill-increase history).
|
||
- `.planning/research/SUMMARY.md` §Phase A.
|
||
- `.planning/codebase/ARCHITECTURE.md` — NestJS module-per-feature pattern.
|
||
- `.planning/codebase/CONVENTIONS.md` — kebab-case files, camelCase functions, PascalCase types, DTOs end in `Dto`, Props in `Props`.
|
||
- `.planning/codebase/TESTING.md` — confirms zero current unit tests; first ones to land per ROADMAP First-Phase Note.
|
||
|
||
### Secondary (MEDIUM confidence)
|
||
- WebFetch: `https://www.prisma.io/docs/orm/prisma-schema/data-model/database-mapping` — confirmed Prisma does not express partial unique indexes; raw SQL migration is the documented workaround.
|
||
- WebFetch: `https://github.com/foundryvtt/pf2e/tree/master/packs/classes` — confirmed list of 28 class JSON files in master branch (we use the 16 from D-16).
|
||
- WebFetch: `https://stately.ai/docs/xstate` — XState v5 capabilities; insufficient to prove serialization story BUT the v5 `createMachine` actor model does support `getPersistedSnapshot()` for resume; ultimately not adopted (see §Standard Stack rejected).
|
||
- WebFetch: Archives of Nethys Leveling Up rule page `https://2e.aonprd.com/Rules.aspx?ID=2065` — confirms general structure but the specific cap-at-18 quote is on a different page; cited from PITFALLS.md / common knowledge of the rule.
|
||
|
||
### Tertiary (LOW confidence — needs validation)
|
||
- A1: Pathbuilder FA auto-detect heuristic — based on common Pathbuilder export shape inferred from `pathbuilder-import.service.ts`; should be verified against an actual FA-enabled character JSON.
|
||
- A5: prereq parser disambiguation (semicolon=AND, comma-in-OR-list-pattern=OR, comma-otherwise=AND) — heuristic based on corpus inspection; expect ~5% misclassification on edge cases. Mitigation built in: any uncertainty → `{ unknown: true }` → user confirms.
|
||
|
||
## Metadata
|
||
|
||
**Confidence breakdown:**
|
||
- Standard stack: HIGH — all versions verified locally and via npm registry; no new dependencies introduced.
|
||
- Architecture: HIGH — every recommendation grounded in existing module/service/gateway patterns and explicit live-code touchpoints.
|
||
- Pitfalls: HIGH — directly mapped to PITFALLS.md #8/#9/#10/#11 plus three new phase-specific pitfalls (Foundry shape drift, spell-slot prose, cascading delete decision).
|
||
- Foundry pf2e data shape: HIGH for class JSON top-level (verified); MEDIUM for class-feature compendiums (verified for wizard-spellcasting only — assumed similar shape for other classes); LOW for the spell-slot extraction pathway (resolved by hand-curated overlay, A3).
|
||
- Prereq evaluator coverage: HIGH for the local corpus audit (5,625 feats inspected); MEDIUM for the projected ~70-80% evaluable rate (depends on grammar implementation quality).
|
||
- License: HIGH — Apache 2.0 + OGL 1.0a + Paizo Community Use Policy (confirmed from Foundry pf2e README); CONTEXT.md D-17 mentions ORC but the practical impact for self-hosted private use is identical.
|
||
- Validation architecture: HIGH — full test map per requirement, executable commands provided.
|
||
|
||
**Research date:** 2026-04-27
|
||
**Valid until:** 2026-05-27 (30 days for stable libraries; sooner if Foundry pf2e major version ships).
|