@hatiolab/figure-model 0.1.33 → 0.1.35

package/docs/v3-motion-contract.md

@@ -0,0 +1,178 @@
+# V3 motion contract — joints, parameters, animations
+
+Status: **contract, fixed 2026-09-22; revised the same day after the chief architect's review; implemented the
+same day** (ADR-0087 decision 2, ruling 4). Implementation: `src/v3-graph.ts` (`axis-turn@1`, `axis-slide@1`),
+`src/v3-driver.ts` (`driverValue`, `driverStates`, `validateV3Drivers`), the motion part of `src/v3-from-v2.ts`
+(`planMotion`), tests in `src/v3-motion.test.ts`. The converter and every consumer use this contract; none of them
+defines motion on its own. Not yet covered by the converter: prismatic joints (none in the live assets; V2 scaled
+their travel by the instance, the contract does not), scale channels (refused as shape deformation), a rotation
+channel with a pivot off the part centre, channels that vary more than one axis, and parameter curves other than
+two linear keys. The review changed three things: the direction of every transform is written down, continuous
+rotation is split into an accumulated amount and a phase, and drivers carry an explicit time convention.
+
+## What a person sees
+
+An author opens the six-axis robot arm. The arm stands in its rest pose. A panel lists six joint values, each with
+its unit and range, and the default is where the arm was drawn. Dragging the elbow value bends the forearm about the
+elbow, and everything hung from the forearm (wrist, tool flange, the box in the gripper) comes along. Nothing else
+moves. Setting the value back to its default puts the arm exactly where it was drawn.
+
+On a board, the same arm has the same six values. A connector writes them; the arm follows. Stretching the arm's
+instance size does not change where its joints turn: a joint sits on the part that carries it and moves with that
+part under sizing, as ADR-0066 decision 3 already says for V2.
+
+## One rule for how a child moves, with every direction written down
+
+`X → Y` below means "takes coordinates written in X and gives them in Y".
+
+| value | transform direction |
+|---|---|
+| parent world pose | parent → world |
+| parent joint frame | jointParent → parent |
+| `A = compose(parent world pose, parent joint frame)` | jointParent → world |
+| `O = motion(q)` | **jointChild → jointParent** |
+| `B` = child joint frame | jointChild → child |
+| `attach@1(A, O, B) = A × O × inverse(B)` | child → world |
+
+- `jointParent` and `jointChild` are two named frames per joint, `<joint>.onParent` and `<joint>.onChild`. They
+  **coincide at `q = 0`**: `motion(0)` is the identity, and the two frames are placed so that the child then sits in
+  its rest pose.
+- A part with no joint to its parent has `motion = identity` (V2 `FigurePart.parent` without a joint).
+- The parent and child joint frames come from the rest pose and sizing (`jointOriginPosition`), so a joint moves
+  with the part that carries it when the instance is resized.
+- `attach@1` already computes `A × O × inverse(B)`, and its type checker refuses a chain whose frames do not meet.
+  No parent-chain node is added; `compose@1` and `attach@1` are enough.
+
+**`q = 0` is the rest pose. That is not the same claim as "the default is the rest pose."** A V2 parameter whose
+default is not 0 drew its rest pose at that default. The converter keeps V2's meaning: the joint frames are placed
+for the drawn pose, and the state default stays what V2 stored. It never subtracts the default or forces it to 0.
+
+## Joint kinds, their state input, and the two motion operators
+
+```
+axis-turn@1   args [ax, ay, az (ratio), q (angle)]   params { from, to }
+              → pose from → to: right-handed rotation about the unit axis (ax, ay, az) by q, no translation
+axis-slide@1  args [ax, ay, az (ratio), q (length)]  params { from, to }
+              → pose from → to: translation by q along the unit axis (ax, ay, az), identity rotation
+```
+
+- The axis is a unit vector **written in the jointParent frame**. Both operators fail on a non-unit axis
+  (|a| − 1 beyond 1e-9).
+- Right-handed: looking down the axis toward the origin, positive `q` turns counter-clockwise. Positive `q` on a
+  slide moves along the axis direction.
+- For a joint, `from = <joint>.onChild`, `to = <joint>.onParent`, so the operator's output is `O` above.
+- An arbitrary axis is carried as three numbers and turned with axis–angle. It is **never** collapsed into one
+  Euler component.
+
+| V2 `FigureJoint.type` | state input | unit stored | `motion(q)` |
+|---|---|---|---|
+| `revolute` | one angle, `role: 'state'`, V2 limits as range | rad (an input may declare `deg`; the kernel converts) | `axis-turn@1` |
+| `prismatic` | one length, `role: 'state'`, V2 limits as range | mm | `axis-slide@1` |
+| `continuous` | one **phase** angle, `role: 'state'`, range `[−180°, 180°)` | rad | `axis-turn@1` |
+
+### Continuous rotation: an amount and a phase, not a limit
+
+A finite input range on a continuous joint is **not** a mechanical limit. Refusing 361° would make it not
+continuous. So the value is split:
+
+- **Accumulated rotation** (turns, total angle) lives at the boundary that produces it: the driver or the external
+  input. If turn counts are product data, they are preserved there, outside the kernel.
+- **Phase** is what the kernel receives: the accumulated angle normalised into `[−180°, 180°)`. The kernel's finite
+  range is the range of poses it can express, nothing more.
+
+**Normalise after interpolating, never before.** A driver going forward from 350° to 370° interpolates in
+accumulated angle (350 → 360 → 370) and normalises each sample afterwards (350 → −180/180 → 10). Wrapping the key
+values first would interpolate 350 → 10 and turn the wrong way. Widening the range does not fix this; the split does.
+
+## Parameters
+
+A V2 `FigureParameter` keeps its **name, unit, range, default and target**. In V3 it is the state input itself:
+`id` = the parameter name, `unit` and `min`/`max` from the range, `role: 'state'`, and the asset's `stateDefaults`
+carries the default as V2 stored it. Its target is the joint (or part channel) whose `motion(q)` reads it. A
+parameter that V2 let drive several joints becomes one input read by several `axis-turn@1` nodes: one writer, many
+readers, which the graph already allows.
+
+## Drivers: the asset declares, figure-model evaluates, the consumer owns time
+
+The kernel has **no clock**. Same inputs, same result, always. A V2 `AnimationClip` becomes a **driver**
+declaration on the asset, not a graph node. Responsibilities:
+
+| who | does |
+|---|---|
+| the asset | carries the driver data |
+| figure-model | the one pure evaluation function `driverValue(driver, time) → state value`, and the validation rules |
+| the consumer (things-scene, a thumbnail renderer, a test) | supplies time, plays and stops, chooses which control source is active |
+| the spatial kernel | receives final state values and evaluates shape and pose |
+
+**No consumer implements interpolation or looping on its own.** All of them call the same function.
+
+```
+drivers: [{
+  id: 'run',
+  state: 'roller.spin',              // the state input it writes
+  time: { unit: 's', duration: 0.833 },
+  keys: [{ at: 0, value: 0 }, { at: 1, value: 360 }],   // `at` is a fraction 0..1 of duration
+  interpolation: 'linear',
+  loop: 'wrap',                      // 'wrap' | 'hold'
+  accumulates: true                  // continuous: keys are accumulated angle; the phase is taken after interpolation
+}]
+```
+
+- **Time convention, one for all drivers.** `time.unit` is seconds; `duration` is the clip length in seconds; every
+  key `at` is a fraction of the duration in `[0, 1]`. The converter normalises V2's two habits (seconds in
+  `duration`, fractions in `at`, ADR-0051 ②) into exactly this and records the source form in the report. A driver
+  with a missing or non-positive duration is refused.
+- **Loop end.** `wrap`: time `t` maps to `t mod duration`, and the sample at `duration` equals the sample at 0 (the
+  last key's value is reached at `at = 1` and the next period starts from key 0). For an accumulating driver, wrapping
+  adds the full-period delta to the accumulated value, so the roller keeps turning rather than snapping back.
+  `hold`: for `t ≥ duration` the value stays at the last key.
+- **One writer per state at a time.** A state input may be named by a driver and also written by a connector. The
+  asset's stateDefaults, drivers and external inputs are three sources; the consumer selects the **active control
+  source per state** explicitly (`driver` or `external`). Values are never summed and "last call wins" is not a
+  rule. figure-model's validation refuses two drivers naming the same state.
+
+A V2 part channel (`path: 'rotation'` on a part with no joint, like the conveyor roller) converts to a continuous
+state input on that part, `<part>.spin`, driving an `axis-turn@1` about the part's own axis, and a driver for the
+clip with `accumulates: true`. The conveyor's rotation animation is therefore carried, not lost.
+
+## What the converter does with the seven motion assets
+
+1. For every `FigureJoint`: two joint frames from the rest pose and sizing, one state input, one `axis-turn@1` or
+   `axis-slide@1`, one `attach@1`, and the child's `place@1` reads the attached pose.
+2. For every part with `parent` and no joint: `compose@1` of the parent's pose and the rigid offset.
+3. For every `parameter`: a state input as above; refuse (`PARAMETER_TARGET`) if its target is not a joint or a part
+   channel this contract covers.
+4. For every animation clip: a driver, with the clip's channels mapped to state inputs; refuse
+   (`ANIMATION_CHANNEL`) for a channel path this contract does not cover (`scale`).
+
+## Two corrections to earlier wording
+
+- **Rigid does not mean affine in the state.** A rigid pose is affine in the spatial coordinates it maps, but a
+  rotation matrix is a sin/cos function of the joint angle. So `axis-turn@1` is **not affine in `q`**, and the
+  operator-list guard is restated: `geomean@1` is the only node that is non-affine in the *design inputs*;
+  `axis-turn@1` is non-affine in a *state input*. The 8-size comparison therefore stays a limited regression check for
+  the rest pose and does not become a proof of equivalence under motion.
+- **Rotation is compared as a relative angle**, the angle of `R₂ · R₁ᵀ`, never as a difference of Euler components.
+
+## "The same" for motion (completion criterion)
+
+For every converted motion asset, V2 and V3 are compared at the base size and the doubled sizes with:
+
+- each joint at its default, its mid-point and both limits;
+- **parent and child joints changed at the same time**, not one at a time;
+- at least one joint with an arbitrary (non-principal) axis;
+- a non-zero default, checked at the default and away from it;
+- a continuous joint just before and just after the phase boundary (e.g. 179° and 181°);
+- a looping driver just before and just after the loop end (e.g. 0.99 and 1.01 durations), and a `hold` driver past
+  its end.
+
+Same part list, same centre and extents within 1 mm, same relative rotation within 0.1°. For each driver, the state
+value at time 0, half and end must equal V2's clip value at those times. Exact conversion and deliberate
+re-authoring are marked separately in the report.
+
+## Not in this contract
+
+- Inverse kinematics, reach checks, collision between links. Consumers may add them on top; the kernel does not.
+- Physical time (velocity limits, easing between commanded values). ADR-0051 ② puts transition time on the instance;
+  a driver may implement it, the graph does not know it.
+- Per-axis corner radii (ruling 6) and theme mapping (ruling 5): reviewed separately before the renderer starts.

package/docs/v3-operator-contracts.md

@@ -78,6 +78,10 @@ args 순서와 output 이름은 버전별 연산 계약이다. 전체 연산 cat
 | geomean@1 | a,b[,c] (동일 차원) | value=(a·b[·c])^(1/n) | 음수 입력 |
 | sphere-shape@1 | radiusX,radiusY,radiusZ (길이) | shape(sphere) | 반지름≤0 |
 | polygon-shape@1 | height, x0,z0, x1,z1, … (길이, 점 3개 이상) | shape(polygon; 단면은 X–Z, Y 로 민다) | height≤0, 단면이 한 축으로 퍼지지 않음 |
+| frustum-shape@1 | radiusTop,radiusBottom,height (길이) | shape(frustum; 축은 Y, radiusTop 이 +Y) | height≤0, 반지름 음수, 둘 다 0 |
+| cylinder-shape@2 | radiusX,radiusZ,length (길이) | shape(ellipticCylinder; 축은 Y) | 반지름·길이≤0 |
+| rounded-box@2 | width,height,depth,roundX,roundZ (길이) | shape(roundedBoxXZ; 모서리는 반축 roundX·roundZ 의 2차 Bézier) | 치수≤0, 반축이 단면의 절반 초과 |
+| hollow-box@2 | width,height,depth,roundX,roundZ,wallX,wallZ,floor (길이) | shape(hollowBoxXZ) | rounded-box@2 의 조건 + hollow-box@1 의 벽·바닥 조건 |
 | hollow-box@1 | width,height,depth,round,wallX,wallZ,floor (길이) | shape(hollowBox) | 치수≤0, 라운드 범위 밖, 벽이 단면의 절반 이상, 바닥이 높이 이상 |
 | sin@1 | angle | value=sin(angle) | nonfinite |
 | between@1 | low,high,marginLow,marginHigh (길이) | length,center | 음수 여백, length≤0 |

package/docs/v3-shape-dimension-contract.md

@@ -0,0 +1,146 @@
+# V3 shape-dimension contract — per-axis radii, elliptic sections, and dimensions that follow state
+
+Status: **contract, fixed 2026-09-22 by the V3 designer** (ADR-0087, stage-review rulings 3 and 5). §1 (per-axis
+dimensions) implemented the same day: `cylinder-shape@2`, `rounded-box@2`, `hollow-box@2`, the converter writing
+them, the sampler reading them. §2–3 implemented the same night: dependence on state is tracked per value in the
+compiler and printed as `dependence` beside `outputTypes`; every operator carries a `state` policy (`follows` or
+`refuses`; an operator without one fails with `STATE_POLICY`); `occupancy.extent` may not depend on state
+(`OCCUPANCY_STATE`); `inspectV3Asset` covers the state range and reports `proven` (corners; no state-dependent
+rotation), `sampled` (a rotation depends on state; corners plus per-input sweeps, step stated, not a proof) or
+`defaults` (one state, as asked). The `bounded` method of §3 (swept envelope) is not implemented; such assets report
+`sampled`. The converter writes a two-key scale channel as dimensions × affine(parameter) for percent or ratio
+parameters (`STATE_DIMENSION` note). This is one rule for what a shape's dimensions are and what they may depend on. It is not three
+exceptions bolted on for the three assets that needed them.
+
+## What a person sees
+
+An author opens the electrode roll cradle. A "fed" value sits at 0 %. As they drag it toward 100 %, the roll on the
+cradle gets thinner: its radius shrinks, its length does not. The edge plates that ride on the roll shrink with it and
+stay on its surface. Nothing else moves. At 0 % the roll is exactly the drawn roll.
+
+An author stretches a kiosk to twice its width. The bezel's corners stay the same round in front view where the
+section did not stretch, and go wider than they are tall where it did, because V2 drew them that way. Nothing pops
+back to a circle on its own.
+
+An author opens the worker figure and stretches it sideways. The legs, which the author chose not to keep round,
+become oval like V2 drew them. The renderer draws the oval it is given. It never "fixes" it to a circle.
+
+## 1. Every round thing has per-axis dimensions
+
+A section is round only when its two cross dimensions are equal. The providers write both:
+
+| operator | evaluated provider | dimensions | round when | status |
+|---|---|---|---|---|
+| `cylinder-shape@2` | `ellipticCylinder` | `radiusX`, `radiusZ`, `length` (axis Y) | `radiusX = radiusZ` | implemented 2026-09-22 |
+| `frustum-shape@2` | — | `topRadiusX`, `topRadiusZ`, `bottomRadiusX`, `bottomRadiusZ`, `height` | pairs equal | not implemented; no V2 shape needs it (V2 draws no frustum) |
+| `sphere-shape@1` | `sphere` | `radiusX`, `radiusY`, `radiusZ` (already so) | all equal | implemented |
+| `rounded-box@2` | `roundedBoxXZ` | `width`, `height`, `depth`, `roundX`, `roundZ` | `roundX = roundZ` | implemented 2026-09-22 |
+| `hollow-box@2` | `hollowBoxXZ` | as `hollow-box@1` with `roundX`, `roundZ` in place of `round` | same | implemented 2026-09-22 |
+
+The evaluated provider name is distinct from the `@1` one so a renderer can never mistake per-axis dimensions for a
+single radius. Features on `ellipticCylinder` are `start` and `end` only; `radialBottom` has no single meaning on an
+ellipse.
+
+- `@1` of each provider stays valid and means the equal case; the converter writes `@2` only where V2 drew an
+  unequal section. Nothing that exists today is invalidated.
+- **The renderer draws what it is given.** An elliptic section is an ellipse; an elliptic corner is the quadratic
+  Bézier from `(hw − roundX, −hd)` to `(hw, −hd + roundZ)` with the corner `(hw, −hd)` as control point, which is
+  what things-scene's `roundedRect` draws and what `src/v3-mesh-compare.ts` samples. It is not a circular or
+  elliptic arc: an arc differs from the Bézier by up to 0.06 × round at the corner's middle. A renderer that snaps a
+  section to a circle is wrong, and the mesh-level comparison of the completion criterion is what catches it.
+- Validity: every dimension positive (a corner radius may be 0), `roundX ≤ width/2`, `roundZ ≤ depth/2`. A
+  declared corner larger than the section is refused at compile; the converter normalises V2's declared value to
+  what V2 drew (ruling 2) and reports it.
+
+### What `keepRound` becomes
+
+V2's `keepRound` was a rule about **what happens to a round section under non-uniform sizing**: keep it round by
+the geometric mean of the two factors. In V3 that is not a flag; it is two possible expressions for two dimensions:
+
+```
+kept round      radiusX = radiusZ = r₀ · geomean(fx, fz)          (V2 keepRound on, the default)
+follows axes    radiusX = r₀ · fx,   radiusZ = r₀ · fz            (V2 keepRound off)
+```
+
+Both are ordinary length expressions. The converter chooses by the V2 flag and writes the expression; the
+`ELLIPTIC_SECTION` refusal is now a note on the report (implemented 2026-09-22), and `CORNER_PER_AXIS` notes a
+corner written with two semi-axes. The same two shapes apply to corners: V2 scaled a rounded box's finished mesh
+per axis, so a corner drawn with radius `r₀` becomes `roundX = r₀·fx`, `roundZ = r₀·fz`. That is what
+`ROUND_NOT_SCALED` (40 parts in the last run) was reporting as a loss; with `@2` corners it is no longer a loss.
+
+## 2. A dimension may depend on state
+
+A state input (`role: 'state'`) may be an argument of a shape or length node. A consumed roll's radius is
+`r₀ − fed · k`; a lamp's glow radius grows with the gate. This is the core-semantics §2 invariant ("state changes the
+actual shape dimension") made concrete, and it is what a V2 `scale` channel means: `dims × affine(p)`.
+
+### Dependence is tracked in the type, apart from unit and frame
+
+Every value carries, next to its unit or frame, a **dependence set**: which state inputs its value can change with.
+Inputs of role `state` start with `{self}`; constants and design inputs with `∅`; every operator's outputs carry the
+union of its arguments' sets, unless the operator's contract says otherwise. This is the existing `stateful`
+tracking in `compileV3Graph`, made a first-class part of the type and printed in `outputTypes`.
+
+### Every consuming operator declares its policy
+
+An operator that receives a state-dependent argument does one of three things, **written in its contract**, and a
+new operator that says nothing fails to compile the moment such an argument reaches it. There is no list of banned
+operators to keep in sync.
+
+| policy | meaning | operators |
+|---|---|---|
+| `follows` | the output depends on state; fine | shape providers, `rigid`, `compose`, `attach`, `axis-turn`, `axis-slide`, `add`, `mul`, `div`, `geomean`, `feature`, `place`, `member` |
+| `refuses` | a state-dependent argument is a compile error | `fit-pitch@1`, `fixed-count@1` (count and pitch: structure and cost stay design-only; this is today's `TOPOLOGY_STATE`), the three lengths named by `occupancy.extent` |
+| `bounded` | allowed, and the contract states the resource limit that holds over the whole state range | none today; the slot for a future layout that may follow state |
+
+So: shape, attachment position and pose may follow state (a plate riding on the thinning roll follows it); the
+declared occupancy is a state-independent contract; structure- and cost-changing operations say so themselves.
+
+## 3. The occupancy holds over the whole valid state range
+
+`occupancy` is the contract a board's placement relies on (ADR-0087 decision 7). A volume that is true at the
+default state and false at another is not that contract. So `inspectV3Asset` answers for the **whole** valid state
+range, and says how it knows:
+
+| how the geometry depends on state | how the check is done | what the report says |
+|---|---|---|
+| no state dependence | one evaluation at the defaults | `proven` |
+| every state-dependent world coordinate is affine or monotone in each state input (shape dimensions from `add`/`mul`/`geomean` of a single state input; slides along an axis) | evaluate at every corner of the state box (each input at min and max); the extremes are at the corners | `proven`, listing the corners |
+| a rotation or other non-linear composition is in the chain (`axis-turn` under a state input) | a conservative bound: the swept envelope of the turning subtree over the joint's range, or an extremum search on the offending coordinate with a stated step | `bounded`, with the method |
+| neither is available | sample the range with a stated step | `sampled`, with the range and the samples; **never** worded as a whole-range guarantee |
+
+- A violation found anywhere in the range is a violation. The gate never widens the occupancy to make it go away.
+  The author either declares a volume that covers the valid range, or narrows the allowed state range.
+- The endpoint-only shortcut is **wrong** for a rotating long part: inside at both end angles, out in the middle.
+  That case takes the `bounded` row, not the `proven` one.
+
+## 4. What the converter writes with this contract
+
+- V2 cylinder with `keepRound: false` and differing cross factors → `cylinder-shape@2` with `radiusX`, `radiusZ`
+  following their own axes. WORKER converts; `ELLIPTIC_SECTION` is retired.
+- V2 rect or hollow rect whose section follows the instance → `rounded-box@2` / `hollow-box@2` with per-axis corner
+  radii `r·fx`, `r·fz`. `ROUND_NOT_SCALED` is retired.
+- V2 `scale` channel on a part, two linear keys, from a parameter → each scaled dimension becomes
+  `dim × affine(p)`; the part's centre is unchanged (V2 scaled about the part centre). The dependence set of every
+  affected length includes the parameter. DRY_ROOM's lamps and ROLL_CRADLE's roll convert; `ANIMATION_CHANNEL`
+  stays only for channels the contract does not cover (pivots, compound axes, curves other than two linear keys).
+- The report marks every state-dependent dimension it wrote, and the occupancy inspection of a converted asset
+  runs over the parameter ranges as §3 says.
+
+## 5. Completion criterion for this contract
+
+- The four providers' `@2` forms compile, evaluate, and their `@1` forms are unchanged (the operator-list guard
+  gains the four names).
+- Dependence appears in `outputTypes`; a synthetic new operator with no policy fails to compile when handed a
+  state-dependent value; `fit-pitch@1` and `fixed-count@1` still refuse it; a shape provider accepts it.
+- The three assets convert and match V2 at box level at 8 sizes × states, and the WORKER's legs match as ovals.
+- An occupancy check on the roll cradle reports `proven` over the `fed` range, and a synthetic rotating long part
+  reports `bounded`, with a violation found at a middle angle that the endpoints alone would have missed.
+- The mesh-level comparison of the completion criterion covers sections and corners, so an elliptic section drawn
+  round would fail it.
+
+## Not in this contract
+
+- Theme mapping and the colour cache (renderer work; ADR-0087 stage review ruling 4).
+- Shape deformation beyond dimensions: bending, twisting, free-form profiles that change with state. Those would be
+  new providers with their own contracts.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hatiolab/figure-model",
-  "version": "0.1.33",
+  "version": "0.1.35",
   "description": "Figure 저작 결과의 정본 형식과 검증 — 재질별로 병합되고 이름이 붙은 부품 그래프. 3D 로 저작한 형상 하나가 씬 컴포넌트로 서는 데 필요한 것을 담는다.",
   "keywords": [
     "figure",
@@ -62,6 +62,7 @@
     "access": "public"
   },
   "scripts": {
+    "version": "node scripts/sync-kernel-version.mjs && git add src/v3-kernel-version.ts",
     "build": "tsc -p tsconfig.build.json",
     "check": "tsc -p tsconfig.json --noEmit",
     "test": "npm run check && node --test src/*.test.ts",