@deepblend/dsh-blender-host 0.2.20 → 0.3.0

package/lib/obj-resources.js

@@ -0,0 +1,89 @@
+/** Inspect OBJ/MTL file references without loading a mesh or rewriting source bytes. */
+import { openSync, closeSync, readSync, statSync } from 'node:fs'
+import { BlenderError, BlenderErrorCode } from '@deepblend/dsh-blender-contracts'
+
+export const OBJ_LIMITS = Object.freeze({ modelBytes: 1024 * 1024 * 1024, materialBytes: 16 * 1024 * 1024, lineBytes: 1024 * 1024 })
+const invalid = (message, code = BlenderErrorCode.ASSET_REQUEST_INVALID) => { throw new BlenderError(code, message) }
+const numeric = value => /^[+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?$/i.test(value) && Number.isFinite(Number(value))
+const mapKeys = new Set(['map_Kd', 'map_Ks', 'map_Ns', 'map_d', 'refl', 'map_refl', 'map_Ke', 'bump', 'map_Bump', 'map_bump', 'map_Pr', 'map_Pm', 'map_Ps'])
+const counts = { '-bm': 1, '-type': 1, '-blendu': 1, '-blendv': 1, '-boost': 1, '-cc': 1, '-clamp': 1, '-imfchan': 1, '-mm': 2, '-t': 3, '-texres': 1 }
+
+/** Physical lines are bounded; only OBJ has backslash/newline continuation. */
+function lines(file, limit, callback, { continuation = false, signal } = {}) {
+  signal?.throwIfAborted()
+  if (statSync(file).size > limit) invalid('OBJ/MTL text exceeds its byte limit.', BlenderErrorCode.ASSET_TOO_LARGE)
+  const fd = openSync(file, 'r'), decoder = new TextDecoder('utf-8', { fatal: true }), chunk = Buffer.alloc(64 * 1024)
+  let pending = '', logical = '', bytes = 0
+  const emit = physical => {
+    if (Buffer.byteLength(physical) > OBJ_LIMITS.lineBytes) invalid('OBJ/MTL lines exceed 1 MiB.', BlenderErrorCode.ASSET_TOO_LARGE)
+    const continued = continuation && /\\[\t\r ]*$/.test(physical)
+    logical += continued ? physical.replace(/\\[\t\r ]*$/, ' ') : physical
+    if (Buffer.byteLength(logical) > OBJ_LIMITS.lineBytes) invalid('OBJ/MTL logical lines exceed 1 MiB.', BlenderErrorCode.ASSET_TOO_LARGE)
+    if (!continued) { callback(logical); logical = '' }
+  }
+  try {
+    for (;;) {
+      signal?.throwIfAborted()
+      const n = readSync(fd, chunk, 0, chunk.length, null)
+      bytes += n
+      if (bytes > limit) invalid('OBJ/MTL text exceeds its byte limit.', BlenderErrorCode.ASSET_TOO_LARGE)
+      pending += decoder.decode(chunk.subarray(0, n), { stream: n !== 0 })
+      let start = 0, end
+      while ((end = pending.indexOf('\n', start)) >= 0) { emit(pending.slice(start, end)); start = end + 1 }
+      pending = pending.slice(start)
+      if (Buffer.byteLength(pending) > OBJ_LIMITS.lineBytes) invalid('OBJ/MTL lines exceed 1 MiB.', BlenderErrorCode.ASSET_TOO_LARGE)
+      if (!n) { if (pending || logical) emit(pending); if (logical) callback(logical); break }
+    }
+  } catch (error) {
+    signal?.throwIfAborted()
+    if (error instanceof BlenderError) throw error
+    invalid('OBJ/MTL text must be valid UTF-8.', BlenderErrorCode.ASSET_CONTENT_MISMATCH)
+  } finally { closeSync(fd) }
+}
+const field = line => /^\s*([^\s]+)(?:\s+(.*))?$/.exec(line.trim())
+export function objLibraries(file, options = {}) {
+  const libraries = new Set()
+  lines(file, OBJ_LIMITS.modelBytes, line => {
+    const match = field(line)
+    if (match?.[1] !== 'mtllib') return
+    let name = (match[2] ?? '').trim()
+    if (name.length > 2 && name.startsWith('"') && name.endsWith('"')) name = name.slice(1, -1)
+    if (!name) invalid('An OBJ material library reference is empty.')
+    libraries.add(name)
+  }, { ...options, continuation: true })
+  return [...libraries]
+}
+export function mtlImages(file, options = {}) {
+  const images = new Set()
+  let material = false
+  lines(file, OBJ_LIMITS.materialBytes, line => {
+    const match = field(line)
+    if (!match) return
+    if (match[1] === 'newmtl') { material = true; return }
+    if (!material || !mapKeys.has(match[1])) return
+    let rest = (match[2] ?? '').trim()
+    for (;;) {
+      const token = /^([^\s]+)(?:\s+|$)/.exec(rest)?.[1]
+      if (!token) break
+      if (['-o', '-s'].includes(token)) {
+        rest = rest.slice(token.length).trimStart()
+        for (let n = 0; n < 3; n++) {
+          const value = /^([^\s]+)(?:\s+|$)/.exec(rest)?.[1]
+          if (!numeric(value ?? '')) break
+          rest = rest.slice(value.length).trimStart()
+        }
+      } else if (Object.hasOwn(counts, token)) {
+        rest = rest.slice(token.length).trimStart()
+        for (let n = 0; n < counts[token]; n++) {
+          const value = /^([^\s]+)(?:\s+|$)/.exec(rest)?.[1]
+          if (!value || (token === '-bm' && !numeric(value))) invalid('An MTL texture option is incomplete or invalid.')
+          rest = rest.slice(value.length).trimStart()
+        }
+      } else break
+    }
+    const name = rest.trim().replaceAll('"', '')
+    if (!name) invalid('An MTL texture reference is empty.')
+    images.add(name)
+  }, options)
+  return [...images]
+}

package/lib/paths.js

@@ -21,6 +21,9 @@
 import { createHash } from 'node:crypto'
 import {
   existsSync,
+  openSync,
+  closeSync,
+  readSync,
   mkdirSync,
   readFileSync,
   readdirSync,
@@ -272,10 +275,18 @@ export function fileSize(path) {
 
 /** sha256 of a file's bytes, or `null` when the file is absent. */
 export function fileSha256(path) {
+  let descriptor
   try {
-    return createHash('sha256').update(readFileSync(path)).digest('hex')
+    descriptor = openSync(path, 'r')
+    const hash = createHash('sha256')
+    const buffer = Buffer.allocUnsafe(64 * 1024)
+    let bytes
+    while ((bytes = readSync(descriptor, buffer, 0, buffer.length, null)) > 0) hash.update(buffer.subarray(0, bytes))
+    return hash.digest('hex')
   } catch {
     return null
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor)
   }
 }
 

package/lib/project-store.js

@@ -36,14 +36,17 @@
  *    revision manifest describes that revision and nothing else, so publishing a
  *    revision and moving the pointer stay two separate steps and a half-finished
  *    publish cannot claim to be current.
- *  - **`staging/` is the only mutable revision state.** Everything under
- *    `revisions/` was published by an atomic rename and is never written again.
+ *  - **Revision decisions are immutable.** SceneSpecs and checkpoints publish by
+ *    atomic rename; later emitted artifacts amend only their protected indices.
  *
  * Owner: DeepBlend Studio — M1
  */
 
 import { existsSync, readdirSync } from 'node:fs'
+import { randomUUID } from 'node:crypto'
 import { join } from 'node:path'
+import { assertProjectWriter, withProjectWriter } from './project-writer.js'
+import { withArtifactWriter } from './artifact-writer.js'
 
 import {
   BlenderError,
@@ -186,6 +189,16 @@ export class ProjectStore {
     return record
   }
 
+  /** Hold the revision writer lease until a synchronous or asynchronous action finishes. */
+  withProjectWrite(projectId, action) {
+    return withProjectWriter(this.projectDirectory(projectId), this.workspaceRoot, action)
+  }
+
+  /** Check ownership again immediately before publishing a revision. */
+  assertProjectWrite(projectId) {
+    assertProjectWriter(this.projectDirectory(projectId))
+  }
+
   /**
    * Allocate a project id from a title, avoiding collisions.
    *
@@ -303,7 +316,7 @@ export class ProjectStore {
    * @param {string} projectId
    * @param {string} revision
    * @param {object} artifact
-   * @returns {object[]} the revision's previews, in render order.
+   * @returns {Promise<object[]>} the revision's previews, in render order.
    */
   recordRevisionPreview(projectId, revision, artifact) {
     return this.recordRevisionArtifact(projectId, revision, 'previews', artifact)
@@ -333,22 +346,29 @@ export class ProjectStore {
    * @param {string} revision
    * @param {'previews'|'contactSheets'|'reviews'} indexKey
    * @param {object} artifact
-   * @returns {object[]} the revision's entries under that key, in emission order.
+   * @returns {Promise<object[]>} the revision's entries under that key, in emission order.
    */
   recordRevisionArtifact(projectId, revision, indexKey, artifact) {
-    const path = join(this.revisionDirectory(projectId, revision), 'revision-manifest.json')
-    const manifest = readJson(path)
-    if (manifest === null) {
-      // A revision directory with no manifest did not finish publishing, so there
-      // is nothing to amend and nothing safe to write into it.
-      return [artifact]
-    }
-    const existing = Array.isArray(manifest[indexKey]) ? manifest[indexKey] : []
-    // Re-emitting the same path replaces its entry rather than duplicating it:
-    // re-rendering a view after a fix must not make the sheet look like two.
-    const next = [...existing.filter(entry => entry.path !== artifact.path), artifact]
-    writeJsonAtomic(path, { ...manifest, [indexKey]: next })
-    return next
+    return this.withRevisionArtifacts(projectId, revision, () => {
+      const path = join(this.revisionDirectory(projectId, revision), 'revision-manifest.json')
+      const manifest = readJson(path)
+      if (manifest === null) {
+        // A revision directory with no manifest did not finish publishing, so there
+        // is nothing to amend and nothing safe to write into it.
+        return [artifact]
+      }
+      const existing = Array.isArray(manifest[indexKey]) ? manifest[indexKey] : []
+      // Re-emitting the same path replaces its entry rather than duplicating it:
+      // re-rendering a view after a fix must not make the sheet look like two.
+      const next = [...existing.filter(entry => entry.path !== artifact.path), artifact]
+      writeJsonAtomic(path, { ...manifest, [indexKey]: next })
+      return next
+    })
+  }
+
+  /** Coordinate a short group of file publications and manifest amendments. */
+  withRevisionArtifacts(projectId, revision, action, options = {}) {
+    return withArtifactWriter(this.revisionDirectory(projectId, revision), this.workspaceRoot, action, options)
   }
 
   /**
@@ -416,19 +436,15 @@ export class ProjectStore {
   }
 
   /**
-   * Allocate a job id. Monotonic within the project and readable in a log,
-   * because a job id ends up in a tool result the model reasons about.
+   * Allocate an opaque attempt id across independent Host processes. The time
+   * helps locate an attempt; uniqueness must not depend on directory counts.
    * @param {string} projectId
    * @param {string} action
    * @returns {string}
    */
   allocateJobId(projectId, action) {
-    const directory = join(this.projectDirectory(projectId), 'jobs')
-    const existing = existsSync(directory)
-      ? readdirSync(directory).filter(name => name.endsWith('.json')).length
-      : 0
     const stamp = new Date().toISOString().replace(/[-:.TZ]/g, '').slice(0, 14)
-    return `${action}-${stamp}-${String(existing + 1).padStart(3, '0')}`
+    return `${action}-${stamp}-${randomUUID()}`
   }
 
   // -------------------------------------------------------------------------

package/lib/project-writer.js

@@ -0,0 +1,96 @@
+/**
+ * A project has one revision writer, including across local Node processes.
+ *
+ * mkdir is the acquisition primitive. A lease has no time-based expiry: a slow
+ * compile must never lose ownership to a timeout. Only a recorded owner on this
+ * host whose process is known to be gone can be recovered automatically. Missing
+ * or malformed ownership, another hostname, EPERM and a reused live PID all fail
+ * closed. The recovery guard is deliberately not recovered automatically; a crash
+ * inside that short critical section needs an operator to inspect the lock paths.
+ *
+ * This coordinates cooperating processes on one local filesystem. It is not a
+ * distributed lock for network filesystems or protection against external edits.
+ */
+import { mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { randomUUID } from 'node:crypto'
+import { hostname } from 'node:os'
+import { basename, join } from 'node:path'
+import { BlenderError, BlenderErrorCode, sha256 } from '@deepblend/dsh-blender-contracts'
+import { ensureDirectory, readJsonSafe, resolveInside } from './paths.js'
+
+const held = new Map()
+
+function ownerAt(path) {
+  try { return JSON.parse(readFileSync(join(path, 'owner.json'), 'utf8')) } catch { return null }
+}
+
+function gone(owner) {
+  if (owner?.hostname !== hostname() || !Number.isSafeInteger(owner.pid) || owner.pid <= 0
+      || typeof owner.token !== 'string' || owner.token.length === 0) return false
+  try { process.kill(owner.pid, 0); return false } catch (cause) { return cause.code === 'ESRCH' }
+}
+
+function conflict(directory, lockPath, owner, reason = 'another revision write is in progress') {
+  const currentRevision = readJsonSafe(join(directory, 'project.json'))?.currentRevision ?? null
+  return new BlenderError(BlenderErrorCode.REVISION_CONFLICT,
+    `Project "${basename(directory)}" cannot be changed: ${reason}. Current revision is ${currentRevision ?? 'not yet created'}. ` +
+    'Wait for the writer to finish, then read the scene again before retrying. ' +
+    'If a lock owner cannot be verified, inspect the lock only after all writers have stopped.',
+    { detail: { projectId: basename(directory), currentRevision, lockPath, owner } })
+}
+
+function acquire(directory, workspaceRoot) {
+  const root = ensureDirectory(workspaceRoot, join(workspaceRoot, '.revision-writers'), 'revision writer locks')
+  const lockPath = resolveInside(root, join(root, sha256(directory)), 'project writer lock')
+  const recoveryPath = `${lockPath}.recovery`
+  const owner = { pid: process.pid, hostname: hostname(), token: randomUUID(), createdAt: new Date().toISOString() }
+  // Creating the recovery guard is itself an atomic test for another recovery.
+  // Normal acquisition also passes through it, so no new writer can enter between
+  // checking a dead owner and removing its stale lease.
+  try { mkdirSync(recoveryPath) } catch (cause) {
+    if (cause.code !== 'EEXIST') throw cause
+    throw conflict(directory, recoveryPath, ownerAt(lockPath), 'writer ownership is being checked or requires recovery')
+  }
+  try {
+    try { mkdirSync(lockPath) } catch (cause) {
+      if (cause.code !== 'EEXIST') throw cause
+      const previous = ownerAt(lockPath)
+      if (!gone(previous)) throw conflict(directory, lockPath, previous)
+      rmSync(lockPath, { recursive: true })
+      mkdirSync(lockPath)
+    }
+    try {
+      writeFileSync(join(lockPath, 'owner.json'), JSON.stringify(owner), { flag: 'wx', mode: 0o600 })
+    } catch (cause) {
+      rmSync(lockPath, { recursive: true, force: true })
+      throw cause
+    }
+    return { lockPath, owner }
+  } finally {
+    rmSync(recoveryPath, { recursive: true, force: true })
+  }
+}
+
+export function assertProjectWriter(directory) {
+  const lease = held.get(directory)
+  if (!lease || ownerAt(lease.lockPath)?.token !== lease.owner.token) {
+    throw conflict(directory, lease?.lockPath ?? null, null, 'this transaction no longer owns the project writer lease')
+  }
+}
+
+export function withProjectWriter(directory, workspaceRoot, action) {
+  const existing = held.get(directory)
+  if (existing) throw conflict(directory, existing.lockPath, existing.owner)
+  const lease = acquire(directory, workspaceRoot)
+  held.set(directory, lease)
+  const release = () => {
+    held.delete(directory)
+    // Never remove another writer's lease after an external lock replacement.
+    if (ownerAt(lease.lockPath)?.token === lease.owner.token) rmSync(lease.lockPath, { recursive: true, force: true })
+  }
+  let result
+  try { result = action() } catch (cause) { release(); throw cause }
+  if (result && typeof result.then === 'function') return Promise.resolve(result).finally(release)
+  release()
+  return result
+}

package/lib/recipe-catalog.js

@@ -0,0 +1,128 @@
+/** Local, data-only recipe packages. Only operator-configured directories are read. */
+import { constants, openSync, closeSync, fstatSync, readSync, lstatSync, readdirSync, realpathSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { BlenderError, canonicalStringify, sha256, validateRecipePackage, instantiateRecipe, RECIPE_LIMITS, RECIPE_SCHEMA_VERSION } from '@deepblend/dsh-blender-contracts'
+
+export const BUILTIN_RECIPES = fileURLToPath(new URL('../recipes/', import.meta.url))
+const fail = (code, message) => { throw new BlenderError(code, message) }
+const identity = manifest => `${manifest.id}@${manifest.version}`
+const limits = { 'recipe.json': 65536, 'scene-spec.json': RECIPE_LIMITS.sceneBytes, 'preview.png': RECIPE_LIMITS.previewBytes }
+
+function readBounded(path, limit) {
+  if (lstatSync(path).isSymbolicLink()) fail('RECIPE_PATH_INVALID', 'Recipe files cannot be symbolic links')
+  const fd = openSync(path, constants.O_RDONLY | constants.O_NOFOLLOW)
+  try {
+    const stat = fstatSync(fd)
+    if (!stat.isFile() || stat.size > limit) fail('RECIPE_SIZE_LIMIT', 'Recipe file exceeds its byte limit or is not a regular file')
+    const bytes = Buffer.alloc(limit + 1)
+    let length = 0, read = 0
+    do { read = readSync(fd, bytes, length, bytes.length - length, null); length += read } while (read && length < bytes.length)
+    if (length > limit) fail('RECIPE_SIZE_LIMIT', 'Recipe file grew beyond its byte limit')
+    return Buffer.from(bytes.subarray(0, length))
+  } finally { closeSync(fd) }
+}
+
+export class RecipeCatalog {
+  constructor({ directories = [], builtinRoot = BUILTIN_RECIPES } = {}) {
+    if (directories.length > 32) fail('RECIPE_CATALOG_LIMIT', 'At most 32 recipe directories may be configured')
+    this.roots = [...new Set([builtinRoot, ...directories].map(path => resolve(path)))]
+    this.cache = new Map()
+  }
+
+  _read(directory, fresh = false) {
+    if (lstatSync(directory).isSymbolicLink() || !lstatSync(directory).isDirectory()) fail('RECIPE_PATH_INVALID', 'Recipe packages must be real directories')
+    const real = realpathSync(directory)
+    if (dirname(real) !== realpathSync(dirname(directory))) fail('RECIPE_PATH_INVALID', 'Recipe directory escapes its registered root')
+    const signature = Object.keys(limits).map(name => {
+      const stat = lstatSync(join(real, name), { bigint: true })
+      if (!stat.isFile() || stat.isSymbolicLink()) fail('RECIPE_PATH_INVALID', 'Recipe files must be regular files')
+      return `${name}:${stat.dev}:${stat.ino}:${stat.size}:${stat.mtimeNs}:${stat.ctimeNs}`
+    }).join('|')
+    const cached = this.cache.get(real)
+    if (!fresh && cached?.signature === signature) return cached
+    const manifestBytes = readBounded(join(real, 'recipe.json'), limits['recipe.json'])
+    const bundle = { manifest: JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(manifestBytes)),
+      sceneBytes: readBounded(join(real, 'scene-spec.json'), limits['scene-spec.json']),
+      previewBytes: readBounded(join(real, 'preview.png'), limits['preview.png']) }
+    const check = validateRecipePackage(bundle)
+    if (!check.ok) fail(check.errors[0].code, check.summary)
+    const digest = sha256(canonicalStringify(bundle.manifest))
+    const { id, version, title, description, author, license, source, parameters } = bundle.manifest
+    const value = { signature, directory: real, bundle, digest,
+      summary: { id, version, title, description, author, license, source, parameters, digest,
+        previewUrl: `/deepblend/recipes/${encodeURIComponent(id)}/${encodeURIComponent(version)}/preview?digest=${digest}` } }
+    value.byteLength = manifestBytes.length + bundle.sceneBytes.length + bundle.previewBytes.length
+    this.cache.delete(real)
+    this.cache.set(real, value)
+    let cachedBytes = [...this.cache.values()].reduce((sum, item) => sum + item.byteLength, 0)
+    for (const [key, item] of this.cache) {
+      if (cachedBytes <= 64 * 1024 * 1024) break
+      this.cache.delete(key); cachedBytes -= item.byteLength
+    }
+    return value
+  }
+
+  _scan() {
+    const entries = new Map(), conflicts = new Set(), errors = []
+    let count = 0
+    const seenRoots = new Set()
+    for (const root of this.roots) {
+      try {
+        const realRoot = realpathSync(root)
+        if (seenRoots.has(realRoot)) continue
+        seenRoots.add(realRoot)
+        for (const folder of readdirSync(realRoot, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+          if (!folder.isDirectory() && !folder.isSymbolicLink()) continue
+          if (++count > 200) fail('RECIPE_CATALOG_LIMIT', 'At most 200 recipe packages may be registered')
+          try {
+            const entry = this._read(join(realRoot, folder.name)), key = identity(entry.bundle.manifest)
+            if (entries.has(key) || conflicts.has(key)) {
+              entries.delete(key); conflicts.add(key)
+              fail('RECIPE_ID_CONFLICT', `More than one package declares ${key}; neither can be selected`)
+            }
+            entries.set(key, { directory: entry.directory, summary: entry.summary })
+          } catch (error) { errors.push({ package: folder.name, code: error.code ?? 'RECIPE_PACKAGE_INVALID', message: error.message }) }
+        }
+      } catch (error) { errors.push({ code: error.code ?? 'RECIPE_DIRECTORY_INVALID', message: error.message }) }
+    }
+    const active = new Set([...entries.values()].map(entry => entry.directory))
+    for (const key of this.cache.keys()) if (!active.has(key)) this.cache.delete(key)
+    return { entries, errors }
+  }
+
+  list() {
+    const { entries, errors } = this._scan()
+    return { recipeSchemaVersion: RECIPE_SCHEMA_VERSION, recipes: [...entries.values()].map(entry => structuredClone(entry.summary)), errors }
+  }
+
+  get(request) {
+    if (!request || typeof request.id !== 'string' || typeof request.version !== 'string' || !/^[a-f0-9]{64}$/.test(request.digest ?? '')) {
+      fail('RECIPE_REQUEST_INVALID', 'Select a recipe with its id, version and digest')
+    }
+    const entry = this._scan().entries.get(`${request.id}@${request.version}`)
+    if (!entry) fail('RECIPE_NOT_FOUND', 'The selected recipe is unavailable; refresh the catalog')
+    // Recheck actual bytes at the write/preview boundary, even when listing used a cache.
+    const current = this._read(entry.directory, true)
+    if (current.digest !== request.digest) fail('RECIPE_CHANGED', 'The recipe changed; refresh the catalog before creating a project')
+    return current
+  }
+
+  instantiate(request) {
+    const entry = this.get(request)
+    let result
+    try { result = instantiateRecipe(entry.bundle, request.parameters === undefined ? {} : request.parameters) }
+    catch (error) { throw new BlenderError(error.code ?? 'RECIPE_PARAMETER_INVALID', error.message, { detail: error.details }) }
+    return { sceneSpec: result.spec, lock: {
+      schemaVersion: 'deepblend.recipe-lock/v1', ...result.recipe, packageDigest: entry.digest,
+      manifest: entry.bundle.manifest, values: result.values,
+      // Exact bytes make the declared input hash verifiable after the local recipe is removed.
+      sceneSource: entry.bundle.sceneBytes.toString('utf8'),
+    } }
+  }
+
+  preview(request) {
+    const { bundle } = this.get(request)
+    return { bytes: bundle.previewBytes, contentType: 'image/png', size: bundle.previewBytes.length }
+  }
+}

package/lib/reference-image.js

@@ -0,0 +1,186 @@
+import { createHash } from 'node:crypto'
+import { extname } from 'node:path'
+import { BlenderError, BlenderErrorCode } from '@deepblend/dsh-blender-contracts'
+
+export const REFERENCE_IMAGE_MAX_BYTES = 8 * 1024 * 1024
+export const REFERENCE_IMAGE_MAX_PIXELS = 16_000_000
+export const REFERENCE_IMAGE_MAX_EDGE = 8192
+
+const PNG_SIGNATURE = Buffer.from([137, 80, 78, 71, 13, 10, 26, 10])
+const CRC_TABLE = Uint32Array.from({ length: 256 }, (_, value) => {
+  for (let bit = 0; bit < 8; bit += 1) value = (value >>> 1) ^ ((value & 1) ? 0xedb88320 : 0)
+  return value >>> 0
+})
+
+function invalid(message) {
+  throw new BlenderError(BlenderErrorCode.ASSET_REQUEST_INVALID, message)
+}
+
+function mismatch(message, cause) {
+  throw new BlenderError(BlenderErrorCode.ASSET_CONTENT_MISMATCH, message, { cause })
+}
+
+function crc32(bytes) {
+  let value = 0xffffffff
+  for (const byte of bytes) value = CRC_TABLE[(value ^ byte) & 0xff] ^ (value >>> 8)
+  return (value ^ 0xffffffff) >>> 0
+}
+
+// libpng can ignore unknown ancillary chunks, including APNG's animation chunks.
+// Check the complete container as well as decoding its pixels; never silently
+// accept just a first frame, a concatenated file, or a damaged ancillary chunk.
+function checkPng(data) {
+  let offset = PNG_SIGNATURE.length
+  let imageData = false
+  let imageDataEnded = false
+  while (offset < data.length) {
+    if (offset + 12 > data.length) mismatch('The PNG image has a truncated chunk.')
+    const length = data.readUInt32BE(offset)
+    const end = offset + 12 + length
+    if (end > data.length) mismatch('The PNG image has a truncated chunk.')
+    const type = data.toString('ascii', offset + 4, offset + 8)
+    if (!/^[A-Za-z]{2}[A-Z][A-Za-z]$/.test(type)) mismatch('The PNG image has an invalid chunk type.')
+    if (crc32(data.subarray(offset + 4, end - 4)) !== data.readUInt32BE(end - 4)) {
+      mismatch('The PNG image has a damaged chunk checksum.')
+    }
+    if (offset === 8 ? type !== 'IHDR' || length !== 13 : type === 'IHDR') {
+      mismatch('The PNG image has an invalid header.')
+    }
+    if (['acTL', 'fcTL', 'fdAT'].includes(type)) invalid('Reference images must be still images; animated PNG is not supported.')
+    if (type === 'IDAT') {
+      if (imageDataEnded) mismatch('The PNG image has nonconsecutive pixel chunks.')
+      imageData = true
+    } else if (imageData) imageDataEnded = true
+    if (type === 'IEND') {
+      if (length !== 0 || !imageData || end !== data.length) mismatch('The PNG image has an invalid ending or trailing content.')
+      return
+    }
+    offset = end
+  }
+  mismatch('The PNG image is missing its complete ending.')
+}
+
+// Walk marker lengths and entropy-coded scans so progressive JPEG remains valid
+// while truncated streams and extra images after EOI cannot be repaired by the
+// decoder. MPF is a multi-picture container even if only its first image decodes.
+function checkJpeg(data) {
+  let offset = 2
+  let sawScan = false
+  let frames = 0
+  let inScan = false
+  while (offset < data.length) {
+    if (inScan) {
+      while (offset < data.length) {
+        if (data[offset] !== 0xff) { offset += 1; continue }
+        const start = offset
+        while (data[offset] === 0xff) offset += 1
+        const marker = data[offset]
+        if (marker === 0x00 || (marker >= 0xd0 && marker <= 0xd7)) { offset += 1; continue }
+        offset = start
+        inScan = false
+        break
+      }
+    }
+    if (data[offset] !== 0xff) mismatch('The JPEG image has a truncated scan or invalid marker.')
+    while (data[offset] === 0xff) offset += 1
+    const marker = data[offset++]
+    if (marker === 0xd9) {
+      if (!sawScan || offset !== data.length) mismatch('The JPEG image has an invalid ending or trailing content.')
+      return
+    }
+    if (marker === undefined || marker === 0x00 || marker === 0xd8 || (marker >= 0xd0 && marker <= 0xd7)) {
+      mismatch('The JPEG image has an invalid marker.')
+    }
+    if (marker === 0x01) continue // TEM is the only other stand-alone marker.
+    if (offset + 2 > data.length) mismatch('The JPEG image has a truncated segment.')
+    const length = data.readUInt16BE(offset)
+    const end = offset + length
+    if (length < 2 || end > data.length) mismatch('The JPEG image has a truncated segment.')
+    if (marker === 0xe2 && data.toString('latin1', offset + 2, offset + 6) === 'MPF\0') {
+      invalid('Reference images must contain one image; multi-picture JPEG is not supported.')
+    }
+    if (marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker)) {
+      frames += 1
+      if (frames > 1) invalid('Reference images must contain one image; multi-frame JPEG is not supported.')
+    }
+    offset = end
+    if (marker === 0xda) { sawScan = true; inScan = true }
+  }
+  mismatch('The JPEG image is missing its complete ending.')
+}
+
+/**
+ * Inspect immutable source bytes without resizing, orienting or re-encoding.
+ * Width/height describe the stored pixel grid, before any EXIF orientation.
+ * The native codec is loaded only when a reference image is actually inspected.
+ */
+export async function inspectReferenceImage(data, { name, mediaType } = {}) {
+  if (!(data instanceof Uint8Array) || data.byteLength === 0) invalid('A reference image must contain PNG or JPEG bytes.')
+  if (data.byteLength > REFERENCE_IMAGE_MAX_BYTES) {
+    throw new BlenderError(BlenderErrorCode.ASSET_TOO_LARGE, 'A reference image must be at most 8 MiB.', {
+      detail: { bytes: data.byteLength, maxBytes: REFERENCE_IMAGE_MAX_BYTES },
+    })
+  }
+  let extension
+  if (name !== undefined) {
+    if (typeof name !== 'string' || !name.trim()) invalid('A reference image name must end in .png, .jpg or .jpeg.')
+    extension = extname(name).slice(1).toLowerCase()
+    if (!['png', 'jpg', 'jpeg'].includes(extension)) invalid('A reference image name must end in .png, .jpg or .jpeg.')
+  }
+  let declaredMime
+  if (mediaType !== undefined) {
+    if (typeof mediaType !== 'string') invalid('A reference image media type must be image/png or image/jpeg.')
+    declaredMime = mediaType.trim().toLowerCase()
+    if (!['image/png', 'image/jpeg'].includes(declaredMime)) invalid('A reference image media type must be image/png or image/jpeg.')
+  }
+  // Own the bytes across asynchronous decode so a caller cannot change the hash
+  // or source content after its type was checked.
+  const source = Buffer.from(data)
+  const format = source.subarray(0, 8).equals(PNG_SIGNATURE) ? 'png'
+    : source[0] === 0xff && source[1] === 0xd8 && source[2] === 0xff ? 'jpeg' : undefined
+  if (!format) mismatch('The reference image bytes are not a PNG or JPEG image.')
+  const mime = format === 'png' ? 'image/png' : 'image/jpeg'
+  if ((extension && (extension === 'png' ? 'png' : 'jpeg') !== format) || (declaredMime && declaredMime !== mime)) {
+    mismatch('The reference image extension, media type and actual content must agree.')
+  }
+  if (format === 'png') checkPng(source)
+  else checkJpeg(source)
+
+  // Installation errors are not malformed user files. Let the original import
+  // failure surface with its actionable native-binary/package diagnostic.
+  const { default: sharp } = await import('sharp')
+  let metadata
+  try {
+    // metadata() does not decode pixels. Keep libvips' safety checks; our stricter
+    // dimensions are checked below before allocating the decoded image buffer.
+    metadata = await sharp(source, { failOn: 'warning', limitInputPixels: false }).metadata()
+  } catch (cause) {
+    mismatch('The reference image metadata is invalid.', cause)
+  }
+  const { width, height } = metadata
+  if (metadata.format !== format || !Number.isSafeInteger(width) || !Number.isSafeInteger(height) || width < 1 || height < 1) {
+    mismatch('The reference image has invalid dimensions or content type.')
+  }
+  if ((metadata.pages ?? 1) !== 1 || metadata.pageHeight !== undefined || metadata.loop !== undefined || metadata.delay !== undefined) {
+    invalid('Reference images must contain one still image.')
+  }
+  if (width > REFERENCE_IMAGE_MAX_EDGE || height > REFERENCE_IMAGE_MAX_EDGE || width * height > REFERENCE_IMAGE_MAX_PIXELS) {
+    throw new BlenderError(BlenderErrorCode.ASSET_TOO_LARGE, 'A reference image must be at most 16 megapixels and 8192 pixels on each side.', {
+      detail: { width, height, maxPixels: REFERENCE_IMAGE_MAX_PIXELS, maxEdge: REFERENCE_IMAGE_MAX_EDGE },
+    })
+  }
+  try {
+    // raw().toBuffer() forces every pixel to be decoded; metadata alone accepts
+    // some corrupt/truncated pixel streams. No encoded copy replaces the source.
+    const { info } = await sharp(source, { failOn: 'warning', limitInputPixels: REFERENCE_IMAGE_MAX_PIXELS })
+      .raw().toBuffer({ resolveWithObject: true })
+    if (info.width !== width || info.height !== height) mismatch('The decoded reference image dimensions do not match its header.')
+  } catch (cause) {
+    if (cause instanceof BlenderError) throw cause
+    mismatch('The reference image pixels cannot be completely decoded.', cause)
+  }
+  return {
+    type: extension ?? (format === 'png' ? 'png' : 'jpg'), mime, width, height,
+    bytes: source.length, sha256: createHash('sha256').update(source).digest('hex'),
+  }
+}

package/lib/render-job-store.js

@@ -24,8 +24,8 @@
  * `jobs/` holds M1's attempt log: written once at the start of an action and once
  * at the end, because every M1/M2 action finished inside the tool call that
  * started it. The durable render job is a different object with a different
- * lifetime (SPEC §10.2), and `allocateJobId` counts `*.json` in `jobs/` to mint
- * its ids — writing render jobs there would both inflate that counter and make
+ * lifetime (SPEC §10.2). Attempt ids use UUIDs; delivery ids keep their existing
+ * ordinal format. Writing render jobs into `jobs/` would make
  * "list this project's attempts" return two shapes.
  *
  * WHY THE RECORD IS WRITTEN SO OFTEN