@pixel-point/toolcraft 0.0.17 → 0.0.19

package/templates/starter/scripts/toolcraft-motion-reference-evidence-assembly.mjs

@@ -0,0 +1,270 @@
+import path from "node:path";
+
+import {
+  defineToolcraftMotionReferenceEvidence,
+  writeCanonicalToolcraftMotionReferenceEvidence,
+} from "../src/app/acceptance/motion-reference-evidence.mjs";
+import {
+  createToolcraftMotionReferenceGroupId,
+  createToolcraftMotionReferencePlanSha256,
+  createToolcraftMotionReferenceStudyId,
+  createToolcraftSha256,
+} from "./toolcraft-motion-reference-artifacts.mjs";
+import {
+  createToolcraftMotionReviewSelection,
+  TOOLCRAFT_MOTION_OVERVIEW_FPS,
+} from "./toolcraft-motion-reference-sampling.mjs";
+
+function samplingInput(inspection, scan, options) {
+  if (inspection.timingMode === "ordinal") return {
+    input: {
+      changeScores: scan.changeScores,
+      frameCount: inspection.decodedFrameCount,
+      loopSeamScore: scan.loopSeamScore,
+      timingMode: "ordinal",
+    },
+    sourceIndices: Array.from({ length: inspection.decodedFrameCount }, (_, index) => index),
+  };
+  const sourceRange = { endSeconds: inspection.durationSeconds, startSeconds: 0 };
+  const range = options.segment ?? sourceRange;
+  const sourceIndices = inspection.frameTimes.flatMap((time, index) =>
+    time >= range.startSeconds && time <= range.endSeconds ? [index] : []);
+  if (sourceIndices.length === 0) {
+    throw new TypeError("Toolcraft motion reference segment contains no decoded frames.");
+  }
+  return {
+    input: {
+      changeScores: sourceIndices.map((index, position) =>
+        position === 0 && index > 0 ? 0 : scan.changeScores[index]),
+      focusWindows: options.focus ?? [],
+      frameTimes: sourceIndices.map((index) => inspection.frameTimes[index]),
+      loopSeamScore: scan.loopSeamScore,
+      ...(inspection.nominalFrameRate ? {
+        nominalFrameRate: inspection.nominalFrameRate,
+      } : {}),
+      range,
+      sourceRange,
+      timingMode: "seconds",
+    },
+    sourceIndices,
+  };
+}
+
+function remapSelection(selection, sourceIndices) {
+  const globalIndex = (index) => sourceIndices[index];
+  const events = selection.events.map((event) => {
+    const frameIndices = event.frameIndices.map(globalIndex);
+    const peakFrameIndex = globalIndex(event.peakFrameIndex);
+    return {
+      ...event,
+      eventId: `motion-event:${event.kind}:${frameIndices.join("-")}`,
+      frameIds: frameIndices.map((index) => `source-frame:${index}`),
+      frameIndices,
+      peakFrameId: `source-frame:${peakFrameIndex}`,
+      peakFrameIndex,
+    };
+  });
+  const eventIds = new Map(selection.events.map((event, index) =>
+    [event.eventId, events[index].eventId]));
+  return {
+    ...selection,
+    events,
+    focusWindows: selection.focusWindows.map((focus) => ({
+      ...focus, frameIndices: focus.frameIndices.map(globalIndex),
+    })),
+    ...(selection.kind === "selection" ? {
+      overviewFrameIndices: selection.overviewFrameIndices.map(globalIndex),
+      reviewFrameIndices: selection.reviewFrameIndices.map(globalIndex),
+    } : {
+      partitions: selection.partitions.map((partition) => ({
+        ...partition,
+        eventIds: partition.eventIds.map((id) => eventIds.get(id)),
+        reviewFrameIndices: partition.reviewFrameIndices.map(globalIndex),
+      })),
+    }),
+  };
+}
+
+function studyPlans(selection, options) {
+  if (selection.kind === "selection") return [{
+    eventIds: selection.events.map(({ eventId }) => eventId),
+    focusWindows: selection.focusWindows,
+    index: 0,
+    overviewFrameIndices: selection.overviewFrameIndices,
+    reviewFrameIndices: selection.reviewFrameIndices,
+    ...(options.segment ? { segment: options.segment } : {}),
+  }];
+  const count = selection.partitions.length;
+  const scope = options.segment ?? {
+    endSeconds: selection.partitions.at(-1).endSeconds,
+    startSeconds: selection.partitions[0].startSeconds,
+  };
+  return selection.partitions.map((partition) => {
+    const membership = new Set(partition.reviewFrameIndices);
+    return {
+      eventIds: partition.eventIds,
+      focusWindows: selection.focusWindows.filter(({ frameIndices }) =>
+        frameIndices.every((index) => membership.has(index))),
+      index: partition.index,
+      overviewFrameIndices: selection.overviewFrameIndices.filter((index) =>
+        membership.has(index)),
+      partition: { count, index: partition.index, scope },
+      reviewFrameIndices: partition.reviewFrameIndices,
+      segment: { endSeconds: partition.endSeconds, startSeconds: partition.startSeconds },
+    };
+  });
+}
+
+export function createToolcraftMotionEvidenceReviewPlan(inspection, scan, options) {
+  const sampling = samplingInput(inspection, scan, options);
+  const selected = createToolcraftMotionReviewSelection(sampling.input);
+  if (selected.kind === "error") throw new TypeError(
+    selected.code === "ordinal-review-too-large" ?
+      "Ordinal motion reference review above 120 frames is unsupported; declare authoritative timing or provide a bounded source." :
+      `Motion reference review cannot be safely partitioned (${selected.code}).`,
+  );
+  const selection = remapSelection(selected, sampling.sourceIndices);
+  const plans = studyPlans(selection, options);
+  return {
+    plans,
+    selection,
+    unionSourceFrameIndices: [...new Set(plans.flatMap(({ reviewFrameIndices }) =>
+      reviewFrameIndices))].sort((left, right) => left - right),
+  };
+}
+
+function timingAuthority(options) {
+  if (!options.timing) return { authority: "decoded-timestamps" };
+  return options.timing.authority === "declared-fps" ? {
+    authority: "declared-fps", framesPerSecond: options.timing.framesPerSecond,
+  } : {
+    authority: "declared-timestamps",
+    timestampsSha256: options.timing.timestampsSha256,
+  };
+}
+function maximumFrameGap(frameTimes) {
+  let maximum = 0;
+  for (let index = 1; index < frameTimes.length; index += 1) {
+    maximum = Math.max(maximum, frameTimes[index] - frameTimes[index - 1]);
+  }
+  return maximum;
+}
+function evidenceEvents(events, eventIds) {
+  const selected = new Set(eventIds);
+  return events.filter(({ eventId }) => selected.has(eventId)).map((event) => ({
+    afterFrameId: event.frameIds.at(-1), beforeFrameId: event.frameIds[0],
+    eventId: event.eventId, kind: event.kind, peakFrameId: event.peakFrameId,
+    score: event.score, windowFrameIds: event.frameIds,
+  }));
+}
+function identitySeed(inspection, sourceSha256, segment, timing) {
+  return {
+    evidenceVersion: 1,
+    ...(inspection.sourceGrid ? { sourceGrid: inspection.sourceGrid } : {}),
+    ...(segment ? { segment } : {}),
+    sourceKind: inspection.sourceKind,
+    sourceSha256,
+    ...(inspection.timingMode === "seconds" ? { timing } : {}),
+    timingMode: inspection.timingMode,
+  };
+}
+function evidenceFocus(focusWindows, reviewedFrames) {
+  return focusWindows.map((focus) => {
+    const frames = reviewedFrames.filter(({ timeSeconds }) =>
+      timeSeconds >= focus.startSeconds && timeSeconds <= focus.endSeconds);
+    return {
+      endSeconds: focus.endSeconds,
+      frameIds: frames.map(({ frameId }) => frameId),
+      sourceFrameEndIndex: frames.at(-1).sourceFrameIndex,
+      sourceFrameStartIndex: frames[0].sourceFrameIndex,
+      startSeconds: focus.startSeconds,
+    };
+  });
+}
+
+async function stageOne(input, plan) {
+  const { dependencies, inspection, materializedByIndex, options, scan,
+    selection, sourceSha256, stagingRoot } = input;
+  const timing = inspection.timingMode === "seconds" ? timingAuthority(options) : undefined;
+  const seed = identitySeed(inspection, sourceSha256, plan.segment, timing);
+  const studyId = createToolcraftMotionReferenceStudyId(seed);
+  const stagingDirectory = path.join(stagingRoot, studyId);
+  await dependencies.fileSystem.mkdir(stagingDirectory);
+  const frames = plan.reviewFrameIndices.map((index) => materializedByIndex.get(index));
+  const sheetPath = path.join(stagingDirectory, "contact-sheet.png");
+  const sheet = await dependencies.createContactSheet({
+    execute: dependencies.execute, frames, outputPath: sheetPath,
+    sourceHeight: inspection.height, sourceWidth: inspection.width,
+  });
+  const reviewedFrames = frames.map((frame, index) => ({
+    cell: { column: sheet.cells[index].column, row: sheet.cells[index].row },
+    frameId: `source-frame:${frame.sourceFrameIndex}`,
+    sourceFrameIndex: frame.sourceFrameIndex, sourceLocator: frame.sourceLocator,
+    sourceSha256,
+    ...(inspection.timingMode === "seconds" ? {
+      timeSeconds: inspection.frameTimes[frame.sourceFrameIndex],
+    } : {}),
+  }));
+  const overviewSet = new Set(plan.overviewFrameIndices);
+  const overviewFrameIds = reviewedFrames.filter(({ sourceFrameIndex }, index) =>
+    overviewSet.has(sourceFrameIndex) || index === 0 || index === reviewedFrames.length - 1)
+    .map(({ frameId }) => frameId);
+  const relativeDirectory = path.posix.join("src/app/reference-studies", studyId);
+  return {
+    raw: {
+      changeMetric: scan.changeMetric,
+      contactSheet: {
+        columns: sheet.columns, height: sheet.height,
+        path: path.posix.join(relativeDirectory, "contact-sheet.png"),
+        rows: sheet.rows,
+        sha256: createToolcraftSha256(await dependencies.fileSystem.readFile(sheetPath)),
+        width: sheet.width,
+      },
+      decodedFrameCount: inspection.decodedFrameCount,
+      detectedEvents: evidenceEvents(selection.events, plan.eventIds),
+      evidenceVersion: 1, ffmpegVersion: inspection.ffmpegVersion,
+      ffprobeVersion: inspection.ffprobeVersion,
+      focusWindows: inspection.timingMode === "seconds" ?
+        evidenceFocus(plan.focusWindows, reviewedFrames) : [],
+      height: inspection.height, overviewFrameIds, reviewedFrames,
+      scannedFrameCount: scan.scannedFrameCount,
+      sourceBasename: inspection.sourceBasename, sourceKind: inspection.sourceKind,
+      sourceSha256, studyId, timingMode: inspection.timingMode, width: inspection.width,
+      ...(inspection.sourceGrid ? { sourceGrid: inspection.sourceGrid } : {}),
+      ...(inspection.timingMode === "seconds" ? {
+        durationSeconds: inspection.durationSeconds,
+        maximumSourceFrameGapSeconds: maximumFrameGap(inspection.frameTimes),
+        ...(inspection.nominalFrameRate ? { nominalFrameRate: inspection.nominalFrameRate } : {}),
+        overviewTargetFps: TOOLCRAFT_MOTION_OVERVIEW_FPS,
+        ...(plan.partition ? { reviewPartition: {
+          ...plan.partition,
+          groupId: createToolcraftMotionReferenceGroupId(seed, plan.partition.scope),
+          planSha256: "0".repeat(64),
+        } } : {}),
+        ...(plan.segment ? { segment: plan.segment } : {}), timing,
+      } : {}),
+    },
+    stagingDirectory,
+  };
+}
+
+export async function stageToolcraftMotionReferenceEvidences(input) {
+  const records = [];
+  for (const plan of input.review.plans) records.push(await stageOne({
+    ...input, selection: input.review.selection,
+  }, plan));
+  if (records.length > 1) {
+    const planSha256 = createToolcraftMotionReferencePlanSha256(
+      records.map(({ raw }) => raw),
+    );
+    records.forEach(({ raw }) => { raw.reviewPartition.planSha256 = planSha256; });
+  }
+  return Promise.all(records.map(async ({ raw, stagingDirectory }) => {
+    const evidence = defineToolcraftMotionReferenceEvidence(raw);
+    await input.dependencies.fileSystem.writeFile(
+      path.join(stagingDirectory, "evidence.json"),
+      writeCanonicalToolcraftMotionReferenceEvidence(evidence),
+    );
+    return { evidence, stagingDirectory };
+  }));
+}

package/templates/starter/scripts/toolcraft-motion-reference-evidence.test.mjs

@@ -0,0 +1,432 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  defineToolcraftMotionReferenceEvidence,
+  getToolcraftMotionReferenceEvidenceErrors,
+  writeCanonicalToolcraftMotionReferenceEvidence,
+} from "../src/app/acceptance/motion-reference-evidence.mjs";
+
+const hex = (character) => character.repeat(64);
+
+function createEvidence() {
+  const sourceSha256 = hex("a");
+  const reviewedFrames = Array.from({ length: 5 }, (_, sourceFrameIndex) => ({
+    cell: { column: sourceFrameIndex % 3, row: Math.floor(sourceFrameIndex / 3) },
+    frameId: `source-frame:${sourceFrameIndex}`,
+    sourceFrameIndex,
+    sourceLocator: `reference.mp4#frame=${sourceFrameIndex}`,
+    sourceSha256,
+    timeSeconds: sourceFrameIndex,
+  }));
+  return {
+    changeMetric: "max-yuva-diff-v1",
+    contactSheet: {
+      columns: 3,
+      height: 200,
+      path: `src/app/reference-studies/motion-v1-${hex("b")}/contact-sheet.png`,
+      rows: 2,
+      sha256: hex("c"),
+      width: 300,
+    },
+    decodedFrameCount: 5,
+    detectedEvents: [{
+      afterFrameId: "source-frame:3",
+      beforeFrameId: "source-frame:1",
+      eventId: "motion-event:change:1-2-3",
+      kind: "change",
+      peakFrameId: "source-frame:2",
+      score: 0.8,
+      windowFrameIds: ["source-frame:1", "source-frame:2", "source-frame:3"],
+    }],
+    durationSeconds: 4,
+    evidenceVersion: 1,
+    ffmpegVersion: "ffmpeg 8.0",
+    ffprobeVersion: "ffprobe 8.0",
+    focusWindows: [{
+      endSeconds: 2,
+      frameIds: ["source-frame:1", "source-frame:2"],
+      sourceFrameEndIndex: 2,
+      sourceFrameStartIndex: 1,
+      startSeconds: 1,
+    }],
+    height: 180,
+    maximumSourceFrameGapSeconds: 0.2,
+    nominalFrameRate: 1,
+    overviewFrameIds: reviewedFrames.map(({ frameId }) => frameId),
+    overviewTargetFps: 1,
+    reviewedFrames,
+    scannedFrameCount: 5,
+    sourceBasename: "reference.mp4",
+    sourceKind: "video",
+    sourceSha256,
+    studyId: `motion-v1-${hex("b")}`,
+    timing: { authority: "decoded-timestamps" },
+    timingMode: "seconds",
+    width: 320,
+  };
+}
+
+function createPartitionZeroSeamEvidence() {
+  const evidence = createEvidence();
+  const indices = [0, 1, 90, 599];
+  evidence.reviewedFrames = indices.map((sourceFrameIndex, position) => ({
+    cell: { column: position, row: 0 },
+    frameId: `source-frame:${sourceFrameIndex}`,
+    sourceFrameIndex,
+    sourceLocator: `reference.mp4#frame=${sourceFrameIndex}`,
+    sourceSha256: evidence.sourceSha256,
+    timeSeconds: sourceFrameIndex / 30,
+  }));
+  evidence.contactSheet.columns = indices.length;
+  evidence.contactSheet.rows = 1;
+  evidence.decodedFrameCount = 600;
+  evidence.scannedFrameCount = 600;
+  evidence.durationSeconds = 20;
+  evidence.segment = { endSeconds: 4, startSeconds: 0 };
+  evidence.reviewPartition = {
+    count: 2,
+    groupId: `motion-group-v1-${hex("d")}`,
+    index: 0,
+    planSha256: hex("e"),
+    scope: { endSeconds: 20, startSeconds: 0 },
+  };
+  evidence.focusWindows = [];
+  evidence.maximumSourceFrameGapSeconds = 3;
+  evidence.overviewFrameIds = evidence.reviewedFrames.map(({ frameId }) => frameId);
+  evidence.detectedEvents = [{
+    afterFrameId: "source-frame:1",
+    beforeFrameId: "source-frame:599",
+    eventId: "motion-event:loop-seam:599-0-1",
+    kind: "loop-seam",
+    peakFrameId: "source-frame:0",
+    score: 0.5,
+    windowFrameIds: ["source-frame:599", "source-frame:0", "source-frame:1"],
+  }];
+  return evidence;
+}
+
+test("defines frozen evidence and writes deterministic canonical JSON", () => {
+  const evidence = defineToolcraftMotionReferenceEvidence(createEvidence());
+  const canonical = writeCanonicalToolcraftMotionReferenceEvidence(evidence);
+
+  assert.equal(Object.isFrozen(evidence), true);
+  assert.equal(Object.isFrozen(evidence.reviewedFrames[0].cell), true);
+  assert.equal(canonical.endsWith("\n"), true);
+  assert.equal(canonical, writeCanonicalToolcraftMotionReferenceEvidence(evidence));
+  assert.ok(canonical.indexOf('"changeMetric"') < canonical.indexOf('"width"'));
+});
+
+test("rejects unknown properties, invalid hashes, and scan count mismatches", () => {
+  for (const [mutate, expected] of [
+    [(value) => { value.unexpected = true; }, /unknown.*unexpected/iu],
+    [(value) => { value.sourceSha256 = "A".repeat(64); }, /sourceSha256.*hash/iu],
+    [(value) => { value.scannedFrameCount = 4; }, /decodedFrameCount.*scannedFrameCount/iu],
+  ]) {
+    const evidence = createEvidence();
+    mutate(evidence);
+    assert.match(getToolcraftMotionReferenceEvidenceErrors(evidence).join("\n"), expected);
+  }
+});
+
+test("returns shape errors for every unknown and malformed nested boundary", () => {
+  const malformedValues = [
+    null,
+    7,
+    "evidence",
+    [],
+    { overviewFrameIds: ["x"], reviewedFrames: null },
+  ];
+  for (const value of malformedValues) {
+    let errors;
+    assert.doesNotThrow(() => { errors = getToolcraftMotionReferenceEvidenceErrors(value); });
+    assert.ok(errors.length > 0);
+    assert.ok(errors.every((error) => typeof error === "string"));
+  }
+
+  for (const [property, malformed] of [
+    ["contactSheet", 3],
+    ["detectedEvents", {}],
+    ["focusWindows", [null]],
+    ["overviewFrameIds", 1],
+    ["reviewedFrames", null],
+    ["segment", []],
+    ["timing", 4],
+  ]) {
+    const evidence = createEvidence();
+    evidence[property] = malformed;
+    let errors;
+    assert.doesNotThrow(() => { errors = getToolcraftMotionReferenceEvidenceErrors(evidence); });
+    assert.ok(errors.length > 0, `${property} must report a shape error`);
+    assert.ok(errors.every((error) => typeof error === "string"));
+  }
+
+  const partition = createEvidence();
+  partition.reviewPartition = 9;
+  let partitionErrors;
+  assert.doesNotThrow(() => {
+    partitionErrors = getToolcraftMotionReferenceEvidenceErrors(partition);
+  });
+  assert.ok(partitionErrors.length > 0);
+  assert.ok(partitionErrors.every((error) => typeof error === "string"));
+});
+
+test("requires overview endpoints and recorded-density coverage", () => {
+  const missingEndpoint = createEvidence();
+  missingEndpoint.overviewFrameIds = missingEndpoint.overviewFrameIds.slice(1);
+  assert.match(
+    getToolcraftMotionReferenceEvidenceErrors(missingEndpoint).join("\n"),
+    /first reviewed frame/iu,
+  );
+
+  const sparse = createEvidence();
+  sparse.overviewFrameIds = ["source-frame:0", "source-frame:2", "source-frame:4"];
+  assert.match(
+    getToolcraftMotionReferenceEvidenceErrors(sparse).join("\n"),
+    /overview.*gap/iu,
+  );
+});
+
+test("closes events over known frames and caps each review at 120 frames", () => {
+  const unknownEventFrame = createEvidence();
+  unknownEventFrame.detectedEvents[0].peakFrameId = "source-frame:99";
+  assert.match(
+    getToolcraftMotionReferenceEvidenceErrors(unknownEventFrame).join("\n"),
+    /event.*unknown.*source-frame:99/iu,
+  );
+
+  const oversized = createEvidence();
+  oversized.reviewedFrames = Array.from({ length: 121 }, (_, index) => ({
+    ...oversized.reviewedFrames[0],
+    cell: { column: index % 11, row: Math.floor(index / 11) },
+    frameId: `source-frame:${index}`,
+    sourceFrameIndex: index,
+    timeSeconds: index / 30,
+  }));
+  oversized.contactSheet.columns = 11;
+  oversized.contactSheet.rows = 11;
+  oversized.decodedFrameCount = 121;
+  oversized.scannedFrameCount = 121;
+  oversized.durationSeconds = 4;
+  oversized.overviewFrameIds = oversized.reviewedFrames.map(({ frameId }) => frameId);
+  assert.match(
+    getToolcraftMotionReferenceEvidenceErrors(oversized).join("\n"),
+    /at most 120 reviewed frames/iu,
+  );
+});
+
+test("requires timed focus arrays and canonical complete event windows", () => {
+  const missingFocusArray = createEvidence();
+  missingFocusArray.focusWindows = {};
+  assert.match(
+    getToolcraftMotionReferenceEvidenceErrors(missingFocusArray).join("\n"),
+    /focusWindows must be an array/iu,
+  );
+
+  for (const windowFrameIds of [
+    ["source-frame:3", "source-frame:2", "source-frame:1"],
+    ["source-frame:0", "source-frame:2", "source-frame:4"],
+  ]) {
+    const evidence = createEvidence();
+    evidence.detectedEvents[0] = {
+      afterFrameId: windowFrameIds.at(-1),
+      beforeFrameId: windowFrameIds[0],
+      eventId: `motion-event:change:${windowFrameIds.map((id) => id.split(":")[1]).join("-")}`,
+      kind: "change",
+      peakFrameId: windowFrameIds[1],
+      score: 0.8,
+      windowFrameIds,
+    };
+    assert.match(
+      getToolcraftMotionReferenceEvidenceErrors(evidence).join("\n"),
+      /change.*strictly contiguous source-frame order/iu,
+    );
+  }
+
+  const canonicalLoop = createEvidence();
+  canonicalLoop.detectedEvents = [{
+    afterFrameId: "source-frame:1",
+    beforeFrameId: "source-frame:4",
+    eventId: "motion-event:loop-seam:4-0-1",
+    kind: "loop-seam",
+    peakFrameId: "source-frame:0",
+    score: 0.5,
+    windowFrameIds: ["source-frame:4", "source-frame:0", "source-frame:1"],
+  }];
+  assert.deepEqual(getToolcraftMotionReferenceEvidenceErrors(canonicalLoop), []);
+
+  canonicalLoop.detectedEvents[0].peakFrameId = "source-frame:4";
+  assert.match(
+    getToolcraftMotionReferenceEvidenceErrors(canonicalLoop).join("\n"),
+    /loop-seam.*exact cyclic source endpoint window/iu,
+  );
+
+  for (const frameCount of [1, 2]) {
+    const shortLoop = createEvidence();
+    shortLoop.reviewedFrames = shortLoop.reviewedFrames.slice(0, frameCount)
+      .map((frame, position) => ({ ...frame, cell: { column: position, row: 0 } }));
+    shortLoop.overviewFrameIds = shortLoop.reviewedFrames.map(({ frameId }) => frameId);
+    shortLoop.contactSheet.columns = frameCount;
+    shortLoop.contactSheet.rows = 1;
+    shortLoop.decodedFrameCount = frameCount;
+    shortLoop.scannedFrameCount = frameCount;
+    shortLoop.durationSeconds = Math.max(1, frameCount - 1);
+    shortLoop.focusWindows = [];
+    const ids = frameCount === 1 ? ["source-frame:0"] :
+      ["source-frame:1", "source-frame:0"];
+    shortLoop.detectedEvents = [{
+      afterFrameId: ids.at(-1),
+      beforeFrameId: ids[0],
+      eventId: `motion-event:loop-seam:${ids.map((id) => id.split(":")[1]).join("-")}`,
+      kind: "loop-seam",
+      peakFrameId: "source-frame:0",
+      score: 0.5,
+      windowFrameIds: ids,
+    }];
+    assert.deepEqual(getToolcraftMotionReferenceEvidenceErrors(shortLoop), []);
+  }
+});
+
+test("bounds timed frames, focus windows, segments, and partitions", () => {
+  const bounded = createEvidence();
+  bounded.segment = { endSeconds: 3, startSeconds: 1 };
+  bounded.reviewedFrames = bounded.reviewedFrames.slice(1, 4)
+    .map((frame, position) => ({ ...frame, cell: { column: position, row: 0 } }));
+  bounded.overviewFrameIds = bounded.reviewedFrames.map(({ frameId }) => frameId);
+  bounded.contactSheet.columns = 3;
+  bounded.contactSheet.rows = 1;
+  assert.deepEqual(getToolcraftMotionReferenceEvidenceErrors(bounded), []);
+
+  const outsideFrame = createEvidence();
+  outsideFrame.reviewedFrames[0].timeSeconds = -0.1;
+  assert.match(
+    getToolcraftMotionReferenceEvidenceErrors(outsideFrame).join("\n"),
+    /timeSeconds.*active timed scope/iu,
+  );
+
+  const invalidSegment = createEvidence();
+  invalidSegment.segment = { endSeconds: 5, startSeconds: 1 };
+  assert.match(
+    getToolcraftMotionReferenceEvidenceErrors(invalidSegment).join("\n"),
+    /segment.*durationSeconds/iu,
+  );
+
+  const invalidFocus = createEvidence();
+  invalidFocus.focusWindows[0].startSeconds = 1.5;
+  invalidFocus.focusWindows[0].sourceFrameStartIndex = 0;
+  assert.match(
+    getToolcraftMotionReferenceEvidenceErrors(invalidFocus).join("\n"),
+    /focusWindows\[0\].*first and last referenced frames|frame timestamps.*focus range/iu,
+  );
+
+  const invalidPartition = createEvidence();
+  invalidPartition.reviewPartition = {
+    count: 1,
+    groupId: `motion-group-v1-${hex("d")}`,
+    index: 0,
+    planSha256: hex("e"),
+    scope: { endSeconds: 5, startSeconds: 0 },
+  };
+  assert.match(
+    getToolcraftMotionReferenceEvidenceErrors(invalidPartition).join("\n"),
+    /reviewPartition.*scope.*durationSeconds|partitioned.*segment/iu,
+  );
+});
+
+test("allows only a complete-scope partition-zero external loop seam", () => {
+  assert.deepEqual(
+    getToolcraftMotionReferenceEvidenceErrors(createPartitionZeroSeamEvidence()),
+    [],
+  );
+
+  for (const mutate of [
+    (evidence) => { evidence.reviewPartition.index = 1; },
+    (evidence) => { evidence.reviewPartition.scope.endSeconds = 19; },
+    (evidence) => { evidence.detectedEvents = []; },
+    (evidence) => { evidence.detectedEvents[0].peakFrameId = "source-frame:599"; },
+    (evidence) => {
+      evidence.reviewedFrames.splice(3, 0, {
+        ...evidence.reviewedFrames[2],
+        cell: { column: 3, row: 0 },
+        frameId: "source-frame:500",
+        sourceFrameIndex: 500,
+        sourceLocator: "reference.mp4#frame=500",
+        timeSeconds: 500 / 30,
+      });
+      evidence.reviewedFrames[4].cell.column = 4;
+      evidence.contactSheet.columns = 5;
+      evidence.overviewFrameIds.splice(3, 0, "source-frame:500");
+    },
+  ]) {
+    const evidence = createPartitionZeroSeamEvidence();
+    mutate(evidence);
+    assert.match(
+      getToolcraftMotionReferenceEvidenceErrors(evidence).join("\n"),
+      /active timed scope|exact cyclic source endpoint window/iu,
+    );
+  }
+});
+
+test("requires interior change peaks and positive focus duration", () => {
+  for (const peakFrameId of ["source-frame:1", "source-frame:3"]) {
+    const evidence = createEvidence();
+    evidence.detectedEvents[0].peakFrameId = peakFrameId;
+    assert.match(
+      getToolcraftMotionReferenceEvidenceErrors(evidence).join("\n"),
+      /change peak must be strictly interior/iu,
+    );
+  }
+
+  const zeroLengthFocus = createEvidence();
+  zeroLengthFocus.focusWindows = [{
+    endSeconds: 1,
+    frameIds: ["source-frame:1"],
+    sourceFrameEndIndex: 1,
+    sourceFrameStartIndex: 1,
+    startSeconds: 1,
+  }];
+  assert.match(
+    getToolcraftMotionReferenceEvidenceErrors(zeroLengthFocus).join("\n"),
+    /focusWindows\[0\].*positive duration/iu,
+  );
+});
+
+test("requires focus windows to contain every reviewed frame in their timed range", () => {
+  for (const [startSeconds, endSeconds, frameIds, startIndex, endIndex] of [
+    [0, 2, ["source-frame:1", "source-frame:2"], 1, 2],
+    [0, 4, ["source-frame:0", "source-frame:1", "source-frame:3", "source-frame:4"], 0, 4],
+    [1, 3, ["source-frame:1", "source-frame:2"], 1, 2],
+  ]) {
+    const evidence = createEvidence();
+    evidence.focusWindows[0] = {
+      endSeconds,
+      frameIds,
+      sourceFrameEndIndex: endIndex,
+      sourceFrameStartIndex: startIndex,
+      startSeconds,
+    };
+    assert.match(
+      getToolcraftMotionReferenceEvidenceErrors(evidence).join("\n"),
+      /focusWindows\[0\].*exact ordered membership/iu,
+    );
+  }
+});
+
+test("ordinal evidence forbids timestamps and timing-only properties", () => {
+  const ordinal = createEvidence();
+  ordinal.timingMode = "ordinal";
+  ordinal.focusWindows = [];
+  assert.match(
+    getToolcraftMotionReferenceEvidenceErrors(ordinal).join("\n"),
+    /ordinal.*durationSeconds|unknown.*durationSeconds/iu,
+  );
+});
+
+test("define throws the same checked errors returned by the decoder", () => {
+  const invalid = { ...createEvidence(), extra: true };
+  const errors = getToolcraftMotionReferenceEvidenceErrors(invalid);
+  assert.throws(
+    () => defineToolcraftMotionReferenceEvidence(invalid),
+    new RegExp(errors[0].replace(/[.*+?^${}()|[\]\\]/gu, "\\$&"), "u"),
+  );
+});