abelien-harness 0.4.0 → 0.6.0

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

@@ -0,0 +1,1623 @@
+"""Bounded sandbox invocation: trusted API export, non-executing AST precheck, independent build and inspection."""
+import base64
+import contextlib
+import hashlib
+from io import BytesIO
+import itertools
+import json
+import math
+import os
+from pathlib import Path
+import re
+import struct
+import sys
+
+# OCCT also writes through native fd 1; Python redirect_stdout alone cannot isolate
+# those messages from the JSON protocol. Only the explicit response uses this fd.
+response_stream = os.fdopen(os.dup(1), 'w')
+
+
+def failure_diagnostic(stage, exc):
+    """Bounded, model-facing reason a build failed: no paths, addresses, worker code or control chars."""
+    line = None
+    if isinstance(exc, SyntaxError) and exc.filename == 'model.py':
+        line = exc.lineno
+    tb = exc.__traceback__
+    while tb is not None:  # innermost frame of the submitted source; worker frames never count
+        if tb.tb_frame.f_code.co_filename == 'model.py':
+            line = tb.tb_lineno
+        tb = tb.tb_next
+    message = re.sub(r'(?:[A-Za-z]:)?(?:/|\\)[^\s\'",)]+', '<path>', str(exc))
+    message = re.sub(r'0x[0-9a-fA-F]+', '0x?', message)
+    message = ''.join(ch if ch.isprintable() else ' ' for ch in message).strip()[:200]
+    name = type(exc).__name__
+    return {'stage': stage, 'exceptionType': name if re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]{0,63}', name) else 'Error',
+            'message': message, 'line': line if isinstance(line, int) and 0 < line <= 32768 else None}
+
+
+def fail_with_diagnostic(stage, exc):
+    import traceback
+    traceback.print_exc(file=sys.stderr)
+    print(json.dumps({'diagnostic': failure_diagnostic(stage, exc)}, ensure_ascii=False), file=response_stream, flush=True)
+    raise SystemExit(0)
+os.dup2(2, 1)
+
+VIEWS = ('normal', 'internal', 'exploded')
+DEFERRED = ('voltage', 'peak_current', 'port_occupancy', 'logic_level', 'concurrent_resources', 'actuator_load')
+STABLE = re.compile(r'^[a-z0-9][a-z0-9._:-]{0,127}$')
+TARGET_ID = re.compile(r'^[A-Za-z0-9][A-Za-z0-9:_.-]{0,127}$')
+NODE_ID = re.compile(r'^[a-z0-9][a-z0-9_-]{0,127}$')
+HEX = re.compile(r'^[a-f0-9]{64}$')
+REVISION_CHANGES = ('geometry', 'transform', 'interfaces', 'appearance_mapping')
+
+def load_cad_library(*, reset=False):
+    """Load the trusted adjacent library under isolated Python without changing sys.path."""
+    import importlib.util
+    library_path = Path(__file__).with_name('abelien_cad.py')
+    spec = importlib.util.spec_from_file_location('abelien_cad', library_path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError('CAD library unavailable')
+    module = importlib.util.module_from_spec(spec)
+    sys.modules['abelien_cad'] = module
+    spec.loader.exec_module(module)
+    if reset:
+        module._RECORDS.clear()
+    return module
+
+
+def load_source_call_stats():
+    """Load the trusted adjacent pure counter under isolated Python without changing sys.path."""
+    import importlib.util
+    helper_path = Path(__file__).with_name('source_call_stats.py')
+    spec = importlib.util.spec_from_file_location('_abelien_source_call_stats', helper_path)
+    if spec is None or spec.loader is None:
+        raise RuntimeError('source call statistics unavailable')
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.source_call_stats
+
+
+source_call_stats = load_source_call_stats()
+
+
+def library_signature(node):
+    """Python-style signature of one abelien_cad function from its own AST; omitted-sentinel defaults read as '...'."""
+    import ast
+    args = node.args
+    leading = [argument.arg for argument in args.posonlyargs + args.args]
+    keywords = [argument.arg if default is None else
+                f"{argument.arg}={'...' if isinstance(default, ast.Name) and default.id.startswith('_') else ast.unparse(default)}"
+                for argument, default in zip(args.kwonlyargs, args.kw_defaults)]
+    text = f"{node.name}({', '.join(leading + (['*'] + keywords if keywords else []))})"
+    if len(text) > 240 or not text.isprintable():
+        raise RuntimeError('CAD library signature invalid')
+    return text
+
+
+def library_preflight(tree, request):
+    """Statically validate imports and trusted-library/runtime names; never execute model source."""
+    import ast
+    allowed_imports = {'build123d', 'math', 'abelien_cad', 'typing', 'dataclasses', 'itertools',
+                       'functools', 'collections', 'copy', 'enum'}
+    nodes = sorted(ast.walk(tree), key=lambda node: (getattr(node, 'lineno', 0), getattr(node, 'col_offset', 0)))
+    library_aliases, build123d_aliases, library_direct = set(), set(), {}
+    build123d_names = request.get('build123dNames')
+    dynamic_names = any(isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id in {'exec', 'eval', 'globals', 'locals'} for node in nodes)
+    star_import = any(isinstance(node, ast.ImportFrom) and any(alias.name == '*' for alias in node.names) for node in nodes)
+    runtime_names = set(build123d_names) if not dynamic_names and not star_import and isinstance(build123d_names, list) and all(isinstance(name, str) for name in build123d_names) else None
+    for node in nodes:
+        if isinstance(node, ast.Import):
+            for alias in node.names:
+                if alias.name not in allowed_imports:
+                    return {'code': 'source_unsupported', 'feature': 'import_unavailable',
+                            'line': min(max(node.lineno, 1), 32768)}
+                if alias.name == 'abelien_cad':
+                    library_aliases.add(alias.asname or alias.name)
+                if alias.name == 'build123d':
+                    build123d_aliases.add(alias.asname or alias.name)
+        elif isinstance(node, ast.ImportFrom):
+            module = node.module or ''
+            if node.level or module not in allowed_imports:
+                return {'code': 'source_unsupported', 'feature': 'import_unavailable',
+                        'line': min(max(node.lineno, 1), 32768)}
+
+    library_tree = ast.parse(Path(__file__).with_name('abelien_cad.py').read_text(encoding='utf8'), filename='abelien_cad.py')
+    public = set()
+    functions, positional, signatures = {}, {}, {}
+    for node in library_tree.body:
+        if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+            functions[node.name] = {argument.arg for argument in node.args.kwonlyargs}
+            positional[node.name] = len(node.args.posonlyargs) + len(node.args.args)
+            signatures[node.name] = library_signature(node)
+        elif isinstance(node, (ast.Assign, ast.AnnAssign)):
+            targets = node.targets if isinstance(node, ast.Assign) else [node.target]
+            if any(isinstance(target, ast.Name) and target.id == '__all__' for target in targets):
+                value = node.value
+                if isinstance(value, (ast.List, ast.Tuple)) and all(isinstance(item, ast.Constant) and isinstance(item.value, str) for item in value.elts):
+                    public.update(item.value for item in value.elts)
+    if not public or any(name not in functions for name in public):
+        raise RuntimeError('CAD library index invalid')
+
+    library_unknown, argument_unknown, positional_excess, build123d_unknown = set(), set(), set(), set()
+    for node in nodes:
+        if isinstance(node, ast.ImportFrom) and node.module == 'abelien_cad':
+            for alias in node.names:
+                if alias.name == '*':
+                    continue
+                if alias.name not in public:
+                    library_unknown.add(alias.name)
+                else:
+                    library_direct[alias.asname or alias.name] = alias.name
+        if isinstance(node, ast.ImportFrom) and node.module == 'build123d' and runtime_names is not None:
+            build123d_unknown.update(alias.name for alias in node.names if alias.name != '*' and alias.name not in runtime_names)
+        if isinstance(node, ast.Attribute) and isinstance(node.value, ast.Name):
+            if node.value.id in library_aliases and node.attr not in public:
+                library_unknown.add(node.attr)
+            if node.value.id in build123d_aliases and runtime_names is not None and node.attr not in runtime_names:
+                build123d_unknown.add(node.attr)
+        if isinstance(node, ast.Call):
+            function = node.func.attr if isinstance(node.func, ast.Attribute) and isinstance(node.func.value, ast.Name) and node.func.value.id in library_aliases \
+                else library_direct.get(node.func.id) if isinstance(node.func, ast.Name) else None
+            if function in public:
+                argument_unknown.update(f'{function}.{keyword.arg}' for keyword in node.keywords
+                                        if keyword.arg is not None and keyword.arg not in functions[function])
+                # Library parameters after the leading shape/profile/body are keyword-only; a starred call stays dynamic.
+                if not any(isinstance(argument, ast.Starred) for argument in node.args) and len(node.args) > positional[function]:
+                    positional_excess.add(function)
+    bounded = lambda values: sorted(name for name in values if re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]{0,63}', name))[:5]
+    bounded_arguments = lambda values: sorted(name for name in values if re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]{0,63}\.[A-Za-z_][A-Za-z0-9_]{0,63}', name))[:5]
+    unknown_names = bounded(library_unknown)
+    unknown_arguments = bounded_arguments(argument_unknown)
+    excess_positional = bounded(positional_excess)
+    runtime_unknown = bounded(build123d_unknown)
+    # Argument errors carry the exact signature of each affected function so the next attempt can call it correctly.
+    signatures_for = lambda names: [signatures[name] for name in sorted({name.split('.', 1)[0] for name in names})]
+    if unknown_names:
+        return {'code': 'library_unknown', 'names': unknown_names}
+    if unknown_arguments:
+        return {'code': 'library_argument_unknown', 'names': unknown_arguments, 'signatures': signatures_for(unknown_arguments)}
+    if excess_positional:
+        return {'code': 'library_argument_positional', 'names': excess_positional, 'signatures': signatures_for(excess_positional)}
+    if runtime_unknown:
+        return {'code': 'build123d_unknown', 'names': runtime_unknown}
+    return None
+
+
+def representation_text(value):
+    if not isinstance(value, str) or not value.strip() or value != value.strip() or len(value) > 200:
+        raise ValueError('invalid representation text')
+    return value
+
+
+def validate_representation(value, assembly):
+    """Strictly bind optional representation evidence to the exact occurrence assembly."""
+    if not isinstance(value, dict) or set(value) != {'schema', 'occurrences', 'stats'} or \
+       value.get('schema') != 'abelien.structure-representation.v1' or assembly.get('mode') != 'occurrence_assembly':
+        raise ValueError('invalid representation')
+    occurrences, stats = value.get('occurrences'), value.get('stats')
+    owners = assembly.get('occurrences')
+    if not isinstance(occurrences, list) or not isinstance(owners, list) or len(occurrences) != len(owners) or \
+       not isinstance(stats, dict) or set(stats) != {'libraryCalls', 'build123dCalls'} or \
+       any(not isinstance(stats.get(name), int) or isinstance(stats.get(name), bool) or stats[name] < 0
+           for name in ('libraryCalls', 'build123dCalls')):
+        raise ValueError('invalid representation')
+    for item, owner in zip(occurrences, owners):
+        if not isinstance(item, dict) or set(item) != {'occurrenceId', 'representation', 'omitted'} or \
+           item.get('occurrenceId') != owner.get('occurrenceId') or item.get('representation') not in ('detailed', 'simplified', 'envelope') or \
+           not isinstance(item.get('omitted'), list) or len(item['omitted']) > 16:
+            raise ValueError('invalid representation occurrence')
+        precision = owner.get('geometryPrecision')
+        if precision == 'envelope':
+            if item['representation'] != 'envelope':
+                raise ValueError('envelope representation mismatch')
+        elif precision == 'custom_brep':
+            if item['representation'] == 'envelope':
+                raise ValueError('custom representation mismatch')
+        else:
+            raise ValueError('unsupported representation precision')
+        if item['representation'] == 'detailed' and item['omitted'] or item['representation'] == 'simplified' and not item['omitted']:
+            raise ValueError('representation gaps mismatch')
+        for omission in item['omitted']:
+            if not isinstance(omission, dict) or set(omission) != {'feature', 'reason', 'affects'} or \
+               not isinstance(omission.get('affects'), list) or not omission['affects'] or len(omission['affects']) > 32:
+                raise ValueError('invalid representation omission')
+            representation_text(omission.get('feature')); representation_text(omission.get('reason'))
+            for affect in omission['affects']:
+                representation_text(affect)
+    return value
+
+
+def build_representation(source, records, assembly, library_names, build123d_names):
+    """Convert trusted-library records to the report contract after assembly identities exist."""
+    if not isinstance(records, list) or len(records) > 512:
+        raise ValueError('invalid representation records')
+    if assembly.get('mode') != 'occurrence_assembly':
+        if records:
+            raise ValueError('representation record requires occurrence assembly')
+        return None
+    owners = {item['occurrenceId']: item for item in assembly['occurrences']}
+    rows = {item['occurrenceId']: {'occurrenceId': item['occurrenceId'],
+            'representation': 'envelope' if item['geometryPrecision'] == 'envelope' else 'detailed', 'omitted': []}
+            for item in assembly['occurrences']}
+    for record in records:
+        if not isinstance(record, dict) or record.get('kind') not in ('simplified', 'envelope'):
+            raise ValueError('invalid representation record')
+        kind, expected = record['kind'], {'kind', 'occurrence_id', 'reason', 'omitted', 'affects'} if record['kind'] == 'simplified' \
+            else {'kind', 'occurrence_id', 'reason'}
+        if set(record) != expected:
+            raise ValueError('invalid representation record')
+        occurrence_id = record.get('occurrence_id')
+        owner, row = owners.get(occurrence_id), rows.get(occurrence_id)
+        if owner is None or row is None:
+            raise ValueError('representation missing occurrence')
+        reason = representation_text(record.get('reason'))
+        if kind == 'envelope':
+            if owner['geometryPrecision'] != 'envelope':
+                raise ValueError('envelope representation mismatch')
+            row['omitted'].append({'feature': 'detailed_geometry', 'reason': reason,
+                                   'affects': ['geometry_fidelity']})
+        else:
+            omitted, affects = record.get('omitted'), record.get('affects')
+            if owner['geometryPrecision'] != 'custom_brep' or not isinstance(omitted, list) or not omitted or \
+               not isinstance(affects, list) or not affects or len(affects) > 32:
+                raise ValueError('invalid simplified representation')
+            affects = [representation_text(item) for item in affects]
+            row['omitted'].extend({'feature': representation_text(feature), 'reason': reason, 'affects': list(affects)}
+                                  for feature in omitted)
+            row['representation'] = 'simplified'
+        if len(row['omitted']) > 16:
+            raise ValueError('representation omissions exceed supported bound')
+    value = {'schema': 'abelien.structure-representation.v1',
+             'occurrences': [rows[item['occurrenceId']] for item in assembly['occurrences']],
+             'stats': source_call_stats(source, library_names, build123d_names)}
+    return validate_representation(value, assembly)
+
+def encode(path):
+    return base64.b64encode(Path(path).read_bytes()).decode('ascii')
+
+def canonical_manifest(value):
+    """Language-neutral manifest hash input; every number is its IEEE-754 value."""
+    if value is None:
+        return 'null'
+    if isinstance(value, bool):
+        return 'true' if value else 'false'
+    if isinstance(value, (int, float)):
+        number = float(value)
+        if not math.isfinite(number):
+            raise ValueError('non-finite manifest number')
+        return '#' + struct.pack('>d', number).hex()
+    if isinstance(value, str):
+        return json.dumps(value, ensure_ascii=False, separators=(',', ':'))
+    if isinstance(value, (list, tuple)):
+        return '[' + ','.join(canonical_manifest(item) for item in value) + ']'
+    if isinstance(value, dict) and all(isinstance(key, str) for key in value):
+        return '{' + ','.join(json.dumps(key, ensure_ascii=False) + ':' + canonical_manifest(value[key]) for key in sorted(value)) + '}'
+    raise ValueError('unsupported manifest value')
+
+def digest(value):
+    if isinstance(value, bytes):
+        body = value
+    else:
+        body = canonical_manifest(value).encode()
+    return hashlib.sha256(body).hexdigest()
+
+def vector(value):
+    if not isinstance(value, (list, tuple)) or len(value) != 3 or not all(isinstance(item, (int, float)) and not isinstance(item, bool) and math.isfinite(item) for item in value):
+        raise ValueError('invalid assembly transform')
+    result = [float(item) for item in value]
+    if any(abs(item) > 1_000_000 for item in result):
+        raise ValueError('assembly transform outside bounds')
+    return result
+
+def transform(value, *, normal=False):
+    if not isinstance(value, dict) or set(value) != {'translation_mm', 'rotation_deg', 'visible'} or not isinstance(value['visible'], bool):
+        raise ValueError('invalid assembly transform')
+    result = {'translationMm': vector(value['translation_mm']), 'rotationDeg': vector(value['rotation_deg']), 'visible': value['visible']}
+    if normal and not result['visible']:
+        raise ValueError('normal assembly occurrence must be visible')
+    return result
+
+def shape_digest(shape):
+    stream = BytesIO()
+    bd.export_brep(shape, stream)
+    return digest(stream.getvalue())
+
+def normalize_mount_frames(value):
+    if value is None:
+        return []
+    if not isinstance(value, list) or len(value) > 32:
+        raise ValueError('invalid mount frames')
+    rows, identifiers = [], set()
+    for item in value:
+        if not isinstance(item, dict) or set(item) != {'frame_id', 'translation_mm', 'rotation_deg'} or not isinstance(item['frame_id'], str) or not NODE_ID.fullmatch(item['frame_id']) or item['frame_id'] in identifiers:
+            raise ValueError('invalid or duplicate mount frame')
+        identifiers.add(item['frame_id'])
+        rows.append({'frameId': item['frame_id'], 'translationMm': vector(item['translation_mm']), 'rotationDeg': vector(item['rotation_deg'])})
+    return rows
+
+def normalize_interfaces(value, frames):
+    if value is None:
+        return []
+    if not isinstance(value, list) or len(value) > 32:
+        raise ValueError('invalid interfaces')
+    frame_ids = {item['frameId'] for item in frames}; rows, identifiers = [], set()
+    for item in value:
+        if not isinstance(item, dict) or set(item) != {'interface_id', 'frame_id', 'compatibility_key'} or \
+           not isinstance(item['interface_id'], str) or not NODE_ID.fullmatch(item['interface_id']) or item['interface_id'] in identifiers or \
+           not isinstance(item['frame_id'], str) or item['frame_id'] not in frame_ids or \
+           not isinstance(item['compatibility_key'], str) or not STABLE.fullmatch(item['compatibility_key']):
+            raise ValueError('invalid or duplicate mount interface')
+        identifiers.add(item['interface_id'])
+        rows.append({'interfaceId': item['interface_id'], 'frameId': item['frame_id'], 'compatibilityKey': item['compatibility_key']})
+    return rows
+
+def normalize_appearance_bindings(value):
+    if value is None:
+        return []
+    if not isinstance(value, list) or len(value) > 32:
+        raise ValueError('invalid appearance bindings')
+    rows, identifiers = [], set()
+    for item in value:
+        if not isinstance(item, dict) or set(item) != {'binding_id', 'material_slot'} or \
+           not isinstance(item['binding_id'], str) or not TARGET_ID.fullmatch(item['binding_id']) or item['binding_id'] in identifiers or \
+           not isinstance(item['material_slot'], str) or not STABLE.fullmatch(item['material_slot']):
+            raise ValueError('invalid or duplicate appearance binding')
+        identifiers.add(item['binding_id']); rows.append({'bindingId': item['binding_id'], 'materialSlot': item['material_slot']})
+    return rows
+
+def normalize_lineage(value):
+    if value is None:
+        return None
+    if not isinstance(value, dict) or set(value) != {'kind', 'prior_assembly_sha256', 'previous_occurrence_ids'} or value['kind'] not in ('preserved', 'replaced', 'split', 'merged') or \
+       not isinstance(value['prior_assembly_sha256'], str) or not HEX.fullmatch(value['prior_assembly_sha256']) or \
+       not isinstance(value['previous_occurrence_ids'], list) or not value['previous_occurrence_ids'] or len(value['previous_occurrence_ids']) > 128 or len(set(value['previous_occurrence_ids'])) != len(value['previous_occurrence_ids']) or \
+       any(not isinstance(item, str) or not NODE_ID.fullmatch(item) for item in value['previous_occurrence_ids']):
+        raise ValueError('invalid occurrence lineage')
+    return {'kind': value['kind'], 'priorAssemblySha256': value['prior_assembly_sha256'], 'previousOccurrenceIds': list(value['previous_occurrence_ids'])}
+
+def component_counts(occurrences):
+    counts = {}
+    for occurrence in occurrences:
+        counts[occurrence['componentId']] = counts.get(occurrence['componentId'], 0) + 1
+    return [{'componentId': key, 'count': counts[key]} for key in sorted(counts)]
+
+def occurrence_identity(occurrences):
+    return [{key: occurrence[key] for key in ('occurrenceId', 'componentId', 'bomItemId', 'source', 'geometryPrecision',
+                                                'geometrySha256', 'transformSha256', 'interfaceSha256', 'appearanceSha256',
+                                                'mountFrames', 'interfaces', 'appearanceBindings', 'lineage', 'material') if key in occurrence} for occurrence in occurrences]
+
+def normalize_material(value):
+    if not isinstance(value, dict) or set(value) != {'base_color_srgb', 'roughness', 'metallic'} or \
+       not isinstance(value['base_color_srgb'], str) or not re.fullmatch(r'#[0-9a-fA-F]{6}', value['base_color_srgb']) or \
+       any(not isinstance(value[key], (int, float)) or isinstance(value[key], bool) or \
+           not math.isfinite(value[key]) or not 0 <= value[key] <= 1 for key in ('roughness', 'metallic')):
+        raise ValueError('invalid occurrence material')
+    return {'baseColorSrgb': value['base_color_srgb'].lower(), 'roughness': float(value['roughness']), 'metallic': float(value['metallic'])}
+
+def appearance_identity(bindings, material):
+    return bindings if material is None else {'appearanceBindings': bindings, 'material': material}
+
+def material_linear_color(material):
+    channels = [int(material['baseColorSrgb'][index:index+2], 16) / 255 for index in (1, 3, 5)]
+    return [value / 12.92 if value <= 0.04045 else ((value + 0.055) / 1.055) ** 2.4 for value in channels] + [1.0]
+
+def apply_materials_to_glb(raw, assembly):
+    if not any('material' in occurrence for occurrence in assembly['occurrences']):
+        return raw
+    document = gltf_document(raw)
+    validate_occurrence_nodes(document, assembly)
+    materials = document.setdefault('materials', [])
+    for occurrence in assembly['occurrences']:
+        material = occurrence.get('material')
+        if material is None:
+            continue
+        index = len(materials)
+        materials.append({'name': 'occurrence-material:' + occurrence['occurrenceId'],
+                          'pbrMetallicRoughness': {'baseColorFactor': material_linear_color(material),
+                            'roughnessFactor': material['roughness'], 'metallicFactor': material['metallic']},
+                          'alphaMode': 'OPAQUE', 'doubleSided': True})
+        nodes = document['nodes']
+        root_index = next(index for index, node in enumerate(nodes) if node.get('name') == occurrence['occurrenceId'])
+        def assign(node_index):
+            node = nodes[node_index]
+            if 'mesh' in node:
+                mesh = json.loads(json.dumps(document['meshes'][node['mesh']]))
+                for primitive in mesh['primitives']:
+                    primitive['material'] = index
+                    primitive.get('attributes', {}).pop('COLOR_0', None)
+                node['mesh'] = len(document['meshes'])
+                document['meshes'].append(mesh)
+            for child in node.get('children', []):
+                assign(child)
+        assign(root_index)
+    encoded = json.dumps(document, separators=(',', ':'), ensure_ascii=False).encode()
+    encoded += b' ' * ((-len(encoded)) % 4)
+    tail = raw[20 + int.from_bytes(raw[12:16], 'little'):]
+    return b'glTF' + struct.pack('<II', 2, 20 + len(encoded) + len(tail)) + struct.pack('<II', len(encoded), 0x4E4F534A) + encoded + tail
+
+def inspection_number(value):
+    if not isinstance(value, (int, float)) or isinstance(value, bool) or not math.isfinite(value) or value < 0 or value > 1_000_000_000_000:
+        raise ValueError('invalid inspection threshold')
+    return float(value)
+
+def inspection_ids(value, identifiers, *, minimum=1):
+    if not isinstance(value, list) or not minimum <= len(value) <= 128 or len(set(value)) != len(value) or any(not isinstance(item, str) or item not in identifiers for item in value):
+        raise ValueError('invalid inspection occurrence list')
+    return list(value)
+
+def not_applicable(value):
+    if not isinstance(value, dict) or set(value) != {'applicable', 'reason'} or value['applicable'] is not False or not isinstance(value['reason'], str) or not value['reason'].strip() or len(value['reason']) > 300:
+        return None
+    return {'kind': 'not_applicable', 'reason': value['reason'].strip()}
+
+def normalize_inspection_geometry(raw, occurrences, source_sha256):
+    """Inspection bodies travel separately; they are never product occurrences."""
+    if raw is None:
+        return None, None
+    if not isinstance(raw, list) or not 1 <= len(raw) <= 32:
+        raise ValueError('invalid inspection geometry')
+    owners = {item['occurrenceId']: item for item in occurrences}
+    identifiers, shell_ids, regions, shells, breps = set(owners), set(), [], [], {}
+    for item in raw:
+        if not isinstance(item, dict) or set(item) != {'shell', 'outer', 'cavity', 'openings'} or item['shell'] not in owners or item['shell'] in shell_ids:
+            raise ValueError('invalid inspection shell')
+        owner = owners[item['shell']]
+        if owner['geometryPrecision'] != 'custom_brep':
+            raise ValueError('inspection shell must be actual custom BRep')
+        shell_ids.add(item['shell'])
+        if not isinstance(item['openings'], list) or len(item['openings']) > 32:
+            raise ValueError('invalid inspection openings')
+
+        def register(region, kind):
+            if not isinstance(region, dict) or set(region) != {'region_id', 'shape'} or not isinstance(region['region_id'], str) or not NODE_ID.fullmatch(region['region_id']) or region['region_id'] in identifiers or not isinstance(region['shape'], bd.Shape):
+                raise ValueError('invalid or duplicate inspection region')
+            region_id = region['region_id']; identifiers.add(region_id)
+            stream = BytesIO(); bd.export_brep(region['shape'], stream); body = stream.getvalue()
+            if not body:
+                raise ValueError('empty inspection BRep')
+            breps[region_id] = base64.b64encode(body).decode('ascii')
+            regions.append({'regionId': region_id, 'kind': kind, 'ownerOccurrenceId': owner['occurrenceId'], 'brepSha256': digest(body)})
+            return region_id
+
+        outer_id, cavity_id = register(item['outer'], 'outer'), register(item['cavity'], 'cavity')
+        opening_ids = [register(region, 'opening') for region in item['openings']]
+        shells.append({'occurrenceId': owner['occurrenceId'], 'geometrySha256': owner['geometrySha256'],
+                       'transformSha256': owner['transformSha256'], 'outerRegionId': outer_id,
+                       'cavityRegionId': cavity_id, 'openingRegionIds': opening_ids})
+    if len(regions) > 128 or sum(len(value) for value in breps.values()) > 12 * 1024 * 1024:
+        raise ValueError('inspection geometry exceeds bound')
+    return {'schema': 'abelien.structure-inspection-geometry.v1', 'sourceSha256': source_sha256,
+            'regions': regions, 'shells': shells}, breps
+
+def normalize_inspection(raw, occurrences, geometry=None):
+    identifiers = {item['occurrenceId'] for item in occurrences}
+    regions = {item['regionId']: item['kind'] for item in geometry['regions']} if geometry else {}
+    keys = {'collision', 'containment', 'openings', 'motion_envelopes'}
+    if raw is not None and (not isinstance(raw, dict) or not set(raw).issubset(keys)):
+        raise ValueError('invalid inspection plan')
+    raw = raw or {}
+
+    collision = raw.get('collision')
+    if collision is not None:
+        omitted = not_applicable(collision)
+        if omitted:
+            collision = omitted
+        else:
+            if not isinstance(collision, dict) or set(collision) != {'occurrence_ids', 'allowed_pairs', 'maximum_overlap_mm3'}:
+                raise ValueError('invalid collision inspection')
+            occurrence_ids = inspection_ids(collision['occurrence_ids'], identifiers, minimum=2)
+            pairs, seen = [], set()
+            if not isinstance(collision['allowed_pairs'], list) or len(collision['allowed_pairs']) > 8128:
+                raise ValueError('invalid collision allowed pairs')
+            for pair in collision['allowed_pairs']:
+                if not isinstance(pair, list) or len(pair) != 2 or pair[0] == pair[1] or any(item not in occurrence_ids for item in pair):
+                    raise ValueError('invalid collision allowed pair')
+                normalized = tuple(sorted(pair))
+                if normalized in seen:
+                    raise ValueError('duplicate collision allowed pair')
+                seen.add(normalized); pairs.append(list(normalized))
+            collision = {'kind': 'rules', 'occurrenceIds': occurrence_ids, 'allowedPairs': sorted(pairs),
+                         'maximumOverlapMm3': inspection_number(collision['maximum_overlap_mm3'])}
+
+    def normalize_rules(name, output_name, required, normalize):
+        value = raw.get(name)
+        if value is None:
+            return None
+        omitted = not_applicable(value)
+        if omitted:
+            return omitted
+        if not isinstance(value, list) or not value or len(value) > 128:
+            raise ValueError(f'invalid {name} inspection')
+        rows = []
+        for item in value:
+            if not isinstance(item, dict) or set(item) != required:
+                raise ValueError(f'invalid {name} inspection rule')
+            rows.append(normalize(item))
+        return {'kind': 'rules', output_name: rows}
+
+    def containment_rule(item):
+        container = item['container']
+        if not isinstance(container, str) or (container not in identifiers and regions.get(container) != 'cavity'):
+            raise ValueError('invalid containment container')
+        targets = inspection_ids(item['targets'], identifiers)
+        if container in targets:
+            raise ValueError('containment target cannot be its container')
+        return {'container': container, 'targets': targets, 'maximumOutsideMm3': inspection_number(item['maximum_outside_mm3'])}
+
+    def opening_rule(item):
+        opening, target = item['opening'], item['target']
+        if not isinstance(opening, str) or not isinstance(target, str) or (opening not in identifiers and regions.get(opening) != 'opening') or target not in identifiers or opening == target:
+            raise ValueError('invalid opening inspection identities')
+        if opening in regions and inspection_number(item['minimum_overlap_mm3']) <= 0:
+            raise ValueError('inspection opening needs positive target overlap')
+        return {'opening': opening, 'target': target, 'maximumDistanceMm': inspection_number(item['maximum_distance_mm']),
+                'minimumOverlapMm3': inspection_number(item['minimum_overlap_mm3'])}
+
+    def motion_rule(item):
+        envelope = item['envelope']
+        if not isinstance(envelope, str) or envelope not in identifiers:
+            raise ValueError('invalid motion envelope')
+        obstacles = inspection_ids(item['obstacles'], identifiers)
+        if envelope in obstacles:
+            raise ValueError('motion envelope cannot obstruct itself')
+        return {'envelope': envelope, 'obstacles': obstacles, 'maximumOverlapMm3': inspection_number(item['maximum_overlap_mm3'])}
+
+    containment = normalize_rules('containment', 'rules', {'container', 'targets', 'maximum_outside_mm3'}, containment_rule)
+    openings = normalize_rules('openings', 'rules', {'opening', 'target', 'maximum_distance_mm', 'minimum_overlap_mm3'}, opening_rule)
+    motion = normalize_rules('motion_envelopes', 'rules', {'envelope', 'obstacles', 'maximum_overlap_mm3'}, motion_rule)
+    return {'schema': 'abelien.structure-inspection-plan.v2' if geometry else 'abelien.structure-inspection-plan.v1',
+            'collision': collision, 'containment': containment, 'openings': openings, 'motionEnvelopes': motion,
+            **({'inspectionGeometry': geometry} if geometry else {})}
+
+def revision_not_applicable():
+    return {name: {'status': 'not_applicable', 'method': 'declared_not_applicable', 'reason': 'initial_build', 'findings': []}
+            for name in ('delta', 'preservation', 'mount')}
+
+def rotation_matrix(degrees):
+    x, y, z = (math.radians(value) for value in degrees)
+    cx, sx, cy, sy, cz, sz = math.cos(x), math.sin(x), math.cos(y), math.sin(y), math.cos(z), math.sin(z)
+    return [[cy * cz, -cy * sz, sy],
+            [sx * sy * cz + cx * sz, -sx * sy * sz + cx * cz, -sx * cy],
+            [-cx * sy * cz + sx * sz, cx * sy * sz + sx * cz, cx * cy]]
+
+def matrix_multiply(left, right):
+    return [[sum(left[row][axis] * right[axis][column] for axis in range(3)) for column in range(3)] for row in range(3)]
+
+def matrix_vector(matrix, vector):
+    return [sum(matrix[row][axis] * vector[axis] for axis in range(3)) for row in range(3)]
+
+def matrix_transpose(matrix):
+    return [[matrix[column][row] for column in range(3)] for row in range(3)]
+
+def vector_add(left, right):
+    return [left[index] + right[index] for index in range(3)]
+
+def vector_subtract(left, right):
+    return [left[index] - right[index] for index in range(3)]
+
+def frame_matrix(occurrence, frame_id):
+    frame = next((item for item in occurrence['mountFrames'] if item['frameId'] == frame_id), None)
+    if frame is None:
+        raise ValueError('mount alignment frame missing')
+    normal = occurrence['views']['normal']
+    normal_rotation = rotation_matrix(normal['rotationDeg'])
+    frame_rotation = rotation_matrix(frame['rotationDeg'])
+    rotation = matrix_multiply(normal_rotation, frame_rotation)
+    position = vector_add(normal['translationMm'], matrix_vector(normal_rotation, frame['translationMm']))
+    return [rotation[row] + [position[row]] for row in range(3)]
+
+def euler_degrees(rotation):
+    # Inverse of rotation_matrix for the same Rx * Ry * Rz convention.  The
+    # singular branch is deterministic; mount checks reject any residual error.
+    y = math.asin(max(-1.0, min(1.0, rotation[0][2])))
+    cy = math.cos(y)
+    if abs(cy) > 1e-9:
+        x = math.atan2(-rotation[1][2], rotation[2][2])
+        z = math.atan2(-rotation[0][1], rotation[0][0])
+    else:
+        x = math.atan2(rotation[2][1], rotation[1][1])
+        z = 0.0
+    return [0.0 if abs(value) < 1e-12 else math.degrees(value) for value in (x, y, z)]
+
+def apply_rigid_transform(view, correction_rotation, correction_translation):
+    view_rotation = rotation_matrix(view['rotationDeg'])
+    rotation = matrix_multiply(correction_rotation, view_rotation)
+    position = [0.0 if abs(value) < 1e-12 else value
+                for value in vector_add(matrix_vector(correction_rotation, view['translationMm']), correction_translation)]
+    return {'translationMm': position, 'rotationDeg': euler_degrees(rotation), 'visible': view['visible']}
+
+def auto_align_mounts(previous, current, alignments):
+    """Move each replaced occurrence onto its prior mount frame without scaling.
+
+    The correction is a rigid transform in assembly space and is applied to all
+    views, so STEP, GLB and rendered views are generated from the same corrected
+    assembly. Ambiguous many-to-one mount requests fail closed.
+    """
+    aligned_targets = set()
+    for alignment in alignments:
+        previous_id, next_id = alignment['previousOccurrenceId'], alignment['nextOccurrenceId']
+        if next_id in aligned_targets:
+            raise ValueError('mount alignment target is ambiguous')
+        aligned_targets.add(next_id)
+        before, after = previous[previous_id], current[next_id]
+        compatible_before = any(item['frameId'] == alignment['previousFrameId'] and item['compatibilityKey'] == alignment['compatibilityKey'] for item in before['interfaces'])
+        compatible_after = any(item['frameId'] == alignment['nextFrameId'] and item['compatibilityKey'] == alignment['compatibilityKey'] for item in after['interfaces'])
+        if not compatible_before or not compatible_after:
+            raise ValueError('mount interface incompatible or misaligned')
+        before_frame = frame_matrix(before, alignment['previousFrameId'])
+        after_frame = frame_matrix(after, alignment['nextFrameId'])
+        before_rotation = [row[:3] for row in before_frame]
+        after_rotation = [row[:3] for row in after_frame]
+        before_position = [row[3] for row in before_frame]
+        after_position = [row[3] for row in after_frame]
+        correction_rotation = matrix_multiply(before_rotation, matrix_transpose(after_rotation))
+        correction_translation = vector_subtract(before_position, matrix_vector(correction_rotation, after_position))
+        for view_name in VIEWS:
+            after['views'][view_name] = apply_rigid_transform(after['views'][view_name], correction_rotation, correction_translation)
+        after['transformSha256'] = digest(after['views'])
+    return aligned_targets
+
+def frame_errors(previous, next_value):
+    translation = math.sqrt(sum((previous[row][3] - next_value[row][3]) ** 2 for row in range(3)))
+    relative_trace = sum(sum(previous[row][axis] * next_value[row][axis] for row in range(3)) for axis in range(3))
+    angle = math.degrees(math.acos(max(-1.0, min(1.0, (relative_trace - 1.0) / 2.0))))
+    return translation, angle
+
+def validate_revision(prior, occurrences, revision):
+    if revision is None:
+        if any(item['lineage'] is not None for item in occurrences):
+            raise ValueError('initial assembly cannot claim revision lineage')
+        return None, revision_not_applicable()
+    if not isinstance(prior, dict) or prior.get('schema') != 'abelien.structure-assembly.v2' or prior.get('mode') != 'occurrence_assembly':
+        raise ValueError('revision prior assembly unavailable')
+    public_keys = {'schema', 'prior', 'targetOccurrenceIds', 'allowedChanges', 'preserveOccurrenceIds',
+                   'preserveAppearanceTargetIds', 'appearanceTargetBindings', 'replacementMappings', 'mountAlignments', 'requestSha256'}
+    if not isinstance(revision, dict) or set(revision) != public_keys | {'priorAssembly'} or revision.get('schema') != 'abelien.structure-revision.v1' or revision.get('priorAssembly') != prior:
+        raise ValueError('invalid revision request')
+    summary = {key: revision[key] for key in public_keys}
+    unsigned = dict(summary); request_sha256 = unsigned.pop('requestSha256', None)
+    if not isinstance(request_sha256, str) or request_sha256 != digest(unsigned):
+        raise ValueError('revision request hash mismatch')
+    prior_subject = summary['prior']
+    if not isinstance(prior_subject, dict) or set(prior_subject) != {'jobId', 'sourceSha256', 'assemblySha256', 'occurrenceSetSha256'} or \
+       prior_subject['sourceSha256'] != prior.get('sourceSha256') or prior_subject['assemblySha256'] != prior.get('assemblySha256') or prior_subject['occurrenceSetSha256'] != prior.get('occurrenceSetSha256'):
+        raise ValueError('revision prior subject mismatch')
+    previous = {item['occurrenceId']: item for item in prior['occurrences']}; current = {item['occurrenceId']: item for item in occurrences}
+    targets, preserved = summary['targetOccurrenceIds'], summary['preserveOccurrenceIds']
+    if not isinstance(targets, list) or not targets or not isinstance(preserved, list) or len(set(targets)) != len(targets) or len(set(preserved)) != len(preserved) or set(targets) & set(preserved) or set(targets) | set(preserved) != set(previous):
+        raise ValueError('revision target/preserve partition invalid')
+    if not isinstance(summary['allowedChanges'], list) or not summary['allowedChanges'] or len(set(summary['allowedChanges'])) != len(summary['allowedChanges']) or any(item not in REVISION_CHANGES for item in summary['allowedChanges']):
+        raise ValueError('revision allowed changes invalid')
+    alignments = summary['mountAlignments']
+    if not isinstance(alignments, list) or len(alignments) > 128:
+        raise ValueError('invalid mount alignments')
+    aligned_targets = auto_align_mounts(previous, current, alignments)
+    mappings = summary['replacementMappings']
+    if not isinstance(mappings, list) or not mappings or len(mappings) > 128:
+        raise ValueError('revision replacement mappings missing')
+    previous_seen, next_seen, delta_findings = set(), set(), []
+    digest_fields = {'geometry': 'geometrySha256', 'transform': 'transformSha256', 'interfaces': 'interfaceSha256', 'appearance_mapping': 'appearanceSha256'}
+    for mapping in mappings:
+        if not isinstance(mapping, dict) or set(mapping) != {'kind', 'previousOccurrenceIds', 'nextOccurrenceIds'} or mapping['kind'] not in ('preserved', 'replaced', 'split', 'merged'):
+            raise ValueError('invalid replacement mapping')
+        old_ids, new_ids = mapping['previousOccurrenceIds'], mapping['nextOccurrenceIds']
+        if not isinstance(old_ids, list) or not old_ids or not isinstance(new_ids, list) or not new_ids or len(set(old_ids)) != len(old_ids) or len(set(new_ids)) != len(new_ids) or any(item not in previous for item in old_ids) or any(item not in current for item in new_ids) or previous_seen.intersection(old_ids) or next_seen.intersection(new_ids):
+            raise ValueError('invalid replacement mapping identity')
+        if mapping['kind'] in ('preserved', 'replaced') and (len(old_ids) != 1 or len(new_ids) != 1) or mapping['kind'] == 'split' and (len(old_ids) != 1 or len(new_ids) < 2) or mapping['kind'] == 'merged' and (len(old_ids) < 2 or len(new_ids) != 1):
+            raise ValueError('replacement mapping cardinality mismatch')
+        previous_seen.update(old_ids); next_seen.update(new_ids)
+        changed = []
+        for change, field in digest_fields.items():
+            before = sorted(previous[item][field] for item in old_ids); after = sorted(current[item][field] for item in new_ids)
+            # A mount correction is a server-derived rigid transform, not an
+            # independently authorized user change. The corrected pose is
+            # still recorded in the manifest and checked below.
+            derived_transform = change == 'transform' and all(item in aligned_targets for item in new_ids)
+            if before != after and not derived_transform:
+                changed.append(change)
+        if any(change not in summary['allowedChanges'] for change in changed):
+            raise ValueError('revision changed a field outside allowed changes')
+        delta_findings.append({'kind': mapping['kind'], 'previousOccurrenceIds': old_ids, 'nextOccurrenceIds': new_ids, 'changes': changed})
+        for next_id in new_ids:
+            lineage = current[next_id]['lineage']
+            if lineage != {'kind': mapping['kind'], 'priorAssemblySha256': prior['assemblySha256'], 'previousOccurrenceIds': old_ids}:
+                raise ValueError('occurrence lineage does not match replacement mapping')
+    if previous_seen != set(previous) or next_seen != set(current):
+        raise ValueError('revision mapping does not cover complete assemblies')
+    # Source/report versions, presentation views and interface labels alone
+    # cannot turn an unchanged physical target into a repaired candidate.
+    physical_change = False
+    for mapping in mappings:
+        old_ids, new_ids = mapping['previousOccurrenceIds'], mapping['nextOccurrenceIds']
+        if not set(old_ids).intersection(targets):
+            continue
+        for change, identity in (
+                ('geometry', lambda item: item['geometrySha256']),
+                ('transform', lambda item: digest(item['views']['normal'])),
+                ('appearance_mapping', lambda item: digest(item.get('material')))):
+            if change in summary['allowedChanges'] and sorted(identity(previous[item]) for item in old_ids) != sorted(identity(current[item]) for item in new_ids):
+                physical_change = True
+    if not physical_change:
+        raise ValueError('revision target has no authorized physical change')
+    preservation_findings = []
+    for occurrence_id in preserved:
+        mapping = next((item for item in mappings if item['previousOccurrenceIds'] == [occurrence_id]), None)
+        if not mapping or mapping['kind'] != 'preserved' or mapping['nextOccurrenceIds'] != [occurrence_id]:
+            raise ValueError('preserved occurrence mapping invalid')
+        before, after = previous[occurrence_id], current[occurrence_id]
+        result = {'previousOccurrenceId': occurrence_id, 'nextOccurrenceId': occurrence_id,
+                  'geometryPreserved': before['geometrySha256'] == after['geometrySha256'],
+                  'transformPreserved': before['transformSha256'] == after['transformSha256'],
+                  'interfacesPreserved': before['interfaceSha256'] == after['interfaceSha256'],
+                  'appearancePreserved': before['appearanceSha256'] == after['appearanceSha256']}
+        if not all(value for key, value in result.items() if key.endswith('Preserved')):
+            raise ValueError('preserved occurrence changed')
+        preservation_findings.append(result)
+    appearance_targets = summary['preserveAppearanceTargetIds']
+    appearance_bindings = summary['appearanceTargetBindings']
+    if not isinstance(appearance_targets, list) or len(appearance_targets) > 512 or len(set(appearance_targets)) != len(appearance_targets) or any(not isinstance(item, str) or not TARGET_ID.fullmatch(item) for item in appearance_targets) or \
+       not isinstance(appearance_bindings, list) or len(appearance_bindings) != len(appearance_targets):
+        raise ValueError('appearance preservation target invalid')
+    seen_appearance_targets = set()
+    for index, binding in enumerate(appearance_bindings):
+        if not isinstance(binding, dict) or set(binding) != {'targetId', 'occurrenceId'} or binding['targetId'] != appearance_targets[index] or \
+           not isinstance(binding['targetId'], str) or not TARGET_ID.fullmatch(binding['targetId']) or binding['targetId'] in seen_appearance_targets or \
+           not isinstance(binding['occurrenceId'], str) or binding['occurrenceId'] not in previous:
+            raise ValueError('appearance target binding invalid')
+        seen_appearance_targets.add(binding['targetId'])
+        mapping = next((item for item in mappings if binding['occurrenceId'] in item['previousOccurrenceIds']), None)
+        if mapping is None or len(mapping['previousOccurrenceIds']) != 1 or len(mapping['nextOccurrenceIds']) != 1 or \
+           previous[binding['occurrenceId']]['appearanceSha256'] != current[mapping['nextOccurrenceIds'][0]]['appearanceSha256']:
+            raise ValueError('appearance binding was not preserved')
+    mount_findings = []
+    for alignment in alignments:
+        required = {'previousOccurrenceId', 'previousFrameId', 'nextOccurrenceId', 'nextFrameId', 'compatibilityKey'}
+        if not isinstance(alignment, dict) or set(alignment) != required or alignment['previousOccurrenceId'] not in previous or alignment['nextOccurrenceId'] not in current or not isinstance(alignment['compatibilityKey'], str) or not STABLE.fullmatch(alignment['compatibilityKey']):
+            raise ValueError('invalid mount alignment')
+        before, after = previous[alignment['previousOccurrenceId']], current[alignment['nextOccurrenceId']]
+        compatible_before = any(item['frameId'] == alignment['previousFrameId'] and item['compatibilityKey'] == alignment['compatibilityKey'] for item in before['interfaces'])
+        compatible_after = any(item['frameId'] == alignment['nextFrameId'] and item['compatibilityKey'] == alignment['compatibilityKey'] for item in after['interfaces'])
+        translation_error, rotation_error = frame_errors(frame_matrix(before, alignment['previousFrameId']), frame_matrix(after, alignment['nextFrameId']))
+        finding = {**alignment, 'translationErrorMm': translation_error, 'rotationErrorDeg': rotation_error,
+                   'compatible': compatible_before and compatible_after, 'aligned': translation_error <= 1e-6 and rotation_error <= 1e-6}
+        if not finding['compatible'] or not finding['aligned']:
+            raise ValueError('mount interface incompatible or misaligned')
+        mount_findings.append(finding)
+    checks = {
+        'delta': {'status': 'pass', 'method': 'manifest_digest', 'reason': None, 'findings': delta_findings},
+        'preservation': {'status': 'pass', 'method': 'manifest_digest', 'reason': None, 'findings': preservation_findings},
+        'mount': {'status': 'pass', 'method': 'frame_alignment', 'reason': None, 'findings': mount_findings},
+    }
+    return summary, checks
+
+def local_geometry(shape):
+    """Bake the source Shape's own rigid location, leaving the occurrence pose separate."""
+    if shape.location.wrapped.IsIdentity():
+        return shape
+    from OCP.BRepBuilderAPI import BRepBuilderAPI_Transform
+    unlocated = shape.located(bd.Location())
+    # Copy the geometry so OCCT does not merely return another top-level Location.
+    # Unlike a general affine transform this preserves analytic planes/cylinders.
+    return bd.Compound.cast(BRepBuilderAPI_Transform(
+        unlocated.wrapped, shape.location.wrapped.Transformation(), True).Shape())
+
+
+def draft_manifest(scope, source_sha256, revision=None):
+    raw = scope.get('assembly')
+    if raw is None:
+        if scope.get('inspection_geometry') is not None:
+            raise ValueError('inspection geometry requires occurrence assembly')
+        model = scope.get('result')
+        if not isinstance(model, bd.Shape):
+            raise ValueError('source must assign assembly occurrences or a legacy Shape to result')
+        model.label = 'legacy-shape'
+        identity = {'translationMm': [0.0, 0.0, 0.0], 'rotationDeg': [0.0, 0.0, 0.0], 'visible': True}
+        views = {name: dict(identity) for name in VIEWS}
+        occurrence = {'occurrenceId': 'legacy-shape', 'componentId': 'legacy:unverified-shape', 'bomItemId': None,
+                      'label': 'Legacy single shape', 'source': {'kind': 'legacy_unverified', 'sha256': source_sha256},
+                      'geometryPrecision': 'legacy_unverified', 'geometrySha256': shape_digest(model), 'transformSha256': digest(views),
+                      'interfaceSha256': digest({'mountFrames': [], 'interfaces': []}), 'appearanceSha256': digest([]),
+                      'mountFrames': [], 'interfaces': [], 'appearanceBindings': [], 'lineage': None, 'views': views}
+        inspection = normalize_inspection(scope.get('inspection'), [occurrence])
+        summary, revision_checks = validate_revision(None, [occurrence], revision)
+        return model, {'schema': 'abelien.structure-assembly.v2', 'mode': 'legacy_shape', 'status': 'legacy_unverified',
+                       'units': 'mm', 'coordinateSystem': 'z_up', 'transformSpace': 'assembly_root_mm', 'sourceSha256': source_sha256,
+                       'revision': summary,
+                       'inspectionPlanSha256': digest(inspection), 'occurrenceCount': 1, 'componentCounts': component_counts([occurrence]), 'occurrences': [occurrence],
+                       'deferredChecks': {name: {'status': 'unverified', 'gating': False} for name in DEFERRED}}, inspection, revision_checks, None
+    if not isinstance(raw, list) or not 2 <= len(raw) <= 128:
+        raise ValueError('assembly must contain 2..128 occurrences')
+    occurrences, shapes, shapes_by_id, identifiers = [], [], {}, set()
+    required = {'occurrence_id', 'component_id', 'bom_item_id', 'label', 'shape', 'geometry_precision', *VIEWS}
+    optional = {'mount_frames', 'interfaces', 'appearance_bindings', 'lineage', 'material'}
+    for item in raw:
+        if not isinstance(item, dict) or not required.issubset(item) or not set(item).issubset(required | optional):
+            raise ValueError('invalid assembly occurrence')
+        occurrence_id, component_id, bom_item_id = item['occurrence_id'], item['component_id'], item['bom_item_id']
+        if not isinstance(occurrence_id, str) or not NODE_ID.fullmatch(occurrence_id) or occurrence_id in identifiers or not isinstance(component_id, str) or not STABLE.fullmatch(component_id) or not isinstance(bom_item_id, str) or not STABLE.fullmatch(bom_item_id):
+            raise ValueError('invalid or duplicate assembly identity')
+        # Separate reasons: a merged message once led the model to rewrite a valid Shape for an over-long label.
+        if not isinstance(item['label'], str) or not item['label'].strip():
+            raise ValueError(f'assembly occurrence {occurrence_id} label must be a non-empty string')
+        if len(item['label']) > 128:
+            raise ValueError(f'assembly occurrence {occurrence_id} label has {len(item["label"])} characters; maximum is 128')
+        if not isinstance(item['shape'], bd.Shape):
+            raise ValueError(f'assembly occurrence {occurrence_id} shape must be a build123d Shape, not {type(item["shape"]).__name__}')
+        if item['geometry_precision'] not in ('custom_brep', 'envelope'):
+            raise ValueError('unsupported geometry precision')
+        views = {name: transform(item[name], normal=name == 'normal') for name in VIEWS}
+        mount_frames = normalize_mount_frames(item.get('mount_frames')); interfaces = normalize_interfaces(item.get('interfaces'), mount_frames)
+        appearance_bindings = normalize_appearance_bindings(item.get('appearance_bindings')); lineage = normalize_lineage(item.get('lineage'))
+        material = normalize_material(item['material']) if 'material' in item else None
+        shapes_by_id[occurrence_id] = item['shape']
+        identifiers.add(occurrence_id)
+        occurrences.append({'occurrenceId': occurrence_id, 'componentId': component_id, 'bomItemId': bom_item_id,
+                            'label': item['label'].strip(),
+                            'source': {'kind': 'generated_envelope' if item['geometry_precision'] == 'envelope' else 'generated_custom', 'sha256': source_sha256},
+                            'geometryPrecision': item['geometry_precision'], 'geometrySha256': shape_digest(item['shape']),
+                            'transformSha256': digest(views), 'interfaceSha256': digest({'mountFrames': mount_frames, 'interfaces': interfaces}),
+                            'appearanceSha256': digest(appearance_identity(appearance_bindings, material)), 'mountFrames': mount_frames, 'interfaces': interfaces,
+                            'appearanceBindings': appearance_bindings, 'lineage': lineage, 'views': views,
+                            **({'material': material} if material is not None else {})})
+    if not any(occurrence['views']['internal'] != occurrence['views']['normal'] for occurrence in occurrences):
+        raise ValueError('internal view must differ from normal assembly')
+    if not any(occurrence['views']['exploded'] != occurrence['views']['normal'] for occurrence in occurrences):
+        raise ValueError('exploded view must differ from normal assembly')
+    if any(not occurrence['views']['exploded']['visible'] for occurrence in occurrences):
+        raise ValueError('exploded view must keep every occurrence visible')
+    if any(not any(occurrence['views'][name]['visible'] for occurrence in occurrences) for name in VIEWS):
+        raise ValueError('every assembly view must keep at least one visible occurrence')
+    prior = revision.get('priorAssembly') if isinstance(revision, dict) else None
+    summary, revision_checks = validate_revision(prior, occurrences, revision)
+    if summary is not None:
+        previous = {item['occurrenceId']: item for item in prior['occurrences']}
+        for occurrence in occurrences:
+            if occurrence['lineage']['kind'] == 'preserved':
+                occurrence['source'] = previous[occurrence['lineage']['previousOccurrenceIds'][0]]['source']
+    geometry, breps = normalize_inspection_geometry(scope.get('inspection_geometry'), occurrences, source_sha256)
+    inspection = normalize_inspection(scope.get('inspection'), occurrences, geometry)
+    for occurrence in occurrences:
+        normal = occurrence['views']['normal']
+        placed = local_geometry(shapes_by_id[occurrence['occurrenceId']]).moved(bd.Location(tuple(normal['translationMm']), tuple(normal['rotationDeg'])))
+        placed.label = occurrence['occurrenceId']
+        shapes.append(placed)
+    model = bd.Compound(children=shapes); model.label = 'assembly'
+    return model, {'schema': 'abelien.structure-assembly.v2', 'mode': 'occurrence_assembly', 'status': 'candidate',
+                   'units': 'mm', 'coordinateSystem': 'z_up', 'transformSpace': 'assembly_root_mm', 'sourceSha256': source_sha256,
+                   'revision': summary,
+                   'inspectionPlanSha256': digest(inspection),
+                   'occurrenceCount': len(occurrences), 'componentCounts': component_counts(occurrences), 'occurrences': occurrences,
+                   'deferredChecks': {name: {'status': 'unverified', 'gating': False} for name in DEFERRED}}, inspection, revision_checks, breps
+
+def transform_set(occurrences, view):
+    return [{'occurrenceId': occurrence['occurrenceId'], 'transform': occurrence['views'][view]} for occurrence in occurrences]
+
+def final_manifest(draft, step_bytes, glb_bytes, view_images):
+    result = dict(draft)
+    result['occurrenceSetSha256'] = digest(occurrence_identity(result['occurrences']))
+    result['artifacts'] = {'modelStepSha256': digest(step_bytes), 'modelGlbSha256': digest(glb_bytes)}
+    reset = digest(transform_set(result['occurrences'], 'normal'))
+    result['views'] = {name: {'modelGlbSha256': result['artifacts']['modelGlbSha256'],
+                              'occurrenceSetSha256': result['occurrenceSetSha256'],
+                              'artifactName': f'{name}.png', 'imageSha256': digest(view_images[name]),
+                              'transformSetSha256': digest(transform_set(result['occurrences'], name)),
+                              'resetTransformSetSha256': reset, 'scale': 1.0,
+                              'labels': ([{'occurrenceId': occurrence['occurrenceId'], 'bomItemId': occurrence['bomItemId']}
+                                          for occurrence in result['occurrences'] if occurrence['bomItemId'] is not None]
+                                         if name == 'exploded' else [])} for name in VIEWS}
+    result['assemblySha256'] = digest(result)
+    return result
+
+def gltf_document(raw):
+    if len(raw) < 20 or raw[:4] != b'glTF' or int.from_bytes(raw[8:12], 'little') != len(raw) or int.from_bytes(raw[16:20], 'little') != 0x4E4F534A:
+        raise ValueError('invalid GLB')
+    length = int.from_bytes(raw[12:16], 'little')
+    document = json.loads(raw[20:20 + length].decode().rstrip('\0 '))
+    if not document.get('meshes') or not isinstance(document.get('nodes'), list):
+        raise ValueError('GLB contains no addressable meshes')
+    return document
+
+def validate_occurrence_nodes(document, manifest):
+    if manifest['mode'] != 'occurrence_assembly':
+        return
+    nodes = document['nodes']
+    scenes = document.get('scenes'); scene_index = document.get('scene', 0)
+    if not isinstance(scenes, list) or not isinstance(scene_index, int) or scene_index < 0 or scene_index >= len(scenes) or not isinstance(scenes[scene_index].get('nodes'), list) or not scenes[scene_index]['nodes']:
+        raise ValueError('GLB has no active assembly scene')
+    parents = {}
+    for index, node in enumerate(nodes):
+        for child in node.get('children', []):
+            if not isinstance(child, int) or child in parents:
+                raise ValueError('invalid GLB hierarchy')
+            parents[child] = index
+    reachable = set()
+    def visit(index):
+        if not isinstance(index, int) or index < 0 or index >= len(nodes) or index in reachable:
+            return
+        reachable.add(index)
+        for child in nodes[index].get('children', []):
+            visit(child)
+    for root_index in scenes[scene_index]['nodes']:
+        visit(root_index)
+    near = lambda left, right: isinstance(left, (int, float)) and math.isfinite(left) and abs(left - right) < 1e-9
+    def quaternion(rotation_deg):
+        x, y, z = (math.radians(value) / 2 for value in rotation_deg)
+        sx, cx, sy, cy, sz, cz = math.sin(x), math.cos(x), math.sin(y), math.cos(y), math.sin(z), math.cos(z)
+        return [sx*cy*cz + cx*sy*sz, cx*sy*cz - sx*cy*sz, cx*cy*sz + sx*sy*cz, cx*cy*cz - sx*sy*sz]
+    def same_quaternion(actual, expected):
+        return isinstance(actual, list) and len(actual) == 4 and (all(near(actual[index], expected[index]) for index in range(4)) or all(near(actual[index], -expected[index]) for index in range(4)))
+    def occurrence_pose(node, normal):
+        translation = node.get('translation', [0, 0, 0]); rotation = node.get('rotation', [0, 0, 0, 1]); scale = node.get('scale', [1, 1, 1])
+        return node.get('matrix') is None and isinstance(translation, list) and len(translation) == 3 and all(near(translation[index], normal['translationMm'][index] / 1000) for index in range(3)) and \
+               same_quaternion(rotation, quaternion(normal['rotationDeg'])) and isinstance(scale, list) and len(scale) == 3 and all(near(item, 1) for item in scale)
+    def assembly_root(node):
+        expected = [-math.sqrt(0.5), 0, 0, math.sqrt(0.5)]
+        return node.get('name') == 'assembly-root' and node.get('matrix') is None and node.get('translation') is None and node.get('scale') is None and same_quaternion(node.get('rotation'), expected) and not isinstance(node.get('mesh'), int)
+    def has_mesh(index, seen):
+        if not isinstance(index, int) or index < 0 or index >= len(nodes) or index in seen:
+            return False
+        seen.add(index); node = nodes[index]
+        return isinstance(node.get('mesh'), int) or any(has_mesh(child, seen) for child in node.get('children', []))
+    mapped = []
+    for occurrence in manifest['occurrences']:
+        matching = [index for index, node in enumerate(nodes) if node.get('name') == occurrence['occurrenceId']]
+        if len(matching) != 1 or matching[0] not in reachable or not has_mesh(matching[0], set()) or not occurrence_pose(nodes[matching[0]], occurrence['views']['normal']):
+            raise ValueError('GLB occurrence mapping lost during export')
+        mapped.append(matching[0])
+    root_indices = {parents.get(index) for index in mapped}
+    if len(root_indices) != 1 or None in root_indices:
+        raise ValueError('GLB occurrences do not share one assembly root')
+    root_index = next(iter(root_indices)); root_node = nodes[root_index]
+    if root_index not in scenes[scene_index]['nodes'] or root_index in parents or scenes[scene_index]['nodes'] != [root_index] or not assembly_root(root_node) or root_node.get('children') != mapped:
+        raise ValueError('GLB assembly root transform is not the fixed Build123d basis')
+
+def scene_rows(children, manifest, view):
+    if manifest['mode'] == 'legacy_shape':
+        return [(manifest['occurrences'][0], children[0])]
+    rows = []
+    for occurrence, child in zip(manifest['occurrences'], children):
+        pose = occurrence['views'][view]
+        if pose['visible']:
+            rows.append((occurrence, child.located(bd.Location(tuple(pose['translationMm']), tuple(pose['rotationDeg'])))))
+    return rows
+
+def scene_mesh(rows, tolerance):
+    meshes, total = [], 0
+    for occurrence, shape in rows:
+        vertices, faces = shape.tessellate(tolerance); total += len(faces)
+        if total > 200000:
+            raise ValueError('render complexity budget exceeded')
+        points = np.asarray([tuple(point) for point in vertices]); triangles = points[np.asarray(faces)]
+        meshes.append((occurrence, triangles, tuple(shape.bounding_box().center())))
+    if not meshes:
+        raise ValueError('assembly view has no visible geometry')
+    return meshes
+
+def render_scene(root, name, mesh, elevation, azimuth, *, labels=False):
+    # Painter-order collections cannot resolve an enclosed component against a
+    # hollow shell. Orthographic per-pixel depth uses the actual readback triangles.
+    colors = ('#96a3b5', '#82aab8', '#c3a67e', '#9f96bd', '#7fa88e', '#bd8f98')
+    points = np.concatenate([triangles.reshape(-1, 3) for _, triangles, _ in mesh], axis=0)
+    middle = (points.min(axis=0) + points.max(axis=0)) / 2
+    elev, azim = math.radians(elevation), math.radians(azimuth)
+    toward_camera = np.array([math.cos(elev)*math.cos(azim), math.cos(elev)*math.sin(azim), math.sin(elev)])
+    right = np.array([-math.sin(azim), math.cos(azim), 0.0])
+    up = np.cross(toward_camera, right)
+    basis = np.stack((right, up, toward_camera), axis=1)
+    projected = (points-middle) @ basis
+    extent = max(float(np.abs(projected[:, :2]).max()) * 1.16, 1.0)
+    size = 640; scale = (size-1) / (extent*2)
+    def project(values):
+        result = (values-middle) @ basis
+        result[..., 0] = size/2 + result[..., 0]*scale
+        result[..., 1] = size/2 - result[..., 1]*scale
+        return result
+    depth = np.full((size, size), -np.inf)
+    pixels = np.ones((size, size, 3), dtype=np.float64)
+    light = np.array([-0.3, -0.5, 0.8]); light /= np.linalg.norm(light)
+    processed_pixels = 0
+    for occurrence, triangles, _ in mesh:
+        fallback = colors[int(hashlib.sha256(occurrence['occurrenceId'].encode()).hexdigest()[:8], 16) % len(colors)]
+        color = occurrence.get('material', {}).get('baseColorSrgb', fallback)
+        # PNG is a bounded diffuse preview of the declared sRGB base color. The
+        # GLB stores the actual PBR roughness/metallic; this is no reflectance test.
+        base = np.array([int(color[index:index+2], 16)/255 for index in (1, 3, 5)])
+        normals = np.cross(triangles[:, 1]-triangles[:, 0], triangles[:, 2]-triangles[:, 0])
+        lengths = np.linalg.norm(normals, axis=1)
+        normals /= np.maximum(lengths[:, None], 1e-20)
+        shades = 0.65 + 0.35*np.abs(normals @ light)
+        for triangle, shade in zip(project(triangles), shades):
+            x0, y0, z0 = triangle[0]; x1, y1, z1 = triangle[1]; x2, y2, z2 = triangle[2]
+            denominator = (y1-y2)*(x0-x2) + (x2-x1)*(y0-y2)
+            if abs(denominator) < 1e-12:
+                continue
+            left = max(0, math.floor(min(x0, x1, x2))); top = max(0, math.floor(min(y0, y1, y2)))
+            right_edge = min(size-1, math.ceil(max(x0, x1, x2))); bottom = min(size-1, math.ceil(max(y0, y1, y2)))
+            if left > right_edge or top > bottom:
+                continue
+            processed_pixels += (right_edge-left+1)*(bottom-top+1)
+            if processed_pixels > 200_000_000:
+                raise ValueError('render raster budget exceeded')
+            yy, xx = np.mgrid[top:bottom+1, left:right_edge+1]
+            xx = xx+0.5; yy = yy+0.5
+            w0 = ((y1-y2)*(xx-x2) + (x2-x1)*(yy-y2)) / denominator
+            w1 = ((y2-y0)*(xx-x2) + (x0-x2)*(yy-y2)) / denominator
+            w2 = 1-w0-w1
+            candidate_depth = w0*z0 + w1*z1 + w2*z2
+            previous = depth[top:bottom+1, left:right_edge+1]
+            visible = (w0 >= -1e-9) & (w1 >= -1e-9) & (w2 >= -1e-9) & (candidate_depth > previous)
+            previous[visible] = candidate_depth[visible]
+            pixels[top:bottom+1, left:right_edge+1][visible] = base*shade
+    fig = plt.figure(figsize=(size/120, size/120), dpi=120)
+    axis = fig.add_axes((0, 0, 1, 1)); axis.imshow(pixels, interpolation='nearest')
+    if labels:
+        for occurrence, _, center in mesh:
+            if occurrence['bomItemId'] is not None:
+                x, y, _ = project(np.asarray(center))
+                axis.text(x, y, f"{occurrence['occurrenceId']}\n{occurrence['bomItemId']}", fontsize=7, color='#111827',
+                          horizontalalignment='center', verticalalignment='bottom')
+    axis.set_axis_off()
+    image = root / f'{name}.png'; fig.savefig(image, facecolor='white'); plt.close(fig)
+    return image.read_bytes()
+
+def render_assembly_views(root, children, manifest, tolerance):
+    normal = scene_mesh(scene_rows(children, manifest, 'normal'), tolerance)
+    internal = scene_mesh(scene_rows(children, manifest, 'internal'), tolerance)
+    exploded = scene_mesh(scene_rows(children, manifest, 'exploded'), tolerance)
+    images = {
+        'normal': render_scene(root, 'normal', normal, 25, -55),
+        'internal': render_scene(root, 'internal', internal, 25, -55),
+        'exploded': render_scene(root, 'exploded', exploded, 25, -55, labels=manifest['mode'] == 'occurrence_assembly'),
+        'front': render_scene(root, 'front', normal, 0, -90),
+        'top': render_scene(root, 'top', normal, 90, -90),
+        'iso': render_scene(root, 'iso', normal, 25, -55),
+    }
+    return images
+
+def shape_result_volume(value):
+    if value is None:
+        return 0.0
+    if isinstance(value, bd.Shape):
+        return max(float(value.volume), 0.0)
+    return sum(max(float(shape.volume), 0.0) for shape in value)
+
+def boolean_shape(value):
+    """One Shape (or None) from a build123d 0.11.1 boolean: intersect/cut may return a ShapeList even for one piece."""
+    if value is None or isinstance(value, bd.Shape):
+        return value
+    items = list(value)
+    if not items:
+        return None
+    return items[0] if len(items) == 1 else bd.Compound(items)
+
+def overlap_volume(left, right):
+    return shape_result_volume(left.intersect(right))
+
+def geometry_finding(subjects, metric, measured, operator, threshold):
+    measured = float(measured); threshold = float(threshold)
+    if not math.isfinite(measured) or measured < 0:
+        raise ValueError('non-finite inspection measurement')
+    passed = measured <= threshold if operator == '<=' else measured >= threshold
+    return {'subjectIds': list(subjects), 'metric': metric, 'measured': measured, 'operator': operator, 'threshold': threshold, 'passed': passed}
+
+def evaluate_rule_set(spec, plan_sha256, callback):
+    if spec is None:
+        return {'status': 'unknown', 'method': 'unavailable', 'planSha256': plan_sha256,
+                'reason': 'inspection_not_declared', 'findings': []}
+    if spec['kind'] == 'not_applicable':
+        return {'status': 'not_applicable', 'method': 'declared_not_applicable', 'planSha256': plan_sha256,
+                'reason': spec['reason'], 'findings': []}
+    try:
+        findings = callback(spec)
+    except Exception:
+        return {'status': 'unknown', 'method': 'unavailable', 'planSha256': plan_sha256,
+                'reason': 'brep_operation_failed', 'findings': []}
+    return {'status': 'pass' if all(item['passed'] for item in findings) else 'conflict', 'method': 'occt_brep',
+            'planSha256': plan_sha256, 'reason': None, 'findings': findings}
+
+def read_inspection_geometry(children, assembly, plan, encoded):
+    """Independently read BRep witnesses and prove their relation to actual STEP."""
+    metadata = plan.get('inspectionGeometry')
+    if metadata is None:
+        if plan.get('schema') != 'abelien.structure-inspection-plan.v1' or encoded is not None:
+            raise ValueError('unexpected inspection geometry')
+        return {}, None
+    if plan.get('schema') != 'abelien.structure-inspection-plan.v2' or not isinstance(metadata, dict) or set(metadata) != {'schema', 'sourceSha256', 'regions', 'shells'} or metadata['schema'] != 'abelien.structure-inspection-geometry.v1' or metadata['sourceSha256'] != assembly['sourceSha256']:
+        raise ValueError('inspection geometry identity mismatch')
+    if not isinstance(metadata['regions'], list) or not 2 <= len(metadata['regions']) <= 128 or not isinstance(metadata['shells'], list) or not 1 <= len(metadata['shells']) <= 32 or not isinstance(encoded, dict):
+        raise ValueError('invalid inspection geometry transport')
+    owners = {item['occurrenceId']: item for item in assembly['occurrences']}
+    product_shapes = {item['occurrenceId']: shape for item, shape in zip(assembly['occurrences'], children)}
+    region_specs, shapes, total = {}, {}, 0
+    from OCP.BRep import BRep_Builder
+    from OCP.BRepTools import BRepTools
+    from OCP.TopoDS import TopoDS_Shape
+    for region in metadata['regions']:
+        if not isinstance(region, dict) or set(region) != {'regionId', 'kind', 'ownerOccurrenceId', 'brepSha256'} or not isinstance(region['regionId'], str) or not NODE_ID.fullmatch(region['regionId']) or region['regionId'] in owners or region['regionId'] in region_specs or region['kind'] not in ('outer', 'cavity', 'opening') or region['ownerOccurrenceId'] not in owners:
+            raise ValueError('invalid inspection region binding')
+        region_id = region['regionId']; region_specs[region_id] = region
+        body = base64.b64decode(encoded[region_id], validate=True); total += len(body)
+        if not body or total > 8 * 1024 * 1024 or digest(body) != region['brepSha256']:
+            raise ValueError('inspection BRep hash or size mismatch')
+        wrapped = TopoDS_Shape(); BRepTools.Read_s(wrapped, BytesIO(body), BRep_Builder())
+        if wrapped.IsNull():
+            raise ValueError('inspection BRep readback failed')
+        shape = bd.Compound.cast(wrapped)
+        if not shape.is_valid or len(shape.solids()) != 1 or not math.isfinite(shape.volume) or shape.volume <= 0:
+            raise ValueError('inspection region must be a valid single solid')
+        normal = owners[region['ownerOccurrenceId']]['views']['normal']
+        shapes[region_id] = shape.moved(bd.Location(tuple(normal['translationMm']), tuple(normal['rotationDeg'])))
+    if set(encoded) != set(region_specs):
+        raise ValueError('inspection BRep set mismatch')
+    # Numerical equivalence tolerance, never a model-selected business clearance.
+    epsilon = 1e-6
+    used, shell_ids, checks = set(), set(), []
+    for shell in metadata['shells']:
+        if not isinstance(shell, dict) or set(shell) != {'occurrenceId', 'geometrySha256', 'transformSha256', 'outerRegionId', 'cavityRegionId', 'openingRegionIds'} or shell['occurrenceId'] not in owners or shell['occurrenceId'] in shell_ids or not isinstance(shell['openingRegionIds'], list) or len(shell['openingRegionIds']) > 32:
+            raise ValueError('invalid inspection shell binding')
+        owner = owners[shell['occurrenceId']]; shell_ids.add(owner['occurrenceId'])
+        if owner['geometryPrecision'] != 'custom_brep' or shell['geometrySha256'] != owner['geometrySha256'] or shell['transformSha256'] != owner['transformSha256']:
+            raise ValueError('inspection shell version mismatch')
+        expected_regions = [(shell['outerRegionId'], 'outer'), (shell['cavityRegionId'], 'cavity'), *[(item, 'opening') for item in shell['openingRegionIds']]]
+        for region_id, kind in expected_regions:
+            spec = region_specs.get(region_id)
+            if not spec or region_id in used or spec['kind'] != kind or spec['ownerOccurrenceId'] != owner['occurrenceId']:
+                raise ValueError('inspection region owner mismatch')
+            used.add(region_id)
+        outer, cavity = shapes[shell['outerRegionId']], shapes[shell['cavityRegionId']]
+        if len(outer.shells()) != 1 or len(cavity.shells()) != 1:
+            raise ValueError('inspection outer and cavity must be closed filled bodies')
+        outside = shape_result_volume(cavity.cut(outer))
+        wall_distance = float(outer.shells()[0].distance_to(cavity))
+        if not math.isfinite(wall_distance) or outside > epsilon or wall_distance <= epsilon:
+            raise ValueError('inspection cavity is not strictly inside outer')
+        wall = boolean_shape(outer.cut(cavity)); expected_shell = wall; opening_checks = []
+        if wall is None:
+            raise ValueError('inspection outer and cavity leave no wall')
+        for region_id in shell['openingRegionIds']:
+            opening = shapes[region_id]
+            cavity_overlap = overlap_volume(opening, cavity)
+            outside_outer = shape_result_volume(opening.cut(outer))
+            unique_cut = boolean_shape(opening.intersect(wall))
+            for other in shell['openingRegionIds']:
+                if other != region_id and unique_cut is not None:
+                    unique_cut = boolean_shape(unique_cut.cut(shapes[other]))
+            wall_cut = shape_result_volume(unique_cut)
+            if any(not math.isfinite(value) or value <= epsilon for value in (cavity_overlap, outside_outer, wall_cut)):
+                raise ValueError('inspection opening must cut a unique passage through actual wall')
+            expected_shell = boolean_shape(expected_shell.cut(opening))
+            if expected_shell is None:
+                raise ValueError('inspection openings remove the whole wall')
+            opening_checks.append({'regionId': region_id, 'cavityOverlapMm3': cavity_overlap,
+                                   'outsideOuterVolumeMm3': outside_outer, 'uniqueWallCutVolumeMm3': wall_cut})
+        actual = product_shapes[owner['occurrenceId']]
+        difference = shape_result_volume(actual.cut(expected_shell)) + shape_result_volume(expected_shell.cut(actual))
+        if not math.isfinite(difference) or difference > epsilon:
+            raise ValueError('inspection shell reconstruction differs from actual STEP')
+        checks.append({'shellOccurrenceId': owner['occurrenceId'], 'cavityOutsideMm3': outside,
+                       'minimumWallMm': wall_distance, 'shellSymmetricDifferenceMm3': difference, 'openings': opening_checks})
+    if used != set(region_specs):
+        raise ValueError('unbound inspection region')
+    return {key: shape for key, shape in shapes.items() if region_specs[key]['kind'] != 'outer'}, {
+        'schema': 'abelien.structure-inspection-geometry-evidence.v1', 'sourceSha256': assembly['sourceSha256'],
+        'inspectionPlanSha256': assembly['inspectionPlanSha256'], 'plan': metadata,
+        'status': 'pass', 'method': 'occt_brep_boolean_reconstruction', 'toleranceMm3': epsilon, 'checks': checks}
+
+def inspect_geometry(children, manifest, plan, inspection_shapes=None):
+    by_id = {occurrence['occurrenceId']: child for occurrence, child in zip(manifest['occurrences'], children)}
+    by_id.update(inspection_shapes or {})
+    plan_sha256 = digest(plan)
+    if plan_sha256 != manifest['inspectionPlanSha256']:
+        raise ValueError('inspection plan hash mismatch')
+
+    def collisions(spec):
+        allowed = {tuple(pair) for pair in spec['allowedPairs']}; findings = []
+        for left, right in itertools.combinations(spec['occurrenceIds'], 2):
+            pair = tuple(sorted((left, right)))
+            if pair not in allowed:
+                findings.append(geometry_finding(pair, 'overlap_volume_mm3', overlap_volume(by_id[left], by_id[right]), '<=', spec['maximumOverlapMm3']))
+        return findings
+
+    def containment(spec):
+        findings = []
+        for rule in spec['rules']:
+            for target in rule['targets']:
+                outside = shape_result_volume(by_id[target].cut(by_id[rule['container']]))
+                findings.append(geometry_finding((rule['container'], target), 'outside_volume_mm3', outside, '<=', rule['maximumOutsideMm3']))
+        return findings
+
+    def openings(spec):
+        findings = []
+        for rule in spec['rules']:
+            opening, target = by_id[rule['opening']], by_id[rule['target']]
+            findings.append(geometry_finding((rule['opening'], rule['target']), 'distance_mm', opening.distance_to(target), '<=', rule['maximumDistanceMm']))
+            findings.append(geometry_finding((rule['opening'], rule['target']), 'overlap_volume_mm3', overlap_volume(opening, target), '>=', rule['minimumOverlapMm3']))
+        return findings
+
+    def motion(spec):
+        findings = []
+        for rule in spec['rules']:
+            for obstacle in rule['obstacles']:
+                findings.append(geometry_finding((rule['envelope'], obstacle), 'overlap_volume_mm3', overlap_volume(by_id[rule['envelope']], by_id[obstacle]), '<=', rule['maximumOverlapMm3']))
+        return findings
+
+    return {
+        'collision': evaluate_rule_set(plan['collision'], plan_sha256, collisions),
+        'containment': evaluate_rule_set(plan['containment'], plan_sha256, containment),
+        'opening_alignment': evaluate_rule_set(plan['openings'], plan_sha256, openings),
+        'motion_envelope': evaluate_rule_set(plan['motionEnvelopes'], plan_sha256, motion),
+    }
+
+def export_source_api():
+    """Trusted startup only: inspect the installed module, never a submitted program."""
+    import build123d
+    import inspect
+    import importlib.metadata
+    classes = ('Part', 'Solid', 'Compound', 'Vertex', 'Edge', 'Face', 'Sketch', 'BuildPart', 'BuildSketch', 'Location')
+    def signature(value):
+        try:
+            sig = inspect.signature(value)
+        except (ValueError, TypeError):
+            return None
+        def annotation(value):
+            return None if value is inspect.Signature.empty else value if isinstance(value, str) else str(value)
+        return {'text': str(sig), 'parameters': [
+            {'name': p.name, 'kind': p.kind.name, 'annotation': annotation(p.annotation)} for p in sig.parameters.values()],
+            'returns': annotation(sig.return_annotation)}
+    names = sorted(name for name in dir(build123d) if re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]{0,63}', name))
+    result = {'schema': 'abelien.build123d-api.v1', 'build123dVersion': importlib.metadata.version('build123d'),
+              'moduleNames': names, 'callables': {}, 'classes': {}}
+    for name in names:
+        value = getattr(build123d, name)
+        if callable(value):
+            result['callables'][name] = signature(value)
+    for name in classes:
+        cls = getattr(build123d, name)
+        attrs = sorted(attr for attr in dir(cls) if re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]{0,63}', attr))
+        members = {}
+        for attr in attrs:
+            raw = inspect.getattr_static(cls, attr)
+            value = raw.fget if isinstance(raw, property) else getattr(cls, attr)
+            if callable(value):
+                members[attr] = {'property': isinstance(raw, property), 'signature': signature(value)}
+        result['classes'][name] = {'attributes': attrs, 'members': members, 'signature': signature(cls),
+            'dynamicAttributes': any('__getattr__' in base.__dict__ for base in cls.__mro__)}
+    library = load_cad_library()
+    result['library'] = {'version': library.LIBRARY_VERSION,
+                         'functions': [{'name': name, 'params': list(inspect.signature(getattr(library, name)).parameters)}
+                                       for name in library.__all__]}
+    return result
+
+
+def source_symbol_precheck(tree, manifest):
+    """Conservative straight-line inference. Unknown/dynamic receivers are left to the sandbox runtime."""
+    import ast
+    import builtins
+    module_names, classes = set(manifest['moduleNames']), manifest['classes']
+    callables = manifest['callables']
+    env, star, generation = {}, False, 0
+    declared = {node.id for node in ast.walk(tree) if isinstance(node, ast.Name) and isinstance(node.ctx, ast.Store)}
+    declared.update(node.name for node in ast.walk(tree) if isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef, ast.ClassDef)))
+    declared.update(dir(builtins))
+    for node in ast.walk(tree):
+        if isinstance(node, (ast.Import, ast.ImportFrom)):
+            declared.update(alias.asname or alias.name.split('.')[0] for alias in node.names)
+    class InvalidSymbol(Exception):
+        def __init__(self, node, symbol):
+            self.diagnostic = {'code': 'source_symbol', 'stage': 'source_precheck',
+                               'line': min(max(node.lineno, 1), 32768), 'symbol': symbol}
+    def invalid(node, symbol):
+        raise InvalidSymbol(node, symbol)
+    # These are headless-contract restrictions, independent of inferred CAD types.
+    for node in ast.walk(tree):
+        desktop = isinstance(node, ast.Import) and any(alias.name.split('.')[0] == 'ocp_vscode' for alias in node.names) or \
+                  isinstance(node, ast.ImportFrom) and (node.module or '').split('.')[0] == 'ocp_vscode'
+        display = isinstance(node, ast.Call) and (isinstance(node.func, ast.Name) and node.func.id == 'show_object' or
+                  isinstance(node.func, ast.Attribute) and node.func.attr == 'show_object')
+        if desktop or display:
+            return {'code': 'source_symbol', 'stage': 'source_precheck', 'line': min(max(node.lineno, 1), 32768),
+                    'symbol': 'ocp_vscode' if desktop else 'show_object'}
+    if any(isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id in
+           {'exec', 'eval', 'globals', 'locals', 'setattr', 'delattr'} for node in ast.walk(tree)):
+        return None
+    def binding(name):
+        return ('class', name) if name in classes else ('function', name) if name in callables else None
+    def result_type(sig, owner=None):
+        annotation = (sig or {}).get('returns')
+        if annotation in classes:
+            return ('instance', annotation)
+        if annotation in ('Self', 'typing.Self') and owner:
+            return ('instance', owner)
+        return None
+    def forget():
+        nonlocal star, generation
+        env.clear(); star = False; generation += 1
+    def expression(node):
+        if isinstance(node, ast.Name):
+            if node.id in env:
+                return env[node.id]
+            if star and node.id in module_names:
+                return binding(node.id)
+            if star and node.id not in declared:
+                invalid(node, 'build123d.' + node.id)
+            return None
+        if isinstance(node, ast.Attribute):
+            base = expression(node.value)
+            if base and base[0] == 'module':
+                if node.attr not in module_names:
+                    invalid(node, 'build123d.' + node.attr)
+                return binding(node.attr)
+            if base and base[0] in ('class', 'instance'):
+                cls = classes[base[1]]
+                # Instance attributes may be set in __init__, so only reject a missing method when called.
+                member = cls['members'].get(node.attr)
+                if member and member['property']:
+                    return result_type(member['signature'], base[1])
+                return ('member', base[1], node.attr)
+            return None
+        if isinstance(node, ast.Call):
+            fn = expression(node.func)
+            proof_generation = generation
+            args = [expression(arg) for arg in node.args]
+            kwargs = {item.arg: expression(item.value) for item in node.keywords}
+            if not fn or proof_generation != generation or any(isinstance(arg, ast.Starred) for arg in node.args) or None in kwargs:
+                # User callbacks can rebind or mutate any global/argument; discard earlier proofs.
+                forget(); return None
+            if fn[0] == 'class':
+                sig, symbol = classes[fn[1]]['signature'], fn[1]
+            elif fn[0] == 'function':
+                sig, symbol = callables[fn[1]], fn[1]
+            elif fn[0] == 'member':
+                cls = classes[fn[1]]
+                if fn[2] not in cls['attributes'] and not cls['dynamicAttributes']:
+                    invalid(node, fn[1] + '.' + fn[2])
+                sig, symbol = (cls['members'].get(fn[2]) or {}).get('signature'), fn[1] + '.' + fn[2]
+            else:
+                forget(); return None
+            if sig:
+                parameters = sig['parameters']
+                if not any(p['kind'] == 'VAR_KEYWORD' for p in parameters):
+                    accepted = {p['name'] for p in parameters if p['kind'] in ('POSITIONAL_OR_KEYWORD', 'KEYWORD_ONLY')}
+                    for keyword in node.keywords:
+                        if keyword.arg is not None and keyword.arg not in accepted:
+                            invalid(node, symbol + '.' + keyword.arg)
+                if fn == ('function', 'extrude'):
+                    first = kwargs.get('to_extrude', args[0] if args else None)
+                    accepted = next((p['annotation'] for p in parameters if p['name'] == 'to_extrude'), None)
+                    # Only BuildSketch is a proven builder/shape mismatch; no general annotation type checker.
+                    if first == ('instance', 'BuildSketch') and accepted and 'BuildSketch' not in accepted:
+                        invalid(node, 'extrude.to_extrude.BuildSketch')
+            return ('instance', fn[1]) if fn[0] == 'class' else result_type(sig, fn[1] if fn[0] == 'member' else None)
+        if isinstance(node, ast.NamedExpr):
+            value = expression(node.value); assign(node.target, value); return value
+        if isinstance(node, (ast.Lambda, ast.ListComp, ast.SetComp, ast.DictComp, ast.GeneratorExp, ast.BoolOp, ast.IfExp)):
+            # Local scopes, deferred callbacks, short-circuited branches and iterator types are not inferred.
+            forget(); return None
+        for child in ast.iter_child_nodes(node):
+            if isinstance(child, ast.expr):
+                expression(child)
+        return None
+    def assign(target, value):
+        if isinstance(target, ast.Name):
+            env[target.id] = value
+        else:
+            # Attribute mutation, unpacking and indexed aliases are intentionally not inferred.
+            forget()
+    def statements(nodes):
+        nonlocal star
+        for node in nodes:
+            # Re-importing a cached Python module cannot restore proof after a possible monkey patch.
+            if generation:
+                return
+            if isinstance(node, ast.Import):
+                for alias in node.names:
+                    if alias.name not in ('build123d', 'math'):
+                        forget()
+                    env[alias.asname or alias.name.split('.')[0]] = ('module',) if alias.name == 'build123d' else None
+            elif isinstance(node, ast.ImportFrom):
+                for alias in node.names:
+                    if node.module == 'build123d':
+                        if alias.name == '*':
+                            star = True
+                        elif alias.name not in module_names:
+                            invalid(node, 'build123d.' + alias.name)
+                        else:
+                            env[alias.asname or alias.name] = binding(alias.name)
+                    elif alias.name == '*':
+                        forget()
+                    else:
+                        if node.module != 'math':
+                            forget()
+                        env[alias.asname or alias.name] = None
+            elif isinstance(node, (ast.Assign, ast.AnnAssign)):
+                value = expression(node.value) if node.value else None
+                for target in node.targets if isinstance(node, ast.Assign) else [node.target]:
+                    assign(target, value)
+            elif isinstance(node, ast.Expr):
+                expression(node.value)
+            elif isinstance(node, ast.With):
+                for item in node.items:
+                    value = expression(item.context_expr)
+                    if item.optional_vars:
+                        assign(item.optional_vars, value)
+                statements(node.body)
+            elif isinstance(node, (ast.FunctionDef, ast.AsyncFunctionDef)):
+                parameters = [*node.args.posonlyargs, *node.args.args, *node.args.kwonlyargs,
+                              *([node.args.vararg] if node.args.vararg else []), *([node.args.kwarg] if node.args.kwarg else [])]
+                if node.decorator_list or node.args.defaults or node.args.kw_defaults or node.returns or any(arg.annotation for arg in parameters):
+                    forget()
+                env[node.name] = None
+            else:
+                # Control flow, deletion and augmented writes lose certainty; do not reject based on stale types.
+                forget()
+    try:
+        statements(tree.body)
+    except InvalidSymbol as exc:
+        return exc.diagnostic
+    return None
+
+
+request = json.load(sys.stdin)
+if request.get('mode') == 'api_manifest':
+    print(json.dumps(export_source_api()), file=response_stream, flush=True)
+    raise SystemExit(0)
+if request.get('mode') == 'preflight':
+    # Never import or execute generated source here. This is a conservative
+    # syntax/global-name lint, not a proof of execution or geometric validity.
+    import ast
+    import builtins
+    import symtable
+    try:
+        source = request['source']
+        tree = ast.parse(source, filename='model.py')
+        table = symtable.symtable(source, 'model.py', 'exec')
+        declared = {symbol.get_name() for symbol in table.get_symbols() if symbol.is_assigned() or symbol.is_imported() or symbol.is_namespace()}
+        declared.update(dir(builtins)); declared.update({'__name__', '__builtins__'})
+        star = any(isinstance(node, ast.ImportFrom) and any(alias.name == '*' for alias in node.names) for node in ast.walk(tree))
+        dynamic = any(isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id in {'exec', 'eval', 'globals', 'locals'} for node in ast.walk(tree))
+        missing = set()
+        def names(scope):
+            for symbol in scope.get_symbols():
+                if symbol.is_referenced() and symbol.is_global() and symbol.get_name() not in declared:
+                    missing.add(symbol.get_name())
+            for child in scope.get_children():
+                names(child)
+        if not star and not dynamic:
+            names(table)
+        safe = sorted(name for name in missing if re.fullmatch(r'[A-Za-z_][A-Za-z0-9_]{0,63}', name))[:5]
+        unsupported = library_preflight(tree, request)
+        for node in ast.walk(tree):
+            desktop = isinstance(node, ast.Import) and any(alias.name.split('.')[0] == 'ocp_vscode' for alias in node.names) or \
+                      isinstance(node, ast.ImportFrom) and (node.module or '').split('.')[0] == 'ocp_vscode'
+            manual_export = isinstance(node, ast.Call) and (isinstance(node.func, ast.Attribute) and node.func.attr == 'export_step' or \
+                            isinstance(node.func, ast.Name) and node.func.id == 'export_step')
+            if desktop or manual_export:
+                unsupported = {'code': 'source_unsupported', 'feature': 'desktop_import' if desktop else 'manual_export',
+                               'line': min(max(node.lineno, 1), 32768)}
+                break
+        assigned = {symbol.get_name() for symbol in table.get_symbols() if symbol.is_assigned()}
+        if unsupported is None and not dynamic and not {'assembly', 'result'}.intersection(assigned):
+            unsupported = {'code': 'source_unsupported', 'feature': 'missing_output', 'line': 1}
+        # An initializer is not the final assembly: append/extend, loops and
+        # later assignments may populate it. Only a final non-unpacked literal
+        # has a statically known count; runtime validates every actual result.
+        for node in tree.body[-1:]:
+            target = node.targets[0] if isinstance(node, ast.Assign) and len(node.targets) == 1 else node.target if isinstance(node, ast.AnnAssign) else None
+            if unsupported is None and isinstance(target, ast.Name) and target.id == 'assembly' and isinstance(node.value, (ast.List, ast.Tuple)) and \
+               not any(isinstance(item, ast.Starred) for item in node.value.elts) and not 2 <= len(node.value.elts) <= 128:
+                unsupported = {'code': 'source_unsupported', 'feature': 'assembly_shape', 'line': min(max(node.lineno, 1), 32768)}
+        symbol_diagnostic = source_symbol_precheck(tree, request['sourceApi']) if request.get('sourceApi') else None
+        response = {'ok': False, 'diagnostic': symbol_diagnostic} if symbol_diagnostic else \
+                   {'ok': False, 'diagnostic': {'code': 'source_unbound', 'names': safe}} if missing else \
+                   {'ok': False, 'diagnostic': unsupported} if unsupported else {'ok': True}
+    except SyntaxError as exc:
+        response = {'ok': False, 'diagnostic': {'code': 'source_syntax', 'line': min(max(exc.lineno or 1, 1), 32768)}}
+    print(json.dumps(response), file=response_stream, flush=True)
+    raise SystemExit(0)
+
+import build123d as bd
+import runpy
+engineering = runpy.run_path(str(Path(__file__).with_name('engineering.py')))
+root = Path(os.environ.get('STRUCTURE_TASK_DIR', '/tmp/structure'))
+root.mkdir(exist_ok=True)
+step = root / 'model.step'
+if request['mode'] in ('component_fit_build', 'component_fit_inspect'):
+    try:
+        if request['mode'] == 'component_fit_inspect':
+            import matplotlib
+            matplotlib.use('Agg')
+            import matplotlib.pyplot as plt
+            import numpy as np
+        result = engineering['construct' if request['mode'] == 'component_fit_build' else 'verify_final'](request, globals())
+        print(json.dumps(result), file=response_stream, flush=True)
+    except Exception as exc:
+        fail_with_diagnostic('geometry_validation', exc)
+    raise SystemExit(0)
+if request['mode'] == 'build':
+    source = request['source']; source_sha256 = request.get('sourceSha256')
+    if not isinstance(source_sha256, str) or source_sha256 != digest(source.encode()):
+        raise ValueError('source hash mismatch')
+    scope = {'__name__': '__main__'}
+    stage = 'source_exec'
+    try:
+        abelien_cad = load_cad_library(reset=True)
+        with contextlib.redirect_stdout(sys.stderr):
+            exec(compile(source, 'model.py', 'exec'), scope)
+            representation_records = abelien_cad._RECORDS
+            stage = 'assembly_contract'
+            model, assembly, inspection, revision_checks, inspection_breps = draft_manifest(scope, source_sha256, request.get('revision'))
+            representation = build_representation(source, representation_records, assembly, abelien_cad.__all__, dir(bd))
+            attachment_proposal = engineering['proposal'](scope['engineering_attachment']) if 'engineering_attachment' in scope else None
+            stage = 'step_export'
+            bd.export_step(model, str(step))
+    except Exception as exc:  # The model's own source failed: return a bounded reason it can act on.
+        fail_with_diagnostic(stage, exc)
+    print(json.dumps({'step': encode(step), 'assembly': assembly, 'inspection': inspection, 'revisionChecks': revision_checks,
+                      **({'representation': representation} if representation is not None else {}),
+                      **({'inspectionGeometryBreps': inspection_breps} if inspection_breps is not None else {}),
+                      **({'attachmentProposal': attachment_proposal} if attachment_proposal is not None else {})}), file=response_stream, flush=True)
+else:
+    source_sha256, assembly, inspection, revision_checks = request.get('sourceSha256'), request.get('assembly'), request.get('inspection'), request.get('revisionChecks')
+    if not isinstance(source_sha256, str) or not isinstance(assembly, dict) or assembly.get('sourceSha256') != source_sha256:
+        raise ValueError('assembly source mismatch')
+    if not isinstance(inspection, dict) or digest(inspection) != assembly.get('inspectionPlanSha256'):
+        raise ValueError('inspection plan mismatch')
+    if not isinstance(revision_checks, dict) or set(revision_checks) != {'delta', 'preservation', 'mount'}:
+        raise ValueError('revision checks missing')
+    representation = validate_representation(request['representation'], assembly) if 'representation' in request else None
+    try:
+        step_bytes = base64.b64decode(request['step'], validate=True); step.write_bytes(step_bytes)
+        model = bd.import_step(str(step))
+        dimensions = list(model.bounding_box().size); volume = model.volume; solids = len(model.solids())
+        if not model.is_valid or not solids or not math.isfinite(volume) or volume <= 0:
+            raise ValueError('invalid or empty solid')
+        if not all(math.isfinite(value) and value > 0 for value in dimensions):
+            raise ValueError('invalid dimensions')
+        glb = root / 'model.glb'
+        if assembly.get('mode') == 'legacy_shape':
+            display_model = bd.Part(model.wrapped); display_model.label = 'legacy-shape'
+            children = [display_model]
+        elif assembly.get('mode') == 'occurrence_assembly':
+            children = list(model.children)
+            expected = [occurrence['occurrenceId'] for occurrence in assembly['occurrences']]
+            if len(children) != len(expected) or [child.label for child in children] != expected:
+                raise ValueError('STEP occurrence hierarchy lost during readback')
+            display_model = bd.Compound(children=children); display_model.label = 'assembly-root'
+        else:
+            raise ValueError('unknown assembly mode')
+        inspection_shapes, inspection_evidence = read_inspection_geometry(children, assembly, inspection, request.get('inspectionGeometryBreps'))
+        if not bd.export_gltf(display_model, str(glb), binary=True, linear_deflection=0.2 if request['pass'] == 'preview' else 0.05):
+            raise ValueError('GLB export failed')
+        raw = apply_materials_to_glb(glb.read_bytes(), assembly); glb.write_bytes(raw)
+        document = gltf_document(raw); validate_occurrence_nodes(document, assembly)
+        import matplotlib
+        matplotlib.use('Agg')
+        import matplotlib.pyplot as plt
+        import numpy as np
+        view_images = render_assembly_views(root, children, assembly, 0.3)
+        manifest = final_manifest(assembly, step_bytes, raw, view_images)
+        geometric_checks = inspect_geometry(children, manifest, inspection, inspection_shapes)
+        unknown = [name for name, check in geometric_checks.items() if check['status'] == 'unknown']
+        not_checked = ['reference_match', 'wall_thickness', 'manufacturability', 'physical_performance', *unknown, *DEFERRED]
+        if representation is not None and any(item['omitted'] for item in representation['occurrences']):
+            not_checked.append('representation_gaps')
+        report = {'schema': 'abelien.structure-inspection.v2', 'units': 'mm', 'build123d': bd.__version__,
+                  'assembly': {'mode': manifest['mode'], 'sha256': manifest['assemblySha256'], 'occurrence_count': manifest['occurrenceCount'],
+                               'node_mapping': manifest['mode'] == 'occurrence_assembly', 'inspection_plan_sha256': manifest['inspectionPlanSha256']},
+                  'checks': {'step_readback': True, 'solid_validity': True, 'solid_count': solids,
+                             'dimensions_mm': dimensions, 'volume_mm3': volume, 'geometry': geometric_checks, 'revision': revision_checks},
+                  'visual_review': 'review_required',
+                  'not_checked': not_checked,
+                  **({'representation': representation} if representation is not None else {})}
+        if inspection_evidence is not None:
+            report['inspectionGeometry'] = {**inspection_evidence, 'assemblySha256': manifest['assemblySha256']}
+        images = {f'{name}.png': base64.b64encode(body).decode('ascii') for name, body in view_images.items()}
+        artifacts = {'model.step': encode(step), 'model.glb': encode(glb), **images,
+                     'geometry.json': base64.b64encode(json.dumps(report, separators=(',', ':')).encode()).decode('ascii'),
+                     'assembly.json': base64.b64encode(json.dumps(manifest, separators=(',', ':'), ensure_ascii=False).encode()).decode('ascii')}
+        if 'attachmentProposal' in request:
+            attachment = engineering['baseline'](children, manifest, request['attachmentProposal'], step_bytes, globals())
+            artifacts['attachment.json'] = base64.b64encode(json.dumps(attachment, separators=(',', ':')).encode()).decode()
+        print(json.dumps({'artifacts': artifacts}), file=response_stream, flush=True)
+    except Exception as exc:  # Geometry of the built model failed validation; integrity checks above stay fatal.
+        fail_with_diagnostic('geometry_validation', exc)