@deepblend/dsh-blender-contracts 0.1.0

package/lib/asset-content.js

@@ -0,0 +1,134 @@
+/**
+ * What a file's first bytes say it is — the content half of SPEC §15.2's
+ * "MIME 与扩展名双重校验".
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * The extension check (`IMPORT_OPERATOR_BY_ASSET_TYPE`) decides which import operator a file
+ * gets, and it trusts the NAME. That is fine as far as it goes — Blender classifies the import
+ * behaviourally and a file that is not really a glTF fails as a branchable result (D10) — but
+ * it means the first thing that notices "this `.glb` is actually a ZIP" is a Blender launch
+ * that fails several seconds later, with a message about the importer rather than about the
+ * file. This module is the cheap gate in front of that: 512 bytes, no subprocess, decided
+ * before anything is copied into the project.
+ *
+ * THE RULE IS ASYMMETRIC ON PURPOSE
+ * ---------------------------------
+ * It refuses only when the bytes POSITIVELY CONTRADICT the extension — a known signature for
+ * a different format, a NUL byte in a format that must be text, or an empty file. Anything it
+ * cannot tell about is `inconclusive` and passes, because the alternative (a matcher clever
+ * enough to be sure) is also a matcher clever enough to reject somebody's legitimate model.
+ * Three of the six importable types have no magic number at all: `.obj` and ascii `.usd` are
+ * text, and `.gltf` is JSON.
+ *
+ * WHAT IT IS NOT
+ * --------------
+ * Not a security boundary. It cannot tell a real glTF from a crafted one, and it is not meant
+ * to: DECIDING what a file is remains Blender's job, and this only refuses the cases where the
+ * file says out loud that it is something else.
+ *
+ * Owner: DeepBlend Studio — M5
+ */
+
+/** How many bytes of a file this needs. Enough for a text sniff, small enough to be free. */
+export const ASSET_HEAD_BYTES = 512
+
+/**
+ * The signatures worth knowing, in one table.
+ *
+ * `format` is the asset type a signature belongs to, or `null` for a format this product
+ * cannot import — which is the interesting half: a ZIP or a PNG inside a `.glb` is exactly the
+ * case the extension check cannot see.
+ */
+const SIGNATURES = Object.freeze([
+  // Importable types.
+  { format: 'glb', magic: 'glTF', at: 0 },
+  { format: 'blend', magic: 'BLENDER', at: 0 },
+  { format: 'fbx', magic: 'Kaydara FBX Binary', at: 0 },
+  { format: 'usd', magic: 'PXR-USDC', at: 0 },
+  // Everything else that is common enough to name, all of it a contradiction for any of the
+  // six importable types.
+  { format: null, magic: 'PK\u0003\u0004', at: 0, label: 'a ZIP archive' },
+  { format: null, magic: '\u0089PNG\r\n\u001a\n', at: 0, label: 'a PNG image' },
+  { format: null, magic: '\u00ff\u00d8\u00ff', at: 0, label: 'a JPEG image' },
+  { format: null, magic: '%PDF', at: 0, label: 'a PDF' },
+  { format: null, magic: '\u007fELF', at: 0, label: 'an ELF binary' },
+  { format: null, magic: 'MZ', at: 0, label: 'a Windows executable' },
+  { format: null, magic: '\u001f\u008b', at: 0, label: 'a gzip stream' },
+  { format: null, magic: 'RIFF', at: 0, label: 'a RIFF container' },
+  { format: null, magic: 'OggS', at: 0, label: 'an Ogg stream' },
+  { format: null, magic: 'ID3', at: 0, label: 'an MP3' },
+  { format: null, magic: 'ftyp', at: 4, label: 'an ISO base media file (MP4/MOV)' },
+  { format: null, magic: '\u0000asm', at: 0, label: 'a WebAssembly module' },
+])
+
+/** Asset types whose content is text and must therefore contain no NUL byte. */
+const TEXT_TYPES = Object.freeze(['obj', 'gltf', 'usd', 'fbx'])
+
+/** The label a contradiction reports, from the signature it matched. */
+function labelFor(entry) {
+  return entry.label ?? `a ${entry.format} file`
+}
+
+/** Does `head` begin with `magic` at `at`? Bytes, never a decoded string. */
+function startsWith(head, magic, at) {
+  const needle = Buffer.from(magic, 'latin1')
+  if (head.length < at + needle.length) return false
+  return head.subarray(at, at + needle.length).equals(needle)
+}
+
+/** Bytes a text file may legitimately contain besides the printable range. */
+const PRINTABLE_EXCEPTIONS = Object.freeze([0x09, 0x0a, 0x0d])
+
+/**
+ * What the bytes say, independently of the name.
+ *
+ * `signature` is the whole verdict about magic numbers: an entry MATCHED, and whether the
+ * format it belongs to is importable is a separate question — `format: null` in the table
+ * means "a known format this product cannot import". Collapsing those two, "no signature
+ * matched" and "a signature for something else matched", is the bug the first version of this
+ * function had: it made a ZIP named `.glb` read as *unknown* rather than as a ZIP.
+ *
+ * @param {Uint8Array|Buffer} head - the first bytes of the file (`ASSET_HEAD_BYTES` is enough)
+ * @returns {{ signature: {format: string|null, label: string}|null, text: boolean, empty: boolean }}
+ */
+export function describeAssetContent(head) {
+  const bytes = Buffer.isBuffer(head) ? head : Buffer.from(head ?? [])
+  const empty = bytes.length === 0
+  for (const entry of SIGNATURES) {
+    if (startsWith(bytes, entry.magic, entry.at)) {
+      return { signature: { format: entry.format, label: labelFor(entry) }, text: false, empty }
+    }
+  }
+  // Text, for the purposes of this gate, is bytes a text file can contain: the printable
+  // range, UTF-8 continuation bytes, and tab/newline/CR. A NUL fails that, and so does binary
+  // garbage that merely happens to contain no NUL — which is what the second version of this
+  // function learned, because "contains no zero byte" is not the same claim as "is text".
+  const text = !empty && bytes.every(byte => byte >= 0x20 || PRINTABLE_EXCEPTIONS.includes(byte))
+  return { signature: null, text, empty }
+}
+
+/**
+ * Does the content agree with the extension?
+ *
+ * @param {Uint8Array|Buffer} head
+ * @param {string} type - an asset type from `IMPORT_OPERATOR_BY_ASSET_TYPE`
+ * @returns {'agrees'|'contradicts'|'inconclusive'}
+ */
+export function assetContentVerdict(head, type) {
+  const described = describeAssetContent(head)
+
+  if (described.empty) return 'contradicts'
+  if (described.signature !== null) {
+    // A signature for THIS type agrees. A signature for anything else contradicts — including
+    // for another importable type, which is how a `.obj` holding a `.blend` reads, and
+    // including for a format this product cannot import at all, which is how a ZIP named
+    // `.glb` reads.
+    return described.signature.format === type ? 'agrees' : 'contradicts'
+  }
+  // No signature. Text formats are satisfied by text; a binary format is not satisfied by
+  // anything (its magic was required and did not match), but it is not contradicted either,
+  // so it stays inconclusive rather than being refused on a guess.
+  if (TEXT_TYPES.includes(type)) return described.text ? 'agrees' : 'contradicts'
+  return 'inconclusive'
+}

package/lib/bitmap-font.js

@@ -0,0 +1,149 @@
+/**
+ * A 5x7 bitmap font, for labelling contact-sheet cells.
+ *
+ * WHY A FONT IS IN THE CONTRACTS PACKAGE AT ALL
+ * --------------------------------------------
+ * A contact sheet without labels forces the model to guess which cell is which
+ * view. It *could* guess — the cells come back in a documented order — but the one
+ * thing a vision review must not do is mislabel its own evidence: an occlusion
+ * reported against "the top view" that is actually the three-quarter view produces
+ * a confident, well-formed, wrong patch. A label removes the guess.
+ *
+ * The alternative was an image library with real text rendering, which is the
+ * dependency this design exists to avoid (see `png.js`). 5x7 uppercase glyphs are
+ * about forty lines of data and are unambiguous at 2x scale inside a 1600px sheet.
+ *
+ * Each glyph is 7 rows of 5 bits, most significant bit on the left. Every row is
+ * OR'd with `0b1000000`, which both pads to a byte and makes a truncated or
+ * mistyped row visibly wrong rather than a plausible shorter one.
+ *
+ * Owner: DeepBlend Studio — M2
+ */
+
+/** One glyph: 7 rows of 5 bits, each padded to a byte by a set high bit. */
+const GLYPHS = {
+  ' ': [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00],
+  '-': [0x00, 0x00, 0x00, 0x1f, 0x00, 0x00, 0x00],
+  '_': [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x1f],
+  '.': [0x00, 0x00, 0x00, 0x00, 0x00, 0x0c, 0x0c],
+  ',': [0x00, 0x00, 0x00, 0x00, 0x0c, 0x0c, 0x18],
+  ':': [0x00, 0x0c, 0x0c, 0x00, 0x0c, 0x0c, 0x00],
+  '/': [0x01, 0x02, 0x04, 0x08, 0x10, 0x00, 0x00],
+  '#': [0x0a, 0x1f, 0x0a, 0x0a, 0x1f, 0x0a, 0x00],
+  '(': [0x02, 0x04, 0x08, 0x08, 0x08, 0x04, 0x02],
+  ')': [0x08, 0x04, 0x02, 0x02, 0x02, 0x04, 0x08],
+  '+': [0x00, 0x04, 0x04, 0x1f, 0x04, 0x04, 0x00],
+  '=': [0x00, 0x00, 0x1f, 0x00, 0x1f, 0x00, 0x00],
+  '?': [0x0e, 0x11, 0x01, 0x06, 0x04, 0x00, 0x04],
+  '!': [0x04, 0x04, 0x04, 0x04, 0x04, 0x00, 0x04],
+  '0': [0x0e, 0x11, 0x13, 0x15, 0x19, 0x11, 0x0e],
+  '1': [0x04, 0x0c, 0x04, 0x04, 0x04, 0x04, 0x0e],
+  '2': [0x0e, 0x11, 0x01, 0x02, 0x04, 0x08, 0x1f],
+  '3': [0x1f, 0x02, 0x04, 0x02, 0x01, 0x11, 0x0e],
+  '4': [0x02, 0x06, 0x0a, 0x12, 0x1f, 0x02, 0x02],
+  '5': [0x1f, 0x10, 0x1e, 0x01, 0x01, 0x11, 0x0e],
+  '6': [0x06, 0x08, 0x10, 0x1e, 0x11, 0x11, 0x0e],
+  '7': [0x1f, 0x01, 0x02, 0x04, 0x08, 0x08, 0x08],
+  '8': [0x0e, 0x11, 0x11, 0x0e, 0x11, 0x11, 0x0e],
+  '9': [0x0e, 0x11, 0x11, 0x0f, 0x01, 0x02, 0x0c],
+  'A': [0x0e, 0x11, 0x11, 0x1f, 0x11, 0x11, 0x11],
+  'B': [0x1e, 0x11, 0x11, 0x1e, 0x11, 0x11, 0x1e],
+  'C': [0x0e, 0x11, 0x10, 0x10, 0x10, 0x11, 0x0e],
+  'D': [0x1c, 0x12, 0x11, 0x11, 0x11, 0x12, 0x1c],
+  'E': [0x1f, 0x10, 0x10, 0x1e, 0x10, 0x10, 0x1f],
+  'F': [0x1f, 0x10, 0x10, 0x1e, 0x10, 0x10, 0x10],
+  'G': [0x0e, 0x11, 0x10, 0x17, 0x11, 0x11, 0x0f],
+  'H': [0x11, 0x11, 0x11, 0x1f, 0x11, 0x11, 0x11],
+  'I': [0x0e, 0x04, 0x04, 0x04, 0x04, 0x04, 0x0e],
+  'J': [0x07, 0x02, 0x02, 0x02, 0x02, 0x12, 0x0c],
+  'K': [0x11, 0x12, 0x14, 0x18, 0x14, 0x12, 0x11],
+  'L': [0x10, 0x10, 0x10, 0x10, 0x10, 0x10, 0x1f],
+  'M': [0x11, 0x1b, 0x15, 0x15, 0x11, 0x11, 0x11],
+  'N': [0x11, 0x19, 0x15, 0x13, 0x11, 0x11, 0x11],
+  'O': [0x0e, 0x11, 0x11, 0x11, 0x11, 0x11, 0x0e],
+  'P': [0x1e, 0x11, 0x11, 0x1e, 0x10, 0x10, 0x10],
+  'Q': [0x0e, 0x11, 0x11, 0x11, 0x15, 0x12, 0x0d],
+  'R': [0x1e, 0x11, 0x11, 0x1e, 0x14, 0x12, 0x11],
+  'S': [0x0f, 0x10, 0x10, 0x0e, 0x01, 0x01, 0x1e],
+  'T': [0x1f, 0x04, 0x04, 0x04, 0x04, 0x04, 0x04],
+  'U': [0x11, 0x11, 0x11, 0x11, 0x11, 0x11, 0x0e],
+  'V': [0x11, 0x11, 0x11, 0x11, 0x11, 0x0a, 0x04],
+  'W': [0x11, 0x11, 0x11, 0x15, 0x15, 0x1b, 0x11],
+  'X': [0x11, 0x11, 0x0a, 0x04, 0x0a, 0x11, 0x11],
+  'Y': [0x11, 0x11, 0x0a, 0x04, 0x04, 0x04, 0x04],
+  'Z': [0x1f, 0x01, 0x02, 0x04, 0x08, 0x10, 0x1f],
+}
+
+/** Glyph cell size in pixels, before scaling. */
+export const GLYPH_WIDTH = 5
+export const GLYPH_HEIGHT = 7
+/** One blank column between glyphs. */
+const GLYPH_ADVANCE = GLYPH_WIDTH + 1
+
+/** The character drawn for anything the font has no glyph for. */
+const FALLBACK = '?'
+
+/**
+ * Measure the text width at a given scale.
+ *
+ * @param {string} text
+ * @param {number} scale
+ * @returns {number}
+ */
+export function textWidth(text, scale = 1) {
+  if (text.length === 0) return 0
+  return (text.length * GLYPH_ADVANCE - 1) * scale
+}
+
+/**
+ * Draw text with the top-left corner at (x, y). Uppercases its input, because the
+ * font has only one case and silently drawing blanks for lowercase would be worse
+ * than the visible transformation.
+ *
+ * @param {import('./png.js').RgbaImage} image
+ * @param {string} text
+ * @param {number} x
+ * @param {number} y
+ * @param {[number, number, number, number]} color
+ * @param {number} [scale]
+ */
+export function drawText(image, text, x, y, color, scale = 1) {
+  const upper = text.toUpperCase()
+  let cursor = x
+  for (const character of upper) {
+    const glyph = GLYPHS[character] ?? GLYPHS[FALLBACK]
+    for (let row = 0; row < GLYPH_HEIGHT; row += 1) {
+      const bits = glyph[row]
+      for (let column = 0; column < GLYPH_WIDTH; column += 1) {
+        // The set high bit is the padding marker, never a pixel: reading the
+        // glyph's own 5 data bits means a row written with the wrong length
+        // still cannot produce stray pixels to the right of the glyph.
+        const on = (bits >> (GLYPH_WIDTH - 1 - column)) & 1
+        if (on === 0) continue
+        for (let dy = 0; dy < scale; dy += 1) {
+          for (let dx = 0; dx < scale; dx += 1) {
+            setPixel(image, cursor + column * scale + dx, y + row * scale + dy, color)
+          }
+        }
+      }
+    }
+    cursor += GLYPH_ADVANCE * scale
+  }
+}
+
+/**
+ * Write one pixel, ignoring anything outside the image.
+ *
+ * @param {import('./png.js').RgbaImage} image
+ * @param {number} x
+ * @param {number} y
+ * @param {[number, number, number, number]} color
+ */
+function setPixel(image, x, y, color) {
+  if (x < 0 || y < 0 || x >= image.width || y >= image.height) return
+  const offset = (y * image.width + x) * 4
+  image.data[offset] = color[0]
+  image.data[offset + 1] = color[1]
+  image.data[offset + 2] = color[2]
+  image.data[offset + 3] = color[3]
+}

package/lib/canonical.js

@@ -0,0 +1,98 @@
+/**
+ * Canonical JSON serialization and content hashing.
+ *
+ * The word "canonical" here is load-bearing (SPEC §11.1 "返回 Canonical JSON"):
+ *
+ *  - **Key order is significant and fixed** (sorted, recursively), because a
+ *    revision digest, an idempotency record and a test fixture all hash the same
+ *    document. Two structurally identical SceneSpecs that differ only in key
+ *    insertion order MUST hash identically, or the same intent would look like
+ *    two different revisions.
+ *  - **Absent keys are omitted rather than emitted as `null`**, so "not set" has
+ *    exactly one representation. `undefined` is never valid JSON and is dropped.
+ *  - **No whitespace**, so the hash is over bytes and not over formatting.
+ *
+ * Owner: DeepBlend Studio — M1
+ */
+
+import { createHash } from 'node:crypto'
+
+/**
+ * Serialize a JSON value with recursively sorted object keys and no whitespace.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function canonicalStringify(value) {
+  return JSON.stringify(sortValue(value))
+}
+
+/**
+ * Pretty-print a JSON value with recursively sorted keys.
+ *
+ * Used for every document DeepBlend writes to disk. Sorted keys make a revision
+ * diff between two SceneSpecs read as an actual change rather than as noise from
+ * insertion order — which is the whole point of keeping the spec, not the
+ * `.blend`, as the source of truth (SPEC §8.1).
+ *
+ * @param {unknown} value
+ * @param {number} [indent]
+ * @returns {string}
+ */
+export function canonicalPretty(value, indent = 2) {
+  return JSON.stringify(sortValue(value), null, indent)
+}
+
+/**
+ * Recursively rebuild a value with sorted keys, dropping `undefined`.
+ *
+ * @param {unknown} value
+ * @returns {unknown}
+ */
+export function sortValue(value) {
+  if (Array.isArray(value)) return value.map(entry => sortValue(entry))
+  if (value === null || typeof value !== 'object') return value
+  /** @type {Record<string, unknown>} */
+  const output = {}
+  for (const key of Object.keys(value).sort()) {
+    const member = /** @type {Record<string, unknown>} */ (value)[key]
+    if (member === undefined) continue
+    output[key] = sortValue(member)
+  }
+  return output
+}
+
+/**
+ * SHA-256 of the canonical serialization, as lowercase hex.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function sha256Canonical(value) {
+  return createHash('sha256').update(canonicalStringify(value), 'utf8').digest('hex')
+}
+
+/**
+ * SHA-256 of raw bytes or text.
+ *
+ * @param {Buffer|string} data
+ * @returns {string}
+ */
+export function sha256(data) {
+  return createHash('sha256').update(data).digest('hex')
+}
+
+/** Hex prefix length used when hashes appear inside identifiers. */
+const SHORT_HASH_LENGTH = 16
+
+/**
+ * A short, file-name-safe digest used for cache keys and idempotency records.
+ * Long enough that a collision would require a deliberate attack, short enough
+ * to keep an on-disk path readable.
+ *
+ * @param {unknown} value
+ * @returns {string}
+ */
+export function shortDigest(value) {
+  return sha256Canonical(value).slice(0, SHORT_HASH_LENGTH)
+}

package/lib/config-surface.js

@@ -0,0 +1,88 @@
+/**
+ * Which config keys a row actually reads — the check that turns a silent no-op into a startup error.
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * SPEC §17 illustrates the configuration as a NESTED document:
+ *
+ *     { "finalRender": { "requireApprovalAboveFrames": 900 }, "security": { "assetMaxBytes": … } }
+ *
+ * and the implementation reads FLAT keys (`requireApprovalAboveFrames`, `assetMaxBytes`, …), because
+ * each key belongs to the package that enforces it rather than to a group. MEASURED before this
+ * module existed: Schemastery accepts the nested document, keeps `finalRender` as an unknown property,
+ * and reports nothing — so an operator who follows the spec gets a deployment where the approval
+ * threshold is whatever the DEFAULT was, with no error anywhere. The key is not ignored loudly; it is
+ * ignored silently, which is the only failure mode this repository treats as unacceptable in a
+ * configuration.
+ *
+ * WHAT IT DOES NOT DO
+ * -------------------
+ * It does not reject a key for having the wrong TYPE or VALUE — the schema already does that, with a
+ * better message than this could write. It answers one question only: does this row read this name at
+ * all?
+ *
+ * Owner: DeepBlend Studio — M5
+ */
+
+/**
+ * The top-level keys a schema declares.
+ *
+ * Read from `toJSON()` rather than from the builder: the same shape the bundle validator and the
+ * settings card use, so there is one description of a row's surface rather than a second one here.
+ *
+ * @param {{toJSON: () => object}} schema
+ * @returns {string[]}
+ */
+export function declaredConfigKeys(schema) {
+  const json = schema.toJSON()
+  // `dict` sits on the ROOT node, which is `refs[uid]` as soon as the schema has any refs at all — a
+  // schema of scalars with defaults has them, so reading `json.dict` alone found nothing and this check
+  // declared every key unknown. MEASURED against `StudioConfig`: `{uid: 47, refs: {…, 47: {dict: {…}}}}`.
+  const dict = json?.refs?.[json.uid]?.dict ?? json?.dict ?? {}
+  return Object.keys(dict).sort()
+}
+
+/**
+ * A message naming every key this row does not read, or `null` when there are none.
+ *
+ * The known keys are listed in full rather than counted: this runs once, at composition, and the
+ * operator reading it is looking for the name they meant to type.
+ *
+ * @param {{toJSON: () => object}} schema
+ * @param {object} config - the row's config as the loader passed it
+ * @param {string} label - the row id, so the error says which row is wrong
+ * @returns {string|null}
+ */
+export function describeUnknownConfigKeys(schema, config, label) {
+  const known = declaredConfigKeys(schema)
+  const knownSet = new Set(known)
+  const given = config !== null && typeof config === 'object' ? Object.keys(config) : []
+  const unknown = given.filter(key => !knownSet.has(key))
+  if (unknown.length === 0) return null
+  return (
+    `${label} does not read ${unknown.map(key => `"${key}"`).join(', ')}. ` +
+    `It reads: ${known.join(', ')}. ` +
+    'Note that a key with the wrong shape is NOT rejected by the schema — a nested object like SPEC §17\u2019s ' +
+    '`finalRender: {…}` is accepted and simply never read, so this check is what makes that loud. ' +
+    // THE MOST LIKELY CAUSE IS NOT A TYPO, and the message has to say so: an operator layer is GENERATED from
+    // the bundle (`npm run plugin:install`), so a bundle that dropped a key leaves every existing layer
+    // carrying it — and this refusal then fires at the next restart, which is a long way from the edit that
+    // caused it. MEASURED: exactly that happened in this repository when `serveCachedCapabilities` was
+    // deleted, and the only thing that surfaced it was `npm run plugin:check` being run by hand.
+    'If this config came from a generated operator layer, the layer is stale rather than wrong: ' +
+    'run `npm run plugin:install` to regenerate it from the bundle, then restart the profile. ' +
+    'See `deepblend/docs/install.md` for the SPEC §17 name \u2192 real name table.'
+  )
+}
+
+/**
+ * Throw when a row's config carries a key the row does not read.
+ *
+ * @param {{toJSON: () => object}} schema
+ * @param {object} config
+ * @param {string} label
+ */
+export function assertKnownConfigKeys(schema, config, label) {
+  const problem = describeUnknownConfigKeys(schema, config, label)
+  if (problem !== null) throw new Error(problem)
+}