@hatiolab/figure-model 0.1.30 → 0.1.31

package/docs/prototypes/render-full-dryroom.mjs

@@ -0,0 +1,86 @@
+// Isolated browser experiment; never connects to the product server or edits assets.
+import {createServer} from 'node:http'
+import {readFile} from 'node:fs/promises'
+import {chromium} from '/Users/super/.cache/codex-runtimes/codex-primary-runtime/dependencies/node/node_modules/playwright/index.mjs'
+import {seed,defaults,evaluateFull,geometryOf,sourceGeometry} from './v3-full-dryroom.mjs'
+import * as conveyor from './v3-full-conveyor.mjs'
+import * as robot from './v3-full-robot.mjs'
+import * as forklift from './v3-full-forklift.mjs'
+import {forkliftBindings} from './v3-capability-samples.mjs'
+import {compilePayloadInspection} from './v3-payload-fit.mjs'
+import {compileCollisionInspection} from './v3-payload-collision.mjs'
+const isConveyor=process.argv.includes('--conveyor')
+const isRobot=process.argv.includes('--robot')
+const isCollision=process.argv.includes('--collision')
+const isPayload=process.argv.includes('--payload')||isCollision
+const isForklift=process.argv.includes('--forklift')||isPayload
+const pack=(items)=>items.map(x=>({id:x.id,material:x.material,geometry:x.geometry.toJSON()}))
+const fromV3=args=>pack(evaluateFull(args).map(x=>({...x,geometry:geometryOf(x)})))
+const robotPose={...robot.defaults,'base-pan':30,'shoulder-lift':-35,'elbow-flex':65,'wrist-pitch':-25,'wrist-yaw':40,'tool-roll':20,gripper:50}
+function payloadVariants(){
+ const sample=forkliftBindings(),p=(isCollision?compileCollisionInspection:compilePayloadInspection)(sample.model,sample.declaration)
+ const scenarios=isCollision?[['Clear placement',[260,50,75],620,100,700],['Upper forks penetrated',[260,250,75],620,500,700],['Floating',[260,200,75],620,100,700],['Curved body: unresolved',[260,343,-1485],50,50,50]]:[['Contact',[260,50,0],620],['Floating 150mm',[260,200,0],620],['Penetrates 20mm',[260,30,0],620],['Between forks: no contact',[260,50,0],100]]
+ return scenarios.map(([title,center,width,height=100,depth=850])=>{
+  const q={bindingId:'load-low',type:'PALLET',occupied:0,dimensions:[width,height,depth],center,yawDeg:0},r=p.evaluate(forklift.defaults,q)
+  const b=r.evaluation.bindings[0],t=b.pose.r.map((row,j)=>b.pose.t[j]+row.reduce((v,x,i)=>v+x*center[i],0))
+  const placed={shape:{provider:'box',dimensions:{width,height,depth}},pose:{r:b.pose.r,t}}
+  return {title:title+' · contact '+r.inspection.contact.status+(isCollision?' / collision '+r.inspection.collision.status:''),parts:pack([...forklift.evaluateFull().map(x=>({...x,material:isCollision&&r.inspection.collision.pairs.some(p=>p.geometryId===x.id&&p.status==='failed')?{token:'palette.status-danger'}:x.material,geometry:forklift.geometryOf(x)})),{id:'payload',material:{token:'palette.accent'},geometry:forklift.geometryOf(placed)}])}
+ })
+}
+const variants=isPayload?payloadVariants():isForklift?[
+ {title:'Source seed · rest pose',parts:pack(forklift.seed.parts.map(p=>({id:p.name,material:p.material,geometry:forklift.sourceGeometry(p)})))},
+ ...[
+  ['V3 · same rest pose',forklift.defaults],
+  ['V3 · lift 1000 / reach 200 / drive 37',{...forklift.defaults,lift:1000,reach:200,drive:37}],
+  ['V3 · longer forks / lift 2000 / reach 400',{forkLength:1275,lift:2000,reach:400,drive:73}]
+ ].map(([title,args])=>({title,parts:pack(forklift.evaluateFull(args).map(x=>({...x,geometry:forklift.geometryOf(x)})))}))
+]:isRobot?[
+ {title:'Source fixture · rest pose',parts:pack(robot.seed.parts.map(p=>({id:p.name,material:p.material??{token:'palette.neutral'},geometry:robot.sourceGeometry(p)})))},
+ ...[
+  ['V3 · same rest pose',robot.defaults],
+  ['V3 · six joints + gripper',robotPose],
+  ['V3 · changed link lengths + same joints',{...robotPose,upperLength:630,foreLength:570}]
+ ].map(([title,args])=>({title,parts:pack(robot.evaluateFull(args).map(x=>({...x,geometry:robot.geometryOf(x)})))}))
+]:isConveyor?[
+ {title:'Source seed · overlapping end rollers',parts:pack(conveyor.sourceItems())},
+ ...[
+  ['V3 · reserved end roller space',conveyor.defaults],
+  ['V3 · roller rotation 37 degrees',{...conveyor.defaults,angle:37}],
+  ['V3 · resized assembly',{length:3000,width:900,rollerHeight:700,angle:37}]
+ ].map(([title,args])=>({title,parts:pack(conveyor.evaluateFull(args).map(x=>({...x,geometry:conveyor.geometryOf(x)})))}))
+]:[
+  {title:'Source seed · six parts',parts:pack(seed.parts.map(p=>({id:p.name,material:p.material,geometry:sourceGeometry(p)})))},
+  {title:'V3 · same dimensions',parts:fromV3(defaults)},
+  {title:'V3 · portal bottom trimmed to floor',parts:fromV3({...defaults,bottom:0})},
+  {title:'V3 · resized + lamps raised',parts:fromV3({...defaults,width:4800,height:3600,depth:7200,bottom:0,lampLift:100})}
+]
+const html=`<!doctype html><meta charset="utf-8"><style>body{margin:0;background:#e9edf2;font:16px sans-serif;color:#17283b}main{display:grid;grid-template-columns:1fr 1fr;gap:12px;padding:12px}section{background:white;border-radius:8px;overflow:hidden}h3{margin:12px;font-size:16px}canvas{display:block;width:100%}p{margin:12px;font-size:12px}</style><main></main><script type="module">
+import * as T from '/three.module.js';
+const variants=${JSON.stringify(variants)};
+const palette={'palette.primary':'#154473','palette.accent':'#f79c40','palette.neutral':'#96989b','palette.dark':'#27292c','palette.light':'#d6d7d9','palette.surface':'#56585b','palette.status-danger':'#f61b30','palette.status-warning':'#e68d1a','palette.status-success':'#1cb648','palette.status-info':'#158bde'};
+window.results=[];window.pixels=[];
+for(const v of variants){
+ const section=document.createElement('section');section.innerHTML='<h3>'+v.title+'</h3>';document.querySelector('main').append(section);
+ const renderer=new T.WebGLRenderer({antialias:true,preserveDrawingBuffer:true});renderer.setSize(640,420);renderer.setClearColor('#f7f9fb');section.append(renderer.domElement);
+ const scene=new T.Scene();scene.add(new T.HemisphereLight(0xffffff,0x687381,2));const light=new T.DirectionalLight(0xffffff,3);light.position.set(5000,9000,9000);scene.add(light);
+ // Metal needs reflected illumination; a hemisphere light alone leaves it nearly black.
+ const envCanvas=document.createElement('canvas');envCanvas.width=512;envCanvas.height=256;const ctx=envCanvas.getContext('2d');const grad=ctx.createLinearGradient(0,0,0,256);grad.addColorStop(0,'#ffffff');grad.addColorStop(.5,'#b8c4d4');grad.addColorStop(1,'#4e5c6b');ctx.fillStyle=grad;ctx.fillRect(0,0,512,256);ctx.fillStyle='#ffffff';ctx.fillRect(70,30,90,80);const envTex=new T.CanvasTexture(envCanvas);envTex.colorSpace=T.SRGBColorSpace;const pmrem=new T.PMREMGenerator(renderer);scene.environment=pmrem.fromEquirectangular(envTex).texture;
+ for(const p of v.parts){const m=p.material,e=m.emissive;const color=palette[e?.on?e.token:m.token]??'#96989b';const mat=new T.MeshStandardMaterial({color,metalness:m.preset==='metal'?1:0,roughness:m.preset==='rubber'?.9:m.preset==='metal'?.3:.4,flatShading:true,transparent:!!m.transparent,emissive:e?.on?color:0,emissiveIntensity:e?.on?e.intensity:0});scene.add(new T.Mesh(new T.BufferGeometryLoader().parse(p.geometry),mat));}
+ const camera=new T.PerspectiveCamera(38,640/420,1,50000);camera.position.set(...${JSON.stringify(isForklift?[5200,4200,6200]:isRobot?[2300,1900,2900]:isConveyor?[3000,2400,3300]:[10000,8000,13500])});camera.lookAt(0,${isForklift?1250:isRobot?750:isConveyor?350:1300},0);renderer.render(scene,camera);
+ const gl=renderer.getContext(),px=new Uint8Array(640*420*4);gl.readPixels(0,0,640,420,gl.RGBA,gl.UNSIGNED_BYTE,px);window.pixels.push(px);
+ window.results.push({title:v.title,calls:renderer.info.render.calls,triangles:renderer.info.render.triangles});
+ section.insertAdjacentHTML('beforeend','<p>'+renderer.info.render.calls+' draw calls / '+renderer.info.render.triangles+' triangles · identical camera</p>');
+}
+let different=0,max=0;for(let i=0;i<pixels[0].length;i++){const d=Math.abs(pixels[0][i]-pixels[1][i]);if(d)different++;max=Math.max(max,d)}window.comparison={differentChannels:different,maxChannelDifference:max};window.ready=true;
+</script>`
+const server=createServer(async(req,res)=>{try{if(req.url==='/'){res.setHeader('Content-Type','text/html');res.end(html)}else if(['/three.module.js','/three.core.js'].includes(req.url)){res.setHeader('Content-Type','text/javascript');res.end(await readFile(new URL('../../../things-scene/node_modules/three/build'+req.url,import.meta.url)))}else{res.statusCode=404;res.end()}}catch(e){res.statusCode=500;res.end(String(e))}})
+await new Promise(r=>server.listen(0,'127.0.0.1',r));let browser
+try{
+ browser=await chromium.launch({headless:true,executablePath:'/Applications/Google Chrome.app/Contents/MacOS/Google Chrome'});
+ const page=await browser.newPage({viewport:{width:1328,height:990},deviceScaleFactor:1});const errors=[];page.on('pageerror',e=>errors.push(String(e)));
+ await page.goto('http://127.0.0.1:'+server.address().port);await page.waitForFunction(()=>window.ready);
+ const screenshot='/private/tmp/figure-v3-full-'+(isCollision?'collision':isPayload?'payload':isForklift?'forklift':isRobot?'robot':isConveyor?'conveyor':'dryroom')+'.png';
+ await page.screenshot({path:screenshot,fullPage:true});
+ console.log(JSON.stringify({...await page.evaluate(()=>({results:window.results,comparison:window.comparison})),errors,screenshot},null,2));
+ if(errors.length)process.exitCode=1;
+}finally{await browser?.close();server.close()}

package/docs/prototypes/shapeassembly-probe-results.json

@@ -0,0 +1,325 @@
+{
+  "revision": "cc22bd84afb65e8e37c7d14bebd9a4a629b5d943",
+  "python": "3.12.14 (main, Aug 25 2026, 13:50:33) [Clang 22.1.3 ]",
+  "torch": "2.8.0",
+  "numpy": "2.2.6",
+  "faiss": "1.12.0",
+  "units": "native abstract units, not Figure mm",
+  "results": [
+    {
+      "case": "lamp_fresh_replay_height_1",
+      "lines": [
+        "bbox = Cuboid(4, 1, 4, True)",
+        "body = Cuboid(1, 1, 1, True)",
+        "lamp = Cuboid(.2, .2, .2, True)",
+        "attach(body, bbox, .5, 0, .5, .5, 0, .5)",
+        "attach(lamp, body, .5, 0, .5, .5, 1, .5)"
+      ],
+      "result": {
+        "body": {
+          "size": [
+            1,
+            1,
+            1
+          ],
+          "center": [
+            0,
+            0,
+            0
+          ]
+        },
+        "lamp": {
+          "size": [
+            0.20000000298023224,
+            0.20000000298023224,
+            0.20000000298023224
+          ],
+          "center": [
+            0,
+            0.6000000238418579,
+            0
+          ]
+        }
+      },
+      "contact_point_residuals": [
+        0
+      ]
+    },
+    {
+      "case": "lamp_fresh_replay_height_2",
+      "lines": [
+        "bbox = Cuboid(4, 2, 4, True)",
+        "body = Cuboid(1, 2, 1, True)",
+        "lamp = Cuboid(.2, .2, .2, True)",
+        "attach(body, bbox, .5, 0, .5, .5, 0, .5)",
+        "attach(lamp, body, .5, 0, .5, .5, 1, .5)"
+      ],
+      "result": {
+        "body": {
+          "size": [
+            1,
+            2,
+            1
+          ],
+          "center": [
+            0,
+            0,
+            0
+          ]
+        },
+        "lamp": {
+          "size": [
+            0.20000000298023224,
+            0.20000000298023224,
+            0.20000000298023224
+          ],
+          "center": [
+            0,
+            1.100000023841858,
+            0
+          ]
+        }
+      },
+      "contact_point_residuals": [
+        0
+      ]
+    },
+    {
+      "case": "lamp_fresh_replay_height_4",
+      "lines": [
+        "bbox = Cuboid(4, 4, 4, True)",
+        "body = Cuboid(1, 4, 1, True)",
+        "lamp = Cuboid(.2, .2, .2, True)",
+        "attach(body, bbox, .5, 0, .5, .5, 0, .5)",
+        "attach(lamp, body, .5, 0, .5, .5, 1, .5)"
+      ],
+      "result": {
+        "body": {
+          "size": [
+            1,
+            4,
+            1
+          ],
+          "center": [
+            0,
+            0,
+            0
+          ]
+        },
+        "lamp": {
+          "size": [
+            0.20000000298023224,
+            0.20000000298023224,
+            0.20000000298023224
+          ],
+          "center": [
+            0,
+            2.0999999046325684,
+            0
+          ]
+        }
+      },
+      "contact_point_residuals": [
+        1.1920928955078125e-7
+      ]
+    },
+    {
+      "case": "squeeze_height_0.5_aligned_True",
+      "lines": [
+        "bbox = Cuboid(1, 1, 1, True)",
+        "beam = Cuboid(.2, 0.5, .2, True)",
+        "squeeze(beam, bbox, bbox, top, .5, .5)"
+      ],
+      "result": {
+        "beam": {
+          "size": [
+            0.20000000298023224,
+            0.5,
+            0.20000000298023224
+          ],
+          "center": [
+            0,
+            0.25,
+            0
+          ]
+        }
+      },
+      "contact_point_residuals": [
+        0,
+        0.5
+      ]
+    },
+    {
+      "case": "squeeze_height_2_aligned_True",
+      "lines": [
+        "bbox = Cuboid(1, 1, 1, True)",
+        "beam = Cuboid(.2, 2, .2, True)",
+        "squeeze(beam, bbox, bbox, top, .5, .5)"
+      ],
+      "result": {
+        "beam": {
+          "size": [
+            0.20000000298023224,
+            2,
+            0.20000000298023224
+          ],
+          "center": [
+            0,
+            -0.5,
+            0
+          ]
+        }
+      },
+      "contact_point_residuals": [
+        0,
+        1
+      ]
+    },
+    {
+      "case": "squeeze_height_0.5_aligned_False",
+      "lines": [
+        "bbox = Cuboid(1, 1, 1, True)",
+        "beam = Cuboid(.2, 0.5, .2, False)",
+        "squeeze(beam, bbox, bbox, top, .5, .5)"
+      ],
+      "result": {
+        "beam": {
+          "size": [
+            0.20000000298023224,
+            1,
+            0.20000000298023224
+          ],
+          "center": [
+            0,
+            0,
+            0
+          ]
+        }
+      },
+      "contact_point_residuals": [
+        0,
+        0
+      ]
+    },
+    {
+      "case": "squeeze_height_2_aligned_False",
+      "lines": [
+        "bbox = Cuboid(1, 1, 1, True)",
+        "beam = Cuboid(.2, 2, .2, False)",
+        "squeeze(beam, bbox, bbox, top, .5, .5)"
+      ],
+      "result": {
+        "beam": {
+          "size": [
+            0.20000000298023224,
+            1,
+            0.20000000298023224
+          ],
+          "center": [
+            0,
+            0,
+            0
+          ]
+        }
+      },
+      "contact_point_residuals": [
+        0,
+        0
+      ]
+    },
+    {
+      "case": "direct_resize_after_attachment",
+      "lines": [
+        "bbox = Cuboid(4, 4, 4, True)",
+        "body = Cuboid(1, 1, 1, True)",
+        "lamp = Cuboid(.2, .2, .2, True)",
+        "attach(body, bbox, .5, 0, .5, .5, 0, .5)",
+        "attach(lamp, body, .5, 0, .5, .5, 1, .5)",
+        "body = Cuboid(1, 2, 1, True)"
+      ],
+      "result": {
+        "body": {
+          "size": [
+            1,
+            2,
+            1
+          ],
+          "center": [
+            0,
+            -1.5,
+            0
+          ]
+        },
+        "lamp": {
+          "size": [
+            0.20000000298023224,
+            0.20000000298023224,
+            0.20000000298023224
+          ],
+          "center": [
+            0,
+            -0.8999999761581421,
+            0
+          ]
+        }
+      },
+      "contact_point_residuals": [
+        0.5
+      ]
+    },
+    {
+      "case": "conflicting_same_point_reverse_False",
+      "lines": [
+        "bbox = Cuboid(1, 1, 1, True)",
+        "part = Cuboid(.2, .2, .2, True)",
+        "attach(part, bbox, .5, 0, .5, .5, 0, .5)",
+        "attach(part, bbox, .5, 0, .5, .5, 1, .5)"
+      ],
+      "result": {
+        "part": {
+          "size": [
+            0.20000000298023224,
+            0.20000000298023224,
+            0.20000000298023224
+          ],
+          "center": [
+            0,
+            -0.4000000059604645,
+            0
+          ]
+        }
+      },
+      "contact_point_residuals": [
+        0,
+        1
+      ]
+    },
+    {
+      "case": "conflicting_same_point_reverse_True",
+      "lines": [
+        "bbox = Cuboid(1, 1, 1, True)",
+        "part = Cuboid(.2, .2, .2, True)",
+        "attach(part, bbox, .5, 0, .5, .5, 1, .5)",
+        "attach(part, bbox, .5, 0, .5, .5, 0, .5)"
+      ],
+      "result": {
+        "part": {
+          "size": [
+            0.20000000298023224,
+            0.20000000298023224,
+            0.20000000298023224
+          ],
+          "center": [
+            0,
+            0.6000000238418579,
+            0
+          ]
+        }
+      },
+      "contact_point_residuals": [
+        1,
+        0
+      ]
+    }
+  ]
+}

package/docs/prototypes/shapeassembly-probe.py

@@ -0,0 +1,84 @@
+"""Independent research probe. Requires an external checkout; not product code.
+
+Usage: python shapeassembly-probe.py /path/to/ShapeAssembly
+No upstream source is copied or modified. No models are trained/downloaded.
+Reports observed behavior, not a claim that Figure or the paper is fully tested.
+"""
+import json
+import subprocess
+import sys
+from pathlib import Path
+
+checkout = Path(sys.argv[1]).resolve()
+expected = 'cc22bd84afb65e8e37c7d14bebd9a4a629b5d943'
+revision = subprocess.check_output(['git', '-C', str(checkout), 'rev-parse', 'HEAD'], text=True).strip()
+if revision != expected:
+    raise RuntimeError(f'Expected {expected}, found {revision}')
+sys.path.insert(0, str(checkout / 'code'))
+import torch
+import numpy as np
+import faiss
+from ShapeAssembly import Program
+
+torch.set_num_threads(1)
+
+def point(p, name, xyz):
+    return p.cuboids[name].getPos(*(torch.tensor(float(v)) for v in xyz))
+
+def snapshot(p):
+    return {name: {'size': c.dims.tolist(), 'center': c.pos.tolist()}
+            for name, c in p.cuboids.items() if name != 'bbox'}
+
+def run(name, lines, contacts):
+    p = Program()
+    try:
+        for line in lines:
+            p.execute(line)
+        residuals = [float(torch.linalg.vector_norm(point(p,a,u)-point(p,b,v)))
+                     for a,u,b,v in contacts]
+        return {'case': name, 'lines': lines, 'result': snapshot(p),
+                'contact_point_residuals': residuals}
+    except Exception as exc:
+        return {'case': name, 'lines': lines, 'error': type(exc).__name__ + ': ' + str(exc)}
+
+results = []
+for height in [1, 2, 4]:
+    results.append(run(f'lamp_fresh_replay_height_{height}', [
+        f'bbox = Cuboid(4, {height}, 4, True)',
+        f'body = Cuboid(1, {height}, 1, True)',
+        'lamp = Cuboid(.2, .2, .2, True)',
+        'attach(body, bbox, .5, 0, .5, .5, 0, .5)',
+        'attach(lamp, body, .5, 0, .5, .5, 1, .5)'
+    ], [('lamp',(.5,0,.5),'body',(.5,1,.5))]))
+
+for aligned in ['True', 'False']:
+    for size in [.5, 2]:
+        results.append(run(f'squeeze_height_{size}_aligned_{aligned}', [
+            'bbox = Cuboid(1, 1, 1, True)',
+            f'beam = Cuboid(.2, {size}, .2, {aligned})',
+            'squeeze(beam, bbox, bbox, top, .5, .5)'
+        ], [('beam',(.5,1,.5),'bbox',(.5,1,.5)),
+            ('beam',(.5,0,.5),'bbox',(.5,0,.5))]))
+
+results.append(run('direct_resize_after_attachment', [
+    'bbox = Cuboid(4, 4, 4, True)',
+    'body = Cuboid(1, 1, 1, True)',
+    'lamp = Cuboid(.2, .2, .2, True)',
+    'attach(body, bbox, .5, 0, .5, .5, 0, .5)',
+    'attach(lamp, body, .5, 0, .5, .5, 1, .5)',
+    'body = Cuboid(1, 2, 1, True)'
+], [('lamp',(.5,0,.5),'body',(.5,1,.5))]))
+
+for reverse in [False, True]:
+    attach = ['attach(part, bbox, .5, 0, .5, .5, 0, .5)',
+              'attach(part, bbox, .5, 0, .5, .5, 1, .5)']
+    results.append(run(f'conflicting_same_point_reverse_{reverse}', [
+        'bbox = Cuboid(1, 1, 1, True)',
+        'part = Cuboid(.2, .2, .2, True)',
+        *(reversed(attach) if reverse else attach)
+    ], [('part',(.5,0,.5),'bbox',(.5,0,.5)),
+        ('part',(.5,0,.5),'bbox',(.5,1,.5))]))
+
+print(json.dumps({'revision': revision, 'python': sys.version,
+    'torch': torch.__version__, 'numpy': np.__version__, 'faiss': faiss.__version__,
+    'units': 'native abstract units, not Figure mm', 'results': results}, indent=2))

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

@@ -0,0 +1,15 @@
+import * as dryroom from './v3-full-dryroom.mjs'
+import * as conveyor from './v3-full-conveyor.mjs'
+import * as robot from './v3-full-robot.mjs'
+import * as forklift from './v3-full-forklift.mjs'
+import {robotBinding,forkliftBindings} from './v3-capability-samples.mjs'
+export function sampleAsset(kind){
+ const modules={dryroom,conveyor,robot,forklift},sample=modules[kind]
+ if(!sample)throw Error('unknown sample')
+ const pair=kind==='robot'?robotBinding():kind==='forklift'?forkliftBindings():{model:sample.fullModel(),declaration:{version:'r3-capability-3',assetFrame:'world',bindings:[]}}
+ const designInputs={},stateDefaults={}
+ for(const i of pair.model.inputs)(i.role==='state'?stateDefaults:designInputs)[i.id]=sample.defaults[i.id]
+ return {version:'figure-v3-asset-experiment-1',name:sample.seed.type,document:{version:'figure-v3-prototype-1',model:pair.model,capabilities:pair.declaration},designInputs,stateDefaults,
+  palette:{'palette.primary':'#154473','palette.accent':'#f79c40','palette.neutral':'#96989b','palette.dark':'#27292c','palette.light':'#d6d7d9','palette.surface':'#56585b','palette.status-danger':'#f61b30','palette.status-warning':'#e68d1a','palette.status-info':'#158bde','palette.status-success':'#1cb648'},
+  appearance:sample.seed.parts.map(p=>({target:p.name,material:structuredClone(p.material??{token:'palette.neutral'}),...(p.primitive==='cylinder'?{segments:p.segments??8}:{}),...(p.capability?{legacyCapability:structuredClone(p.capability)}:{})}))}
+}

package/docs/prototypes/v3-asset-store.mjs

@@ -0,0 +1,52 @@
+// Single-process, isolated disk store. Not the product database or an authorization layer.
+import {readFile, open, rename, unlink} from 'node:fs/promises'
+import {join, resolve} from 'node:path'
+import {randomUUID, createHash} from 'node:crypto'
+import {parseAsset, serializeAsset} from './v3-asset.mjs'
+
+export class StoreError extends Error {
+ constructor(code,message){super(message);this.code=code}
+}
+const fail=(code,message)=>{throw new StoreError(code,message)}
+// Shared across store handles in this process; a multi-process deployment needs database CAS.
+const queues=new Map()
+async function exclusive(key,operation){
+ const previous=queues.get(key)||Promise.resolve()
+ const next=previous.catch(()=>{}).then(operation);queues.set(key,next)
+ try{return await next}finally{if(queues.get(key)===next)queues.delete(key)}
+}
+export function createAssetStore(directory){
+ const root=resolve(directory)
+ function file(scope,id){
+  for(const v of [scope,id])if(typeof v!=='string'||!v.trim()||v.length>200)fail('IDENTITY','scope and asset ID required')
+  return join(root,createHash('sha256').update(JSON.stringify([scope,id])).digest('hex')+'.json')
+ }
+ async function load(path,scope,id){
+  let raw;try{raw=await readFile(path,'utf8')}catch(e){if(e.code==='ENOENT')return null;throw e}
+  let record;try{record=JSON.parse(raw)}catch{fail('CORRUPT','stored record is not JSON')}
+  if(record?.format!=='v3-store-experiment-1'||record.scope!==scope||record.id!==id||typeof record.revision!=='string'||!record.revision)fail('CORRUPT','stored record identity or revision invalid')
+  // Stored content must pass the same semantic validation as incoming content.
+  parseAsset(record.text)
+  return record
+ }
+ return {
+  async read({scope,id}){const record=await load(file(scope,id),scope,id);if(!record)fail('NOT_FOUND','asset not found');return record},
+  async save({scope,id,expectedRevision,text}){
+   if(expectedRevision!==null&&(typeof expectedRevision!=='string'||!expectedRevision))fail('PRECONDITION','expectedRevision required; null means create only')
+   const path=file(scope,id),canonical=serializeAsset(parseAsset(text))
+   return exclusive(path,async()=>{
+    const current=await load(path,scope,id)
+    if((current?.revision??null)!==expectedRevision)fail('CONFLICT','asset changed; reload before saving')
+    const record={format:'v3-store-experiment-1',scope,id,revision:randomUUID(),text:canonical}
+    const temporary=path+'.'+randomUUID()+'.tmp';let handle
+    try{
+     handle=await open(temporary,'wx',0o600);await handle.writeFile(JSON.stringify(record));await handle.sync();await handle.close();handle=null
+     await rename(temporary,path)
+    }finally{
+     await handle?.close();await unlink(temporary).catch(e=>{if(e.code!=='ENOENT')throw e})
+    }
+    return record
+   })
+  }
+ }
+}

package/docs/prototypes/v3-asset-store.test.mjs

@@ -0,0 +1,59 @@
+import {test} from 'node:test'
+import assert from 'node:assert/strict'
+import {mkdtemp,rm,readdir} from 'node:fs/promises'
+import {tmpdir} from 'node:os'
+import {join} from 'node:path'
+import {execFile} from 'node:child_process'
+import {promisify} from 'node:util'
+import {createAssetStore} from './v3-asset-store.mjs'
+import {sampleAsset} from './v3-asset-samples.mjs'
+import {serializeAsset,parseAsset} from './v3-asset.mjs'
+import {createEditorWorkspace} from './v3-editor-workspace.mjs'
+async function fixture(t){const dir=await mkdtemp(join(tmpdir(),'v3-store-'));t.after(()=>rm(dir,{recursive:true,force:true}));return {dir,store:createAssetStore(dir)}}
+const body=()=>serializeAsset(sampleAsset('forklift'))
+const key={scope:'test-domain',id:'forklift'}
+test('disk save survives independent store handle; explicit create and scoped identity',async t=>{
+ const {dir,store}=await fixture(t),saved=await store.save({...key,expectedRevision:null,text:body()})
+ assert.deepEqual(await createAssetStore(dir).read(key),saved)
+ await assert.rejects(store.read({...key,scope:'other-domain'}),e=>e.code==='NOT_FOUND')
+ await assert.rejects(store.save({...key,expectedRevision:null,text:body()}),e=>e.code==='CONFLICT')
+ await assert.rejects(store.save({...key,text:body()}),e=>e.code==='PRECONDITION')
+ // Raw identifiers never become filesystem paths.
+ await store.save({scope:'../other',id:'../../escape',expectedRevision:null,text:body()})
+ assert.equal((await readdir(dir)).length,2)
+ assert.ok((await readdir(dir)).every(f=>/^[0-9a-f]{64}\.json$/.test(f)))
+})
+test('two writers cannot silently overwrite; content ABA still gets new revision',async t=>{
+ const {dir,store}=await fixture(t),a=await store.save({...key,expectedRevision:null,text:body()})
+ const asset=parseAsset(body());asset.designInputs.forkLength=1275;const changed=serializeAsset(asset)
+ const results=await Promise.allSettled([store,createAssetStore(dir)].map(s=>s.save({...key,expectedRevision:a.revision,text:changed})))
+ assert.equal(results.filter(r=>r.status==='fulfilled').length,1)
+ assert.equal(results.find(r=>r.status==='rejected').reason.code,'CONFLICT')
+ const b=await store.read(key),c=await store.save({...key,expectedRevision:b.revision,text:body()})
+ assert.notEqual(c.revision,a.revision)
+ await assert.rejects(store.save({...key,expectedRevision:a.revision,text:changed}),e=>e.code==='CONFLICT')
+})
+test('invalid source leaves prior snapshot intact and produces no temporary file',async t=>{
+ const {dir,store}=await fixture(t),a=await store.save({...key,expectedRevision:null,text:body()})
+ await assert.rejects(store.save({...key,expectedRevision:a.revision,text:'{"version":2}'}))
+ assert.deepEqual(await store.read(key),a);assert.equal((await readdir(dir)).length,1)
+})
+test('failed persistence does not clear editor dirty state',async t=>{
+ const {store}=await fixture(t),original=await store.save({...key,expectedRevision:null,text:body()})
+ const w=createEditorWorkspace(),v=w.open(original.text)
+ w.apply({context:v.context,origin:'ui',expectedRevision:0,changes:[{kind:'set-design',input:'forkLength',unit:'mm',value:1275}]})
+ const snapshot=w.export({context:v.context})
+ await store.save({...key,expectedRevision:original.revision,text:body()})
+ await assert.rejects(store.save({...key,expectedRevision:original.revision,text:snapshot.text}),e=>e.code==='CONFLICT')
+ assert.equal(w.read().dirty,true)
+ assert.equal(w.read().fields.find(f=>f.id==='forkLength').value,1275)
+})
+test('a separate Node process can restore the saved asset without editor memory',async t=>{
+ const {dir,store}=await fixture(t),asset=parseAsset(body());asset.designInputs.forkLength=1275
+ const saved=await store.save({...key,expectedRevision:null,text:serializeAsset(asset)})
+ const script=`import {createAssetStore} from ${JSON.stringify(new URL('./v3-asset-store.mjs',import.meta.url).href)};
+ const record=await createAssetStore(process.argv[1]).read(${JSON.stringify(key)});
+ console.log(JSON.stringify({revision:record.revision,length:JSON.parse(record.text).designInputs.forkLength}));`
+ const {stdout}=await promisify(execFile)(process.execPath,['--input-type=module','-e',script,dir])
+ assert.deepEqual(JSON.parse(stdout),{revision:saved.revision,length:1275})
+})

package/docs/prototypes/v3-asset.mjs

@@ -0,0 +1 @@
+export {compileV3Asset as compileAsset,parseV3Asset as parseAsset,serializeV3Asset as serializeAsset,captureV3AuthoredInputs as captureAuthoredInputs} from '../../src/v3-asset.ts'