# HANDOVER — V385 RESOLVED EXERCISE BANK ARCHITECTURE

## Kort slutsats

Efter V384E128/V384E129 är huvudinsikten att Nex i dag löser för mycket “live” även för övningar som redan är färdiglösta, QA:ade och accepterade.

Nuvarande pipeline fungerar bra för authoring/felsökning:

```text
source/spec/keypose
→ runtime läser IK-targets
→ Nex-normalisering
→ IK/CCD/tvåbenslösning
→ support/floor/contact-regler
→ generic grip solver
→ palm snap
→ elbow branch solve
→ finger solver
→ gates
→ render/QA
```

Men för godkända övningar i övningsbanken är detta både instabilt och resurskrävande. Rätt produktionsmodell bör vara:

```text
authoring/build-time = dyr solve
runtime/playback = billig uppspelning
```

Alltså:

```text
live solvers skapar/fixar/QA:ar övningen
resolved exercise bank spelar upp den låsta lösningen
```

## Bakgrund

V384E128 löste Figure four-problemet genom att identifiera att armen inte var biomekaniskt omöjlig. Felet var att generic grip arm-solve valde fel/mirrored elbow branch för samma wrist/snap-target.

Låst V384E128-status:

```text
- V383 bengeometri
- V382 lower sole-edge snap
- V374/V373 separated front-shin snap
- V384E128 analytic outward elbow branch
```

V384E129 adderade därefter en mer generell Chromium/OpenGL visual-QA-harness ovanpå V384E128, utan att ändra pose/runtime/grip-logik.

Efter detta blev det tydligt att nästa stora förbättring inte är ännu en posepatch, utan ett arkitekturlager för färdiglösta övningar.

## Problem med nuvarande live-solver-modell

I dag är övningsbanken delvis fortfarande input-driven:

```text
övningsbank = IK/spec + instruktioner
runtime = löser om övningen vid uppspelning
```

Konsekvenser:

1. En ny solverfix kan ändra gamla redan godkända övningar.
2. Runtime betalar kostnad för IK, grip, contact och finger-solve även när lösningen redan är känd.
3. QA blir svårare eftersom “samma” exercise-spec kan renderas annorlunda med annan runtime/solver.
4. Mobil/browser/prestanda blir sämre än nödvändigt.
5. Checkpoints måste behandla både data/spec och solverversion som del av samma resultat.

## Föreslagen arkitektur

Inför ett nytt lager:

```text
RESOLVED_EXERCISE_BANK
```

Tre huvudlager:

### 1. Source / input layer

Innehåller rå- och spårbarhetsmaterial:

```text
video/source
MediaPipe landmarks/world landmarks
canonical IK
normaliserad IK
source evidence
source hashes
```

Detta används för import, audit och re-solve, men ska inte behöva köras vid normal uppspelning.

### 2. Solve / bake layer

Detta är authoring-/QA-läget:

```text
IK
Nex-normalisering
support/floor solve
contact solve
generic grip solver
palm snap
analytic elbow branch
finger close
collision/contact gates
visual QA
```

När en övning är godkänd exporteras den som en färdig resolved Nex asset.

### 3. Runtime / playback layer

Produktionsläget ska i första hand göra:

```text
load resolved exercise
interpolate keyposes
apply local bone transforms
play tempo/loop
render
```

Runtime ska inte lösa om grip/fingrar/kontakt/armpath för en låst övning.

## Ny huvudregel

```text
Live solvers får användas för att skapa, reparera och QA:a övningar.

Godkända övningar i övningsbanken ska sparas som resolved Nex assets och spelas upp utan att lösas om.
```

Mer explicit:

```text
solve-time:
  generic solver = authority

playback-time:
  resolved baked pose/motion = authority
```

Detta bevarar den generella solver-principen utan att göra godkända övningar instabila.

## Föreslagna runtime-lägen

```text
mode=authoringLiveSolve
```

Används vid import, felsökning, solverutveckling och ny QA.

```text
mode=resolvedPlayback
```

Används för godkända övningar i produktionsbanken.

```text
mode=compareLiveVsResolved
```

Debug/QA-läge som kör både live-solve och resolved playback och rapporterar diff.

## Föreslagen statusmodell för övningar

```text
RAW_IMPORTED
  video/mediapipe finns men övningen är inte löst

NORMALIZED_IK
  canonical/normaliserad IK finns

SOLVER_CANDIDATE
  runtime kan lösa övningen men den är inte låst

RESOLVED_NEX
  färdig actual Nex-lösning finns

VISUAL_QA_APPROVED
  resolved lösning är visuellt QA:ad

LOCKED_EXERCISE_BANK_ASSET
  används som stabil playback-asset i övningsbanken
```

## Föreslaget resolved exercise-format

En resolved exercise bör spara faktisk Nex-lösning, inte bara IK-targets.

Minimum:

```text
resolvedExerciseId
sourceProfileId
sourceSpecHash
solverVersion
runtimeVersion
modelHash
createdFromCheckpoint
qaStatus
```

Per keypose:

```text
phase
expectedKeypose
boneLocalTransforms
optionalBoneWorldReadback
supportContacts
contactLocks
gripLocks
fingerLocks
qaGates
```

Viktigast är:

```text
boneLocalTransforms
```

Det gör att runtime kan spela upp direkt på Nex-riggen utan att köra om solverlagret.

## Figure four som första testfall

Första implementerade resolved asset bör vara:

```text
Dynamic Warm Up · 04 · Figure fours
profileId: warmup_figure_four_walk_ik_v1
resolvedBy: V384E128
```

Process:

```text
1. Kör V384E128 authoringLiveSolve på Figure four.
2. Exportera actual Nex bone local transforms för alla authored keyposes.
3. Spara contact/grip/finger/support locks.
4. Rendera och QA:a resolvedPlayback.
5. Kör compareLiveVsResolved.
6. Lås som LOCKED_EXERCISE_BANK_ASSET.
```

Efter detta ska Figure four i produktion inte behöva kalla:

```text
generic grip solver
analytic outward elbow branch solve
finger solver
support solve
```

Den ska spela upp den färdiga lösningen.

## Re-solve-regel

En godkänd resolved övning får inte ändras automatiskt av ny solver.

Om en ny solver verkar bättre:

```text
1. Re-solve övningen explicit.
2. Jämför mot nuvarande resolved asset.
3. Kör Node + visual QA.
4. Godkänn ny resolved version manuellt.
5. Lås ny asset.
```

Detta förhindrar tysta regressioner.

## Regression/QA för V385

V385 ska inte ändra posekvalitet som första mål. Målet är att bevisa att resolved playback kan reproducera V384E128.

Minsta QA:

```text
- export resolved Figure four från V384E128
- load resolved Figure four i resolvedPlayback
- compareLiveVsResolved:
    bone transform diff
    contact point diff
    grip/finger lock consistency
- Chromium/OpenGL eller deterministic visual QA
- Dynamic Warmup 17-sweep ska fortsatt vara oförsämrad
```

Godkänt om:

```text
- resolvedPlayback matchar V384E128 live-solve inom tolerans
- Figure four ser visuellt likadan eller bättre ut
- ingen ny solver krävs vid playback
- övriga live-solve vägar påverkas inte
```

## Viktiga stop boundaries

1. Skapa inte exercise-specifika solvers.
2. Lägg inte in nya fot/ben/hand-patchar i V385 om syftet är architecture bake.
3. Ändra inte V384E128 pose-resultat som del av resolved-bank-arbetet.
4. Om export saknar nödvändiga bone transforms, stoppa och rapportera exakt vad som saknas.
5. Om playback inte matchar live-solve, felsök export/playback-lagret först, inte grip/IK-lagret.

## Rekommenderad nästa patch

```text
V385_RESOLVED_EXERCISE_BANK_ARCHITECTURE
```

Scope:

```text
- schema för resolved exercise
- exporter från live-solved Nex state
- resolvedPlayback-loader
- compareLiveVsResolved-QA
- Figure four som första resolved exercise asset
```

Ej scope:

```text
- nya posefixar
- nya grip-specialfall
- ny MediaPipe-import
- ändrad Dynamic Warmup source-data
```

## Slutbedömning

V384E128/V384E129 gav oss en fungerande och visuellt verifierad Figure four-kandidat samt en bättre QA-harness. Nästa produktionsmässiga steg är att sluta lösa om godkända övningar live.

V385 bör därför etablera principen:

```text
solvers are authoring tools
resolved exercises are production assets
```