abelien-harness 0.4.0 → 0.6.0

package/skills/abelien-structure/worker/engineering.py

@@ -0,0 +1,324 @@
+"""Trusted bounded analytic plate carrier + one faceted solid decoration.
+Never executed as model source. Every final check consumes fresh STEP readback.
+"""
+import base64
+import collections
+import copy
+import math
+import json
+import runpy
+from pathlib import Path
+import build123d as bd
+import numpy as np
+from OCP.BRepAdaptor import BRepAdaptor_Surface
+from OCP.BRepBuilderAPI import BRepBuilderAPI_MakeFace, BRepBuilderAPI_MakePolygon, BRepBuilderAPI_MakeSolid, BRepBuilderAPI_Sewing
+from OCP.BRepCheck import BRepCheck_Analyzer
+from OCP.BRep import BRep_Tool
+from OCP.BRepLib import BRepLib
+from OCP.BRepPrimAPI import BRepPrimAPI_MakeHalfSpace
+from OCP.BOPAlgo import BOPAlgo_CheckerSI
+from OCP.GeomAbs import GeomAbs_Cylinder, GeomAbs_Plane
+from OCP.TopAbs import TopAbs_SHELL
+from OCP.TopExp import TopExp_Explorer
+from OCP.TopTools import TopTools_ListOfShape
+from OCP.TopoDS import TopoDS
+from OCP.gp import gp_Pnt, gp_Pln, gp_Dir
+
+VERSION = 'planar-two-hole-fit.v1'
+POLICY = json.loads(Path(__file__).with_name('engineering-policy.json').read_text())
+REPAIR = runpy.run_path(Path(__file__).with_name('engineering-repair.py'))
+EPS = POLICY['linearToleranceMm']
+VOL = POLICY['volumeToleranceMm3']
+NOT_CHECKED = ['strength', 'manufacturability', 'physical_assembly', 'local_thin_features', 'texture_fidelity', 'hardware_geometry_accuracy']
+CHECK_IDS = ['baseline', 'closed_solid', 'self_intersection', 'carrier_preservation', 'interface_surfaces',
+             'protected_regions', 'continuous_join', 'static_collision', 'clearance', 'planar_insertion',
+             'preserved_occurrences', 'step_readback']
+
+def require(condition, code):
+    if not condition:
+        raise ValueError('engineering_' + code)
+
+def keys(value, names):
+    return isinstance(value, dict) and set(value) == set(names)
+
+def number(value, low=0, high=500):
+    return isinstance(value, (float, int)) and not isinstance(value, bool) and math.isfinite(value) and low < value <= high
+
+def proposal(value):
+    require(keys(value, ['schema', 'targetOccurrenceId', 'baseOccurrenceId', 'plate', 'baseThicknessMm', 'decoration', 'join', 'clearanceMm']), 'proposal')
+    require(value['schema'] == 'abelien.planar-attachment-proposal.v1', 'proposal_schema')
+    p,d,j = value['plate'],value['decoration'],value['join']
+    require(keys(p, ['widthMm','depthMm','thicknessMm','holeRadiusMm','holeCentersMm']) and
+            keys(d, ['heightMm','maximumWidthMm','maximumDepthMm','trimBottomFraction']) and
+            keys(j, ['radiusMm','embedMm','gapMm']), 'proposal_fields')
+    require(all(number(p[x]) for x in ['widthMm','depthMm','thicknessMm','holeRadiusMm']) and
+            all(number(d[x]) for x in ['heightMm','maximumWidthMm','maximumDepthMm']) and
+            all(number(j[x]) for x in j) and number(value['baseThicknessMm']) and number(value['clearanceMm']), 'dimensions')
+    require(isinstance(d['trimBottomFraction'], (float,int)) and not isinstance(d['trimBottomFraction'],bool) and 0 <= d['trimBottomFraction'] <= .25, 'trim')
+    holes=p['holeCentersMm']; require(isinstance(holes,list) and len(holes)==2 and all(isinstance(v,list) and len(v)==2 and all(number(abs(x)+EPS) for x in v) for v in holes), 'holes')
+    r=p['holeRadiusMm']; guard=value['clearanceMm']
+    for x,y in holes:
+        require(abs(x)+r+guard < p['widthMm']/2 and abs(y)+r+guard < p['depthMm']/2, 'hole_boundary')
+        require(math.hypot(x,y) > r+j['radiusMm']+guard, 'join_hole_overlap')
+    require(math.dist(holes[0],holes[1]) > 2*(r+guard), 'hole_overlap')
+    require(j['embedMm'] < p['thicknessMm'] and j['radiusMm']+guard < min(p['widthMm'],p['depthMm'])/2, 'join_dimensions')
+    require(value['targetOccurrenceId'] != value['baseOccurrenceId'], 'target')
+    return copy.deepcopy(value)
+
+def vol(shape):
+    if shape is None: return 0.0
+    if isinstance(shape, bd.Shape):
+        value=float(shape.volume); require(math.isfinite(value) and value >= -VOL, 'volume')
+        return max(0,value)
+    return sum(vol(item) for item in shape)
+
+def as_shape(value):
+    if isinstance(value,bd.Shape): return value
+    items=list(value or [])
+    return items[0] if len(items)==1 else bd.Compound(items)
+
+def diff(a,b):
+    if vol(a)==0:return vol(b)
+    if vol(b)==0:return vol(a)
+    a,b=as_shape(a),as_shape(b)
+    return vol(a.cut(b))+vol(b.cut(a))
+def cyl(radius, height, z=0, x=0, y=0):
+    return bd.Cylinder(radius,height,align=(bd.Align.CENTER,bd.Align.CENTER,bd.Align.MIN)).moved(bd.Location((x,y,z)))
+def plate(p, thickness, z=0):
+    result=bd.Box(p['widthMm'],p['depthMm'],thickness,align=(bd.Align.CENTER,bd.Align.CENTER,bd.Align.MIN)).moved(bd.Location((0,0,z)))
+    for x,y in p['holeCentersMm']: result=result.cut(cyl(p['holeRadiusMm'],thickness,z,x,y))
+    return result
+def half(z, above):
+    face=BRepBuilderAPI_MakeFace(gp_Pln(gp_Pnt(0,0,z),gp_Dir(0,0,1))).Face()
+    return bd.Solid(BRepPrimAPI_MakeHalfSpace(face,gp_Pnt(0,0,z+(1 if above else -1))).Solid())
+def valid(shape):
+    return isinstance(shape,bd.Shape) and shape.is_valid and len(shape.solids())==1 and vol(shape)>VOL and len(shape.shells())==1 and BRep_Tool.IsClosed_s(shape.shells()[0].wrapped)
+def local_shapes(children, manifest, target):
+    rows=manifest['occurrences']; require(len(children)==len(rows) and [s.label for s in children]==[r['occurrenceId'] for r in rows], 'step_occurrences')
+    row=next((r for r in rows if r['occurrenceId']==target),None);require(row is not None,'target_missing')
+    transform=row['views']['normal']; location=bd.Location(tuple(transform['translationMm']),tuple(transform['rotationDeg']))
+    return {r['occurrenceId']:s.moved(location.inverse()) for r,s in zip(rows,children)},location
+
+def surfaces(shape, p):
+    holes=[]; seat_area=0.0
+    for face in shape.faces():
+        surface=BRepAdaptor_Surface(face.wrapped)
+        if surface.GetType()==GeomAbs_Cylinder:
+            c=surface.Cylinder(); a=c.Axis(); direction=a.Direction(); origin=a.Location()
+            if abs(abs(direction.Z())-1)>EPS:continue
+            bounds=face.bounding_box()
+            holes.append({'center':[origin.X(),origin.Y()], 'radius':c.Radius(), 'zMin':bounds.min.Z,'zMax':bounds.max.Z})
+        elif surface.GetType()==GeomAbs_Plane:
+            plane=surface.Plane(); n=plane.Axis().Direction()
+            if abs(abs(n.Z())-1)<=EPS and abs(plane.Location().Z())<=EPS: seat_area+=float(face.area)
+    measurements=[]
+    for center in p['holeCentersMm']:
+        found=[h for h in holes if math.dist(h['center'],center)<=EPS and abs(h['radius']-p['holeRadiusMm'])<=EPS and abs(h['zMin'])<=EPS and abs(h['zMax']-p['thicknessMm'])<=EPS]
+        require(len(found)==1,'interface_cylinder')
+        measurements.append(found[0])
+    expected=p['widthMm']*p['depthMm']-2*math.pi*p['holeRadiusMm']**2
+    require(abs(seat_area-expected)<=max(VOL,expected*1e-8),'interface_seat')
+    return {'holes':measurements,'seatAreaMm2':seat_area}
+
+def baseline(children, manifest, raw, step_bytes, api):
+    spec=proposal(raw); p=spec['plate'];target=spec['targetOccurrenceId'];base_id=spec['baseOccurrenceId']
+    require(manifest['mode']=='occurrence_assembly' and manifest['units']=='mm' and len(children)<=POLICY['maximumOccurrences'],'baseline_mode')
+    shapes,location=local_shapes(children,manifest,target)
+    require(base_id in shapes and all(r['geometryPrecision'] in ['custom_brep','envelope'] for r in manifest['occurrences']) and
+            all(r['geometryPrecision']=='custom_brep' for r in manifest['occurrences'] if r['occurrenceId'] in [target,base_id]), 'baseline_precision')
+    require(all(valid(s) for s in shapes.values()),'baseline_solids')
+    carrier,base=shapes[target],shapes[base_id]
+    carrier_error=diff(carrier,plate(p,p['thicknessMm']));base_error=diff(base,plate(p,spec['baseThicknessMm'],-spec['baseThicknessMm']))
+    require(carrier_error<=VOL and base_error<=VOL,'baseline_template')
+    dims=surfaces(carrier,p)
+    for identifier,s in shapes.items():
+        if identifier!=target:require(vol(s.intersect(half(EPS,True)))<=VOL,'baseline_insertion')
+    ids=list(shapes)
+    for i,a in enumerate(ids):
+        for b in ids[i+1:]:require(vol(shapes[a].intersect(shapes[b]))<=VOL,'baseline_collision')
+    row=next(r for r in manifest['occurrences'] if r['occurrenceId']==target)
+    evidence={'schema':'abelien.planar-attachment-baseline.v1','checkerVersion':VERSION,'policy':POLICY,
+      'proposal':spec,'sourceSha256':manifest['sourceSha256'],'modelStepSha256':api['digest'](step_bytes),
+      'assemblySha256':manifest['assemblySha256'],'occurrenceSetSha256':manifest['occurrenceSetSha256'],
+      'asModeledOnlyOccurrenceIds':[r['occurrenceId'] for r in manifest['occurrences'] if r['geometryPrecision']=='envelope'],
+      'targetGeometrySha256':row['geometrySha256'],'targetTransformSha256':row['transformSha256'],
+      'checks':{'carrierSymmetricDifferenceMm3':carrier_error,'baseSymmetricDifferenceMm3':base_error,'interfaces':dims,'staticCollision':'pass','planarInsertion':'pass'}}
+    evidence['attachmentSha256']=api['digest'](evidence)
+    return evidence
+
+def self_evidence(shape):
+    args=TopTools_ListOfShape();args.Append(shape.wrapped)
+    checker=BOPAlgo_CheckerSI();checker.SetArguments(args);checker.SetLevelOfCheck(9);checker.Perform()
+    require(not checker.HasErrors(),'self_check_failed')
+    ds=checker.DS()
+    count=ds.Interferences().Extent()
+    points=[]
+    for pair in ds.Interferences():
+        for index in pair.Indices():
+            points.extend([list(v.center()) for v in bd.Compound.cast(ds.Shape(index)).vertices()])
+    return {'count':count,'points':points}
+
+def self_check(shape):
+    evidence=self_evidence(shape);require(evidence['count']==0,'self_intersection')
+    return evidence['count']
+
+def mesh_solid(triangles, check_self=True):
+    array=np.asarray(triangles,dtype=np.float64)
+    require(array.ndim==3 and array.shape[1:]==(3,3) and 4<=len(array)<=POLICY['maximumTriangles'] and np.isfinite(array).all(),'mesh_shape')
+    # Exact welding only: no geometric repair/displacement. UV seams may duplicate positions.
+    vertices,indices=np.unique(array.reshape(-1,3),axis=0,return_inverse=True);faces=indices.reshape(-1,3)
+    edges=collections.defaultdict(list); links=collections.defaultdict(list)
+    for i,f in enumerate(faces):
+        require(len(set(map(int,f)))==3,'mesh_degenerate')
+        require(float(np.linalg.norm(np.cross(vertices[f[1]]-vertices[f[0]],vertices[f[2]]-vertices[f[0]])))>1e-14,'mesh_degenerate')
+        for k in range(3):
+            a,b=int(f[k]),int(f[(k+1)%3]); edges[tuple(sorted((a,b)))].append((i,a,b))
+            links[int(f[k])].append((int(f[(k+1)%3]),int(f[(k+2)%3])))
+    adjacency=[set() for _ in faces]
+    for es in edges.values():
+        require(len(es)==2 and es[0][1:]==es[1][1:][::-1],'mesh_nonmanifold')
+        adjacency[es[0][0]].add(es[1][0]);adjacency[es[1][0]].add(es[0][0])
+    def connected(adjacency,start):
+        seen={start};todo=[start]
+        while todo:
+            for n in adjacency[todo.pop()]:
+                if n not in seen:seen.add(n);todo.append(n)
+        return seen
+    require(len(connected(adjacency,0))==len(faces),'mesh_components')
+    for pairs in links.values():
+        ring=collections.defaultdict(set)
+        for a,b in pairs:ring[a].add(b);ring[b].add(a)
+        require(all(len(v)==2 for v in ring.values()) and len(connected(ring,next(iter(ring))))==len(ring),'mesh_vertex_nonmanifold')
+    signed=float(np.sum(np.einsum('ij,ij->i',array[:,0],np.cross(array[:,1],array[:,2])))/6)
+    require(signed>1e-12,'mesh_orientation')
+    sewing=BRepBuilderAPI_Sewing(EPS)
+    for tri in array:
+        wire=BRepBuilderAPI_MakePolygon(*[gp_Pnt(*map(float,p)) for p in tri],True).Wire()
+        sewing.Add(BRepBuilderAPI_MakeFace(wire).Face())
+    sewing.Perform();shells=[];it=TopExp_Explorer(sewing.SewedShape(),TopAbs_SHELL)
+    while it.More():shells.append(TopoDS.Shell_s(it.Current()));it.Next()
+    require(len(shells)==1 and sewing.NbFreeEdges()==0 and sewing.NbMultipleEdges()==0 and BRep_Tool.IsClosed_s(shells[0]),'mesh_open_shell')
+    wrapped=BRepBuilderAPI_MakeSolid(shells[0]).Solid();require(BRepLib.OrientClosedSolid_s(wrapped),'mesh_orientation')
+    solid=bd.Solid(wrapped);require(valid(solid),'mesh_invalid_solid')
+    if check_self:self_check(solid)
+    return solid
+
+def prepare_decoration(triangles,spec,candidate_bytes):
+    array=np.asarray(triangles,dtype=np.float64)
+    require(array.ndim==3 and array.shape[1:]==(3,3),'mesh_shape')
+    # glTF Y-up -> carrier Z-up. No inferred provider metres are used.
+    array=array[:,:,[0,2,1]]*np.array([1,-1,1])
+    low=array.min(axis=(0,1));high=array.max(axis=(0,1));span=high-low
+    require(np.isfinite(span).all() and np.all(span>1e-9),'mesh_span')
+    d=spec['decoration'];p=spec['plate'];j=spec['join'];scale=d['heightMm']/span[2]
+    require(span[0]*scale<=d['maximumWidthMm']+EPS and span[1]*scale<=d['maximumDepthMm']+EPS,'decoration_size')
+    crop=d['heightMm']*d['trimBottomFraction'];cut_z=p['thicknessMm']+j['gapMm']
+    translation=np.array([-(low[0]+high[0])/2*scale,-(low[1]+high[1])/2*scale,cut_z-crop-low[2]*scale])
+    placed=array*scale+translation
+    initial=mesh_solid(placed,check_self=False)
+    placement={'method':'declared_design_height','sourceUnits':'unknown','scaleMmPerSourceUnit':scale,
+       'translationMm':translation.tolist(),'trimBottomMm':crop,'cutZMm':cut_z,'heightBeforeTrimMm':d['heightMm']}
+    derived,derived_bytes,repair=REPAIR['derive'](placed,candidate_bytes,self_evidence(initial),placement,POLICY,mesh_solid,self_evidence)
+    solid=initial if repair['status']=='not_needed' else mesh_solid(derived)
+    decoration=as_shape(solid.intersect(half(cut_z,True)))
+    require(valid(decoration),'trim_disconnected')
+    connector=cyl(j['radiusMm'],j['embedMm']*2+j['gapMm'],p['thicknessMm']-j['embedMm'])
+    witness=cyl(j['radiusMm'],j['embedMm'],cut_z)
+    require(vol(witness.cut(decoration))<=VOL,'join_not_embedded')
+    return decoration,connector,placement,derived_bytes,repair
+
+def source_read(request,api):
+    encoded=request['baselineStep'];body=base64.b64decode(encoded,validate=True)
+    require(api['digest'](body)==request['attachment']['modelStepSha256'],'baseline_step_hash')
+    path=api['root']/'baseline.step';path.write_bytes(body);model=bd.import_step(str(path));children=list(model.children)
+    actual=baseline(children,request['baselineAssembly'],request['attachment']['proposal'],body,api)
+    require(actual==request['attachment'],'attachment_changed')
+    return body,children
+
+def construct(request,api):
+    body,children=source_read(request,api);original=request['baselineAssembly'];attachment=request['attachment'];spec=attachment['proposal'];target=spec['targetOccurrenceId']
+    local,location=local_shapes(children,original,target);decoration,connector,placement,derived_bytes,repair=prepare_decoration(request['triangles'],spec,base64.b64decode(request['candidateGlb'],validate=True))
+    result=local[target].fuse(decoration,connector);require(valid(result),'union_not_single_solid')
+    self_check(result)
+    newchildren=[]
+    for child in children:
+        replacement=result.moved(location) if child.label==target else child
+        replacement.label=child.label;newchildren.append(replacement)
+    model=bd.Compound(children=newchildren);model.label='assembly';bd.export_step(model,str(api['step']))
+    recipe={'schema':'abelien.component-engineering-recipe.v1','checkerVersion':VERSION,'policy':POLICY,
+      'baseline':{k:attachment[k] for k in ['sourceSha256','modelStepSha256','assemblySha256','occurrenceSetSha256','attachmentSha256','targetGeometrySha256','targetTransformSha256']},
+      'targetOccurrenceId':target,'candidateGlbSha256':request['candidateGlbSha256'],'placement':placement,
+      'decorationGlbSha256':api['digest'](derived_bytes),'repair':repair}
+    return {'step':api['encode'](api['step']),'recipe':recipe,'decorationGlb':base64.b64encode(derived_bytes).decode()}
+
+def verify_final(request,api):
+    baseline_bytes,previous=source_read(request,api);original=request['baselineAssembly'];spec=request['attachment']['proposal'];target=spec['targetOccurrenceId'];base_id=spec['baseOccurrenceId']
+    final_bytes=base64.b64decode(request['step'],validate=True);api['step'].write_bytes(final_bytes);model=bd.import_step(str(api['step']));children=list(model.children)
+    before,location=local_shapes(previous,original,target);after,_=local_shapes(children,original,target)
+    require(set(before)==set(after) and all(valid(s) for s in after.values()),'readback_solids')
+    decoration,connector,placement,derived_bytes,repair=prepare_decoration(request['triangles'],spec,base64.b64decode(request['candidateGlb'],validate=True))
+    expected_recipe={'schema':'abelien.component-engineering-recipe.v1','checkerVersion':VERSION,'policy':POLICY,
+      'baseline':{k:request['attachment'][k] for k in ['sourceSha256','modelStepSha256','assemblySha256','occurrenceSetSha256','attachmentSha256','targetGeometrySha256','targetTransformSha256']},
+      'targetOccurrenceId':target,'candidateGlbSha256':request['candidateGlbSha256'],'placement':placement,
+      'decorationGlbSha256':api['digest'](derived_bytes),'repair':repair}
+    require(api['digest'](base64.b64decode(request['candidateGlb'],validate=True))==request['candidateGlbSha256'],'candidate_hash')
+    require(expected_recipe==request['recipe'] and derived_bytes==base64.b64decode(request['decorationGlb'],validate=True),'recipe_changed')
+    expected=before[target].fuse(decoration,connector);require(diff(after[target],expected)<=VOL,'composition_changed')
+    result=after[target];carrier=before[target];p=spec['plate'];j=spec['join'];clearance=spec['clearanceMm']
+    lost=vol(carrier.cut(result));require(lost<=VOL,'carrier_changed')
+    surface_evidence=surfaces(result,p)
+    protected_errors=[];blocked=[]
+    zmax=p['thicknessMm']+j['gapMm']+spec['decoration']['heightMm']+1
+    for x,y in p['holeCentersMm']:
+        region=cyl(p['holeRadiusMm']+clearance,zmax+1,-1,x,y)
+        error=diff(carrier.intersect(region),result.intersect(region));require(error<=VOL,'protected_interface_changed');protected_errors.append(error)
+        keepout=cyl(p['holeRadiusMm']-EPS,zmax+spec['baseThicknessMm'],-spec['baseThicknessMm'],x,y)
+        overlap=vol(result.intersect(keepout));require(overlap<=VOL,'hole_access_blocked');blocked.append(overlap)
+    seat=half(EPS,False);seat_error=diff(carrier.intersect(seat),result.intersect(seat));require(seat_error<=VOL,'seat_changed')
+    witness=connector;missing=vol(witness.cut(result));require(missing<=VOL,'join_discontinuous')
+    carrier_end=cyl(j['radiusMm'],j['embedMm'],p['thicknessMm']-j['embedMm'])
+    decorative_end=cyl(j['radiusMm'],j['embedMm'],placement['cutZMm'])
+    require(vol(carrier_end.cut(carrier))<=VOL and vol(decorative_end.cut(decoration))<=VOL,'join_embedding')
+    preserved=[];overlaps=[];distances=[];added=as_shape(result.cut(carrier))
+    for identifier,shape in after.items():
+        if identifier==target:continue
+        delta=diff(before[identifier],shape);require(delta<=VOL,'preserved_occurrence_changed');preserved.append({'occurrenceId':identifier,'symmetricDifferenceMm3':delta})
+        overlap=vol(result.intersect(shape));require(overlap<=VOL,'static_collision');overlaps.append({'occurrenceId':identifier,'overlapMm3':overlap})
+        require(vol(shape.intersect(half(EPS,True)))<=VOL,'insertion_fixed_above_plane')
+        distance=float(added.distance_to(shape));require(distance+EPS>=clearance,'clearance');distances.append({'occurrenceId':identifier,'distanceMm':distance})
+    require(vol(result.intersect(half(-EPS,False)))<=VOL,'insertion_target_below_plane')
+    intersections=self_check(result)
+    measurements=[{'validatedAttachmentSha256':request['attachment']['attachmentSha256']},{'solidCount':1,'shellCount':1},
+      {'interferenceCount':intersections},{'lostVolumeMm3':lost},surface_evidence,
+      {'symmetricDifferenceMm3':protected_errors,'holeObstructionMm3':blocked,'seatDifferenceMm3':seat_error},
+      {'missingWitnessMm3':missing,'radiusMm':j['radiusMm'],'sectionAreaMm2':math.pi*j['radiusMm']**2,'embedMm':j['embedMm']},
+      {'pairs':overlaps},{'minimumRequiredMm':clearance,'pairs':distances},{'method':'brep_separating_halfspaces','outwardLocal':[0,0,1]},
+      {'occurrences':preserved},{'compositionSymmetricDifferenceMm3':diff(result,expected),'solidCount':len(children)}]
+    checks=[{'id':name,'status':'pass','method':'occt_brep_independent_readback','measured':value} for name,value in zip(CHECK_IDS,measurements)]
+    recipe=request['recipe'];recipe_bytes=api['json'].dumps(recipe,separators=(',',':'),ensure_ascii=False).encode();recipe_sha=api['digest'](recipe_bytes)
+    assembly=copy.deepcopy(original)
+    for k in ['assemblySha256','occurrenceSetSha256','artifacts','views']:assembly.pop(k,None)
+    assembly['sourceSha256']=recipe_sha;assembly['revision']=None
+    for row in assembly['occurrences']:
+        if row['occurrenceId']==target:
+            row['geometrySha256']=api['shape_digest'](result);row['source']={'kind':'generated_custom','sha256':recipe_sha};row['lineage']=None
+    display=bd.Compound(children=children);display.label='assembly-root';glb=api['root']/'model.glb'
+    require(bd.export_gltf(display,str(glb),binary=True,linear_deflection=.05),'glb_export')
+    raw=api['apply_materials_to_glb'](glb.read_bytes(),assembly);glb.write_bytes(raw)
+    api['validate_occurrence_nodes'](api['gltf_document'](raw),assembly)
+    # Renderer functions depend on trusted globals initialized by the caller.
+    images=api['render_assembly_views'](api['root'],children,assembly,.3)
+    manifest=api['final_manifest'](assembly,final_bytes,raw,images)
+    report={'schema':'abelien.component-engineering-fit-report.v1','checkerVersion':VERSION,'policy':POLICY,
+      'representation':'analytic_carrier_faceted_decoration','scope':'planar_two_hole_solid_decoration.v1',
+      'fitStatus':'pass','adoptionEligible':True,'baseline':recipe['baseline'],'targetOccurrenceId':target,
+      'asModeledOnlyOccurrenceIds':request['attachment']['asModeledOnlyOccurrenceIds'],'repair':repair,'decorationGlbSha256':api['digest'](derived_bytes),
+      'candidateGlbSha256':request['candidateGlbSha256'],'recipeSha256':recipe_sha,'modelStepSha256':api['digest'](final_bytes),
+      'modelGlbSha256':api['digest'](raw),'assemblySha256':manifest['assemblySha256'],
+      'subject':{k:manifest[k] for k in ['sourceSha256','assemblySha256','occurrenceSetSha256']} | {'modelStepSha256':api['digest'](final_bytes),'modelGlbSha256':api['digest'](raw)},'checks':checks,
+      'notChecked':NOT_CHECKED,'decorationShellWall':{'status':'not_applicable','reason':'filled_decoration_no_cavity'}}
+    artifacts={'decoration.glb':base64.b64encode(derived_bytes).decode(),'model.step':base64.b64encode(final_bytes).decode(),'model.glb':base64.b64encode(raw).decode(),'recipe.json':base64.b64encode(recipe_bytes).decode(),
+      'fit.json':base64.b64encode(api['json'].dumps(report,separators=(',',':')).encode()).decode(),
+      'assembly.json':base64.b64encode(api['json'].dumps(manifest,separators=(',',':')).encode()).decode()}
+    artifacts.update({f'{name}.png':base64.b64encode(body).decode() for name,body in images.items()})
+    return {'artifacts':artifacts}

package/skills/abelien-structure/worker/identity.mjs

@@ -0,0 +1,98 @@
+/** Worker-owned capability identity, including opt-in actual-runtime API manifest. No request field participates. */
+import fs from 'node:fs';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {fileURLToPath} from 'node:url';
+import {execFileSync} from 'node:child_process';
+import {STRUCTURE_SOURCE_CONTRACT,sourceApiDigest,sourceApiReference} from './source-contract.mjs';
+
+export const STRUCTURE_PROTOCOL_VERSION='abelien.structure-worker.v3';
+export const STRUCTURE_CHECKER_VERSION='abelien.structure-checker.v2';
+const here=path.dirname(fileURLToPath(import.meta.url));
+const checker=path.join(here,'cad.py');
+const packagePrefixes=['build123d-','matplotlib-','numpy-','cadquery_ocp_novtk-','cadquery_ocp_proxy-'];
+
+const inside=(parent,child)=>child===parent||child.startsWith(`${parent}${path.sep}`);
+const add=(digest,label,bytes)=>{
+  const name=Buffer.from(label),body=Buffer.isBuffer(bytes)?bytes:Buffer.from(bytes);
+  const size=Buffer.allocUnsafe(8);size.writeBigUInt64BE(BigInt(body.length));
+  digest.update(name).update(Buffer.from([0])).update(size).update(body);
+};
+
+function nativeMaterials(runtime){
+  const root=fs.realpathSync(runtime),venv=path.join(root,'venv');
+  const python=fs.realpathSync(path.join(venv,'bin/python3'));
+  if(!inside(path.join(root,'python'),python))throw new Error('structure_runtime_identity_invalid');
+  const lib=path.join(venv,'lib'),pythonDirs=fs.readdirSync(lib).filter(name=>/^python3\.\d+$/.test(name));
+  if(pythonDirs.length!==1)throw new Error('structure_runtime_identity_invalid');
+  const site=path.join(lib,pythonDirs[0],'site-packages'),entries=fs.readdirSync(site);
+  const files=[path.join(venv,'pyvenv.cfg'),python];
+  for(const prefix of packagePrefixes){
+    const matches=entries.filter(name=>name.startsWith(prefix)&&name.endsWith('.dist-info'));
+    if(matches.length!==1)throw new Error('structure_runtime_identity_invalid');
+    files.push(path.join(site,matches[0],'METADATA'),path.join(site,matches[0],'RECORD'));
+  }
+  return files.map(file=>{
+    const real=fs.realpathSync(file);if(!inside(root,real))throw new Error('structure_runtime_identity_invalid');
+    const bytes=fs.readFileSync(real);if(!bytes.length||bytes.length>64*1024*1024)throw new Error('structure_runtime_identity_invalid');
+    return [path.relative(root,real),bytes];
+  });
+}
+
+export function createWorkerIdentity(config){
+  if(!config||!['docker','native-macos'].includes(config.backend))throw new Error('structure_runtime_identity_invalid');
+  const digest=createHash('sha256');
+  add(digest,'protocol',STRUCTURE_PROTOCOL_VERSION);add(digest,'checkerVersion',STRUCTURE_CHECKER_VERSION);
+  add(digest,'validator/materials.mjs',fs.readFileSync(path.join(here,'materials.mjs')));
+  for(const name of ['engineering-fit.mjs','engineering-policy.json','assembly-validation.mjs','manifest-digest.mjs','component-fit-glb.mjs'])add(digest,`validator/${name}`,fs.readFileSync(path.join(here,name)));
+  add(digest,'validator/inspection-geometry.mjs',fs.readFileSync(path.join(here,'inspection-geometry.mjs')));
+  add(digest,'validator/representation.mjs',fs.readFileSync(path.join(here,'representation.mjs')));
+  add(digest,'contract/source-contract.mjs',fs.readFileSync(path.join(here,'source-contract.mjs')));
+  for(const name of ['component-target-image.mjs','component-target-render.py'])add(digest,`renderer/${name}`,fs.readFileSync(path.join(here,name)));
+  if(config.sourceSymbolPrecheck){
+    add(digest,'contract/source-api',sourceApiDigest(config.sourceApi));
+    if(config.backend==='native-macos'&&createWorkerSourceContract(config).runtime.build123dVersion!==config.sourceApi.build123dVersion)
+      throw new Error('structure_runtime_identity_invalid');
+  }
+  if(config.backend==='native-macos'){
+    add(digest,'checker/cad.py',fs.readFileSync(checker));
+    add(digest,'checker/abelien_cad.py',fs.readFileSync(path.join(here,'abelien_cad.py')));
+    add(digest,'checker/source_call_stats.py',fs.readFileSync(path.join(here,'source_call_stats.py')));
+    add(digest,'checker/engineering.py',fs.readFileSync(path.join(here,'engineering.py')));
+    add(digest,'checker/engineering-repair.py',fs.readFileSync(path.join(here,'engineering-repair.py')));
+    for(const [name,bytes] of nativeMaterials(config.runtime))add(digest,`runtime/${name}`,bytes);
+  }
+  else{
+    if(typeof config.imageId!=='string'||!/^sha256:[a-f0-9]{64}$/.test(config.imageId))throw new Error('structure_runtime_identity_invalid');
+    add(digest,'runtime/docker-image-id',config.imageId);
+  }
+  return {ok:true,protocolVersion:STRUCTURE_PROTOCOL_VERSION,runtimeDigest:digest.digest('hex'),checkerVersion:STRUCTURE_CHECKER_VERSION};
+}
+
+/** Native version comes from the same installed METADATA bound into runtimeDigest; Docker remains image-pinned. */
+export function createWorkerSourceContract(config) {
+  let build123dVersion=null;
+  if(config.backend==='native-macos'){
+    const metadata=nativeMaterials(config.runtime).find(([name])=>/build123d-[^/]+\.dist-info\/METADATA$/.test(name));
+    build123dVersion=metadata?.[1].toString('utf8').match(/^Version: ([A-Za-z0-9.+-]+)$/m)?.[1];
+    if(!build123dVersion)throw new Error('structure_runtime_identity_invalid');
+  }else if(config.backend!=='docker')throw new Error('structure_runtime_identity_invalid');
+  if(config.sourceSymbolPrecheck){
+    const reference=sourceApiReference(config.sourceApi);
+    if(build123dVersion!==null&&reference.build123dVersion!==build123dVersion)throw new Error('structure_runtime_identity_invalid');
+    return {...STRUCTURE_SOURCE_CONTRACT,apiReference:reference,runtime:{backend:config.backend,build123dVersion:reference.build123dVersion,
+      versionEvidence:'isolated_installed_module',sourceSymbolPrecheck:true,sourceApiSha256:reference.manifestSha256}};
+  }
+  return {...STRUCTURE_SOURCE_CONTRACT,runtime:{backend:config.backend,build123dVersion,
+    versionEvidence:config.backend==='native-macos'?'installed_metadata':'immutable_image_id'}};
+}
+
+/** Resolve a mutable operator-facing tag once, then use the immutable image ID for both identity and every job. */
+export function resolveDockerImage(image,inspect=execFileSync){
+  if(typeof image!=='string'||!image.trim()||image.length>300)throw new Error('structure_runtime_identity_invalid');
+  try{
+    const id=inspect('docker',['image','inspect','--format','{{.Id}}',image],{encoding:'utf8',timeout:10000,maxBuffer:4096}).trim();
+    if(!/^sha256:[a-f0-9]{64}$/.test(id))throw new Error();
+    return id;
+  }catch{throw new Error('structure_runtime_identity_invalid');}
+}

package/skills/abelien-structure/worker/inspection-geometry.mjs

@@ -0,0 +1,71 @@
+/** Validate bounded inspection-only BRep witnesses; never add product occurrences. */
+import {createHash} from 'node:crypto';
+
+const HEX=/^[a-f0-9]{64}$/,ID=/^[a-z0-9][a-z0-9_-]{0,127}$/;
+const fail=()=>{throw new Error('invalid_inspection_geometry');};
+const keys=(value,expected)=>value&&typeof value==='object'&&!Array.isArray(value)&&Object.keys(value).length===expected.length&&expected.every(key=>Object.hasOwn(value,key));
+const finite=value=>typeof value==='number'&&Number.isFinite(value)&&value>=0;
+const hash=value=>createHash('sha256').update(value).digest('hex');
+export const INSPECTION_GEOMETRY_TOLERANCE_MM3=1e-6;
+export const INSPECTION_GEOMETRY_MAX_BYTES=8*1024*1024;
+
+export function validateInspectionGeometryPlan(value,assembly){
+  const regions=new Map();
+  if(value===undefined)return regions;
+  if(!keys(value,['schema','sourceSha256','regions','shells'])||value.schema!=='abelien.structure-inspection-geometry.v1'||value.sourceSha256!==assembly.sourceSha256||!HEX.test(value.sourceSha256)||
+    !Array.isArray(value.regions)||value.regions.length<2||value.regions.length>128||!Array.isArray(value.shells)||!value.shells.length||value.shells.length>32)fail();
+  const owners=new Map(assembly.occurrences.map(item=>[item.occurrenceId,item]));
+  for(const region of value.regions){
+    if(!keys(region,['regionId','kind','ownerOccurrenceId','brepSha256'])||!ID.test(region.regionId??'')||owners.has(region.regionId)||regions.has(region.regionId)||
+      !['outer','cavity','opening'].includes(region.kind)||!owners.has(region.ownerOccurrenceId)||!HEX.test(region.brepSha256??''))fail();
+    regions.set(region.regionId,region);
+  }
+  const used=new Set(),shells=new Set();
+  for(const shell of value.shells){
+    if(!keys(shell,['occurrenceId','geometrySha256','transformSha256','outerRegionId','cavityRegionId','openingRegionIds'])||shells.has(shell.occurrenceId)||
+      !Array.isArray(shell.openingRegionIds)||shell.openingRegionIds.length>32)fail();
+    const owner=owners.get(shell.occurrenceId);
+    if(!owner||owner.geometryPrecision!=='custom_brep'||!HEX.test(shell.geometrySha256??'')||!HEX.test(shell.transformSha256??'')||owner.geometrySha256!==shell.geometrySha256||owner.transformSha256!==shell.transformSha256)fail();
+    shells.add(shell.occurrenceId);
+    for(const [id,kind] of [[shell.outerRegionId,'outer'],[shell.cavityRegionId,'cavity'],...shell.openingRegionIds.map(id=>[id,'opening'])]){
+      const region=regions.get(id);
+      if(!region||used.has(id)||region.kind!==kind||region.ownerOccurrenceId!==shell.occurrenceId)fail();
+      used.add(id);
+    }
+  }
+  if(used.size!==regions.size)fail();
+  return regions;
+}
+
+export function validateInspectionGeometryTransport(plan,assembly,breps){
+  const regions=validateInspectionGeometryPlan(plan.inspectionGeometry,assembly);
+  if(!regions.size){if(breps!==undefined)fail();return;}
+  if(!keys(breps,[...regions.keys()]))fail();
+  let bytes=0;
+  for(const [id,region] of regions){
+    const encoded=breps[id];
+    if(typeof encoded!=='string'||encoded.length>12*1024*1024||!/^[A-Za-z0-9+/]+={0,2}$/.test(encoded))fail();
+    const body=Buffer.from(encoded,'base64');bytes+=body.length;
+    if(!body.length||body.toString('base64')!==encoded||bytes>INSPECTION_GEOMETRY_MAX_BYTES||hash(body)!==region.brepSha256)fail();
+  }
+}
+
+export function validateInspectionGeometryEvidence(evidence,metadata,assembly){
+  validateInspectionGeometryPlan(metadata,assembly);
+  if(metadata===undefined){if(evidence!==undefined)fail();return;}
+  if(!keys(evidence,['schema','sourceSha256','assemblySha256','inspectionPlanSha256','plan','status','method','toleranceMm3','checks'])||
+    evidence.schema!=='abelien.structure-inspection-geometry-evidence.v1'||evidence.sourceSha256!==assembly.sourceSha256||evidence.assemblySha256!==assembly.assemblySha256||
+    evidence.inspectionPlanSha256!==assembly.inspectionPlanSha256||JSON.stringify(evidence.plan)!==JSON.stringify(metadata)||evidence.status!=='pass'||
+    evidence.method!=='occt_brep_boolean_reconstruction'||evidence.toleranceMm3!==INSPECTION_GEOMETRY_TOLERANCE_MM3||!Array.isArray(evidence.checks)||evidence.checks.length!==metadata.shells.length)fail();
+  const epsilon=INSPECTION_GEOMETRY_TOLERANCE_MM3;
+  evidence.checks.forEach((check,index)=>{
+    const shell=metadata.shells[index];
+    if(!keys(check,['shellOccurrenceId','cavityOutsideMm3','minimumWallMm','shellSymmetricDifferenceMm3','openings'])||check.shellOccurrenceId!==shell.occurrenceId||
+      !finite(check.cavityOutsideMm3)||check.cavityOutsideMm3>epsilon||!finite(check.minimumWallMm)||check.minimumWallMm<=epsilon||
+      !finite(check.shellSymmetricDifferenceMm3)||check.shellSymmetricDifferenceMm3>epsilon||!Array.isArray(check.openings)||check.openings.length!==shell.openingRegionIds.length)fail();
+    check.openings.forEach((opening,openingIndex)=>{
+      if(!keys(opening,['regionId','cavityOverlapMm3','outsideOuterVolumeMm3','uniqueWallCutVolumeMm3'])||opening.regionId!==shell.openingRegionIds[openingIndex]||
+        ['cavityOverlapMm3','outsideOuterVolumeMm3','uniqueWallCutVolumeMm3'].some(key=>!finite(opening[key])||opening[key]<=epsilon))fail();
+    });
+  });
+}