@hraness/slopcamera 3.2.8 → 3.3.2

package/src/spatial-scene/simulation-bake.ts

@@ -0,0 +1,206 @@
+import { z } from "zod"
+
+import { canonicalJson } from "../code/canonical-json.js"
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import {
+  SpatialDigestSchema,
+  SpatialEntityIdSchema,
+  SpatialQuaternionSchema,
+  SpatialTimeUsSchema,
+  SpatialVec3Schema,
+} from "./contracts.js"
+import { parseSpatialValue, SpatialSceneError, spatialValueSha256 } from "./identity.js"
+import {
+  SPATIAL_SIMULATION_LIMITS,
+  createSpatialSimulationBakeReceipt,
+  parseSpatialSimulationPlan,
+  spatialSimulationPlanSha256,
+  type SpatialSimulationBakeReceipt,
+} from "./simulation.js"
+
+/**
+ * Deterministic fixed-step reference bake for `slopcamera-rigid-body-reference-v1`.
+ * Semi-implicit Euler with analytic forces only — gravity, declared springs,
+ * and fixed-constraint projection — plus free rigid rotation from the initial
+ * angular velocity. The integrator is deliberately narrow: undeclared world
+ * colliders, contact, and hinge constraints are outside this qualification and
+ * reject rather than approximate. All arithmetic is IEEE-754 binary64 in
+ * declared plan order, so identical plans produce identical bytes everywhere.
+ * The native secondary-motion profile stays fail-closed here.
+ */
+
+export const SPATIAL_SIMULATION_BAKE_LIMITS = Object.freeze({
+  channels: SPATIAL_SIMULATION_LIMITS.bodies,
+  keysPerChannel: SPATIAL_SIMULATION_LIMITS.steps,
+})
+
+const transformKeySchema = z.strictObject({
+  orientation: SpatialQuaternionSchema,
+  position: SpatialVec3Schema,
+  timeUs: SpatialTimeUsSchema,
+})
+
+export const SpatialSimulationBakeChannelSchema = z.strictObject({
+  entityId: SpatialEntityIdSchema,
+  keys: z.array(transformKeySchema).min(1).max(SPATIAL_SIMULATION_BAKE_LIMITS.keysPerChannel),
+  kind: z.literal("transform"),
+})
+
+export const SpatialSimulationBakeDocumentSchema = z.strictObject({
+  cacheId: z.string().min(1).max(128).regex(/^cache_[a-z0-9][a-z0-9_-]*$/u),
+  channels: z.array(SpatialSimulationBakeChannelSchema).min(1).max(SPATIAL_SIMULATION_BAKE_LIMITS.channels),
+  engineProfile: z.literal("slopcamera-rigid-body-reference-v1"),
+  kind: z.literal("slopcamera.spatial-simulation-bake"),
+  planSha256: SpatialDigestSchema,
+  schemaVersion: z.literal(1),
+  stepCount: z.number().int().min(1).max(SPATIAL_SIMULATION_LIMITS.steps),
+  timeStepUs: SpatialTimeUsSchema.min(1).max(1_000_000),
+}).superRefine((document, context) => {
+  const entityIds = new Set<string>()
+  for (const [index, channel] of document.channels.entries()) {
+    if (entityIds.has(channel.entityId)) context.addIssue({ code: "custom", path: ["channels", index, "entityId"], message: `Duplicate bake channel for ${channel.entityId}.` })
+    entityIds.add(channel.entityId)
+    let previous = -1
+    for (const [keyIndex, key] of channel.keys.entries()) {
+      if (key.timeUs <= previous) context.addIssue({ code: "custom", path: ["channels", index, "keys", keyIndex, "timeUs"], message: "Bake keys must be strictly ordered by timeUs." })
+      previous = key.timeUs
+    }
+    if (channel.keys.length !== document.stepCount) {
+      context.addIssue({ code: "custom", path: ["channels", index, "keys"], message: `Bake channel must carry exactly ${document.stepCount} ordered keys.` })
+    }
+  }
+})
+
+export type SpatialSimulationBakeDocument = Readonly<z.infer<typeof SpatialSimulationBakeDocumentSchema>>
+
+export function parseSpatialSimulationBakeDocument(input: unknown): SpatialSimulationBakeDocument {
+  return deepFreezeJson(parseSpatialValue(SpatialSimulationBakeDocumentSchema, input, "simulation bake"))
+}
+
+export function spatialSimulationBakeSha256(document: SpatialSimulationBakeDocument): string {
+  return spatialValueSha256(document)
+}
+
+const round = (value: number): number => (Object.is(value, -0) ? 0 : value)
+
+export interface SpatialSimulationBakeResult {
+  readonly document: SpatialSimulationBakeDocument
+  readonly receipt: SpatialSimulationBakeReceipt
+}
+
+/**
+ * Executes one admitted plan and returns the canonical bake document plus its
+ * reconciled receipt. Only the reference profile executes; every other engine
+ * identity, including the native secondary-motion profile, rejects here even
+ * when the plan parses.
+ */
+export function bakeSpatialSimulation(planInput: unknown): SpatialSimulationBakeResult {
+  const plan = parseSpatialSimulationPlan(planInput)
+  if (plan.engine.profile !== "slopcamera-rigid-body-reference-v1" || plan.simulationKind !== "rigid-body") {
+    throw new SpatialSceneError("invalid-data", `Simulation engine ${plan.engine.profile} is not qualified for portable deterministic baking.`, "simulation-bake")
+  }
+  for (const constraint of plan.constraints) {
+    if (constraint.kind === "hinge") {
+      throw new SpatialSceneError("invalid-data", `Hinge constraint ${constraint.constraintId} is not qualified in the reference integrator.`, "simulation-bake")
+    }
+  }
+  const dt = plan.timeStepUs / 1_000_000
+  interface BodyState { position: [number, number, number]; velocity: [number, number, number]; orientation: [number, number, number, number]; angular: [number, number, number] }
+  const states: BodyState[] = plan.bodies.map(body => ({
+    position: [...body.initialPosition],
+    velocity: [...body.initialVelocity],
+    orientation: [...body.initialOrientation],
+    angular: [...body.initialAngularVelocity],
+  }))
+  const indexByBodyId = new Map(plan.bodies.map((body, index) => [body.id, index]))
+  const springs = plan.constraints.filter((constraint): constraint is Extract<typeof constraint, { kind: "spring" }> => constraint.kind === "spring")
+    .map(constraint => {
+      const a = states[indexByBodyId.get(constraint.bodyA)!]!, b = states[indexByBodyId.get(constraint.bodyB)!]!
+      const dx = b.position[0] - a.position[0], dy = b.position[1] - a.position[1], dz = b.position[2] - a.position[2]
+      return { a: indexByBodyId.get(constraint.bodyA)!, b: indexByBodyId.get(constraint.bodyB)!, damping: constraint.damping, restLength: Math.sqrt(dx * dx + dy * dy + dz * dz), stiffness: constraint.stiffness }
+    })
+  const fixed = plan.constraints.filter((constraint): constraint is Extract<typeof constraint, { kind: "fixed" }> => constraint.kind === "fixed")
+    .map(constraint => {
+      const a = states[indexByBodyId.get(constraint.bodyA)!]!, b = states[indexByBodyId.get(constraint.bodyB)!]!
+      return { a: indexByBodyId.get(constraint.bodyA)!, b: indexByBodyId.get(constraint.bodyB)!,
+        offset: [b.position[0] - a.position[0], b.position[1] - a.position[1], b.position[2] - a.position[2]] as const }
+    })
+  const keys: { orientation: [number, number, number, number]; position: [number, number, number]; timeUs: number }[][] = plan.bodies.map(() => [])
+  for (let step = 0; step < plan.stepCount; step++) {
+    const forces = plan.bodies.map(body => [body.pinned || body.mass <= 0 ? 0 : plan.gravity[0] * body.mass,
+      body.pinned || body.mass <= 0 ? 0 : plan.gravity[1] * body.mass,
+      body.pinned || body.mass <= 0 ? 0 : plan.gravity[2] * body.mass] as [number, number, number])
+    for (const spring of springs) {
+      const a = states[spring.a]!, b = states[spring.b]!
+      const dx = b.position[0] - a.position[0], dy = b.position[1] - a.position[1], dz = b.position[2] - a.position[2]
+      const distance = Math.sqrt(dx * dx + dy * dy + dz * dz)
+      const nx = distance > 0 ? dx / distance : 0, ny = distance > 0 ? dy / distance : 0, nz = distance > 0 ? dz / distance : 0
+      const stretch = distance - spring.restLength
+      const relative = (b.velocity[0] - a.velocity[0]) * nx + (b.velocity[1] - a.velocity[1]) * ny + (b.velocity[2] - a.velocity[2]) * nz
+      const magnitude = spring.stiffness * stretch + spring.damping * relative
+      const fa = forces[spring.a]!, fb = forces[spring.b]!
+      fa[0] += magnitude * nx; fa[1] += magnitude * ny; fa[2] += magnitude * nz
+      fb[0] -= magnitude * nx; fb[1] -= magnitude * ny; fb[2] -= magnitude * nz
+    }
+    for (const [index, body] of plan.bodies.entries()) {
+      if (body.pinned || body.mass <= 0) continue
+      const state = states[index]!, force = forces[index]!
+      state.velocity[0] += force[0] / body.mass * dt
+      state.velocity[1] += force[1] / body.mass * dt
+      state.velocity[2] += force[2] / body.mass * dt
+      state.position[0] += state.velocity[0] * dt
+      state.position[1] += state.velocity[1] * dt
+      state.position[2] += state.velocity[2] * dt
+      const [wx, wy, wz] = state.angular
+      if (wx !== 0 || wy !== 0 || wz !== 0) {
+        const [qx, qy, qz, qw] = state.orientation
+        const hx = 0.5 * dt * (wx * qw + wy * qz - wz * qy)
+        const hy = 0.5 * dt * (wy * qw + wz * qx - wx * qz)
+        const hz = 0.5 * dt * (wz * qw + wx * qy - wy * qx)
+        const hw = 0.5 * dt * (-wx * qx - wy * qy - wz * qz)
+        const nx = qx + hx, ny = qy + hy, nz = qz + hz, nw = qw + hw
+        const length = Math.sqrt(nx * nx + ny * ny + nz * nz + nw * nw)
+        state.orientation = [nx / length, ny / length, nz / length, nw / length]
+      }
+    }
+    for (const constraint of fixed) {
+      const a = states[constraint.a]!, b = states[constraint.b]!
+      b.position[0] = a.position[0] + constraint.offset[0]
+      b.position[1] = a.position[1] + constraint.offset[1]
+      b.position[2] = a.position[2] + constraint.offset[2]
+      b.velocity[0] = a.velocity[0]; b.velocity[1] = a.velocity[1]; b.velocity[2] = a.velocity[2]
+    }
+    const timeUs = step * plan.timeStepUs
+    for (const [index, state] of states.entries()) {
+      keys[index]!.push({ orientation: [round(state.orientation[0]), round(state.orientation[1]), round(state.orientation[2]), round(state.orientation[3])],
+        position: [round(state.position[0]), round(state.position[1]), round(state.position[2])], timeUs })
+    }
+  }
+  const document = parseSpatialSimulationBakeDocument({
+    cacheId: plan.cacheId,
+    channels: plan.bodies.map((body, index) => ({ entityId: body.entityId, keys: keys[index]!, kind: "transform" })),
+    engineProfile: "slopcamera-rigid-body-reference-v1",
+    kind: "slopcamera.spatial-simulation-bake",
+    planSha256: spatialSimulationPlanSha256(plan),
+    schemaVersion: 1,
+    stepCount: plan.stepCount,
+    timeStepUs: plan.timeStepUs,
+  })
+  const bytes = new TextEncoder().encode(`${canonicalJson(document)}\n`).byteLength
+  if (bytes > plan.maximumOutputBytes) {
+    throw new SpatialSceneError("invalid-data", `Simulation bake output (${bytes} bytes) exceeds the plan output-byte budget (${plan.maximumOutputBytes}).`, "simulation-bake")
+  }
+  const receipt = createSpatialSimulationBakeReceipt({
+    cacheId: plan.cacheId,
+    engine: plan.engine,
+    kind: "slopcamera.spatial-simulation-bake-receipt",
+    output: { animationSha256: spatialSimulationBakeSha256(document), bytes, channelCount: document.channels.length, keyCount: document.channels.reduce((sum, channel) => sum + channel.keys.length, 0) },
+    planSha256: spatialSimulationPlanSha256(plan),
+    schemaVersion: 1,
+    seed: plan.seed,
+    sourceDigest: plan.sourceDigest,
+    stepCount: plan.stepCount,
+    timeStepUs: plan.timeStepUs,
+  })
+  return { document, receipt }
+}

package/src/spatial-scene/simulation.ts

@@ -0,0 +1,187 @@
+import { z } from "zod"
+
+import { canonicalJsonSha256 } from "../code/canonical-json.js"
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import {
+  SpatialDigestSchema,
+  SpatialEntityIdSchema,
+  SpatialQuaternionSchema,
+  SpatialTimeUsSchema,
+  SpatialVec3Schema,
+} from "./contracts.js"
+import { parseSpatialValue, SpatialSceneError, spatialValueSha256 } from "./identity.js"
+
+/**
+ * Deterministic fixed-step physics and secondary-motion bakes.
+ * No live mutable physics — these are cache-bound, authored plans that emit
+ * ordinary deterministic animation curves for renderer lowering and audit.
+ */
+
+export const SPATIAL_SIMULATION_LIMITS = Object.freeze({
+  bodies: 256,
+  constraints: 256,
+  durationUs: 3_600_000_000,
+  outputBytes: 1_000_000_000,
+  steps: 100_000,
+  substeps: 128,
+})
+
+const positiveDimension = z.number().finite().positive().max(1_000_000)
+const unit = z.number().finite().min(0).max(1)
+const bodyId = z.string().min(1).max(64).regex(/^[a-z][a-z0-9_-]*$/u)
+const constraintId = z.string().min(1).max(64).regex(/^[a-z][a-z0-9_-]*$/u)
+
+export const SpatialSimulationEngineSchema = z.strictObject({
+  identitySha256: SpatialDigestSchema,
+  profile: z.enum(["slopcamera-rigid-body-reference-v1", "slopcamera-native-secondary-motion-v1"]),
+})
+
+export const SpatialRigidBodySchema = z.strictObject({
+  entityId: SpatialEntityIdSchema,
+  friction: unit,
+  id: bodyId,
+  initialAngularVelocity: SpatialVec3Schema,
+  initialOrientation: SpatialQuaternionSchema,
+  initialPosition: SpatialVec3Schema,
+  initialVelocity: SpatialVec3Schema,
+  mass: z.number().finite().min(0).max(1_000_000_000),
+  pinned: z.boolean().default(false),
+  restitution: unit,
+  shape: z.discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("sphere"), radius: positiveDimension }),
+    z.strictObject({ kind: z.literal("box"), size: z.tuple([positiveDimension, positiveDimension, positiveDimension]) }),
+    z.strictObject({ height: positiveDimension, kind: z.literal("capsule"), radius: positiveDimension }),
+  ]),
+}).superRefine((body, context) => {
+  if (!body.pinned && body.mass <= 0) {
+    context.addIssue({ code: "custom", path: ["mass"], message: "Unpinned rigid bodies require positive mass." })
+  }
+})
+
+const constraintBase = {
+  bodyA: bodyId,
+  bodyB: bodyId,
+  constraintId,
+}
+
+export const SpatialConstraintSchema = z.discriminatedUnion("kind", [
+  z.strictObject({ ...constraintBase, axis: SpatialVec3Schema, kind: z.literal("hinge"), limits: z.tuple([z.number().finite(), z.number().finite()]).optional() }),
+  z.strictObject({ ...constraintBase, damping: z.number().finite().min(0).max(1_000_000), kind: z.literal("spring"), stiffness: positiveDimension }),
+  z.strictObject({ ...constraintBase, kind: z.literal("fixed"), localA: SpatialVec3Schema, localB: SpatialVec3Schema }),
+])
+
+export const SpatialSimulationPlanSchema = z.strictObject({
+  bodies: z.array(SpatialRigidBodySchema).min(1).max(SPATIAL_SIMULATION_LIMITS.bodies),
+  cacheId: z.string().min(1).max(128).regex(/^cache_[a-z0-9][a-z0-9_-]*$/u),
+  constraints: z.array(SpatialConstraintSchema).max(SPATIAL_SIMULATION_LIMITS.constraints),
+  engine: SpatialSimulationEngineSchema,
+  entityId: SpatialEntityIdSchema,
+  gravity: SpatialVec3Schema,
+  kind: z.literal("slopcamera.spatial-simulation-plan"),
+  maxSubsteps: z.number().int().min(1).max(SPATIAL_SIMULATION_LIMITS.substeps),
+  maximumOutputBytes: z.number().int().safe().positive().max(SPATIAL_SIMULATION_LIMITS.outputBytes).default(SPATIAL_SIMULATION_LIMITS.outputBytes),
+  schemaVersion: z.literal(1),
+  seed: z.number().int().min(0).max(2_147_483_647),
+  simulationKind: z.enum(["rigid-body", "secondary-motion"]).default("rigid-body"),
+  sourceDigest: SpatialDigestSchema,
+  stepCount: z.number().int().min(1).max(SPATIAL_SIMULATION_LIMITS.steps),
+  timeStepUs: SpatialTimeUsSchema.min(1).max(1_000_000),
+}).superRefine((plan, context) => {
+  if ((plan.simulationKind === "rigid-body" && plan.engine.profile !== "slopcamera-rigid-body-reference-v1")
+    || (plan.simulationKind === "secondary-motion" && plan.engine.profile !== "slopcamera-native-secondary-motion-v1")) {
+    context.addIssue({ code: "custom", path: ["engine", "profile"], message: "Simulation kind must match its closed engine profile." })
+  }
+  if (plan.timeStepUs * plan.stepCount > SPATIAL_SIMULATION_LIMITS.durationUs) {
+    context.addIssue({ code: "custom", path: ["stepCount"], message: "Simulation duration exceeds one hour." })
+  }
+  const bodyIds = new Set<string>()
+  const entityIds = new Set<string>()
+  for (const [index, body] of plan.bodies.entries()) {
+    if (bodyIds.has(body.id)) context.addIssue({ code: "custom", path: ["bodies", index, "id"], message: `Duplicate rigid-body id ${body.id}.` })
+    if (entityIds.has(body.entityId)) context.addIssue({ code: "custom", path: ["bodies", index, "entityId"], message: `Entity ${body.entityId} has more than one rigid body.` })
+    bodyIds.add(body.id)
+    entityIds.add(body.entityId)
+  }
+  const constraintIds = new Set<string>()
+  for (const [index, constraint] of plan.constraints.entries()) {
+    if (constraintIds.has(constraint.constraintId)) context.addIssue({ code: "custom", path: ["constraints", index, "constraintId"], message: `Duplicate constraint id ${constraint.constraintId}.` })
+    constraintIds.add(constraint.constraintId)
+    const missingBodies = [constraint.bodyA, constraint.bodyB].filter(id => !bodyIds.has(id))
+    if (missingBodies.length > 0) {
+      context.addIssue({ code: "custom", path: ["constraints", index], message: `Constraint ${constraint.constraintId} references unknown body ${missingBodies.join(", ")}.` })
+    }
+    if (constraint.bodyA === constraint.bodyB) {
+      context.addIssue({ code: "custom", path: ["constraints", index], message: `Constraint ${constraint.constraintId} cannot connect a body to itself.` })
+    }
+    if (constraint.kind === "hinge") {
+      if (constraint.axis.every(value => value === 0)) context.addIssue({ code: "custom", path: ["constraints", index, "axis"], message: "Hinge axes must be nonzero." })
+      if (constraint.limits !== undefined && constraint.limits[1] < constraint.limits[0]) context.addIssue({ code: "custom", path: ["constraints", index, "limits"], message: "Hinge limits must be ordered." })
+    }
+  }
+  const estimatedBytes = plan.bodies.length * plan.stepCount * 10 * Float64Array.BYTES_PER_ELEMENT
+  if (estimatedBytes > plan.maximumOutputBytes) {
+    context.addIssue({ code: "custom", path: ["maximumOutputBytes"], message: `Estimated ordinary-animation bytes (${estimatedBytes}) exceed maximumOutputBytes (${plan.maximumOutputBytes}).` })
+  }
+})
+
+const simulationBakeReceiptBodySchema = z.strictObject({
+  cacheId: z.string().min(1).max(128).regex(/^cache_[a-z0-9][a-z0-9_-]*$/u),
+  engine: SpatialSimulationEngineSchema,
+  kind: z.literal("slopcamera.spatial-simulation-bake-receipt"),
+  output: z.strictObject({
+    animationSha256: SpatialDigestSchema,
+    bytes: z.number().int().safe().positive().max(SPATIAL_SIMULATION_LIMITS.outputBytes),
+    channelCount: z.number().int().min(1).max(SPATIAL_SIMULATION_LIMITS.bodies * 2),
+    keyCount: z.number().int().min(1).max(SPATIAL_SIMULATION_LIMITS.bodies * SPATIAL_SIMULATION_LIMITS.steps * 2),
+  }),
+  planSha256: SpatialDigestSchema,
+  schemaVersion: z.literal(1),
+  seed: z.number().int().min(0).max(2_147_483_647),
+  sourceDigest: SpatialDigestSchema,
+  stepCount: z.number().int().min(1).max(SPATIAL_SIMULATION_LIMITS.steps),
+  timeStepUs: SpatialTimeUsSchema.min(1).max(1_000_000),
+})
+
+export const SpatialSimulationBakeReceiptSchema = simulationBakeReceiptBodySchema.extend({
+  receiptSha256: SpatialDigestSchema,
+})
+
+export type SpatialSimulationPlan = Readonly<z.infer<typeof SpatialSimulationPlanSchema>>
+export type SpatialSimulationBakeReceipt = Readonly<z.infer<typeof SpatialSimulationBakeReceiptSchema>>
+
+export function parseSpatialSimulationPlan(input: unknown): SpatialSimulationPlan {
+  return deepFreezeJson(parseSpatialValue(SpatialSimulationPlanSchema, input, "simulation plan"))
+}
+
+export function spatialSimulationPlanSha256(plan: SpatialSimulationPlan): string {
+  return spatialValueSha256(plan)
+}
+
+export function createSpatialSimulationBakeReceipt(input: z.input<typeof simulationBakeReceiptBodySchema>): SpatialSimulationBakeReceipt {
+  const body = simulationBakeReceiptBodySchema.parse(input)
+  return deepFreezeJson(SpatialSimulationBakeReceiptSchema.parse({ ...body, receiptSha256: canonicalJsonSha256(body) }))
+}
+
+export function parseSpatialSimulationBakeReceipt(input: unknown): SpatialSimulationBakeReceipt {
+  const receipt = parseSpatialValue(SpatialSimulationBakeReceiptSchema, input, "simulation bake receipt")
+  const { receiptSha256, ...body } = receipt
+  if (canonicalJsonSha256(body) !== receiptSha256) {
+    throw new SpatialSceneError("conflict", "Simulation bake receipt digest does not match its body.", "simulation-bake")
+  }
+  return deepFreezeJson(receipt)
+}
+
+export function reconcileSpatialSimulationBakeReceipt(planInput: unknown, receiptInput: unknown): SpatialSimulationBakeReceipt {
+  const plan = parseSpatialSimulationPlan(planInput)
+  const receipt = parseSpatialSimulationBakeReceipt(receiptInput)
+  const planSha256 = spatialSimulationPlanSha256(plan)
+  if (receipt.planSha256 !== planSha256 || receipt.cacheId !== plan.cacheId || receipt.sourceDigest !== plan.sourceDigest
+    || receipt.engine.profile !== plan.engine.profile || receipt.engine.identitySha256 !== plan.engine.identitySha256
+    || receipt.seed !== plan.seed || receipt.stepCount !== plan.stepCount || receipt.timeStepUs !== plan.timeStepUs) {
+    throw new SpatialSceneError("conflict", "Simulation bake receipt is stale or belongs to a different plan, cache, source, engine, seed, or clock.", "simulation-bake")
+  }
+  if (receipt.output.bytes > plan.maximumOutputBytes) {
+    throw new SpatialSceneError("invalid-data", "Simulation bake output exceeds the plan output-byte budget.", "simulation-bake")
+  }
+  return deepFreezeJson(receipt)
+}