@pixel-point/toolcraft 0.0.17 → 0.0.19

package/templates/starter/src/app/acceptance/motion-reference-evidence-windows.mjs

@@ -0,0 +1,301 @@
+import {
+  finite,
+  hasExactKeys,
+  isGroupId,
+  isRecord,
+  isSha256,
+  nonnegativeInteger,
+  positive,
+  positiveInteger,
+  requireValue,
+} from "./motion-reference-evidence-validation.mjs";
+
+function validateStrictRange(value, label, durationSeconds, errors) {
+  if (!hasExactKeys(value, ["endSeconds", "startSeconds"], [], label, errors)) {
+    return false;
+  }
+  const valid = finite(value.startSeconds) && value.startSeconds >= 0 &&
+    finite(value.endSeconds) && value.endSeconds > value.startSeconds &&
+    value.endSeconds <= durationSeconds;
+  requireValue(valid,
+    `${label} must satisfy 0 <= startSeconds < endSeconds <= durationSeconds.`,
+    errors);
+  return valid;
+}
+function validateAuthority(evidence, errors) {
+  const authority = evidence.timing?.authority;
+  const keys = authority === "declared-fps" ? ["authority", "framesPerSecond"] :
+    authority === "declared-timestamps" ? ["authority", "timestampsSha256"] :
+      ["authority"];
+  const label = "timed motion reference evidence timing";
+  if (!hasExactKeys(evidence.timing, keys, [], label, errors)) return;
+  requireValue(["decoded-timestamps", "declared-fps", "declared-timestamps"]
+    .includes(authority), `${label} authority is unsupported.`, errors);
+  if (authority === "declared-fps") requireValue(
+    positive(evidence.timing.framesPerSecond),
+    "declared timing framesPerSecond must be positive and finite.", errors,
+  );
+  if (authority === "declared-timestamps") requireValue(
+    isSha256(evidence.timing.timestampsSha256),
+    "declared timing timestampsSha256 must be a lowercase SHA-256 hash.", errors,
+  );
+}
+function validatePartition(evidence, segmentValid, errors) {
+  const partition = evidence.reviewPartition;
+  if (partition === undefined) return;
+  const label = "timed motion reference evidence reviewPartition";
+  if (!hasExactKeys(partition,
+    ["count", "groupId", "index", "planSha256", "scope"], [], label, errors)) return;
+  requireValue(positiveInteger(partition.count),
+    `${label}.count must be a positive safe integer.`, errors);
+  requireValue(nonnegativeInteger(partition.index) && partition.index < partition.count,
+    `${label}.index must be within count.`, errors);
+  requireValue(isGroupId(partition.groupId), `${label}.groupId is invalid.`, errors);
+  requireValue(isSha256(partition.planSha256),
+    `${label}.planSha256 must be a lowercase SHA-256 hash.`, errors);
+  const scopeValid = validateStrictRange(
+    partition.scope, `${label}.scope`, evidence.durationSeconds, errors,
+  );
+  requireValue(evidence.segment !== undefined,
+    "partitioned timed motion reference evidence must declare a segment.", errors);
+  if (scopeValid && segmentValid) requireValue(
+    evidence.segment.startSeconds >= partition.scope.startSeconds &&
+      evidence.segment.endSeconds <= partition.scope.endSeconds,
+    `${label} segment must be contained within its partition scope.`, errors,
+  );
+}
+function validateTimedShape(evidence, errors) {
+  const durationValid = positive(evidence.durationSeconds);
+  requireValue(durationValid,
+    "timed motion reference evidence durationSeconds must be positive and finite.", errors);
+  requireValue(positive(evidence.overviewTargetFps),
+    "timed motion reference evidence overviewTargetFps must be positive and finite.", errors);
+  requireValue(finite(evidence.maximumSourceFrameGapSeconds) &&
+    evidence.maximumSourceFrameGapSeconds >= 0,
+  "timed motion reference evidence maximumSourceFrameGapSeconds must be finite and nonnegative.", errors);
+  if (evidence.nominalFrameRate !== undefined) requireValue(
+    positive(evidence.nominalFrameRate),
+    "timed motion reference evidence nominalFrameRate must be positive and finite.", errors,
+  );
+  requireValue(Array.isArray(evidence.focusWindows),
+    "timed motion reference evidence focusWindows must be an array.", errors);
+  validateAuthority(evidence, errors);
+  const segmentValid = evidence.segment === undefined ? false :
+    validateStrictRange(evidence.segment, "timed motion reference evidence segment",
+      evidence.durationSeconds, errors);
+  validatePartition(evidence, segmentValid, errors);
+  return evidence.segment !== undefined && segmentValid ? evidence.segment :
+    { endSeconds: durationValid ? evidence.durationSeconds : 0, startSeconds: 0 };
+}
+const EVENT_KEYS = [
+  "afterFrameId", "beforeFrameId", "eventId", "kind", "peakFrameId", "score",
+  "windowFrameIds",
+];
+function expectedLoopFrameIds(evidence) {
+  const lastIndex = evidence.decodedFrameCount - 1;
+  return [...new Set([
+    `source-frame:${lastIndex}`, "source-frame:0",
+    `source-frame:${Math.min(1, lastIndex)}`,
+  ])];
+}
+function isExactLoopEvent(evidence, event, frames) {
+  const shapeErrors = [];
+  if (!hasExactKeys(event, EVENT_KEYS, [], "loop event", shapeErrors) ||
+      shapeErrors.length > 0 || event.kind !== "loop-seam" ||
+      !finite(event.score) || event.score < 0 || event.score > 1 ||
+      !Array.isArray(event.windowFrameIds)) return false;
+  const expectedIds = expectedLoopFrameIds(evidence);
+  return expectedIds.every((frameId) => frames.has(frameId)) &&
+    event.windowFrameIds.length === expectedIds.length &&
+    event.windowFrameIds.every((frameId, index) => frameId === expectedIds[index]) &&
+    event.beforeFrameId === expectedIds[0] &&
+    event.peakFrameId === "source-frame:0" &&
+    event.afterFrameId === expectedIds.at(-1) &&
+    event.eventId === `motion-event:loop-seam:${expectedIds
+      .map((frameId) => frames.get(frameId).sourceFrameIndex).join("-")}`;
+}
+function canonicalExternalSeamFrameIds(evidence, frames) {
+  const partition = evidence.reviewPartition;
+  const completePartitionZero = isRecord(evidence.segment) &&
+    isRecord(partition) && isRecord(partition.scope) &&
+    evidence.segment.startSeconds === 0 && partition?.index === 0 &&
+    partition.scope?.startSeconds === 0 &&
+    partition.scope?.endSeconds === evidence.durationSeconds;
+  if (!completePartitionZero || !Array.isArray(evidence.detectedEvents)) {
+    return new Set();
+  }
+  const loopEvent = evidence.detectedEvents.find((event) =>
+    isExactLoopEvent(evidence, event, frames));
+  if (!loopEvent) return new Set();
+  return new Set(loopEvent.windowFrameIds.filter((frameId) => {
+    const time = frames.get(frameId)?.timeSeconds;
+    return finite(time) && (time < evidence.segment.startSeconds ||
+      time > evidence.segment.endSeconds);
+  }));
+}
+function validateFrameTimes(evidence, activeScope, externalSeamFrameIds, errors) {
+  let previousTime = -Infinity;
+  for (const [index, frame] of evidence.reviewedFrames.entries()) {
+    if (!isRecord(frame)) continue;
+    const inScope = finite(frame.timeSeconds) &&
+      frame.timeSeconds >= activeScope.startSeconds &&
+      frame.timeSeconds <= activeScope.endSeconds;
+    requireValue(inScope || externalSeamFrameIds.has(frame.frameId),
+      `motion reference evidence reviewedFrames[${index}].timeSeconds must be within the active timed scope.`,
+      errors);
+    requireValue(finite(frame.timeSeconds) && frame.timeSeconds > previousTime,
+      `motion reference evidence reviewedFrames[${index}].timeSeconds must be strictly increasing.`,
+      errors);
+    if (finite(frame.timeSeconds)) previousTime = frame.timeSeconds;
+  }
+}
+function validateOverview(evidence, frames, externalSeamFrameIds, errors) {
+  if (!Array.isArray(evidence.overviewFrameIds) || evidence.overviewFrameIds.length === 0) {
+    errors.push("motion reference evidence overviewFrameIds must be a nonempty array.");
+    return;
+  }
+  if (Array.isArray(evidence.reviewedFrames) && evidence.reviewedFrames.length > 0) {
+    requireValue(evidence.overviewFrameIds[0] === evidence.reviewedFrames[0]?.frameId,
+      "motion reference evidence overviewFrameIds must include the first reviewed frame.", errors);
+    requireValue(evidence.overviewFrameIds.at(-1) === evidence.reviewedFrames.at(-1)?.frameId,
+      "motion reference evidence overviewFrameIds must include the last reviewed frame.", errors);
+  }
+  let previousIndex = -1;
+  let previousTime;
+  const seen = new Set();
+  for (const frameId of evidence.overviewFrameIds) {
+    const frame = frames.get(frameId);
+    requireValue(frame !== undefined,
+      `motion reference evidence overview has unknown frame ${String(frameId)}.`, errors);
+    if (!frame) continue;
+    requireValue(frame.sourceFrameIndex > previousIndex && !seen.has(frameId),
+      "motion reference evidence overviewFrameIds must follow canonical reviewed-frame order.", errors);
+    const externalSeamFrame = externalSeamFrameIds.has(frameId);
+    if (!externalSeamFrame && evidence.timingMode === "seconds" &&
+        previousTime !== undefined &&
+        positive(evidence.overviewTargetFps) &&
+        finite(evidence.maximumSourceFrameGapSeconds)) {
+      const allowance = 1 / evidence.overviewTargetFps +
+        evidence.maximumSourceFrameGapSeconds;
+      requireValue(frame.timeSeconds - previousTime <= allowance + Number.EPSILON,
+        "motion reference evidence overview timestamp gap exceeds its recorded density allowance.", errors);
+    }
+    previousIndex = frame.sourceFrameIndex;
+    if (!externalSeamFrame) previousTime = frame.timeSeconds;
+    seen.add(frameId);
+  }
+}
+function validateChangeEvent(event, ids, sourceIndices, label, errors) {
+  const contiguous = ids.length >= 3 && sourceIndices.every((value, index) =>
+    nonnegativeInteger(value) && (index === 0 || value === sourceIndices[index - 1] + 1));
+  requireValue(contiguous,
+    `${label} change window must use strictly contiguous source-frame order.`, errors);
+  requireValue(event.beforeFrameId === ids[0] && event.afterFrameId === ids.at(-1) &&
+    ids.includes(event.peakFrameId),
+  `${label} change window must bind before, peak, and after frames.`, errors);
+  const peakIndex = sourceIndices[ids.indexOf(event.peakFrameId)];
+  requireValue(nonnegativeInteger(peakIndex) && peakIndex > sourceIndices[0] &&
+    peakIndex < sourceIndices.at(-1),
+  `${label} change peak must be strictly interior to its frame window.`, errors);
+}
+function validateLoopEvent(evidence, event, ids, label, frames, errors) {
+  requireValue(isExactLoopEvent(evidence, event, frames),
+    `${label} loop-seam must use the exact cyclic source endpoint window.`, errors);
+}
+function validateEvents(evidence, frames, errors) {
+  if (!Array.isArray(evidence.detectedEvents)) {
+    errors.push("motion reference evidence detectedEvents must be an array.");
+    return;
+  }
+  const seen = new Set();
+  for (const [index, event] of evidence.detectedEvents.entries()) {
+    const label = `motion reference evidence event[${index}]`;
+    if (!hasExactKeys(event, EVENT_KEYS, [], label, errors)) continue;
+    requireValue(event.kind === "change" || event.kind === "loop-seam",
+      `${label}.kind is invalid.`, errors);
+    requireValue(finite(event.score) && event.score >= 0 && event.score <= 1,
+      `${label}.score must be within [0, 1].`, errors);
+    const ids = Array.isArray(event.windowFrameIds) ? event.windowFrameIds : [];
+    requireValue(ids.length > 0, `${label}.windowFrameIds must be nonempty.`, errors);
+    for (const frameId of new Set([
+      ...ids, event.beforeFrameId, event.peakFrameId, event.afterFrameId,
+    ])) requireValue(frames.has(frameId),
+      `${label} references unknown frame ${String(frameId)}.`, errors);
+    const sourceIndices = ids.map((id) => frames.get(id)?.sourceFrameIndex);
+    if (event.kind === "change") {
+      validateChangeEvent(event, ids, sourceIndices, label, errors);
+    } else if (event.kind === "loop-seam") {
+      validateLoopEvent(evidence, event, ids, label, frames, errors);
+    }
+    requireValue(event.eventId ===
+      `motion-event:${event.kind}:${sourceIndices.join("-")}`,
+    `${label}.eventId must be canonical for its complete frame window.`, errors);
+    requireValue(!seen.has(event.eventId), `${label}.eventId is duplicated.`, errors);
+    seen.add(event.eventId);
+  }
+}
+function validateFocusWindows(evidence, frames, activeScope, errors) {
+  if (!Array.isArray(evidence.focusWindows)) return;
+  let previousStartIndex = -1;
+  for (const [index, focus] of evidence.focusWindows.entries()) {
+    const label = `motion reference evidence focusWindows[${index}]`;
+    if (!hasExactKeys(focus, ["endSeconds", "frameIds", "sourceFrameEndIndex",
+      "sourceFrameStartIndex", "startSeconds"], [], label, errors)) continue;
+    const rangeValid = finite(focus.startSeconds) && finite(focus.endSeconds) &&
+      focus.startSeconds >= activeScope.startSeconds &&
+      focus.endSeconds > focus.startSeconds &&
+      focus.endSeconds <= activeScope.endSeconds;
+    requireValue(rangeValid,
+      `${label} must have positive duration bounded by the active timed scope.`, errors);
+    if (!Array.isArray(focus.frameIds)) {
+      errors.push(`${label}.frameIds must be a nonempty array.`);
+      continue;
+    }
+    const derivedFrames = rangeValid && Array.isArray(evidence.reviewedFrames) ?
+      evidence.reviewedFrames.filter((frame) => isRecord(frame) &&
+        finite(frame.timeSeconds) && frame.timeSeconds >= focus.startSeconds &&
+        frame.timeSeconds <= focus.endSeconds) : [];
+    const derivedIds = derivedFrames.map(({ frameId }) => frameId);
+    const sourceIndices = derivedFrames.map(({ sourceFrameIndex }) => sourceFrameIndex);
+    requireValue(derivedIds.length > 0,
+      `${label} must derive a nonempty reviewed-frame membership.`, errors);
+    requireValue(focus.frameIds.length === derivedIds.length &&
+      focus.frameIds.every((frameId, position) => frameId === derivedIds[position]),
+    `${label}.frameIds must equal the exact ordered membership of reviewed frames in its timed range.`,
+    errors);
+    const contiguous = sourceIndices.length > 0 && sourceIndices.every((value, position) =>
+      nonnegativeInteger(value) &&
+      (position === 0 || value === sourceIndices[position - 1] + 1));
+    requireValue(contiguous, `${label}.frameIds must cover contiguous source indices.`, errors);
+    requireValue(focus.sourceFrameStartIndex === sourceIndices[0] &&
+      focus.sourceFrameEndIndex === sourceIndices.at(-1),
+    `${label} source bounds must match its first and last referenced frames.`, errors);
+    requireValue(sourceIndices[0] >= previousStartIndex,
+      `${label} must follow canonical source-frame order.`, errors);
+    if (nonnegativeInteger(sourceIndices[0])) previousStartIndex = sourceIndices[0];
+  }
+}
+
+export function validateToolcraftMotionReferenceTimingAndWindows(
+  evidence,
+  frames,
+  errors,
+) {
+  let activeScope;
+  let externalSeamFrameIds = new Set();
+  if (evidence.timingMode === "ordinal") {
+    requireValue(Array.isArray(evidence.focusWindows) && evidence.focusWindows.length === 0,
+      "ordinal motion reference evidence focusWindows must be an empty array.", errors);
+  } else if (evidence.timingMode === "seconds") {
+    activeScope = validateTimedShape(evidence, errors);
+    if (Array.isArray(evidence.reviewedFrames)) {
+      externalSeamFrameIds = canonicalExternalSeamFrameIds(evidence, frames);
+      validateFrameTimes(evidence, activeScope, externalSeamFrameIds, errors);
+    }
+  }
+  validateOverview(evidence, frames, externalSeamFrameIds, errors);
+  validateEvents(evidence, frames, errors);
+  if (evidence.timingMode === "seconds") {
+    validateFocusWindows(evidence, frames, activeScope, errors);
+  }
+}

package/templates/starter/src/app/acceptance/motion-reference-evidence.d.mts

@@ -0,0 +1,11 @@
+import type { ToolcraftMotionReferenceEvidence } from "./reference-study-types";
+
+export function defineToolcraftMotionReferenceEvidence(
+  value: unknown,
+): ToolcraftMotionReferenceEvidence;
+export function getToolcraftMotionReferenceEvidenceErrors(
+  value: unknown,
+): string[];
+export function writeCanonicalToolcraftMotionReferenceEvidence(
+  evidence: ToolcraftMotionReferenceEvidence,
+): string;

package/templates/starter/src/app/acceptance/motion-reference-evidence.mjs

@@ -0,0 +1,145 @@
+import {
+  validateToolcraftMotionReferenceTimingAndWindows,
+} from "./motion-reference-evidence-windows.mjs";
+import {
+  hasExactKeys,
+  isRecord,
+  isSha256,
+  isStudyId,
+  nonemptyString,
+  nonnegativeInteger,
+  positiveInteger,
+  requireValue,
+} from "./motion-reference-evidence-validation.mjs";
+
+const SOURCE_KINDS = new Set([
+  "contact-sheet", "frame-sequence", "gif", "screen-recording", "video",
+]);
+function validateContactSheet(sheet, evidence, errors) {
+  const label = "motion reference evidence contactSheet";
+  if (!hasExactKeys(sheet,
+    ["columns", "height", "path", "rows", "sha256", "width"], [], label, errors)) return;
+  requireValue(positiveInteger(sheet.columns), `${label}.columns must be a positive safe integer.`, errors);
+  requireValue(positiveInteger(sheet.rows), `${label}.rows must be a positive safe integer.`, errors);
+  requireValue(positiveInteger(sheet.width), `${label}.width must be a positive safe integer.`, errors);
+  requireValue(positiveInteger(sheet.height), `${label}.height must be a positive safe integer.`, errors);
+  requireValue(isSha256(sheet.sha256), `${label}.sha256 must be a lowercase SHA-256 hash.`, errors);
+  requireValue(
+    sheet.path === `src/app/reference-studies/${evidence.studyId}/contact-sheet.png`,
+    `${label}.path must name the contact sheet in the canonical study directory.`, errors,
+  );
+}
+function validateSource(evidence, errors) {
+  requireValue(SOURCE_KINDS.has(evidence.sourceKind),
+    "motion reference evidence sourceKind is unsupported.", errors);
+  requireValue(isSha256(evidence.sourceSha256),
+    "motion reference evidence sourceSha256 must be a lowercase SHA-256 hash.", errors);
+  requireValue(nonemptyString(evidence.sourceBasename) &&
+    !/[\\/]/u.test(evidence.sourceBasename),
+  "motion reference evidence sourceBasename must be a basename.", errors);
+  if (evidence.sourceKind === "contact-sheet") {
+    if (hasExactKeys(evidence.sourceGrid, ["columns", "rows"], [],
+      "motion reference evidence sourceGrid", errors)) {
+      requireValue(positiveInteger(evidence.sourceGrid.columns) &&
+        positiveInteger(evidence.sourceGrid.rows),
+      "motion reference evidence sourceGrid dimensions must be positive safe integers.", errors);
+    }
+  }
+}
+function validateFrames(evidence, errors) {
+  if (!Array.isArray(evidence.reviewedFrames)) {
+    errors.push("motion reference evidence reviewedFrames must be an array.");
+    return new Map();
+  }
+  requireValue(evidence.reviewedFrames.length > 0 && evidence.reviewedFrames.length <= 120,
+    "motion reference evidence must contain between 1 and at most 120 reviewed frames.", errors);
+  const frames = new Map();
+  let previousIndex = -1;
+  for (const [position, frame] of evidence.reviewedFrames.entries()) {
+    const label = `motion reference evidence reviewedFrames[${position}]`;
+    const keys = ["cell", "frameId", "sourceFrameIndex", "sourceLocator", "sourceSha256",
+      ...(evidence.timingMode === "seconds" ? ["timeSeconds"] : [])];
+    if (!hasExactKeys(frame, keys, [], label, errors)) continue;
+    if (hasExactKeys(frame.cell, ["column", "row"], [], `${label}.cell`, errors)) {
+      requireValue(nonnegativeInteger(frame.cell.column) && nonnegativeInteger(frame.cell.row),
+        `${label}.cell coordinates must be nonnegative safe integers.`, errors);
+      requireValue(frame.cell.column === position % evidence.contactSheet?.columns &&
+        frame.cell.row === Math.floor(position / evidence.contactSheet?.columns),
+      `${label}.cell must follow canonical contact-sheet order.`, errors);
+    }
+    requireValue(nonnegativeInteger(frame.sourceFrameIndex) &&
+      frame.sourceFrameIndex < evidence.decodedFrameCount &&
+      frame.sourceFrameIndex > previousIndex,
+      `${label}.sourceFrameIndex must be in strictly increasing order.`, errors);
+    requireValue(frame.frameId === `source-frame:${frame.sourceFrameIndex}`,
+      `${label}.frameId must be canonical for its sourceFrameIndex.`, errors);
+    requireValue(nonemptyString(frame.sourceLocator), `${label}.sourceLocator must be nonempty.`, errors);
+    requireValue(frame.sourceSha256 === evidence.sourceSha256 && isSha256(frame.sourceSha256),
+      `${label}.sourceSha256 must match the evidence source hash.`, errors);
+    previousIndex = frame.sourceFrameIndex;
+    if (frames.has(frame.frameId)) errors.push(`${label}.frameId is duplicated.`);
+    frames.set(frame.frameId, frame);
+  }
+  if (positiveInteger(evidence.contactSheet?.columns)) {
+    requireValue(evidence.contactSheet.rows ===
+      Math.ceil(evidence.reviewedFrames.length / evidence.contactSheet.columns),
+    "motion reference evidence contactSheet.rows must fit reviewedFrames exactly.", errors);
+  }
+  return frames;
+}
+
+export function getToolcraftMotionReferenceEvidenceErrors(value) {
+  const errors = [];
+  const timingMode = value?.timingMode;
+  const sourceKind = value?.sourceKind;
+  const required = ["changeMetric", "contactSheet", "decodedFrameCount", "detectedEvents",
+    "evidenceVersion", "ffmpegVersion", "ffprobeVersion", "focusWindows", "height",
+    "overviewFrameIds", "reviewedFrames", "scannedFrameCount", "sourceBasename",
+    "sourceKind", "sourceSha256", "studyId", "timingMode", "width",
+    ...(sourceKind === "contact-sheet" ? ["sourceGrid"] : []),
+    ...(timingMode === "seconds" ? ["durationSeconds", "maximumSourceFrameGapSeconds",
+      "overviewTargetFps", "timing"] : [])];
+  const optional = timingMode === "seconds" ?
+    ["nominalFrameRate", "reviewPartition", "segment"] : [];
+  if (!hasExactKeys(value, required, optional, "motion reference evidence", errors)) return errors;
+  requireValue(value.evidenceVersion === 1, "motion reference evidence evidenceVersion must be 1.", errors);
+  requireValue(value.changeMetric === "max-yuva-diff-v1", "motion reference evidence changeMetric is invalid.", errors);
+  requireValue(isStudyId(value.studyId), "motion reference evidence studyId must match motion-v1-<64 lowercase hex>.", errors);
+  requireValue(positiveInteger(value.decodedFrameCount) && positiveInteger(value.scannedFrameCount),
+    "motion reference evidence frame counts must be positive safe integers.", errors);
+  requireValue(value.decodedFrameCount === value.scannedFrameCount,
+    "motion reference evidence decodedFrameCount must equal scannedFrameCount.", errors);
+  requireValue(positiveInteger(value.width) && positiveInteger(value.height),
+    "motion reference evidence dimensions must be positive safe integers.", errors);
+  requireValue(nonemptyString(value.ffmpegVersion) && nonemptyString(value.ffprobeVersion),
+    "motion reference evidence tool versions must be nonempty.", errors);
+  requireValue(value.timingMode === "ordinal" || value.timingMode === "seconds",
+    "motion reference evidence timingMode is invalid.", errors);
+  validateSource(value, errors);
+  validateContactSheet(value.contactSheet, value, errors);
+  const frames = validateFrames(value, errors);
+  validateToolcraftMotionReferenceTimingAndWindows(value, frames, errors);
+  return errors;
+}
+
+function deepFreeze(value) {
+  if (value !== null && typeof value === "object" && !Object.isFrozen(value)) {
+    for (const child of Object.values(value)) deepFreeze(child);
+    Object.freeze(value);
+  }
+  return value;
+}
+export function defineToolcraftMotionReferenceEvidence(value) {
+  const errors = getToolcraftMotionReferenceEvidenceErrors(value);
+  if (errors.length > 0) throw new TypeError(`Invalid Toolcraft motion reference evidence:\n${errors.join("\n")}`);
+  return deepFreeze(value);
+}
+function sortJson(value) {
+  if (Array.isArray(value)) return value.map(sortJson);
+  if (isRecord(value)) return Object.fromEntries(Object.keys(value).sort()
+    .map((key) => [key, sortJson(value[key])]));
+  return value;
+}
+export function writeCanonicalToolcraftMotionReferenceEvidence(evidence) {
+  return `${JSON.stringify(sortJson(evidence), null, 2)}\n`;
+}

package/templates/starter/src/app/acceptance/motion-reference-study-behaviors.ts

@@ -0,0 +1,162 @@
+import type {
+  ToolcraftComponentAcceptance,
+  ToolcraftMotionReferenceInput,
+} from "./types";
+
+type AcceptanceRowsById = ReadonlyMap<
+  string,
+  readonly ToolcraftComponentAcceptance[]
+>;
+
+function validateAcceptanceFields({
+  acceptance,
+  behaviorId,
+}: {
+  acceptance: ToolcraftComponentAcceptance;
+  behaviorId: string;
+}): string[] {
+  const errors: string[] = [];
+  if (!acceptance.automated || !acceptance.automatedTestName.trim()) {
+    errors.push(
+      `motion reference behavior "${behaviorId}" acceptance "${acceptance.id}" must have automated coverage.`,
+    );
+  }
+  if (!acceptance.browser || !acceptance.browserTestName.trim()) {
+    errors.push(
+      `motion reference behavior "${behaviorId}" acceptance "${acceptance.id}" must have browser coverage.`,
+    );
+  }
+  if (!acceptance.expectedObservable.trim()) {
+    errors.push(
+      `motion reference behavior "${behaviorId}" acceptance "${acceptance.id}" must describe its observable result.`,
+    );
+  }
+  return errors;
+}
+
+export function validateBehaviorCoverage(
+  input: ToolcraftMotionReferenceInput,
+  acceptanceRowsById: AcceptanceRowsById,
+): string[] {
+  const errors: string[] = [];
+  const studiesById = new Map<
+    string,
+    ToolcraftMotionReferenceInput["studies"]
+  >();
+  const usedBehaviorIds = new Set<string>();
+
+  for (const study of input.studies) {
+    studiesById.set(study.studyId, [
+      ...(studiesById.get(study.studyId) ?? []),
+      study,
+    ]);
+    for (const phase of study.phases) {
+      phase.behaviorIds.forEach((behaviorId) => usedBehaviorIds.add(behaviorId));
+    }
+    for (const event of study.events) {
+      if (event.classification === "product-behavior") {
+        event.behaviorIds.forEach((behaviorId) => usedBehaviorIds.add(behaviorId));
+      }
+    }
+  }
+
+  for (const behavior of input.behaviors) {
+    if (!behavior.description.trim()) {
+      errors.push(
+        `motion reference behavior "${behavior.id}" must include a non-empty description.`,
+      );
+    }
+    if (!behavior.implementationIntent.trim()) {
+      errors.push(
+        `motion reference behavior "${behavior.id}" must include a non-empty implementationIntent.`,
+      );
+    }
+    if (!usedBehaviorIds.has(behavior.id)) {
+      errors.push(
+        `motion reference behavior "${behavior.id}" must be used by a phase or product event.`,
+      );
+    }
+
+    const timingClaimStudies = new Map<string, Set<string>>();
+    for (const timingClaim of behavior.timingClaims) {
+      const studyIds = timingClaimStudies.get(timingClaim.claim) ?? new Set();
+      if (studyIds.has(timingClaim.studyId)) {
+        errors.push(
+          `motion reference behavior "${behavior.id}" timing claim "${timingClaim.claim}" for study "${timingClaim.studyId}" is duplicated.`,
+        );
+      }
+      studyIds.add(timingClaim.studyId);
+      timingClaimStudies.set(timingClaim.claim, studyIds);
+
+      const studies = studiesById.get(timingClaim.studyId) ?? [];
+      if (studies.length === 0) {
+        errors.push(
+          `motion reference behavior "${behavior.id}" timing claim "${timingClaim.claim}" names missing study "${timingClaim.studyId}".`,
+        );
+      } else if (studies.length > 1) {
+        errors.push(
+          `motion reference behavior "${behavior.id}" timing claim "${timingClaim.claim}" studyId "${timingClaim.studyId}" resolves to ${studies.length} studies; expected exactly one.`,
+        );
+      } else {
+        const [study] = studies;
+        if (study.evidence.timingMode !== "seconds") {
+          errors.push(
+            `motion reference behavior "${behavior.id}" timing claim "${timingClaim.claim}" must name a seconds-timed study; "${timingClaim.studyId}" is ordinal.`,
+          );
+        }
+      }
+    }
+
+    const acceptanceRows = acceptanceRowsById.get(behavior.acceptanceId) ?? [];
+    if (acceptanceRows.length === 0) {
+      errors.push(
+        `motion reference behavior "${behavior.id}" points to missing acceptanceId "${behavior.acceptanceId}".`,
+      );
+      continue;
+    }
+    for (const acceptance of acceptanceRows) {
+      errors.push(...validateAcceptanceFields({ acceptance, behaviorId: behavior.id }));
+    }
+    if (acceptanceRows.length > 1) {
+      errors.push(
+        `motion reference behavior "${behavior.id}" acceptanceId "${behavior.acceptanceId}" resolves to ${acceptanceRows.length} acceptance rows; expected exactly one.`,
+      );
+      continue;
+    }
+    const [acceptance] = acceptanceRows;
+
+    const matchingReverseCoverage = (
+      acceptance.motionReferenceCoverage ?? []
+    ).filter(
+      (coverage) =>
+        coverage.referenceId === input.referenceId &&
+        coverage.behaviorId === behavior.id,
+    );
+    if (matchingReverseCoverage.length !== 1) {
+      errors.push(
+        `motion reference behavior "${behavior.id}" acceptance "${acceptance.id}" must own exactly one reverse coverage pair; found ${matchingReverseCoverage.length}.`,
+      );
+    }
+
+    let coverageOwnerCount = 0;
+    for (const rows of acceptanceRowsById.values()) {
+      for (const entry of rows) {
+        const ownsCoverage = (entry.motionReferenceCoverage ?? []).some(
+          (coverage) =>
+            coverage.referenceId === input.referenceId &&
+            coverage.behaviorId === behavior.id,
+        );
+        if (ownsCoverage) {
+          coverageOwnerCount += 1;
+        }
+      }
+    }
+    if (coverageOwnerCount > 1) {
+      errors.push(
+        `motion reference behavior "${behavior.id}" coverage pair has ${coverageOwnerCount} acceptance owners; expected exactly one.`,
+      );
+    }
+  }
+
+  return errors;
+}