@pixel-point/toolcraft 0.0.18 → 0.0.19

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

@@ -0,0 +1,65 @@
+const SHA256 = /^[a-f0-9]{64}$/u;
+const STUDY_ID = /^motion-v1-[a-f0-9]{64}$/u;
+const GROUP_ID = /^motion-group-v1-[a-f0-9]{64}$/u;
+
+export function isRecord(value) {
+  return value !== null && typeof value === "object" && !Array.isArray(value) &&
+    (Object.getPrototypeOf(value) === Object.prototype ||
+      Object.getPrototypeOf(value) === null);
+}
+
+export function hasExactKeys(
+  value,
+  required,
+  optional,
+  label,
+  errors,
+) {
+  if (!isRecord(value)) {
+    errors.push(`${label} must be an object.`);
+    return false;
+  }
+  const allowed = new Set([...required, ...optional]);
+  let exact = true;
+  for (const key of required) {
+    if (!Object.hasOwn(value, key)) {
+      errors.push(`${label} is missing ${key}.`);
+      exact = false;
+    }
+  }
+  for (const key of Object.keys(value)) {
+    if (!allowed.has(key)) {
+      errors.push(`${label} has unknown property ${key}.`);
+      exact = false;
+    }
+  }
+  return exact;
+}
+
+export function finite(value) {
+  return typeof value === "number" && Number.isFinite(value);
+}
+export function positive(value) {
+  return finite(value) && value > 0;
+}
+export function positiveInteger(value) {
+  return Number.isSafeInteger(value) && value > 0;
+}
+export function nonnegativeInteger(value) {
+  return Number.isSafeInteger(value) && value >= 0;
+}
+export function nonemptyString(value) {
+  return typeof value === "string" && value.trim().length > 0;
+}
+export function isSha256(value) {
+  return typeof value === "string" && SHA256.test(value);
+}
+export function isStudyId(value) {
+  return typeof value === "string" && STUDY_ID.test(value);
+}
+export function isGroupId(value) {
+  return typeof value === "string" && GROUP_ID.test(value);
+}
+export function requireValue(condition, message, errors) {
+  if (!condition) errors.push(message);
+}

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`;
+}