@deepblend/dsh-blender-contracts 0.5.0 → 0.6.0

package/lib/index.js

@@ -877,4 +877,5 @@ export {
   managedBlenderCandidates,
 } from './deployment-paths.js'
 
-export { RECIPE_SCHEMA_VERSION, RECIPE_CAPABILITIES, RECIPE_LIMITS, RecipeError, recipeCapabilitiesForScene, validateRecipeManifest, validateRecipePackage, instantiateRecipe } from './recipe.js'
+export { RECIPE_SCHEMA_VERSION, RECIPE_CAPABILITIES, RECIPE_LIMITS, RecipeError, recipeCapabilitiesForScene, validateRecipeManifest, validateRecipePackage, instantiateRecipe, instantiateRecipeLock } from './recipe.js'
+export { planRecipeGeometryEdit, recipeGeometryParameters } from './recipe-parameters.js'

package/lib/recipe-parameters.js

@@ -0,0 +1,107 @@
+/** Plan existing-assembly edits as ordinary, bounded ScenePatch operations. */
+import { canonicalStringify, sha256Canonical } from './canonical.js'
+import { instantiateRecipeLock, RecipeError } from './recipe.js'
+import { validateSceneSpec } from './scene-spec.js'
+
+const axisOf = binding => ['x', 'y', 'z'].indexOf(binding.axis)
+const structural = parameter => parameter.bindings.some(binding => binding.kind === 'entity')
+  && parameter.bindings.every(binding => ['entity', 'camera'].includes(binding.kind))
+const entity = (spec, id) => spec.entities.find(item => item.id === id)
+const vector = (target, property) => property === 'dimensions' ? target?.generator?.dimensions
+  : property === 'targetPoint' ? target?.targetPoint : target?.transform?.location
+const close = (a, b) => Number.isFinite(a) && Number.isFinite(b)
+  && Math.abs(a - b) <= 1e-9 * Math.max(1, Math.abs(b))
+
+export function recipeGeometryParameters(manifest) {
+  return manifest.parameters.filter(structural)
+}
+
+export function planRecipeGeometryEdit(lock, currentSpec, parameterState, changes) {
+  const origin = instantiateRecipeLock(lock)
+  const scene = validateSceneSpec(currentSpec)
+  if (!scene.ok) throw new RecipeError('RECIPE_SCENE_INVALID', scene.summary, { errors: scene.errors })
+  let currentLock = lock
+  if (parameterState !== undefined) {
+    if (parameterState?.schemaVersion !== 'deepblend.recipe-parameters/v1'
+        || parameterState.manifestSha256 !== lock.manifestSha256) {
+      throw new RecipeError('RECIPE_LOCK_INVALID', 'Parameter state belongs to a different recipe')
+    }
+    currentLock = { ...lock, values: parameterState.values, valuesSha256: parameterState.valuesSha256 }
+  }
+  const before = parameterState === undefined ? origin : instantiateRecipeLock(currentLock)
+  const after = instantiateRecipeLock(currentLock, changes)
+  const parameters = recipeGeometryParameters(lock.manifest)
+  for (const id of Object.keys(changes)) {
+    if (!parameters.some(parameter => parameter.id === id)) {
+      throw new RecipeError('RECIPE_PARAMETER_INVALID', `Parameter ${id} is not an assembly geometry control`)
+    }
+  }
+  const conflicts = []
+  for (const parameter of parameters) for (const binding of parameter.bindings) {
+    if (binding.kind !== 'entity') continue
+    const expected = vector(entity(before.spec, binding.entityId), binding.property)?.[axisOf(binding)]
+    const actual = vector(entity(currentSpec, binding.entityId), binding.property)?.[axisOf(binding)]
+    if (!close(actual, expected)) conflicts.push({ parameterId: parameter.id, entityId: binding.entityId,
+      property: binding.property, axis: binding.axis, expected, actual })
+    if (binding.property === 'dimensions') {
+      const oldScale = entity(before.spec, binding.entityId).transform.scale
+      const scale = entity(currentSpec, binding.entityId)?.transform.scale
+      if (!scale?.every((value, axis) => close(value, oldScale[axis]))) {
+        conflicts.push({ parameterId: parameter.id, entityId: binding.entityId,
+          property: 'scale', expected: oldScale, actual: scale })
+      }
+    }
+  }
+  if (conflicts.length) throw new RecipeError('RECIPE_PARAMETER_CONFLICT',
+    'Recipe-controlled geometry was independently edited; resolve these fields before resizing', { conflicts })
+
+  const changed = parameters.filter(parameter => before.values[parameter.id] !== after.values[parameter.id])
+  const generators = new Map(), locations = new Map(), cameras = new Map(), tracks = new Map(), animationOffsets = new Map()
+  const protectedCameras = new Set()
+  for (const parameter of changed) for (const binding of parameter.bindings) {
+    const axis = axisOf(binding)
+    if (binding.kind === 'camera') {
+      const actual = currentSpec.cameras?.find(item => item.id === binding.cameraId)
+      const original = before.spec.cameras?.find(item => item.id === binding.cameraId)
+      // Independently authored photography remains intact, including deleted cameras.
+      if (!actual || canonicalStringify(actual) !== canonicalStringify(original)) {
+        protectedCameras.add(binding.cameraId); continue
+      }
+      if (!cameras.has(binding.cameraId)) cameras.set(binding.cameraId, { op: 'camera.update', cameraId: binding.cameraId })
+      const operation = cameras.get(binding.cameraId)
+      const target = after.spec.cameras.find(item => item.id === binding.cameraId)
+      if (binding.property === 'targetPoint') operation.targetPoint = structuredClone(target.targetPoint)
+      else operation.transform = { location: structuredClone(target.transform.location) }
+      continue
+    }
+    const actual = entity(currentSpec, binding.entityId), target = entity(after.spec, binding.entityId)
+    if (binding.property === 'dimensions') {
+      if (!generators.has(actual.id)) generators.set(actual.id, structuredClone(actual.generator))
+      generators.get(actual.id).dimensions[axis] = target.generator.dimensions[axis]
+    } else {
+      if (!locations.has(actual.id)) locations.set(actual.id, structuredClone(actual.transform.location))
+      const delta = target.transform.location[axis] - entity(before.spec, actual.id).transform.location[axis]
+      locations.get(actual.id)[axis] = target.transform.location[axis]
+      if (binding.offsetAnimation === true) animationOffsets.set(`${actual.id}:${binding.axis}`, {
+        entityId: actual.id, property: `location.${binding.axis}`, delta,
+      })
+    }
+  }
+  for (const offset of animationOffsets.values()) for (const track of currentSpec.animationTracks ?? []) {
+    if ((track.targetKind ?? 'entity') !== 'entity' || track.targetEntityId !== offset.entityId
+        || track.property !== offset.property) continue
+    if (!tracks.has(track.id)) tracks.set(track.id, structuredClone(track))
+    for (const keyframe of tracks.get(track.id).keyframes) keyframe.value += offset.delta
+  }
+  const operations = [
+    ...[...generators].map(([entityId, generator]) => ({ op: 'entity.generator.set', entityId, generator })),
+    ...[...locations].map(([entityId, location]) => ({ op: 'entity.transform.update', entityId, location })),
+    ...cameras.values(),
+    ...[...tracks.values()].map(track => ({ op: 'animation.track.set', track })),
+  ]
+  return { operations, changedParameters: changed.map(parameter => parameter.id),
+    preservedCameraIds: [...protectedCameras], parameterState: {
+      schemaVersion: 'deepblend.recipe-parameters/v1', manifestSha256: lock.manifestSha256,
+      values: after.values, valuesSha256: sha256Canonical(after.values),
+    } }
+}

package/lib/recipe.js

@@ -231,20 +231,14 @@ function bindingsAgainstScene(manifest, spec) {
   return errors
 }
 
-/** Hash actual loaded bytes; the manifest is a claim, never a verification receipt. */
-export function validateRecipePackage(bundle, options = {}) {
-  const checked = validateRecipeManifest(bundle?.manifest, options)
-  if (!checked.ok) return checked
-  const { manifest } = bundle
+/** Shared input validation; locked recipes do not retain original preview pixels. */
+function validateRecipeInput(manifest, input) {
   const errors = []
   let sceneSpec
   try {
-    const sceneBytes = asBytes(bundle.sceneBytes, RECIPE_LIMITS.sceneBytes, 'input')
-    const previewBytes = asBytes(bundle.previewBytes, RECIPE_LIMITS.previewBytes, 'preview')
+    const sceneBytes = asBytes(input, RECIPE_LIMITS.sceneBytes, 'input')
     if (sha256(sceneBytes) !== manifest.input.sha256) errors.push(issue('RECIPE_HASH_MISMATCH', 'input.sha256', 'Loaded SceneSpec bytes differ from the declared hash'))
-    if (sha256(previewBytes) !== manifest.preview.sha256) errors.push(issue('RECIPE_HASH_MISMATCH', 'preview.sha256', 'Loaded preview bytes differ from the declared hash'))
     if (errors.length) return result(errors)
-    try { validatePreview(previewBytes) } catch (error) { return result([issue('RECIPE_PREVIEW_INVALID', 'preview', error.message)]) }
     try { sceneSpec = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(sceneBytes)) }
     catch { return result([issue('RECIPE_INPUT_INVALID', 'input', 'SceneSpec must be valid UTF-8 JSON')]) }
     const scene = validateSceneSpec(sceneSpec)
@@ -269,12 +263,55 @@ export function validateRecipePackage(bundle, options = {}) {
   } catch (error) { return result([issue(error.code ?? 'RECIPE_INPUT_INVALID', 'input', error.message)]) }
 }
 
+/** Hash actual loaded bytes; the manifest is a claim, never a verification receipt. */
+export function validateRecipePackage(bundle, options = {}) {
+  const checked = validateRecipeManifest(bundle?.manifest, options)
+  if (!checked.ok) return checked
+  const { manifest } = bundle
+  try {
+    const sceneBytes = asBytes(bundle.sceneBytes, RECIPE_LIMITS.sceneBytes, 'input')
+    const previewBytes = asBytes(bundle.previewBytes, RECIPE_LIMITS.previewBytes, 'preview')
+    const errors = []
+    if (sha256(sceneBytes) !== manifest.input.sha256) errors.push(issue('RECIPE_HASH_MISMATCH', 'input.sha256', 'Loaded SceneSpec bytes differ from the declared hash'))
+    if (sha256(previewBytes) !== manifest.preview.sha256) errors.push(issue('RECIPE_HASH_MISMATCH', 'preview.sha256', 'Loaded preview bytes differ from the declared hash'))
+    if (errors.length) return result(errors)
+    try { validatePreview(previewBytes) } catch (error) { return result([issue('RECIPE_PREVIEW_INVALID', 'preview', error.message)]) }
+    return validateRecipeInput(manifest, sceneBytes)
+  } catch (error) { return result([issue(error.code ?? 'RECIPE_INPUT_INVALID', 'input', error.message)]) }
+}
+
 /** Return a fresh resolved SceneSpec; only explicit scalar/color slots can change. */
 export function instantiateRecipe(bundle, values = {}, options = {}) {
   const checked = validateRecipePackage(bundle, options)
   if (!checked.ok) throw new RecipeError(checked.errors[0].code, checked.summary, { errors: checked.errors })
+  return resolveRecipe(bundle.manifest, checked, values)
+}
+
+/** Resolve a saved origin without inventing or accepting replacement preview bytes. */
+export function instantiateRecipeLock(lock, changes = {}, options = {}) {
+  const fail = message => { throw new RecipeError('RECIPE_LOCK_INVALID', message) }
+  if (!plain(lock) || lock.schemaVersion !== 'deepblend.recipe-lock/v1') fail('Unsupported recipe lock')
+  const manifestCheck = validateRecipeManifest(lock.manifest, options)
+  if (!manifestCheck.ok) throw new RecipeError(manifestCheck.errors[0].code, manifestCheck.summary, { errors: manifestCheck.errors })
+  const { manifest } = lock
+  if (lock.id !== manifest.id || lock.version !== manifest.version
+      || lock.manifestSha256 !== sha256Canonical(manifest) || lock.packageDigest !== lock.manifestSha256
+      || lock.inputSha256 !== manifest.input.sha256 || lock.previewSha256 !== manifest.preview.sha256) {
+    fail('Recipe lock identity or manifest hashes differ')
+  }
+  if (typeof lock.sceneSource !== 'string' || lock.sceneSource.length > RECIPE_LIMITS.sceneBytes
+      || !plain(lock.values)) fail('Recipe lock must retain bounded exact input and resolved values')
+  const checked = validateRecipeInput(manifest, new TextEncoder().encode(lock.sceneSource))
+  if (!checked.ok) throw new RecipeError(checked.errors[0].code, checked.summary, { errors: checked.errors })
+  const original = resolveRecipe(manifest, checked, lock.values)
+  if (sha256Canonical(original.values) !== lock.valuesSha256
+      || sha256Canonical(lock.values) !== lock.valuesSha256) fail('Recipe lock values differ from their resolved hash')
+  if (!plain(changes)) throw new RecipeError('RECIPE_PARAMETER_INVALID', 'Parameter values must be a plain object')
+  return resolveRecipe(manifest, checked, { ...original.values, ...changes })
+}
+
+function resolveRecipe(manifest, checked, values) {
   if (!plain(values)) throw new RecipeError('RECIPE_PARAMETER_INVALID', 'Parameter values must be a plain object')
-  const { manifest } = bundle
   const known = new Set(manifest.parameters.map(parameter => parameter.id))
   const errors = Object.keys(values).filter(key => !known.has(key) || RESERVED.has(key))
     .map(key => issue('RECIPE_PARAMETER_UNKNOWN', `values.${key}`, 'Unknown parameter'))

package/lib/sdk.d.ts

@@ -94,6 +94,19 @@ export type RecipeValues = Record<string, number | [number, number, number]>;
 export interface RecipeBundle { manifest: RecipeManifest; sceneBytes: string | Uint8Array; previewBytes: string | Uint8Array }
 export interface RecipeOptions { supportedCapabilities?: Iterable<RecipeCapability> }
 export interface RecipeValidation extends ValidationResult { notices: SceneSpecIssue[]; sceneSpec?: SceneSpec }
+export interface RecipeLock {
+  schemaVersion: 'deepblend.recipe-lock/v1'; id: string; version: string;
+  manifestSha256: string; packageDigest: string; inputSha256: string; previewSha256: string;
+  valuesSha256: string; manifest: RecipeManifest; values: RecipeValues; sceneSource: string;
+}
+export interface RecipeParameterState {
+  schemaVersion: 'deepblend.recipe-parameters/v1'; manifestSha256: string;
+  values: RecipeValues; valuesSha256: string; originRevision?: string;
+}
+export interface RecipeGeometryPlan {
+  operations: ScenePatchOperation[]; changedParameters: string[]; preservedCameraIds: string[];
+  parameterState: RecipeParameterState;
+}
 export function recipeCapabilitiesForScene(spec: SceneSpec): RecipeCapability[];
 export function validateRecipeManifest(manifest: unknown, options?: RecipeOptions): RecipeValidation;
 export function parseRecipeManifest(manifest: unknown, options?: RecipeOptions): RecipeManifest;
@@ -102,3 +115,7 @@ export function instantiateRecipe(bundle: RecipeBundle, values?: RecipeValues, o
   spec: SceneSpec; values: RecipeValues; notices: SceneSpecIssue[];
   recipe: { id: string; version: string; manifestSha256: string; inputSha256: string; previewSha256: string; valuesSha256: string };
 };
+export function instantiateRecipeLock(lock: RecipeLock, changes?: RecipeValues, options?: RecipeOptions): ReturnType<typeof instantiateRecipe>;
+export function recipeGeometryParameters(manifest: RecipeManifest): RecipeManifest['parameters'];
+export function planRecipeGeometryEdit(lock: RecipeLock, currentSpec: SceneSpec,
+  parameterState: RecipeParameterState | undefined, changes: Record<string, number>): RecipeGeometryPlan;

package/lib/sdk.js

@@ -17,8 +17,9 @@ export {
 export { SCENE_OPERATION_NAMES, validateScenePatch, applyPatchToSpec, buildOperationManifest } from './scene-patch.js'
 export {
   RECIPE_SCHEMA_VERSION, RECIPE_CAPABILITIES, RECIPE_LIMITS, RecipeError,
-  recipeCapabilitiesForScene, validateRecipeManifest, validateRecipePackage, instantiateRecipe,
+  recipeCapabilitiesForScene, validateRecipeManifest, validateRecipePackage, instantiateRecipe, instantiateRecipeLock,
 } from './recipe.js'
+export { planRecipeGeometryEdit, recipeGeometryParameters } from './recipe-parameters.js'
 
 /** Validate untrusted JSON and return a separate document; never assert a type without checking it. */
 export function parseSceneSpec(input) {

package/lib/ui-api.js

@@ -83,6 +83,8 @@ export const UI_ROUTES = Object.freeze([
   { id: 'project.review', method: 'POST', path: '/deepblend/projects/:projectId/review', write: true, summary: 'Explicitly render and consult the visual reviewer for one revision.' },
   { id: 'project.autofix', method: 'POST', path: '/deepblend/projects/:projectId/autofix', write: true, summary: 'Explicitly run a bounded visual correction loop for one revision.' },
   { id: 'project.patch', method: 'POST', path: '/deepblend/projects/:projectId/patch', write: true, summary: 'Apply a ScenePatch as one atomic revision.' },
+  { id: 'project.recipeParameters', method: 'GET', path: '/deepblend/projects/:projectId/recipe-parameters', write: false, summary: 'Read saved assembly controls at one revision.' },
+  { id: 'project.recipeParameters.update', method: 'POST', path: '/deepblend/projects/:projectId/recipe-parameters', write: true, summary: 'Save bounded assembly dimensions as an atomic revision.' },
   { id: 'project.restore', method: 'POST', path: '/deepblend/projects/:projectId/restore', write: true, summary: 'Move the current revision pointer to a saved revision, preserving history without creating a new revision.' },
   { id: 'project.jobs', method: 'GET', path: '/deepblend/projects/:projectId/jobs', write: false, summary: 'Render/export jobs of a project.' },
   { id: 'project.job', method: 'GET', path: '/deepblend/projects/:projectId/jobs/:jobId', write: false, summary: 'One job with its live progress.' },
@@ -930,4 +932,5 @@ export const UI_TOOL_CARD_KEYS = Object.freeze([
   'blender_export',
   'blender_job_status',
   'blender_job_cancel',
+  'blender_recipe_parameters',
 ])

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepblend/dsh-blender-contracts",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "description": "DeepBlend Studio Service Definition, protocol contracts, and stable error codes.",
   "main": "lib/index.js",