@deepblend/dsh-blender-provider-local 0.8.1 → 0.10.0

package/lib/geometry-inspection.js

@@ -0,0 +1,2 @@
+// Compatibility entry; Host and Provider share one validated wire contract.
+export { GEOMETRY_INSPECTION_VERSION, GEOMETRY_INSPECTION_LIMITS, validateGeometrySelection, verifyGeometryReport } from '@deepblend/dsh-blender-contracts'

package/lib/index.js

@@ -20,10 +20,13 @@
  */
 
 import { spawnSync } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { createReadStream } from 'node:fs'
 import { existsSync, mkdirSync, readFileSync, realpathSync, rmSync, statSync, writeFileSync } from 'node:fs'
 import net from 'node:net'
-import { readFile } from 'node:fs/promises'
-import { delimiter, isAbsolute, join, resolve, sep } from 'node:path'
+import { readFile, copyFile } from 'node:fs/promises'
+import { GEOMETRY_INSPECTION_LIMITS, validateGeometrySelection, verifyGeometryReport } from './geometry-inspection.js'
+import { delimiter, isAbsolute, join, relative, resolve, sep } from 'node:path'
 import { randomUUID } from 'node:crypto'
 
 import { Service } from '@deepseek-ai/cordis'
@@ -228,8 +231,9 @@ async function connect(socketPath, timeoutMs) {
 /**
  * The actions this provider can serve from a kept session, and the ONLY ones it can.
  *
- * DERIVED, NOT CHOSEN: these are exactly the actions whose calls go through `runBootstrap`, which is
- * the one place the session path is decided. Everything else spawns its own process on purpose —
+ * These are the actions whose calls permit session routing through `runBootstrap`.
+ * Explicitly isolated actions also use that dispatcher but force session:false.
+ * Everything else spawns its own process on purpose —
  * `render_frames` most of all, because cancelling a render has to kill exactly that render, and a
  * request inside a kept session cannot be killed without ending the session (and, attached, the
  * user's own Blender).
@@ -246,6 +250,7 @@ export const SESSION_ROUTABLE_ACTIONS = Object.freeze([
   'render_preview',
   'render_views',
 ])
+export const ISOLATED_BOOTSTRAP_ACTIONS = Object.freeze(['inspect_geometry'])
 
 /**
  * A live Blender, presented as one shape whatever carries the bytes.
@@ -1537,6 +1542,60 @@ export default class LocalBlenderRuntime extends Service {
     }
   }
 
+  /** Optional read-only measurement; always isolated from a kept or interactive session. */
+  async inspectGeometry(request) {
+    validateGeometrySelection(request)
+    const aborted = () => {
+      if (request.signal?.aborted) throw new BlenderError(BlenderErrorCode.ABORTED, 'Geometry inspection cancelled.')
+    }
+    aborted()
+    if (typeof request.checkpointPath !== 'string' || !isAbsolute(request.checkpointPath) || !existsSync(request.checkpointPath)) {
+      throw new BlenderError(BlenderErrorCode.REVISION_CHECKPOINT_MISSING, 'Geometry inspection needs an absolute native checkpoint path.')
+    }
+    if (!existsSync(this.workspaceRoot)) throw new BlenderError(BlenderErrorCode.PATH_OUTSIDE_WORKSPACE, 'The inspection workspace does not exist.')
+    const source = realpathSync(request.checkpointPath), root = realpathSync(this.workspaceRoot)
+    const local = relative(root, source)
+    if (!local || local === '..' || local.startsWith('..' + sep) || isAbsolute(local)) throw new BlenderError(BlenderErrorCode.PATH_OUTSIDE_WORKSPACE, 'The inspected checkpoint is outside the runtime workspace.')
+    const info = statSync(source)
+    if (!info.isFile() || info.size > GEOMETRY_INSPECTION_LIMITS.checkpointBytes) {
+      throw new BlenderError(BlenderErrorCode.SCENE_VALIDATION_FAILED, 'The inspected checkpoint is not a bounded native file.')
+    }
+    const digest = async path => {
+      const hash = createHash('sha256')
+      for await (const bytes of createReadStream(path, { signal: request.signal })) hash.update(bytes)
+      return hash.digest('hex')
+    }
+    const expected = request.checkpointSha256
+    const assertDigest = actual => {
+      if (actual !== expected) throw new BlenderError(BlenderErrorCode.SCENE_VALIDATION_FAILED, 'The checkpoint differs from the expected inspection source.')
+    }
+    const { directory } = this._createWorkingDirectory()
+    try {
+      assertDigest(await digest(source))
+      const snapshot = join(directory, 'inspection-source.blend')
+      await copyFile(source, snapshot)
+      aborted()
+      assertDigest(await digest(snapshot))
+      const run = await this.runBootstrap({ action: 'inspect_geometry', jobId: request.jobId,
+        payload: { entityIds: request.entityIds, frame: request.frame, checkpointSha256: expected,
+          ...(request.surfaceSamples === undefined ? {} : { surfaceSamples: request.surfaceSamples }) } },
+      { signal: request.signal, session: false, args: ['--blend', snapshot] })
+      aborted()
+      if (request.surfaceSamples !== undefined && run.envelope?.result?.schemaVersion === 'deepblend.geometry-inspection/v1') {
+        throw new BlenderError(BlenderErrorCode.RUNTIME_UNAVAILABLE, 'The Blender bootstrap does not support local surface sampling. Upgrade DeepBlend; ordinary native geometry reads remain available.')
+      }
+      const report = verifyGeometryReport(run.envelope?.result, request)
+      assertDigest(await digest(source))
+      aborted()
+      return { report, envelope: run.envelope, durationMs: run.durationMs, stdout: run.stdout, stderr: run.stderr }
+    } catch (cause) {
+      aborted()
+      throw cause
+    } finally {
+      this._cleanup(directory)
+    }
+  }
+
   /**
    * Render one preview frame from an existing `.blend` checkpoint.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-provider-local",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "type": "module",
   "description": "Local Blender Provider: the BlenderRuntime Service over ctx.subprocess (batch execution).",
   "main": "lib/index.js",
@@ -11,7 +11,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@deepblend/dsh-blender-contracts": "0.8.1"
+    "@deepblend/dsh-blender-contracts": "0.10.0"
   },
   "license": "MIT",
   "repository": {

package/python/bootstrap.py

@@ -99,6 +99,7 @@ from deepblend_util import (  # noqa: E402  (path set up above)
 SUPPORTED_ACTIONS = (
     "get_capabilities",
     "compile_scene",
+    "inspect_geometry",
     "render_preview",
     "render_views",
     "render_frames",
@@ -474,7 +475,10 @@ KNOWN_SESSION_OPTIONS = (
     "--frames", "--events", "--proc",
 )
 
+from deepblend_inspect_geometry import inspect_geometry
+
 ACTIONS = {
+    "inspect_geometry": inspect_geometry,
     "get_capabilities": action_get_capabilities,
     "compile_scene": action_compile_scene,
     "render_preview": action_render_preview,
@@ -588,6 +592,12 @@ def _session_dispatch(request, options):
             % (request.get("protocolVersion"), PROTOCOL_VERSION),
         }, [], [])
 
+    if action == 'inspect_geometry':
+        return build_envelope(job_id, action, None, {
+            'code': 'BLENDER_UNSUPPORTED_ACTION',
+            'message': 'Native geometry inspection requires an isolated batch and cannot open a checkpoint in a kept or live Blender session.',
+        }, [], [])
+
     handler = ACTIONS.get(action)
     if handler is None:
         return build_envelope(job_id, action, None, {

package/python/deepblend_inspect_geometry.py

@@ -0,0 +1,100 @@
+"""Bounded, read-only evaluation of a hash-pinned native checkpoint."""
+import hashlib
+import math
+import os
+import re
+
+from deepblend_util import ActionError
+
+
+def file_digest(path):
+    digest = hashlib.sha256()
+    with open(path, 'rb') as stream:
+        for chunk in iter(lambda: stream.read(1024 * 1024), b''):
+            digest.update(chunk)
+    return digest.hexdigest()
+
+
+def inspect_geometry(request, options):
+    import bpy
+    payload = request.get('payload')
+    if not isinstance(payload, dict):
+        raise ActionError('BLENDER_SCRIPT_ERROR', 'Geometry inspection payload must be an object.')
+    ids, frame, expected = payload.get('entityIds'), payload.get('frame'), payload.get('checkpointSha256')
+    if (not isinstance(ids, list) or not 1 <= len(ids) <= 8 or
+            any(not isinstance(x, str) or not x or x.strip() != x or len(x) > 128 or '\x00' in x for x in ids) or
+            len(set(ids)) != len(ids) or type(frame) is not int or not 0 <= frame <= 1000000 or
+            not isinstance(expected, str) or re.fullmatch('[a-f0-9]{64}', expected) is None):
+        raise ActionError('BLENDER_SCRIPT_ERROR', 'Geometry inspection requires 1–8 distinct entity IDs, an explicit frame and checkpoint SHA256.')
+    samples = payload.get('surfaceSamples')
+    if 'surfaceSamples' in payload:
+        from deepblend_inspect_surface import validate_surface_selection
+        validate_surface_selection(samples, ids)
+    checkpoint = options.get('blend')
+    if not checkpoint or not os.path.isfile(checkpoint):
+        raise ActionError('REVISION_CHECKPOINT_MISSING', 'Geometry inspection needs a native checkpoint.')
+    if os.path.getsize(checkpoint) > 1024 ** 3 or file_digest(checkpoint) != expected:
+        raise ActionError('SCENE_VALIDATION_FAILED', 'The inspected checkpoint differs from the expected source.')
+    try:
+        bpy.ops.wm.open_mainfile(filepath=checkpoint, load_ui=False, use_scripts=False)
+    except Exception as exc:
+        raise ActionError('SCENE_VALIDATION_FAILED', 'The native checkpoint cannot be opened for inspection.') from exc
+    if bpy.data.libraries:
+        raise ActionError('BLENDER_UNSUPPORTED_ACTION', 'Inspection requires self-contained geometry; externally linked Blender libraries are not hash-bound by this checkpoint.')
+    unit_scale = float(bpy.context.scene.unit_settings.scale_length)
+    if not math.isfinite(unit_scale) or abs(unit_scale - 1.0) > 1e-8:
+        raise ActionError('BLENDER_UNSUPPORTED_ACTION', 'Inspection requires a native unit scale of 1 metre per Blender unit; rescaled display units cannot be reported as millimetres.')
+    bpy.context.scene.frame_set(frame)
+    measured_frame = int(bpy.context.scene.frame_current)
+    if measured_frame != frame:
+        raise ActionError('SCENE_VALIDATION_FAILED', 'Blender did not evaluate the requested inspection frame.')
+    graph = bpy.context.evaluated_depsgraph_get()
+    objects = []
+    for entity_id in ids:
+        obj = bpy.data.objects.get('db_entity__' + entity_id)
+        if obj is None:
+            raise ActionError('SCENE_SPEC_INVALID', 'The selected native entity does not exist: ' + entity_id)
+        entry = {'entityId': entity_id, 'type': obj.type, 'available': False}
+        if obj.type != 'MESH':
+            entry['unavailableReason'] = 'not-mesh'
+        elif not obj.visible_get(view_layer=bpy.context.view_layer):
+            entry['unavailableReason'] = 'viewport-disabled'
+        else:
+            evaluated = obj.evaluated_get(graph)
+            mesh = evaluated.to_mesh()
+            try:
+                if mesh is None or not mesh.vertices:
+                    entry['unavailableReason'] = 'empty-or-invalid-geometry'
+                else:
+                    low = [math.inf] * 3
+                    high = [-math.inf] * 3
+                    finite = True
+                    for vertex in mesh.vertices:
+                        point = evaluated.matrix_world @ vertex.co
+                        if not all(math.isfinite(x) for x in point):
+                            finite = False
+                            break
+                        for axis in range(3):
+                            low[axis] = min(low[axis], float(point[axis]))
+                            high[axis] = max(high[axis], float(point[axis]))
+                    matrix = [[float(x) for x in row] for row in evaluated.matrix_world]
+                    scale = [float(x) for x in obj.scale]
+                    if not finite or not all(math.isfinite(x) for row in matrix for x in row) or not all(math.isfinite(x) for x in scale):
+                        entry['unavailableReason'] = 'empty-or-invalid-geometry'
+                    else:
+                        entry.update(available=True, worldBoundsMeters={'min': low, 'max': high},
+                                     worldAxisExtentMm=[(high[i] - low[i]) * 1000 for i in range(3)],
+                                     worldMatrix=matrix, scale=scale, vertexCount=len(mesh.vertices), polygonCount=len(mesh.polygons))
+            finally:
+                evaluated.to_mesh_clear()
+        objects.append(entry)
+    report = {'schemaVersion': 'deepblend.geometry-inspection/v1', 'checkpointSha256': expected,
+              'checkpointUnchanged': True, 'frame': measured_frame, 'blenderVersion': bpy.app.version_string,
+              'objects': objects}
+    if 'surfaceSamples' in payload:
+        from deepblend_inspect_surface import inspect_surface_samples
+        report['schemaVersion'] = 'deepblend.geometry-inspection/v2'
+        report['surfaceSamples'] = inspect_surface_samples(samples, graph)
+    if file_digest(checkpoint) != expected:
+        raise ActionError('SCENE_VALIDATION_FAILED', 'The checkpoint changed during geometry inspection.')
+    return report, [], []

package/python/deepblend_inspect_surface.py

@@ -0,0 +1,130 @@
+"""Finite local surface rays. This does not establish global wall or clearance minima."""
+import math
+import re
+from deepblend_util import ActionError
+
+EPSILON = 1e-7  # metres: 0.0001 mm; smaller separations are unavailable
+MAX_SURFACE_DISTANCE = .1
+
+
+def validate_surface_selection(samples, ids):
+    if not isinstance(samples, list) or not 1 <= len(samples) <= 8:
+        raise ActionError('BLENDER_SCRIPT_ERROR', 'Select 1–8 surface samples.')
+    seen = set()
+    allowed = {'sampleId', 'entityId', 'targetEntityId', 'originMeters', 'direction', 'searchDistanceMm'}
+    for q in samples:
+        if (not isinstance(q, dict) or set(q) - allowed or
+                not isinstance(q.get('sampleId'), str) or re.fullmatch('[a-zA-Z0-9_-]{1,64}', q['sampleId']) is None or
+                q['sampleId'] in seen or q.get('entityId') not in ids or
+                ('targetEntityId' in q and (q['targetEntityId'] not in ids or q['targetEntityId'] == q['entityId']))):
+            raise ActionError('BLENDER_SCRIPT_ERROR', 'Invalid surface identity or unsupported fields.')
+        seen.add(q['sampleId'])
+        for key in ('originMeters', 'direction'):
+            v = q.get(key)
+            if not isinstance(v, list) or len(v) != 3 or any(type(x) not in (int, float) or not math.isfinite(x) for x in v):
+                raise ActionError('BLENDER_SCRIPT_ERROR', 'Surface seeds and directions must be finite vectors.')
+        norm = math.hypot(*q['direction'])
+        search = q.get('searchDistanceMm')
+        if (any(abs(x) > 1000 for x in q['originMeters']) or not 1e-12 <= norm <= 1e6 or
+                type(search) not in (int, float) or not math.isfinite(search) or not .01 <= search <= 500):
+            raise ActionError('BLENDER_SCRIPT_ERROR', 'Surface seeds, directions or search distances exceed the budget.')
+
+
+def evaluated_surface(obj, graph):
+    import bpy
+    import bmesh
+    from mathutils.bvhtree import BVHTree
+    if obj.type != 'MESH':
+        return {'reason': 'not-mesh'}
+    if not obj.visible_get(view_layer=bpy.context.view_layer):
+        return {'reason': 'viewport-disabled'}
+    evaluated = obj.evaluated_get(graph)
+    mesh = evaluated.to_mesh()
+    bm = bmesh.new()
+    try:
+        if mesh is None or not mesh.vertices or not mesh.polygons:
+            return {'reason': 'empty-or-invalid-geometry'}
+        if len(mesh.vertices) > 250_000 or len(mesh.polygons) > 250_000:
+            return {'reason': 'geometry-budget-exceeded'}
+        bm.from_mesh(mesh)
+        bm.transform(evaluated.matrix_world)
+        bm.normal_update()
+        if any(not math.isfinite(x) for v in bm.verts for x in v.co):
+            return {'reason': 'empty-or-invalid-geometry'}
+        volume = bm.calc_volume(signed=True)
+        if any(not e.is_manifold or not e.is_contiguous for e in bm.edges) or not math.isfinite(volume) or volume <= 0:
+            return {'reason': 'unsupported-topology-or-winding'}
+        remaining = set(bm.verts)
+        pending = [remaining.pop()]
+        while pending:
+            for edge in pending.pop().link_edges:
+                for vertex in edge.verts:
+                    if vertex in remaining:
+                        remaining.remove(vertex)
+                        pending.append(vertex)
+        if remaining:
+            return {'reason': 'unsupported-topology-or-winding'}
+        return {'bvh': BVHTree.FromBMesh(bm)}
+    finally:
+        bm.free()
+        evaluated.to_mesh_clear()
+
+
+def surface_sample(q, surfaces):
+    from mathutils import Vector
+    magnitude = math.hypot(*q['direction'])
+    direction = Vector([x / magnitude for x in q['direction']]).normalized()
+    result = {k: q[k] for k in ('sampleId', 'entityId', 'originMeters', 'searchDistanceMm')}
+    result['direction'] = list(direction)
+    if 'targetEntityId' in q:
+        result['targetEntityId'] = q['targetEntityId']
+    source = surfaces[q['entityId']]
+
+    def unavailable(reason):
+        return dict(result, status=reason)
+
+    if 'reason' in source:
+        return unavailable(source['reason'])
+    outer, normal, _, _ = source['bvh'].ray_cast(Vector(q['originMeters']), direction, q['searchDistanceMm'] / 1000)
+    if outer is None:
+        return unavailable('no-entry')
+    if normal.dot(direction) >= -1e-6:
+        return unavailable('entry-not-inward')
+    inward = -normal.normalized()
+    inner, opposite_normal, _, _ = source['bvh'].ray_cast(outer + inward * EPSILON, inward, MAX_SURFACE_DISTANCE)
+    if inner is None:
+        return unavailable('no-opposite-surface')
+    if opposite_normal.dot(inward) <= 1e-6:
+        return unavailable('exit-not-outward')
+    chord = (inner - outer).length * 1000
+    if not math.isfinite(chord) or chord <= 2 * EPSILON * 1000:
+        return unavailable('below-resolution')
+    result.update(status='sampled', entryMeters=list(outer), exitMeters=list(inner),
+                  inwardUnitNormal=list(inward), normalSurfaceChordMm=chord)
+    if 'targetEntityId' in q:
+        target = surfaces[q['targetEntityId']]
+        if 'reason' in target:
+            result['gap'] = {'status': target['reason']}
+        else:
+            start = inner + inward * EPSILON
+            point, n, _, _ = target['bvh'].ray_cast(start, inward, MAX_SURFACE_DISTANCE)
+            obstruction, _, _, _ = source['bvh'].ray_cast(start, inward, MAX_SURFACE_DISTANCE)
+            if point is None:
+                result['gap'] = {'status': 'no-target-entry'}
+            elif n.dot(inward) >= -1e-6:
+                result['gap'] = {'status': 'target-not-inward'}
+            elif obstruction is not None and (obstruction - inner).length <= (point - inner).length + EPSILON:
+                result['gap'] = {'status': 'source-surface-before-target'}
+            elif (point - inner).length <= 2 * EPSILON:
+                result['gap'] = {'status': 'below-resolution'}
+            else:
+                result['gap'] = {'status': 'sampled', 'targetEntryMeters': list(point),
+                                 'normalRaySeparationMm': (point - inner).length * 1000}
+    return result
+
+
+def inspect_surface_samples(samples, graph):
+    import bpy
+    ids = {q['entityId'] for q in samples} | {q['targetEntityId'] for q in samples if 'targetEntityId' in q}
+    surfaces = {id: evaluated_surface(bpy.data.objects['db_entity__' + id], graph) for id in sorted(ids)}
+    return [surface_sample(q, surfaces) for q in samples]