abelien-harness 0.4.0 → 0.6.0

package/skills/abelien-structure/worker/cli-adapter.mjs

@@ -0,0 +1,207 @@
+/** Host-only CLI adapter for `ab capability run structure.*`. Files stay under the host IO root; Worker credentials come only from host env. */
+import fs from 'node:fs';
+import path from 'node:path';
+import {createHash} from 'node:crypto';
+import {ENGINEERING_VERSION,ENGINEERING_CHECKS,ENGINEERING_NOT_CHECKED,ENGINEERING_ARTIFACT_TYPES,ENGINEERING_MAX_BODY_BYTES,ENGINEERING_POLICY,
+  normalizeEngineeringFitRequest,validateAttachmentBaseline,validateEngineeringArtifacts,validateEngineeringStoredArtifacts} from './engineering-fit.mjs';
+import {fitAppearanceComponent,verifyAppearanceComponentFit,deriveTargetLocalPlacement} from './component-fit.mjs';
+import {MAX_GLB_BYTES} from './component-fit-glb.mjs';
+
+const MAX_STEP_BYTES=24*1024*1024,MAX_JSON_BYTES=128*1024,MAX_PNG_BYTES=4*1024*1024,ERROR_BODY_BYTES=4096,TARGET_ERROR_BODY_BYTES=128*1024;
+const hex=/^[a-f0-9]{64}$/,reasonPattern=/^[a-z][a-z0-9_]{0,63}$/;
+const sha256=bytes=>createHash('sha256').update(bytes).digest('hex');
+const fail=(code,message,details)=>Object.assign(new Error(message),{code},details===undefined?{}:{details});
+const object=(value,name)=>{if(!value||typeof value!=='object'||Array.isArray(value))throw fail('STRUCTURE_INPUT_INVALID',`${name} must be an object`);return value;};
+const reason=value=>typeof value==='string'&&reasonPattern.test(value)?value:'invalid';
+
+/** Worker validators throw plain Errors; keep their exact code/message so the host maps them as before. */
+async function guarded(run){
+  try{return await run();}
+  catch(error){
+    if(/^STRUCTURE_[A-Z_]+$/.test(error?.code??''))throw error;
+    throw fail('STRUCTURE_REJECTED','structure input rejected',{code:reason(error?.code??error?.message),message:reason(error?.message)});
+  }
+}
+
+function ioRoot(env){
+  const root=env.ABELIEN_STRUCTURE_IO_ROOT;
+  if(typeof root!=='string'||!path.isAbsolute(root))throw fail('STRUCTURE_HOST_ENV_MISSING','ABELIEN_STRUCTURE_IO_ROOT must be an absolute directory set by the host');
+  let real;try{real=fs.realpathSync(root);}catch{real=null;}
+  if(!real||!fs.statSync(real).isDirectory())throw fail('STRUCTURE_HOST_ENV_MISSING','ABELIEN_STRUCTURE_IO_ROOT must be an existing directory');
+  return real;
+}
+const within=(root,real)=>real.startsWith(root+path.sep);
+
+function readInput(root,file,maximum,name){
+  if(typeof file!=='string'||!path.isAbsolute(file))throw fail('STRUCTURE_PATH_INVALID',`${name} must be an absolute path`);
+  const stat=fs.lstatSync(file,{throwIfNoEntry:false});
+  if(!stat?.isFile())throw fail('STRUCTURE_PATH_INVALID',`${name} must be a regular file, not a link`,{name});
+  const real=fs.realpathSync(file);
+  if(!within(root,real))throw fail('STRUCTURE_PATH_INVALID',`${name} is outside the host IO root`,{name});
+  if(stat.size>maximum)throw fail('STRUCTURE_PATH_INVALID',`${name} exceeds ${maximum} bytes`,{name,maximum});
+  return fs.readFileSync(real);
+}
+
+function writeOutput(root,directory,name,bytes){
+  if(typeof directory!=='string'||!path.isAbsolute(directory))throw fail('STRUCTURE_PATH_INVALID','outDir must be an absolute path');
+  const stat=fs.lstatSync(directory,{throwIfNoEntry:false});
+  if(!stat?.isDirectory())throw fail('STRUCTURE_PATH_INVALID','outDir must be an existing directory, not a link');
+  const real=fs.realpathSync(directory);
+  if(real!==root&&!within(root,real))throw fail('STRUCTURE_PATH_INVALID','outDir is outside the host IO root');
+  const file=path.join(real,name);
+  try{fs.writeFileSync(file,bytes,{flag:'wx',mode:0o600});}
+  catch{throw fail('STRUCTURE_PATH_INVALID','output file already exists or cannot be written',{name});}
+  return {path:file,sha256:sha256(bytes),bytes:bytes.length};
+}
+
+const readFiles=(root,files)=>new Map(Object.entries(object(files,'files')).map(([name,file])=>{
+  if(!Object.hasOwn(ENGINEERING_ARTIFACT_TYPES,name))throw fail('STRUCTURE_INPUT_INVALID','files contains an unknown artifact name',{name:reason(name)});
+  return [name,readInput(root,file,name.endsWith('.png')?MAX_PNG_BYTES:name.endsWith('.json')?MAX_JSON_BYTES:MAX_STEP_BYTES,`files.${name}`)];
+}));
+
+export function engineeringContract(){
+  return {version:ENGINEERING_VERSION,checks:[...ENGINEERING_CHECKS],notChecked:[...ENGINEERING_NOT_CHECKED],
+    artifactTypes:{...ENGINEERING_ARTIFACT_TYPES},maxBodyBytes:ENGINEERING_MAX_BODY_BYTES,policy:structuredClone(ENGINEERING_POLICY)};
+}
+
+export function engineeringRequestCheck({input}){
+  return guarded(()=>{const normalized=normalizeEngineeringFitRequest(object(input,'input').request);
+    return {request:normalized.input,triangleCount:normalized.triangles.length};});
+}
+
+export function attachmentBaselineCheck({input,env}){
+  const root=ioRoot(env),value=object(input,'input');
+  return guarded(()=>({attachment:validateAttachmentBaseline(value.attachment,value.assembly,readInput(root,value.stepPath,MAX_STEP_BYTES,'stepPath'))}));
+}
+
+export function engineeringArtifactsCheck({input,env}){
+  const root=ioRoot(env),value=object(input,'input'),expected=object(value.expected,'expected');
+  if(typeof value.stored!=='boolean')throw fail('STRUCTURE_INPUT_INVALID','stored must be a boolean');
+  return guarded(()=>{const files=readFiles(root,value.files);
+    return value.stored?validateEngineeringStoredArtifacts(files,expected):validateEngineeringArtifacts(files,expected);});
+}
+
+export function componentFit({input,env}){
+  const root=ioRoot(env),value=object(input,'input');
+  return guarded(()=>{
+    const fit=fitAppearanceComponent({request:value.request,trusted:value.trusted,
+      baselineGlb:readInput(root,value.baselineGlbPath,MAX_GLB_BYTES,'baselineGlbPath'),candidateGlb:readInput(root,value.candidateGlbPath,MAX_GLB_BYTES,'candidateGlbPath')});
+    return {report:fit.report,assemblyGlb:writeOutput(root,value.outDir,'assembly.glb',fit.assemblyGlb)};
+  });
+}
+
+export function componentFitVerify({input,env}){
+  const root=ioRoot(env),value=object(input,'input');
+  return guarded(()=>({verified:verifyAppearanceComponentFit({request:value.request,trusted:value.trusted,report:value.report,
+    baselineGlb:readInput(root,value.baselineGlbPath,MAX_GLB_BYTES,'baselineGlbPath'),candidateGlb:readInput(root,value.candidateGlbPath,MAX_GLB_BYTES,'candidateGlbPath'),
+    assemblyGlb:readInput(root,value.assemblyGlbPath,MAX_GLB_BYTES,'assemblyGlbPath')})}));
+}
+
+export function targetPlacement({input,env}){
+  const root=ioRoot(env),value=object(input,'input');
+  return guarded(()=>({candidateToTarget:deriveTargetLocalPlacement({baseline:value.baseline,baselineGlb:readInput(root,value.baselineGlbPath,MAX_GLB_BYTES,'baselineGlbPath')})}));
+}
+
+function workerConfig(env,input){
+  const origin=env.AGENT_STRUCTURE_ORIGIN,token=env.AGENT_STRUCTURE_TOKEN;
+  let url=null;try{url=new URL(origin);}catch{/* reported below */}
+  const loopback=['127.0.0.1','localhost','[::1]'].includes(url?.hostname);
+  if(!url||url.origin!==origin||!(url.protocol==='https:'||(url.protocol==='http:'&&loopback)))
+    throw fail('STRUCTURE_HOST_ENV_MISSING','AGENT_STRUCTURE_ORIGIN must be an https origin (http only on loopback) set by the host');
+  if(typeof token!=='string'||token.length<32)throw fail('STRUCTURE_HOST_ENV_MISSING','AGENT_STRUCTURE_TOKEN must be set by the host');
+  const timeoutMs=input.timeoutMs??30000;
+  if(!Number.isSafeInteger(timeoutMs)||timeoutMs<1000||timeoutMs>300000)throw fail('STRUCTURE_INPUT_INVALID','timeoutMs must be an integer from 1000 to 300000');
+  return {origin,token,timeoutMs};
+}
+
+/** One mapping from Worker HTTP outcomes to host reasons; noEffect is true only where the Worker provably did nothing. */
+const workerFailure=(why,noEffect,diagnostic)=>fail('STRUCTURE_WORKER',why,{reason:why,noEffect,...(diagnostic===undefined?{}:{diagnostic})});
+
+async function bounded(response,maximum){
+  if(!response.body||response.redirected)throw workerFailure('worker_unavailable',false);
+  const reader=response.body.getReader(),chunks=[];let total=0;
+  try{
+    for(;;){const {done,value}=await reader.read();if(done)break;
+      total+=value.byteLength;if(total>maximum)throw workerFailure('worker_unavailable',false);chunks.push(value);}
+  }finally{void reader.cancel().catch(()=>undefined);reader.releaseLock();}
+  return Buffer.concat(chunks,total);
+}
+
+async function call(worker,fetchImpl,{route,scope='0'.repeat(64),body,errorBytes=ERROR_BODY_BYTES}){
+  let response;
+  try{
+    response=await fetchImpl(`${worker.origin}${route}`,{method:body===undefined?'GET':'POST',redirect:'error',cache:'no-store',
+      headers:{authorization:`Bearer ${worker.token}`,'x-structure-scope':scope,...(body===undefined?{}:{'content-type':'application/json'})},
+      ...(body===undefined?{}:{body:JSON.stringify(body)}),signal:AbortSignal.timeout(worker.timeoutMs)});
+  }catch{throw workerFailure('worker_result_unknown',false);}
+  if(response.status===404)throw workerFailure('not_found',true);
+  if([400,429,503].includes(response.status)){
+    let why=response.status===429?'queue_full':response.status===503?'worker_unavailable':'invalid_input',diagnostic;
+    try{
+      const value=JSON.parse((await bounded(response,errorBytes)).toString('utf8'));
+      if(typeof value.error==='string'&&/^[a-z][a-z0-9_]{0,47}$/.test(value.error))why=value.error;
+      if(value.diagnostic!==undefined)diagnostic=value.diagnostic;
+    }catch{/* status remains authoritative */}
+    throw workerFailure(why,true,diagnostic);
+  }
+  if(!response.ok)throw workerFailure(response.status===409?'upstream_key_conflict':'worker_unavailable',false);
+  return response;
+}
+const json=async response=>JSON.parse((await bounded(response,262_144)).toString('utf8'));
+const scopeOf=value=>{if(!hex.test(value??''))throw fail('STRUCTURE_INPUT_INVALID','scope must be 64 lowercase hex characters');return value;};
+const jobIdOf=value=>{if(typeof value!=='string'||!/^[a-f0-9-]{1,64}$/.test(value))throw fail('STRUCTURE_INPUT_INVALID','jobId is invalid');return value;};
+
+export async function workerHealth({input,env,fetchImpl}){
+  return json(await call(workerConfig(env,object(input,'input')),fetchImpl,{route:'/health'}));
+}
+
+export async function sourceContract({input,env,fetchImpl}){
+  return json(await call(workerConfig(env,object(input,'input')),fetchImpl,{route:'/source-contract'}));
+}
+
+export async function jobSubmit({input,env,fetchImpl}){
+  const value=object(input,'input'),worker=workerConfig(env,value);
+  return json(await call(worker,fetchImpl,{route:'/jobs',scope:scopeOf(value.scope),body:object(value.command,'command')}));
+}
+
+export async function jobLookup({input,env,fetchImpl}){
+  const value=object(input,'input'),worker=workerConfig(env,value);
+  if(!hex.test(value.upstreamKey??''))throw fail('STRUCTURE_INPUT_INVALID','upstreamKey must be 64 lowercase hex characters');
+  return json(await call(worker,fetchImpl,{route:`/jobs/by-upstream-key/${value.upstreamKey}`,scope:scopeOf(value.scope)}));
+}
+
+export async function jobCancel({input,env,fetchImpl}){
+  const value=object(input,'input'),worker=workerConfig(env,value);
+  return json(await call(worker,fetchImpl,{route:`/jobs/${jobIdOf(value.jobId)}/cancel`,scope:scopeOf(value.scope),body:{}}));
+}
+
+/** Header identity and body bytes must both match the caller's expected artifact row before anything is written. */
+export async function artifactRead({input,env,fetchImpl}){
+  const value=object(input,'input'),worker=workerConfig(env,value),root=ioRoot(env),expected=object(value.expected,'expected');
+  if(typeof value.name!=='string'||!/^[a-z][a-z0-9-]{0,62}\.(step|glb|png|json|py)$/.test(value.name))throw fail('STRUCTURE_INPUT_INVALID','name is invalid');
+  if(typeof expected.mediaType!=='string'||!hex.test(expected.sha256??'')||(expected.bytes!==undefined&&!Number.isSafeInteger(expected.bytes)))
+    throw fail('STRUCTURE_INPUT_INVALID','expected needs mediaType, sha256 and optional integer bytes');
+  const response=await call(worker,fetchImpl,{route:`/jobs/${jobIdOf(value.jobId)}/artifacts/${value.name}`,scope:scopeOf(value.scope)});
+  if(response.headers.get('content-type')?.split(';')[0]!==expected.mediaType||response.headers.get('x-content-sha256')!==expected.sha256)
+    throw workerFailure('artifact_changed',false);
+  const bytes=await bounded(response,value.name.endsWith('.png')?MAX_PNG_BYTES:value.name.endsWith('.json')?MAX_JSON_BYTES:MAX_STEP_BYTES);
+  if(sha256(bytes)!==expected.sha256||(expected.bytes!==undefined&&bytes.length!==expected.bytes))throw workerFailure('artifact_changed',false);
+  return {...writeOutput(root,value.outDir,value.name,bytes),mediaType:expected.mediaType};
+}
+
+/** Rendering runs inside the Worker's runtime (v3 /target-image); the host only moves bytes and keeps the private diagnostic. */
+export async function targetImage({input,env,fetchImpl}){
+  const value=object(input,'input'),worker=workerConfig(env,value),root=ioRoot(env);
+  const baselineGlb=readInput(root,value.baselineGlbPath,MAX_GLB_BYTES,'baselineGlbPath');
+  const response=await call(worker,fetchImpl,{route:'/target-image',errorBytes:TARGET_ERROR_BODY_BYTES,
+    body:{baseline:object(value.baseline,'baseline'),baselineGlb:{sha256:sha256(baselineGlb),base64:baselineGlb.toString('base64')}}});
+  const result=JSON.parse((await bounded(response,Math.ceil((MAX_GLB_BYTES+MAX_PNG_BYTES)/3)*4+TARGET_ERROR_BODY_BYTES*2)).toString('utf8'));
+  const decode=(field,maximum)=>{
+    const item=result?.[field],bytes=Buffer.from(typeof item?.base64==='string'?item.base64:'','base64');
+    if(!bytes.length||bytes.length>maximum||sha256(bytes)!==item.sha256)throw workerFailure('worker_unavailable',false);
+    return bytes;
+  };
+  const png=decode('png',MAX_PNG_BYTES),targetGlb=decode('targetGlb',MAX_GLB_BYTES);
+  return {provenance:result.provenance,diagnostic:result.diagnostic??null,
+    png:writeOutput(root,value.outDir,'target.png',png),targetGlb:writeOutput(root,value.outDir,'target.glb',targetGlb)};
+}

package/skills/abelien-structure/worker/component-fit-glb.mjs

@@ -0,0 +1,173 @@
+/** Bounded static glTF 2.0 decoding and lossless resource relocation for component previews. */
+import {createHash} from 'node:crypto';
+
+export const MAX_GLB_BYTES=64*1024*1024;
+const MAX_NODES=4096, MAX_ELEMENTS=2_000_000;
+export const identity=[1,0,0,0,0,1,0,0,0,0,1,0,0,0,0,1];
+export const sha256=bytes=>createHash('sha256').update(bytes).digest('hex');
+export const fail=code=>{throw Object.assign(new Error(code),{code});};
+const integer=(value,max)=>Number.isSafeInteger(value)&&value>=0&&value<max;
+const finiteArray=(value,n)=>Array.isArray(value)&&value.length===n&&value.every(Number.isFinite);
+const near=(a,b)=>Math.abs(a-b)<1e-8;
+const components={SCALAR:1,VEC2:2,VEC3:3,VEC4:4,MAT2:4,MAT3:9,MAT4:16};
+const componentBytes={5120:1,5121:1,5122:2,5123:2,5125:4,5126:4};
+
+export function rigid(matrix){
+  if(!finiteArray(matrix,16)||![3,7,11].every(index=>near(matrix[index],0))||!near(matrix[15],1))return false;
+  for(let a=0;a<3;a++)for(let b=a;b<3;b++){
+    const dot=[0,1,2].reduce((sum,row)=>sum+matrix[a*4+row]*matrix[b*4+row],0);
+    if(!near(dot,a===b?1:0))return false;
+  }
+  const determinant=matrix[0]*(matrix[5]*matrix[10]-matrix[9]*matrix[6])-matrix[4]*(matrix[1]*matrix[10]-matrix[9]*matrix[2])+matrix[8]*(matrix[1]*matrix[6]-matrix[5]*matrix[2]);
+  return near(determinant,1);
+}
+export function multiply(a,b){
+  const output=Array(16).fill(0);
+  for(let col=0;col<4;col++)for(let row=0;row<4;row++)for(let k=0;k<4;k++)output[col*4+row]+=a[k*4+row]*b[col*4+k];
+  return output;
+}
+export const point=(matrix,p)=>[0,1,2].map(row=>matrix[row]*p[0]+matrix[4+row]*p[1]+matrix[8+row]*p[2]+matrix[12+row]);
+export function nodeMatrix(node,{allowUniformScale=false}={}){
+  if(node.matrix!==undefined){
+    const matrix=node.matrix;
+    let valid=rigid(matrix);
+    if(!valid&&allowUniformScale&&finiteArray(matrix,16)){
+      const scale=Math.hypot(...matrix.slice(0,3));
+      if(scale>0&&Number.isFinite(scale)){const normalized=[...matrix];for(const i of [0,1,2,4,5,6,8,9,10])normalized[i]/=scale;valid=rigid(normalized);}
+    }
+    if(node.translation!==undefined||node.rotation!==undefined||node.scale!==undefined||!valid)fail('unsupported_node_transform');
+    return node.matrix;
+  }
+  const translation=node.translation??[0,0,0],rotation=node.rotation??[0,0,0,1],scale=node.scale??[1,1,1];
+  if(!finiteArray(translation,3)||!finiteArray(rotation,4)||!finiteArray(scale,3)||!scale.every(value=>near(value,1))||!near(rotation.reduce((sum,v)=>sum+v*v,0),1))fail('unsupported_node_transform');
+  const [x,y,z,w]=rotation;
+  return [1-2*(y*y+z*z),2*(x*y+z*w),2*(x*z-y*w),0,
+    2*(x*y-z*w),1-2*(x*x+z*z),2*(y*z+x*w),0,
+    2*(x*z+y*w),2*(y*z-x*w),1-2*(x*x+y*y),0,...translation,1];
+}
+function rejectUnsupported(value,depth=0){
+  if(depth>128)fail('unsupported_gltf_depth');
+  if(!value||typeof value!=='object')return;
+  if(value.extensions&&Object.keys(value.extensions).some(key=>!['KHR_materials_unlit','KHR_texture_transform'].includes(key)))fail('unsupported_gltf_extension');
+  for(const child of Object.values(value))rejectUnsupported(child,depth+1);
+}
+export function parseGlb(bytes,{allowedUniformScaleNodeIndices=[]}={}){
+  if(!(bytes instanceof Uint8Array)||bytes.byteLength<28||bytes.byteLength>MAX_GLB_BYTES)fail('invalid_glb');
+  const raw=Buffer.from(bytes);
+  if(raw.readUInt32LE(0)!==0x46546c67||raw.readUInt32LE(4)!==2||raw.readUInt32LE(8)!==raw.length)fail('invalid_glb');
+  const jsonLength=raw.readUInt32LE(12);
+  if(jsonLength>8*1024*1024||jsonLength%4||20+jsonLength+8>raw.length||raw.readUInt32LE(16)!==0x4e4f534a)fail('invalid_glb');
+  let doc;try{doc=JSON.parse(raw.subarray(20,20+jsonLength).toString('utf8'));}catch{fail('invalid_glb_json');}
+  const binHeader=20+jsonLength,binLength=raw.readUInt32LE(binHeader);
+  if(raw.readUInt32LE(binHeader+4)!==0x004e4942||binLength%4||binHeader+8+binLength!==raw.length)fail('invalid_glb');
+  const bin=raw.subarray(binHeader+8);
+  if(doc.asset?.version!=='2.0'||!Array.isArray(doc.buffers)||doc.buffers.length!==1||doc.buffers[0].uri!==undefined||!Number.isSafeInteger(doc.buffers[0].byteLength)||doc.buffers[0].byteLength<=0||doc.buffers[0].byteLength>bin.length||bin.length-doc.buffers[0].byteLength>3)fail('unsupported_gltf_buffer');
+  if(doc.animations?.length||doc.skins?.length||doc.cameras?.length)fail('unsupported_dynamic_gltf');
+  if((doc.extensionsRequired??[]).some(key=>!['KHR_materials_unlit','KHR_texture_transform'].includes(key)))fail('unsupported_gltf_extension');
+  rejectUnsupported(doc);
+  for(const field of ['nodes','meshes','accessors','bufferViews'])if(!Array.isArray(doc[field])||!doc[field].length||doc[field].length>MAX_NODES*8)fail('invalid_gltf_resources');
+  if(doc.nodes.length>MAX_NODES||!Array.isArray(doc.scenes)||doc.scenes.length!==1||(doc.scene??0)!==0||!Array.isArray(doc.scenes[0].nodes)||!doc.scenes[0].nodes.length)fail('unsupported_gltf_scene');
+  for(const view of doc.bufferViews){
+    if(view.buffer!==0||!Number.isSafeInteger(view.byteOffset??0)||(view.byteOffset??0)<0||!Number.isSafeInteger(view.byteLength)||view.byteLength<=0||(view.byteOffset??0)+view.byteLength>doc.buffers[0].byteLength||
+      (view.byteStride!==undefined&&(!Number.isSafeInteger(view.byteStride)||view.byteStride<4||view.byteStride>252||view.byteStride%4)))fail('invalid_gltf_buffer_view');
+  }
+  for(const accessor of doc.accessors){
+    const count=components[accessor.type],size=componentBytes[accessor.componentType];
+    if(!integer(accessor.bufferView,doc.bufferViews.length)||accessor.sparse||!count||!size||!Number.isSafeInteger(accessor.count)||accessor.count<=0||accessor.count>MAX_ELEMENTS)fail('unsupported_gltf_accessor');
+    const view=doc.bufferViews[accessor.bufferView],stride=view.byteStride??count*size,offset=accessor.byteOffset??0;
+    if(!Number.isSafeInteger(offset)||offset<0||stride<count*size||offset%size||((view.byteOffset??0)+offset)%size||offset+(accessor.count-1)*stride+count*size>view.byteLength)fail('invalid_gltf_accessor_bounds');
+  }
+  for(const mesh of doc.meshes){
+    if(mesh.weights||!Array.isArray(mesh.primitives)||!mesh.primitives.length||mesh.primitives.length>MAX_NODES)fail('unsupported_gltf_mesh');
+    for(const primitive of mesh.primitives){
+      if((primitive.mode??4)!==4||primitive.targets||!primitive.attributes||!integer(primitive.attributes.POSITION,doc.accessors.length)||Object.values(primitive.attributes).some(index=>!integer(index,doc.accessors.length))||
+        (primitive.indices!==undefined&&!integer(primitive.indices,doc.accessors.length))||(primitive.material!==undefined&&!integer(primitive.material,doc.materials?.length??0)))fail('unsupported_gltf_primitive');
+      const pos=doc.accessors[primitive.attributes.POSITION];
+      if(pos.componentType!==5126||pos.type!=='VEC3'||pos.normalized)fail('unsupported_gltf_positions');
+      if(Object.values(primitive.attributes).some(index=>doc.accessors[index].count!==pos.count))fail('invalid_gltf_attribute_count');
+      if(primitive.indices!==undefined){const index=doc.accessors[primitive.indices];if(index.type!=='SCALAR'||![5121,5123,5125].includes(index.componentType)||index.normalized)fail('unsupported_gltf_indices');}
+      if((primitive.indices===undefined?pos.count:doc.accessors[primitive.indices].count)%3)fail('invalid_gltf_triangles');
+    }
+  }
+  for(const image of doc.images??[])if(image.uri!==undefined||!integer(image.bufferView,doc.bufferViews.length)||!['image/png','image/jpeg'].includes(image.mimeType))fail('unsupported_gltf_image');
+  for(const texture of doc.textures??[])if(!integer(texture.source,doc.images?.length??0)||(texture.sampler!==undefined&&!integer(texture.sampler,doc.samplers?.length??0)))fail('invalid_gltf_texture');
+  for(const material of doc.materials??[]){
+    for(const texture of [material.pbrMetallicRoughness?.baseColorTexture,material.pbrMetallicRoughness?.metallicRoughnessTexture,material.normalTexture,material.occlusionTexture,material.emissiveTexture])if(texture&&!integer(texture.index,doc.textures?.length??0))fail('invalid_gltf_material');
+  }
+  const parents=new Map(),reachable=new Set(),world=new Map();
+  for(let index=0;index<doc.nodes.length;index++){
+    const node=doc.nodes[index];nodeMatrix(node,{allowUniformScale:allowedUniformScaleNodeIndices.includes(index)});
+    if(node.skin!==undefined||node.camera!==undefined||node.weights||(node.mesh!==undefined&&!integer(node.mesh,doc.meshes.length))||(node.children!==undefined&&!Array.isArray(node.children)))fail('unsupported_gltf_node');
+    for(const child of node.children??[]){if(!integer(child,doc.nodes.length)||parents.has(child))fail('invalid_gltf_hierarchy');parents.set(child,index);}
+  }
+  const visit=(index,matrix,depth)=>{
+    if(!integer(index,doc.nodes.length)||reachable.has(index)||depth>128)fail('invalid_gltf_hierarchy');
+    reachable.add(index);const transform=multiply(matrix,nodeMatrix(doc.nodes[index],{allowUniformScale:allowedUniformScaleNodeIndices.includes(index)}));world.set(index,transform);
+    for(const child of doc.nodes[index].children??[])visit(child,transform,depth+1);
+  };
+  for(const root of doc.scenes[0].nodes){if(parents.has(root))fail('invalid_gltf_hierarchy');visit(root,identity,0);}
+  if(reachable.size!==doc.nodes.length)fail('unsupported_unreachable_nodes');
+  return {doc,bin,parents,world};
+}
+export function encodeGlb(doc,bin){
+  const jsonRaw=Buffer.from(JSON.stringify(doc)),json=Buffer.alloc(Math.ceil(jsonRaw.length/4)*4,0x20);jsonRaw.copy(json);
+  const padded=Buffer.alloc(Math.ceil(bin.length/4)*4);bin.copy(padded);
+  const result=Buffer.alloc(28+json.length+padded.length);
+  result.writeUInt32LE(0x46546c67,0);result.writeUInt32LE(2,4);result.writeUInt32LE(result.length,8);
+  result.writeUInt32LE(json.length,12);result.writeUInt32LE(0x4e4f534a,16);json.copy(result,20);
+  result.writeUInt32LE(padded.length,20+json.length);result.writeUInt32LE(0x004e4942,24+json.length);padded.copy(result,28+json.length);
+  if(result.length>MAX_GLB_BYTES)fail('assembly_glb_too_large');
+  return result;
+}
+function readAccessor(parsed,index){
+  const accessor=parsed.doc.accessors[index],view=parsed.doc.bufferViews[accessor.bufferView],n=components[accessor.type],size=componentBytes[accessor.componentType];
+  const offset=(view.byteOffset??0)+(accessor.byteOffset??0),stride=view.byteStride??n*size;
+  const read={5121:'readUInt8',5123:'readUInt16LE',5125:'readUInt32LE',5126:'readFloatLE'}[accessor.componentType];
+  if(!read)fail('unsupported_geometry_accessor');
+  return {count:accessor.count,get:i=>Array.from({length:n},(_,axis)=>parsed.bin[read](offset+i*stride+axis*size))};
+}
+export function* triangles(parsed,nodeIndex,matrix){
+  const node=parsed.doc.nodes[nodeIndex];if(node.mesh===undefined)return;
+  for(const primitive of parsed.doc.meshes[node.mesh].primitives){
+    const positions=readAccessor(parsed,primitive.attributes.POSITION),indices=primitive.indices===undefined?undefined:readAccessor(parsed,primitive.indices),count=indices?.count??positions.count;
+    for(let index=0;index<count;index+=3){
+      const triangle=[];
+      for(let vertex=0;vertex<3;vertex++){
+        const positionIndex=indices?indices.get(index+vertex)[0]:index+vertex;
+        if(!integer(positionIndex,positions.count))fail('invalid_gltf_index');
+        const xyz=positions.get(positionIndex);if(!xyz.every(Number.isFinite))fail('invalid_gltf_position');
+        const transformed=point(matrix,xyz);if(!transformed.every(Number.isFinite)||transformed.some(value=>Math.abs(value)>1e6))fail('invalid_geometry_range');triangle.push(transformed);
+      }
+      yield triangle;
+    }
+  }
+}
+/** Appends resources; baseline buffer/accessor/mesh/material indices and bytes stay unchanged. */
+export function appendCandidate(baseline,candidate,prefix){
+  const doc=structuredClone(baseline.doc),source=candidate.doc,counts=Object.fromEntries(['nodes','meshes','accessors','bufferViews','materials','textures','samplers','images'].map(key=>[key,doc[key]?.length??0]));
+  const bin=Buffer.concat([baseline.bin,candidate.bin]),byteOffset=baseline.bin.length;
+  doc.buffers=[{...doc.buffers[0],byteLength:bin.length}];
+  for(const key of Object.keys(counts)){
+    if(!source[key]?.length)continue;
+    const rows=structuredClone(source[key]);
+    for(let index=0;index<rows.length;index++){
+      const row=rows[index];
+      if(key==='nodes'){
+        row.name=`${prefix}-${index}`;
+        if(row.mesh!==undefined)row.mesh+=counts.meshes;
+        if(row.children)row.children=row.children.map(child=>child+counts.nodes);
+      }else if(key==='meshes')for(const primitive of row.primitives){
+        for(const attribute of Object.keys(primitive.attributes))primitive.attributes[attribute]+=counts.accessors;
+        if(primitive.indices!==undefined)primitive.indices+=counts.accessors;
+        if(primitive.material!==undefined)primitive.material+=counts.materials;
+      }else if(key==='accessors')row.bufferView+=counts.bufferViews;
+      else if(key==='bufferViews'){row.buffer=0;row.byteOffset=(row.byteOffset??0)+byteOffset;}
+      else if(key==='images')row.bufferView+=counts.bufferViews;
+      else if(key==='textures'){row.source+=counts.images;if(row.sampler!==undefined)row.sampler+=counts.samplers;}
+      else if(key==='materials')for(const texture of [row.pbrMetallicRoughness?.baseColorTexture,row.pbrMetallicRoughness?.metallicRoughnessTexture,row.normalTexture,row.occlusionTexture,row.emissiveTexture])if(texture)texture.index+=counts.textures;
+    }
+    doc[key]=[...(doc[key]??[]),...rows];
+  }
+  for(const key of ['extensionsUsed','extensionsRequired'])if(source[key]?.length)doc[key]=[...new Set([...(doc[key]??[]),...source[key]])];
+  return {doc,bin,roots:source.scenes[0].nodes.map(index=>index+counts.nodes)};
+}

package/skills/abelien-structure/worker/component-fit.d.mts

@@ -0,0 +1,82 @@
+/** Server-only immutable inputs. Never populate `trusted` from a model or browser request. */
+export interface ComponentFitBinding {
+  draftId: string;
+  baselineId: string;
+  baselineRevision: number;
+  baselineGlbSha256: string;
+  targetOccurrenceId: string;
+}
+export interface ComponentFitRequest {
+  schema: 'abelien.appearance-component-fit-request.v1';
+  baseline: ComponentFitBinding;
+  candidateGlbSha256: string;
+}
+export interface ComponentFitBox {
+  id: string;
+  /** Axis aligned box in the target occurrence's local frame, in metres. */
+  min: [number, number, number];
+  max: [number, number, number];
+}
+export interface TrustedComponentFitBaseline {
+  schema: 'abelien.appearance-component-fit-baseline.v1';
+  baseline: ComponentFitBinding;
+  /** glTF positions use metres; unknown physical units must stay preview-only upstream. */
+  units: 'm';
+  /** Unknown by default. Unknown requires explicit visualNormalization; never infer from glTF convention. */
+  candidatePhysicalUnits?: 'verified_m' | 'unknown';
+  /** Display-only scale/centering of generated wrapper; original geometry is never resized. */
+  visualNormalization?: 'fit_target_bounds';
+  /** Column-major rigid transform. No automatic sizing or non-unit scale is allowed. */
+  candidateToTarget: number[];
+  /** Omitted: replace all visual meshes under target, protected checks unknown. */
+  constraints?: {
+    /** Unique mesh-bearing node names strictly beneath, or equal to, target; children are preserved. */
+    replaceNodeNames: string[];
+    /** Exact original mesh-bearing nodes retained under target, disjoint from replacements. */
+    protectedNodeNames: string[];
+    protectedRegions: ComponentFitBox[];
+    keepouts: ComponentFitBox[];
+    allowedEnvelope?: ComponentFitBox;
+  };
+}
+export interface ComponentFitCheck {
+  id: string;
+  status: 'pass' | 'conflict' | 'unknown';
+  reason: string;
+}
+export interface ComponentFitReport {
+  schema: 'abelien.appearance-component-fit-report.v1';
+  checkerVersion: 'mesh-assembly-preview.v1';
+  baseline: ComponentFitBinding;
+  candidateGlbSha256: string;
+  assemblyGlbSha256: string;
+  trustedInputSha256: string;
+  representation: 'mesh_assembly_preview';
+  fitStatus: 'conflict' | 'unknown';
+  previewEligible: boolean;
+  adoptionEligible: false;
+  checks: ComponentFitCheck[];
+  preservedNodeCount: number;
+  replacedNodeNames: string[];
+  candidateTriangleCount: number;
+  candidateBounds: {min: number[]; max: number[]};
+  visualNormalization?: {method: 'fit_target_bounds'; scale: number; translationM: number[]; sourceBounds: {min: number[]; max: number[]}; targetBounds: {min: number[]; max: number[]}};
+}
+export function fitAppearanceComponent(input: {
+  request: ComponentFitRequest;
+  trusted: TrustedComponentFitBaseline;
+  baselineGlb: Uint8Array;
+  candidateGlb: Uint8Array;
+}): {assemblyGlb: Buffer; report: ComponentFitReport};
+/** Recomputes geometry and compares the complete report and output bytes; supplied pass fields are never trusted. */
+export function verifyAppearanceComponentFit(input: {
+  request: ComponentFitRequest;
+  trusted: TrustedComponentFitBaseline;
+  baselineGlb: Uint8Array;
+  candidateGlb: Uint8Array;
+  assemblyGlb: Uint8Array;
+  report: ComponentFitReport;
+}): boolean;
+
+/** Inverse target world rotation from trusted baseline; zero translation, centering belongs to normalization. */
+export function deriveTargetLocalPlacement(input: {baseline: ComponentFitBinding; baselineGlb: Uint8Array}): number[];

package/skills/abelien-structure/worker/component-fit.mjs

@@ -0,0 +1,167 @@
+/**
+ * Server-only deterministic static-mesh component replacement.
+ * The caller resolves ownership, latest revision and immutable assets before calling.
+ * Geometric preview evidence never authorizes CAD adoption or manufacturing export.
+ */
+import {MAX_GLB_BYTES,appendCandidate,encodeGlb,fail,identity,multiply,nodeMatrix,parseGlb,rigid,sha256,triangles} from './component-fit-glb.mjs';
+
+const HEX=/^[a-f0-9]{64}$/,MAX_TRIANGLES=500_000;
+const isObject=value=>value&&typeof value==='object'&&!Array.isArray(value);
+const keys=(value,required,optional=[])=>isObject(value)&&required.every(key=>Object.hasOwn(value,key))&&Object.keys(value).every(key=>required.includes(key)||optional.includes(key));
+const text=value=>typeof value==='string'&&value.length>0&&value.length<=200&&!/[\u0000-\u001f\u007f]/.test(value);
+const canonical=value=>JSON.stringify(canonicalValue(value));
+function canonicalValue(value){
+  if(Array.isArray(value))return value.map(canonicalValue);
+  if(isObject(value))return Object.fromEntries(Object.keys(value).sort().map(key=>[key,canonicalValue(value[key])]));
+  return value;
+}
+function validBinding(value){
+  return keys(value,['draftId','baselineId','baselineRevision','baselineGlbSha256','targetOccurrenceId'])&&['draftId','baselineId','targetOccurrenceId'].every(key=>text(value[key]))&&Number.isSafeInteger(value.baselineRevision)&&value.baselineRevision>=0&&HEX.test(value.baselineGlbSha256);
+}
+function validBox(value){return keys(value,['id','min','max'])&&text(value.id)&&['min','max'].every(key=>Array.isArray(value[key])&&value[key].length===3&&value[key].every(Number.isFinite))&&value.min.every((n,i)=>n<value.max[i]);}
+function validateInputs(request,trusted,baselineGlb,candidateGlb){
+  if(!keys(request,['schema','baseline','candidateGlbSha256'])||request.schema!=='abelien.appearance-component-fit-request.v1'||!validBinding(request.baseline)||!HEX.test(request.candidateGlbSha256))fail('invalid_fit_request');
+  if(!keys(trusted,['schema','baseline','units','candidateToTarget'],['constraints','visualNormalization','candidatePhysicalUnits'])||trusted.schema!=='abelien.appearance-component-fit-baseline.v1'||!validBinding(trusted.baseline)||trusted.units!=='m')fail('invalid_trusted_fit_baseline');
+  if(canonical(request.baseline)!==canonical(trusted.baseline))fail('stale_or_mismatched_fit_baseline');
+  if(!rigid(trusted.candidateToTarget))fail('non_rigid_fit_transform');
+  if(trusted.visualNormalization!==undefined&&trusted.visualNormalization!=='fit_target_bounds')fail('invalid_visual_normalization');
+  if(trusted.candidatePhysicalUnits!==undefined&&!['verified_m','unknown'].includes(trusted.candidatePhysicalUnits))fail('invalid_candidate_physical_units');
+  if(trusted.visualNormalization===undefined&&trusted.candidatePhysicalUnits!=='verified_m')fail('candidate_physical_units_unknown');
+  if(!(baselineGlb instanceof Uint8Array)||!(candidateGlb instanceof Uint8Array)||baselineGlb.byteLength>MAX_GLB_BYTES||candidateGlb.byteLength>MAX_GLB_BYTES||sha256(baselineGlb)!==trusted.baseline.baselineGlbSha256||sha256(candidateGlb)!==request.candidateGlbSha256)fail('fit_source_hash_mismatch');
+  if(trusted.constraints!==undefined){
+    const c=trusted.constraints;
+    if(!keys(c,['replaceNodeNames','protectedNodeNames','protectedRegions','keepouts'],['allowedEnvelope'])||!Array.isArray(c.replaceNodeNames)||!c.replaceNodeNames.length||c.replaceNodeNames.length>4096||!Array.isArray(c.protectedNodeNames)||c.protectedNodeNames.length>4096||
+      [...c.replaceNodeNames,...c.protectedNodeNames].some(name=>!text(name))||new Set([...c.replaceNodeNames,...c.protectedNodeNames]).size!==c.replaceNodeNames.length+c.protectedNodeNames.length||
+      !Array.isArray(c.protectedRegions)||!Array.isArray(c.keepouts)||c.protectedRegions.length+c.keepouts.length>128||[...c.protectedRegions,...c.keepouts].some(box=>!validBox(box))||
+      (c.allowedEnvelope!==undefined&&!validBox(c.allowedEnvelope)))fail('invalid_fit_constraints');
+    const regionIds=[...c.protectedRegions,...c.keepouts,...(c.allowedEnvelope?[c.allowedEnvelope]:[])].map(box=>box.id);
+    if(new Set(regionIds).size!==regionIds.length)fail('invalid_fit_constraints');
+  }
+}
+function bounds(triangle){return {min:[0,1,2].map(axis=>Math.min(...triangle.map(p=>p[axis]))),max:[0,1,2].map(axis=>Math.max(...triangle.map(p=>p[axis])))};}
+// Conservative exclusion: an overlapping triangle bounding box is a conflict even
+// when the exact triangle would miss the box. This never grants a false clear.
+const touches=(triangle,box)=>triangle.min.every((n,axis)=>n<=box.max[axis]&&triangle.max[axis]>=box.min[axis]);
+const inside=(triangle,box)=>triangle.min.every((n,axis)=>n>=box.min[axis]&&triangle.max[axis]<=box.max[axis]);
+const check=(id,status,reason)=>({id,status,reason});
+const uniqueNode=(parsed,name)=>{
+  const matching=parsed.doc.nodes.flatMap((node,index)=>node.name===name?[index]:[]);
+  if(matching.length!==1)fail('missing_or_ambiguous_fit_target');
+  return matching[0];
+};
+function relativeTransforms(parsed,target){
+  const relative=new Map();
+  const visit=(index,matrix)=>{relative.set(index,matrix);for(const child of parsed.doc.nodes[index].children??[])visit(child,multiply(matrix,nodeMatrix(parsed.doc.nodes[child])));};
+  visit(target,identity);return relative;
+}
+
+/** Map a generated glTF world-oriented component into the existing target local basis.
+ * Translation remains zero: preview normalization owns centering. Only trusted
+ * baseline bytes/name determine this transform; never a model-provided mount frame.
+ */
+export function deriveTargetLocalPlacement({baseline:binding,baselineGlb}){
+  if(!validBinding(binding)||!(baselineGlb instanceof Uint8Array)||baselineGlb.byteLength>MAX_GLB_BYTES||sha256(baselineGlb)!==binding.baselineGlbSha256)fail('invalid_fit_placement_baseline');
+  const parsed=parseGlb(baselineGlb),target=uniqueNode(parsed,binding.targetOccurrenceId),world=parsed.world.get(target);
+  if(!rigid(world))fail('non_rigid_fit_target_basis');
+  return [world[0],world[4],world[8],0,world[1],world[5],world[9],0,world[2],world[6],world[10],0,0,0,0,1];
+}
+
+export function fitAppearanceComponent({request,trusted,baselineGlb,candidateGlb}){
+  validateInputs(request,trusted,baselineGlb,candidateGlb);
+  const baseline=parseGlb(baselineGlb),candidate=parseGlb(candidateGlb),target=uniqueNode(baseline,trusted.baseline.targetOccurrenceId);
+  const relative=relativeTransforms(baseline,target),constraints=trusted.constraints;
+  const meshNodes=[...relative.keys()].filter(index=>baseline.doc.nodes[index].mesh!==undefined);
+  if(!meshNodes.length)fail('fit_target_has_no_geometry');
+  const resolveNames=names=>names.map(name=>{
+    const index=uniqueNode(baseline,name);if(!relative.has(index)||baseline.doc.nodes[index].mesh===undefined)fail('fit_constraint_outside_target');return index;
+  });
+  const replacements=constraints?resolveNames(constraints.replaceNodeNames):meshNodes;
+  const protectedNodes=constraints?resolveNames(constraints.protectedNodeNames):[];
+  const replaced=new Set(replacements),protectedSet=new Set(protectedNodes);
+  const checks=[check('baseline_identity','pass','server_binding_and_requested_revision_match'),check('source_integrity','pass','baseline_and_candidate_bytes_match_sha256'),check('rigid_placement',trusted.visualNormalization?'unknown':'pass',trusted.visualNormalization?'visual_normalization_not_physical_calibration':'verified_metre_frame_rigid_transform_without_resizing')];
+  // Validate all reachable baseline geometry, including unrelated components.
+  let baselineTriangles=0,removedProtectedSurface=false,unassignedProtectedSurface=false;
+  const witnessedRegions=new Set(),targetBounds={min:[Infinity,Infinity,Infinity],max:[-Infinity,-Infinity,-Infinity]};
+  for(let index=0;index<baseline.doc.nodes.length;index++){
+    const local=relative.get(index);
+    for(const triangle of triangles(baseline,index,local??baseline.world.get(index))){
+      if(++baselineTriangles>MAX_TRIANGLES)fail('fit_geometry_too_large');
+      if(replaced.has(index)){const box=bounds(triangle);for(let axis=0;axis<3;axis++){targetBounds.min[axis]=Math.min(targetBounds.min[axis],box.min[axis]);targetBounds.max[axis]=Math.max(targetBounds.max[axis],box.max[axis]);}}
+      if(local&&constraints)for(const region of constraints.protectedRegions)if(touches(bounds(triangle),region)){
+        if(replaced.has(index))removedProtectedSurface=true;
+        else if(protectedSet.has(index))witnessedRegions.add(region.id);
+        else unassignedProtectedSurface=true;
+      }
+    }
+  }
+  let placement=[...trusted.candidateToTarget],visualNormalization;
+  if(trusted.visualNormalization){
+    const sourceBounds={min:[Infinity,Infinity,Infinity],max:[-Infinity,-Infinity,-Infinity]};let count=0;
+    for(let index=0;index<candidate.doc.nodes.length;index++)for(const triangle of triangles(candidate,index,multiply(placement,candidate.world.get(index)))){
+      if(++count>MAX_TRIANGLES)fail('fit_geometry_too_large');const box=bounds(triangle);
+      for(let axis=0;axis<3;axis++){sourceBounds.min[axis]=Math.min(sourceBounds.min[axis],box.min[axis]);sourceBounds.max[axis]=Math.max(sourceBounds.max[axis],box.max[axis]);}
+    }
+    if(!count)fail('fit_candidate_has_no_geometry');
+    const ratios=[0,1,2].filter(axis=>sourceBounds.max[axis]>sourceBounds.min[axis]).map(axis=>(targetBounds.max[axis]-targetBounds.min[axis])/(sourceBounds.max[axis]-sourceBounds.min[axis]));
+    const scale=Math.min(...ratios);if(!Number.isFinite(scale)||scale<=0||scale>1e9||scale<1e-9)fail('unsupported_visual_normalization');
+    const translationM=[0,1,2].map(axis=>(targetBounds.min[axis]+targetBounds.max[axis])/2-scale*(sourceBounds.min[axis]+sourceBounds.max[axis])/2);
+    const normalization=[scale,0,0,0,0,scale,0,0,0,0,scale,0,...translationM,1];placement=multiply(normalization,placement);
+    visualNormalization={method:'fit_target_bounds',scale,translationM,sourceBounds,targetBounds};
+  }
+  let candidateTriangleCount=0,protectedIntrusion=false,keepoutIntrusion=false,outsideEnvelope=false;
+  const candidateBounds={min:[Infinity,Infinity,Infinity],max:[-Infinity,-Infinity,-Infinity]};
+  for(let index=0;index<candidate.doc.nodes.length;index++){
+    const matrix=multiply(placement,candidate.world.get(index));
+    for(const triangle of triangles(candidate,index,matrix)){
+      if(++candidateTriangleCount>MAX_TRIANGLES)fail('fit_geometry_too_large');
+      const box=bounds(triangle);
+      for(let axis=0;axis<3;axis++){candidateBounds.min[axis]=Math.min(candidateBounds.min[axis],box.min[axis]);candidateBounds.max[axis]=Math.max(candidateBounds.max[axis],box.max[axis]);}
+      if(constraints){
+        if(constraints.protectedRegions.some(region=>touches(box,region)))protectedIntrusion=true;
+        if(constraints.keepouts.some(region=>touches(box,region)))keepoutIntrusion=true;
+        if(constraints.allowedEnvelope&&!inside(box,constraints.allowedEnvelope))outsideEnvelope=true;
+      }
+    }
+  }
+  if(!candidateTriangleCount)fail('fit_candidate_has_no_geometry');
+  checks.push(check('protected_geometry',removedProtectedSurface||unassignedProtectedSurface?'conflict':protectedNodes.length?'pass':'unknown',removedProtectedSurface?'replacement_removes_protected_region_triangles':unassignedProtectedSurface?'protected_region_geometry_has_no_protected_node_binding':protectedNodes.length?'original_protected_mesh_nodes_and_resources_preserved_exactly':'no_trusted_protected_mesh_nodes'));
+  checks.push(check('protected_regions',protectedIntrusion?'conflict':!constraints?.protectedRegions.length||witnessedRegions.size!==constraints.protectedRegions.length?'unknown':'pass',protectedIntrusion?'generated_triangle_bounds_enter_protected_region':!constraints?.protectedRegions.length?'no_trusted_protected_regions':witnessedRegions.size!==constraints.protectedRegions.length?'region_has_no_original_protected_surface_witness':'generated_surface_bounds_excluded_from_witnessed_protected_regions'));
+  checks.push(check('keepouts',keepoutIntrusion?'conflict':constraints?.keepouts.length?'pass':'unknown',keepoutIntrusion?'generated_triangle_bounds_enter_keepout':constraints?.keepouts.length?'generated_surface_bounds_excluded_from_declared_keepouts':'no_trusted_keepouts'));
+  checks.push(check('allowed_envelope',outsideEnvelope?'conflict':constraints?.allowedEnvelope?'pass':'unknown',outsideEnvelope?'generated_surface_outside_allowed_envelope':constraints?.allowedEnvelope?'all_generated_triangles_inside_allowed_envelope':'no_trusted_allowed_envelope'));
+  const prefix=`appearance-${request.candidateGlbSha256.slice(0,16)}`;
+  if(baseline.doc.nodes.some(node=>typeof node.name==='string'&&node.name.startsWith(prefix)))fail('fit_candidate_name_collision');
+  const output=appendCandidate(baseline,candidate,prefix);
+  for(const index of replacements)delete output.doc.nodes[index].mesh;
+  const wrapper=output.doc.nodes.length;
+  output.doc.nodes.push({name:`${prefix}-placement`,matrix:placement,children:output.roots});
+  output.doc.nodes[target].children=[...(output.doc.nodes[target].children??[]),wrapper];
+  // Exactly the named mesh bindings and target children change. All ancestor
+  // transforms, unrelated nodes and original binary resource bytes remain exact.
+  let preservedNodeCount=0;
+  for(let index=0;index<baseline.doc.nodes.length;index++){
+    const expected=structuredClone(baseline.doc.nodes[index]);if(replaced.has(index))delete expected.mesh;
+    if(index===target)expected.children=[...(expected.children??[]),wrapper];
+    if(canonical(expected)!==canonical(output.doc.nodes[index]))fail('fit_preservation_failed');
+    if(index!==target&&!replaced.has(index))preservedNodeCount++;
+  }
+  if(!output.bin.subarray(0,baseline.bin.length).equals(baseline.bin))fail('fit_preservation_failed');
+  const assemblyGlb=encodeGlb(output.doc,output.bin);
+  parseGlb(assemblyGlb,{allowedUniformScaleNodeIndices:visualNormalization?[wrapper]:[]}); // Independently decode exported resource indices/hierarchy.
+  checks.push(check('unrelated_preservation','pass','original_nodes_ancestor_transforms_and_resource_bytes_preserved'));
+  checks.push(check('joint_continuity','unknown','no_mesh_boolean_stitch_or_manifold_joint_validation'));
+  checks.push(check('solid_collision','unknown','surface_box_exclusion_does_not_establish_solid_volume_clearance'));
+  checks.push(check('wall_thickness','unknown','no_trusted_solid_or_wall_thickness_validation'));
+  checks.push(check('engineering_fit','unknown','mesh_preview_cannot_certify_mechanical_interface_tolerance_or_manufacturing'));
+  const hasConflict=checks.some(item=>item.status==='conflict');
+  return {assemblyGlb,report:{schema:'abelien.appearance-component-fit-report.v1',checkerVersion:'mesh-assembly-preview.v1',baseline:structuredClone(trusted.baseline),candidateGlbSha256:request.candidateGlbSha256,
+    assemblyGlbSha256:sha256(assemblyGlb),trustedInputSha256:sha256(canonical(trusted)),representation:'mesh_assembly_preview',fitStatus:hasConflict?'conflict':'unknown',previewEligible:!hasConflict,adoptionEligible:false,checks,
+    ...(visualNormalization?{visualNormalization}:{}),preservedNodeCount,replacedNodeNames:replacements.map(index=>baseline.doc.nodes[index].name??`node:${index}`),candidateTriangleCount,candidateBounds}};
+}
+
+export function verifyAppearanceComponentFit(input){
+  try{
+    if(!(input.assemblyGlb instanceof Uint8Array))return false;
+    const result=fitAppearanceComponent(input);
+    return Buffer.from(input.assemblyGlb).equals(result.assemblyGlb)&&canonical(input.report)===canonical(result.report);
+  }catch{return false;}
+}