@nodaro/shared 2.27.0 → 3.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nodaro/shared",
-  "version": "2.27.0",
+  "version": "3.1.0",
   "description": "Shared types, model catalog, wire contracts, and structural vocabularies for the Nodaro platform and SDK.",
   "type": "module",
   "license": "Apache-2.0",

package/src/__tests__/presentation-utils.test.ts

@@ -12,6 +12,7 @@ import {
   getItemSortId,
   cleanOrphanedItems,
 } from "../presentation-utils.js"
+import { AUDIO_PRODUCER_TYPES, VIDEO_PRODUCER_TYPES } from "../producer-types.js"
 import type { GenericNode, GenericEdge } from "../types.js"
 import type { PresentationItem } from "../presentation-types.js"
 
@@ -1135,3 +1136,99 @@ describe("presentation-utils — action-fx", () => {
     expect(getInputFieldSchema("action-fx")).toEqual({ key: "actionFx", type: "select" })
   })
 })
+
+// ---------------------------------------------------------------------------
+// Canonical output typing — the presentation classifier vs the producer sets
+// ---------------------------------------------------------------------------
+
+/**
+ * `getOutputType` is what a published app renders from and what `/v1` app
+ * schemas and run results declare (`routes/api-tokens.ts`). A node it calls
+ * `"data"` is shown as a JSON blob instead of a player, is skipped by the
+ * lightbox media list, and is announced to API consumers with the wrong type.
+ *
+ * The literal sets in the module are the classifier's own opinion and win; the
+ * tail is derived from the producer vocabularies the canvas validators already
+ * maintain, so a node cannot be a declared video producer and be typed `"data"`
+ * at the same time.
+ */
+describe("getOutputType — derived from the producer vocabularies", () => {
+  it("types 3D Render Pro as video (it settles with the standard videoUrl)", () => {
+    expect(getOutputType("pro-3d-render")).toBe("video")
+  })
+
+  it("types every declared video producer as video", () => {
+    for (const t of VIDEO_PRODUCER_TYPES) expect([t, getOutputType(t)]).toEqual([t, "video"])
+  })
+
+  it("types every declared audio producer as audio, except the dual-mode ones the literal sets claim", () => {
+    for (const t of AUDIO_PRODUCER_TYPES) {
+      // voice-changer / voice-changer-pro / dubbing can emit video; the
+      // classifier's own list still calls them audio, which is their default.
+      expect([t, getOutputType(t)]).toEqual([t, "audio"])
+    }
+  })
+
+  it("leaves a run-time-decided producer as data — there is no honest static answer", () => {
+    expect(getOutputType("list")).toBe("data")
+    expect(getOutputType("sub-workflow")).toBe("data")
+    expect(getOutputType("split-media")).toBe("data")
+  })
+
+  it("keeps the literal sets authoritative where they and the producer sets disagree", () => {
+    // adjust-volume is in AUDIO_PRODUCER_TYPES and DYNAMIC_PRODUCER_TYPES;
+    // upload-video is a video producer AND an input node.
+    expect(getOutputType("adjust-volume")).toBe("audio")
+    expect(getOutputType("upload-video")).toBe("video")
+    expect(getOutputType("text-prompt")).toBe("text")
+  })
+})
+
+describe("published-app / API-token output mapping for 3D Render Pro", () => {
+  const proNode = mkNode("pro", "pro-3d-render", { presentationOutput: true, label: "Render" })
+
+  it("declares the app-schema output type the SDK and MCP read (mirrors routes/api-tokens.ts)", () => {
+    // The route builds `{ nodeId, label, type: getOutputType(node.type) }` for
+    // both the app schema and the run result.
+    const outputs = getOutputNodes([proNode], []).map((n) => ({
+      nodeId: n.id,
+      type: getOutputType(n.type),
+    }))
+    expect(outputs).toEqual([{ nodeId: "pro", type: "video" }])
+  })
+
+  it("is an OUTPUT, not an input — the picker must not offer it as an app input", () => {
+    expect(INPUT_NODE_TYPES.has("pro-3d-render")).toBe(false)
+    expect(getInputNodes([mkNode("pro", "pro-3d-render", { presentationVisible: true })])).toEqual([])
+  })
+})
+
+describe("legacy presentationVisible rules for a media producer", () => {
+  it("stays an output when its composition ALSO feeds something downstream", () => {
+    // The Pro node's `composition` handle commonly feeds an editor or a
+    // re-render; the legacy rule drops a node with an outgoing edge unless it
+    // produces media of its own.
+    const nodes = [
+      mkNode("pro", "pro-3d-render", { presentationVisible: true }),
+      mkNode("edit", "edit-3d-scene", {}),
+    ]
+    const out = getOutputNodes(nodes, [mkEdge("pro", "edit")])
+    expect(out.map((n) => n.id)).toEqual(["pro"])
+  })
+
+  it("applies the same rule to the other video producers the literal list forgot", () => {
+    const nodes = [
+      mkNode("gv", "generate-video", { presentationVisible: true }),
+      mkNode("cap", "add-captions", {}),
+    ]
+    expect(getOutputNodes(nodes, [mkEdge("gv", "cap")]).map((n) => n.id)).toEqual(["gv"])
+  })
+
+  it("still drops a non-media node that feeds something downstream", () => {
+    const nodes = [
+      mkNode("txt", "text-prompt", { presentationVisible: true }),
+      mkNode("gv", "generate-video", {}),
+    ]
+    expect(getOutputNodes(nodes, [mkEdge("txt", "gv")])).toEqual([])
+  })
+})

package/src/__tests__/scene3d-authoring-engine.test.ts

@@ -0,0 +1,104 @@
+import { describe, it, expect } from "vitest"
+import {
+  SCENE3D_DEFAULT_ADVANCED_ENGINE,
+  SCENE3D_SUPPORTED_SCHEMA_VERSIONS,
+  resolveScene3DAuthoringEngine,
+} from "../index.js"
+
+/** Only the fields the resolver reads — it must not need a whole valid plan. */
+const v1Plan = { planType: "3d-scene", schemaVersion: 1 }
+const v2Plan = (engine = "blender-cloud") => ({
+  planType: "3d-scene",
+  schemaVersion: 2,
+  provenance: { engine },
+})
+
+describe("resolveScene3DAuthoringEngine", () => {
+  it("keeps a plain generate on Basic, with NO extra wire fields", () => {
+    const choice = resolveScene3DAuthoringEngine({})
+    expect(choice).toEqual({ ok: true, lane: "basic", engine: undefined, fields: {} })
+  })
+
+  it("keeps a v1 edit on Basic", () => {
+    const choice = resolveScene3DAuthoringEngine({ plan: v1Plan })
+    expect(choice.ok && choice.lane).toBe("basic")
+    expect(choice.ok && choice.fields).toEqual({})
+  })
+
+  it("sends an explicitly requested advanced engine plus the accepted versions", () => {
+    const choice = resolveScene3DAuthoringEngine({
+      requested: "blender-cloud",
+      availableEngines: ["blender-cloud"],
+    })
+    expect(choice.ok && choice.lane).toBe("advanced")
+    expect(choice.ok && choice.fields).toEqual({
+      engine: "blender-cloud",
+      acceptedSceneSchemaVersions: [...SCENE3D_SUPPORTED_SCHEMA_VERSIONS],
+    })
+  })
+
+  it("routes a v2 edit to the advanced lane with no engine chosen", () => {
+    const choice = resolveScene3DAuthoringEngine({ plan: v2Plan() })
+    expect(choice.ok && choice.lane).toBe("advanced")
+    expect(choice.ok && choice.engine).toBe(SCENE3D_DEFAULT_ADVANCED_ENGINE)
+  })
+
+  it("keeps a v2 edit on the engine that authored it", () => {
+    const choice = resolveScene3DAuthoringEngine({
+      plan: v2Plan("blender-local"),
+      availableEngines: ["blender-cloud", "blender-local"],
+    })
+    expect(choice.ok && choice.engine).toBe("blender-local")
+  })
+
+  it("does not send a v2 edit to an authoring engine this install dropped", () => {
+    const choice = resolveScene3DAuthoringEngine({
+      plan: v2Plan("blender-local"),
+      availableEngines: ["blender-cloud"],
+    })
+    expect(choice.ok && choice.engine).toBe("blender-cloud")
+  })
+
+  it("REFUSES a v2 scene pointed at Basic instead of downgrading it", () => {
+    const choice = resolveScene3DAuthoringEngine({ requested: "basic", plan: v2Plan() })
+    expect(choice.ok).toBe(false)
+    expect(!choice.ok && choice.code).toBe("schema_requires_advanced")
+  })
+
+  it("REFUSES a v2 edit when the install has no advanced engine at all", () => {
+    const choice = resolveScene3DAuthoringEngine({ plan: v2Plan(), availableEngines: [] })
+    expect(!choice.ok && choice.code).toBe("advanced_unavailable")
+  })
+
+  it("REFUSES an explicit engine this install does not serve — never falls back to Basic", () => {
+    const choice = resolveScene3DAuthoringEngine({
+      requested: "blender-local",
+      availableEngines: ["blender-cloud"],
+    })
+    expect(!choice.ok && choice.code).toBe("engine_unavailable")
+  })
+
+  it("REFUSES an explicit engine on a v2 scene the same way", () => {
+    const choice = resolveScene3DAuthoringEngine({
+      requested: "blender-local",
+      plan: v2Plan(),
+      availableEngines: ["blender-cloud"],
+    })
+    expect(!choice.ok && choice.code).toBe("engine_unavailable")
+  })
+
+  it("REFUSES an engine name the contract does not know", () => {
+    const choice = resolveScene3DAuthoringEngine({ requested: "unknown-renderer" })
+    expect(!choice.ok && choice.code).toBe("unknown_engine")
+  })
+
+  it("REFUSES a scene claiming a schema version nothing here can author against", () => {
+    const choice = resolveScene3DAuthoringEngine({ plan: { planType: "3d-scene", schemaVersion: 3 } })
+    expect(!choice.ok && choice.code).toBe("unsupported_schema_version")
+  })
+
+  it("stays permissive when availability is UNKNOWN — the route refuses honestly", () => {
+    const choice = resolveScene3DAuthoringEngine({ requested: "blender-local" })
+    expect(choice.ok && choice.engine).toBe("blender-local")
+  })
+})

package/src/__tests__/scene3d-camera-track.test.ts

@@ -0,0 +1,235 @@
+import { describe, expect, it } from "vitest"
+import {
+  SCENE3D_CAMERA_TRACK_LIMITS,
+  isScene3DCameraTrack,
+  parseScene3DCameraTrackJson,
+  scene3DCameraTrackIssues,
+  scene3DCameraTrackPlanIssues,
+  scene3DCameraTrackSchema,
+  scene3DProjectionIssues,
+  scene3DSampleForFrame,
+} from "../scene3d-camera-track.js"
+import {
+  FIXTURE_FPS,
+  FIXTURE_FRAMES,
+  FIXTURE_HEIGHT,
+  FIXTURE_WIDTH,
+  cameraSample,
+  cameraTrack,
+  orthographicMatrix,
+  perspectiveMatrix,
+  planV2,
+} from "./scene3d-v2-fixtures.js"
+
+function joined(track: unknown): string {
+  const result = scene3DCameraTrackSchema.safeParse(track)
+  return result.success ? "" : result.error.issues.map((issue) => issue.message).join(" | ")
+}
+
+describe("scene3d camera track — structure", () => {
+  it("accepts a full 720-sample track", () => {
+    const track = cameraTrack()
+    expect(scene3DCameraTrackSchema.safeParse(track).success).toBe(true)
+    expect(isScene3DCameraTrack(track)).toBe(true)
+    expect(scene3DCameraTrackIssues(track)).toEqual([])
+  })
+
+  it("accepts the maximum frame count and rejects one more", () => {
+    expect(SCENE3D_CAMERA_TRACK_LIMITS.maxFrameCount).toBe(3600)
+    expect(scene3DCameraTrackSchema.safeParse(cameraTrack(3600)).success).toBe(true)
+    expect(scene3DCameraTrackSchema.safeParse(cameraTrack(3601)).success).toBe(false)
+  })
+
+  it("requires exactly one sample per frame", () => {
+    const short = cameraTrack(10)
+    short.samples = short.samples.slice(0, 9)
+    expect(joined(short)).toContain("exactly one sample per frame is required")
+
+    const long = cameraTrack(10)
+    long.samples.push(cameraSample())
+    expect(joined(long)).toContain("exactly one sample per frame is required")
+  })
+
+  it("pins the format, version and zero-based frame start", () => {
+    expect(joined({ ...cameraTrack(2), format: "something-else" })).not.toBe("")
+    expect(joined({ ...cameraTrack(2), version: 2 })).not.toBe("")
+    expect(joined({ ...cameraTrack(2), frameStart: 1 })).not.toBe("")
+  })
+
+  it("rejects unknown keys on the track and on a sample", () => {
+    expect(joined({ ...cameraTrack(2), extra: true })).not.toBe("")
+    const track = cameraTrack(2)
+    ;(track.samples[0] as unknown as Record<string, unknown>).lookAtOverride = [0, 0, 0]
+    expect(joined(track)).not.toBe("")
+  })
+
+  it("rejects a foreign value outright", () => {
+    for (const bad of [null, 7, "track", [], {}]) {
+      expect(isScene3DCameraTrack(bad)).toBe(false)
+    }
+  })
+})
+
+describe("scene3d camera track — quaternions", () => {
+  it("rejects an unnormalized quaternion", () => {
+    const track = cameraTrack(3)
+    track.samples[1] = cameraSample({ quaternion: [0, 0, 0, 2] })
+    expect(joined(track)).toContain("it must be normalized")
+  })
+
+  it("accepts float noise inside the tolerance", () => {
+    const track = cameraTrack(3)
+    track.samples[1] = cameraSample({ quaternion: [0, 0, 0, 1 + 1e-6] })
+    expect(scene3DCameraTrackSchema.safeParse(track).success).toBe(true)
+  })
+
+  it("rejects a non-finite quaternion component", () => {
+    const track = cameraTrack(2)
+    track.samples[0] = cameraSample({ quaternion: [0, 0, 0, Number.NaN] })
+    expect(scene3DCameraTrackSchema.safeParse(track).success).toBe(false)
+  })
+})
+
+describe("scene3d camera track — projection", () => {
+  const aspect = FIXTURE_WIDTH / FIXTURE_HEIGHT
+
+  it("accepts a real perspective matrix", () => {
+    expect(scene3DProjectionIssues(perspectiveMatrix(35, aspect, 0.1, 200), 0.1, 200, ["m"])).toEqual([])
+  })
+
+  it("names orthographic instead of mis-reading it as a broken perspective", () => {
+    const issues = scene3DProjectionIssues(orthographicMatrix(0.1, 200), 0.1, 200, ["m"])
+    expect(issues).toHaveLength(1)
+    expect(issues[0].message).toContain("orthographic")
+  })
+
+  it("rejects the wrong number of entries and non-finite entries", () => {
+    expect(scene3DProjectionIssues([1, 2, 3], 0.1, 200, ["m"])[0].message).toContain("exactly 16 entries")
+    const broken = perspectiveMatrix(35, aspect, 0.1, 200)
+    broken[0] = Number.POSITIVE_INFINITY
+    expect(scene3DProjectionIssues(broken, 0.1, 200, ["m"])[0].message).toContain("non-finite")
+  })
+
+  it("rejects a matrix whose fixed entries are not fixed", () => {
+    for (const index of [1, 2, 3, 4, 6, 7, 12, 13, 15]) {
+      const matrix = perspectiveMatrix(35, aspect, 0.1, 200)
+      matrix[index] = 0.5
+      const issues = scene3DProjectionIssues(matrix, 0.1, 200, ["m"])
+      expect(issues.length).toBeGreaterThan(0)
+    }
+    const notPerspective = perspectiveMatrix(35, aspect, 0.1, 200)
+    notPerspective[11] = -0.5
+    expect(scene3DProjectionIssues(notPerspective, 0.1, 200, ["m"])[0].message).toContain("must be -1")
+  })
+
+  it("rejects a matrix that disagrees with its own declared near/far", () => {
+    const matrix = perspectiveMatrix(35, aspect, 0.1, 200)
+    const nearIssues = scene3DProjectionIssues(matrix, 0.5, 200, ["m"])
+    expect(nearIssues.map((issue) => issue.message).join(" ")).toContain("implies near")
+
+    const farIssues = scene3DProjectionIssues(matrix, 0.1, 500, ["m"])
+    expect(farIssues.map((issue) => issue.message).join(" ")).toContain("implies far")
+  })
+
+  it("rejects an infinite-far matrix that declares a finite far plane", () => {
+    const matrix = perspectiveMatrix(35, aspect, 0.1, 200)
+    matrix[10] = -1
+    matrix[14] = -0.2
+    expect(scene3DProjectionIssues(matrix, 0.1, 200, ["m"]).map((i) => i.message).join(" ")).toContain(
+      "infinite far plane",
+    )
+  })
+
+  it("rejects near/far that are not strictly ordered", () => {
+    const track = cameraTrack(2)
+    track.samples[0] = cameraSample({ near: 200, far: 200 })
+    expect(joined(track)).toContain("must be greater than near")
+  })
+})
+
+describe("scene3d camera track — agreement with the manifest", () => {
+  const plan = planV2()
+
+  it("accepts a matching track", () => {
+    expect(scene3DCameraTrackPlanIssues(cameraTrack(), plan)).toEqual([])
+  })
+
+  it("rejects a different fps — retiming needs a new revision", () => {
+    const track = cameraTrack(FIXTURE_FRAMES, { fps: 30 })
+    const messages = scene3DCameraTrackPlanIssues(track, plan).map((issue) => issue.message)
+    expect(messages.join(" ")).toContain("changing fps requires an explicit resample")
+    expect(FIXTURE_FPS).toBe(24)
+  })
+
+  it("rejects a different length", () => {
+    const messages = scene3DCameraTrackPlanIssues(cameraTrack(600), plan).map((issue) => issue.message)
+    expect(messages.join(" ")).toContain("covers 600 frames but the scene is 720 frames")
+  })
+
+  it("rejects a projection baked for another aspect ratio", () => {
+    const track = cameraTrack(4)
+    track.samples[2] = cameraSample({ projectionMatrix: perspectiveMatrix(35, 16 / 9, 0.1, 200) })
+    const messages = scene3DCameraTrackPlanIssues(track, {
+      fps: FIXTURE_FPS,
+      durationInFrames: 4,
+      width: FIXTURE_WIDTH,
+      height: FIXTURE_HEIGHT,
+    }).map((issue) => issue.message)
+    expect(messages.join(" ")).toContain("reprojection requires a new revision")
+  })
+})
+
+describe("scene3d camera track — deterministic sampling", () => {
+  it("maps frame f to samples[f], and refuses to clamp", () => {
+    const track = cameraTrack(10)
+    for (const frame of [0, 4, 9]) {
+      expect(scene3DSampleForFrame(track, frame)).toBe(track.samples[frame])
+    }
+    expect(scene3DSampleForFrame(track, 10)).toBeUndefined()
+    expect(scene3DSampleForFrame(track, -1)).toBeUndefined()
+    expect(scene3DSampleForFrame(track, 2.5)).toBeUndefined()
+  })
+
+  it("is order-independent: backwards and shuffled reads give identical samples", () => {
+    const track = cameraTrack(24)
+    const forward = Array.from({ length: 24 }, (_unused, frame) => scene3DSampleForFrame(track, frame))
+    const backward = Array.from({ length: 24 }, (_unused, index) => scene3DSampleForFrame(track, 23 - index)).reverse()
+    const shuffled = [7, 0, 23, 12, 3].map((frame) => scene3DSampleForFrame(track, frame))
+    expect(backward).toEqual(forward)
+    expect(shuffled).toEqual([7, 0, 23, 12, 3].map((frame) => forward[frame]))
+  })
+})
+
+describe("scene3d camera track — JSON admission", () => {
+  it("accepts a well-formed payload", () => {
+    const result = parseScene3DCameraTrackJson(JSON.stringify(cameraTrack(12)))
+    expect(result.ok).toBe(true)
+  })
+
+  it("refuses an oversized payload before parsing it", () => {
+    const padding = "x".repeat(SCENE3D_CAMERA_TRACK_LIMITS.maxJsonBytes + 1)
+    const result = parseScene3DCameraTrackJson(padding)
+    expect(result.ok).toBe(false)
+    expect(result.ok ? "" : result.issues[0].message).toContain("the limit is")
+  })
+
+  it("reports malformed JSON as an issue rather than throwing", () => {
+    const result = parseScene3DCameraTrackJson("{ not json")
+    expect(result.ok).toBe(false)
+    expect(result.ok ? "" : result.issues[0].message).toContain("not valid JSON")
+  })
+
+  it("reports schema failures with paths", () => {
+    const track = cameraTrack(3)
+    track.samples[1] = cameraSample({ quaternion: [1, 1, 1, 1] })
+    const result = parseScene3DCameraTrackJson(JSON.stringify(track))
+    expect(result.ok).toBe(false)
+    expect(result.ok ? [] : result.issues.map((issue) => issue.path.join("."))).toContain("samples.1.quaternion")
+  })
+
+  it("counts bytes, not characters", () => {
+    // A multi-byte name must not slip past a length check that counted chars.
+    const text = JSON.stringify({ note: "é".repeat(10) })
+    expect(text.length).toBeLessThan(new TextEncoder().encode(text).length)
+  })
+})

package/src/__tests__/scene3d-v2-edit.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest"
+import { applyScene3DV2EditOperations } from "../scene3d-v2-edit.js"
+import { computeScene3DPlanV2ContentHash, verifyScene3DPlanV2ContentHash } from "../scene3d-v2-resources.js"
+import { planV2 } from "./scene3d-v2-fixtures.js"
+
+async function fixture() {
+  const p = planV2()
+  return { ...p, provenance: { ...p.provenance, contentHash: await computeScene3DPlanV2ContentHash(p) } }
+}
+const move = { op: "set-override" as const, override: { kind: "entity-transform" as const, entityId: "e2", space: "world" as const, position: [4, 0, 0] as [number, number, number] } }
+const revision = "c94b9f2f-4f10-48a6-a0bf-3ca4c2653b5a"
+
+describe("baked scene edits", () => {
+  it("preserves unrelated state, stamps an immutable revision, and withdraws a stale native download", async () => {
+    const p = await fixture()
+    const before = JSON.stringify(p)
+    const result = await applyScene3DV2EditOperations(p, [move], { expectedRevisionId: p.revisionId, newRevisionId: revision })
+    expect(result.ok).toBe(true)
+    if (!result.ok) return
+    expect(result.plan.revisionId).toBe(revision)
+    expect(result.plan.parentRevisionId).toBe(p.revisionId)
+    expect(result.plan.objects).toEqual(p.objects)
+    expect(result.plan.assets).toEqual(p.assets.filter((a) => a.kind === "glb" || a.kind === "camera-track-json").map((a) => ({ ...a, originRevisionId: a.originRevisionId ?? p.revisionId })))
+    expect(result.plan.provenance.sourceArtifactId).toBeUndefined()
+    expect(result.plan.overrides?.find((o) => o.kind === "entity-color")).toEqual(p.overrides?.find((o) => o.kind === "entity-color"))
+    expect(result.plan.overrides?.find((o) => o.kind === "entity-transform")).toMatchObject({ position: [4, 0, 0], sourceRevisionId: p.revisionId, sourceContentHash: p.provenance.contentHash })
+    expect(await verifyScene3DPlanV2ContentHash(result.plan)).toBe(true)
+    expect(JSON.stringify(p)).toBe(before)
+  })
+  it("replays identically with an admission-allocated revision", async () => {
+    const p = await fixture()
+    const options = { expectedRevisionId: p.revisionId, newRevisionId: revision }
+    expect(await applyScene3DV2EditOperations(p, [move], options)).toEqual(await applyScene3DV2EditOperations(p, [move], options))
+  })
+  it("withdraws images and validation that describe the previous revision", async () => {
+    const p = await fixture()
+    p.assets.push(
+      { assetId: "12b3a7d6-3aef-4e5f-b388-e6b96dcaa0f1", kind: "poster", role: "poster", sha256: "a".repeat(64), byteLength: 100 },
+      { assetId: "12b3a7d6-3aef-4e5f-b388-e6b96dcaa0f2", kind: "validation-report", role: "validation-report", sha256: "b".repeat(64), byteLength: 100 },
+    )
+    p.provenance.contentHash = await computeScene3DPlanV2ContentHash(p)
+    const result = await applyScene3DV2EditOperations(p, [move], { expectedRevisionId: p.revisionId })
+    expect(result.ok).toBe(true)
+    if (result.ok) expect(result.plan.assets.every((a) => a.kind === "glb" || a.kind === "camera-track-json")).toBe(true)
+  })
+  it("rejects stale identity and content, and tampered manifests", async () => {
+    const p = await fixture()
+    expect(await applyScene3DV2EditOperations(p, [move], { expectedRevisionId: revision })).toMatchObject({ ok: false, code: "stale_revision" })
+    expect(await applyScene3DV2EditOperations(p, [move], { expectedRevisionId: p.revisionId, expectedContentHash: "a".repeat(64) })).toMatchObject({ ok: false, code: "stale_revision" })
+    expect(await applyScene3DV2EditOperations({ ...p, backgroundColor: "#ffffff" }, [move], { expectedRevisionId: p.revisionId })).toMatchObject({ ok: false, code: "invalid_plan" })
+  })
+  it("blocks changes and removal of changes on locked entities", async () => {
+    const p = await fixture()
+    const options = { expectedRevisionId: p.revisionId, lockedObjectIds: ["e2"] }
+    expect(await applyScene3DV2EditOperations(p, [move], options)).toMatchObject({ ok: false, code: "locked" })
+    expect(await applyScene3DV2EditOperations(p, [{ op: "remove-override", overrideId: "ov-1" }], options)).toMatchObject({ ok: false, code: "locked" })
+  })
+  it("cannot evade a descendant lock by moving or hiding its parent", async () => {
+    const p = await fixture()
+    const options = { expectedRevisionId: p.revisionId, lockedObjectIds: ["e2"] }
+    expect(await applyScene3DV2EditOperations(p, [{ ...move, override: { ...move.override, entityId: "e1" } }], options)).toMatchObject({ ok: false, code: "locked" })
+    expect(await applyScene3DV2EditOperations(p, [{ op: "set-override", override: { kind: "entity-visibility", entityId: "e1", visible: false } }], options)).toMatchObject({ ok: false, code: "locked" })
+  })
+  it("preserves edited pose components when another component changes", async () => {
+    const p = await fixture()
+    const result = await applyScene3DV2EditOperations(p, [move, { ...move, override: { kind: "entity-transform", entityId: "e2", space: "world", rotation: [0, 1, 0] } }], { expectedRevisionId: p.revisionId })
+    expect(result.ok).toBe(true)
+    if (result.ok) expect(result.plan.overrides?.find((o) => o.kind === "entity-transform")).toMatchObject({ position: [4, 0, 0], rotation: [0, 1, 0] })
+  })
+  it("does not carry coordinates across a space change", async () => {
+    const p = await fixture()
+    const result = await applyScene3DV2EditOperations(p, [{ ...move, override: { kind: "entity-transform", entityId: "e2", space: "local", rotation: [0, 1, 0] } }], { expectedRevisionId: p.revisionId })
+    expect(result.ok).toBe(true)
+    if (result.ok) expect(result.plan.overrides?.find((o) => o.kind === "entity-transform")).not.toHaveProperty("position")
+  })
+  it("rejects missing targets, unknown material roles, and invalid later operations atomically", async () => {
+    const p = await fixture()
+    const before = JSON.stringify(p)
+    expect(await applyScene3DV2EditOperations(p, [move, { op: "set-override", override: { kind: "entity-color", entityId: "e2", materialRole: "chair", color: "#ffffff" } }], { expectedRevisionId: p.revisionId })).toMatchObject({ ok: false, code: "invalid_operations" })
+    expect(await applyScene3DV2EditOperations(p, [{ op: "remove-override", overrideId: "missing" }], { expectedRevisionId: p.revisionId })).toMatchObject({ ok: false, code: "invalid_operations" })
+    expect(JSON.stringify(p)).toBe(before)
+  })
+})