@hraness/slopcamera 3.2.8 → 3.3.2

package/src/spatial-scene/gallery.ts

@@ -0,0 +1,277 @@
+import { z } from "zod"
+
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import {
+  SpatialCameraIdSchema,
+  SpatialDigestSchema,
+  SpatialSceneV1Schema,
+  SpatialTimeUsSchema,
+} from "./contracts.js"
+import {
+  compileSpatialDirection,
+  SpatialDirectionCompilationSchema,
+  spatialDirectionCompilationSha256,
+  type SpatialDirectionCompilation,
+} from "./direction-compile.js"
+import { SpatialDirectionSchema, type SpatialDirection } from "./direction.js"
+import { parseSpatialValue, spatialValueSha256 } from "./identity.js"
+
+/**
+ * Bounded direction galleries for Phase 12.
+ *
+ * A gallery plan enumerates at most six deterministic variants of one direction
+ * along a single axis — performance pacing, camera rig families, lighting and
+ * material presets, post-process suggestions, or sequence granularity. Camera
+ * and sequence variants re-author the direction and recompile; look variants
+ * annotate the compiled look intents. Every candidate embeds its own compiled
+ * variant document: source, derived, and selection identities stay separate,
+ * and the planner never renders or selects.
+ */
+
+export const SPATIAL_GALLERY_LIMITS = Object.freeze({
+  candidates: 6,
+  previewSamples: 8,
+})
+
+export const SpatialGalleryAxisSchema = z.enum([
+  "performance",
+  "camera",
+  "lighting",
+  "materials",
+  "effects",
+  "sequence",
+])
+export type SpatialGalleryAxis = z.infer<typeof SpatialGalleryAxisSchema>
+
+export const SpatialGalleryCandidateSchema = z.strictObject({
+  candidateId: z.string().min(1).max(96).regex(/^cand_[a-f0-9]{16}$/u),
+  label: z.string().min(1).max(128),
+  parameter: z.string().min(1).max(64),
+  documentKind: z.literal("slopcamera.spatial-direction-compilation"),
+  documentSha256: SpatialDigestSchema,
+  document: z.unknown(),
+})
+export type SpatialGalleryCandidate = Readonly<z.infer<typeof SpatialGalleryCandidateSchema>>
+
+export const SpatialGalleryPlanSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-gallery-plan"),
+  schemaVersion: z.literal(1),
+  axis: SpatialGalleryAxisSchema,
+  sourceSha256: SpatialDigestSchema,
+  sceneSha256: SpatialDigestSchema,
+  cameraId: SpatialCameraIdSchema.optional(),
+  candidates: z.array(SpatialGalleryCandidateSchema).max(SPATIAL_GALLERY_LIMITS.candidates),
+  previewReel: z.strictObject({
+    sampleTimesUs: z.array(SpatialTimeUsSchema).max(SPATIAL_GALLERY_LIMITS.previewSamples),
+  }).optional(),
+  selection: z.strictObject({
+    candidateId: z.string().min(1).max(96),
+    selectorDigest: SpatialDigestSchema.optional(),
+    note: z.string().min(1).max(256).optional(),
+  }).optional(),
+})
+export type SpatialGalleryPlan = Readonly<z.infer<typeof SpatialGalleryPlanSchema>>
+
+export function spatialGalleryPlanSha256(plan: SpatialGalleryPlan): string {
+  return spatialValueSha256(plan)
+}
+
+const CAMERA_VARIANT_RIGS = ["tripod", "dolly", "orbit", "rail", "chase", "handheld"] as const
+const PERFORMANCE_VARIANT_SCALE = [1, 0.9, 1.1, 0.75, 1.25, 1.5] as const
+const LIGHTING_VARIANT_PRESETS = ["neutral", "low-key", "high-key", "night", "dawn", "storm"] as const
+const MATERIAL_VARIANT_PALETTES = ["authored", "warm", "cool", "monochrome", "pastel", "noir"] as const
+const SEQUENCE_VARIANT_STRIDE = [1, 2, 3, 4, 5, 6] as const
+
+const EFFECTS_VARIANT_STACKS: ReadonlyArray<readonly Record<string, unknown>[]> = [
+  [],
+  [{ kind: "tone-map", exposure: 1, whitePoint: 4 }],
+  [
+    { kind: "tone-map", exposure: 1, whitePoint: 4 },
+    { kind: "vignette", intensity: 0.25, radius: 0.5 },
+  ],
+  [
+    { kind: "tone-map", exposure: 1, whitePoint: 4 },
+    { kind: "grain", intensity: 0.08, seed: 7 },
+  ],
+  [
+    { kind: "tone-map", exposure: 1, whitePoint: 4 },
+    { kind: "bloom", threshold: 0.85, intensity: 0.35, radius: 0.5 },
+  ],
+  [
+    { kind: "tone-map", exposure: 0.9, whitePoint: 2 },
+    { kind: "vignette", intensity: 0.35, radius: 0.6 },
+    { kind: "grain", intensity: 0.1, seed: 11 },
+  ],
+]
+
+const candidateId = (axis: SpatialGalleryAxis, parameter: string, sourceSha256: string): string =>
+  `cand_${spatialValueSha256({ domain: "slopcamera.gallery-candidate.v1", axis, parameter, sourceSha256 }).slice(0, 16)}`
+
+interface GalleryVariant {
+  readonly parameter: string
+  readonly label: string
+  readonly direction?: (direction: SpatialDirection) => SpatialDirection
+  readonly document?: (compilation: SpatialDirectionCompilation) => SpatialDirectionCompilation
+}
+
+function variantsForAxis(axis: SpatialGalleryAxis, sceneDurationUs: number): readonly GalleryVariant[] {
+  switch (axis) {
+    case "camera":
+      return CAMERA_VARIANT_RIGS.map((rigKind) => ({
+        parameter: rigKind,
+        label: `All coverage on ${rigKind} rigs`,
+        direction: (direction) => deepFreezeJson({
+          ...direction,
+          coverage: direction.coverage.map((coverage) => ({ ...coverage, rigKind })),
+        }),
+      }))
+    case "performance":
+      return PERFORMANCE_VARIANT_SCALE.map((scale) => ({
+        parameter: `pacing-${scale}`,
+        label: `Action pacing scaled ${scale}×`,
+        direction: (direction) => deepFreezeJson({
+          ...direction,
+          actions: direction.actions.map((action) => ({
+            ...action,
+            endUs: Math.min(
+              action.startUs + Math.max(1, Math.round((action.endUs - action.startUs) * scale)),
+              sceneDurationUs,
+            ),
+          })),
+        }),
+      }))
+    case "sequence":
+      return SEQUENCE_VARIANT_STRIDE.map((stride) => ({
+        parameter: `stride-${stride}`,
+        label: stride === 1 ? "Coverage-aligned shots" : `Merge coverage in groups of ${stride}`,
+        direction: (direction) => {
+          if (stride <= 1) return direction
+          const coverage = []
+          for (let index = 0; index < direction.coverage.length; index += stride) {
+            const group = direction.coverage.slice(index, index + stride)
+            const first = group[0]!
+            const last = group[group.length - 1]!
+            coverage.push({ ...first, endUs: last.endUs })
+          }
+          return deepFreezeJson({ ...direction, coverage })
+        },
+      }))
+    case "lighting":
+      return LIGHTING_VARIANT_PRESETS.map((preset) => ({
+        parameter: preset,
+        label: `Lighting preset ${preset}`,
+        document: (compilation) => SpatialDirectionCompilationSchema.parse(deepFreezeJson({
+          ...compilation,
+          proposals: {
+            ...compilation.proposals,
+            lookIntents: compilation.proposals.lookIntents.map((intent) => ({
+              ...intent,
+              suggestedLightingPreset: preset,
+            })),
+          },
+        })),
+      }))
+    case "materials":
+      return MATERIAL_VARIANT_PALETTES.map((palette) => ({
+        parameter: palette,
+        label: `Material palette ${palette}`,
+        document: (compilation) => SpatialDirectionCompilationSchema.parse(deepFreezeJson({
+          ...compilation,
+          proposals: {
+            ...compilation.proposals,
+            lookIntents: compilation.proposals.lookIntents.map((intent) => ({
+              ...intent,
+              suggestedMaterialPalette: palette,
+            })),
+          },
+        })),
+      }))
+    case "effects":
+      return EFFECTS_VARIANT_STACKS.map((stack, index) => ({
+        parameter: `stack-${index}`,
+        label: stack.length === 0
+          ? "No post-process stack"
+          : `Post stack: ${stack.map((step) => String(step.kind)).join(" → ")}`,
+        document: (compilation) => SpatialDirectionCompilationSchema.parse(deepFreezeJson({
+          ...compilation,
+          proposals: {
+            ...compilation.proposals,
+            lookIntents: compilation.proposals.lookIntents.map((intent) => ({
+              ...intent,
+              suggestedPostProcess: stack,
+            })),
+          },
+        })),
+      }))
+  }
+}
+
+const galleryOptionsSchema = z.strictObject({
+  direction: z.unknown(),
+  scene: z.unknown(),
+  axis: SpatialGalleryAxisSchema,
+  cameraId: z.string().min(1).max(128).optional(),
+})
+
+const compileVariant = (
+  direction: SpatialDirection,
+  scene: unknown,
+  cameraId: string | undefined,
+): SpatialDirectionCompilation =>
+  compileSpatialDirection({ direction, scene, ...(cameraId === undefined ? {} : { cameraId }) })
+
+/**
+ * Builds a bounded gallery plan. Variants compile independently; candidates
+ * whose documents collide keep the first so the plan stays deduplicated and
+ * deterministic. `selection` is never populated by the planner.
+ */
+export function planSpatialDirectionGallery(input: unknown): SpatialGalleryPlan {
+  const options = parseSpatialValue(galleryOptionsSchema, input, "direction gallery")
+  const direction = parseSpatialValue(SpatialDirectionSchema, options.direction, "direction")
+  const scene = parseSpatialValue(SpatialSceneV1Schema, options.scene, "scene")
+  const base = compileSpatialDirection({
+    direction, scene, ...(options.cameraId === undefined ? {} : { cameraId: options.cameraId }),
+  })
+
+  const seen = new Set<string>()
+  const candidates: SpatialGalleryCandidate[] = []
+  for (const variant of variantsForAxis(options.axis, scene.durationUs)) {
+    const document = variant.direction !== undefined
+      ? compileVariant(variant.direction(direction), scene, options.cameraId)
+      : variant.document!(base)
+    const documentSha256 = spatialDirectionCompilationSha256(document)
+    if (seen.has(documentSha256)) continue
+    seen.add(documentSha256)
+    candidates.push(deepFreezeJson({
+      candidateId: candidateId(options.axis, variant.parameter, base.directionSha256),
+      label: variant.label,
+      parameter: variant.parameter,
+      documentKind: "slopcamera.spatial-direction-compilation",
+      documentSha256,
+      document,
+    }))
+    if (candidates.length >= SPATIAL_GALLERY_LIMITS.candidates) break
+  }
+
+  const sampleTimes = new Set<number>()
+  for (const beat of direction.beats) {
+    sampleTimes.add(Math.min(beat.startUs + Math.floor((beat.endUs - beat.startUs) / 2), scene.durationUs))
+  }
+  for (const coverage of direction.coverage) {
+    sampleTimes.add(Math.min(coverage.startUs, scene.durationUs))
+  }
+  const previewReel = sampleTimes.size === 0
+    ? undefined
+    : { sampleTimesUs: [...sampleTimes].sort((a, b) => a - b).slice(0, SPATIAL_GALLERY_LIMITS.previewSamples) }
+
+  return deepFreezeJson(SpatialGalleryPlanSchema.parse({
+    kind: "slopcamera.spatial-gallery-plan",
+    schemaVersion: 1,
+    axis: options.axis,
+    sourceSha256: base.directionSha256,
+    sceneSha256: base.sceneSha256,
+    ...(base.cameraId === undefined ? {} : { cameraId: base.cameraId }),
+    candidates,
+    ...(previewReel === undefined ? {} : { previewReel }),
+  }))
+}

package/src/spatial-scene/generate.ts

@@ -0,0 +1,239 @@
+import { z } from "zod"
+import type { JsonValue } from "../code/contracts.js"
+import { deepFreezeJson, createBoundedJsonValueSnapshot } from "../code/json-snapshot.js"
+import {
+  SPATIAL_SCENE_LIMITS, SpatialDigestSchema, SpatialEntitySchema, SpatialGeneratorIdSchema,
+  SpatialGeneratorSchema,
+  type SpatialAssetManifest, type SpatialEntity, type SpatialGenerator, type SpatialSceneV1,
+} from "./contracts.js"
+import {
+  generatedSpatialEntityId, parseSpatialScene, parseSpatialValue, SpatialSceneError,
+  spatialGeneratorOutputSha256, spatialValueSha256,
+} from "./identity.js"
+
+/**
+ * Authoring-time generator support. These functions shape and validate the
+ * output of an already-executed generator module; importing or running module
+ * source is a host effect owned by the CLI layer, never this portable layer.
+ */
+export const SPATIAL_GENERATOR_LIMITS = Object.freeze({
+  moduleSourceBytes: 1_048_576,
+  parametersBytes: 65_536,
+  parametersDepth: 16,
+  parametersValues: 8_192,
+})
+
+/** The module contract: generate(ctx) returns entities without identity plus declared editable keys. */
+export interface SpatialGeneratorModuleContext {
+  readonly seed: number
+  readonly parameters: JsonValue
+  readonly lib: {
+    /** Derived identity for a sibling key, for parentId links inside one output. */
+    readonly entityId: (key: string) => string
+  }
+}
+
+const moduleResultSchema = z.strictObject({
+  entities: z.array(z.unknown()).max(SPATIAL_SCENE_LIMITS.entities),
+  editableKeys: SpatialGeneratorSchema.shape.editableKeys.optional(),
+})
+
+export interface ValidatedSpatialGeneratorOutput {
+  readonly entities: readonly SpatialEntity[]
+  readonly editableKeys: SpatialGenerator["editableKeys"]
+}
+
+/** Parameters are bounded plain JSON; modules receive the frozen captured value. */
+export function parseSpatialGeneratorParameters(input: unknown): JsonValue {
+  return createBoundedJsonValueSnapshot(input, SPATIAL_GENERATOR_LIMITS.parametersBytes, "generator parameters", {
+    maximumDepth: SPATIAL_GENERATOR_LIMITS.parametersDepth,
+    maximumValues: SPATIAL_GENERATOR_LIMITS.parametersValues,
+  }).value
+}
+
+export function spatialGeneratorParametersSha256(parameters: unknown): string {
+  return spatialValueSha256({ domain: "slopcamera.generator-parameters.v1", parameters })
+}
+
+/** Absent --seed derives a stable uint32 from the exact source bytes. */
+export function deriveSpatialGeneratorSeed(sourceSha256: string): number {
+  SpatialDigestSchema.parse(sourceSha256)
+  return Number.parseInt(sourceSha256.slice(0, 8), 16)
+}
+
+/**
+ * Content-addressed attempt identity. Identical inputs reproduce the identical
+ * retained record; a changed source, parameters, seed, runtime, or output is a
+ * different attempt.
+ */
+export function spatialGeneratorAttemptId(options: {
+  readonly generatorId: string
+  readonly sourceSha256: string
+  readonly parametersSha256: string
+  readonly runtimeSha256: string
+  readonly outputSha256: string
+  readonly seed: number
+}): string {
+  return `attempt_${spatialValueSha256({ domain: "slopcamera.generator-attempt.v1", ...options }).slice(0, 32)}`
+}
+
+function generatedAssetReference(entity: SpatialEntity): string | undefined {
+  if (entity.kind === "mesh") {
+    if (entity.geometry.kind === "asset") return entity.geometry.assetId
+    return entity.material.kind !== "pbr" ? entity.material.map : undefined
+  }
+  if (entity.kind === "text") return entity.fontAssetId
+  return "assetId" in entity ? entity.assetId : undefined
+}
+
+/**
+ * Stamps generated identity onto keyed entities and validates the result.
+ * Modules must not set entityId or origin: the host owns the
+ * entityId == generatedSpatialEntityId(generatorId, key) invariant, so a module
+ * cannot forge authored provenance or another generator's output. This version
+ * rejects asset references; generated output is mesh primitives, lights, and
+ * groups only.
+ */
+export function validateSpatialGeneratorOutput(generatorId: string, output: unknown): ValidatedSpatialGeneratorOutput {
+  SpatialGeneratorIdSchema.parse(generatorId)
+  const result = parseSpatialValue(moduleResultSchema, output, "generator output")
+  const seen = new Set<string>()
+  const entities: SpatialEntity[] = []
+  for (const [index, raw] of result.entities.entries()) {
+    if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+      throw new SpatialSceneError("invalid-data", `Generated entity ${index} must be a plain object carrying a stable key.`, "generator output")
+    }
+    const record = raw as Readonly<Record<string, unknown>>
+    const key = record.key
+    if (typeof key !== "string" || key.length < 1 || key.length > 256) {
+      throw new SpatialSceneError("invalid-data", `Generated entity ${index} must carry a string "key" of 1–256 characters.`, "generator output")
+    }
+    if ("entityId" in record || "origin" in record) {
+      throw new SpatialSceneError("invalid-data", `Generated entity "${key}" must not set entityId or origin; the host stamps generated identity.`, "generator output")
+    }
+    if (seen.has(key)) throw new SpatialSceneError("invalid-data", `Duplicate generator output key "${key}".`, "generator output")
+    seen.add(key)
+    const { key: _omitted, ...fields } = record
+    const entity = parseSpatialValue(SpatialEntitySchema, {
+      ...fields,
+      entityId: generatedSpatialEntityId(generatorId, key),
+      origin: { kind: "generated", generatorId, key },
+    }, `generator output ${key}`)
+    const assetId = generatedAssetReference(entity)
+    if (assetId !== undefined) {
+      throw new SpatialSceneError("invalid-data", `Generated entity "${key}" references ${assetId}; generated entities cannot reference assets in this version.`, "generator output")
+    }
+    entities.push(entity)
+  }
+  const editableKeys = result.editableKeys ?? []
+  const declared = new Set<string>()
+  for (const editable of editableKeys) {
+    if (declared.has(editable.key)) throw new SpatialSceneError("invalid-data", `Duplicate editable key "${editable.key}".`, "generator editableKeys")
+    declared.add(editable.key)
+    if (!seen.has(editable.key)) {
+      throw new SpatialSceneError("invalid-data", `Editable key "${editable.key}" does not match any produced entity key.`, "generator editableKeys")
+    }
+  }
+  return deepFreezeJson({ entities, editableKeys })
+}
+
+/** Builds the retained attempt record; outputSha256 is recomputed from stamped entities. */
+export function buildSpatialGeneratorRecord(options: {
+  readonly generatorId: string
+  readonly sourceSha256: string
+  readonly closureSha256: string
+  readonly parametersSha256: string
+  readonly seed: number
+  readonly runtimeSha256: string
+  readonly entities: readonly SpatialEntity[]
+  readonly editableKeys: SpatialGenerator["editableKeys"]
+  /** Sorted ids of generator-owned assets (generated payloads and derived facts manifests). */
+  readonly assets?: readonly string[]
+}): SpatialGenerator {
+  const outputSha256 = spatialGeneratorOutputSha256(options.entities)
+  const attemptId = spatialGeneratorAttemptId({
+    generatorId: options.generatorId,
+    sourceSha256: options.sourceSha256,
+    parametersSha256: options.parametersSha256,
+    runtimeSha256: options.runtimeSha256,
+    outputSha256,
+    seed: options.seed,
+  })
+  return parseSpatialValue(SpatialGeneratorSchema, {
+    generatorId: options.generatorId,
+    sourceSha256: options.sourceSha256,
+    closureSha256: options.closureSha256,
+    parametersSha256: options.parametersSha256,
+    seed: options.seed,
+    outputSha256,
+    execution: { kind: "attempt", attemptId, runtimeSha256: options.runtimeSha256 },
+    editableKeys: options.editableKeys,
+    ...(options.assets === undefined ? {} : { assets: [...options.assets].sort() }),
+  }, "generator")
+}
+
+/** A minimal editable scene: one calibrated default camera, no authored entities. */
+export function createSpatialGeneratorSceneShell(): unknown {
+  return {
+    kind: "slopcamera.spatial-scene", schemaVersion: 1, sceneId: "scene_generated",
+    coordinates: "right-handed-y-up-meters", durationUs: 4_000_000,
+    entities: [],
+    cameras: [{ cameraId: "camera_main", name: "Main", pose: { position: [0, 3, 8], rotation: [0, 0, 0, 1] },
+      projection: { kind: "perspective", width: 960, height: 540, fx: 650, fy: 650, cx: 480, cy: 270, near: 0.1, far: 200 } }],
+    assets: [], animations: [], generators: [], overrides: [],
+  }
+}
+
+/**
+ * Applies replace-generator-output semantics to a whole scene: retained output
+ * for this generatorId is removed wholesale, the stamped entities and the new
+ * generator record are installed, and the merged document is revalidated end to
+ * end. Other generators' retained output and all authored content are preserved.
+ */
+export function mergeSpatialGeneratorOutput(scene: SpatialSceneV1 | undefined, generator: SpatialGenerator, entities: readonly SpatialEntity[], assets: readonly SpatialAssetManifest[] = []): SpatialSceneV1 {
+  const base = scene ?? (parseSpatialScene(createSpatialGeneratorSceneShell()) as SpatialSceneV1)
+  const previous = base.generators.find(record => record.generatorId === generator.generatorId)?.assets ?? []
+  if ([...assets.map(asset => asset.assetId)].sort().join("") !== [...(generator.assets ?? [])].sort().join("")) {
+    throw new SpatialSceneError("conflict", "Generator output must carry exactly the asset manifests its record declares.", "assets")
+  }
+  for (const asset of assets) {
+    if (asset.provenance.source !== "generated" && asset.provenance.source !== "derived") {
+      throw new SpatialSceneError("conflict", "Generator-owned assets require generated or derived provenance.", "assets")
+    }
+  }
+  const retired = new Set(previous)
+  const keptAssets = base.assets.filter(asset => !retired.has(asset.assetId))
+  const keptAssetIds = new Set([...keptAssets.map(asset => asset.assetId), ...assets.map(asset => asset.assetId)])
+  const colliding = assets.find(asset => base.assets.some(existing => existing.assetId === asset.assetId) && !retired.has(asset.assetId))
+  if (colliding !== undefined) throw new SpatialSceneError("conflict", `Generator asset ${colliding.assetId} collides with an existing asset.`, "assets")
+  const retained = new Set(entities.map(entity => entity.entityId))
+  const removed = new Set<string>()
+  const kept: SpatialEntity[] = []
+  for (const entity of base.entities) {
+    if (entity.origin.kind === "generated" && entity.origin.generatorId === generator.generatorId) {
+      if (!retained.has(entity.entityId)) removed.add(entity.entityId)
+      continue
+    }
+    kept.push(entity)
+  }
+  for (const override of base.overrides) {
+    if (removed.has(override.entityId)) {
+      throw new SpatialSceneError("conflict", `Regeneration removed ${override.entityId}; remove its ${override.property} override or restore the produced key.`, "overrides")
+    }
+  }
+  for (const channel of base.animations) {
+    if (removed.has(channel.targetId)) {
+      throw new SpatialSceneError("conflict", `Regeneration removed ${channel.targetId}; remove channel ${channel.channelId} or restore the produced key.`, "animations")
+    }
+  }
+  const keptIds = new Set(kept.map(entity => entity.entityId))
+  for (const entity of entities) {
+    if (keptIds.has(entity.entityId)) throw new SpatialSceneError("conflict", `Generator output collides with ${entity.entityId}.`, "entities")
+    const assetId = generatedAssetReference(entity)
+    if (assetId !== undefined && !keptAssetIds.has(assetId)) {
+      throw new SpatialSceneError("conflict", `Generator output references missing asset ${assetId}.`, "entities")
+    }
+  }
+  const generators = [...base.generators.filter(record => record.generatorId !== generator.generatorId), generator]
+  return parseSpatialScene({ ...base, assets: [...keptAssets, ...assets], entities: [...kept, ...entities], generators })
+}

package/src/spatial-scene/geometry-native.ts

@@ -0,0 +1,165 @@
+import { z } from "zod"
+import { createBoundedJsonValueSnapshot, deepFreezeJson } from "../code/json-snapshot.js"
+import { canonicalJson } from "../code/canonical-json.js"
+import { createSha256HexHasher } from "../code/sha256.js"
+import { SpatialDigestSchema } from "./contracts.js"
+import { parseSpatialValue, SpatialSceneError, spatialValueSha256 } from "./identity.js"
+import { SPATIAL_GLB_LIMITS } from "./gltf.js"
+
+/**
+ * Retained-native adapter contracts for heavy geometry operations (mesh repair,
+ * complex CSG beyond the portable hull bound, UV atlasing, decimation,
+ * hull decomposition and GLB emission). The portable layer owns only the
+ * typed request/receipt documents and their binding rules: every receipt must
+ * name its request's content-derived identity and copy its operation, engine
+ * and profile, and declared output digests are verified against real bytes
+ * before any artifact may be published into a scene. No native execution lives
+ * here — hosts run engines; this module also provides a deterministic fake
+ * adapter so tests exercise the full contract without native dependencies.
+ */
+export const SPATIAL_GEOMETRY_NATIVE_LIMITS = Object.freeze({
+  inputs: 8,
+  inputBytes: SPATIAL_GLB_LIMITS.bytes,
+  outputs: 16,
+  outputBytes: 33_554_432,
+  parametersBytes: 4_096,
+  parametersDepth: 8,
+  parametersValues: 256,
+})
+
+export const SPATIAL_GEOMETRY_NATIVE_OPERATIONS = [
+  "mesh-repair", "complex-csg", "uv-atlas", "decimation", "hull-decomposition", "glb-emission",
+] as const
+export type SpatialGeometryNativeOperation = (typeof SPATIAL_GEOMETRY_NATIVE_OPERATIONS)[number]
+
+const operation = z.enum(SPATIAL_GEOMETRY_NATIVE_OPERATIONS)
+const engine = z.strictObject({
+  engine: z.string().min(1).max(64),
+  version: z.string().min(1).max(64),
+  device: z.string().min(1).max(64).optional(),
+})
+const digestEntry = z.strictObject({ sha256: SpatialDigestSchema, bytes: z.number().int().safe().min(1).max(SPATIAL_GEOMETRY_NATIVE_LIMITS.outputBytes) })
+
+export const SpatialGeometryNativeRequestSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-geometry-native-request"),
+  schemaVersion: z.literal(1),
+  operation,
+  engine,
+  /** Closed adapter profile for this operation, e.g. slopcamera.geometry-native-csg-v1. */
+  profile: z.string().min(1).max(128),
+  /** Sorted digests of the exact input payloads the engine consumed. */
+  inputs: z.array(digestEntry).max(SPATIAL_GEOMETRY_NATIVE_LIMITS.inputs),
+  /** Bounded plain-JSON operation parameters; captured canonically. */
+  parameters: z.unknown().optional(),
+})
+export type SpatialGeometryNativeRequest = Readonly<z.infer<typeof SpatialGeometryNativeRequestSchema>>
+
+export const SpatialGeometryNativeReceiptSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-geometry-native-receipt"),
+  schemaVersion: z.literal(1),
+  requestId: z.string().regex(/^native_[a-f0-9]{32}$/u),
+  requestSha256: SpatialDigestSchema,
+  operation,
+  engine,
+  profile: z.string().min(1).max(128),
+  state: z.enum(["succeeded", "failed"]),
+  /** Sorted declared output digests; publication verifies real bytes against them. */
+  outputs: z.array(digestEntry).max(SPATIAL_GEOMETRY_NATIVE_LIMITS.outputs),
+  failure: z.strictObject({ code: z.enum(["validation", "engine", "budget", "custody"]), message: z.string().min(1).max(2_048) }).optional(),
+}).superRefine((receipt, context) => {
+  if (receipt.state === "succeeded" && receipt.failure !== undefined) context.addIssue({ code: "custom", path: ["failure"], message: "Successful receipts carry no failure." })
+  if (receipt.state === "failed" && receipt.failure === undefined) context.addIssue({ code: "custom", path: ["failure"], message: "Failed receipts require a failure reason." })
+  if (receipt.outputs.reduce((sum, output) => sum + output.bytes, 0) > SPATIAL_GEOMETRY_NATIVE_LIMITS.outputBytes) context.addIssue({ code: "custom", path: ["outputs"], message: "Receipt exceeds the output byte bound." })
+})
+export type SpatialGeometryNativeReceipt = Readonly<z.infer<typeof SpatialGeometryNativeReceiptSchema>>
+
+function nativeFail(message: string, path = "geometry-native"): never {
+  throw new SpatialSceneError("invalid-data", `slopcamera.spatial-geometry-native-v1: ${message}`, path)
+}
+
+/** Parses a foreign request: strict schema plus canonical bounded parameter capture. */
+export function parseSpatialGeometryNativeRequest(input: unknown): SpatialGeometryNativeRequest {
+  const request = parseSpatialValue(SpatialGeometryNativeRequestSchema, input, "geometry-native request")
+  if (request.inputs.length !== new Set(request.inputs.map(item => item.sha256)).size) nativeFail("Request inputs must carry distinct digests.", "request.inputs")
+  const parameters = request.parameters === undefined ? undefined
+    : createBoundedJsonValueSnapshot(request.parameters, SPATIAL_GEOMETRY_NATIVE_LIMITS.parametersBytes, "geometry-native parameters", {
+      maximumDepth: SPATIAL_GEOMETRY_NATIVE_LIMITS.parametersDepth, maximumValues: SPATIAL_GEOMETRY_NATIVE_LIMITS.parametersValues,
+    }).value
+  return deepFreezeJson({ ...request, ...(parameters === undefined ? {} : { parameters }) })
+}
+
+/** Content-derived request identity and digest; identical requests reproduce both. */
+export function spatialGeometryNativeRequestSha256(request: unknown): string {
+  return spatialValueSha256({ domain: "slopcamera.spatial-geometry-native-request.v1", request: parseSpatialGeometryNativeRequest(request) })
+}
+export function spatialGeometryNativeRequestId(request: unknown): string {
+  return `native_${spatialGeometryNativeRequestSha256(request).slice(0, 32)}`
+}
+export function spatialGeometryNativeReceiptSha256(receipt: unknown): string {
+  return spatialValueSha256({ domain: "slopcamera.spatial-geometry-native-receipt.v1", receipt: parseSpatialValue(SpatialGeometryNativeReceiptSchema, receipt, "geometry-native receipt") })
+}
+
+/**
+ * Validates that a receipt binds its exact request: operation, engine, profile,
+ * requestId and requestSha256 must match, mirroring native-admission plan/receipt
+ * reconciliation. Any mismatch is a typed rejection.
+ */
+export function validateSpatialGeometryNativeReceipt(input: { readonly request: unknown; readonly receipt: unknown }): SpatialGeometryNativeReceipt {
+  const request = parseSpatialGeometryNativeRequest(input.request)
+  const receipt = parseSpatialValue(SpatialGeometryNativeReceiptSchema, input.receipt, "geometry-native receipt")
+  if (receipt.requestSha256 !== spatialGeometryNativeRequestSha256(request) || receipt.requestId !== spatialGeometryNativeRequestId(request)) {
+    nativeFail("Receipt identity differs from the exact request it claims.", "receipt.requestSha256")
+  }
+  if (receipt.operation !== request.operation || receipt.profile !== request.profile || canonicalJson(receipt.engine) !== canonicalJson(request.engine)) {
+    nativeFail("Receipt operation, profile, or engine differs from its request.", "receipt.operation")
+  }
+  return deepFreezeJson(receipt)
+}
+
+/**
+ * Verifies declared output digests against real retained bytes BEFORE any
+ * manifest or facts document may publish them. A mismatch is a typed error.
+ */
+export function verifySpatialGeometryNativeOutputs(receipt: unknown, outputs: readonly Uint8Array[]): readonly { sha256: string; bytes: number }[] {
+  const parsed = parseSpatialValue(SpatialGeometryNativeReceiptSchema, receipt, "geometry-native receipt")
+  if (parsed.state !== "succeeded") nativeFail("Only succeeded receipts publish retained outputs.", "receipt.state")
+  const declared = parsed.outputs
+  if (outputs.length !== declared.length) nativeFail("Retained output count differs from the receipt declaration.", "receipt.outputs")
+  const verified = declared.map((output, index) => {
+    const bytes = outputs[index]!
+    if (!(bytes instanceof Uint8Array) || bytes.byteLength !== output.bytes) nativeFail(`Native output ${index} byte length differs from its receipt.`, `receipt.outputs.${index}`)
+    const hasher = createSha256HexHasher(); hasher.update(bytes); const sha256 = hasher.digestHex()
+    if (sha256 !== output.sha256) nativeFail(`Native output ${index} digest mismatch; refusing publication.`, `receipt.outputs.${index}`)
+    return { sha256, bytes: output.bytes }
+  })
+  return deepFreezeJson(verified)
+}
+
+/**
+ * Deterministic fake adapter for tests and hosts without a native engine: the
+ * output stream derives entirely from the request digest, so identical inputs
+ * always produce byte-identical artifacts and receipts.
+ */
+export function executeSpatialGeometryNativeFake(input: unknown): { readonly receipt: SpatialGeometryNativeReceipt; readonly outputs: readonly Uint8Array[] } {
+  const request = parseSpatialGeometryNativeRequest(input)
+  const requestSha256 = spatialGeometryNativeRequestSha256(request)
+  const count = request.operation === "hull-decomposition" ? 4 : 1
+  const outputs: Uint8Array[] = []
+  const declared: { sha256: string; bytes: number }[] = []
+  for (let index = 0; index < count; index++) {
+    const seed = spatialValueSha256({ domain: "slopcamera.spatial-geometry-native-output.v1", requestSha256, index })
+    const length = 256 + (Number.parseInt(seed.slice(0, 4), 16) % 256)
+    const bytes = new Uint8Array(length)
+    for (let offset = 0; offset < length; offset++) bytes[offset] = Number.parseInt(seed.slice((offset % 32) * 2, (offset % 32) * 2 + 2), 16)
+    const hasher = createSha256HexHasher(); hasher.update(bytes); const sha256 = hasher.digestHex()
+    outputs.push(bytes)
+    declared.push({ sha256, bytes: length })
+  }
+  const receipt = parseSpatialValue(SpatialGeometryNativeReceiptSchema, {
+    kind: "slopcamera.spatial-geometry-native-receipt", schemaVersion: 1,
+    requestId: spatialGeometryNativeRequestId(request), requestSha256,
+    operation: request.operation, engine: request.engine, profile: request.profile,
+    state: "succeeded", outputs: declared,
+  }, "geometry-native receipt")
+  return deepFreezeJson({ receipt, outputs: Object.freeze(outputs) })
+}