@deepblend/dsh-blender-host 0.4.0 → 0.6.0

package/lib/asset-preview.js

@@ -1,4 +1,5 @@
 /** Fixed asset preview scenes, compiled in batch mode outside project revisions. */
+import { assertRuntimeSceneFeatures } from './runtime-scene-features.js'
 import { copyFileSync, existsSync, writeFileSync } from 'node:fs'
 import { join } from 'node:path'
 import { randomUUID } from 'node:crypto'
@@ -100,6 +101,8 @@ export async function renderAssetPreview({ runtime, asset, directory, maxMeshPol
       'The isolated preview scene is invalid.', { detail: { errors: checked.errors } })
     const compiled = compileSceneSpec(scene).spec
     writeFileSync(sceneSpecPath, JSON.stringify(compiled))
+    const featureCheck = assertRuntimeSceneFeatures(runtime, compiled, { signal })
+    if (featureCheck) await featureCheck
     const result = await runtime.compileScene({ sceneSpecPath, profile: 'preview', projectRoot: directory,
       jobId: `asset-compile-${randomUUID()}`, session: false, signal,
       onWorkingDirectory: info => { copyFileSync(join(info.directory, 'result.blend'), checkpointPath) } })

package/lib/diagnostic-preview.js

@@ -1,4 +1,5 @@
 /** Isolated inspection renders. Successful tasks are published with one directory rename. */
+import { assertRuntimeSceneFeatures } from './runtime-scene-features.js'
 import { createReadStream, copyFileSync, existsSync, mkdirSync, readdirSync, renameSync, writeFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { randomUUID } from 'node:crypto'
@@ -186,6 +187,8 @@ export async function renderDiagnostic(host, request) {
     }
     const sceneSpecPath = join(compileRoot, 'scene-spec.json'), checkpointPath = join(compileRoot, 'derived.blend')
     writeJsonAtomic(sceneSpecPath, scene)
+    const featureCheck = assertRuntimeSceneFeatures(runtime, scene, { signal })
+    if (featureCheck) await featureCheck
     const compiled = await runtime.compileScene({ sceneSpecPath, projectRoot: compileRoot, profile: 'preview',
       jobId: `${jobId}-compile`, session: false, signal,
       onWorkingDirectory: info => copyFileSync(join(info.directory, 'result.blend'), checkpointPath) })

package/lib/index.js

@@ -25,6 +25,9 @@
  * Plane: Host composition
  */
 
+import { assertRuntimeSceneFeatures } from './runtime-scene-features.js'
+import { readRecipeContext } from './recipe-state.js'
+import { instantiateRecipeLock, planRecipeGeometryEdit, recipeGeometryParameters } from '@deepblend/dsh-blender-contracts'
 import { Service } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 
@@ -628,6 +631,7 @@ export default class BlenderStudio extends Service {
 
   get creationRequestProtocol() { return CREATION_REQUEST_VERSION }
   get cameraTargetResetSupported() { return CAMERA_UPDATE_FIELDS.includes('clearTarget') }
+  get recipeParameterEditingSupported() { return true }
 
   async _createProject(request, creationRequest) {
     const source = request.recipe ? this.recipes.instantiate(request.recipe) : null
@@ -775,6 +779,49 @@ export default class BlenderStudio extends Service {
     }
   }
 
+  async getRecipeParameters(projectId, options = {}) {
+    const record = this.store.readRecord(projectId)
+    const revision = options.revision ?? record.currentRevision
+    const context = readRecipeContext(this.store, projectId, revision)
+    if (context === null) return { projectId, revision, available: false, parameters: [], reason: 'This revision has no saved recipe' }
+    const definitions = recipeGeometryParameters(context.lock.manifest)
+    if (!definitions.length) return { projectId, revision, available: false, parameters: [], reason: 'This saved recipe has no assembly dimensions' }
+    const locked = context.state ? { ...context.lock, values: context.state.values,
+      valuesSha256: context.state.valuesSha256 } : context.lock
+    const resolved = instantiateRecipeLock(locked)
+    let conflicts = []
+    try { planRecipeGeometryEdit(context.lock, this.store.readRevisionSpec(projectId, revision), context.state ?? undefined, {}) }
+    catch (error) {
+      if (error.code !== 'RECIPE_PARAMETER_CONFLICT') throw error
+      conflicts = error.details.conflicts
+    }
+    return { projectId, revision, available: true, originRevision: context.originRevision,
+      recipe: { id: context.lock.id, version: context.lock.version }, valuesSha256: resolved.recipe.valuesSha256,
+      parameters: definitions.map(parameter => ({ id: parameter.id, title: parameter.title, type: parameter.type,
+        minimum: parameter.minimum, maximum: parameter.maximum, default: parameter.default, value: resolved.values[parameter.id] })),
+      conflicts }
+  }
+
+  async updateRecipeParameters(request) {
+    if (!request || typeof request !== 'object' || Array.isArray(request)
+        || typeof request.projectId !== 'string' || !/^r[0-9]{4,}$/.test(request.baseRevision ?? '')
+        || ['saveCheckpoint', 'renderPreview'].some(key => request[key] !== undefined && typeof request[key] !== 'boolean')
+        || request.idempotencyKey !== undefined && typeof request.idempotencyKey !== 'string'
+        || Object.keys(request).some(key => !['projectId', 'baseRevision', 'parameters', 'saveCheckpoint', 'renderPreview', 'idempotencyKey', 'signal', 'projectsRoot'].includes(key))) {
+      throw new BlenderError('RECIPE_PARAMETER_INVALID', 'Expected a bounded recipe parameter request')
+    }
+    const { signal, ...input } = request
+    if (input.projectsRoot !== undefined && input.projectsRoot !== this.store.projectsRoot) {
+      throw new BlenderError('REVISION_CONFLICT', 'The active project store changed; read the selected work again')
+    }
+    const outcome = await this.transactions.applyRecipeParameters(input, { signal })
+    return { ...toCanonicalRevisionSummary({ manifest: outcome.revision, checkpointPath: outcome.revision.checkpoint }),
+      unchanged: outcome.unchanged === true, idempotentReplay: outcome.idempotentReplay === true,
+      parameterState: outcome.parameterState, preservedCameraIds: outcome.preservedCameraIds,
+      parameters: await this.getRecipeParameters(input.projectId, { revision: outcome.revision.revision }),
+      ...(outcome.job ? { job: toCanonicalJobRecord(outcome.job) } : {}) }
+  }
+
   /**
    * Validate a revision (SPEC §7.2 `validateScene`).
    *
@@ -1187,6 +1234,8 @@ export default class BlenderStudio extends Service {
    */
   async compileRevisionForRender(input) {
     const { projectId, revision, spec } = input
+    const featureCheck = assertRuntimeSceneFeatures(this.runtime, spec, { signal: input.signal })
+    if (featureCheck) await featureCheck
     const scratch = resolveInside(
       this.store.workspaceRoot,
       join(this.store.workspaceRoot, 'tmp', `render-${revision}-${Date.now().toString(36)}`),

package/lib/recipe-state.js

@@ -0,0 +1,62 @@
+/** Resolve saved recipe provenance using the selected revision's own ancestry. */
+import { constants, openSync, closeSync, fstatSync, readSync } from 'node:fs'
+import { join } from 'node:path'
+import { BlenderError, instantiateRecipeLock, sha256Canonical } from '@deepblend/dsh-blender-contracts'
+
+const fail = message => { throw new BlenderError('RECIPE_LOCK_INVALID', message) }
+function readBounded(path, limit) {
+  let fd
+  try {
+    fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW)
+    const stat = fstatSync(fd)
+    if (!stat.isFile() || stat.size > limit) fail('Stored recipe metadata exceeds its limit or is not a file')
+    const bytes = Buffer.alloc(limit + 1)
+    let length = 0, read
+    do { read = readSync(fd, bytes, length, bytes.length - length, null); length += read } while (read && length < bytes.length)
+    if (length > limit) fail('Stored recipe metadata grew beyond its limit')
+    return JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.subarray(0, length)))
+  } catch (error) {
+    if (error instanceof BlenderError) throw error
+    fail('Stored recipe metadata cannot be decoded')
+  } finally { if (fd !== undefined) closeSync(fd) }
+}
+
+export function readRecipeContext(store, projectId, revision) {
+  const visited = new Set()
+  let cursor = revision, state = null, stateRevision = null
+  while (cursor !== 'r0000') {
+    if (visited.has(cursor) || visited.size >= 4096) fail('Recipe revision ancestry is cyclic or exceeds its limit')
+    visited.add(cursor)
+    const manifest = store.readRevisionManifest(projectId, cursor)
+    if (!manifest || manifest.revision !== cursor) fail('Recipe revision ancestry contains an invalid manifest')
+    if (state === null && manifest.recipeParameters) {
+      if (manifest.recipeParameters.statePath !== 'recipe-parameters.json') fail('Unexpected recipe parameter state path')
+      state = readBounded(join(store.revisionDirectory(projectId, cursor), 'recipe-parameters.json'), 65536)
+      if (sha256Canonical(state) !== manifest.recipeParameters.stateSha256) fail('Recipe parameter state differs from its saved hash')
+      stateRevision = cursor
+    }
+    if (manifest.recipe) {
+      if (manifest.recipe.lockPath !== 'recipe-lock.json') fail('Unexpected recipe origin path')
+      const lock = readBounded(join(store.revisionDirectory(projectId, cursor), 'recipe-lock.json'), 8 * 1024 * 1024)
+      if (lock.id !== manifest.recipe.id || lock.version !== manifest.recipe.version
+          || lock.packageDigest !== manifest.recipe.packageDigest) fail('Recipe origin differs from its revision reference')
+      try { instantiateRecipeLock(lock) }
+      catch (error) { throw new BlenderError(error.code ?? 'RECIPE_LOCK_INVALID', error.message, { detail: error.details }) }
+      if (state !== null && (state.schemaVersion !== 'deepblend.recipe-parameters/v1'
+          || state.originRevision !== cursor || state.manifestSha256 !== lock.manifestSha256)) {
+        fail('Saved parameters belong to a different recipe origin')
+      }
+      if (state !== null) {
+        try { instantiateRecipeLock({ ...lock, values: state.values, valuesSha256: state.valuesSha256 }) }
+        catch (error) { throw new BlenderError(error.code ?? 'RECIPE_LOCK_INVALID', error.message, { detail: error.details }) }
+      }
+      return { originRevision: cursor, lock, state, stateRevision }
+    }
+    const base = manifest.baseRevision
+    if (typeof base !== 'string' || !/^r[0-9]{4,}$/.test(base)
+        || Number(base.slice(1)) >= Number(cursor.slice(1))) fail('Recipe ancestry must refer to an earlier revision')
+    cursor = base
+  }
+  if (state !== null) fail('Saved parameters have no recipe origin')
+  return null
+}

package/lib/revision-transaction.js

@@ -41,6 +41,7 @@
  * Plane: Host composition
  */
 
+import { assertRuntimeSceneFeatures } from './runtime-scene-features.js'
 import { existsSync, mkdirSync, readdirSync, renameSync, statSync } from 'node:fs'
 import { randomUUID } from 'node:crypto'
 import { join } from 'node:path'
@@ -59,6 +60,8 @@ import {
   sceneSpecDigest,
   shortDigest,
   specHash,
+  planRecipeGeometryEdit,
+  sha256Canonical,
   summarizeSceneSpec,
   toCanonicalFailure,
   validateScenePatch,
@@ -67,6 +70,7 @@ import {
 } from '@deepblend/dsh-blender-contracts'
 import { verifyAssetBundle, verifyUnbundledGltfAsset, verifyUnbundledObjAsset } from './asset-bundle.js'
 import { GENESIS_REVISION, parseRevisionId } from './project-store.js'
+import { readRecipeContext } from './recipe-state.js'
 import {
   fileSha256,
   fileSize,
@@ -295,6 +299,37 @@ export class RevisionTransaction {
     return this.store.withProjectWrite(patch.projectId, () => this._applyScenePatch(patch, options))
   }
 
+  async applyRecipeParameters(request, options = {}) {
+    return this.store.withProjectWrite(request.projectId, async () => {
+      const context = readRecipeContext(this.store, request.projectId, request.baseRevision)
+      if (context === null) throw new BlenderError('RECIPE_NOT_FOUND', 'This revision has no saved recipe origin')
+      const current = this.store.readRevisionSpec(request.projectId, request.baseRevision)
+      let planned
+      try { planned = planRecipeGeometryEdit(context.lock, current, context.state ?? undefined, request.parameters) }
+      catch (error) { throw new BlenderError(error.code ?? 'RECIPE_PARAMETER_INVALID', error.message, { detail: error.details }) }
+      if (planned.operations.length === 0) {
+        const record = this.store.readRecord(request.projectId)
+        if (record.currentRevision !== request.baseRevision) throw new BlenderError(BlenderErrorCode.REVISION_CONFLICT, 'The current revision changed')
+        return { unchanged: true, projectId: request.projectId,
+          revision: this.store.readRevisionManifest(request.projectId, request.baseRevision),
+          parameterState: context.state, preservedCameraIds: planned.preservedCameraIds }
+      }
+      const patch = { projectId: request.projectId, baseRevision: request.baseRevision, operations: planned.operations,
+        saveCheckpoint: request.saveCheckpoint !== false, renderPreview: request.renderPreview === true,
+        idempotencyKey: request.idempotencyKey ?? `recipe-${sha256Canonical({ projectId: request.projectId,
+          baseRevision: request.baseRevision, manifestSha256: context.lock.manifestSha256,
+          valuesSha256: planned.parameterState.valuesSha256 })}`,
+        note: 'Update assembled recipe dimensions' }
+      const checked = validateScenePatch(patch)
+      if (!checked.ok) throw new BlenderError(BlenderErrorCode.SCENE_PATCH_INVALID, checked.summary)
+      const state = { ...planned.parameterState, originRevision: context.originRevision }
+      const outcome = await this._applyScenePatch(patch, { ...options, recipeParameters: state })
+      const committed = readRecipeContext(this.store, request.projectId, outcome.revision.revision)
+      if (!committed?.state) throw new BlenderError('RECIPE_LOCK_INVALID', 'The recorded outcome has no recipe parameter state')
+      return { ...outcome, parameterState: committed.state, preservedCameraIds: planned.preservedCameraIds }
+    })
+  }
+
   async _applyScenePatch(patch, options) {
     const projectId = patch.projectId
     const record = this.store.readRecord(projectId)
@@ -442,6 +477,7 @@ export class RevisionTransaction {
       operations: patch.operations,
       spec: nextSpec,
       kind: 'scene_patch',
+      recipeParameters: options.recipeParameters ?? null,
       summary,
       actor: patch.actor ?? null,
       stage: patch.stage ?? null,
@@ -570,6 +606,8 @@ export class RevisionTransaction {
       const checkpointStaging = join(staging, 'scene.blend')
 
       try {
+        const featureCheck = assertRuntimeSceneFeatures(this.runtime, plan.spec, { signal: plan.signal })
+        if (featureCheck) await featureCheck
         const run = await this.runtime.compileScene({
           sceneSpecPath: specPath,
           profile: plan.spec.renderProfiles?.preview === undefined ? undefined : 'preview',
@@ -750,6 +788,8 @@ export class RevisionTransaction {
       stage: plan.stage ?? null,
       note: plan.note ?? null,
       ...(plan.recipeLock ? { recipe: { id: plan.recipeLock.id, version: plan.recipeLock.version, packageDigest: plan.recipeLock.packageDigest, lockPath: 'recipe-lock.json' } } : {}),
+      ...(plan.recipeParameters ? { recipeParameters: { statePath: 'recipe-parameters.json',
+        stateSha256: sha256Canonical(plan.recipeParameters) } } : {}),
       sceneSpecVersion: plan.spec.schemaVersion,
       counts: sceneSummary.counts,
       subjectBounds: sceneSummary.subjectBounds,
@@ -826,6 +866,7 @@ export class RevisionTransaction {
     }
 
     if (plan.recipeLock) writeJsonAtomic(join(staging, 'recipe-lock.json'), plan.recipeLock)
+    if (plan.recipeParameters) writeJsonAtomic(join(staging, 'recipe-parameters.json'), plan.recipeParameters)
 
     writeJsonAtomic(join(staging, 'validation.json'), {
       schemaVersion: 'deepblend.validation/v1',

package/lib/runtime-scene-features.js

@@ -0,0 +1,21 @@
+import { BlenderError, BlenderErrorCode, requiredSceneFeatures } from '@deepblend/dsh-blender-contracts'
+
+/** Old runtimes must not silently compile an axis-sized box as their scalar default. */
+export function assertRuntimeSceneFeatures(runtime, spec, { signal } = {}) {
+  const required = requiredSceneFeatures(spec)
+  if (required.length === 0) return
+  return (async () => {
+    signal?.throwIfAborted()
+    const capabilities = typeof runtime?.getCapabilities === 'function'
+      ? await runtime.getCapabilities({ signal }) : null
+    signal?.throwIfAborted()
+    if (capabilities?.installed === false) {
+      throw new BlenderError(BlenderErrorCode.NOT_FOUND, 'Blender is unavailable for this scene.')
+    }
+    const supported = Array.isArray(capabilities?.sceneFeatures) ? capabilities.sceneFeatures : []
+    const missing = required.filter(feature => !supported.includes(feature))
+    if (missing.length) throw new BlenderError(BlenderErrorCode.SCENE_FEATURE_UNSUPPORTED,
+      `The runtime does not support ${missing.join(', ')}. Update the runtime before compiling this scene.`,
+      { detail: { required, supported, missing } })
+  })()
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-host",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "DeepBlend Host service: the blenderStudio business facade over the BlenderRuntime seam.",
   "main": "lib/index.js",
@@ -20,7 +20,7 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
-    "@deepblend/dsh-blender-contracts": "0.4.0",
+    "@deepblend/dsh-blender-contracts": "0.6.0",
     "sharp": "0.35.5"
   },
   "license": "MIT",