@hatiolab/figure-model 0.1.30 → 0.1.31

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

@@ -0,0 +1,46 @@
+import {test} from 'node:test'
+import assert from 'node:assert/strict'
+import {repeatedBinding} from './v3-repeated-binding.mjs'
+import {compileCapabilities} from './v3-capability-plan.mjs'
+import {compileDocument,parseDocument,serializeDocument} from './v3-document.mjs'
+import {defaults} from './v3-full-conveyor.mjs'
+import Ajv from '../../../things-factory/node_modules/ajv/lib/ajv.js'
+import fs from 'node:fs'
+const near=(a,b)=>assert.ok(Math.abs(a-b)<1e-7)
+const args={...defaults,selectedIndex:13}
+test('whole conveyor: selected occurrence follows dimensions and motion without another mesh',()=>{
+ const s=repeatedBinding(),p=compileCapabilities(s.model,s.declaration);let states=0
+ for(const length of [2400,2550,4800])for(const width of [400,600,1200])for(const angle of [-90,0,37,90]){
+  const r=p.evaluate({...args,length,width,angle}),b=r.bindings[0],item=r.geometry.find(g=>g.id===b.targetGeometryId)
+  assert.equal(item.index,13);assert.equal(item.key,'rollerPlaced');assert.equal(b.contacts[0].geometryId,item.id)
+  assert.equal(r.geometry.length,16+1+Math.floor((length-386)/150))
+  near(b.pose.t[0],item.pose.t[0]);near(b.pose.t[1],500);near(b.pose.t[2],(width-80)/2)
+  b.contacts[0].normal.forEach((v,i)=>near(v,[0,0,1][i]));states++
+ }
+ console.log({repeatedBindingStates:states})
+})
+test('shrink deletes selected occurrence: fail atomically, no nearest fallback, regrow restores id',()=>{
+ const s=repeatedBinding(),p=compileCapabilities(s.model,s.declaration),before=p.evaluate(args)
+ assert.throws(()=>p.evaluate({...args,length:2335.999}),e=>e.code==='TARGET_ABSENT')
+ const boundary=p.evaluate({...args,length:2336});assert.equal(boundary.bindings[0].targetGeometryId,before.bindings[0].targetGeometryId)
+ assert.deepEqual(p.evaluate(args),before)
+ const changed=p.evaluate({...args,selectedIndex:0});assert.notEqual(changed.bindings[0].targetGeometryId,before.bindings[0].targetGeometryId)
+ assert.throws(()=>p.evaluate({...args,selectedIndex:100}),e=>e.code==='TARGET_ABSENT')
+})
+test('reference origin rejects foreign feature/member, animated index, wrong binding frame',()=>{
+ for(const [code,edit] of [
+  ['SURFACE_OWNER',s=>s.model.nodes.find(n=>n.id==='rollerEnd').args[0]='roller-headShape'],
+  ['SURFACE_PROVENANCE',s=>s.model.nodes.find(n=>n.id==='selectedRoller').params.member='deckPlaced'],
+  ['TARGET_STATE',s=>s.model.inputs.find(i=>i.id==='selectedIndex').role='state'],
+  ['FRAME_TYPE',s=>s.declaration.bindings[0].frame='wrong']
+ ]){const s=repeatedBinding();edit(s);assert.throws(()=>compileCapabilities(s.model,s.declaration),e=>e.code===code)}
+})
+test('schema/serialization/reorder preserve occurrence identity and deletion behavior',()=>{
+ const s=repeatedBinding(),doc={version:'figure-v3-prototype-1',model:s.model,capabilities:s.declaration}
+ const validate=new Ajv().compile(JSON.parse(fs.readFileSync(new URL('./v3-document.schema.json',import.meta.url))))
+ assert.ok(validate(doc),JSON.stringify(validate.errors))
+ const restored=parseDocument(serializeDocument(doc));restored.model.nodes.reverse()
+ const a=compileDocument(doc).evaluate(args),b=compileDocument(restored).evaluate(args)
+ assert.deepEqual(a.bindings,b.bindings);assert.equal(a.geometry.length,b.geometry.length)
+ assert.throws(()=>compileDocument(restored).evaluate({...args,length:900}),e=>e.code==='TARGET_ABSENT')
+})

package/docs/prototypes/v3-runtime-browser.mjs

@@ -0,0 +1,76 @@
+// Run npm run build first. Exercises emitted ESM in Chrome, not a Node polyfill.
+import {readFile} from 'node:fs/promises'
+import assert from 'node:assert/strict'
+import {sampleAsset} from './v3-asset-samples.mjs'
+import {compileV3Graph} from '../../src/v3-graph.ts'
+import {compileV3Asset} from '../../src/v3-asset.ts'
+import {chromium} from '/Users/super/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/node_modules/playwright/index.mjs'
+const url=source=>'data:text/javascript;base64,'+Buffer.from(source).toString('base64')
+const contract=url(await readFile(new URL('../../dist/v3-contract.js',import.meta.url),'utf8'))
+const source=await readFile(new URL('../../dist/v3-json.js',import.meta.url),'utf8')
+assert.ok(source.includes('./v3-contract.js'))
+const entry=url(source.replace('./v3-contract.js',contract))
+const graphSource=await readFile(new URL('../../dist/v3-graph.js',import.meta.url),'utf8')
+const graphEntry=url(graphSource.replace('./v3-contract.js',contract))
+const modules=new Map()
+async function moduleUrl(name){
+ if(modules.has(name))return modules.get(name)
+ assert.match(name,/^v3-[a-z-]+\.js$/)
+ let code=await readFile(new URL('../../dist/'+name,import.meta.url),'utf8')
+ for(const match of [...code.matchAll(/from ['"]\.\/(v3-[a-z-]+\.js)['"]/g)]){
+  code=code.replace(match[0],'from '+JSON.stringify(await moduleUrl(match[1])))
+ }
+ const entry=url(code);modules.set(name,entry);return entry
+}
+const assetEntry=await moduleUrl('v3-asset.js')
+const workspaceEntry=await moduleUrl('v3-editor-workspace.js')
+const createEntry=await moduleUrl('v3-create.js')
+const browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'})
+try{
+ const page=await browser.newPage()
+ const result=await page.evaluate(async entry=>{
+  const module=await import(entry)
+  const value=module.parseV3Json('{"name":"드라이룸 😀"}')
+  let duplicate
+  try{module.parseV3Json('{"a":1,"\\u0061":2}')}catch(e){duplicate=e.code}
+  return {buffer:typeof globalThis.Buffer,process:typeof globalThis.process,value,bytes:module.v3Utf8ByteLength('드라이룸 😀'),duplicate}
+ },entry)
+ assert.deepEqual(result,{buffer:'undefined',process:'undefined',value:{name:'드라이룸 😀'},bytes:17,duplicate:'JSON_DUPLICATE_KEY'})
+ console.log(JSON.stringify(result,null,2))
+ for(const kind of ['dryroom','conveyor','robot','forklift']){
+  const asset=sampleAsset(kind),model=asset.document.model,inputs={...asset.designInputs,...asset.stateDefaults}
+  const expected=compileV3Graph(model).evaluate(inputs)
+  const actual=await page.evaluate(async({entry,model,inputs})=>(await import(entry)).compileV3Graph(model).evaluate(inputs),{entry:graphEntry,model,inputs})
+  // JSON normalizes -0 across the browser transport, not meaningful to the geometry contract.
+  assert.deepEqual(JSON.parse(JSON.stringify(actual)),JSON.parse(JSON.stringify(expected)))
+  console.log(kind+': browser/server values and geometry match; '+actual.geometry.length+' meshes')
+  const restored=await page.evaluate(async({entry,text})=>{const m=await import(entry);return m.compileV3Asset(m.parseV3Asset(text)).evaluate()},{entry:assetEntry,text:JSON.stringify(asset)})
+  assert.deepEqual(JSON.parse(JSON.stringify(restored)),JSON.parse(JSON.stringify(compileV3Asset(asset).evaluate())))
+  console.log(kind+': serialized asset, materials, palette and capability bindings match')
+ }
+ const editing=await page.evaluate(async({entry,forklift,robot})=>{
+  const w=(await import(entry)).createV3EditorWorkspace(),first=w.open(forklift)
+  const edit=(revision,value)=>({context:first.context,origin:'ai',expectedRevision:revision,changes:[{kind:'set-design',input:'forkLength',unit:'mm',value}]})
+  const before=w.read();w.preview(edit(0,1275));const previewUnchanged=JSON.stringify(w.read())===JSON.stringify(before)
+  w.apply(edit(0,1275));const pending=w.export({context:first.context});w.apply(edit(1,1500))
+  let staleSave;try{w.acknowledgeSaved(pending)}catch(e){staleSave=e.code}
+  w.undo({context:first.context,origin:'ui',expectedRevision:2});w.redo({context:first.context,origin:'ui',expectedRevision:3})
+  const revision=w.read().revision,snapshot=w.export({context:first.context});w.acknowledgeSaved(snapshot)
+  const next=w.open(robot);let staleEdit;try{w.apply(edit(0,1000))}catch(e){staleEdit=e.code}
+  w.open(snapshot.text);const restored=w.read().fields.find(f=>f.id==='forkLength').value
+  return {previewUnchanged,staleSave,revision,robotMeshes:next.geometry.length,staleEdit,restored,empty:w.close().geometry.length}
+ },{entry:workspaceEntry,forklift:JSON.stringify(sampleAsset('forklift')),robot:JSON.stringify(sampleAsset('robot'))})
+ assert.deepEqual(editing,{previewUnchanged:true,staleSave:'REVISION_CONFLICT',revision:4,robotMeshes:10,staleEdit:'CONTEXT_CONFLICT',restored:1500,empty:0})
+ console.log(JSON.stringify({browserWorkspace:editing},null,2))
+ const authored=await page.evaluate(async({createEntry,assetEntry,workspaceEntry})=>{
+  const c=await import(createEntry),a=await import(assetEntry),w=(await import(workspaceEntry)).createV3EditorWorkspace()
+  const empty=c.createV3Asset('New V3'),emptyCount=a.compileV3Asset(empty).evaluate().geometry.length
+  const model=c.addV3Box(empty,{id:'gate',size:{x:800,y:2000,z:100},position:{x:0,y:1000,z:0}})
+  const opened=w.open(a.serializeV3Asset(model))
+  w.apply({context:opened.context,origin:'ui',expectedRevision:0,changes:[{kind:'set-design',input:'gate.size.y',unit:'mm',value:1500}]})
+  const saved=w.export({context:opened.context}),restored=a.compileV3Asset(a.parseV3Asset(saved.text)).evaluate()
+  return {emptyCount,parts:restored.geometry.length,height:restored.geometry[0].shape.dimensions.height}
+ },{createEntry,assetEntry,workspaceEntry})
+ assert.deepEqual(authored,{emptyCount:0,parts:1,height:1500})
+ console.log(JSON.stringify({newV3Authoring:authored}))
+}finally{await browser.close()}

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

@@ -0,0 +1,144 @@
+// Read-only design probes against checked-in product samples. NOT a v3 renderer.
+import fs from 'node:fs'
+import { createHash } from 'node:crypto'
+import assert from 'node:assert/strict'
+import { test } from 'node:test'
+import { repeatPlanOfPart } from '../../src/sizing.ts'
+
+const actualSeedURL = new URL('../../../operato-application/packages/operato-figure/server/seed/figure-samples.json', import.meta.url)
+const actualRobotURL = new URL('../../src/fixtures/robot-arm-6dof.json', import.meta.url)
+const samples = JSON.parse(fs.readFileSync(actualSeedURL))
+const robot = JSON.parse(fs.readFileSync(actualRobotURL))
+const source = type => samples.find(s => s.type === type).source
+const part = (s, name) => s.parts.find(p => p.name === name)
+const vec = v => [v.x, v.y, v.z]
+const plus = (a,b) => a.map((x,i) => x+b[i])
+const minus = (a,b) => a.map((x,i) => x-b[i])
+const near = (a,b) => assert.ok(Math.abs(a-b)<1e-8, `${a} != ${b}`)
+const same = (a,b) => a.forEach((x,i) => near(x,b[i]))
+const dot = (a,b) => a.reduce((s,x,i)=>s+x*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]))))
+const apply = (f,p) => plus(mv(f.r,p),f.t)
+const compose = (a,b) => ({r:mm(a.r,b.r),t:apply(a,b.t)})
+function rotation(axis, degrees) {
+  const [x,y,z] = axis, c=Math.cos(degrees*Math.PI/180),s=Math.sin(degrees*Math.PI/180),k=1-c
+  near(dot(axis,axis),1)
+  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]]
+}
+// One affine evaluator used for derived positions; cycles and duplicate writers rejected.
+function evaluate(defs, inputs) {
+  const values={...inputs}, active=new Set()
+  assert.ok(!Object.keys(defs).some(k=>k in inputs))
+  function visit(k) {
+    if(k in values)return values[k]
+    assert.ok(k in defs && !active.has(k), `unknown or cycle: ${k}`)
+    active.add(k)
+    const [constant,terms]=defs[k]
+    values[k]=constant+Object.entries(terms).reduce((s,[ref,c])=>s+c*visit(ref),0)
+    assert.ok(Number.isFinite(values[k]));active.delete(k);return values[k]
+  }
+  Object.keys(defs).forEach(visit);return values
+}
+
+test('record actual input provenance; seed catalogue plus separate robot fixture', () => {
+  console.log(JSON.stringify({sources:[actualSeedURL,actualRobotURL].map(url=>({path:url.pathname,sha256:createHash('sha256').update(fs.readFileSync(url)).digest('hex')})),catalogue:samples.map(s=>({type:s.type,parts:s.source.parts.length})),robotParts:robot.parts.length}))
+  for(const s of [...samples.map(s=>s.source),robot]) {
+    assert.equal(new Set(s.parts.map(p=>p.name)).size,s.parts.length)
+    for(const p of s.parts) if(p.parent)assert.ok(part(s,p.parent))
+  }
+})
+
+test('robot: relative rest frames reproduce source; all six pivots remain shared under combined poses', () => {
+  const states=[Object.fromEntries(robot.joints.map(j=>[j.name,0]))]
+  for(let n=0;n<31;n++) states.push(Object.fromEntries(robot.joints.map((j,i)=>[j.name,(j.limits?.min??-360)+((n*(i+1)%31)/30)*((j.limits?.max??360)-(j.limits?.min??-360))])))
+  let checks=0
+  for(const q of states) {
+    const frames={}
+    for(const p of robot.parts) {
+      const parent=p.parent?frames[p.parent]:{r:I,t:[0,0,0]}
+      const parentRest=p.parent?vec(part(robot,p.parent).transform.position):[0,0,0]
+      const offset=minus(vec(p.transform.position),parentRest)
+      const rest=compose(parent,{r:I,t:offset})
+      const j=robot.joints.find(j=>j.child===p.name)
+      let motion={r:I,t:[0,0,0]}
+      if(j) {
+        const pivot=minus(vec(j.origin),vec(p.transform.position))
+        const r=rotation(vec(j.axis),q[j.name])
+        motion={r,t:minus(pivot,mv(r,pivot))}
+        const child=compose(rest,motion)
+        same(apply(child,pivot),apply(parent,minus(vec(j.origin),parentRest)))
+        checks++
+      }
+      frames[p.name]=compose(rest,motion)
+      near(dot(frames[p.name].r[0],frames[p.name].r[0]),1)
+      if(q===states[0])same(frames[p.name].t,vec(p.transform.position))
+    }
+    // The gripper and external attachment seat keep their relative rigid distances.
+    const a=frames['finger-left'].t,b=frames['finger-right'].t
+    near(Math.hypot(...minus(a,b)),70)
+  }
+  console.log(JSON.stringify({robot:{poses:states.length,pivotChecks:checks,notTested:['resizing link lengths','self collision','inverse kinematics','renderer parity','gripper motion']}}))
+})
+
+test('conveyor: actual repeat rule requires changing topology, outside an affine-only DAG', () => {
+  const s=source('CONVEYOR'),roller=part(s,'roller')
+  const rows=[]
+  for(const width of [1200,2399.99,2400,2400.01,4800]) {
+    const plan=repeatPlanOfPart(roller,{x:width/s.base.x,y:1,z:1},s.base)
+    assert.equal(plan.count,Math.floor(width/roller.repeat.pitch))
+    const d=evaluate({length:[-80,{depth:1}],radius:[roller.transform.size.x/2,{}]}, {depth:600})
+    near(d.length,roller.transform.size.y);near(d.radius,48)
+    rows.push({width,count:plan.count})
+  }
+  assert.notEqual(rows[1].count,rows[2].count)
+  console.log(JSON.stringify({conveyor:rows,designGap:'stable repeated-instance IDs, disappearance/binding policy and explicit end clearance are not specified by r2'}))
+})
+
+test('forklift: simultaneous lift/reach channels reduce to shared affine state without double motion', () => {
+  const s=source('FORKLIFT'),defs={}
+  for(const p of s.parts) for(const axis of ['x','y','z']) {
+    const terms={}
+    for(const param of s.parameters) {
+      const ch=param.clip.channels.find(c=>c.target===p.name&&c.path==='translation')
+      if(!ch)continue
+      assert.equal(ch.keys.length,2);assert.equal(ch.keys[0].at,0);assert.equal(ch.keys[1].at,1)
+      assert.equal(ch.keys[0].value[axis],0);assert.equal(param.range.min,0)
+      terms[param.name]=ch.keys[1].value[axis]/param.range.max
+    }
+    defs[`${p.name}.${axis}`]=[p.transform.position[axis],terms]
+  }
+  for(const lift of [0,1000,2000])for(const reach of [0,200,400]) {
+    const v=evaluate(defs,{lift,reach})
+    near(v['carriage.y'],260+lift);near(v['carriage.z'],338+reach)
+    near(v['stage-left.y'],940+lift/2)
+    near(v['fork-high-left.y']-v['fork-low-left.y'],400)
+    near(v['fork-low-left.y']-v['carriage.y'],42-260)
+    near(v['fork-low-left.z']-v['carriage.z'],785-338)
+    near(v['body.z'],-700)
+  }
+  console.log(JSON.stringify({forklift:{combinedStates:9,designGap:'hierarchical migration must subtract inherited motion; copying both parent and child channels doubles travel'}}))
+})
+
+test('dryroom: actual U profile protrudes below floor; trim profile, not scale bounding box', () => {
+  const s=source('DRY_ROOM'),rows=[]
+  for(const name of ['portal-in','portal-out']) {
+    const p=part(s,name),y=p.transform.position.y
+    // figure-shape rotates extrusion +90 X; part -90 X cancels it.
+    assert.equal(p.transform.rotation.x,-90)
+    const original=p.shape.path.map(v=>({...v}))
+    const low=Math.min(...original.map(v=>v.y+y)),high=Math.max(...original.map(v=>v.y+y))
+    near(low,-60);near(high,2900)
+    // Only this known orthogonal U profile: moving its four lowest vertices is safe.
+    // NOT a general polygon clipping algorithm or an automatic migration.
+    const clipped=original.map(v=>({...v,y:Math.max(v.y,-y)}))
+    near(Math.min(...clipped.map(v=>v.y+y)),0)
+    near(Math.max(...clipped.map(v=>v.y+y)),high)
+    near(clipped[2].y+y,2200);near(clipped[3].x-clipped[2].x,1400)
+    assert.equal(clipped.filter((v,i)=>v.y!==original[i].y).length,4)
+    assert.deepEqual(p.shape.path,original)
+    rows.push({name,originalBottomMm:low,proposedBottomMm:0,topUnchangedMm:high,openingTopMm:2200})
+  }
+  console.log(JSON.stringify({dryroom:rows,designGap:'real profile feature coordinates are required; transform.size alone cannot express trimming'}))
+})

package/docs/prototypes/v3-semantics.test.mjs

@@ -0,0 +1,55 @@
+// Independent mathematical oracles for r3, NOT tests of the prototype kernel.
+import assert from 'node:assert/strict'
+import {test} from 'node:test'
+const near=(a,b)=>assert.ok(Number.isFinite(a)&&Math.abs(a-b)<1e-8,`${a} != ${b}`)
+const mv=(r,p)=>r.map(row=>row.reduce((sum,x,i)=>sum+x*p[i],0))
+const plus=(a,b)=>a.map((v,i)=>v+b[i])
+const transpose=r=>r.map((_,i)=>r.map(row=>row[i]))
+const compose=(a,b)=>({r:a.r.map(row=>transpose(b.r).map(col=>row.reduce((s,x,i)=>s+x*col[i],0))),t:plus(mv(a.r,b.t),a.t)})
+const inverse=a=>{const r=transpose(a.r);return {r,t:mv(r,a.t.map(v=>-v))}}
+const transform=(angle,t)=>({r:[[Math.cos(angle),-Math.sin(angle),0],[Math.sin(angle),Math.cos(angle),0],[0,0,1]],t})
+const same=(a,b)=>{a.r.flat().forEach((x,i)=>near(x,b.r.flat()[i]));a.t.forEach((x,i)=>near(x,b.t[i]))}
+
+test('attachment W=A O J inverse(B): shared full feature pose survives changing self feature',()=>{
+  let cases=0
+  for(const size of [10,100,1000])for(const angle of [-Math.PI,-.4,0,.7,Math.PI])for(const q of [-1,0,1]) {
+    const A=transform(angle,[100,20,-40]),O=transform(.25,[2,3,4]),J=transform(q,[0,q*50,0]),B=transform(-.8,[size/2,0,30])
+    const target=compose(compose(A,O),J),W=compose(target,inverse(B))
+    same(compose(W,B),target)
+    // Forgetting the inverse of the self feature is not an equivalent definition.
+    const wrong=compose(target,B)
+    assert.ok(Math.hypot(...wrong.t.map((v,i)=>v-target.t[i]))>1)
+    cases++
+  }
+  assert.equal(cases,45)
+})
+
+function fill(L,a,b,e,p,alpha) {
+  assert.ok(p>0&&e>0&&a>=0&&b>=0&&alpha>=0&&alpha<=1)
+  const usable=L-a-b,n=usable<e?0:1+Math.floor((usable-e)/p)
+  const occupied=n?e+(n-1)*p:0,slack=usable-occupied
+  return {n,positions:Array.from({length:n},(_,i)=>a+e/2+alpha*slack+i*p)}
+}
+test('repetition includes item extent and margins: 3000 exact-integer-boundary cases',()=>{
+  for(let k=0;k<1000;k++)for(const alpha of [0,.5,1]) {
+    const L=k+1,a=k%17,b=k%13,e=1+k%59,p=1+k%41
+    const result=fill(L,a,b,e,p,alpha),enumerated=[]
+    // Independent constructive oracle: add items from the low end until the next cannot fit.
+    for(let i=0;a+e+i*p<=L-b;i++)enumerated.push(i)
+    assert.equal(result.n,enumerated.length)
+    if(result.n) {
+      assert.ok(result.positions[0]-e/2>=a-1e-9)
+      assert.ok(result.positions.at(-1)+e/2<=L-b+1e-9)
+      assert.ok(e+result.n*p>L-a-b)
+      for(let i=1;i<result.n;i++)near(result.positions[i]-result.positions[i-1],p)
+    }
+  }
+})
+test('old floor(L/pitch) disagrees with valid packing in both directions',()=>{
+  assert.equal(fill(100,0,0,10,60,0).n,2)
+  assert.equal(Math.floor(100/60),1)
+  assert.equal(fill(100,20,20,50,40,0).n,1)
+  assert.equal(Math.floor(100/40),2)
+  assert.equal(fill(100,0,0,100,150,0).n,1)
+  assert.equal(fill(99,0,0,100,150,0).n,0)
+})

package/docs/prototypes/v3-spatial-plan.test.mjs

@@ -0,0 +1,102 @@
+import {test} from 'node:test'
+import assert from 'node:assert/strict'
+import {compile,ContractError} from './v3-typed-plan.mjs'
+const near=(a,b)=>assert.ok(Number.isFinite(a)&&Math.abs(a-b)<1e-8,`${a} != ${b}`)
+const equal=(a,b)=>a.forEach((v,i)=>near(v,b[i]))
+const c=(id,value,unit='mm')=>({id,value,unit})
+const n=(id,op,args,outputs,params)=>({id,op,args,outputs,...(params?{params}:{})})
+const rigid=(id,from,to,translation=['zero','zero','zero'],rotation=['angle0','angle0','angle0'])=>n(id,'rigid@1',[...translation,...rotation],{pose:id},{from,to})
+function base(){return {version:'r3-spatial-1',inputs:[],constants:[c('zero',0),c('angle0',0,'rad')],nodes:[]}}
+function wheel(){
+  const m=base();m.inputs=[{id:'radius',unit:'mm',min:10,max:1000},{id:'floorY',unit:'mm',min:-100,max:100},{id:'heading',unit:'deg',min:-180,max:180}]
+  m.constants.push(c('axle',84),c('tilt',-90,'deg'))
+  m.nodes.push(n('wheel','cylinder-shape@1',['radius','axle'],{shape:'shape'},{frame:'wheelLocal'}),
+    n('bottom','feature@1',['shape'],{pose:'self'},{frame:'touch',name:'radialBottom'}),
+    rigid('floor','floorFrame','world',['zero','floorY','zero'],['angle0','heading','angle0']),
+    rigid('mating','touch','floorFrame',['zero','zero','zero'],['tilt','angle0','angle0']),
+    n('attachment','attach@1',['floor','mating','self'],{pose:'pose'}),
+    n('place','place@1',['shape','pose'],{placed:'placed'}),
+    n('witness','compose@1',['pose','self'],{pose:'contactWorld'}))
+  return m
+}
+test('AGV wheel intent: changed radius, floor height and heading preserve contact (125 cases)',()=>{
+  const plan=compile(wheel())
+  for(const radius of [50,115,162.63455967,250,500])for(const floorY of [-100,-20,0,20,100])for(const heading of [-180,-45,0,60,180]){
+    const r=plan.evaluate({radius,floorY,heading})
+    equal(r.values.contactWorld.t,[0,floorY,0]);near(r.values.pose.t[1],floorY+radius)
+    near(r.geometry[0].shape.dimensions.radius,radius)
+  }
+})
+function lamp(){
+  const m=base();m.inputs=[{id:'height',unit:'mm',min:100,max:4000},{id:'rx',unit:'deg',min:-180,max:180},{id:'ry',unit:'deg',min:-180,max:180},{id:'rz',unit:'deg',min:-180,max:180}]
+  m.constants.push(c('width',400),c('depth',100),c('lampSize',40))
+  m.nodes.push(n('support','box-shape@1',['width','height','depth'],{shape:'supportShape'},{frame:'supportLocal'}),
+    n('supportFeature','feature@1',['supportShape'],{pose:'top'},{frame:'supportTop',name:'top'}),
+    rigid('supportPose','supportLocal','world',['zero','zero','zero'],['rx','ry','rz']),
+    n('worldTop','compose@1',['supportPose','top'],{pose:'worldTop'}),
+    n('lamp','box-shape@1',['lampSize','lampSize','lampSize'],{shape:'lampShape'},{frame:'lampLocal'}),
+    n('lampFeature','feature@1',['lampShape'],{pose:'bottom'},{frame:'lampBottom',name:'bottom'}),
+    rigid('offset','lampBottom','supportTop'),
+    n('attachment','attach@1',['worldTop','offset','bottom'],{pose:'lampPose'}),
+    n('lampWitness','compose@1',['lampPose','bottom'],{pose:'lampContact'}),
+    n('placedSupport','place@1',['supportShape','supportPose'],{placed:'supportPlaced'}),
+    n('placedLamp','place@1',['lampShape','lampPose'],{placed:'lampPlaced'}))
+  return m
+}
+test('support/lamp attachment: 4 heights × 27 general 3-axis orientations',()=>{
+  const p=compile(lamp())
+  for(const height of [100,500,1500,3000])for(const rx of [-65,0,80])for(const ry of [-35,0,90])for(const rz of [-40,0,160]){
+    const r=p.evaluate({height,rx,ry,rz}),a=r.values.lampContact,b=r.values.worldTop
+    equal(a.t,b.t);equal(a.r.flat(),b.r.flat());assert.equal(r.geometry.length,2)
+  }
+})
+test('two-link articulation: same compiler resolves dimensions, features and moving attachment',()=>{
+  const m=lamp()
+  // Replace static offset with a hinge at the shared interface; no special robot engine.
+  m.nodes.find(n=>n.id==='offset').args[3]='joint'
+  m.inputs.push({id:'joint',unit:'deg',min:-150,max:150})
+  const p=compile(m)
+  for(const height of [100,1000,3000])for(const joint of [-150,-60,0,60,150]){
+    const r=p.evaluate({height,rx:30,ry:45,rz:70,joint})
+    equal(r.values.lampContact.t,r.values.worldTop.t)
+    near(r.values.lampPose.r[0].reduce((s,x)=>s+x*x,0),1)
+  }
+})
+test('world-point distance may drive another shape length in the same graph',()=>{
+  const m=base();m.constants.push(c('x',30),c('y',40),c('r',5))
+  m.nodes.push(n('a','point@1',['zero','zero','zero'],{point:'a'},{frame:'world'}),
+    n('b','point@1',['x','y','zero'],{point:'b'},{frame:'local'}),rigid('map','local','world'),
+    n('mapped','map-point@1',['map','b'],{point:'worldB'}),n('distance','distance@1',['a','worldB'],{length:'len'}),
+    n('beam','cylinder-shape@1',['r','len'],{shape:'shape'},{frame:'beamLocal'}))
+  near(compile(m).evaluate({}).values.shape.dimensions.length,50)
+  m.nodes.find(n=>n.id==='distance').args[1]='b'
+  assert.throws(()=>compile(m),e=>e.code==='FRAME_TYPE')
+})
+test('wrong transform order, wrong self feature frame and scalar/spatial misuse reject',()=>{
+  for(const mutate of [
+    m=>{m.nodes.find(n=>n.id==='witness').args.reverse()},
+    m=>{m.nodes.find(n=>n.id==='mating').params.from='different'},
+    m=>{m.nodes.push(n('bad','add@1',['pose','pose'],{value:'bad'}))},
+    m=>{m.nodes.find(n=>n.id==='place').args[1]='floor'}
+  ]){
+    const m=wheel();mutate(m);assert.throws(()=>compile(m),e=>e instanceof ContractError&&['FRAME_TYPE','TYPE'].includes(e.code))
+  }
+})
+test('cross geometry/feature/placement cycle is diagnosed as one graph',()=>{
+  const m=wheel()
+  m.nodes.push(n('a','point@1',['zero','zero','zero'],{point:'origin'},{frame:'wheelLocal'}),
+    n('mapped','map-point@1',['pose','origin'],{point:'worldOrigin'}),
+    n('b','point@1',['zero','zero','zero'],{point:'worldZero'},{frame:'world'}),
+    n('distance','distance@1',['worldOrigin','worldZero'],{length:'derivedRadius'}))
+  m.nodes.find(n=>n.id==='wheel').args[0]='derivedRadius'
+  assert.throws(()=>compile(m),e=>e.code==='CYCLE'&&e.message.includes('wheel'))
+})
+test('missing feature and declaration reorder; unsuccessful evaluation leaves no stale geometry',()=>{
+  const m=lamp(),args={height:500,rx:30,ry:70,rz:-20},p=compile(m),r=p.evaluate(args)
+  m.nodes.reverse();const reversed=compile(m).evaluate(args)
+  equal(r.values.lampPose.t,reversed.values.lampPose.t)
+  assert.throws(()=>p.evaluate({...args,height:0}),e=>e.code==='INPUT_RANGE')
+  assert.deepEqual(p.evaluate(args),r)
+  m.nodes.find(n=>n.id==='lampFeature').params.name='opening'
+  assert.throws(()=>compile(m),e=>e.code==='UNKNOWN_FEATURE')
+})

package/docs/prototypes/v3-typed-plan.mjs

@@ -0,0 +1,3 @@
+// Compatibility entry for experiments: one implementation lives in production source.
+export {compileV3Graph as compile} from '../../src/v3-graph.ts'
+export {V3ContractError as ContractError} from '../../src/v3-contract.ts'

package/docs/prototypes/v3-typed-plan.test.mjs

@@ -0,0 +1,70 @@
+import assert from 'node:assert/strict'
+import {test} from 'node:test'
+import {compile,ContractError} from './v3-typed-plan.mjs'
+const near=(a,b)=>assert.ok(Math.abs(a-b)<1e-8,`${a} != ${b}`)
+const c=(id,value,unit='mm')=>({id,value,unit})
+function model(){return {version:'r3-scalar-1',inputs:[{id:'width',unit:'cm',min:1,max:1000}],constants:[c('zero',0),c('margin',10),c('radius',48)],nodes:[
+  {id:'span',op:'between@1',args:['zero','width','margin','margin'],outputs:{length:'length',center:'center'}},
+  {id:'roller',op:'cylinder@1',args:['radius','length'],outputs:{start:'start',end:'end',radialMin:'rMin',radialMax:'rMax'}}]}}
+const rejects=(fn,code)=>assert.throws(fn,e=>e instanceof ContractError&&e.code===code)
+
+test('length conversion, multi-output owner and shared provider feature dimensions: 100 widths',()=>{
+  const p=compile(model())
+  for(let width=3;width<103;width++){
+    const r=p.evaluate({width}),g=r.geometry[0]
+    near(g.dimensions.length,width*10-20);near(r.values.center,width*5)
+    near(r.values.center+r.values.start,10);near(r.values.center+r.values.end,width*10-10)
+    near(r.values.rMax,g.dimensions.radius)
+  }
+})
+test('dimension error rejected at compile, geometric infeasibility at evaluation',()=>{
+  const m=model();m.inputs[0].unit='deg';rejects(()=>compile(m),'TYPE')
+  const p=compile(model());rejects(()=>p.evaluate({width:1}),'NO_SPACE');rejects(()=>p.evaluate({width:2}),'NO_SPACE')
+  rejects(()=>p.evaluate({width:0}),'INPUT_RANGE')
+})
+test('multiply/divide compose dimensions and sin requires angle, not an untyped ratio',()=>{
+  const m={version:'r3-scalar-1',inputs:[],constants:[c('w',20),c('h',30),c('a',90,'deg')],nodes:[
+    {id:'area',op:'mul@1',args:['w','h'],outputs:{value:'areaValue'}},
+    {id:'recover',op:'div@1',args:['areaValue','w'],outputs:{value:'height'}},
+    {id:'trig',op:'sin@1',args:['a'],outputs:{value:'sine'}}]}
+  const p=compile(m),r=p.evaluate({});assert.deepEqual(p.outputTypes.areaValue,[2,0,0]);assert.deepEqual(p.outputTypes.height,[1,0,0]);near(r.values.height,30);near(r.values.sine,1)
+  m.constants[2].unit='ratio';rejects(()=>compile(m),'TYPE')
+})
+test('state-dependent radius uses percent conversion; negative radius is not clamped',()=>{
+  const m={version:'r3-scalar-1',inputs:[{id:'fed',unit:'percent',min:0,max:100}],constants:[c('one',1,'ratio'),c('slope',-.68,'ratio'),c('baseRadius',350),c('length',1000)],nodes:[
+    {id:'shrink',op:'mul@1',args:['fed','slope'],outputs:{value:'change'}},
+    {id:'factor',op:'add@1',args:['one','change'],outputs:{value:'factorValue'}},
+    {id:'radius',op:'mul@1',args:['baseRadius','factorValue'],outputs:{value:'r'}},
+    {id:'roll',op:'cylinder@1',args:['r','length'],outputs:{start:'start',end:'end',radialMin:'rMin',radialMax:'rMax'}}]}
+  near(compile(m).evaluate({fed:100}).geometry[0].dimensions.radius,112)
+  m.constants[1].value=-2;rejects(()=>compile(m).evaluate({fed:100}),'GEOMETRY_DOMAIN')
+})
+test('duplicate output and inter-operation cycles do not depend on insertion order',()=>{
+  let m=model();m.nodes[1].outputs.start='length';rejects(()=>compile(m),'DUPLICATE_WRITER')
+  m=model();m.nodes[0].args[1]='end';rejects(()=>compile(m),'CYCLE')
+  m.nodes.reverse();rejects(()=>compile(m),'CYCLE')
+  m=model();m.nodes[0].args[0]='unknown';rejects(()=>compile(m),'UNKNOWN_REFERENCE')
+})
+test('schema is strict and operator version is explicit',()=>{
+  let m=model();m.nodes[0].op='between@2';rejects(()=>compile(m),'OPERATOR')
+  m=model();m.nodes[0].priority=1;rejects(()=>compile(m),'SCHEMA')
+  m=model();delete m.nodes[0].outputs.center;rejects(()=>compile(m),'SCHEMA')
+  m=model();m.nodes[0].outputs.unused='unused';rejects(()=>compile(m),'SCHEMA')
+})
+test('zero division, missing inputs, unknown inputs and nonfinite values reject',()=>{
+  const m=model();m.nodes.push({id:'division',op:'div@1',args:['width','zero'],outputs:{value:'quotient'}})
+  rejects(()=>compile(m).evaluate({width:60}),'DOMAIN')
+  const p=compile(model());rejects(()=>p.evaluate({}),'SCHEMA');rejects(()=>p.evaluate({width:50,extra:3}),'SCHEMA');rejects(()=>p.evaluate({width:NaN}),'NON_FINITE')
+})
+test('compiled snapshot is independent of authoring mutation and definition ordering',()=>{
+  const m=model(),p=compile(m),before=p.evaluate({width:60})
+  m.nodes.reverse();assert.deepEqual(compile(m).evaluate({width:60}),before)
+  m.constants.find(c=>c.id==='radius').value=100
+  assert.deepEqual(p.evaluate({width:60}),before)
+  rejects(()=>p.evaluate({width:1}),'NO_SPACE');assert.deepEqual(p.evaluate({width:60}),before)
+})
+test('box output faces and geometry share dimensions',()=>{
+  const m={version:'r3-scalar-1',inputs:[],constants:[c('w',2,'m'),c('h',30,'cm'),c('d',80)],nodes:[{id:'box',op:'box@1',args:['w','h','d'],outputs:{xMin:'xl',xMax:'xh',yMin:'yl',yMax:'yh',zMin:'zl',zMax:'zh'}}]}
+  const r=compile(m).evaluate({}),d=r.geometry[0].dimensions
+  near(r.values.xh-r.values.xl,d.width);near(r.values.yh-r.values.yl,d.height);near(r.values.zh-r.values.zl,d.depth)
+})

package/docs/prototypes/v3-typed-repeat.test.mjs

@@ -0,0 +1,96 @@
+import fs from 'node:fs'
+import {test} from 'node:test'
+import assert from 'node:assert/strict'
+import {compile} from './v3-typed-plan.mjs'
+import {meshOf,meshAudit} from './v3-dryroom-mesh.mjs'
+const seeds=JSON.parse(fs.readFileSync(new URL('../../../operato-application/packages/operato-figure/server/seed/figure-samples.json',import.meta.url)))
+const c=(id,value,unit='mm')=>({id,value,unit})
+const n=(id,op,args,outputs,params)=>({id,op,args,outputs,...(params?{params}:{})})
+const near=(a,b)=>assert.ok(Math.abs(a-b)<1e-6,`${a} != ${b}`)
+export function repeatModel(kind){
+  const type={tray:'FORMATION_TRAY',charger:'FORMATION_CHARGER',conveyor:'CONVEYOR'}[kind]
+  const s=seeds.find(s=>s.type===type).source,primary=s.parts.find(p=>p.name===({tray:'cell',charger:'shelf',conveyor:'roller'}[kind]))
+  const secondary=kind==='conveyor'?null:s.parts.find(p=>p.name===(kind==='tray'?'contact':'channel-lamp'))
+  const axis=kind==='charger'?'y':'x',extent=kind==='charger'?60:primary.transform.size.x
+  const margin=kind==='tray'?30:kind==='charger'?160:150
+  const m={version:'r3-spatial-1',inputs:[{id:'span',unit:'mm',min:0,max:10000},{id:'angle',unit:'deg',min:-180,max:180,role:'state'}],constants:[c('zero',0),c('a0',0,'rad'),c('quarter',90,'deg'),c('negHalf',-.5,'ratio'),c('margin',margin),c('extent',extent),c('pitch',primary.repeat.pitch),c('align',0,'ratio'),c('limit',100,'count'),c('eight',8,'count')],nodes:[]}
+  const rigid=(id,from,to,xyz,rot=['a0','a0','a0'])=>n(id,'rigid@1',[...xyz,...rot],{pose:id},{from,to})
+  m.nodes.push(n('half','mul@1',['span','negHalf'],{value:'left'}),rigid('root','item','world',axis==='x'?['left','zero','zero']:['zero','zero','zero']))
+  m.nodes.push(kind==='tray'?n('layout','fixed-count@1',['eight','span','margin','margin','extent','align','limit'],{layout:'layout'}):n('layout','fit-pitch@1',['span','margin','margin','extent','pitch','align','limit'],{layout:'layout'}))
+  const members=[]
+  for(const [index,p] of [primary,secondary].filter(Boolean).entries()){
+    const label=index?'secondary':'primary',d=p.transform.size,t=p.transform.position
+    for(const a of ['x','y','z'])m.constants.push(c(`${label}${a}`,t[a]-(a===axis?primary.transform.position[a]:0)))
+    let shape
+    if(kind==='conveyor'){
+      m.constants.push(c('radius',d.x/2),c('length',d.y))
+      shape=n(label,'cylinder-shape@1',['radius','length'],{shape:`${label}Shape`},{frame:label})
+      // Rx(90) lays the cylinder along Z; its local Y rotation follows afterwards.
+    } else {
+      for(const [key,val] of Object.entries(d))m.constants.push(c(`${label}Size${key}`,val))
+      shape=n(label,'box-shape@1',['x','y','z'].map(a=>`${label}Size${a}`),{shape:`${label}Shape`},{frame:label})
+    }
+    m.nodes.push(shape,rigid(`${label}Pose`,label,'item',['x','y','z'].map(a=>`${label}${a}`),kind==='conveyor'?['quarter','angle','a0']:['a0','a0','a0']),n(`${label}Member`,'member@1',[`${label}Shape`,`${label}Pose`],{placed:`${label}Member`}))
+    members.push(`${label}Member`)
+  }
+  m.nodes.push(n('assembly','assembly@1',members,{assembly:'assembly'}),n('repeat','repeat@1',['layout','assembly','root'],{collection:'collection'},{axis}))
+  return m
+}
+
+test('three actual-seed-derived assemblies: combined span and spin, no template duplicates',()=>{
+  let states=0
+  for(const [kind,spans] of [['tray',[500,600,1200]],['charger',[1000,2800,5600]],['conveyor',[1200,2400,4800]]]){
+    const p=compile(repeatModel(kind))
+    for(const span of spans)for(const angle of [-180,-90,0,90,180]){
+      const r=p.evaluate({span,angle}),count=r.values.layout.count
+      assert.equal(r.geometry.length,count*(kind==='conveyor'?1:2))
+      for(let i=0;i<count;i++){
+        const a=r.geometry.find(g=>g.index===i&&g.key==='primaryMember')
+        const axis=kind==='charger'?1:0,center=r.values.layout.centers[i]
+        near(a.pose.t[axis],center+(axis===0?-span/2:0))
+        const extent=kind==='conveyor'?96:kind==='tray'?52:60,margin=kind==='conveyor'?150:kind==='tray'?30:160
+        assert.ok(center-extent/2>=margin-1e-6&&center+extent/2<=span-margin+1e-6)
+        if(kind==='conveyor')near(a.pose.t[1],500)
+        else {
+          const b=r.geometry.find(g=>g.index===i&&g.key==='secondaryMember')
+          near(b.pose.t[axis]-a.pose.t[axis],0)
+          if(kind==='tray')near(b.pose.t[1]-a.pose.t[1],90)
+          else near(b.pose.t[2]-a.pose.t[2],295)
+        }
+      }
+      states++
+    }
+  }
+  assert.equal(states,45)
+})
+test('extent-aware threshold, empty result, limit and fixed-count insufficiency',()=>{
+  const p=compile(repeatModel('conveyor'))
+  for(const [span,want] of [[395,0],[396,1],[545.99,1],[546,2],[546.01,2]])assert.equal(p.evaluate({span,angle:0}).geometry.length,want)
+  const m=repeatModel('conveyor');m.constants.find(c=>c.id==='limit').value=1
+  assert.throws(()=>compile(m).evaluate({span:546,angle:0}),e=>e.code==='RESOURCE_LIMIT')
+  assert.throws(()=>compile(repeatModel('tray')).evaluate({span:400,angle:0}),e=>e.code==='NO_SPACE')
+})
+test('stable keys with grow/shrink/regrow and explicit dangling reference',()=>{
+  const m=repeatModel('conveyor'),p=compile(m),small=p.evaluate({span:545.99,angle:0}),big=p.evaluate({span:546,angle:0})
+  assert.equal(small.geometry[0].id,big.geometry[0].id)
+  assert.deepEqual(p.evaluate({span:546,angle:0}),big)
+  m.constants.push(c('selected',1,'count'));m.nodes.push(n('select','select-item@1',['collection','selected'],{placed:'selectedItem'},{member:'primaryMember'}))
+  const withRef=compile(m);withRef.evaluate({span:546,angle:0})
+  assert.throws(()=>withRef.evaluate({span:545.99,angle:0}),e=>e.code==='TARGET_ABSENT')
+})
+test('topology state dependency, count type, frame mismatch and cycles reject',()=>{
+  let m=repeatModel('tray');m.constants.find(c=>c.id==='eight').unit='ratio';assert.throws(()=>compile(m),e=>e.code==='TYPE')
+  m=repeatModel('tray');m.constants.find(c=>c.id==='eight').value=8.5;assert.throws(()=>compile(m),e=>e.code==='COUNT')
+  m=repeatModel('charger');m.inputs[0].role='state';assert.throws(()=>compile(m),e=>e.code==='TOPOLOGY_STATE')
+  m=repeatModel('conveyor');m.nodes.find(n=>n.id==='root').params.from='wrong';assert.throws(()=>compile(m),e=>e.code==='FRAME_TYPE')
+  m=repeatModel('conveyor');m.nodes.find(n=>n.id==='layout').args[0]='collection';assert.throws(()=>compile(m),e=>e.code==='CYCLE')
+})
+test('all generated boxes and cylinders are closed oriented meshes; layout snapshots repeat exactly',()=>{
+  let meshes=0
+  for(const [kind,span] of [['tray',600],['charger',2800],['conveyor',2400]]){
+    const p=compile(repeatModel(kind)),r=p.evaluate({span,angle:0})
+    for(const placed of r.geometry){const g=meshOf(placed),a=meshAudit(g);assert.equal(a.badEdges,0);assert.equal(a.euler,2);assert.ok(a.volume>0&&a.minArea>0);g.dispose();meshes++}
+    assert.deepEqual(p.evaluate({span,angle:0}),r)
+  }
+  console.log({meshes})
+})