@hraness/slopcamera 3.2.8 → 3.3.2

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

@@ -0,0 +1,252 @@
+import { z } from "zod"
+
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import { SpatialDigestSchema, SpatialTimeUsSchema } from "./contracts.js"
+import { parseSpatialValue, spatialValueSha256 } from "./identity.js"
+import type { SpatialBehaviorEmitted } from "./behavior-trace.js"
+
+/**
+ * Behavior-trace audit: analyzes a baked emitted trace for pathological
+ * patterns that indicate a degenerate, trivially cyclic, or underspecified
+ * behavior. Findings are advisory — they inform gallery review and agent
+ * iteration, not automatic selection.
+ *
+ * Finding kinds:
+ * - `state-thrash` — a state channel transitions more than `maxTransitionsPerSecond`
+ *   times within a one-second window, suggesting an underspecified dwell guard.
+ * - `exact-periodicity` — a channel's values repeat with a fixed period across
+ *   the entire trace, suggesting a degenerate constant or trivial cycle.
+ * - `dead-channel` — a channel emits the same value at every tick, contributing
+ *   no dynamic information to the performance.
+ * - `unreachable-state` — for FSM channels where the transition sub-channel
+ *   is present, any state that appears in transitions as `to` but is never
+ *   the current value is considered unreachable within this trace window.
+ */
+
+export const SPATIAL_BEHAVIOR_AUDIT_LIMITS = Object.freeze({
+  findings: 128,
+  channels: 64,
+})
+
+export const SpatialBehaviorAuditFindingKindSchema = z.enum([
+  "state-thrash",
+  "exact-periodicity",
+  "dead-channel",
+  "unreachable-state",
+])
+export type SpatialBehaviorAuditFindingKind = z.infer<typeof SpatialBehaviorAuditFindingKindSchema>
+
+export const SpatialBehaviorAuditFindingSchema = z.strictObject({
+  kind: SpatialBehaviorAuditFindingKindSchema,
+  channel: z.string().min(1).max(64),
+  severity: z.enum(["warning", "info"]),
+  detail: z.string().min(1).max(240),
+  measured: z.number().finite().optional(),
+  limit: z.number().finite().optional(),
+})
+export type SpatialBehaviorAuditFinding = Readonly<z.infer<typeof SpatialBehaviorAuditFindingSchema>>
+
+export const SpatialBehaviorAuditOptionsSchema = z.strictObject({
+  maxTransitionsPerSecond: z.number().int().min(1).max(1000).default(10),
+  minDistinctValues: z.number().int().min(2).max(100).default(2),
+  maxPeriodicityWindowUs: z.number().int().min(100_000).max(60_000_000).default(5_000_000),
+})
+export type SpatialBehaviorAuditOptions = Readonly<z.infer<typeof SpatialBehaviorAuditOptionsSchema>>
+
+export const SpatialBehaviorAuditReportSchema = z.strictObject({
+  kind: z.literal("slopcamera.spatial-behavior-audit-report"),
+  schemaVersion: z.literal(1),
+  behaviorSha256: SpatialDigestSchema,
+  emittedSha256: SpatialDigestSchema,
+  rangeUs: z.strictObject({ startUs: SpatialTimeUsSchema, endUs: SpatialTimeUsSchema }),
+  emittedCount: z.number().int().min(0),
+  channelCount: z.number().int().min(0),
+  findings: z.array(SpatialBehaviorAuditFindingSchema).max(SPATIAL_BEHAVIOR_AUDIT_LIMITS.findings),
+  omittedFindings: z.number().int().min(0),
+})
+export type SpatialBehaviorAuditReport = Readonly<z.infer<typeof SpatialBehaviorAuditReportSchema>>
+
+export function spatialBehaviorAuditReportSha256(report: SpatialBehaviorAuditReport): string {
+  return spatialValueSha256(report)
+}
+
+// -------------------------------------------------------------- internals ---
+
+const valueKey = (value: unknown): string => {
+  if (typeof value === "string") return value
+  if (typeof value === "number") return `n:${value}`
+  if (typeof value === "boolean") return `b:${value ? 1 : 0}`
+  try { return JSON.stringify(value) } catch { return "\0" }
+}
+
+interface ChannelTrace {
+  readonly channel: string
+  readonly records: readonly SpatialBehaviorEmitted[]
+  readonly values: readonly string[]
+  readonly distinctValues: Set<string>
+}
+
+function groupByChannel(emitted: readonly SpatialBehaviorEmitted[]): Map<string, ChannelTrace> {
+  const groups = new Map<string, SpatialBehaviorEmitted[]>()
+  for (const record of emitted) {
+    let list = groups.get(record.channel)
+    if (list === undefined) { list = []; groups.set(record.channel, list) }
+    list.push(record)
+  }
+  const result = new Map<string, ChannelTrace>()
+  for (const [channel, records] of groups) {
+    const values = records.map((record) => valueKey(record.value))
+    result.set(channel, { channel, records, values, distinctValues: new Set(values) })
+  }
+  return result
+}
+
+function checkStateThrash(
+  trace: ChannelTrace,
+  maxTransitionsPerSecond: number,
+  findings: SpatialBehaviorAuditFinding[],
+): void {
+  const { records, values } = trace
+  if (records.length < 3) return
+  const windowUs = 1_000_000
+  let windowStart = 0
+  let transitions = 0
+  let maxSeen = 0
+  for (let i = 1; i < records.length; i += 1) {
+    if (values[i] !== values[i - 1]) transitions += 1
+    while (windowStart < i && records[i]!.tUs - records[windowStart]!.tUs > windowUs) {
+      if (values[windowStart + 1] !== values[windowStart]) transitions -= 1
+      windowStart += 1
+    }
+    maxSeen = Math.max(maxSeen, transitions)
+  }
+  if (maxSeen > maxTransitionsPerSecond) {
+    findings.push({
+      kind: "state-thrash", channel: trace.channel, severity: "warning",
+      detail: `${maxSeen} transitions/sec in a 1s window exceeds ${maxTransitionsPerSecond}/sec threshold.`,
+      measured: maxSeen, limit: maxTransitionsPerSecond,
+    })
+  }
+}
+
+function checkDeadChannel(
+  trace: ChannelTrace,
+  minDistinct: number,
+  findings: SpatialBehaviorAuditFinding[],
+): void {
+  if (trace.records.length < 2) return
+  if (trace.distinctValues.size < minDistinct) {
+    findings.push({
+      kind: "dead-channel", channel: trace.channel, severity: "info",
+      detail: `Channel emits ${trace.distinctValues.size} distinct value(s) across ${trace.records.length} records.`,
+      measured: trace.distinctValues.size, limit: minDistinct,
+    })
+  }
+}
+
+function checkExactPeriodicity(
+  trace: ChannelTrace,
+  maxWindowUs: number,
+  findings: SpatialBehaviorAuditFinding[],
+): void {
+  const { records, values } = trace
+  if (records.length < 6) return
+  const rangeUs = records[records.length - 1]!.tUs - records[0]!.tUs
+  if (rangeUs <= 0) return
+  // Check if the value sequence repeats with period P for P in [2, half-length].
+  const halfLen = Math.floor(values.length / 2)
+  const maxPeriod = Math.min(halfLen, Math.floor(values.length * maxWindowUs / rangeUs))
+  for (let period = 2; period <= maxPeriod; period += 1) {
+    let match = true
+    for (let i = period; i < values.length; i += 1) {
+      if (values[i] !== values[i - period]) { match = false; break }
+    }
+    if (match) {
+      findings.push({
+        kind: "exact-periodicity", channel: trace.channel, severity: "info",
+        detail: `Values repeat exactly every ${period} records — the behavior may be trivially cyclic.`,
+        measured: period,
+      })
+      return
+    }
+  }
+}
+
+function checkUnreachableStates(
+  channels: Map<string, ChannelTrace>,
+  findings: SpatialBehaviorAuditFinding[],
+): void {
+  for (const [channel, trace] of channels) {
+    const transitionChannel = `${channel}.transition`
+    const transitionTrace = channels.get(transitionChannel)
+    if (transitionTrace === undefined) continue
+
+    const visited = new Set<string>()
+    for (const value of trace.values) {
+      if (typeof value === "string") visited.add(value)
+    }
+
+    const referenced = new Set<string>()
+    for (const record of transitionTrace.records) {
+      const value = record.value
+      if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+        const typed = value as { to?: unknown; from?: unknown }
+        if (typeof typed.to === "string") referenced.add(typed.to)
+        if (typeof typed.from === "string") referenced.add(typed.from)
+      }
+    }
+
+    for (const state of referenced) {
+      if (!visited.has(state)) {
+        findings.push({
+          kind: "unreachable-state", channel, severity: "warning",
+          detail: `State "${state}" appears in ${transitionChannel} transitions but never as the current ${channel} value.`,
+        })
+      }
+    }
+  }
+}
+
+// ---------------------------------------------------------------- public ---
+
+const auditInputSchema = z.strictObject({
+  emitted: z.array(z.strictObject({
+    tUs: SpatialTimeUsSchema,
+    channel: z.string().min(1).max(64),
+    value: z.unknown(),
+  })).max(16_384),
+  behaviorSha256: SpatialDigestSchema,
+  emittedSha256: SpatialDigestSchema,
+  rangeUs: z.strictObject({ startUs: SpatialTimeUsSchema, endUs: SpatialTimeUsSchema }),
+  options: SpatialBehaviorAuditOptionsSchema.optional(),
+})
+
+export function auditSpatialBehaviorTrace(input: unknown): SpatialBehaviorAuditReport {
+  const parsed = parseSpatialValue(auditInputSchema, input, "behavior audit")
+  const options = parsed.options ?? SpatialBehaviorAuditOptionsSchema.parse({})
+  const channels = groupByChannel(parsed.emitted)
+  const findings: SpatialBehaviorAuditFinding[] = []
+
+  for (const trace of channels.values()) {
+    if (findings.length >= SPATIAL_BEHAVIOR_AUDIT_LIMITS.findings) break
+    checkStateThrash(trace, options.maxTransitionsPerSecond, findings)
+    checkDeadChannel(trace, options.minDistinctValues, findings)
+    checkExactPeriodicity(trace, options.maxPeriodicityWindowUs, findings)
+  }
+  checkUnreachableStates(channels, findings)
+
+  const bounded = findings.slice(0, SPATIAL_BEHAVIOR_AUDIT_LIMITS.findings)
+  const omitted = findings.length - bounded.length
+
+  return deepFreezeJson(SpatialBehaviorAuditReportSchema.parse({
+    kind: "slopcamera.spatial-behavior-audit-report",
+    schemaVersion: 1,
+    behaviorSha256: parsed.behaviorSha256,
+    emittedSha256: parsed.emittedSha256,
+    rangeUs: parsed.rangeUs,
+    emittedCount: parsed.emitted.length,
+    channelCount: channels.size,
+    findings: bounded,
+    omittedFindings: omitted,
+  }))
+}

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

@@ -0,0 +1,232 @@
+import { z } from "zod"
+
+import type {
+  FnRegistry,
+  JsonValue as AlgalJsonValue,
+  OrganismManifest,
+  PortMap as AlgalPortMap,
+} from "@hraness/algal"
+
+import { deepFreezeJson } from "../code/json-snapshot.js"
+import {
+  checkSpatialBehavior,
+  parseSpatialBehavior,
+  spatialBehaviorSha256,
+  type SpatialBehavior,
+  type SpatialBehaviorCheckReport,
+} from "./behavior.js"
+import { SPATIAL_BEHAVIOR_FNS, spatialBehaviorFnSignatures } from "./behavior-fns.js"
+import {
+  compileSpatialBehaviorDirectives,
+  parseSpatialBehaviorChannelMap,
+  parseSpatialBehaviorEmissions,
+  spatialBehaviorFnCatalogSha256,
+  SPATIAL_BEHAVIOR_TRACE_LIMITS,
+  SpatialBehaviorBakeSchema,
+  type SpatialBehaviorBake,
+  type SpatialBehaviorChannelMap,
+  type SpatialBehaviorEmitted,
+} from "./behavior-trace.js"
+import { parseSpatialScene, parseSpatialValue, spatialValueSha256, SpatialSceneError } from "./identity.js"
+
+/**
+ * Deterministic behavior bake: an admitted `slopcamera.spatial-behavior`
+ * document runs through the pinned ALGAL runtime under the bake-safe profile
+ * — the closed pure fn catalog, a memory store, zero executors, no tools,
+ * transports, slots, or effects. The run receipt plus the emitted channel
+ * trace and compiled directive proposals form the retained
+ * `slopcamera.spatial-behavior-bake` artifact. Organism digests stored into
+ * the CAS are recomputed by ALGAL's own `manifestToJson`, so a drift between
+ * this mirror and the runtime fails at admission rather than mid-run.
+ */
+
+const bakeOptionsSchema = z.strictObject({
+  behavior: z.unknown(),
+  scene: z.unknown(),
+  channelMap: z.unknown().optional(),
+})
+
+export interface SpatialBehaviorBakeResult {
+  readonly bake: SpatialBehaviorBake
+  readonly check: SpatialBehaviorCheckReport
+}
+
+const algalRegistry = (): FnRegistry => {
+  const registry: FnRegistry = new Map()
+  for (const [name, entry] of SPATIAL_BEHAVIOR_FNS) {
+    registry.set(name, {
+      signature: {
+        inputs: entry.signature.inputs as AlgalPortMap,
+        outputs: entry.signature.outputs as AlgalPortMap,
+        cost: entry.signature.cost,
+      },
+      fn: (inputs: Record<string, AlgalJsonValue>) => entry.invoke(inputs) as Record<string, AlgalJsonValue>,
+    })
+  }
+  return registry
+}
+
+const parseEntryManifest = (
+  behavior: SpatialBehavior,
+  parseOrganismManifest: (input: unknown) => OrganismManifest,
+): OrganismManifest => {
+  const organism = behavior.organisms[behavior.entry]
+  if (organism === undefined) {
+    throw new SpatialSceneError("invalid-data", `unresolved-entry: entry digest ${behavior.entry.slice(0, 24)}… is absent from the organisms closure.`, "behavior-bake")
+  }
+  try {
+    return parseOrganismManifest(organism)
+  } catch (error) {
+    throw new SpatialSceneError("invalid-data", `invalid-manifest: entry organism failed ALGAL manifest parsing: ${error instanceof Error ? error.message : String(error)}`, "behavior-bake")
+  }
+}
+
+/**
+ * Maps declared interface-name args to ALGAL's cell-keyed run args. An entry
+ * interface input named `seed` binds `behavior.seed` by convention when no
+ * arg supplies one — the document-level seed feeds seeded kernels without
+ * duplicating it into args, and galleries vary it for candidate diversity.
+ */
+const entryRunArgs = (behavior: SpatialBehavior, manifest: OrganismManifest): Record<string, Record<string, AlgalJsonValue>> => {
+  const args: Record<string, Record<string, AlgalJsonValue>> = {}
+  for (const [name, value] of Object.entries(behavior.args ?? {})) {
+    const endpoint = manifest.interface?.inputs[name]
+    if (endpoint === undefined) continue // `undeclared-arg` already an error finding
+    ;(args[endpoint.cell] ??= {})[endpoint.port] = value as AlgalJsonValue
+  }
+  const seedEndpoint = manifest.interface?.inputs.seed
+  if (seedEndpoint !== undefined && behavior.args?.seed === undefined) {
+    (args[seedEndpoint.cell] ??= {})[seedEndpoint.port] = behavior.seed
+  }
+  return args
+}
+
+export async function bakeSpatialBehavior(input: unknown): Promise<SpatialBehaviorBakeResult> {
+  const options = parseSpatialValue(bakeOptionsSchema, input, "behavior bake")
+  const behavior = parseSpatialBehavior(options.behavior)
+  const scene = parseSpatialScene(options.scene)
+  const sceneSha256 = spatialValueSha256(scene)
+  const signatures = spatialBehaviorFnSignatures()
+  const check = checkSpatialBehavior({ behavior, scene }, signatures)
+  const errors = check.findings.filter((finding) => finding.severity === "error")
+  if (errors.length > 0) {
+    const codes = [...new Set(errors.map((finding) => finding.code))].join(", ")
+    throw new SpatialSceneError("invalid-data", `behavior-check-failed: behavior ${behavior.behaviorId} failed admission with ${errors.length} error finding(s): ${codes}.`, "behavior-bake")
+  }
+
+  const channelMap: SpatialBehaviorChannelMap | undefined = options.channelMap === undefined
+    ? undefined
+    : parseSpatialBehaviorChannelMap(options.channelMap)
+  if (channelMap !== undefined) {
+    const declared = new Set(behavior.channels)
+    for (const channel of [...Object.keys(channelMap.clips ?? {}), ...(channelMap.trajectories ?? []),
+      ...(channelMap.attachments ?? []).flatMap((entry) => [entry.attachChannel, entry.releaseChannel])]) {
+      if (!declared.has(channel)) {
+        throw new SpatialSceneError("invalid-data", `undeclared-channel: channel map binds channel ${channel}, which behavior ${behavior.behaviorId} does not declare.`, "behavior-bake")
+      }
+    }
+  }
+
+  const { MemoryStore, parseOrganismManifest, runOrganism } = await import("@hraness/algal")
+
+  // Populate the CAS closure through ALGAL's own parser and digest: the
+  // stored digest must equal the closure key, proving runtime parity.
+  const store = new MemoryStore()
+  for (const [digest, organism] of Object.entries(behavior.organisms)) {
+    let manifest: OrganismManifest
+    try {
+      manifest = parseOrganismManifest(organism)
+    } catch (error) {
+      throw new SpatialSceneError("invalid-data", `invalid-manifest: organism ${organism.key} failed ALGAL manifest parsing: ${error instanceof Error ? error.message : String(error)}`, "behavior-bake")
+    }
+    const stored = await store.putManifest(manifest)
+    if (stored !== digest) {
+      throw new SpatialSceneError("invalid-data", `organism-digest-drift: organism ${organism.key} stored at ${stored.slice(0, 24)}… but the closure keys it at ${digest.slice(0, 24)}…; the ALGAL projection drifted from the admitted digest.`, "behavior-bake")
+    }
+  }
+
+  const manifest = parseEntryManifest(behavior, parseOrganismManifest)
+  const args = entryRunArgs(behavior, manifest)
+  const receipt = await runOrganism({
+    manifest,
+    args,
+    fns: algalRegistry(),
+    store,
+    executors: [],
+  })
+
+  if (receipt.manifestDigest !== behavior.entry) {
+    throw new SpatialSceneError("invalid-data", `organism-digest-drift: run manifest digest ${receipt.manifestDigest.slice(0, 24)}… does not match entry ${behavior.entry.slice(0, 24)}….`, "behavior-bake")
+  }
+  if (receipt.effects.length > 0 || receipt.work.agentCalls > 0) {
+    throw new SpatialSceneError("invalid-data", `effect-leak: bake-safe run recorded ${receipt.effects.length} effect(s) and ${receipt.work.agentCalls} agent call(s); the profile admits none.`, "behavior-bake")
+  }
+  if (receipt.outcome !== "complete") {
+    const failure = receipt.failure
+    throw new SpatialSceneError("invalid-data", `behavior-run-failed: ALGAL run ${receipt.outcome}${failure === undefined ? "" : `: ${failure.code} ${failure.message}`}`, "behavior-bake")
+  }
+
+  // Entry interface outputs are the bake surface: every declared output
+  // port carries a bounded emitted-record array. Composition internals
+  // (carried state, per-round records) stay inside the receipt.
+  const declaredChannels = new Set(behavior.channels)
+  const emitted: SpatialBehaviorEmitted[] = []
+  const outputs = manifest.interface?.outputs ?? {}
+  for (const name of Object.keys(outputs).sort()) {
+    const endpoint = outputs[name]!
+    const record = receipt.cells[endpoint.cell]
+    if (record === undefined || record.status !== "committed" || record.outputs === undefined) {
+      throw new SpatialSceneError("invalid-data", `emission-missing: interface output ${name} maps to cell ${endpoint.cell}, which did not commit an output.`, "behavior-bake")
+    }
+    const records = parseSpatialBehaviorEmissions(record.outputs[endpoint.port], `interface output ${name}`)
+    for (const emittedRecord of records) {
+      if (!declaredChannels.has(emittedRecord.channel)) {
+        throw new SpatialSceneError("invalid-data", `undeclared-channel: emission on channel ${emittedRecord.channel}, which behavior ${behavior.behaviorId} does not declare.`, "behavior-bake")
+      }
+      if (emittedRecord.tUs < behavior.rangeUs.startUs || emittedRecord.tUs > behavior.rangeUs.endUs) {
+        throw new SpatialSceneError("invalid-data", `emission-outside-range: emission on channel ${emittedRecord.channel} at ${emittedRecord.tUs}us is outside the declared range ${behavior.rangeUs.startUs}–${behavior.rangeUs.endUs}us.`, "behavior-bake")
+      }
+    }
+    emitted.push(...records)
+  }
+  if (emitted.length > SPATIAL_BEHAVIOR_TRACE_LIMITS.emitted) {
+    throw new SpatialSceneError("invalid-data", `over-bound: run emitted ${emitted.length} records beyond ${SPATIAL_BEHAVIOR_TRACE_LIMITS.emitted}.`, "behavior-bake")
+  }
+  emitted.sort((a, b) => a.tUs - b.tUs || a.channel.localeCompare(b.channel))
+
+  const { directives, unresolvedIntents } = compileSpatialBehaviorDirectives({
+    emitted,
+    ...(channelMap === undefined ? {} : { channelMap }),
+    rangeUs: behavior.rangeUs,
+  })
+
+  const behaviorSha256 = spatialBehaviorSha256(behavior)
+  const bake = deepFreezeJson(SpatialBehaviorBakeSchema.parse({
+    kind: "slopcamera.spatial-behavior-bake",
+    schemaVersion: 1,
+    behaviorSha256,
+    sceneSha256,
+    entry: behavior.entry,
+    seed: behavior.seed,
+    rangeUs: behavior.rangeUs,
+    emitted,
+    directives,
+    unresolvedIntents,
+    receipt: {
+      kind: "slopcamera.spatial-behavior-bake-receipt",
+      schemaVersion: 1,
+      behaviorSha256,
+      sceneSha256,
+      entry: behavior.entry,
+      manifestDigest: receipt.manifestDigest,
+      runDigest: receipt.digest,
+      runtime: { name: receipt.runtime.name, version: receipt.runtime.version },
+      fnCatalogSha256: spatialBehaviorFnCatalogSha256(SPATIAL_BEHAVIOR_FNS),
+      emittedSha256: spatialValueSha256(emitted),
+      ...(channelMap === undefined ? {} : { channelMapSha256: spatialValueSha256(channelMap) }),
+      outcome: receipt.outcome,
+      work: receipt.work,
+    },
+  }))
+  return { bake, check }
+}