@deepblend/dsh-blender-tool 0.9.0 → 0.10.0

package/lib/geometry-comparison.js

@@ -0,0 +1,36 @@
+/** Compare two already verified reports for the same explicit surface selection. */
+export function compareSurfaceReports(reference, current) {
+  const chords = [], separations = [], chordPercentages = [], separationPercentages = []
+  const samples = current.surfaceSamples.map((after, i) => {
+    const before = reference.surfaceSamples[i]
+    const values = sample => ({ status: sample.status,
+      ...(sample.status === 'sampled' ? { normalSurfaceChordMm: sample.normalSurfaceChordMm } : {}),
+      ...(sample.gap ? { targetStatus: sample.gap.status,
+        ...(sample.gap.status === 'sampled' ? { normalRaySeparationMm: sample.gap.normalRaySeparationMm } : {}) } : {}) })
+    const change = { sampleId: after.sampleId, entityId: after.entityId,
+      ...(after.targetEntityId ? { targetEntityId: after.targetEntityId } : {}), before: values(before), after: values(after) }
+    if (before.status === 'sampled' && after.status === 'sampled') {
+      change.normalSurfaceChordChangeMm = after.normalSurfaceChordMm - before.normalSurfaceChordMm
+      change.normalSurfaceChordChangePercent = change.normalSurfaceChordChangeMm / before.normalSurfaceChordMm * 100
+      chords.push(Math.abs(change.normalSurfaceChordChangeMm))
+      chordPercentages.push(Math.abs(change.normalSurfaceChordChangePercent))
+    }
+    if (before.gap?.status === 'sampled' && after.gap?.status === 'sampled') {
+      change.normalRaySeparationChangeMm = after.gap.normalRaySeparationMm - before.gap.normalRaySeparationMm
+      change.normalRaySeparationChangePercent = change.normalRaySeparationChangeMm / before.gap.normalRaySeparationMm * 100
+      separations.push(Math.abs(change.normalRaySeparationChangeMm))
+      separationPercentages.push(Math.abs(change.normalRaySeparationChangePercent))
+    }
+    return change
+  })
+  return { schemaVersion: 'deepblend.surface-comparison/v1', referenceInspection: reference, samples,
+    summary: { requestedSamples: samples.length, comparedChords: chords.length, comparedSeparations: separations.length,
+      ...(chords.length ? { maxAbsoluteChordChangeMm: Math.max(...chords), maxAbsoluteChordChangePercent: Math.max(...chordPercentages) } : {}),
+      ...(separations.length ? { maxAbsoluteSeparationChangeMm: Math.max(...separations), maxAbsoluteSeparationChangePercent: Math.max(...separationPercentages) } : {}) },
+    limitations: [
+      'Changes are current minus reference for identical explicit world seeds, parts and frame. These are not necessarily the same material points.',
+      'Maxima cover every comparable requested sample, including chord-only samples. Unavailable pairs have no numeric change and are not zero.',
+      'Percent changes use each positive reference measurement as denominator. Chord and separation percentages are separate; do not substitute one maximum for the other or derive them from rounded display values.',
+      'Observed changes do not establish their cause, a global minimum, manufacturing tolerance, symmetry, collision absence or artistic approval.',
+    ] }
+}

package/lib/shared.js

@@ -112,7 +112,7 @@ export async function persistImage(attachments, bytes, name) {
  *
  * @param {string} headline
  * @param {object} data
- * @param {{ notes?: string[], warnings?: object[] }} [options]
+ * @param {{ notes?: string[], warnings?: object[], compact?: boolean }} [options]
  * @returns {string}
  */
 export function renderSuccess(headline, data, options = {}) {
@@ -126,7 +126,7 @@ export function renderSuccess(headline, data, options = {}) {
     lines.push('')
   }
   lines.push('Canonical JSON:')
-  lines.push(JSON.stringify(data, null, 2))
+  lines.push(JSON.stringify(data, null, options.compact ? undefined : 2))
   return lines.join('\n')
 }
 

package/lib/tools.js

@@ -53,6 +53,7 @@ import {
   requestApproval,
   resolveStudio,
 } from './shared.js'
+import { compareSurfaceReports } from './geometry-comparison.js'
 
 /** A short parameter description of a SceneSpec engine key. */
 const ENGINE_KEY_DESCRIPTION =
@@ -393,7 +394,13 @@ function sceneGet(ctx) {
       'To measure saved native parts, pass geometryEntityIds (1–8 IDs from this scene) and an explicit geometryFrame. ' +
       'This returns source-verified world-axis spans in millimeters and transforms without rendering or creating a revision. ' +
       'Spans include rotation, handles and protrusions; they are not body diameter, wall thickness, clearance or quality approval. ' +
-      'Do not subtract shell/liner spans or radii to claim a gap, or use unchanged height/scale to certify wall thickness. Those surface conditions remain unmeasured. ' +
+      'Do not subtract shell/liner spans or radii to claim a gap, or use unchanged height/scale to certify wall thickness. ' +
+      'Optional geometrySurfaceSamples measures 1–8 explicit local surface chords and pair separations on the same saved source. ' +
+      'The chord runs from source entry to exit; separation runs from source EXIT to target entry and excludes that chord. ' +
+      'Use geometryOnly:true for a compact verified measurement receipt without the scene catalogue. ' +
+      'When comparing revisions, add geometryCompareRevision with identical surface samples; the tool computes per-sample changes and maxima, including chord-only samples. ' +
+      'Choose outside world seeds and directions from the actual scene/bounds; missed or unsupported samples remain unavailable. ' +
+      'Local samples do not prove full-surface minimum wall thickness, whole-assembly clearance, no collision or quality approval. ' +
       'ALWAYS use the revision this returns as `baseRevision` for your next blender_scene_patch.',
     parameters: {
       projectId: { type: 'string', required: true, description: 'The project id.' },
@@ -402,6 +409,17 @@ function sceneGet(ctx) {
         description: 'Optional: measure 1–8 distinct saved native entity IDs. Requires geometryFrame. Hidden viewport objects and non-mesh roots are explicitly unavailable.' },
       geometryFrame: { type: 'integer',
         description: 'Explicit integer frame from 0 to 1000000 for native geometry measurement. Use the frame of the preview being checked. Requires geometryEntityIds.' },
+      geometryOnly: { type: 'boolean', description: 'Return only source identity and verified geometry evidence, without the scene catalogue. Requires geometryEntityIds and geometryFrame; cannot be combined with full:true. Ordinary reads keep their existing shape.' },
+      geometryCompareRevision: { type: 'string', description: 'Optional explicit reference revision (e.g. r0004). Requires geometrySurfaceSamples. Re-measures that saved source with identical parts, seeds and frame, and computes current-minus-reference changes and maxima for all comparable samples. Unavailable pairs remain unavailable. No global minima or change cause is established.' },
+      geometrySurfaceSamples: { type: 'array', description: 'Optional 1–8 local surface samples. Requires geometryEntityIds including every source/target and geometryFrame. Numeric results are local evidence only.',
+        items: { type: 'object', additionalProperties: false, properties: {
+          sampleId: { type: 'string', required: true, description: 'Distinct short letters/numbers/underscore/hyphen identifier (1–64 characters).' },
+          entityId: { type: 'string', required: true, description: 'Source mesh ID in geometryEntityIds.' },
+          targetEntityId: { type: 'string', description: 'Optional distinct selected mesh for separation after the source exit.' },
+          originMeters: { type: 'array', items: { type: 'number' }, required: true, description: 'Three finite world metre coordinates outside the source. Do not use declared wall or gap values as measurements.' },
+          direction: { type: 'array', items: { type: 'number' }, required: true, description: 'Three finite non-zero direction components toward the source; normalized by the runtime.' },
+          searchDistanceMm: { type: 'number', required: true, description: 'Explicit seed search limit from 0.01 to 500 mm. Normal chord and target searches are separately limited to 100 mm.' },
+        } } },
       full: {
         type: 'boolean',
         description: 'Also return the complete SceneSpec and its compiled form. Costs a lot of context — ' +
@@ -413,27 +431,63 @@ function sceneGet(ctx) {
       const resolved = resolveStudio(ctx)
       if (resolved.unavailable !== undefined) return { ok: false, ...resolved.unavailable }
       try {
+        if (args.geometryOnly !== undefined && typeof args.geometryOnly !== 'boolean') {
+          throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, 'geometryOnly must be boolean.')
+        }
+        if (args.geometryOnly === true && (args.geometryEntityIds === undefined || args.full === true)) {
+          throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, 'geometryOnly requires a native measurement selection and cannot be combined with full:true.')
+        }
         if ((args.geometryEntityIds === undefined) !== (args.geometryFrame === undefined)) {
           throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, 'Native measurements require both geometryEntityIds and geometryFrame.')
         }
+        if (args.geometrySurfaceSamples !== undefined && args.geometryEntityIds === undefined) {
+          throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, 'Surface samples require geometryEntityIds and geometryFrame.')
+        }
+        if (args.geometryCompareRevision !== undefined && (typeof args.geometryCompareRevision !== 'string' ||
+            !/^r\d{4,}$/.test(args.geometryCompareRevision) || args.geometrySurfaceSamples === undefined)) {
+          throw new BlenderError(BlenderErrorCode.SCRIPT_ERROR, 'geometryCompareRevision requires an explicit saved revision and surface samples.')
+        }
         if (args.geometryEntityIds !== undefined) validateGeometrySelection({ entityIds: args.geometryEntityIds,
-          frame: args.geometryFrame, checkpointSha256: '0'.repeat(64) })
+          frame: args.geometryFrame, checkpointSha256: '0'.repeat(64), ...(args.geometrySurfaceSamples === undefined ? {} : { surfaceSamples: args.geometrySurfaceSamples }) })
         const { data, canonicalWarnings } = await canonicalCall(resolved.studio.getScene(args.projectId, {
           ...definedFields({ revision: args.revision }),
           full: args.full === true,
-          ...(args.geometryEntityIds === undefined ? {} : { geometry: { entityIds: args.geometryEntityIds, frame: args.geometryFrame }, signal: exec?.signal }),
+          ...(args.geometryEntityIds === undefined ? {} : { geometry: { entityIds: args.geometryEntityIds, frame: args.geometryFrame,
+            ...(args.geometrySurfaceSamples === undefined ? {} : { surfaceSamples: args.geometrySurfaceSamples }) }, signal: exec?.signal }),
         }), warning)
-        if (args.geometryEntityIds !== undefined && (!data.geometryInspection || data.geometryInspection.schemaVersion !== 'deepblend.scene-geometry/v1' ||
-            data.geometryInspection.projectId !== args.projectId || data.geometryInspection.sourceRevision !== data.revision ||
-            data.geometryInspection.sourceDigest !== data.digest || data.geometryInspection.sourceUnchanged !== true || data.geometryInspection.frame !== args.geometryFrame ||
-            !Array.isArray(data.geometryInspection.limitations) ||
-            JSON.stringify(data.geometryInspection.objects?.map(o => o.entityId)) !== JSON.stringify(args.geometryEntityIds))) {
-          throw new BlenderError(BlenderErrorCode.RUNTIME_UNAVAILABLE, 'The Host did not return measurements for the requested source and frame. Upgrade DeepBlend before measuring; ordinary scene reads remain available.')
+        const hasSamples = args.geometrySurfaceSamples !== undefined
+        const verifyScene = (data, expectedRevision) => {
+          if (expectedRevision !== undefined && data.revision !== expectedRevision) {
+            throw new BlenderError(BlenderErrorCode.RUNTIME_UNAVAILABLE, 'The Host returned a different saved revision than requested.')
+          }
+          if (args.geometryEntityIds !== undefined && (!data.geometryInspection || data.geometryInspection.schemaVersion !== (hasSamples ? 'deepblend.scene-geometry/v2' : 'deepblend.scene-geometry/v1') ||
+              data.geometryInspection.projectId !== args.projectId || data.geometryInspection.sourceRevision !== data.revision ||
+              data.geometryInspection.sourceDigest !== data.digest || data.geometryInspection.sourceUnchanged !== true || data.geometryInspection.frame !== args.geometryFrame ||
+              !Array.isArray(data.geometryInspection.limitations) ||
+              JSON.stringify(data.geometryInspection.objects?.map(o => o.entityId)) !== JSON.stringify(args.geometryEntityIds))) {
+            throw new BlenderError(BlenderErrorCode.RUNTIME_UNAVAILABLE, 'The Host did not return measurements for the requested source and frame. Upgrade DeepBlend before measuring; ordinary scene reads remain available.')
+          }
+          if (data.geometryInspection) verifyGeometryReport({ frame: data.geometryInspection.frame, blenderVersion: data.geometryInspection.blenderVersion, objects: data.geometryInspection.objects,
+            schemaVersion: hasSamples ? 'deepblend.geometry-inspection/v2' : 'deepblend.geometry-inspection/v1',
+            ...(hasSamples ? { surfaceSamples: data.geometryInspection.surfaceSamples } : {}), checkpointSha256: data.geometryInspection.sourceCheckpointSha256,
+            checkpointUnchanged: data.geometryInspection.sourceUnchanged }, { entityIds: args.geometryEntityIds, frame: args.geometryFrame,
+            checkpointSha256: data.geometryInspection.sourceCheckpointSha256, ...(hasSamples ? { surfaceSamples: args.geometrySurfaceSamples } : {}) })
+        }
+        verifyScene(data, args.revision)
+        if (args.geometryCompareRevision !== undefined) {
+          const reference = await canonicalCall(resolved.studio.getScene(args.projectId, { revision: args.geometryCompareRevision,
+            full: false, geometry: { entityIds: args.geometryEntityIds, frame: args.geometryFrame, surfaceSamples: args.geometrySurfaceSamples }, signal: exec?.signal }), warning)
+          verifyScene(reference.data, args.geometryCompareRevision)
+          canonicalWarnings.push(...reference.canonicalWarnings)
+          data.geometryComparison = compareSurfaceReports(reference.data.geometryInspection, data.geometryInspection)
+        }
+        if (args.geometryOnly === true) {
+          const receipt = { projectId: args.projectId, revision: data.revision, digest: data.digest,
+            isCurrent: data.isCurrent, geometryInspection: data.geometryInspection,
+            ...(data.geometryComparison ? { geometryComparison: data.geometryComparison } : {}) }
+          return { ok: true, text: renderSuccess(`Saved native measurement receipt for "${args.projectId}" at ${data.revision}.`, receipt,
+            { warnings: canonicalWarnings, compact: true }), data: receipt }
         }
-        if (data.geometryInspection) verifyGeometryReport({ frame: data.geometryInspection.frame, blenderVersion: data.geometryInspection.blenderVersion, objects: data.geometryInspection.objects,
-          schemaVersion: 'deepblend.geometry-inspection/v1', checkpointSha256: data.geometryInspection.sourceCheckpointSha256,
-          checkpointUnchanged: data.geometryInspection.sourceUnchanged }, { entityIds: args.geometryEntityIds, frame: args.geometryFrame,
-          checkpointSha256: data.geometryInspection.sourceCheckpointSha256 })
         const counts = data.counts ?? {}
         const notes = [
           `Revision ${data.revision}${data.isCurrent ? ' (current)' : ' (NOT current — patches against it will be refused)'}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-tool",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "type": "module",
   "description": "Agent-preset tool consumer: registers the model-visible DeepBlend Blender tools. Publishes no service.",
   "main": "lib/index.js",
@@ -11,7 +11,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@deepblend/dsh-blender-contracts": "0.9.0"
+    "@deepblend/dsh-blender-contracts": "0.10.0"
   },
   "license": "MIT",
   "repository": {