@hatiolab/figure-model 0.6.7 → 0.7.1

package/docs/prototypes/kernel.mjs

@@ -1,147 +0,0 @@
-// Experimental executable contract. No product imports and no model-name branches.
-// Scalars are numeric in documented fixture units, NOT statically unit checked yet.
-export class DesignError extends Error {
-  constructor(code, path, detail) { super(`${code}: ${path}: ${detail}`); this.code=code; this.path=path }
-}
-const fail=(code,path,detail)=>{throw new DesignError(code,path,detail)}
-const finite=(x,path)=>{if(!Number.isFinite(x))fail('NON_FINITE',path,String(x));return x}
-const add=(a,b)=>a.map((v,i)=>v+b[i])
-const sub=(a,b)=>a.map((v,i)=>v-b[i])
-const dot=(a,b)=>a.reduce((s,v,i)=>s+v*b[i],0)
-const I=()=>[[1,0,0],[0,1,0],[0,0,1]]
-const mv=(r,v)=>r.map(row=>dot(row,v))
-const mm=(a,b)=>a.map(row=>[0,1,2].map(i=>dot(row,b.map(r=>r[i]))))
-export const point=(f,p)=>add(mv(f.rotation,p),f.position)
-function rot(axis,degrees,path) {
-  const norm=Math.hypot(...axis)
-  if(Math.abs(norm-1)>1e-10)fail('AXIS',path,'unit axis required')
-  const [x,y,z]=axis,c=Math.cos(degrees*Math.PI/180),s=Math.sin(degrees*Math.PI/180),k=1-c
-  return [[c+x*x*k,x*y*k-z*s,x*z*k+y*s],[y*x*k+z*s,c+y*y*k,y*z*k-x*s],[z*x*k-y*s,z*y*k+x*s,c+z*z*k]]
-}
-
-export function resolve(model,inputs) {
-  const values={},active=new Set(),defs=model.values??{},spec=model.inputs??{}
-  for(const k of Object.keys(inputs))if(!Object.hasOwn(spec,k))fail('UNKNOWN_INPUT',k,'not declared')
-  for(const [k,s] of Object.entries(spec)) {
-    if(Object.hasOwn(defs,k))fail('DUPLICATE_WRITER',k,'input and derived')
-    const x=finite(inputs[k],k)
-    if(x<s.min||x>s.max)fail('INPUT_RANGE',k,`${x} outside [${s.min},${s.max}]`)
-    values[k]=x
-  }
-  function expression(e,path='expression') {
-    if(typeof e==='number')return finite(e,path)
-    if(typeof e==='string')return value(e)
-    if(!e||!Array.isArray(e.args))fail('EXPRESSION',path,'expected number, reference or operator')
-    const a=e.args.map(x=>expression(x,path))
-    if(e.op==='add')return finite(a.reduce((s,x)=>s+x,0),path)
-    if(e.op==='mul'&&a.length===2)return finite(a[0]*a[1],path)
-    fail('EXPRESSION',path,'unsupported operator/arity')
-  }
-  function value(k) {
-    if(Object.hasOwn(values,k))return values[k]
-    if(!Object.hasOwn(defs,k))fail('UNKNOWN_REFERENCE',k,'no definition')
-    if(active.has(k))fail('VALUE_CYCLE',k,[...active,k].join(' -> '))
-    active.add(k);values[k]=expression(defs[k],k);active.delete(k);return values[k]
-  }
-  for(const k of Object.keys(defs))value(k)
-  for(const c of model.assertions??[]) {
-    const left=expression(c.left,c.id),right=expression(c.right,c.id)
-    if(c.op!=='gte')fail('ASSERTION_OPERATOR',c.id,c.op)
-    if(left<right)fail('ASSERTION',c.id,`${left} < ${right}; deficit=${right-left}`)
-  }
-  const frames={},visiting=new Set(),nodes={...model.frames},geometry={...model.geometry},shapeCache={}
-  function vector(v,path) {
-    if(!Array.isArray(v)||v.length!==3)fail('VECTOR',path,'three coordinates required')
-    return v.map(e=>expression(e,path))
-  }
-  function repeatPlan(r,id) {
-    const pitch=expression(r.pitch,id),axis=vector(r.axis,id)
-    if(!(pitch>0)||Math.abs(Math.hypot(...axis)-1)>1e-10)fail('REPEAT_DOMAIN',id,'positive pitch and unit axis')
-    const count=r.mode==='fixed'?expression(r.count,id):r.mode==='pitch'?Math.floor(expression(r.span,id)/pitch):NaN
-    if(!Number.isInteger(count)||count<1||!Number.isInteger(r.limit)||count>r.limit)fail('REPEAT_DOMAIN',id,`count=${count}, limit=${r.limit}`)
-    return {count,pitch,axis}
-  }
-  // Lower one-level repeated assemblies into the SAME frame/geometry evaluator.
-  // No index-dependent scripting, cross-instance references or nested patterns yet.
-  for(const [name,p] of Object.entries(model.patterns??{})) {
-    const {count,pitch,axis}=repeatPlan(p.repeat,name)
-    const localFrames=p.frames??{},localShapes=p.geometry??{}
-    for(let i=0;i<count;i++) {
-      const prefix=kind=>id=>JSON.stringify(['pattern',name,i,kind,id])
-      const fid=prefix('frame'),gid=prefix('geometry'),root=fid('$root')
-      const insert=(target,id,value)=>{if(Object.hasOwn(target,id))fail('DUPLICATE_ID',id,'expanded pattern');target[id]=value}
-      if(Object.hasOwn(localFrames,'$root'))fail('RESERVED_ID',name,'$root')
-      insert(nodes,root,{parent:p.parent,position:axis.map(x=>x*i*pitch)})
-      for(const [id,n] of Object.entries(localFrames)) {
-        if(n.feature&&n.parent)fail('DUPLICATE_PARENT',id,'feature and parent')
-        if(n.parent&&!Object.hasOwn(localFrames,n.parent))fail('PATTERN_REFERENCE',name,n.parent)
-        if(n.feature&&!Object.hasOwn(localShapes,n.feature.geometry))fail('PATTERN_REFERENCE',name,n.feature.geometry)
-        insert(nodes,fid(id),{...n,parent:n.feature?undefined:n.parent?fid(n.parent):root,
-          ...(n.feature?{feature:{...n.feature,geometry:gid(n.feature.geometry)}}:{})})
-      }
-      for(const [id,g] of Object.entries(localShapes)) {
-        if(!Object.hasOwn(localFrames,g.frame))fail('PATTERN_REFERENCE',name,g.frame)
-        if(g.repeat)fail('NESTED_REPEAT',name,id)
-        insert(geometry,gid(id),{...g,frame:fid(g.frame)})
-      }
-    }
-  }
-  function shape(id) {
-    if(Object.hasOwn(shapeCache,id))return shapeCache[id]
-    if(!Object.hasOwn(geometry,id))fail('UNKNOWN_GEOMETRY',id,'no definition')
-    const g=geometry[id],dimensions=Object.fromEntries(Object.entries(g.dimensions).map(([k,v])=>[k,expression(v,id)]))
-    const required=g.kind==='box'?['width','height','depth']:g.kind==='cylinder'?['radius','length']:null
-    if(!required||Object.keys(dimensions).length!==required.length||required.some(k=>!(dimensions[k]>0)))fail('GEOMETRY_DOMAIN',id,'positive provider dimensions required')
-    return shapeCache[id]={g,dimensions,orientation:g.orientation?rot(vector(g.orientation.axis,id),expression(g.orientation.angle,id),id):I()}
-  }
-  function featureFrame(feature,id) {
-    const {g,dimensions:d,orientation}=shape(feature.geometry)
-    if(g.repeat)fail('AMBIGUOUS_FEATURE',id,'use a pattern instance, not a repeated primitive')
-    const owner=frame(g.frame),shapeFrame={position:owner.position,rotation:mm(owner.rotation,orientation)}
-    // Named points retain provider axes. These are NOT normal-oriented attachment frames.
-    const points=g.kind==='box'?{'x-':[-d.width/2,0,0],'x+':[d.width/2,0,0],'y-':[0,-d.height/2,0],'y+':[0,d.height/2,0],'z-':[0,0,-d.depth/2],'z+':[0,0,d.depth/2]}:
-      {'start':[0,-d.length/2,0],'end':[0,d.length/2,0]}
-    if(!Object.hasOwn(points,feature.point))fail('UNKNOWN_FEATURE',id,feature.point)
-    return {position:point(shapeFrame,points[feature.point]),rotation:shapeFrame.rotation}
-  }
-  function frame(id) {
-    if(Object.hasOwn(frames,id))return frames[id]
-    const node=nodes[id]
-    if(!Object.hasOwn(nodes,id))fail('UNKNOWN_FRAME',id,'no definition')
-    if(visiting.has(id))fail('FRAME_CYCLE',id,[...visiting,id].join(' -> '))
-    visiting.add(id)
-    if(node.feature&&node.parent)fail('DUPLICATE_PARENT',id,'feature and parent')
-    const parent=node.feature?featureFrame(node.feature,id):node.parent?frame(node.parent):{position:[0,0,0],rotation:I()}
-    const offset=vector(node.position??[0,0,0],id)
-    const rest=node.orientation?rot(vector(node.orientation.axis,id),expression(node.orientation.angle),id):I()
-    let localOffset=offset,localRotation=rest
-    if(node.joint) {
-      const j=node.joint,axis=vector(j.axis,id),q=expression(j.value,id)
-      if(Math.abs(Math.hypot(...axis)-1)>1e-10)fail('AXIS',id,'unit axis required')
-      if(j.type==='slide')localOffset=add(offset,mv(rest,axis.map(x=>x*q)))
-      else if(j.type==='hinge') {
-        const pivot=vector(j.pivot??[0,0,0],id),r=rot(axis,q,id)
-        localOffset=add(offset,mv(rest,sub(pivot,mv(r,pivot))));localRotation=mm(rest,r)
-      } else fail('JOINT',id,j.type)
-    }
-    frames[id]={position:point(parent,localOffset),rotation:mm(parent.rotation,localRotation)}
-    if(![...frames[id].position,...frames[id].rotation.flat()].every(Number.isFinite))fail('NON_FINITE',id,'frame')
-    visiting.delete(id);return frames[id]
-  }
-  for(const id of Object.keys(nodes))frame(id)
-  const instances=[]
-  for(const [id,g] of Object.entries(geometry)) {
-    const owner=frame(g.frame),{dimensions,orientation}=shape(id)
-    let count=1,pitch=0,axis=[1,0,0]
-    if(g.repeat) {
-      ;({count,pitch,axis}=repeatPlan(g.repeat,id))
-    }
-    // Shape-local orientation follows placement. It does not rotate the repetition row.
-    for(let i=0;i<count;i++) {
-      // Start-anchored identity policy for this experiment. Not approved migration semantics.
-      instances.push({id:JSON.stringify([id,i]),source:id,index:i,kind:g.kind,dimensions:{...dimensions},
-        frame:{rotation:mm(owner.rotation,orientation),position:point(owner,axis.map(x=>x*i*pitch))}})
-    }
-  }
-  return {values,frames,instances}
-}

package/docs/prototypes/kernel.test.mjs

@@ -1,144 +0,0 @@
-import fs from 'node:fs'
-import assert from 'node:assert/strict'
-import {test} from 'node:test'
-import {resolve,point,DesignError} from './kernel.mjs'
-
-const seeds=JSON.parse(fs.readFileSync(new URL('../../../operato-application/packages/operato-figure/server/seed/figure-samples.json',import.meta.url)))
-const robot=JSON.parse(fs.readFileSync(new URL('../../src/fixtures/robot-arm-6dof.json',import.meta.url)))
-const source=t=>seeds.find(s=>s.type===t).source
-const part=(s,n)=>s.parts.find(p=>p.name===n)
-const add=(...args)=>({op:'add',args}),mul=(a,b)=>({op:'mul',args:[a,b]})
-const range=(min,max)=>({min,max})
-const near=(a,b)=>assert.ok(Number.isFinite(a)&&Math.abs(a-b)<1e-7,`${a} != ${b}`)
-const xyz=v=>[v.x,v.y,v.z]
-const equal=(a,b)=>a.forEach((v,i)=>near(v,b[i]))
-const diff=(a,b)=>a.map((x,i)=>x-b[i])
-
-// Authored fixture adapters only. They are not general-purpose v2 migration.
-function conveyor() {
-  const s=source('CONVEYOR'),p=part(s,'roller'),pitch=p.repeat.pitch,r=p.transform.size.x/2
-  return {inputs:{width:range(100,16000),depth:range(81,1800),angle:range(-360,360)},
-    values:{length:add('depth',-80)},assertions:[],
-    frames:{row:{position:[add(mul(-.5,'width'),pitch/2),p.transform.position.y,0],orientation:{axis:[1,0,0],angle:90},joint:{type:'hinge',axis:[0,1,0],value:'angle'}}},
-    geometry:{roller:{frame:'row',kind:'cylinder',dimensions:{radius:r,length:'length'},repeat:{mode:'pitch',span:'width',pitch,axis:[1,0,0],limit:100}}}}
-}
-// Repetition is a placement operation, not movement around the roller's own axis.
-// Give each roller a spinning feature via separate evaluation in the test below.
-// The candidate above deliberately exposes whether joint order corrupts row placement.
-function cradle() {
-  const s=source('ROLL_CRADLE'),roll=part(s,'roll'),core=part(s,'core')
-  return {inputs:{radial:range(.5,2),axial:range(.5,2),fed:range(0,100)},
-    values:{fraction:add(1,mul(-.0068,'fed')),radius:mul(mul(roll.transform.size.x/2,'radial'),'fraction'),coreRadius:mul(core.transform.size.x/2,'radial')},
-    assertions:[{id:'roll-outside-core',op:'gte',left:'radius',right:'coreRadius'}],
-    frames:{axis:{position:xyz(roll.transform.position),orientation:{axis:[0,0,1],angle:90}}},
-    geometry:{roll:{frame:'axis',kind:'cylinder',dimensions:{radius:'radius',length:mul(roll.transform.size.y,'axial')}},core:{frame:'axis',kind:'cylinder',dimensions:{radius:'coreRadius',length:mul(core.transform.size.y,'axial')}}}}
-}
-function robotModel() {
-  const model={inputs:{linkScale:range(.5,2)},values:{},frames:{},geometry:{}}
-  for(const j of robot.joints)model.inputs[j.name]=range(j.limits?.min??-360,j.limits?.max??360)
-  for(const p of robot.parts) {
-    const parent=p.parent?xyz(part(robot,p.parent).transform.position):[0,0,0]
-    const relative=diff(xyz(p.transform.position),parent),j=robot.joints.find(j=>j.child===p.name)
-    model.frames[p.name]={parent:p.parent,position:relative.map((v,i)=>i===1?mul(v,'linkScale'):v)}
-    if(j)model.frames[p.name].joint={type:'hinge',axis:xyz(j.axis),value:j.name,
-      pivot:diff(xyz(j.origin),xyz(p.transform.position)).map((v,i)=>i===1?mul(v,'linkScale'):v)}
-    const size=p.transform.size
-    model.geometry[p.name]={frame:p.name,kind:p.primitive==='cylinder'?'cylinder':'box',dimensions:p.primitive==='cylinder'?
-      {radius:size.x/2,length:mul(size.y,'linkScale')}:{width:size.x,height:mul(size.y,'linkScale'),depth:size.z}}
-  }
-  return model
-}
-function forklift() {
-  const s=source('FORKLIFT'),m={inputs:{heightScale:range(.5,2),lift:range(0,2000),reach:range(0,400)},values:{},frames:{},geometry:{}}
-  // Motion-only frames at rest origin; all descendants retain original source rest coordinates.
-  m.frames.reach={joint:{type:'slide',axis:[0,0,1],value:'reach'}}
-  m.frames.stage={parent:'reach',joint:{type:'slide',axis:[0,1,0],value:mul(.5,'lift')}}
-  m.frames.carriageMotion={parent:'stage',joint:{type:'slide',axis:[0,1,0],value:mul(.5,'lift')}}
-  for(const p of s.parts) {
-    const parent=p.name.startsWith('mast-')?'reach':p.name.startsWith('stage-')?'stage':(p.name==='carriage'||p.name.startsWith('fork-'))?'carriageMotion':undefined
-    m.frames[p.name]={parent,position:xyz(p.transform.position).map((v,i)=>i===1?mul(v,'heightScale'):v)}
-    if(p.transform.rotation)m.frames[p.name].orientation={axis:[0,0,1],angle:p.transform.rotation.z}
-    const d=p.transform.size
-    m.geometry[p.name]={frame:p.name,kind:p.primitive==='cylinder'?'cylinder':'box',dimensions:p.primitive==='cylinder'?{radius:d.x/2,length:d.y}:{width:d.x,height:mul(d.y,'heightScale'),depth:d.z}}
-  }
-  return m
-}
-
-test('robot: common kernel, 3 link scales × 32 poses; shared pivots and rest geometry',()=>{
-  const model=robotModel();let checks=0
-  for(const scale of [.5,1,2])for(let n=0;n<32;n++) {
-    const inputs={linkScale:scale,...Object.fromEntries(robot.joints.map((j,i)=>[j.name,n===0?0:(j.limits?.min??-360)+(n*(i+1)%31)/30*((j.limits?.max??360)-(j.limits?.min??-360))]))}
-    const out=resolve(model,inputs)
-    assert.equal(out.instances.length,10)
-    for(const j of robot.joints) {
-      const p=part(robot,j.child),parent=part(robot,p.parent)
-      const childPivot=diff(xyz(j.origin),xyz(p.transform.position)).map((v,i)=>i===1?v*scale:v)
-      const parentPivot=diff(xyz(j.origin),xyz(parent.transform.position)).map((v,i)=>i===1?v*scale:v)
-      equal(point(out.frames[p.name],childPivot),point(out.frames[parent.name],parentPivot));checks++
-    }
-    if(n===0)for(const p of robot.parts)equal(out.frames[p.name].position,xyz(p.transform.position).map((v,i)=>i===1?v*scale:v))
-  }
-  console.log({robotStates:96,pivotChecks:checks})
-})
-
-test('cradle: common kernel, 3 radial × 3 axial × 5 feed states',()=>{
-  const model=cradle()
-  for(const radial of [.5,1,2])for(const axial of [.5,1,2])for(const fed of [0,25,50,75,100]) {
-    const out=resolve(model,{radial,axial,fed}),[roll,core]=out.instances
-    near(roll.dimensions.radius,350*radial*(1-.0068*fed));near(roll.dimensions.length,1000*axial)
-    assert.ok(roll.dimensions.radius>=core.dimensions.radius)
-    equal(roll.frame.position,core.frame.position)
-  }
-})
-
-test('forklift: common kernel, 3 sizes × 3 lifts × 3 reaches, no double inheritance',()=>{
-  const model=forklift()
-  for(const heightScale of [.5,1,2])for(const lift of [0,1000,2000])for(const reach of [0,200,400]) {
-    const {frames:f,instances}=resolve(model,{heightScale,lift,reach})
-    assert.equal(instances.length,20)
-    equal(f.carriage.position,[0,260*heightScale+lift,338+reach])
-    near(f['stage-left'].position[1],940*heightScale+lift/2)
-    near(f['fork-high-left'].position[1]-f['fork-low-left'].position[1],400*heightScale)
-    near(f.body.position[2],-700)
-  }
-})
-
-test('conveyor: spin must not rotate repeat offsets; prototype rejects naive composition via oracle',()=>{
-  const m=conveyor(),a=resolve(m,{width:2400,depth:600,angle:0}),b=resolve(m,{width:2400,depth:600,angle:90})
-  // Counterexample: placing repetition after owner joint makes the entire row orbit.
-  assert.ok(Math.hypot(...diff(a.instances[1].frame.position,b.instances[1].frame.position))>100)
-})
-
-test('conveyor: corrected placement-before-local-orientation, 5 widths × 3 depths × 3 spins',()=>{
-  const m=conveyor()
-  delete m.frames.row.joint
-  m.geometry.roller.orientation={axis:[0,1,0],angle:'angle'}
-  for(const width of [1200,2399.99,2400,2400.01,4800])for(const depth of [300,600,1200])for(const angle of [0,90,180]) {
-    const out=resolve(m,{width,depth,angle})
-    assert.equal(out.instances.length,Math.floor(width/150))
-    for(const [i,p] of out.instances.entries()) {
-      equal(p.frame.position,[-width/2+75+i*150,500,0])
-      near(p.dimensions.radius,48);near(p.dimensions.length,depth-80)
-      assert.ok(p.frame.position[0]-48>=-width/2&&p.frame.position[0]+48<=width/2)
-      equal(point(p.frame,[0,p.dimensions.length/2,0]),[p.frame.position[0],500,p.dimensions.length/2])
-    }
-  }
-  const a=resolve(m,{width:2399.99,depth:600,angle:0}),b=resolve(m,{width:2400,depth:600,angle:0})
-  assert.deepEqual(a.instances.map(x=>x.id),b.instances.slice(0,15).map(x=>x.id))
-})
-
-test('rejection is explicit and does not mutate source; order independent',()=>{
-  const m=cradle(),before=JSON.stringify(m),input={radial:1,axial:1,fed:50}
-  const result=resolve(m,input),reversed={...m,values:Object.fromEntries(Object.entries(m.values).reverse()),frames:Object.fromEntries(Object.entries(m.frames).reverse())}
-  assert.deepEqual(resolve(reversed,input).instances,result.instances)
-  for(const [model,args,code] of [
-    [m,{...input,fed:101},'INPUT_RANGE'],
-    [{...m,values:{...m.values,radius:'missing'}},input,'UNKNOWN_REFERENCE'],
-    [{...m,values:{...m.values,radius:'radius'}},input,'VALUE_CYCLE'],
-    [{...m,frames:{axis:{parent:'axis'}}},input,'FRAME_CYCLE'],
-    [{...m,values:{...m.values,radius:0}},input,'ASSERTION'],
-    [conveyor(),{width:16000,depth:600,angle:0},'REPEAT_DOMAIN'],
-    [m,{...input,radial:NaN},'NON_FINITE']
-  ])assert.throws(()=>resolve(model,args),e=>e instanceof DesignError&&e.code===code)
-  assert.equal(JSON.stringify(m),before)
-})

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

@@ -1,182 +0,0 @@
-// Design probes, not a 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 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/payload-collision.mjs

@@ -1,54 +0,0 @@
-import {compilePayloadInspection} from './payload-fit.mjs'
-import {ContractError} from './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/payload-collision.test.mjs

@@ -1,68 +0,0 @@
-import {test} from 'node:test'
-import assert from 'node:assert/strict'
-import {boxRelation,compileCollisionInspection} from './payload-collision.mjs'
-import {forkliftBindings} from './capability-samples.mjs'
-import {defaults} from './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})
-})