@hatiolab/figure-model 0.1.30 → 0.1.32

package/docs/prototypes/v3-linear-comparison.py

@@ -0,0 +1,183 @@
+"""Independent linear design comparison; not a production evaluator.
+Requires kiwisolver==1.4.9 in an isolated research environment.
+Run: python docs/prototypes/v3-linear-comparison.py
+All lengths mm. No external research implementation is copied.
+"""
+import itertools
+import json
+import math
+import sys
+import kiwisolver as kiwi
+
+assert kiwi.__version__ == "1.4.9"
+EPS = 1e-7
+results = []
+
+
+def close(a, b):
+    assert math.isfinite(a) and abs(a-b) <= EPS, (a, b)
+
+
+def dag(definitions, inputs):
+    values = dict(inputs)
+    active = []
+    assert not (set(definitions) & set(inputs)), "duplicate writer"
+    def visit(name):
+        if name in values:
+            return values[name]
+        if name in active:
+            raise ValueError("cycle: " + " -> ".join(active + [name]))
+        if name not in definitions:
+            raise ValueError("unknown: " + name)
+        active.append(name)
+        constant, terms = definitions[name]
+        value = constant + sum(coef * visit(ref) for ref, coef in terms.items())
+        assert math.isfinite(value)
+        active.pop()
+        values[name] = value
+        return value
+    for name in definitions:
+        visit(name)
+    return values
+
+
+def solve(names, make, order=None):
+    variables = {n: kiwi.Variable(n) for n in names}
+    constraints = make(variables)
+    solver = kiwi.Solver()
+    for i in (range(len(constraints)) if order is None else order):
+        solver.addConstraint(constraints[i])
+    solver.updateVariables()
+    assert all(not c.violated() for c in constraints)
+    return {n: v.value() for n,v in variables.items()}
+
+
+# Same physical conditions, different formulations; independent edge checks below.
+max_difference = 0
+for width in range(40, 10041, 100):
+    direct = dag({
+        "leaf": (-15, {"width": .5}),
+        "left": (2.5, {"width": -.25}),
+        "right": (-2.5, {"width": .25}),
+        "travel": (-5, {"width": .5})
+    }, {"width": width})
+    for reverse in [False, True]:
+        order = list(range(6))
+        if reverse:
+            order.reverse()
+        constrained = solve(["leaf","left","right","travel"], lambda v: [
+            2*v["leaf"] + 30 == width,
+            v["left"] - v["leaf"]/2 == -width/2 + 10,
+            v["right"] + v["leaf"]/2 == width/2 - 10,
+            v["left"] - v["travel"] + v["leaf"]/2 == -width/2,
+            v["leaf"] >= 1,
+            v["right"]-v["leaf"]/2 - (v["left"]+v["leaf"]/2) == 10
+        ], order)
+        for key in constrained:
+            close(constrained[key], direct[key])
+            max_difference = max(max_difference, abs(constrained[key]-direct[key]))
+        close(constrained["right"]+constrained["travel"]-constrained["leaf"]/2, width/2)
+results.append({"case":"doors_101_widths_two_orders", "solver_runs":202,
+                "max_difference_mm":max_difference})
+
+for length in [.5, 1, 2, 1000]:
+    direct = dag({"size": (0, {"high":1,"low":-1}),
+                  "center": (0, {"high":.5,"low":.5})},
+                 {"low":-length/2, "high":length/2})
+    solved = solve(["size","center"], lambda v:[
+        v["center"]-v["size"]/2 == -length/2,
+        v["center"]+v["size"]/2 == length/2,
+        v["size"] >= .001
+    ])
+    close(solved["size"], direct["size"])
+    close(solved["center"], direct["center"])
+results.append({"case":"two_boundaries", "runs":4, "all_exact_within_tolerance":True})
+
+# r1's greedy auto-track algorithm required 150 instead of the feasible 110.
+def grid_constraints(v):
+    return [v["a"]>=10, v["b"]>=10, v["c"]>=10,
+            v["a"]+v["b"]>=100, v["b"]+v["c"]>=100,
+            v["a"]+v["b"]+v["c"]==110]
+for order in itertools.permutations(range(6)):
+    values = solve(["a","b","c"], grid_constraints, order)
+    for name, expected in zip(["a","b","c"], [10,90,10]):
+        close(values[name], expected)
+results.append({"case":"feasible_overlapping_spans", "orders":720, "solution_mm":[10,90,10],
+                "dag":"requires an authored allocation; inequalities alone are not its input language"})
+
+for reverse in [False, True]:
+    try:
+        solve(["p"], lambda v:[v["p"]==0, v["p"]==100],
+              [1,0] if reverse else [0,1])
+        raise AssertionError("conflict accepted")
+    except kiwi.UnsatisfiableConstraint:
+        pass
+results.append({"case":"contradictory_point", "orders":2, "required_conflict_rejected":True})
+
+for width in [20, 30, 31]:
+    direct = dag({"leaf": (-15, {"width":.5})}, {"width":width})
+    assert direct["leaf"] < 1  # A domain check is necessary after DAG evaluation.
+    try:
+        solve(["leaf"], lambda v:[2*v["leaf"]+30==width, v["leaf"]>=1])
+        raise AssertionError("invalid size accepted")
+    except kiwi.UnsatisfiableConstraint:
+        pass
+results.append({"case":"impossible_door_width", "widths_mm":[20,30,31],
+                "dag":"domain violation; no silent clamping", "kiwi":"required conflict"})
+
+cycle = {"parent":(20,{"child":1}), "child":(0,{"parent":.5})}
+try:
+    dag(cycle,{})
+    raise AssertionError("cycle accepted")
+except ValueError as exc:
+    cycle_error = str(exc)
+cyclic_solution = solve(["parent","child"],lambda v:[
+    v["parent"]==v["child"]+20, v["child"]==v["parent"]/2])
+close(cyclic_solution["parent"],40)
+close(cyclic_solution["child"],20)
+results.append({"case":"solvable_cycle","dag":cycle_error,"kiwi":cyclic_solution})
+
+# Same-strength preferences leave many optima: do not confuse a returned solution with intent.
+tie_outcomes = []
+for reverse in [False,True]:
+    x = kiwi.Variable("x")
+    solver = kiwi.Solver()
+    preferences = [(x==0)|"weak", (x==100)|"weak"]
+    for c in (reversed(preferences) if reverse else preferences):
+        solver.addConstraint(c)
+    solver.updateVariables()
+    assert -EPS <= x.value() <= 100+EPS
+    tie_outcomes.append(x.value())
+results.append({"case":"equal_strength_preferences","values_mm":tie_outcomes,
+                "meaning":"any x in [0,100] has the same sum of absolute errors; no unique intended result"})
+
+x = kiwi.Variable("x")
+solver = kiwi.Solver()
+solver.addConstraint(x>=0)
+solver.addConstraint(x<=100)
+solver.addEditVariable(x,"strong")
+solver.suggestValue(x,120)
+solver.updateVariables()
+close(x.value(),100)
+results.append({"case":"edit_suggestion_not_requirement","requested_mm":120,
+                "actual_mm":x.value(),"must_report_delta_mm":120-x.value()})
+
+# Unique equalities under resize and return: measure edit suggestions AND original invariants.
+w, leaf, left = [kiwi.Variable(n) for n in ["w","leaf","left"]]
+solver = kiwi.Solver()
+solver.addConstraint(2*leaf+30==w)
+solver.addConstraint(left-leaf/2 == -w/2+10)
+solver.addConstraint(leaf>=1)
+solver.addEditVariable(w,"strong")
+for target in [1440,2880,40,1440]:
+    solver.suggestValue(w,target)
+    solver.updateVariables()
+    close(w.value(),target)
+    close(leaf.value(),(target-30)/2)
+    close(left.value()-leaf.value()/2,-target/2+10)
+results.append({"case":"incremental_resize_return","widths_mm":[1440,2880,40,1440],
+                "invariants_and_requested_values_checked":True})
+
+print(json.dumps({"python":sys.version,"kiwi":kiwi.__version__,"tolerance_mm":EPS,
+                  "scope":"linear scalar design experiments; not 3D geometry or user-intent proof",
+                  "results":results},indent=2))

package/docs/prototypes/v3-more-samples.test.mjs

@@ -0,0 +1,182 @@
+// Design probes, not a v3 implementation. No source assets are modified.
+import fs from 'node:fs'
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { createHash } from 'node:crypto'
+import { validate } from '../../src/validate.ts'
+import { centredPart } from '../../src/origin.ts'
+import { sizingPosition, sizingScale, rotatedExtent, repeatPlanOfPart, repeatOffset } from '../../src/sizing.ts'
+
+const files = [new URL('../../../operato-application/packages/operato-figure/server/seed/figure-samples.json',import.meta.url),
+  new URL('../../src/fixtures/robot-arm-6dof.json',import.meta.url),new URL('../../src/fixtures/gantry-crane-3dof.json',import.meta.url)]
+const all = [...JSON.parse(fs.readFileSync(files[0])).map(x=>x.source),...files.slice(1).map(f=>JSON.parse(fs.readFileSync(f)))]
+const source = type => all.find(s=>s.type===type)
+const part = (s,n) => { const p=s.parts.find(p=>p.name===n);assert.ok(p,n);return p }
+const axes=['x','y','z'], unit={x:1,y:1,z:1}
+const near=(a,b)=>assert.ok(Number.isFinite(a)&&Math.abs(a-b)<1e-7,`${a} != ${b}`)
+// Bounds of the declared rotated box, NOT exact polygon/rounded shape contact.
+function bounds(s,n,scale=unit) {
+  const p=centredPart({...part(s,n),sizing:part(s,n).sizing??'scale'},s.base)
+  const at=sizingPosition(p,scale,s.base),factor=sizingScale(p,scale,s.base),extent=rotatedExtent(p)
+  return Object.fromEntries(axes.map(a=>{
+    const center=at[a]*scale[a]+(a==='y'?s.base.y*scale.y/2:0),size=extent[a]*factor[a]*scale[a]
+    return [a,{center,size,min:center-size/2,max:center+size/2}]
+  }))
+}
+function channel(s,param,target) {
+  const p=s.parameters.find(p=>p.name===param),c=p.clip.channels.find(c=>c.target===target)
+  assert.ok(c);assert.equal(c.keys.length,2);assert.equal(c.keys[0].at,0);assert.equal(c.keys[1].at,1)
+  return {p,c}
+}
+function sampleChannel(c,t) {
+  return Object.fromEntries(axes.map(a=>[a,c.keys[0].value[a]*(1-t)+c.keys[1].value[a]*t]))
+}
+
+test('16 sources: validation, finite sizing at 27 scales, baseline positions; provenance',()=>{
+  let checks=0
+  for(const s of all) {
+    assert.deepEqual(validate(s).errors,[],s.type)
+    for(const x of [.5,1,2])for(const y of [.5,1,2])for(const z of [.5,1,2])for(const p of s.parts) {
+      const b=bounds(s,p.name,{x,y,z})
+      for(const a of axes) {assert.ok(Number.isFinite(b[a].center));assert.ok(Number.isFinite(b[a].size)&&b[a].size>0)}
+      if(x===1&&y===1&&z===1)for(const a of axes)near(b[a].center,p.transform.position[a])
+      checks++
+    }
+  }
+  console.log(JSON.stringify({models:all.length,partScaleChecks:checks,provenance:files.map(f=>({path:f.pathname,sha256:createHash('sha256').update(fs.readFileSync(f)).digest('hex')})),scope:'finite numbers and source validity, NOT assembly correctness'}))
+})
+
+test('MIXER: fixed motor attachment cannot be inferred from independent scale positions',()=>{
+  const s=source('MIXER'),body=part(s,'body'),motor=part(s,'motor')
+  const overlap=body.transform.position.y+body.transform.size.y/2-(motor.transform.position.y-motor.transform.size.y/2)
+  near(overlap,5)
+  for(const h of [400,800,1600]) {
+    // Explicit proposed intent: motor height fixed; body height proportional.
+    const top=500*h/800,motorCenter=top-overlap+motor.transform.size.y/2
+    near(top-(motorCenter-80),5)
+  }
+})
+
+test('AGV: concentric wheels/hubs survive scaling but wheel ground contact does not always',()=>{
+  const s=source('AGV'),rows=[]
+  for(const scale of [unit,{x:1,y:2,z:1},{x:2,y:1,z:2}])for(const suffix of ['front-left','front-right','rear-left','rear-right']) {
+    const w=bounds(s,`wheel-${suffix}`,scale),h=bounds(s,`hub-${suffix}`,scale),r=w.y.size/2
+    for(const a of axes)near(w[a].center,h[a].center)
+    near(w.y.size,w.z.size)
+    rows.push({scale,suffix,bottom:w.y.min,radius:r})
+  }
+  assert.ok(rows.some(r=>Math.abs(r.bottom)>1))
+  console.log(JSON.stringify({agv:rows.filter(r=>r.suffix==='front-left'),gap:'roundness does not imply floor contact; wheel center must reference radius'}))
+})
+
+test('SIGNAL_TOWER_3: real contact chain survives height changes with fixed lamp sizes',()=>{
+  const s=source('SIGNAL_TOWER_3')
+  const pairs=[['foot','pole'],['pole','bracket'],['bracket','lamp-lower'],['lamp-lower','ring-lower'],['ring-lower','lamp-middle'],['lamp-middle','ring-upper'],['ring-upper','lamp-upper'],['lamp-upper','cap']]
+  for(const height of [550,1100,2200,3300])for(const [a,b] of pairs) {
+    const before=bounds(s,b).y.min-bounds(s,a).y.max
+    near(bounds(s,b,{x:1,y:height/s.base.y,z:1}).y.min-bounds(s,a,{x:1,y:height/s.base.y,z:1}).y.max,before)
+  }
+  for(const n of ['lamp-lower','lamp-middle','lamp-upper'])near(bounds(s,n,{x:1,y:3,z:1}).y.size,90)
+})
+
+test('WORKER: intentional non-round primitives must not be forced to circular profiles',()=>{
+  const s=source('WORKER'),scale={x:2,y:1,z:.5}
+  for(const n of ['leg-left','arm-left','hand-left','helmet','helmet-brim']) {
+    assert.equal(part(s,n).keepRound,false)
+    const b=bounds(s,n,scale)
+    for(const a of axes)near(b[a].size,part(s,n).transform.size[a]*scale[a])
+  }
+  assert.equal(s.joints,undefined)
+  console.log(JSON.stringify({worker:'static sample only; no walk/pose animation evidence',gap:'ellipse/ellipsoid semantics must coexist with circular rollers'}))
+})
+
+test('KIOSK: screen aperture margins and protrusion are distinct from same-center attachment',()=>{
+  const s=source('KIOSK'),screen=bounds(s,'screen'),bezel=bounds(s,'bezel')
+  near((bezel.x.size-screen.x.size)/2,30);near((bezel.y.size-screen.y.size)/2,30)
+  near(screen.z.max-bezel.z.max,8)
+  for(const width of [205,410,820]) {
+    const opening=width-60;assert.ok(opening>0);near((width-opening)/2,30)
+  }
+  assert.ok(50-60<0) // candidate fixed-margin intent must reject a too-small bezel.
+})
+
+for(const type of ['CELL_TRAY','FORMATION_TRAY'])test(`${type}: fixed count, wall clearance and cell/contact correspondence`,()=>{
+  const s=source(type),cell=part(s,'cell'),tub=part(s,'tub')
+  for(const scale of [.5,1,2]) {
+    const plan=repeatPlanOfPart(cell,{x:scale,y:1,z:1},s.base)
+    assert.equal(plan.count,8)
+    const edge=(repeatOffset(plan.count-1,plan.count,plan.pitch)+cell.transform.size.x/2)*scale
+    // Explicit v3 candidate: wall thickness remains 30mm. Geometry fits only above a bound.
+    const clearance=s.base.x*scale/2-tub.shape.hollow.wall-edge
+    near(clearance,36*scale-30)
+    if(type==='FORMATION_TRAY') {
+      const other=repeatPlanOfPart(part(s,'contact'),{x:scale,y:1,z:1},s.base)
+      assert.equal(other.count,plan.count);near(other.pitch,plan.pitch)
+    }
+  }
+  console.log(JSON.stringify({type,fixedCount:8,candidateFixedWallClearanceAtHalfScaleMm:-12,minimumScale:30/36,scope:'fixed-wall candidate; not a claim about current rendered wall scaling'}))
+})
+
+test('ROLL_CRADLE: state-driven diameter is geometry change, not rigid joint motion',()=>{
+  const s=source('ROLL_CRADLE'),{c}=channel(s,'fed','roll'),r=part(s,'roll'),core=part(s,'core')
+  assert.equal(c.path,'scale')
+  for(const t of [0,.25,.5,.75,1]) {
+    const v=sampleChannel(c,t)
+    near(v.x,v.z);near(v.y,1)
+    assert.ok(r.transform.size.x*v.x>=core.transform.size.x)
+    near(r.transform.size.y*v.y,1000)
+  }
+  near(r.transform.size.x*sampleChannel(c,1).x,224)
+  console.log(JSON.stringify({cradle:{diameterRangeMm:[700,224],coreDiameterMm:200},gap:'state-dependent shape dimensions needed beyond rigid J; resizing radius times state factor is bilinear if both are variable'}))
+})
+
+test('MODULE_PALLET: terminals exceed base height; base is not automatic containment',()=>{
+  const s=source('MODULE_PALLET'),deck=bounds(s,'deck'),module=bounds(s,'module')
+  near(deck.y.max,module.y.min)
+  for(const n of ['terminal-left','terminal-right'])near(bounds(s,n).y.max-s.base.y,45)
+  for(const n of ['foot-front-left','foot-front-right','foot-back-left','foot-back-right']) {
+    near(bounds(s,n).y.min,0);near(bounds(s,n).y.max,deck.y.min)
+  }
+})
+
+test('ROLL_PRESS: opening state versus finite web thickness exposes collision intent ambiguity',()=>{
+  const s=source('ROLL_PRESS'),upper=bounds(s,'roll-upper'),lower=bounds(s,'roll-lower'),web=bounds(s,'web')
+  const uc=channel(s,'nip','roll-upper').c,wc=channel(s,'nip','web').c,rows=[]
+  for(const opening of [0,12,24,120,240]) {
+    const u=sampleChannel(uc,opening/240).y,w=sampleChannel(wc,opening/240).y
+    near((upper.y.min+u)-lower.y.max,opening)
+    near(web.y.center+w,(upper.y.min+u+lower.y.max)/2)
+    const clearance=(opening-web.y.size)/2
+    near(web.y.min+w-lower.y.max,clearance)
+    rows.push({opening,clearancePerSideMm:clearance})
+  }
+  console.log(JSON.stringify({rollPress:rows,gap:'24mm web at zero gap overlaps both rolls by 12mm; distinguish schematic compression from forbidden collision'}))
+})
+
+test('FORMATION_CHARGER: shelf/lamp repeat pairing and envelope at count thresholds',()=>{
+  const s=source('FORMATION_CHARGER'),rows=[]
+  for(const height of [1400,2799.99,2800,2800.01,5600]) {
+    const scale={x:1,y:height/s.base.y,z:1}
+    const a=repeatPlanOfPart(part(s,'shelf'),scale,s.base),b=repeatPlanOfPart(part(s,'channel-lamp'),scale,s.base)
+    assert.equal(a.count,b.count);near(a.pitch,b.pitch)
+    near(bounds(s,'shelf',scale).y.center,bounds(s,'channel-lamp',scale).y.center)
+    const first=bounds(s,'shelf',scale).y.center+repeatOffset(0,a.count,a.pitch)-20
+    rows.push({height,count:a.count,firstShelfBottom:first})
+  }
+  console.log(JSON.stringify({charger:rows,gap:'paired instances need common stable index; whole-base count does not guarantee plinth/HMI clearance'}))
+})
+
+test('GANTRY_CRANE_3DOF: 27 travel combinations inherit each translation exactly once',()=>{
+  const s=source('GANTRY_CRANE_3DOF')
+  for(const x of [-1600,0,1600])for(const z of [-900,0,900])for(const drop of [0,900,1800]) {
+    const q={'bridge-travel':x,'trolley-traverse':z,'hoist-drop':drop},offsets={}
+    for(const p of s.parts) {
+      const inherited=p.parent?offsets[p.parent]:{x:0,y:0,z:0},j=s.joints.find(j=>j.child===p.name)
+      if(j)assert.equal(j.type,'prismatic')
+      offsets[p.name]=Object.fromEntries(axes.map(a=>[a,inherited[a]+(j?j.axis[a]*q[j.name]:0)]))
+    }
+    near(offsets['hook-seat'].x,x);near(offsets['hook-seat'].z,z);near(offsets['hook-seat'].y,-drop)
+    near(part(s,'hook').transform.position.y+offsets.hook.y-(part(s,'hook-seat').transform.position.y+offsets['hook-seat'].y),60)
+    near(offsets['leg-1'].x,0)
+  }
+})

package/docs/prototypes/v3-payload-collision.mjs

@@ -0,0 +1,54 @@
+import {compilePayloadInspection} from './v3-payload-fit.mjs'
+import {ContractError} from './v3-typed-plan.mjs'
+const dot=(a,b)=>a.reduce((s,v,i)=>s+v*b[i],0)
+const cross=(a,b)=>[a[1]*b[2]-a[2]*b[1],a[2]*b[0]-a[0]*b[2],a[0]*b[1]-a[1]*b[0]]
+const columns=r=>[0,1,2].map(i=>r.map(row=>row[i]))
+export function boxRelation(a,b,tolerance=1e-6){
+ // Static OBB SAT: 3 + 3 face normals and 9 cross-product axes.
+ for(const box of [a,b]){
+  if(!box||!Array.isArray(box.center)||box.center.length!==3||!Array.isArray(box.half)||box.half.length!==3||!Array.isArray(box.axes)||box.axes.length!==3||box.axes.some(v=>!Array.isArray(v)||v.length!==3)||[...box.center,...box.half,...box.axes.flat()].some(v=>!Number.isFinite(v))||box.half.some(v=>v<=0))throw new ContractError('OBB_DOMAIN','collision','finite positive OBB required')
+  for(let i=0;i<3;i++)for(let j=0;j<3;j++)if(Math.abs(dot(box.axes[i],box.axes[j])-(i===j?1:0))>1e-9)throw new ContractError('OBB_FRAME','collision','orthonormal axes required')
+ }
+ if(!Number.isFinite(tolerance)||tolerance<0)throw new ContractError('OBB_DOMAIN','collision','invalid tolerance')
+ const delta=b.center.map((v,i)=>v-a.center[i]),axes=[...a.axes,...b.axes,...a.axes.flatMap(x=>b.axes.map(y=>cross(x,y)))]
+ let minOverlap=Infinity,uncertain=false
+ for(const axis of axes){
+  const norm=Math.hypot(...axis)
+  if(norm===0)continue
+  if(norm<1e-12){uncertain=true;continue}
+  const n=axis.map(v=>v/norm),radius=box=>box.half.reduce((s,h,i)=>s+h*Math.abs(dot(box.axes[i],n)),0)
+  const overlap=radius(a)+radius(b)-Math.abs(dot(delta,n))
+  if(overlap < -tolerance)return {relation:'separated',separationMm:-overlap}
+  minOverlap=Math.min(minOverlap,overlap)
+ }
+ if(uncertain)return {relation:'unverified',reason:'NEAR_PARALLEL_NUMERICS'}
+ return {relation:minOverlap<=tolerance?'touching':'penetrating',minimumAxisOverlapMm:Math.max(0,minOverlap)}
+}
+function envelope(g){
+ const d=g.shape.dimensions;let half
+ if(['box','roundedBox'].includes(g.shape.provider))half=[d.width/2,d.height/2,d.depth/2]
+ else if(g.shape.provider==='cylinder')half=[d.radius,d.length/2,d.radius]
+ else return null
+ return {center:g.pose.t,axes:columns(g.pose.r),half}
+}
+export function compileCollisionInspection(model,declaration){
+ const plan=compilePayloadInspection(model,declaration)
+ return {evaluate(input,payload){
+  const result=plan.evaluate(input,payload),binding=result.evaluation.bindings.find(b=>b.id===payload.bindingId)
+  const a=payload.yawDeg*Math.PI/180,c=Math.cos(a),s=Math.sin(a),r=binding.pose.r
+  const mv=v=>r.map(row=>dot(row,v)),axes=[[c,0,-s],[0,1,0],[s,0,c]].map(mv)
+  const box={center:mv(payload.center).map((v,i)=>v+binding.pose.t[i]),axes,half:payload.dimensions.map(v=>v/2)}
+  const pairs=result.evaluation.geometry.map(g=>{
+   const bounds=envelope(g)
+   if(!bounds)return {geometryId:g.id,status:'unverified',reason:'UNSUPPORTED_ENVELOPE'}
+   const relation=boxRelation(box,bounds),exact=g.shape.provider==='box'
+   if(relation.relation==='separated')return {geometryId:g.id,status:'satisfied',reason:exact?'BOX_SEPARATED':'CONSERVATIVE_ENVELOPE_SEPARATED',...relation}
+   if(!exact)return {geometryId:g.id,status:'unverified',reason:'ENVELOPE_OVERLAP_NEEDS_NARROW_PHASE'}
+   if(relation.relation==='unverified')return {geometryId:g.id,status:'unverified',reason:relation.reason}
+   return {geometryId:g.id,status:relation.relation==='penetrating'?'failed':'satisfied',reason:relation.relation==='penetrating'?'BOX_PENETRATION':'TOUCH_WITHIN_TOLERANCE',...relation}
+  })
+  const status=pairs.some(p=>p.status==='failed')?'failed':pairs.some(p=>p.status==='unverified')?'unverified':'satisfied'
+  result.inspection.collision={status,scope:'payload-vs-every-model-part-at-current-state',method:'obb-sat-v1',distanceToleranceMm:1e-6,pairs}
+  return result
+ }}
+}

package/docs/prototypes/v3-payload-collision.test.mjs

@@ -0,0 +1,68 @@
+import {test} from 'node:test'
+import assert from 'node:assert/strict'
+import {boxRelation,compileCollisionInspection} from './v3-payload-collision.mjs'
+import {forkliftBindings} from './v3-capability-samples.mjs'
+import {defaults} from './v3-full-forklift.mjs'
+import {OBB} from '../../../things-scene/node_modules/three/examples/jsm/math/OBB.js'
+import * as THREE from '../../../things-scene/node_modules/three/build/three.module.js'
+const identity=[[1,0,0],[0,1,0],[0,0,1]],box=(center,half=[1,1,1],axes=identity)=>({center,half,axes})
+const payload={bindingId:'load-low',type:'PALLET',occupied:0,dimensions:[620,100,850],center:[260,50,0],yawDeg:0}
+const near=(a,b)=>assert.ok(Math.abs(a-b)<1e-7)
+test('SAT separates, touches, penetrates and handles complete containment symmetrically',()=>{
+ for(const [x,expected] of [[3,'separated'],[2,'touching'],[1,'penetrating'],[0,'penetrating']]){
+  const a=box([0,0,0]),b=box([x,0,0]);assert.equal(boxRelation(a,b).relation,expected);assert.equal(boxRelation(b,a).relation,expected)
+ }
+ assert.equal(boxRelation(box([0,0,0],[10,10,10]),box([0,0,0])).relation,'penetrating')
+ assert.equal(boxRelation(box([0,0,0]),box([2+2e-6,0,0])).relation,'separated')
+ assert.equal(boxRelation(box([0,0,0]),box([2+5e-7,0,0])).relation,'touching')
+})
+test('rotated boxes with overlapping world AABBs can be separated',()=>{
+ const t=Math.PI/4,axes=[[Math.cos(t),0,-Math.sin(t)],[0,1,0],[Math.sin(t),0,Math.cos(t)]]
+ const a=box([0,0,0],[5,1,.1],axes),b=box([.5,0,.5],[5,1,.1],axes)
+ assert.equal(boxRelation(a,b).relation,'separated')
+})
+test('payload bottom contact does not hide upper fork penetration',()=>{
+ const s=forkliftBindings(),p=compileCollisionInspection(s.model,s.declaration)
+ const r=p.evaluate(defaults,{...payload,dimensions:[620,500,850],center:[260,250,0]})
+ assert.equal(r.inspection.contact.status,'satisfied');assert.equal(r.inspection.collision.status,'failed')
+ for(const side of ['left','right'])assert.equal(r.inspection.collision.pairs.find(p=>p.geometryId==='fork-high-'+side).reason,'BOX_PENETRATION')
+ assert.equal(r.inspection.collision.pairs.find(p=>p.geometryId==='fork-low-left').reason,'TOUCH_WITHIN_TOLERANCE')
+ assert.equal(r.inspection.safety.status,'unverified')
+})
+test('all parts are checked, curved envelope overlap stays unverified, never automatically excluded',()=>{
+ const s=forkliftBindings(),p=compileCollisionInspection(s.model,s.declaration)
+ const r=p.evaluate(defaults,{...payload,dimensions:[50,50,50],center:[260,343,-1485]})
+ assert.equal(r.inspection.collision.pairs.length,20)
+ assert.equal(r.inspection.collision.pairs.find(p=>p.geometryId==='body').status,'unverified')
+ assert.equal(r.inspection.collision.pairs.find(p=>p.geometryId==='body').reason,'ENVELOPE_OVERLAP_NEEDS_NARROW_PHASE')
+})
+test('225 state combinations retain upper-fork collision and lower-fork touching',()=>{
+ const s=forkliftBindings(),p=compileCollisionInspection(s.model,s.declaration);let states=0
+ for(const forkLength of [425,850,1700])for(const lift of [0,500,1000,1500,2000])for(const reach of [0,200,400])for(const yawDeg of [-30,-15,0,15,30]){
+  const r=p.evaluate({...defaults,forkLength,lift,reach},{...payload,dimensions:[620,500,forkLength],center:[260,250,0],yawDeg})
+  assert.equal(r.inspection.collision.status,'failed')
+  for(const side of ['left','right'])assert.equal(r.inspection.collision.pairs.find(p=>p.geometryId==='fork-high-'+side).reason,'BOX_PENETRATION')
+  states++
+ }
+ assert.equal(states,225);console.log({payloadCollisionStates:states,pairChecks:states*20})
+})
+test('invalid OBB and numerical near-parallel ambiguity fail closed',()=>{
+ assert.throws(()=>boxRelation(box([0,0,0],[-1,1,1]),box([0,0,0])))
+ assert.throws(()=>boxRelation(box([0,0,0],[1,1,1],[[2,0,0],[0,1,0],[0,0,1]]),box([0,0,0])))
+ const a=1e-14,rot=[[Math.cos(a),Math.sin(a),0],[-Math.sin(a),Math.cos(a),0],[0,0,1]]
+ assert.equal(boxRelation(box([0,0,0]),box([0,0,0],[1,1,1],rot)).relation,'unverified')
+})
+test('1000 deterministic general 3D pairs agree with Three.js OBB implementation',()=>{
+ let state=983451,intersections=0,separations=0
+ const random=()=>{state=(Math.imul(1664525,state)+1013904223)>>>0;return state/2**32}
+ const make=()=>{const matrix=new THREE.Matrix3().setFromMatrix4(new THREE.Matrix4().makeRotationFromEuler(new THREE.Euler(random()*6,random()*6,random()*6)))
+  const e=matrix.elements,center=Array.from({length:3},()=>random()*20-10),half=Array.from({length:3},()=>.1+random()*6)
+  return {ours:box(center,half,[[e[0],e[1],e[2]],[e[3],e[4],e[5]],[e[6],e[7],e[8]]]),reference:new OBB(new THREE.Vector3(...center),new THREE.Vector3(...half),matrix)}}
+ for(let i=0;i<1000;i++){
+  const a=make(),b=make(),expected=a.reference.intersectsOBB(b.reference),r=boxRelation(a.ours,b.ours)
+  assert.notEqual(r.relation,'unverified');assert.equal(r.relation!=='separated',expected)
+  assert.equal(boxRelation(b.ours,a.ours).relation,r.relation)
+  if(expected)intersections++;else separations++
+ }
+ assert.ok(intersections>0&&separations>0);console.log({obbReferencePairs:1000,intersections,separations})
+})

package/docs/prototypes/v3-payload-fit.mjs

@@ -0,0 +1,58 @@
+// Bounded geometric inspection, not a load-bearing or collision-safety certificate.
+import {compileCapabilities} from './v3-capability-plan.mjs'
+import {ContractError} from './v3-typed-plan.mjs'
+const fail=(code,message)=>{throw new ContractError(code,'payload',message)}
+const dot=(a,b)=>a.reduce((s,v,i)=>s+v*b[i],0)
+const mv=(r,v)=>r.map(row=>dot(row,v))
+const local=(pose,p)=>[0,1,2].map(i=>pose.r.reduce((s,row,j)=>s+row[i]*(p[j]-pose.t[j]),0))
+const world=(pose,p)=>mv(pose.r,p).map((v,i)=>v+pose.t[i])
+function clip(poly,axis,bound,sign){
+ const out=[]
+ for(let i=0;i<poly.length;i++){
+  const a=poly[i],b=poly[(i+1)%poly.length],da=sign*(a[axis]-bound),db=sign*(b[axis]-bound),inside=da<=0,next=db<=0
+  if(inside)out.push(a)
+  if(inside!==next){const t=da/(da-db);out.push(a.map((v,j)=>v+t*(b[j]-v)))}
+ }
+ return out
+}
+function overlapArea(poly,width,depth){
+ for(const [axis,bound,sign] of [[0,width/2,1],[0,-width/2,-1],[1,depth/2,1],[1,-depth/2,-1]])poly=clip(poly,axis,bound,sign)
+ return Math.abs(poly.reduce((sum,p,i)=>{const q=poly[(i+1)%poly.length];return sum+p[0]*q[1]-q[0]*p[1]},0))/2
+}
+export function compilePayloadInspection(model,declaration){
+ const plan=compileCapabilities(model,declaration)
+ return {evaluate(input,payload){
+  const keys=['bindingId','type','occupied','dimensions','center','yawDeg']
+  if(!payload||typeof payload!=='object'||Array.isArray(payload)||Object.keys(payload).length!==keys.length||keys.some(k=>!Object.hasOwn(payload,k)))fail('SCHEMA','expected bindingId,type,occupied,dimensions,center,yawDeg')
+  if(typeof payload.bindingId!=='string')fail('SCHEMA','bindingId required')
+  for(const key of ['dimensions','center'])if(!Array.isArray(payload[key])||payload[key].length!==3||payload[key].some(v=>typeof v!=='number'||!Number.isFinite(v)))fail('PAYLOAD_DOMAIN','finite 3D vectors required')
+  if(payload.dimensions.some(v=>v<=0)||!Number.isFinite(payload.yawDeg))fail('PAYLOAD_DOMAIN','positive dimensions and finite yaw required')
+  // Explicit supported numeric envelope. Never silently clamp a larger asset.
+  if([...payload.dimensions,...payload.center].some(v=>Math.abs(v)>1e6)||Math.abs(payload.yawDeg)>360)fail('PAYLOAD_LIMIT','experimental envelope: 1e6 mm and yaw ±360 degrees')
+  const evaluation=plan.evaluate(input,{[payload.bindingId]:{type:payload.type,occupied:payload.occupied}})
+  const binding=evaluation.bindings.find(b=>b.id===payload.bindingId)
+  if(!binding)fail('TARGET_ABSENT',payload.bindingId)
+  const [w,h,d]=payload.dimensions,a=payload.yawDeg*Math.PI/180,c=Math.cos(a),s=Math.sin(a)
+  const rotate=([x,y,z])=>[c*x+s*z,y,-s*x+c*z].map((v,i)=>v+payload.center[i])
+  const bottom=[[-w/2,-h/2,-d/2],[w/2,-h/2,-d/2],[w/2,-h/2,d/2],[-w/2,-h/2,d/2]].map(rotate)
+  const corners=[...bottom,...bottom.map(v=>[v[0],v[1]+h,v[2]])]
+  const distanceToleranceMm=1e-6,areaToleranceMm2=1e-6
+  let containment={status:'unverified',reason:'NO_REGION'}
+  if(binding.region){const excess=Math.max(...corners.flatMap(p=>p.map((v,i)=>Math.abs(v)-binding.region.dimensions[i]/2)));containment={status:excess<=distanceToleranceMm?'satisfied':'failed',reason:excess<=distanceToleranceMm?'BOX_CONTAINED':'OUTSIDE_REGION',excessMm:Math.max(0,excess)}}
+  const up=mv(binding.pose.r,[0,1,0]),bottomWorld=bottom.map(p=>world(binding.pose,p))
+  const contacts=binding.contacts.map(surface=>{
+   const base={geometryId:surface.geometryId,feature:surface.feature}
+   if(binding.role!=='seat'||surface.provider!=='box'||surface.face!=='top')return {...base,status:'unverified',reason:'UNSUPPORTED_CONTACT_PAIR'}
+   if(Math.abs(dot(up,surface.normal)-1)>1e-9)return {...base,status:'unverified',reason:'NONPARALLEL_FACES'}
+   const geometry=evaluation.geometry.find(g=>g.id===surface.geometryId)
+   if(!geometry)fail('TARGET_ABSENT',surface.geometryId)
+   const points=bottomWorld.map(p=>local(surface.pose,p)),dim=geometry.shape.dimensions
+   const overlap=overlapArea(points.map(p=>[p[0],p[2]]),dim.width,dim.depth)
+   const minGap=Math.min(...points.map(p=>p[1])),maxGap=Math.max(...points.map(p=>p[1]))
+   const reason=overlap<=areaToleranceMm2?'NO_POSITIVE_CONTACT_AREA':minGap < -distanceToleranceMm?'PENETRATES_SUPPORT_PLANE':maxGap>distanceToleranceMm?'ABOVE_SUPPORT':'PLANAR_CONTACT'
+   return {...base,status:reason==='PLANAR_CONTACT'?'satisfied':'failed',reason,overlapAreaMm2:overlap,minGapMm:minGap,maxGapMm:maxGap}
+  })
+  const contactStatus=!contacts.length?'unverified':contacts.some(c=>c.status==='failed')?'failed':contacts.some(c=>c.status==='unverified')?'unverified':'satisfied'
+  return {evaluation,inspection:{bindingId:binding.id,method:'box-payload/box-top-v1',distanceToleranceMm,areaToleranceMm2,containment,contact:{status:contactStatus,surfaces:contacts},collision:{status:'unverified',reason:'GLOBAL_COLLISION_NOT_CHECKED'},stability:{status:'unverified',reason:'CENTER_OF_MASS_AND_FORCES_NOT_CHECKED'},safety:{status:'unverified',reason:'NOT_CHECKED'}}}
+ }}
+}

package/docs/prototypes/v3-payload-fit.test.mjs

@@ -0,0 +1,59 @@
+import {test} from 'node:test'
+import assert from 'node:assert/strict'
+import {compilePayloadInspection} from './v3-payload-fit.mjs'
+import {forkliftBindings,robotBinding} from './v3-capability-samples.mjs'
+import {defaults} from './v3-full-forklift.mjs'
+import {defaults as robotDefaults} from './v3-full-robot.mjs'
+const payload={bindingId:'load-low',type:'PALLET',occupied:0,dimensions:[620,100,850],center:[260,50,0],yawDeg:0}
+const plan=s=>compilePayloadInspection(s.model,s.declaration)
+const near=(a,b)=>assert.ok(Math.abs(a-b)<1e-5,`${a} != ${b}`)
+test('both physical fork surfaces support the payload through size/lift/reach/yaw states',()=>{
+ const p=plan(forkliftBindings());let states=0
+ for(const forkLength of [425,850,1700])for(const lift of [0,1000,2000])for(const reach of [0,200,400])for(const yawDeg of [-30,0,30]){
+  const q={...payload,dimensions:[620,100,forkLength],yawDeg},r=p.evaluate({...defaults,forkLength,lift,reach},q)
+  assert.equal(r.inspection.contact.status,'satisfied');assert.equal(r.inspection.containment.status,'unverified')
+  assert.equal(r.evaluation.geometry.length,20)
+  for(const c of r.inspection.contact.surfaces){near(c.minGapMm,0);near(c.maxGapMm,0);assert.ok(c.overlapAreaMm2>0);if(!yawDeg)near(c.overlapAreaMm2,90*forkLength)}
+  states++
+ }
+ console.log({payloadContactStates:states})
+})
+test('floating, penetration, missing one fork and zero-area edge touch fail explicitly',()=>{
+ const p=plan(forkliftBindings())
+ for(const [center,reason] of [[[260,51,0],'ABOVE_SUPPORT'],[[260,49,0],'PENETRATES_SUPPORT_PLANE'],[[0,50,0],'NO_POSITIVE_CONTACT_AREA'],[[-355,50,0],'NO_POSITIVE_CONTACT_AREA']]){
+  const r=p.evaluate(defaults,{...payload,center}).inspection
+  assert.equal(r.contact.status,'failed');assert.ok(r.contact.surfaces.some(c=>c.reason===reason))
+  if(center[0]===-355)assert.equal(r.contact.surfaces[0].overlapAreaMm2,0)
+ }
+ // Narrow object fits between the forks: no support, even though a broad region could contain it.
+ const r=p.evaluate(defaults,{...payload,dimensions:[100,100,850]}).inspection;assert.ok(r.contact.surfaces.every(c=>c.reason==='NO_POSITIVE_CONTACT_AREA'))
+})
+test('containment checks all rotated box corners and does not imply support',()=>{
+ const s=forkliftBindings();for(const [id,value] of [['regionW',1200],['regionH',400],['regionD',900]])s.model.constants.push({id,value,unit:'mm'})
+ s.declaration.bindings[0].region={kind:'centered-box',dimensions:['regionW','regionH','regionD']}
+ const p=plan(s),ok=p.evaluate(defaults,payload).inspection;assert.equal(ok.containment.status,'satisfied')
+ const outside=p.evaluate(defaults,{...payload,yawDeg:45}).inspection;assert.equal(outside.containment.status,'failed')
+ const floating=p.evaluate(defaults,{...payload,center:[260,60,0]}).inspection;assert.equal(floating.containment.status,'satisfied');assert.equal(floating.contact.status,'failed')
+})
+test('contact result invariant under shared rigid rotation; not a gravity stability proof',()=>{
+ const original=plan(forkliftBindings()).evaluate(defaults,payload).inspection
+ for(const angle of [-65,30,90]){
+  const s=forkliftBindings();s.model.constants.push({id:'tilt',value:angle,unit:'deg'});s.model.nodes.find(n=>n.id==='mastPose').args[5]='tilt'
+  const r=plan(s).evaluate({...defaults,lift:700,reach:120},payload).inspection
+  assert.equal(r.contact.status,'satisfied');r.contact.surfaces.forEach((c,i)=>near(c.overlapAreaMm2,original.contact.surfaces[i].overlapAreaMm2));assert.equal(r.stability.status,'unverified')
+ }
+})
+test('contact never certifies global collision, eligibility or safety',()=>{
+ const p=plan(forkliftBindings())
+ // Height 500 crosses the upper fork level. Bottom contact remains correct, not globally safe.
+ const r=p.evaluate(defaults,{...payload,type:'NOT_ACCEPTED',occupied:1,dimensions:[620,500,850],center:[260,250,0]})
+ assert.equal(r.inspection.contact.status,'satisfied');assert.equal(r.evaluation.bindings[0].checks.eligibility.status,'failed')
+ assert.equal(r.inspection.collision.status,'unverified');assert.equal(r.inspection.safety.status,'unverified')
+ const robot=plan(robotBinding()).evaluate(robotDefaults,{...payload,bindingId:'tool-grip',type:'BOX'})
+ assert.equal(robot.inspection.contact.status,'unverified')
+})
+test('invalid payloads reject and subsequent evaluations recover without model mutation',()=>{
+ const s=forkliftBindings(),snapshot=structuredClone(s),p=plan(s),baseline=p.evaluate(defaults,payload)
+ for(const change of [{dimensions:[0,1,1]},{center:[NaN,0,0]},{yawDeg:Infinity},{dimensions:[1e7,1,1]},{extra:1}])assert.throws(()=>p.evaluate(defaults,{...payload,...change}))
+ assert.deepEqual(p.evaluate(defaults,payload),baseline);assert.deepEqual(s,snapshot)
+})

package/docs/prototypes/v3-repeated-binding.mjs

@@ -0,0 +1,13 @@
+import {fullModel} from './v3-full-conveyor.mjs'
+export function repeatedBinding(){
+ const model=fullModel()
+ model.inputs.push({id:'selectedIndex',unit:'count',min:0,max:100,role:'design'})
+ model.nodes.push(
+  {id:'selectedRoller',op:'select-item@1',args:['rollers','selectedIndex'],outputs:{placed:'selectedRoller'},params:{member:'rollerPlaced'}},
+  {id:'rollerEnd',op:'feature@1',args:['rollerShape'],outputs:{pose:'rollerEnd'},params:{frame:'rollerEndFrame',name:'end'}}
+ )
+ const target={placement:'selectedRoller',feature:'rollerEnd'}
+ // Illustrative binding for reference testing, not an asserted industrial roller use case.
+ const declaration={version:'r3-capability-3',assetFrame:'world',bindings:[{id:'selected-end',label:'선택한 롤러 끝면',role:'grip',frame:'rollerEndFrame',pose:target,contacts:[{...target}],accepts:['TEST_FIXTURE'],capacity:1}]}
+ return {model,declaration}
+}