@hraness/slopcamera 3.2.8 → 3.3.2

package/src/scene-gallery.ts

@@ -0,0 +1,184 @@
+import { z } from "zod"
+
+import { createBoundedJsonValueSnapshot } from "./code/json-snapshot.js"
+import {
+  SPATIAL_SCENE_LIMITS,
+  SpatialDigestSchema,
+  SpatialPatchOperationSchema,
+  type SpatialPatchOperation,
+  type SpatialSceneV1,
+} from "./spatial-scene/contracts.js"
+import {
+  parseSpatialScene,
+  parseSpatialValue,
+  SpatialSceneError,
+  spatialSceneSha256,
+  spatialValueSha256,
+} from "./spatial-scene/identity.js"
+import {
+  applySpatialScenePatch,
+  type SpatialSceneDiffEntry,
+} from "./spatial-scene/patch.js"
+
+/**
+ * Scene-variant galleries for agent review.
+ *
+ * One authored base scene plus a bounded list of typed patch variants derives
+ * one candidate scene per variant — no generation, no paid calls. The desktop
+ * host renders each derived scene into a beauty still and composes the stills
+ * into the shared labelled contact sheet, so an agent reviews world variants
+ * the same way it reviews generated image candidates. The authored scene is
+ * never modified: every variant is a new derived document with its own digest,
+ * and promotion is an explicit authored patch afterward.
+ */
+
+export const slopcameraSceneGalleryLimits = Object.freeze({
+  variants: 16,
+  variantsBytes: 1024 * 1024,
+  idEdge: 64,
+  labelEdge: 256,
+  summaryEdge: 256,
+})
+
+const variantId = z
+  .string()
+  .min(1)
+  .max(slopcameraSceneGalleryLimits.idEdge)
+  .regex(
+    /^[a-z0-9][a-z0-9-]*$/u,
+    "Variant ids are lowercase slugs like dusk or golden-hour-2.",
+  )
+
+/**
+ * A variant patch is the versioned spatial patch document with the expected
+ * base digest optional: when omitted the planner stamps the gallery's base
+ * scene digest, when present it must match exactly.
+ */
+const SceneVariantPatchSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-scene-patch"),
+  schemaVersion: z.literal(1),
+  expectedSceneSha256: SpatialDigestSchema.optional(),
+  operations: z
+    .array(SpatialPatchOperationSchema)
+    .min(1)
+    .max(SPATIAL_SCENE_LIMITS.patchOperations),
+})
+
+const SceneGalleryVariantSchema = z.strictObject({
+  id: variantId,
+  label: z.string().min(1).max(slopcameraSceneGalleryLimits.labelEdge).optional(),
+  patch: SceneVariantPatchSchema,
+})
+
+export const SlopcameraSceneVariantsSchema = z.strictObject({
+  kind: z.literal("slopcamera.scene-variants"),
+  schemaVersion: z.literal(1),
+  variants: z
+    .array(SceneGalleryVariantSchema)
+    .min(1)
+    .max(slopcameraSceneGalleryLimits.variants),
+})
+
+export type SlopcameraSceneVariantSpec = z.infer<typeof SceneGalleryVariantSchema>
+
+/** A compact per-variant description recorded as the candidate's prompt. */
+export function summarizeSceneVariantPatch(
+  operations: readonly SpatialPatchOperation[],
+): string {
+  const parts = operations.map(operation => {
+    const target =
+      ("entityId" in operation ? operation.entityId : undefined)
+      ?? ("camera" in operation ? operation.camera.cameraId : undefined)
+      ?? ("channel" in operation ? operation.channel.channelId : undefined)
+      ?? ("asset" in operation ? operation.asset.assetId : undefined)
+      ?? ("generator" in operation ? operation.generator.generatorId : undefined)
+      ?? ("entity" in operation ? operation.entity.entityId : undefined)
+      ?? ("override" in operation ? operation.override.entityId : undefined)
+    return target === undefined ? operation.kind : `${operation.kind} ${target}`
+  })
+  const summary = parts.join("; ")
+  return summary.length <= slopcameraSceneGalleryLimits.summaryEdge
+    ? summary
+    : `${summary.slice(0, slopcameraSceneGalleryLimits.summaryEdge - 1)}…`
+}
+
+export function parseSlopcameraSceneVariants(
+  input: unknown,
+): readonly SlopcameraSceneVariantSpec[] {
+  const value = createBoundedJsonValueSnapshot(
+    input,
+    slopcameraSceneGalleryLimits.variantsBytes,
+    "scene variants",
+  ).value
+  const document = parseSpatialValue(
+    SlopcameraSceneVariantsSchema,
+    value,
+    "scene variants",
+  )
+  const ids = new Set<string>()
+  for (const variant of document.variants) {
+    if (ids.has(variant.id)) {
+      throw new SpatialSceneError(
+        "invalid-data",
+        `Duplicate scene variant id ${variant.id}.`,
+        "variants",
+      )
+    }
+    ids.add(variant.id)
+  }
+  return document.variants
+}
+
+export interface SlopcameraSceneGalleryVariant {
+  readonly index: number
+  readonly id: string
+  readonly label: string
+  readonly prompt: string
+  readonly patchSha256: string
+  readonly scene: SpatialSceneV1
+  readonly sceneSha256: string
+  readonly diff: readonly SpatialSceneDiffEntry[]
+}
+
+export interface SlopcameraSceneGalleryPlan {
+  readonly scene: SpatialSceneV1
+  readonly baseSceneSha256: string
+  readonly variants: readonly SlopcameraSceneGalleryVariant[]
+}
+
+/**
+ * Parses and applies every variant patch before returning — invalid input is
+ * rejected before the host renders anything. Each derived scene is validated
+ * again by the patch transaction itself.
+ */
+export function planSlopcameraSceneGallery(input: {
+  readonly scene: unknown
+  readonly variants: unknown
+}): SlopcameraSceneGalleryPlan {
+  const scene = parseSpatialScene(input.scene)
+  const baseSceneSha256 = spatialSceneSha256(scene)
+  const specs = parseSlopcameraSceneVariants(input.variants)
+  const variants = specs.map((spec, offset) => {
+    const expected = spec.patch.expectedSceneSha256 ?? baseSceneSha256
+    if (expected !== baseSceneSha256) {
+      throw new SpatialSceneError(
+        "conflict",
+        `Variant ${spec.id} was authored against a different scene revision.`,
+        "variants",
+      )
+    }
+    const patch = { ...spec.patch, expectedSceneSha256: expected }
+    const result = applySpatialScenePatch(scene, patch)
+    return {
+      diff: result.diff,
+      id: spec.id,
+      index: offset + 1,
+      label: spec.label ?? spec.id,
+      patchSha256: spatialValueSha256(patch),
+      prompt: summarizeSceneVariantPatch(patch.operations),
+      scene: result.scene,
+      sceneSha256: result.sceneSha256,
+    }
+  })
+  return { baseSceneSha256, scene, variants }
+}

package/src/spatial-scene/asset-admission.ts

@@ -0,0 +1,183 @@
+import { z } from "zod"
+import {
+  SPATIAL_SCENE_LIMITS,
+  SpatialAssetIdSchema,
+  SpatialAssetManifestSchema,
+  SpatialDigestSchema,
+  SpatialEntitySchema,
+  SpatialGeneratorIdSchema,
+  SpatialPatchOperationSchema,
+  SpatialPayloadSchema,
+} from "./contracts.js"
+import { SPATIAL_GLB_LIMITS, SPATIAL_GLB_PROFILE, SPATIAL_GLB_PROFILE_V1, SPATIAL_GLB_RIGGED_PROFILE } from "./gltf.js"
+import { SPATIAL_GEOMETRY_PROFILE } from "./geometry.js"
+
+/**
+ * Canonical document contracts produced by `scene asset admit` and consumed by
+ * `scene audit --asset-bounds` and the MCP `audit_scene` tool. They live in the
+ * portable layer so every surface shares one strict schema; hosts only read or
+ * write the documents.
+ */
+
+/**
+ * Affine guard bound. Node matrices stay below math.MAX_ABS_COMPONENT (1e12)
+ * and decoded vertices below 1e6, so every transformed vertex stays under
+ * ~3e18; 1e18 bounds the reachable evaluated range with margin.
+ */
+const boundsComponent = z.number().finite().min(-1e18).max(1e18)
+const boundsVector = z.tuple([boundsComponent, boundsComponent, boundsComponent])
+export const SpatialBoundsSchema = z.strictObject({ min: boundsVector, max: boundsVector })
+  .refine(value => value.min.every((component, index) => component <= value.max[index]!), "Bounds min must not exceed max.")
+export type SpatialBounds = Readonly<z.infer<typeof SpatialBoundsSchema>>
+
+/**
+ * Derived facts bound to one admitted asset payload. The document persists as a
+ * canonical JSON payload behind a sibling `metadata` manifest that depends on
+ * its subject asset, so a scene may omit it without invalidating the subject
+ * manifest under the unchanged `gltf` interpretation shape.
+ */
+const factsUnit = z.number().finite().min(0).max(1)
+/**
+ * One declared GLB material's capability row. `maps` lists present texture
+ * slots in fixed order; `emissiveLinear` records a declared emissiveFactor.
+ */
+export const SpatialAssetMaterialFactSchema = z.strictObject({
+  name: z.string().max(1_024).optional(),
+  alphaMode: z.enum(["OPAQUE", "MASK", "BLEND"]),
+  doubleSided: z.boolean(),
+  maps: z.array(z.enum(["baseColor", "metallicRoughness", "normal", "occlusion", "emissive", "clearcoat", "clearcoatRoughness", "clearcoatNormal", "transmission", "sheenColor", "sheenRoughness", "anisotropy"])).max(12),
+  textureTransforms: z.array(z.strictObject({ map: z.string().min(1).max(64), offset: z.tuple([z.number().finite(), z.number().finite()]), rotation: z.number().finite().min(-Math.PI).max(Math.PI), scale: z.tuple([z.number().finite(), z.number().finite()]) })).max(12).default([]),
+  emissiveLinear: z.tuple([factsUnit, factsUnit, factsUnit]).optional(),
+  emissiveStrength: z.number().finite().min(0).max(100_000).optional(),
+  /** PBR extension indicators: present only when the GLB declares the corresponding KHR extension on this material. */
+  clearcoat: z.strictObject({ factor: factsUnit, roughness: factsUnit }).optional(),
+  transmission: z.strictObject({ factor: factsUnit }).optional(),
+  sheen: z.strictObject({ colorLinear: z.tuple([factsUnit, factsUnit, factsUnit]), roughness: factsUnit }).optional(),
+  anisotropy: z.strictObject({ strength: z.number().finite().min(-1).max(1), rotation: z.number().finite().min(0).max(2 * Math.PI) }).optional(),
+  ior: z.number().finite().min(1).max(5).optional(),
+})
+const SpatialAssetRigFactsSchema = z.strictObject({
+  profile: z.literal(SPATIAL_GLB_RIGGED_PROFILE),
+  skins: z.array(z.strictObject({
+    name: z.string().max(1_024).optional(),
+    jointNodeIndices: z.array(z.number().int().min(0).max(SPATIAL_GLB_LIMITS.nodes - 1)).min(1).max(SPATIAL_GLB_LIMITS.jointsPerSkin),
+    inverseBindMatricesAccessor: z.number().int().min(0).max(SPATIAL_GLB_LIMITS.accessors - 1),
+  })).min(1).max(SPATIAL_GLB_LIMITS.skins),
+  morphTargets: z.array(z.array(z.array(z.strictObject({
+    name: z.string().min(1).max(1_024), hasPosition: z.boolean(), hasNormal: z.boolean(),
+  })).max(SPATIAL_GLB_LIMITS.morphTargetsPerPrimitive)).max(SPATIAL_GLB_LIMITS.primitives)).max(SPATIAL_GLB_LIMITS.meshes),
+  clips: z.array(z.strictObject({
+    name: z.string().max(1_024).optional(),
+    durationSeconds: z.number().finite().min(0).max(SPATIAL_GLB_LIMITS.durationSeconds),
+    channels: z.array(z.strictObject({
+      nodeIndex: z.number().int().min(0).max(SPATIAL_GLB_LIMITS.nodes - 1),
+      path: z.enum(["translation", "rotation", "scale", "weights"]),
+    })).max(SPATIAL_GLB_LIMITS.channels),
+  })).max(SPATIAL_GLB_LIMITS.clips),
+})
+const meterBound = z.number().finite().min(0).max(1_000_000)
+const lodCoordinate = z.number().finite().min(-1e6).max(1e6)
+const lodVector = z.tuple([lodCoordinate, lodCoordinate, lodCoordinate])
+/** One deterministic LOD level: an alternate retained GLB payload plus its selection rule. */
+export const SpatialAssetLodSchema = z.strictObject({
+  level: z.number().int().min(0).max(7),
+  /** Asset id of the retained payload for this level (level 0 is the facts subject). */
+  assetId: SpatialAssetIdSchema,
+  sha256: SpatialDigestSchema,
+  /** Selection rule: pick the greatest level whose switch distance is met. */
+  switchDistanceM: meterBound,
+})
+export type SpatialAssetLod = Readonly<z.infer<typeof SpatialAssetLodSchema>>
+
+/** Bounded collision proxies in the subject's model space; hulls reference a retained native artifact. */
+export const SpatialCollisionProxySchema = z.discriminatedUnion("kind", [
+  z.strictObject({ kind: z.literal("box"), center: lodVector, halfExtents: z.tuple([meterBound, meterBound, meterBound]).refine(v => v.every(c => c > 0), "Box half extents must be positive.") }),
+  z.strictObject({ kind: z.literal("sphere"), center: lodVector, radius: meterBound.refine(v => v > 0, "Sphere radius must be positive.") }),
+  z.strictObject({ kind: z.literal("capsule"), center: lodVector, axis: z.enum(["x", "y", "z"]), radius: meterBound.refine(v => v > 0, "Capsule radius must be positive."), halfLength: meterBound }),
+  z.strictObject({ kind: z.literal("hull-hull"), artifactSha256: SpatialDigestSchema }),
+])
+export type SpatialCollisionProxy = Readonly<z.infer<typeof SpatialCollisionProxySchema>>
+
+/** Binding to one verified retained-native exchange: request and receipt digests plus emitted outputs. */
+export const SpatialRetainedArtifactSchema = z.strictObject({
+  operation: z.enum(["mesh-repair", "complex-csg", "uv-atlas", "decimation", "hull-decomposition", "glb-emission"]),
+  requestSha256: SpatialDigestSchema,
+  receiptSha256: SpatialDigestSchema,
+  outputs: z.array(z.strictObject({ sha256: SpatialDigestSchema, bytes: z.number().int().safe().min(1).max(SPATIAL_GLB_LIMITS.bytes) })).min(1).max(16),
+})
+export type SpatialRetainedArtifact = Readonly<z.infer<typeof SpatialRetainedArtifactSchema>>
+
+/** Facts for a parametric-geometry subject: generator identity, spec/parameter digests, LOD set and collision proxies. */
+export const SpatialAssetGeneratorFactsSchema = z.strictObject({
+  generatorId: SpatialGeneratorIdSchema,
+  /** Parametric generator kind (wall, stairs, arch, …) as declared by the spec. */
+  parametricKind: z.string().min(1).max(64),
+  /** Canonical digest of the bounded parametric spec document. */
+  specSha256: SpatialDigestSchema,
+  /** Digest of the declared generator parameters (matches the generator record). */
+  parametersSha256: SpatialDigestSchema,
+  /** Sorted LOD set; level 0 must be present and is the facts subject. */
+  lods: z.array(SpatialAssetLodSchema).min(1).max(8),
+  /** Model-space collision proxies consumed by audits and hosts. */
+  collision: z.array(SpatialCollisionProxySchema).max(16),
+  /** Verified retained-native exchanges whose outputs this subject binds. */
+  retainedArtifacts: z.array(SpatialRetainedArtifactSchema).max(8).optional(),
+})
+export type SpatialAssetGeneratorFacts = Readonly<z.infer<typeof SpatialAssetGeneratorFactsSchema>>
+
+export const SpatialAssetFactsV1Schema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-asset-facts"), schemaVersion: z.literal(1),
+  subject: SpatialPayloadSchema,
+  subjectManifestSha256: SpatialDigestSchema,
+  profile: z.enum([SPATIAL_GLB_PROFILE, SPATIAL_GLB_PROFILE_V1, SPATIAL_GLB_RIGGED_PROFILE, SPATIAL_GEOMETRY_PROFILE]),
+  nodeCount: z.number().int().min(1).max(SPATIAL_GLB_LIMITS.nodes),
+  clipDurationsSeconds: z.array(z.number().finite().min(0).max(SPATIAL_GLB_LIMITS.durationSeconds)).max(SPATIAL_GLB_LIMITS.clips),
+  bounds: z.strictObject({ modelSpace: SpatialBoundsSchema, sceneSpace: SpatialBoundsSchema }),
+  /** Present on newly admitted assets; absent facts predate the material-facts extension. */
+  materials: z.array(SpatialAssetMaterialFactSchema).max(SPATIAL_GLB_LIMITS.materials).optional(),
+  /** Exact skeleton, morph and channel facts for the additive rigged profile. */
+  rig: SpatialAssetRigFactsSchema.optional(),
+  /** Generator identity, LOD set, collision proxies and retained artifacts for parametric subjects. */
+  generator: SpatialAssetGeneratorFactsSchema.optional(),
+}).superRefine((facts, context) => {
+  if ((facts.profile === SPATIAL_GLB_RIGGED_PROFILE) !== (facts.rig !== undefined)) context.addIssue({ code: "custom", path: ["rig"], message: "Rig facts must be present exactly for the rigged GLB profile." })
+  if ((facts.profile === SPATIAL_GEOMETRY_PROFILE) !== (facts.generator !== undefined)) context.addIssue({ code: "custom", path: ["generator"], message: "Generator facts must be present exactly for the parametric geometry profile." })
+  if (facts.generator !== undefined) {
+    const levels = new Set(facts.generator.lods.map(lod => lod.level))
+    if (levels.size !== facts.generator.lods.length || !levels.has(0)) context.addIssue({ code: "custom", path: ["generator", "lods"], message: "LOD levels must be unique and include level 0." })
+    const distances = facts.generator.lods.map(lod => lod.switchDistanceM)
+    if (distances.some((value, index) => index > 0 && value <= distances[index - 1]!)) context.addIssue({ code: "custom", path: ["generator", "lods"], message: "LOD switch distances must strictly increase." })
+    const hulls = facts.generator.collision.filter(proxy => proxy.kind === "hull-hull")
+    for (const hull of hulls) {
+      const bound = facts.generator.retainedArtifacts?.some(artifact => artifact.outputs.some(output => output.sha256 === hull.artifactSha256)) ?? false
+      if (!bound) context.addIssue({ code: "custom", path: ["generator", "collision"], message: "Hull-hull proxies must reference a retained artifact output." })
+    }
+  }
+})
+export type SpatialAssetFactsV1 = Readonly<z.infer<typeof SpatialAssetFactsV1Schema>>
+
+export const SpatialPublishedArtifactSchema = z.strictObject({
+  path: z.string().min(1).max(1_024),
+  sha256: SpatialDigestSchema,
+  bytes: z.number().int().safe().min(1).max(SPATIAL_GLB_LIMITS.bytes),
+  disposition: z.enum(["created", "exists"]),
+})
+export type SpatialPublishedArtifact = Readonly<z.infer<typeof SpatialPublishedArtifactSchema>>
+
+/**
+ * The deterministic `scene asset admit` output document. Artifact paths are
+ * relative to the directory containing this document; `operations` apply in
+ * order inside one `SpatialScenePatchV1` alongside the caller's expected scene
+ * digest.
+ */
+export const SpatialAssetAdmissionV1Schema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-asset-admission"), schemaVersion: z.literal(1),
+  manifest: SpatialAssetManifestSchema,
+  factsManifest: SpatialAssetManifestSchema,
+  facts: SpatialAssetFactsV1Schema,
+  bounds: z.strictObject({ modelSpace: SpatialBoundsSchema, sceneSpace: SpatialBoundsSchema }),
+  entity: SpatialEntitySchema,
+  artifacts: z.strictObject({ payload: SpatialPublishedArtifactSchema, facts: SpatialPublishedArtifactSchema }),
+  operations: z.array(SpatialPatchOperationSchema).min(2).max(SPATIAL_SCENE_LIMITS.patchOperations),
+})
+export type SpatialAssetAdmissionV1 = Readonly<z.infer<typeof SpatialAssetAdmissionV1Schema>>