@hatiolab/figure-model 0.1.34 → 0.1.36

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.34",
+  "version": "0.1.36",
   "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",