@deepblend/dsh-blender-contracts 0.1.0

package/lib/index.js

@@ -0,0 +1,829 @@
+/**
+ * @deepblend/dsh-blender-contracts
+ *
+ * Service Definition and shared types for DeepBlend Studio (SPEC §5.1).
+ *
+ * This package is the frozen vocabulary shared by every other DeepBlend package:
+ * the `BlenderRuntime` Service interface, the `BlenderStudio` facade interface,
+ * the Blender bootstrap protocol envelope, stable error codes, and the
+ * deepblend-specific artifact boundaries.
+ *
+ * It publishes NO service and registers NO tool — it is pure data, so it is safe
+ * to consume from a Host composition, an Agent preset, or a Web Client half.
+ *
+ * Owner: DeepBlend Studio — M0
+ */
+
+/** Blender bootstrap protocol version. Bumped only on a breaking wire change. */
+export const BLENDER_PROTOCOL_VERSION = 'deepblend.blender/v1'
+
+/** SceneSpec schema version. Defined in M1; declared here so M0 can reference it. */
+export const SCENE_SCHEMA_VERSION = 'deepblend.scene/v1'
+
+/** ScenePatch document version. */
+export const SCENE_PATCH_VERSION = 'deepblend.scene-patch/v1'
+
+/** Revision manifest version written beside every revision directory. */
+export const REVISION_MANIFEST_VERSION = 'deepblend.revision-manifest/v1'
+
+/**
+ * The job document a revision TRANSACTION writes (SPEC §9.3 result.json). NOT the durable render-job
+ * record, which is `RENDER_JOB_VERSION` — this comment said §10.2 for years while six call sites wrote
+ * this string by hand, which is how the two were mistaken for each other.
+ */
+export const JOB_RECORD_VERSION = 'deepblend.job/v1'
+
+/** Project record version. */
+export const PROJECT_RECORD_VERSION = 'deepblend.project/v1'
+
+/** Settings namespace owned by the DeepBlend host service. */
+export const BLENDER_SETTINGS_NAMESPACE = 'deepblend'
+
+/** Canonical telemetry/log scope marker used in warnings and logs. */
+export const LOG_SCOPE = 'deepblend'
+
+/**
+ * Stable error codes (SPEC §11.1: "每个错误有稳定 errorCode").
+ *
+ * These are part of the wire contract with the model and the UI. Never renumber
+ * or rename one; add a new code instead.
+ */
+export const BlenderErrorCode = Object.freeze({
+  /** No Blender executable could be resolved from config or PATH. */
+  NOT_FOUND: 'BLENDER_NOT_FOUND',
+  /** A configured executable path exists but is not executable / is a directory. */
+  EXECUTABLE_NOT_EXECUTABLE: 'BLENDER_EXECUTABLE_NOT_EXECUTABLE',
+  /** A configured executable path escapes the allowlist (SPEC §15.2). */
+  EXECUTABLE_OUTSIDE_ALLOWLIST: 'BLENDER_EXECUTABLE_OUTSIDE_ALLOWLIST',
+  /** ctx.subprocess.spawn threw before a handle existed. */
+  SPAWN_FAILED: 'BLENDER_SPAWN_FAILED',
+  /** Blender exited with a non-zero code. */
+  NONZERO_EXIT: 'BLENDER_NONZERO_EXIT',
+  /** The probe exceeded its configured deadline. */
+  TIMEOUT: 'BLENDER_TIMEOUT',
+  /** The caller's AbortSignal fired. */
+  ABORTED: 'BLENDER_ABORTED',
+  /** bootstrap.py never wrote its result file. */
+  RESULT_MISSING: 'BLENDER_RESULT_MISSING',
+  /** The result file was not valid JSON. */
+  RESULT_UNPARSEABLE: 'BLENDER_RESULT_UNPARSEABLE',
+  /** bootstrap.py wrote a well-formed error envelope. */
+  SCRIPT_ERROR: 'BLENDER_SCRIPT_ERROR',
+  /** bootstrap.py reported a different protocolVersion. */
+  PROTOCOL_VERSION_MISMATCH: 'BLENDER_PROTOCOL_VERSION_MISMATCH',
+  /** bootstrap.py reported an action it does not implement. */
+  UNSUPPORTED_ACTION: 'BLENDER_UNSUPPORTED_ACTION',
+  /** The collection of capabilities threw unexpectedly inside Blender. */
+  CAPABILITY_PROBE_FAILED: 'BLENDER_CAPABILITY_PROBE_FAILED',
+  /** The configured bootstrap script is missing or unreadable. */
+  BOOTSTRAP_MISSING: 'BLENDER_BOOTSTRAP_MISSING',
+  /** A requested render engine is not available in this runtime (D1/D2). */
+  ENGINE_UNAVAILABLE: 'BLENDER_ENGINE_UNAVAILABLE',
+  /** Reserved: no Blender implementation was injected at all. */
+  RUNTIME_UNAVAILABLE: 'BLENDER_RUNTIME_UNAVAILABLE',
+
+  // ---- M1: project, revision and SceneSpec failures ------------------------
+  //
+  // These are grouped and named so the model can tell apart the three things a
+  // failed write can mean: the input was wrong, the caller's view was stale, or
+  // the machine failed. Only the middle one is worth retrying by re-reading.
+
+  /** The project id does not exist in the project store. */
+  PROJECT_NOT_FOUND: 'PROJECT_NOT_FOUND',
+  /** A project directory exists but its record is missing or unreadable. */
+  PROJECT_CORRUPT: 'PROJECT_CORRUPT',
+  /** A project with this id already exists. */
+  PROJECT_EXISTS: 'PROJECT_EXISTS',
+  /** A project id (or a derived slug) is not usable as a directory name. */
+  PROJECT_ID_INVALID: 'PROJECT_ID_INVALID',
+
+  /** The named revision does not exist in this project. */
+  REVISION_NOT_FOUND: 'REVISION_NOT_FOUND',
+  /** The SceneSpec stored in a revision is missing or no longer parses. */
+  REVISION_CORRUPT: 'REVISION_CORRUPT',
+  /** A checkpoint was required by the requested action but this revision has none. */
+  REVISION_CHECKPOINT_MISSING: 'REVISION_CHECKPOINT_MISSING',
+
+  /**
+   * `baseRevision` is not the current revision. The caller read a stale view;
+   * the write is refused rather than merged, because an implicit merge is how a
+   * concurrent editor silently loses someone else's work (SPEC §8.5).
+   */
+  REVISION_CONFLICT: 'REVISION_CONFLICT',
+  /** No revision could be allocated (clock/sequence guard). */
+  REVISION_ALLOCATION_FAILED: 'REVISION_ALLOCATION_FAILED',
+  /** The requested revision id does not match the `r0001` grammar. */
+  REVISION_ID_INVALID: 'REVISION_ID_INVALID',
+
+  /** The SceneSpec failed structural or semantic validation. */
+  SCENE_SPEC_INVALID: 'SCENE_SPEC_INVALID',
+  /** The ScenePatch failed structural validation. */
+  SCENE_PATCH_INVALID: 'SCENE_PATCH_INVALID',
+  /** The ScenePatch was structurally fine but referenced something absent. */
+  SCENE_PATCH_REJECTED: 'SCENE_PATCH_REJECTED',
+  /** The compiled scene failed technical validation in Blender. */
+  SCENE_VALIDATION_FAILED: 'SCENE_VALIDATION_FAILED',
+  /** No camera could be selected for the requested preview. */
+  SCENE_CAMERA_MISSING: 'SCENE_CAMERA_MISSING',
+
+  /** A generated id, path or key would escape the workspace or project root. */
+  PATH_OUTSIDE_WORKSPACE: 'PATH_OUTSIDE_WORKSPACE',
+  /** A file name or id segment contained a separator or traversal. */
+  PATH_SEGMENT_INVALID: 'PATH_SEGMENT_INVALID',
+
+  /** A referenced asset file is not present in the project. */
+  ASSET_MISSING: 'ASSET_MISSING',
+  /** This Blender build cannot import the asset's format (D10). */
+  ASSET_FORMAT_UNAVAILABLE: 'ASSET_FORMAT_UNAVAILABLE',
+  /** The asset hash does not match the recorded sha256. */
+  ASSET_HASH_MISMATCH: 'ASSET_HASH_MISMATCH',
+
+  // ---- M5: the producer side of an asset (SPEC §11 blender_asset_ingest) -----
+  //
+  // The four above describe a DECLARED asset the consumer cannot use; these describe
+  // a source the producer was asked to bring in. They are separate on purpose: "the
+  // file you pointed me at is not there" and "the file this scene declares is not
+  // there" are different problems with different fixes.
+  /** The ingest request itself is malformed — both sources given, or neither. */
+  ASSET_REQUEST_INVALID: 'ASSET_REQUEST_INVALID',
+  /** The local source path does not name an existing file. */
+  ASSET_SOURCE_NOT_FOUND: 'ASSET_SOURCE_NOT_FOUND',
+  /** The source is larger than `assetMaxBytes` (SPEC §15). */
+  ASSET_TOO_LARGE: 'ASSET_TOO_LARGE',
+  /** A remote source could not be fetched, or exceeded the byte cap mid-download. */
+  ASSET_FETCH_FAILED: 'ASSET_FETCH_FAILED',
+  /**
+   * The bytes do not match the extension (SPEC §15.2 "MIME 与扩展名双重校验").
+   *
+   * Refused only when the content POSITIVELY CONTRADICTS the name — a known signature for
+   * another format, a NUL in a format that must be text, or an empty file. A file whose
+   * shape this gate cannot read passes, because deciding what a model file really is stays
+   * Blender's job (D10) and this only refuses the ones that say out loud that they are
+   * something else. See `contracts/lib/asset-content.js`.
+   */
+  ASSET_CONTENT_MISMATCH: 'ASSET_CONTENT_MISMATCH',
+  /**
+   * The volume holding the project ran out of room.
+   *
+   * Its own code rather than `SCRIPT_ERROR`, because it is an operational event and not a bug:
+   * the frames already written are kept, the renderer is stopped, and the job resumes once there
+   * is space. MEASURED with `tools/disk-full-probe.mjs` on a 24 MiB volume — before this code
+   * existed, the full disk killed the HOST process instead (milestone-status.md §35).
+   */
+  DISK_FULL: 'DISK_FULL',
+  /**
+   * The compiled scene carries more polygons than `maxMeshPolygons` (SPEC §15.2
+   * "Mesh 面数限制").
+   *
+   * A separate code from the timeout, because they are different facts with different
+   * fixes: a timeout says "this took too long — try again, or raise the deadline", while
+   * this says "this scene is this heavy, and it will be this heavy every time". The count
+   * comes from the compile report the provider already produces for the revision manifest,
+   * so the refusal names the number instead of guessing at it.
+   */
+  SCENE_TOO_HEAVY: 'SCENE_TOO_HEAVY',
+  /**
+   * A REMOTE ingest needs a grant first (SPEC §11 "本地自动，网络需审批").
+   *
+   * Enforced in the host for the same reason the render threshold is: every caller
+   * passes through the host, and only the tool plane can ask. A local path needs no
+   * approval — it is already inside the machine the operator controls.
+   */
+  ASSET_APPROVAL_REQUIRED: 'ASSET_APPROVAL_REQUIRED',
+
+  /** The requested render profile is not defined in the SceneSpec. */
+  RENDER_PROFILE_MISSING: 'RENDER_PROFILE_MISSING',
+  /** A render was refused because its estimated cost exceeds the configured budget. */
+  RENDER_BUDGET_EXCEEDED: 'RENDER_BUDGET_EXCEEDED',
+  /** Blender rendered but produced no image file. */
+  RENDER_NO_OUTPUT: 'RENDER_NO_OUTPUT',
+
+  // ---- M3: persistent render jobs, resumption, delivery -------------------
+
+  /** No durable render job exists under that id in this project. */
+  RENDER_JOB_NOT_FOUND: 'RENDER_JOB_NOT_FOUND',
+  /** A render job already owns this project's delivery slot. */
+  RENDER_JOB_CONFLICT: 'RENDER_JOB_CONFLICT',
+  /** The render job is not in a state from which this operation is legal. */
+  RENDER_JOB_STATE_INVALID: 'RENDER_JOB_STATE_INVALID',
+  /** The requested frame range is empty, inverted, or outside the project's own. */
+  RENDER_RANGE_INVALID: 'RENDER_RANGE_INVALID',
+  /** A frame sequence finished without every frame of its range. */
+  RENDER_FRAMES_INCOMPLETE: 'RENDER_FRAMES_INCOMPLETE',
+  /** The encoder executable could not be resolved. */
+  ENCODER_NOT_FOUND: 'ENCODER_NOT_FOUND',
+  /** ffmpeg ran and failed. */
+  ENCODE_FAILED: 'ENCODE_FAILED',
+  /** The encoded file does not have the properties the manifest claims. */
+  ENCODE_VERIFY_FAILED: 'ENCODE_VERIFY_FAILED',
+  /** ffprobe could not be resolved or could not read the file. */
+  PROBE_FAILED: 'PROBE_FAILED',
+  /** A delivery was requested for a job that has not produced every frame. */
+  DELIVERY_INCOMPLETE: 'DELIVERY_INCOMPLETE',
+  /**
+   * A job is already being encoded, so this delivery would put two encoders on one file.
+   *
+   * `encodedPath` is one path per job, and an encode is not instantaneous — two deliveries of the same job write
+   * the same MP4, and each then verifies a file the other is still writing. MEASURED before this code existed:
+   * both callers failed with `ENCODE_VERIFY_FAILED`, a message that blames the video's properties rather than the
+   * collision. The refusal names the call that is already running, and the caller loses nothing: the encode it
+   * was about to duplicate is happening anyway.
+   */
+  EXPORT_IN_PROGRESS: 'EXPORT_IN_PROGRESS',
+
+  /**
+   * A delivery render is large enough that the operator must approve it first
+   * (SPEC §15.1 "高成本最终渲染达阈值审批").
+   *
+   * Reported as a branchable refusal rather than started-and-warned, because the
+   * whole point of a threshold is to PREVENT the cost, not to describe it
+   * afterwards. The caller asks the approval service and re-issues with
+   * `approved: true`; the detail carries `{frames, threshold}` so the request can
+   * state the actual size.
+   */
+  RENDER_APPROVAL_REQUIRED: 'RENDER_APPROVAL_REQUIRED',
+
+  // ---- M4 ----------------------------------------------------------------
+
+  /** A path the browser asked for belongs to no DeepBlend route. */
+  UI_ROUTE_NOT_FOUND: 'UI_ROUTE_NOT_FOUND',
+  /**
+   * An artifact the UI asked to display does not exist.
+   *
+   * Separate from `REVISION_CORRUPT` on purpose: a preview that was never
+   * rendered is a normal state the panel renders as "nothing to show yet", while
+   * a revision whose files are inconsistent is a real fault. One code for both
+   * would make the UI unable to tell them apart.
+   */
+  ARTIFACT_NOT_FOUND: 'ARTIFACT_NOT_FOUND',
+  /** A UI request failed inside the Host for a reason with no more specific code. */
+  UI_REQUEST_FAILED: 'UI_REQUEST_FAILED',
+  /**
+   * The running Host service is older than the UI half asking for it.
+   *
+   * The same half-upgraded deployment M3 taught the tools to name (D59): the
+   * packages on disk are newer than the `blenderStudio` the process constructed.
+   * The panel must say so, because the alternative is a blank panel over a
+   * `TypeError` that names neither the cause nor the fix.
+   */
+  UI_HOST_API_STALE: 'UI_HOST_API_STALE',
+})
+
+/** Warning codes surface on the successful path, where nothing threw. */
+export const BlenderWarningCode = Object.freeze({
+  /** Detection is unavailable; the caller is looking at a degraded result (D1). */
+  BLENDER_NOT_INSTALLED: 'BLENDER_NOT_INSTALLED',
+  /** A preferred engine IS reachable but is silently absent from the static enum (D1). */
+  ENGINE_NOT_IN_STATIC_ENUM: 'ENGINE_NOT_IN_STATIC_ENUM',
+  /** A configured/likely-required engine is genuinely unavailable (D2). */
+  ENGINE_UNAVAILABLE: 'ENGINE_UNAVAILABLE',
+  /** A render profile was downgraded to a reachable engine (D2). */
+  ENGINE_DOWNGRADED: 'ENGINE_DOWNGRADED',
+  /** CPU-only: no GPU device was detected. */
+  GPU_UNAVAILABLE: 'GPU_UNAVAILABLE',
+  /** A format the product wants is not provided by this Blender build (SPEC §2.2 gap). */
+  FORMAT_UNAVAILABLE: 'FORMAT_UNAVAILABLE',
+  /** An add-on could not be enabled. */
+  ADDON_ENABLE_FAILED: 'ADDON_ENABLE_FAILED',
+  /** A warning passed through verbatim from bootstrap.py. */
+  PROBE_WARNING: 'PROBE_WARNING',
+  /** Result derived from a stale cache entry. */
+  STALE_CAPABILITIES: 'STALE_CAPABILITIES',
+
+  // ---- M1 ----------------------------------------------------------------
+
+  /** A write succeeded but changed nothing (the same intent was already applied). */
+  SCENE_PATCH_NO_CHANGE: 'SCENE_PATCH_NO_CHANGE',
+  /** A render profile was downgraded to a reachable engine. */
+  RENDER_ENGINE_DOWNGRADED: 'RENDER_ENGINE_DOWNGRADED',
+  /** Preview rendered at a lower sample count than the profile asked for. */
+  RENDER_SAMPLES_REDUCED: 'RENDER_SAMPLES_REDUCED',
+  /** The compiler made a decision the author did not spell out (see notices). */
+  SCENE_COMPILER_DECISION: 'SCENE_COMPILER_DECISION',
+  /** A referenced asset is declared but its file has not been ingested yet. */
+  SCENE_ASSET_NOT_INGESTED: 'SCENE_ASSET_NOT_INGESTED',
+  /** An animation track targets a property whose keyframes were clamped or dropped. */
+  SCENE_ANIMATION_KEYFRAMES_ADJUSTED: 'SCENE_ANIMATION_KEYFRAMES_ADJUSTED',
+
+  // ---- M3 ----------------------------------------------------------------
+
+  /**
+   * A render could not be registered as a DSH background job, so it will not
+   * appear in the harness job list. The render itself is unaffected and its
+   * durable record is still authoritative — but the caller must be able to see
+   * why the job it asked for is not where it expected it.
+   */
+  JOB_PROJECTION_UNAVAILABLE: 'JOB_PROJECTION_UNAVAILABLE',
+  /** A delivery had to be verified against a claim the runtime could not re-derive. */
+  DELIVERY_CLAIM_UNAVAILABLE: 'DELIVERY_CLAIM_UNAVAILABLE',
+  /**
+   * An attempt at this job was cut off mid-line in its event journal, so the LAST event the renderer
+   * sent never arrived.
+   *
+   * It is not an error and not a reason to distrust any number in the record: progress and the resumed
+   * frame set are read from the frame FILES, byte by byte (`frame-ledger.js`), and the journal was
+   * never the authority for either. What it means is that the journal is not a complete account of
+   * what the renderer did — which is the whole reason the ledger does not count from it.
+   *
+   * Recorded on the job because the alternative is silence: the same fact used to be only a line in
+   * the harness job output, which is drained by whoever reads it first and is gone after a restart.
+   */
+  JOURNAL_INCOMPLETE: 'JOURNAL_INCOMPLETE',
+})
+
+/**
+ * The host API version the packages in this build implement.
+ *
+ * WHY A NUMBER AND NOT A METHOD PROBE
+ * -----------------------------------
+ * A tool plane newer than the host plane is a REAL deployment state, not a
+ * hypothetical: a Cordis service keeps the code it was constructed from, and Node's
+ * ESM module cache is process-level, so replacing the packages on disk does not
+ * replace the running `blenderStudio`. MEASURED while M3 was written — the `dsh web`
+ * process then running had started five hours before the M3 commit.
+ *
+ * Probing for methods catches that state for `resumeRenderJob`, `listJobs` and
+ * `reconcileRenderJobs` (they are simply absent), and MISSES it for
+ * `startFinalRender` and `exportProject`, because M1 implemented those as stubs and
+ * so `typeof` is `'function'` on both the old and the new host. The failure mode of
+ * the probe is therefore the worst kind: it guards four entry points and silently
+ * lets the other two through. A number answers the question the probe was trying to
+ * answer.
+ *
+ * Bump this when the tool plane starts depending on a host method that did not exist
+ * before. 3 is M3 (the persistent render job). 4 is M4, which added the UI plane's
+ * read/aggregate methods — the browser half faces the same half-upgraded deployment
+ * the tools do, and it has to say so instead of painting a blank panel over a
+ * `TypeError` (D59).
+ */
+export const HOST_API_VERSION = 4
+
+/** Formats the product intends to support (SPEC §2.2). Used to emit warnings. */
+export const EXPECTED_IMPORT_FORMATS = Object.freeze(['gltf', 'fbx', 'obj', 'usd'])
+/** Formats the product intends to be able to export. */
+export const EXPECTED_EXPORT_FORMATS = Object.freeze(['gltf', 'fbx', 'usd'])
+
+/** Candidate render engines probed behaviorally. Never assume one exists (D1). */
+export const CANDIDATE_RENDER_ENGINES = Object.freeze([
+  'BLENDER_EEVEE',
+  'CYCLES',
+  'BLENDER_WORKBENCH',
+])
+
+/**
+ * A typed, serializable DeepBlend failure.
+ *
+ * Carries a stable `code` from {@link BlenderErrorCode} so the model, the UI and
+ * the audit log can branch on it without parsing prose.
+ */
+export class BlenderError extends Error {
+  /**
+   * @param {string} code - a {@link BlenderErrorCode} value.
+   * @param {string} message - human-readable, safe to show to the model.
+   * @param {{ detail?: unknown, cause?: unknown }} [options]
+   */
+  constructor(code, message, options = {}) {
+    super(message, options.cause !== undefined ? { cause: options.cause } : undefined)
+    this.name = 'BlenderError'
+    this.code = code
+    if (options.detail !== undefined) this.detail = options.detail
+  }
+
+  /** Canonical JSON form for tool results and API responses. */
+  toJSON() {
+    return {
+      code: this.code,
+      message: this.message,
+      ...this.detail !== undefined ? { detail: this.detail } : {},
+    }
+  }
+}
+
+/** Narrowing helper for callers that receive unknown thrown values. */
+export function isBlenderError(value) {
+  return value instanceof BlenderError
+}
+
+/**
+ * Build a warning entry. Warnings never throw; they degrade a successful result.
+ * @param {string} code - a {@link BlenderWarningCode} value.
+ * @param {string} message - human-readable explanation.
+ * @param {Record<string, unknown>} [detail]
+ */
+export function warning(code, message, detail) {
+  return { code, message, ...detail !== undefined ? { detail } : {} }
+}
+
+/**
+ * @typedef {object} BlenderExecutableReport
+ * @property {string} requested - exactly what the operator configured.
+ * @property {string|null} resolved - canonical absolute path actually used, or null.
+ * @property {boolean} found - whether a usable executable was resolved.
+ * @property {string|null} [advice] - what to do about it when `found` is false: the sentence the
+ *   settings card and the capability text both show, composed once in the provider so the two cannot
+ *   disagree. Null when there is nothing to advise.
+ */
+
+/**
+ * @typedef {object} BlenderEngineProbe
+ * @property {boolean} assignable - whether assigning the identifier actually took effect.
+ * @property {string|null} readback - what `scene.render.engine` read back as.
+ * @property {string|null} error - exception text when the probe threw.
+ */
+
+/**
+ * One GPU compute backend's support status.
+ *
+ * An unsupported backend *raises* on assignment rather than returning an empty
+ * device list (`TypeError: enum "OPTIX" not found in ('NONE', 'METAL')`), so
+ * `supported: false` is a normal, expected outcome — never a probe failure.
+ *
+ * @typedef {object} BlenderGpuBackend
+ * @property {boolean} supported
+ * @property {string[]} gpuDevices
+ * @property {string[]} cpuDevices
+ * @property {string|null} error
+ */
+
+/**
+ * The GPU report produced by `bootstrap.py`, normalised by the provider.
+ *
+ * @typedef {object} BlenderGpuReport
+ * @property {string[]} availableBackends - backends that reported at least one GPU device.
+ * @property {string|null} preferredBackend
+ * @property {string[]} gpuDeviceNames - flattened GPU device names across available backends.
+ * @property {string[]} cpuDeviceNames
+ * @property {Record<string, BlenderGpuBackend>} backendSupport
+ */
+
+/**
+ * @typedef {object} BlenderRenderSmokeTest
+ * @property {boolean} attempted
+ * @property {string|null} engine
+ * @property {boolean} ok
+ * @property {number} bytes
+ * @property {string|null} error
+ */
+
+/**
+ * The behavioral capability report produced by `bootstrap.py` (D1).
+ *
+ * `renderEngines` is deliberately a *behavioral* probe result rather than the
+ * static `engine` enum: on Blender 5.2.1 the enum reports only `BLENDER_EEVEE`
+ * even though assigning `CYCLES` succeeds. `renderEngineEnumItems` is retained
+ * as an informational diagnostic and must never be used to gate availability.
+ *
+ * @typedef {object} BlenderCapabilities
+ * @property {string} protocolVersion
+ * @property {boolean} installed
+ * @property {BlenderExecutableReport} executable
+ * @property {string|null} blenderVersion
+ * @property {number[]|null} blenderVersionTuple
+ * @property {string|null} pythonVersion
+ * @property {string|null} buildHash
+ * @property {string|null} binaryPath
+ * @property {Record<string, BlenderEngineProbe>} renderEngines
+ * @property {string|null} bestAvailableEngine - preferred engine per the probe's own ordering.
+ * @property {string[]} renderEngineEnumItems - diagnostic only (D1).
+ * @property {BlenderGpuReport} gpu
+ * @property {boolean} gpuAvailable
+ * @property {string[]} exportFormats
+ * @property {string[]} importFormats
+ * @property {string[]} unavailableFormats - attribute-present but unregistered operators.
+ * @property {BlenderRenderSmokeTest|null} renderSmokeTest
+ * @property {BlenderRenderSmokeTest|null} cyclesSmokeTest
+ * @property {boolean} textBlockApi
+ * @property {boolean} frameApi
+ * @property {string|null} hostPlatform
+ * @property {{ code: string, message: string, detail?: unknown }[]} warnings
+ * @property {number} probedAt - epoch ms.
+ * @property {number} durationMs
+ * @property {string|null} commandLine - for audit; never contains secrets.
+ */
+
+/**
+ * The Blender execution seam (SPEC §7.1).
+ *
+ * Implementations own process launch, protocol framing and result validation.
+ * They hold NO business state machine — orchestration belongs to
+ * `BlenderOrchestrator` and persistence to the project/revision stores.
+ *
+ * M0 implements `getCapabilities` and the shared `runBootstrap` transport.
+ * The remaining methods are declared here as the frozen target shape and are
+ * implemented in M1+. Calling an unimplemented one throws
+ * `BlenderErrorCode.UNSUPPORTED_ACTION`, never silently succeeds.
+ *
+ * @typedef {object} BlenderRuntime
+ * @property {(signal?: AbortSignal) => Promise<BlenderCapabilities>} getCapabilities
+ * @property {(request: BlenderBootstrapRequest, options?: { signal?: AbortSignal }) => Promise<BlenderBootstrapEnvelope>} runBootstrap
+ * @property {() => void} dispose
+ */
+
+/**
+ * @typedef {object} BlenderBootstrapRequest
+ * @property {string} action - bootstrap action name, e.g. `get_capabilities`.
+ * @property {Record<string, unknown>} [payload] - action-specific fields.
+ * @property {string} [jobId] - correlation id for logs and the result envelope.
+ */
+
+/**
+ * The envelope `bootstrap.py` writes to its result file.
+ *
+ * @typedef {object} BlenderBootstrapEnvelope
+ * @property {'success'|'error'} status
+ * @property {string} protocolVersion
+ * @property {string|null} jobId
+ * @property {BlenderCapabilities|null} capabilities
+ * @property {{ code: string, message: string }|null} error
+ * @property {string[]} warnings
+ */
+
+/**
+ * The model- and UI-facing business facade (SPEC §7.2).
+ *
+ * M0 implements `getCapabilities` only. Everything else is the frozen M1+ target
+ * and throws `UNSUPPORTED_ACTION` until implemented, so the model can never
+ * believe a not-yet-built capability worked.
+ *
+ * @typedef {object} BlenderStudio
+ * @property {(request?: { refresh?: boolean }) => Promise<BlenderCapabilities>} getCapabilities
+ */
+
+/**
+ * Project a raw capabilities object into the canonical, stable-order JSON that
+ * the tool returns and the UI renders.
+ *
+ * Key order is fixed so transcripts diff cleanly and tests can compare output
+ * (SPEC §19.5 golden scenes rely on deterministic serialization).
+ *
+ * @param {BlenderCapabilities} capabilities
+ * @returns {Record<string, unknown>}
+ */
+export function toCanonicalCapabilities(capabilities) {
+  return {
+    protocolVersion: capabilities.protocolVersion,
+    installed: capabilities.installed,
+    executable: {
+      requested: capabilities.executable.requested,
+      resolved: capabilities.executable.resolved,
+      found: capabilities.executable.found,
+      // What to DO when it was not found — composed once by the provider, read by the settings card
+      // (a human) and by the capability text (a model). A canonical projection is where a field is
+      // DECLARED, which is exactly why the first version of this change worked in the provider and
+      // vanished here: the value existed and the contract had no room for it.
+      //
+      // ABSENT rather than null when there is nothing to advise: a healthy install has no "what to do
+      // about it", and the fixture round-trip in `contract/contracts.test.mjs` pins the canonical shape
+      // exactly — a null field would change the shape of every healthy payload to carry a non-fact.
+      ...(typeof capabilities.executable.advice === 'string' && capabilities.executable.advice.length > 0
+        ? { advice: capabilities.executable.advice }
+        : {}),
+    },
+    version: capabilities.blenderVersion,
+    versionTuple: capabilities.blenderVersionTuple,
+    pythonVersion: capabilities.pythonVersion,
+    buildHash: capabilities.buildHash,
+    binaryPath: capabilities.binaryPath,
+    // Behavioral availability — the only field a caller may branch on (D1).
+    engines: Object.fromEntries(
+      Object.entries(capabilities.renderEngines).map(([id, probe]) => [
+        id,
+        { available: probe.assignable, readback: probe.readback, error: probe.error },
+      ]),
+    ),
+    bestAvailableEngine: capabilities.bestAvailableEngine,
+    // Diagnostic only. Present so operators can see the enum lie for themselves.
+    engineEnumItems: capabilities.renderEngineEnumItems,
+    gpu: {
+      available: capabilities.gpuAvailable,
+      backends: capabilities.gpu.availableBackends,
+      preferredBackend: capabilities.gpu.preferredBackend,
+      devices: capabilities.gpu.gpuDeviceNames,
+      cpuDevices: capabilities.gpu.cpuDeviceNames,
+      backendSupport: capabilities.gpu.backendSupport,
+    },
+    formats: {
+      import: capabilities.importFormats,
+      export: capabilities.exportFormats,
+      // Attribute-present but unregistered operators: the trap that makes
+      // `hasattr(bpy.ops.export_scene, 'obj')` an unsafe availability test.
+      unavailable: capabilities.unavailableFormats,
+    },
+    renderSmokeTest: capabilities.renderSmokeTest,
+    cyclesSmokeTest: capabilities.cyclesSmokeTest,
+    api: {
+      textBlocks: capabilities.textBlockApi,
+      frameRange: capabilities.frameApi,
+    },
+    hostPlatform: capabilities.hostPlatform,
+    warnings: capabilities.warnings,
+    probedAt: capabilities.probedAt,
+    durationMs: capabilities.durationMs,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// M1 surface
+//
+// The M0 section above is frozen. Everything this milestone added lives in its
+// own module and is re-exported here, so every consumer keeps importing exactly
+// one package name (SPEC §5.1: contracts is the shared vocabulary) and the
+// dependency graph stays acyclic.
+// ---------------------------------------------------------------------------
+
+export {
+  canonicalStringify,
+  canonicalPretty,
+  sortValue,
+  sha256,
+  sha256Canonical,
+  shortDigest,
+} from './canonical.js'
+
+export {
+  SchemaDefinitionError,
+  compileSchema,
+  formatIssues,
+} from './json-schema.js'
+
+export {
+  DEFAULT_WORLD,
+  ANIMATION_PROPERTIES_BY_KIND,
+  TRANSFORM_ANIMATION_PROPERTIES,
+  MATERIAL_ANIMATION_PROPERTIES,
+  collectionForKind,
+  collectionNameForKind,
+  SCENE_ENGINES,
+  BLENDER_ENGINE_BY_KEY,
+  IMPORT_OPERATOR_BY_ASSET_TYPE,
+  validateSceneSpec,
+  compileSceneSpec,
+  entityBoundingRadius,
+  sceneProjection,
+  sceneSpecDigest,
+  specHash,
+  summarizeSceneSpec,
+  sceneSpecCanonicalText,
+} from './scene-spec.js'
+
+export { ASSET_HEAD_BYTES, assetContentVerdict, describeAssetContent } from './asset-content.js'
+export { redactUrl } from './redact.js'
+export { assertKnownConfigKeys, declaredConfigKeys, describeUnknownConfigKeys } from './config-surface.js'
+
+export {
+  CAMERA_UPDATE_FIELDS,
+  SCENE_OPERATION_NAMES,
+  validateScenePatch,
+  applyPatchToSpec,
+  buildOperationManifest,
+} from './scene-patch.js'
+
+export {
+  toCanonicalProjectSummary,
+  toCanonicalRevisionSummary,
+  toCanonicalPreviewArtifact,
+  toCanonicalQAReport,
+  toCanonicalJobRecord,
+  toCanonicalFailure,
+} from './projections.js'
+
+// ---------------------------------------------------------------------------
+// M2 surface
+//
+// The visual loop's vocabulary: how a render is measured into a score, what a
+// finding is, and how repeated findings are detected. Kept in its own module for
+// the same reason as the M1 block above.
+// ---------------------------------------------------------------------------
+
+export {
+  VISUAL_REVIEW_VERSION,
+  VISUAL_ISSUE_CATEGORIES,
+  VISUAL_SEVERITIES,
+  VISUAL_PASS_SCORE,
+  SUBJECT_PART_TAG,
+  isSubjectPart,
+  LUMINANCE_BUCKETS,
+  COVERAGE_BUCKETS,
+  CENTERING_BUCKETS,
+  quantise,
+  issueFingerprint,
+  scoreView,
+  scoreReview,
+  validateFindings,
+  seedFingerprintCounters,
+  shouldHandOver,
+  updateFingerprintCounters,
+} from './visual-issue.js'
+
+export {
+  decodePng,
+  encodePng,
+  createImage,
+  fillRect,
+  blendInto,
+} from './png.js'
+
+export {
+  GLYPH_WIDTH,
+  GLYPH_HEIGHT,
+  textWidth,
+  drawText,
+} from './bitmap-font.js'
+
+export {
+  CAPTION_BAND_COLOR,
+  composeContactSheet,
+  viewCaption,
+} from './contact-sheet.js'
+
+export {
+  runVisualLoop,
+} from './visual-loop.js'
+
+// ---------------------------------------------------------------------------
+// M3 surface
+//
+// The persistent render job: the durable record's vocabulary, the frame ledger
+// that decides what still has to be rendered, and the delivery manifest's own
+// completeness and video-property checks. Pure, like the M1/M2 blocks above, so
+// the acceptance suite can exercise a restart's decision rules with no Blender
+// and no ffmpeg present.
+// ---------------------------------------------------------------------------
+
+export {
+  RENDER_JOB_VERSION,
+  FRAME_PLAN_VERSION,
+  PROCESS_IDENTITY_VERSION,
+  DELIVERY_MANIFEST_VERSION,
+  RENDER_JOB_STATUSES,
+  RENDER_JOB_TERMINAL_STATUSES,
+  RENDER_JOB_TYPES,
+  FRAME_FILE_PREFIX,
+  FRAME_FILE_PADDING,
+  MIN_FRAME_BYTES,
+  isTerminalRenderJobStatus,
+  canTransitionRenderJob,
+  checkTransition,
+  frameFileName,
+  frameNumbers,
+  inspectFrameSample,
+  inspectFrameBytes,
+  resolveFrameLedger,
+  renderProgressPercent,
+  estimateRemaining,
+  verifyVideoProperties,
+  deliveryCompleteness,
+  describeRenderJob,
+} from './render-job.js'
+
+export {
+  VIEW_ROLES,
+  buildViewPlan,
+  trackedObjects,
+  subjectParts,
+  resolveSubject,
+  resolveSubjectId,
+  buildVisualReview,
+} from './visual-composition.js'
+
+// The workbench UI's contract (M4): the HTTP route table, the panel vocabulary
+// and every view model the browser renders. Pure data and pure functions, so the
+// UI's own rules are covered by contract tests rather than by clicking.
+export {
+  UI_ROUTE_PREFIX,
+  UI_REST_MARKER,
+  UI_ROUTES,
+  UI_PANEL_VIEWS,
+  PREVIEW_SHEET_SLOTS,
+  UI_PANEL_ID,
+  UI_PANEL_LABEL,
+  UI_TOOL_CARD_KEYS,
+  matchUiRoute,
+  writeRouteIds,
+  buildRevisionDiff,
+  buildSceneTree,
+  buildQaView,
+  buildApprovalView,
+  buildJobView,
+  buildProjectView,
+  buildSettingsCard,
+  describeJobForHuman,
+  formatDuration,
+  parseToolCallTarget,
+} from './ui-api.js'
+
+// Where a deployment keeps its state and finds its managed Blender (M5).
+// Shared by the plugin schemas and by the repository's own tools, so that "the
+// project create-demo-project.mjs writes is the one a restarted profile finds"
+// is true by construction rather than by a comment claiming it (see the module).
+export {
+  DEEPBLEND_STATE_DIRECTORY,
+  MANAGED_TOOLS_DIRECTORY,
+  MANAGED_BLENDER_RELATIVE_PATHS,
+  expandHome,
+  resolveDshHome,
+  resolveDefaultWorkspaceRoot,
+  resolveWorkspaceRoot,
+  resolveProjectsRoot,
+  managedBlenderCandidates,
+} from './deployment-paths.js'