@hraness/slopcamera 3.2.7 → 3.3.1

package/src/spatial-scene/behavior-stdlib.ts

@@ -0,0 +1,323 @@
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import { behaviorOrganismSha256, type SpatialBehaviorOrganism } from "./behavior.js"
+
+/**
+ * Standard-library organisms that compose the closed behavior-fn catalog
+ * into common character-behavior patterns. Each organism is a documented
+ * manifest that agents embed in `slopcamera.spatial-behavior` documents;
+ * seed convention auto-binds `behavior.seed` at bake so seeded kernels
+ * produce deterministic diversity across gallery variants.
+ *
+ * The four organisms:
+ * - `locomotionFsm` — state-machine locomotion (idle/walk/run/etc.) over
+ *   a tick window with seeded chance guards and configurable min-dwell.
+ * - `expressionLayer` — blink/gaze/mood autonomous expression over ticks.
+ * - `interactSequence` — linear phase sequencer for pickup/grasp/release
+ *   interactions with emit-on-entry events.
+ * - `combinedBehavior` — top-level composition of the three sub-behaviors
+ *   via pairwise append into one emitted trace.
+ *
+ * Each follows the `repeat`+`carry`+`window.advance` accumulation pattern:
+ * a sub-organism ticks one kernel over the head chunk of a carried window,
+ * appends fresh emissions to a carried accumulator, and advances the window
+ * until `done` — all within ALGAL's 16-round `maxRounds` bound.
+ */
+
+// --------------------------------------------------- shared sub-organisms ---
+
+/**
+ * Build one repeat-round sub-organism: advance the carried window, tick the
+ * kernel over the head chunk, append fresh emissions to the carried accumulator.
+ *
+ * The kernel's spec (machine/spec) is a non-carried pass-through; state and
+ * acc are carried outputs→inputs; the window advances via `rest`→`win`.
+ */
+interface AccTickPorts {
+  readonly spec: string
+  readonly state: string
+  readonly window: string
+  readonly next: string
+  readonly emitted: string
+}
+
+const makeAccTickOrganism = (name: string, kernelFn: string, ports: AccTickPorts): SpatialBehaviorOrganism => {
+  const inputOutputs: Record<string, { type: "json" }> = {
+    [ports.state]: { type: "json" },
+    acc: { type: "json" },
+    win: { type: "json" },
+    [ports.spec]: { type: "json" },
+    step: { type: "json" },
+  }
+  return deepFreezeJson({
+  contract: "morphogen.organism.v1" as const,
+  key: `organism:acc-tick-${name}`,
+  name: `Acc tick ${name}`,
+  cells: [
+    { id: "in", kind: "input" as const, outputs: inputOutputs },
+    { id: "adv", kind: "fn" as const, fn: "window.advance.v1" },
+    { id: "tick", kind: "fn" as const, fn: kernelFn },
+    { id: "ap", kind: "fn" as const, fn: "emitted.append.v1" },
+  ],
+  edges: [
+    { from: { cell: "in", port: "win" }, to: { cell: "adv", port: "window" } },
+    { from: { cell: "in", port: "step" }, to: { cell: "adv", port: "step" } },
+    { from: { cell: "adv", port: "head" }, to: { cell: "tick", port: ports.window } },
+    { from: { cell: "in", port: ports.spec }, to: { cell: "tick", port: ports.spec } },
+    { from: { cell: "in", port: ports.state }, to: { cell: "tick", port: ports.state } },
+    { from: { cell: "in", port: "acc" }, to: { cell: "ap", port: "prior" } },
+    { from: { cell: "tick", port: ports.emitted }, to: { cell: "ap", port: "fresh" } },
+  ],
+  interface: {
+    inputs: {
+      [ports.state]: { cell: "in", port: ports.state },
+      acc: { cell: "in", port: "acc" },
+      win: { cell: "in", port: "win" },
+      [ports.spec]: { cell: "in", port: ports.spec },
+      step: { cell: "in", port: "step" },
+    },
+    outputs: {
+      next: { cell: "tick", port: ports.next },
+      acc: { cell: "ap", port: "emitted" },
+      rest: { cell: "adv", port: "rest" },
+      done: { cell: "adv", port: "done" },
+    },
+  },
+})
+}
+
+/**
+ * Build the outer repeat-loop organism: carries `next→state`, `acc→acc`,
+ * `rest→win`; passes the spec and step constants; exposes `seed` for the
+ * document seed convention.
+ */
+const makeAccLoopOrganism = (
+  name: string,
+  accTickDigest: string,
+  specPort: string,
+  statePort: string,
+): SpatialBehaviorOrganism => {
+  const loopInputOutputs: Record<string, { type: "json" }> = {
+    [statePort]: { type: "json" },
+    [specPort]: { type: "json" },
+    win: { type: "json" },
+    seed: { type: "json" },
+  }
+  const loopConstOutputs: Record<string, { type: "json"; value: unknown }> = {
+    step: { type: "json", value: 3 },
+    acc: { type: "json", value: [] },
+  }
+  return deepFreezeJson({
+  contract: "morphogen.organism.v1" as const,
+  key: `organism:acc-loop-${name}`,
+  name: `Acc loop ${name}`,
+  cells: [
+    { id: "in", kind: "input" as const, outputs: loopInputOutputs },
+    { id: "cfg", kind: "const" as const, outputs: loopConstOutputs },
+    {
+      id: "loop", kind: "repeat" as const,
+      manifest: accTickDigest,
+      maxRounds: 16,
+      carry: { next: statePort, acc: "acc", rest: "win" },
+      until: { output: "done", equals: "true" },
+    },
+  ],
+  edges: [
+    { from: { cell: "in", port: statePort }, to: { cell: "loop", port: statePort } },
+    { from: { cell: "in", port: specPort }, to: { cell: "loop", port: specPort } },
+    { from: { cell: "in", port: "win" }, to: { cell: "loop", port: "win" } },
+    { from: { cell: "cfg", port: "step" }, to: { cell: "loop", port: "step" } },
+    { from: { cell: "cfg", port: "acc" }, to: { cell: "loop", port: "acc" } },
+  ],
+  interface: {
+    inputs: {
+      [statePort]: { cell: "in", port: statePort },
+      [specPort]: { cell: "in", port: specPort },
+      win: { cell: "in", port: "win" },
+      seed: { cell: "in", port: "seed" },
+    },
+    outputs: { trace: { cell: "loop", port: "acc" } },
+  },
+})
+}
+
+// ---------------------------------------------------------- locomotion fsm ---
+
+const locomotionAccTick = makeAccTickOrganism("locomotion", "behavior.fsm.v1", {
+  spec: "machine", state: "state", window: "window", next: "next", emitted: "emitted",
+})
+
+const LOCOMOTION_ACC_TICK_DIGEST = behaviorOrganismSha256(locomotionAccTick)
+
+const locomotionAccLoop = makeAccLoopOrganism("locomotion", LOCOMOTION_ACC_TICK_DIGEST, "machine", "state")
+
+const LOCOMOTION_ACC_LOOP_DIGEST = behaviorOrganismSha256(locomotionAccLoop)
+
+/**
+ * Locomotion FSM organism: a `repeat`+`carry` loop driving `behavior.fsm.v1`
+ * over chunked windows. Entry inputs: `machine` (FSM machine spec), `state`
+ * (initial FSM state), `win` (tick window), `seed` (document seed, auto-bound).
+ * Entry output: `trace` — accumulated emitted records for `<channel>` and
+ * `<channel>.transition` channels.
+ */
+export const SPATIAL_BEHAVIOR_STDLIB_LOCOMOTION_FSM = deepFreezeJson({
+  organisms: {
+    [LOCOMOTION_ACC_TICK_DIGEST]: locomotionAccTick,
+    [LOCOMOTION_ACC_LOOP_DIGEST]: locomotionAccLoop,
+  },
+  entry: LOCOMOTION_ACC_LOOP_DIGEST,
+  /** Interface inputs the doc must supply via `args`. */
+  inputs: { state: "json" as const, machine: "json" as const, win: "json" as const, seed: "json" as const },
+  /** Interface outputs the bake surface extracts. */
+  outputs: { trace: "json" as const },
+})
+
+// ------------------------------------------------------ expression layer ---
+
+const expressionAccTick = makeAccTickOrganism("expression", "behavior.expression.v1", {
+  spec: "spec", state: "state", window: "window", next: "next", emitted: "emitted",
+})
+
+const EXPRESSION_ACC_TICK_DIGEST = behaviorOrganismSha256(expressionAccTick)
+
+const expressionAccLoop = makeAccLoopOrganism("expression", EXPRESSION_ACC_TICK_DIGEST, "spec", "state")
+
+const EXPRESSION_ACC_LOOP_DIGEST = behaviorOrganismSha256(expressionAccLoop)
+
+/**
+ * Expression layer organism: blink, gaze, and mood over chunked tick windows
+ * via `behavior.expression.v1`. Entry inputs: `spec` (expression config),
+ * `state` (initial expression state), `win` (tick window), `seed` (auto-bound).
+ */
+export const SPATIAL_BEHAVIOR_STDLIB_EXPRESSION = deepFreezeJson({
+  organisms: {
+    [EXPRESSION_ACC_TICK_DIGEST]: expressionAccTick,
+    [EXPRESSION_ACC_LOOP_DIGEST]: expressionAccLoop,
+  },
+  entry: EXPRESSION_ACC_LOOP_DIGEST,
+  inputs: { state: "json" as const, spec: "json" as const, win: "json" as const, seed: "json" as const },
+  outputs: { trace: "json" as const },
+})
+
+// ------------------------------------------------- interaction sequence ---
+
+const interactAccTick = makeAccTickOrganism("interact", "behavior.interact.v1", {
+  spec: "spec", state: "state", window: "window", next: "next", emitted: "emitted",
+})
+
+const INTERACT_ACC_TICK_DIGEST = behaviorOrganismSha256(interactAccTick)
+
+const interactAccLoop = makeAccLoopOrganism("interact", INTERACT_ACC_TICK_DIGEST, "spec", "state")
+
+const INTERACT_ACC_LOOP_DIGEST = behaviorOrganismSha256(interactAccLoop)
+
+/**
+ * Interaction sequence organism: linear phase sequencer via
+ * `behavior.interact.v1`. Entry inputs: `spec` (interaction phases),
+ * `state` (initial phase state), `win` (tick window), `seed` (auto-bound).
+ */
+export const SPATIAL_BEHAVIOR_STDLIB_INTERACT = deepFreezeJson({
+  organisms: {
+    [INTERACT_ACC_TICK_DIGEST]: interactAccTick,
+    [INTERACT_ACC_LOOP_DIGEST]: interactAccLoop,
+  },
+  entry: INTERACT_ACC_LOOP_DIGEST,
+  inputs: { state: "json" as const, spec: "json" as const, win: "json" as const, seed: "json" as const },
+  outputs: { trace: "json" as const },
+})
+
+// --------------------------------------------------- combined behavior ---
+
+/**
+ * Combined behavior organism: composes locomotion, expression, and interaction
+ * sub-organisms into a single merged emitted trace. Each sub-organism runs
+ * its own `repeat`+`carry` loop; the combined organism chains pairwise
+ * `emitted.append` to concatenate the three traces into sorted order.
+ *
+ * Entry inputs: `loco-state`, `loco-machine`, `expr-state`, `expr-spec`,
+ * `interact-state`, `interact-spec`, `win` (shared tick window), `seed`.
+ * Entry output: `trace` — merged emitted records sorted by (tUs, channel).
+ */
+
+const combinedOrganism: SpatialBehaviorOrganism = deepFreezeJson({
+  contract: "morphogen.organism.v1" as const,
+  key: "organism:combined-behavior",
+  name: "Combined behavior",
+  cells: [
+    {
+      id: "in", kind: "input" as const,
+      outputs: {
+        "loco-state": { type: "json" as const },
+        "loco-machine": { type: "json" as const },
+        "expr-state": { type: "json" as const },
+        "expr-spec": { type: "json" as const },
+        "interact-state": { type: "json" as const },
+        "interact-spec": { type: "json" as const },
+        win: { type: "json" as const },
+        seed: { type: "json" as const },
+      },
+    },
+    { id: "loco", kind: "organism" as const, manifest: LOCOMOTION_ACC_LOOP_DIGEST },
+    { id: "expr", kind: "organism" as const, manifest: EXPRESSION_ACC_LOOP_DIGEST },
+    { id: "interact", kind: "organism" as const, manifest: INTERACT_ACC_LOOP_DIGEST },
+    { id: "ap-le", kind: "fn" as const, fn: "emitted.append.v1" },
+    { id: "ap-lei", kind: "fn" as const, fn: "emitted.append.v1" },
+  ],
+  edges: [
+    // Locomotion sub
+    { from: { cell: "in", port: "loco-state" }, to: { cell: "loco", port: "state" } },
+    { from: { cell: "in", port: "loco-machine" }, to: { cell: "loco", port: "machine" } },
+    { from: { cell: "in", port: "win" }, to: { cell: "loco", port: "win" } },
+    { from: { cell: "in", port: "seed" }, to: { cell: "loco", port: "seed" } },
+    // Expression sub
+    { from: { cell: "in", port: "expr-state" }, to: { cell: "expr", port: "state" } },
+    { from: { cell: "in", port: "expr-spec" }, to: { cell: "expr", port: "spec" } },
+    { from: { cell: "in", port: "win" }, to: { cell: "expr", port: "win" } },
+    { from: { cell: "in", port: "seed" }, to: { cell: "expr", port: "seed" } },
+    // Interact sub
+    { from: { cell: "in", port: "interact-state" }, to: { cell: "interact", port: "state" } },
+    { from: { cell: "in", port: "interact-spec" }, to: { cell: "interact", port: "spec" } },
+    { from: { cell: "in", port: "win" }, to: { cell: "interact", port: "win" } },
+    { from: { cell: "in", port: "seed" }, to: { cell: "interact", port: "seed" } },
+    // Chain appends: loco+expr → ap-le, then ap-le+interact → ap-lei
+    { from: { cell: "loco", port: "trace" }, to: { cell: "ap-le", port: "prior" } },
+    { from: { cell: "expr", port: "trace" }, to: { cell: "ap-le", port: "fresh" } },
+    { from: { cell: "ap-le", port: "emitted" }, to: { cell: "ap-lei", port: "prior" } },
+    { from: { cell: "interact", port: "trace" }, to: { cell: "ap-lei", port: "fresh" } },
+  ],
+  interface: {
+    inputs: {
+      "loco-state": { cell: "in", port: "loco-state" },
+      "loco-machine": { cell: "in", port: "loco-machine" },
+      "expr-state": { cell: "in", port: "expr-state" },
+      "expr-spec": { cell: "in", port: "expr-spec" },
+      "interact-state": { cell: "in", port: "interact-state" },
+      "interact-spec": { cell: "in", port: "interact-spec" },
+      win: { cell: "in", port: "win" },
+      seed: { cell: "in", port: "seed" },
+    },
+    outputs: { trace: { cell: "ap-lei", port: "emitted" } },
+  },
+})
+
+const COMBINED_DIGEST = behaviorOrganismSha256(combinedOrganism)
+
+export const SPATIAL_BEHAVIOR_STDLIB_COMBINED = deepFreezeJson({
+  organisms: {
+    ...SPATIAL_BEHAVIOR_STDLIB_LOCOMOTION_FSM.organisms,
+    ...SPATIAL_BEHAVIOR_STDLIB_EXPRESSION.organisms,
+    ...SPATIAL_BEHAVIOR_STDLIB_INTERACT.organisms,
+    [COMBINED_DIGEST]: combinedOrganism,
+  },
+  entry: COMBINED_DIGEST,
+  inputs: {
+    "loco-state": "json" as const,
+    "loco-machine": "json" as const,
+    "expr-state": "json" as const,
+    "expr-spec": "json" as const,
+    "interact-state": "json" as const,
+    "interact-spec": "json" as const,
+    win: "json" as const,
+    seed: "json" as const,
+  },
+  outputs: { trace: "json" as const },
+})

package/src/spatial-scene/behavior-trace.ts

@@ -0,0 +1,325 @@
+import { z } from "zod"
+import { HUMANOID_BONE_NAMES } from "./character.js"
+import {
+  SPATIAL_SCENE_LIMITS,
+  SpatialDigestSchema,
+  SpatialQuaternionSchema,
+  SpatialTimeUsSchema,
+  SpatialTransformSchema,
+  SpatialVec3Schema,
+} from "./contracts.js"
+import { SpatialPerformanceDirectiveSchema, type SpatialPerformanceDirective } from "./performance.js"
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import { parseSpatialValue, spatialValueSha256, SpatialSceneError } from "./identity.js"
+import type { JsonValue } from "../code/contracts.js"
+import type { SpatialBehaviorFn } from "./behavior-fns.js"
+
+// ------------------------------------------------------------------ limits ---
+
+export const SPATIAL_BEHAVIOR_TRACE_LIMITS = Object.freeze({
+  emitted: 16_384,
+  channels: 64,
+  clipChannels: 16,
+  clipValues: 64,
+  attachments: 8,
+  trajectories: 8,
+  directives: 4_096,
+  unresolvedIntents: 256,
+})
+
+// ----------------------------------------------------------------- emitted ---
+
+const channelName = z.string().regex(/^[a-z][a-z0-9_.-]{0,62}$/u)
+
+/** One emitted channel record — the vocabulary organisms surface at bake. */
+export const SpatialBehaviorEmittedSchema = z.strictObject({
+  tUs: SpatialTimeUsSchema,
+  channel: channelName,
+  value: z.unknown(),
+})
+export type SpatialBehaviorEmitted = Readonly<z.infer<typeof SpatialBehaviorEmittedSchema>>
+
+/** Validates one organism output value as a bounded emitted-record array. */
+export function parseSpatialBehaviorEmissions(input: unknown, what: string): SpatialBehaviorEmitted[] {
+  return parseSpatialValue(z.array(SpatialBehaviorEmittedSchema).max(SPATIAL_BEHAVIOR_TRACE_LIMITS.emitted), input, what)
+}
+
+// -------------------------------------------------------------- channel map ---
+
+const humanoidBone = z.enum(HUMANOID_BONE_NAMES)
+const bindingChannel = channelName
+const clipValue = z.string().min(1).max(64)
+
+/**
+ * Host-supplied bindings from emitted channels to performance-directive
+ * assets. Clip digests, prop identities and attachment bones are
+ * scene-admission concerns, so they live outside the portable behavior doc:
+ * the map rides the bake request. Channels absent from the map stay
+ * trace-only; a mapped channel missing a sub-binding reports an unresolved
+ * intent rather than fabricating identity.
+ */
+export const SpatialBehaviorChannelMapSchema = z.strictObject({
+  clips: z.record(
+    bindingChannel,
+    z.record(clipValue, z.strictObject({
+      clipDigest: SpatialDigestSchema,
+      durationUs: SpatialTimeUsSchema.refine((value) => value > 0, "Clip duration must be positive."),
+    })),
+  ).refine(
+    (clips) => Object.keys(clips).length <= SPATIAL_BEHAVIOR_TRACE_LIMITS.clipChannels
+      && Object.values(clips).every((values) => Object.keys(values).length <= SPATIAL_BEHAVIOR_TRACE_LIMITS.clipValues),
+    { message: `At most ${SPATIAL_BEHAVIOR_TRACE_LIMITS.clipChannels} clip channels with ${SPATIAL_BEHAVIOR_TRACE_LIMITS.clipValues} values each.` },
+  ).optional(),
+  attachments: z.array(z.strictObject({
+    attachChannel: bindingChannel,
+    releaseChannel: bindingChannel,
+    propId: z.string().min(1).max(128),
+    bone: humanoidBone,
+    localOffset: SpatialTransformSchema,
+  })).max(SPATIAL_BEHAVIOR_TRACE_LIMITS.attachments).optional(),
+  trajectories: z.array(bindingChannel).max(SPATIAL_BEHAVIOR_TRACE_LIMITS.trajectories).optional(),
+}).superRefine((map, context) => {
+  const attachChannels = new Set<string>()
+  for (const [index, attachment] of (map.attachments ?? []).entries()) {
+    if (attachChannels.has(attachment.attachChannel)) {
+      context.addIssue({ code: "custom", path: ["attachments", index, "attachChannel"], message: `Attach channel ${attachment.attachChannel} is bound twice.` })
+    }
+    attachChannels.add(attachment.attachChannel)
+  }
+  for (const name of map.trajectories ?? []) {
+    if (map.clips !== undefined && name in map.clips) {
+      context.addIssue({ code: "custom", path: ["trajectories"], message: `Channel ${name} is bound as both clip and trajectory.` })
+    }
+  }
+})
+export type SpatialBehaviorChannelMap = Readonly<z.infer<typeof SpatialBehaviorChannelMapSchema>>
+
+export function parseSpatialBehaviorChannelMap(input: unknown): SpatialBehaviorChannelMap {
+  return deepFreezeJson(parseSpatialValue(SpatialBehaviorChannelMapSchema, input, "behavior channel map"))
+}
+
+// ----------------------------------------------------------- unresolved ----
+
+export const SpatialBehaviorUnresolvedIntentSchema = z.strictObject({
+  intentId: z.string().regex(/^prop_[a-f0-9]{16}$/u),
+  domain: z.literal("behavior"),
+  referenceId: z.string().min(1).max(128),
+  slot: z.string().min(1).max(64).regex(/^[a-z][a-z0-9-]*$/u),
+  detail: z.string().min(1).max(240),
+})
+export type SpatialBehaviorUnresolvedIntent = Readonly<z.infer<typeof SpatialBehaviorUnresolvedIntentSchema>>
+
+const intentId = (domain: string, reference: string): string =>
+  `prop_${spatialValueSha256({ domain: `slopcamera.behavior-intent.${domain}`, reference }).slice(0, 16)}`
+
+const unresolved = (domain: string, referenceId: string, slot: string, detail: string): SpatialBehaviorUnresolvedIntent =>
+  deepFreezeJson({ intentId: intentId(domain, `${referenceId}/${slot}`), domain: "behavior", referenceId, slot, detail })
+
+// ------------------------------------------------------------ mapper --------
+
+const emittedValueKey = (value: unknown): string => {
+  try {
+    return spatialValueSha256(value as JsonValue)
+  } catch {
+    return "\u0000unrepresentable"
+  }
+}
+
+const directiveId = (domain: string, parts: readonly (string | number)[]): string =>
+  `dir_${domain}_${spatialValueSha256({ domain: `slopcamera.behavior-directive.${domain}`, parts }).slice(0, 12)}`
+
+export interface SpatialBehaviorDirectiveCompilation {
+  readonly directives: readonly SpatialPerformanceDirective[]
+  readonly unresolvedIntents: readonly SpatialBehaviorUnresolvedIntent[]
+}
+
+/**
+ * Maps a validated emitted trace to performance directives under a channel
+ * map. Clip channels emit contiguous same-value runs as clip directives;
+ * attach/release channels pair into prop bindings; trajectory channels
+ * accumulate waypoint values into one root-trajectory directive. Unmapped
+ * channels contribute nothing — their records stay trace evidence only.
+ */
+export function compileSpatialBehaviorDirectives(input: {
+  readonly emitted: readonly SpatialBehaviorEmitted[]
+  readonly channelMap?: SpatialBehaviorChannelMap
+  readonly rangeUs: { readonly startUs: number; readonly endUs: number }
+}): SpatialBehaviorDirectiveCompilation {
+  const { emitted, channelMap, rangeUs } = input
+  const directives: SpatialPerformanceDirective[] = []
+  const unresolvedIntents: SpatialBehaviorUnresolvedIntent[] = []
+  const map = channelMap ?? {}
+
+  const sorted = [...emitted].sort((a, b) => a.tUs - b.tUs || a.channel.localeCompare(b.channel))
+
+  const clipChannels = Object.keys(map.clips ?? {})
+  for (const channel of clipChannels) {
+    const bindings = map.clips![channel]!
+    const records = sorted.filter((record) => record.channel === channel)
+    if (records.length === 0) continue
+    let runStart = records[0]!.tUs
+    let runValue = emittedValueKey(records[0]!.value)
+    let runLabel = records[0]!.value
+    const flush = (endUs: number): void => {
+      const label = typeof runLabel === "string" ? runLabel : undefined
+      const binding = label === undefined ? undefined : bindings[label]
+      if (binding === undefined) {
+        unresolvedIntents.push(unresolved("clip", `${channel}:${label ?? "non-string"}`, "clip-binding",
+          `Channel ${channel} emitted ${label === undefined ? "a non-string value" : `value ${label}`} with no clip binding at ${runStart}us.`))
+        return
+      }
+      const intervalUs = endUs - runStart
+      if (intervalUs <= 0) return
+      directives.push(deepFreezeJson(SpatialPerformanceDirectiveSchema.parse({
+        directiveId: directiveId("clip", [channel, runStart, endUs]),
+        kind: "clip",
+        clipDigest: binding.clipDigest,
+        startUs: runStart,
+        endUs,
+        trimStartUs: 0,
+        trimEndUs: Math.min(intervalUs, binding.durationUs),
+        loop: intervalUs > binding.durationUs ? Math.ceil(intervalUs / binding.durationUs) : "once",
+        timeScale: 1,
+      })))
+    }
+    for (let index = 1; index < records.length; index += 1) {
+      const record = records[index]!
+      const key = emittedValueKey(record.value)
+      if (key !== runValue) {
+        flush(record.tUs)
+        runStart = record.tUs
+        runValue = key
+        runLabel = record.value
+      }
+    }
+    flush(rangeUs.endUs)
+  }
+
+  for (const attachment of map.attachments ?? []) {
+    const attachRecords = sorted.filter((record) => record.channel === attachment.attachChannel)
+    const releaseRecords = sorted.filter((record) => record.channel === attachment.releaseChannel)
+    if (attachRecords.length === 0 && releaseRecords.length === 0) continue
+    if (releaseRecords.length > attachRecords.length) {
+      unresolvedIntents.push(unresolved("attach", attachment.propId, "release-order",
+        `Channel ${attachment.releaseChannel} emits ${releaseRecords.length} releases against ${attachRecords.length} attaches on ${attachment.attachChannel}.`))
+      continue
+    }
+    for (const [index, attachRecord] of attachRecords.entries()) {
+      const releaseRecord = releaseRecords[index]
+      if (releaseRecord !== undefined && releaseRecord.tUs <= attachRecord.tUs) {
+        unresolvedIntents.push(unresolved("attach", attachment.propId, "release-order",
+          `Release on ${attachment.releaseChannel} at ${releaseRecord.tUs}us does not follow attach on ${attachment.attachChannel} at ${attachRecord.tUs}us.`))
+        continue
+      }
+      const endUs = releaseRecord !== undefined ? releaseRecord.tUs : rangeUs.endUs
+      directives.push(deepFreezeJson(SpatialPerformanceDirectiveSchema.parse({
+        directiveId: directiveId("attach", [attachment.propId, attachRecord.tUs]),
+        kind: "attach",
+        propId: attachment.propId,
+        bone: attachment.bone,
+        localOffset: attachment.localOffset,
+        startUs: attachRecord.tUs,
+        endUs,
+      })))
+      if (releaseRecord !== undefined) {
+        directives.push(deepFreezeJson(SpatialPerformanceDirectiveSchema.parse({
+          directiveId: directiveId("release", [attachment.propId, releaseRecord.tUs]),
+          kind: "release",
+          propId: attachment.propId,
+          startUs: releaseRecord.tUs,
+        })))
+      }
+    }
+  }
+
+  for (const channel of map.trajectories ?? []) {
+    const records = sorted.filter((record) => record.channel === channel)
+    if (records.length === 0) continue
+    const waypoints: { timeUs: number; position: readonly number[]; rotation: readonly number[] }[] = []
+    let malformed = 0
+    for (const record of records) {
+      const value = record.value
+      if (value === null || typeof value !== "object" || Array.isArray(value)) { malformed += 1; continue }
+      const waypoint = value as { position?: unknown; rotation?: unknown }
+      const position = SpatialVec3Schema.safeParse(waypoint.position)
+      const rotation = waypoint.rotation === undefined ? undefined : SpatialQuaternionSchema.safeParse(waypoint.rotation)
+      if (!position.success || (rotation !== undefined && !rotation.success)) { malformed += 1; continue }
+      waypoints.push({
+        timeUs: record.tUs,
+        position: position.data,
+        rotation: rotation === undefined ? [0, 0, 0, 1] : rotation.data,
+      })
+    }
+    if (malformed > 0) {
+      unresolvedIntents.push(unresolved("trajectory", channel, "waypoint-shape",
+        `Channel ${channel} emitted ${malformed} malformed waypoint records; waypoints need {position, rotation?}.`))
+    }
+    if (waypoints.length < 2) {
+      unresolvedIntents.push(unresolved("trajectory", channel, "waypoint-count",
+        `Channel ${channel} produced ${waypoints.length} valid waypoints; a root trajectory needs at least 2.`))
+      continue
+    }
+    directives.push(deepFreezeJson(SpatialPerformanceDirectiveSchema.parse({
+      directiveId: directiveId("trajectory", [channel, waypoints[0]!.timeUs, waypoints.length]),
+      kind: "root-trajectory",
+      waypoints,
+    })))
+  }
+
+  if (directives.length > SPATIAL_BEHAVIOR_TRACE_LIMITS.directives) {
+    throw new SpatialSceneError("invalid-data", `over-bound: channel map produced ${directives.length} directives beyond ${SPATIAL_BEHAVIOR_TRACE_LIMITS.directives}.`, "behavior-trace")
+  }
+  return deepFreezeJson({ directives, unresolvedIntents })
+}
+
+// ------------------------------------------------------------- bake ---------
+
+export const SpatialBehaviorBakeReceiptSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-behavior-bake-receipt"),
+  schemaVersion: z.literal(1),
+  behaviorSha256: SpatialDigestSchema,
+  sceneSha256: SpatialDigestSchema,
+  entry: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+  manifestDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+  runDigest: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+  runtime: z.strictObject({ name: z.string().min(1).max(64), version: z.string().min(1).max(64) }),
+  fnCatalogSha256: SpatialDigestSchema,
+  emittedSha256: SpatialDigestSchema,
+  channelMapSha256: SpatialDigestSchema.optional(),
+  outcome: z.enum(["complete", "failed", "stuck"]),
+  work: z.strictObject({
+    steps: z.number().int().min(0).max(SPATIAL_SCENE_LIMITS.durationUs),
+    agentCalls: z.number().int().min(0).max(65_536),
+    units: z.number().int().min(0).max(100_000_000),
+  }),
+})
+export type SpatialBehaviorBakeReceipt = Readonly<z.infer<typeof SpatialBehaviorBakeReceiptSchema>>
+
+export const SpatialBehaviorBakeSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-behavior-bake"),
+  schemaVersion: z.literal(1),
+  behaviorSha256: SpatialDigestSchema,
+  sceneSha256: SpatialDigestSchema,
+  entry: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
+  seed: z.number().int().min(0).max(4_294_967_295),
+  rangeUs: z.strictObject({ startUs: SpatialTimeUsSchema, endUs: SpatialTimeUsSchema }),
+  emitted: z.array(SpatialBehaviorEmittedSchema).max(SPATIAL_BEHAVIOR_TRACE_LIMITS.emitted),
+  directives: z.array(SpatialPerformanceDirectiveSchema).max(SPATIAL_BEHAVIOR_TRACE_LIMITS.directives),
+  unresolvedIntents: z.array(SpatialBehaviorUnresolvedIntentSchema).max(SPATIAL_BEHAVIOR_TRACE_LIMITS.unresolvedIntents),
+  receipt: SpatialBehaviorBakeReceiptSchema,
+})
+export type SpatialBehaviorBake = Readonly<z.infer<typeof SpatialBehaviorBakeSchema>>
+
+export function spatialBehaviorBakeSha256(bake: SpatialBehaviorBake): string {
+  return spatialValueSha256(bake)
+}
+
+/** Digest binding the admitted fn catalog — names, port signatures, and modeled work costs. */
+export function spatialBehaviorFnCatalogSha256(fns: ReadonlyMap<string, SpatialBehaviorFn>): string {
+  const projection: Record<string, unknown> = {}
+  for (const name of [...fns.keys()].sort()) {
+    const signature = fns.get(name)!.signature
+    projection[name] = { inputs: signature.inputs, outputs: signature.outputs, cost: signature.cost }
+  }
+  return spatialValueSha256({ domain: "slopcamera.behavior-fn-catalog.v1", fns: projection } as JsonValue & Record<string, unknown>)
+}