@pixel-point/toolcraft 0.0.17 → 0.0.19

package/templates/starter/scripts/toolcraft-functional-proof-model.types.test.mts

@@ -1,80 +1,18 @@
-import type {
-  ToolcraftFunctionalProofOwner,
-} from "./toolcraft-functional-proof-model.mjs";
 import {
   createToolcraftFunctionalProofModel,
 } from "./toolcraft-functional-proof-model.mjs";
 import type {
   ToolcraftDeliveryCatalog,
-  ToolcraftVerificationImpactOwner,
-} from "./toolcraft-verification-impact.mjs";
+} from "./playwright-test-title-selection.mjs";
 
-const functionalOwner: ToolcraftFunctionalProofOwner = {
-  acceptanceIds: ["material.shape"],
-  kind: "functional",
-  path: "src/material.ts",
-};
-const presentationOwner: ToolcraftFunctionalProofOwner = {
-  acceptanceIds: ["appearance.background"],
-  kind: "presentation",
-  path: "public/background.png",
-};
-const performanceOwner: ToolcraftFunctionalProofOwner = {
-  acceptanceIds: ["material.shape"],
-  kind: "performance",
-  passIds: ["preview-composite"],
-  path: "src/output.ts",
-};
-const invalidFunctional: ToolcraftFunctionalProofOwner = {
-  acceptanceIds: ["material.shape"],
-  kind: "functional",
-  // @ts-expect-error Functional owners cannot carry renderer passes.
-  passIds: ["preview-composite"],
-  path: "src/material.ts",
-};
-const invalidPresentation: ToolcraftFunctionalProofOwner = {
-  acceptanceIds: ["appearance.background"],
-  kind: "presentation",
-  // @ts-expect-error Presentation owners cannot carry renderer passes.
-  passIds: ["preview-composite"],
-  path: "public/background.png",
-};
-// @ts-expect-error Performance owners require renderer passes.
-const invalidPerformance: ToolcraftFunctionalProofOwner = {
-  acceptanceIds: ["material.shape"],
-  kind: "performance",
-  path: "src/output.ts",
-};
-const publicFunctionalOwner: ToolcraftVerificationImpactOwner = {
-  acceptanceIds: ["material.shape"],
-  kind: "functional",
-  path: "src/material.ts",
-};
-const invalidPublicFunctionalOwner: ToolcraftVerificationImpactOwner = {
-  acceptanceIds: ["material.shape"],
-  kind: "functional",
-  // @ts-expect-error Functional impact owners cannot carry passIds.
-  passIds: ["preview-composite"],
-  path: "src/material.ts",
-};
-// @ts-expect-error Performance impact owners require passIds.
-const invalidPublicPerformanceOwner: ToolcraftVerificationImpactOwner = {
-  acceptanceIds: ["material.shape"],
-  kind: "performance",
-  path: "src/output.ts",
-};
-const sharedCurrentCatalog: ToolcraftDeliveryCatalog = {
+const catalog: ToolcraftDeliveryCatalog = {
   acceptance: [],
   performance: [],
   version: 2,
 };
-const validCurrentModel = createToolcraftFunctionalProofModel({
-  catalog: sharedCurrentCatalog,
-  inventory: {
-    owners: [],
-    version: 3,
-  },
-});
+
+const model = createToolcraftFunctionalProofModel({ catalog });
+
 createToolcraftFunctionalProofModel({
   catalog: {
     acceptance: [],
@@ -82,21 +20,6 @@ createToolcraftFunctionalProofModel({
     // @ts-expect-error Delivery catalog is current-only v2.
     version: 3,
   },
-  inventory: {
-    owners: [],
-    version: 3,
-  },
 });
 
-void [
-  functionalOwner,
-  presentationOwner,
-  performanceOwner,
-  invalidFunctional,
-  invalidPresentation,
-  invalidPerformance,
-  publicFunctionalOwner,
-  invalidPublicFunctionalOwner,
-  invalidPublicPerformanceOwner,
-  validCurrentModel,
-];
+void model;

package/templates/starter/scripts/toolcraft-functional-proof-primitives.d.mts

@@ -1,5 +1,16 @@
 export function serializeToolcraftCanonicalJson(value: unknown): string;
 export function createToolcraftCanonicalJsonHash(value: unknown): string;
+export function hasToolcraftExactRecordKeys(
+  value: unknown,
+  keys: readonly string[],
+): boolean;
+export function isToolcraftCanonicalTargetArray(
+  value: unknown,
+  options?: Readonly<{ empty?: boolean; paths?: boolean }>,
+): boolean;
+export function isToolcraftDenseExactArray(value: unknown): value is unknown[];
+export function deepFreezeToolcraftValue<T>(value: T): T;
+export function isToolcraftDeeplyFrozen(value: unknown): boolean;
 export function deriveToolcraftAcceptanceDomainId(acceptanceId: string): string;
 export function createToolcraftAcceptanceContractHash(
   acceptanceEntry: unknown,

package/templates/starter/scripts/toolcraft-functional-proof-primitives.mjs

@@ -4,6 +4,67 @@ const compareCodeUnits = (left, right) => left < right ? -1 : left > right ? 1 :
 const isTrimmedString = (value) =>
   typeof value === "string" && value.length > 0 && value.trim() === value;
 
+export function hasToolcraftExactRecordKeys(value, keys) {
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return false;
+  }
+  const prototype = Object.getPrototypeOf(value);
+  if (prototype !== Object.prototype && prototype !== null) return false;
+  const ownKeys = Reflect.ownKeys(value);
+  return ownKeys.length === keys.length && ownKeys.every((key) =>
+    typeof key === "string" &&
+    keys.includes(key) &&
+    Object.prototype.propertyIsEnumerable.call(value, key)
+  );
+}
+
+export function isToolcraftCanonicalTargetArray(
+  value,
+  { empty = false, paths = false } = {},
+) {
+  const dense = isToolcraftDenseExactArray(value);
+  const valid = (item) =>
+    typeof item === "string" &&
+    item.length > 0 &&
+    item.trim() === item &&
+    (!paths || (
+      !item.includes("\\") &&
+      !item.startsWith("/") &&
+      !/^[A-Za-z]:\//u.test(item) &&
+      item.split("/").every((part) => part && part !== "." && part !== "..")
+    ));
+  return dense && (empty || value.length > 0) && value.every(valid) &&
+    value.every((item, index) =>
+      index === 0 || compareCodeUnits(value[index - 1], item) < 0
+    );
+}
+
+export function isToolcraftDenseExactArray(value) {
+  return (
+    Array.isArray(value) &&
+    Reflect.ownKeys(value).length === value.length + 1 &&
+    Array.from(
+      { length: value.length },
+      (_, index) => Object.hasOwn(value, index),
+    ).every(Boolean)
+  );
+}
+
+export function deepFreezeToolcraftValue(value) {
+  if (value && typeof value === "object" && !Object.isFrozen(value)) {
+    Object.values(value).forEach(deepFreezeToolcraftValue);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+export function isToolcraftDeeplyFrozen(value) {
+  return !(value && typeof value === "object") || (
+    Object.isFrozen(value) &&
+    Object.values(value).every(isToolcraftDeeplyFrozen)
+  );
+}
+
 export function serializeToolcraftCanonicalJson(value, ancestors = new Set()) {
   if (value === null || typeof value === "boolean" || typeof value === "string") {
     return JSON.stringify(value);

package/templates/starter/scripts/toolcraft-functional-proof-primitives.test.mjs

@@ -5,7 +5,12 @@ import test from "node:test";
 import {
   createToolcraftAcceptanceContractHash,
   createToolcraftCanonicalJsonHash,
+  deepFreezeToolcraftValue,
   deriveToolcraftAcceptanceDomainId,
+  hasToolcraftExactRecordKeys,
+  isToolcraftCanonicalTargetArray,
+  isToolcraftDeeplyFrozen,
+  isToolcraftDenseExactArray,
   serializeToolcraftCanonicalJson,
 } from "./toolcraft-functional-proof-primitives.mjs";
 
@@ -24,6 +29,44 @@ test("one primitive boundary owns canonical serialization and semantic hashes",
   assert.equal(deriveToolcraftAcceptanceDomainId("material.shape"), "material");
 });
 
+test("canonical structural primitives reject ambiguous proof shapes", () => {
+  assert.equal(
+    hasToolcraftExactRecordKeys({ files: [], kind: "product-tests" }, [
+      "files",
+      "kind",
+    ]),
+    true,
+  );
+  assert.equal(
+    hasToolcraftExactRecordKeys({ files: [], kind: "product-tests", extra: true }, [
+      "files",
+      "kind",
+    ]),
+    false,
+  );
+  assert.equal(isToolcraftDenseExactArray(["a"]), true);
+  assert.equal(isToolcraftDenseExactArray(Array(1)), false);
+  assert.equal(
+    isToolcraftCanonicalTargetArray(["src/app/a.ts", "src/app/b.ts"], {
+      paths: true,
+    }),
+    true,
+  );
+  assert.equal(
+    isToolcraftCanonicalTargetArray(["src/app/b.ts", "../a.ts"], {
+      paths: true,
+    }),
+    false,
+  );
+});
+
+test("canonical deep freeze preserves identity and proves nested immutability", () => {
+  const value = { nested: { acceptanceIds: ["output.updates"] } };
+
+  assert.equal(deepFreezeToolcraftValue(value), value);
+  assert.equal(isToolcraftDeeplyFrozen(value), true);
+});
+
 test("canonical primitives reject symbol keys at every object depth", () => {
   const topLevel = { value: true, [Symbol("top")]: true };
   const nested = { nested: { value: true, [Symbol("nested")]: true } };

package/templates/starter/scripts/toolcraft-integrity-policy.mjs

@@ -8,8 +8,10 @@ export const requiredPackageScriptNames = [
   "docs:check",
   "preview",
   "preview:restart",
+  "reference:study",
   "test",
   "test:browser",
+  "test:feature",
   "typecheck",
   "verify:delivery",
   "verify:kernel",
@@ -17,6 +19,12 @@ export const requiredPackageScriptNames = [
   "verify:receipt",
 ];
 
+const requiredMotionReferenceTrustRootFilePaths = [
+  "scripts/create-toolcraft-motion-reference-study.mjs",
+  "src/app/acceptance/motion-reference-evidence.d.mts",
+  "src/app/acceptance/motion-reference-evidence.mjs",
+];
+
 export const reservedGeneratedVerificationConfigPatterns = [
   /^playwright\.config\.[cm]?[jt]s$/u,
   /^vite\.config\.[cm]?[jt]s$/u,
@@ -32,6 +40,7 @@ export const requiredProtectedTrustRootFilePaths = [
   "e2e/browser-performance-report.ts",
   "e2e/browser-runtime-evidence-reporter.ts",
   "e2e/browser-runtime-evidence-requirements.ts",
+  "e2e/toolcraft-feature-verification-reporter.ts",
   "e2e/performance-pipeline-evidence.ts",
   "e2e/toolcraft-product-test.ts",
   "playwright.config.ts",
@@ -40,6 +49,8 @@ export const requiredProtectedTrustRootFilePaths = [
   "scripts/run-browser-performance.mjs",
   "scripts/run-delivery-verification.mjs",
   "scripts/run-kernel-benchmarks.mjs",
+  "scripts/run-feature-verification.mjs",
+  "scripts/toolcraft-feature-verification-plan.mjs",
   "scripts/toolcraft-integrity-manifest.mjs",
   "scripts/toolcraft-integrity-policy.mjs",
   "scripts/toolcraft-product-boundary.mjs",
@@ -51,8 +62,10 @@ export const requiredProtectedTrustRootFilePaths = [
   "scripts/toolcraft-vitest-runtime-evidence-reporter.mjs",
   "scripts/toolcraft-workflow-routes.mjs",
   "src/app/acceptance/validation-pipeline.ts",
+  "src/app/acceptance/feature-verification-selection.ts",
   "src/app/app-automated-runtime-evidence.test.ts",
   "vite.config.ts",
+  ...requiredMotionReferenceTrustRootFilePaths,
 ];
 
 export const runtimeSurfaceComponentNames = Object.freeze([

package/templates/starter/scripts/toolcraft-integrity-test-utils.mjs

@@ -9,7 +9,7 @@ import {
 } from "./toolcraft-integrity-policy.mjs";
 
 const fixtureManifestSignature =
-  "qU2Tc5z8NqfzbGr7ZdcGhKtt6eLBkw+kJMvmTNq5cE3andSTf/tF3SUdwpNJ4nNSiSHn/x6FcP0/iKW98nEWDg==";
+  "KwSG36fxNC20k9czN8i/613IjmdGNj7SJXOdWjSXRlWIQwddFrC6lWf9moWCAjDP4bxke6j6pBLkdPt/xjopDw==";
 const runtimeSource = "export const runtime = true;\n";
 
 const sha256 = (value) =>

package/templates/starter/scripts/toolcraft-layer-evidence-facade.test.mjs

@@ -26,7 +26,11 @@ async function loadLayerEvidenceFacade(context) {
       '"./transition.mjs"',
     )
     .replaceAll('"./browser-runtime-evidence"', '"./evidence.mjs"')
-    .replaceAll('"./browser-proof-session"', '"./proof-session.mjs"');
+    .replaceAll('"./browser-proof-session"', '"./proof-session.mjs"')
+    .replaceAll(
+      '"./browser-selection-scope-evidence"',
+      '"./selection-scope.mjs"',
+    );
   const { outputText } = ts.transpileModule(source, {
     compilerOptions: {
       module: ts.ModuleKind.ESNext,
@@ -88,6 +92,24 @@ async function loadLayerEvidenceFacade(context) {
         }
       `,
     ),
+    fs.writeFile(
+      path.join(outputDir, "selection-scope.mjs"),
+      `
+        export async function expectToolcraftSelectionScopedControl(options) {
+          globalThis.__toolcraftLayerSelectionScopeCalls.push(options);
+          globalThis.__toolcraftLayerEvidenceAttachments.push({
+            evidenceType: "product-observable-change",
+            requirementId: options.requirementId,
+            target: options.propertyTarget,
+          });
+          globalThis.__toolcraftLayerEvidenceAttachments.push({
+            evidenceType: "selection-scoped-control",
+            requirementId: options.requirementId,
+            target: options.propertyTarget,
+          });
+        }
+      `,
+    ),
   ]);
 
   return import(`${pathToFileURL(outputPath).href}?test=${Date.now()}`);
@@ -100,6 +122,7 @@ function setTransition(before, after) {
 test("layer recipes attach exact-target base and specialized evidence", async (context) => {
   const facade = await loadLayerEvidenceFacade(context);
   globalThis.__toolcraftLayerEvidenceAttachments = [];
+  globalThis.__toolcraftLayerSelectionScopeCalls = [];
   globalThis.__toolcraftLayerEvidenceTransitionCalls = 0;
   const action = { target: "layers.semantic-target" };
   const observation = {};
@@ -168,24 +191,11 @@ test("layer recipes attach exact-target base and specialized evidence", async (c
     options,
   );
 
-  setTransition(
-    {
-      controlValue: 0,
-      outputSignature: "before",
-      selectedLayerId: "layer-a",
-    },
-    {
-      controlValue: 1,
-      outputSignature: "after",
-      selectedLayerId: "layer-a",
-    },
-  );
-  await facade.expectToolcraftSelectedLayerControl(
-    observation,
-    action,
-    globalThis.__toolcraftLayerEvidenceTransition.after,
-    options,
-  );
+  const selectedLayerOptions = {
+    propertyTarget: action.target,
+    requirementId: options.requirementId,
+  };
+  await facade.expectToolcraftSelectedLayerControl(selectedLayerOptions);
 
   setTransition(
     { layerIds: ["layer-a"], outputSignature: "before" },
@@ -211,8 +221,6 @@ test("layer recipes attach exact-target base and specialized evidence", async (c
       ["product-observable-change", "layer-visibility"],
       ["product-observable-change", "layer-reorder"],
       ["product-observable-change", "layer-grouping"],
-      ["media-lifecycle", "layer-selected-layer-controls"],
-      ["media-lifecycle", "layer-media-lifecycle"],
     ].flatMap(([baseEvidenceType, specializedEvidenceType]) => [
       {
         evidenceType: baseEvidenceType,
@@ -225,12 +233,40 @@ test("layer recipes attach exact-target base and specialized evidence", async (c
         target: action.target,
       },
     ]),
+    {
+      evidenceType: "product-observable-change",
+      requirementId: options.requirementId,
+      target: action.target,
+    },
+    {
+      evidenceType: "selection-scoped-control",
+      requirementId: options.requirementId,
+      target: action.target,
+    },
+    {
+      evidenceType: "layer-selected-layer-controls",
+      requirementId: options.requirementId,
+      target: action.target,
+    },
+    {
+      evidenceType: "media-lifecycle",
+      requirementId: options.requirementId,
+      target: action.target,
+    },
+    {
+      evidenceType: "layer-media-lifecycle",
+      requirementId: options.requirementId,
+      target: action.target,
+    },
   ];
   assert.deepEqual(
     globalThis.__toolcraftLayerEvidenceAttachments,
     expectedEvidence,
   );
-  assert.equal(globalThis.__toolcraftLayerEvidenceTransitionCalls, 6);
+  assert.equal(globalThis.__toolcraftLayerEvidenceTransitionCalls, 5);
+  assert.deepEqual(globalThis.__toolcraftLayerSelectionScopeCalls, [
+    selectedLayerOptions,
+  ]);
 });
 
 test("layer recipes fail before assertions or evidence when action has no target", async (context) => {

package/templates/starter/scripts/toolcraft-motion-reference-analysis-protocol.mjs

@@ -0,0 +1,111 @@
+export const TOOLCRAFT_MOTION_ANALYSIS_COMPONENT_MAX = 255;
+export const TOOLCRAFT_MOTION_CHANGE_METRIC = "max-yuva-diff-v1";
+export const TOOLCRAFT_MOTION_FFMPEG_TIMESTAMP_TOLERANCE_SECONDS = 1e-6;
+
+const PROBE_SHOW_ENTRIES =
+  "program_version=version:stream=codec_type,width,height,pix_fmt," +
+  "avg_frame_rate,r_frame_rate,nb_frames,duration,start_time:" +
+  "format=duration,start_time:" +
+  "frame=best_effort_timestamp_time,pts_time:pixel_format=name,nb_components:" +
+  "pixel_format_flags=alpha:pixel_format_components=index,bit_depth";
+
+function fail(message) {
+  throw new TypeError(`Invalid Toolcraft motion analysis protocol: ${message}`);
+}
+
+export function createToolcraftMotionProbeArguments(inputPath) {
+  if (typeof inputPath !== "string" || inputPath.length === 0) {
+    fail("an input path is required for probing");
+  }
+  return [
+    "-v", "error", "-select_streams", "v:0",
+    "-show_program_version", "-show_pixel_formats",
+    "-show_streams", "-show_format", "-show_frames",
+    "-show_entries", PROBE_SHOW_ENTRIES,
+    "-of", "json", inputPath,
+  ];
+}
+
+export function createToolcraftMotionAnalysisGraph(inputLabel, hasAlpha) {
+  if (typeof inputLabel !== "string" || inputLabel.length === 0 ||
+      typeof hasAlpha !== "boolean") {
+    fail("an input label and alpha decision are required");
+  }
+  const color = "format=yuv444p,signalstats," +
+    "metadata=mode=add:key=toolcraft.channel:value=color," +
+    "metadata=print:file=-";
+  if (!hasAlpha) return `${inputLabel}${color}[colorout]`;
+  const alpha = "alphaextract,format=gray,signalstats," +
+    "metadata=mode=add:key=toolcraft.channel:value=alpha," +
+    "metadata=print:file=-";
+  return `${inputLabel}split=2[colorSource][alphaSource];` +
+    `[colorSource]${color}[colorout];[alphaSource]${alpha}[alphaout]`;
+}
+
+export function createToolcraftMotionAnalysisOutputArguments(hasAlpha) {
+  if (typeof hasAlpha !== "boolean") fail("an alpha decision is required");
+  return [
+    "-map", "[colorout]",
+    ...(hasAlpha ? ["-map", "[alphaout]"] : []),
+    "-f", "null", "-",
+  ];
+}
+
+export function toolcraftMotionTimestampsAgree(left, right) {
+  return typeof left === "number" && Number.isFinite(left) &&
+    typeof right === "number" && Number.isFinite(right) &&
+    Math.abs(left - right) <= TOOLCRAFT_MOTION_FFMPEG_TIMESTAMP_TOLERANCE_SECONDS;
+}
+
+export function toolcraftMotionAnalysisChangeScore(record) {
+  const values = [record?.yDifference, record?.uDifference, record?.vDifference,
+    ...(record?.alphaDifference === undefined ? [] : [record.alphaDifference])];
+  if (values.length < 3 || values.some((value) =>
+    typeof value !== "number" || !Number.isFinite(value) || value < 0 ||
+      value > TOOLCRAFT_MOTION_ANALYSIS_COMPONENT_MAX)) {
+    fail(`change components must be finite values between 0 and ${TOOLCRAFT_MOTION_ANALYSIS_COMPONENT_MAX}`);
+  }
+  return Math.max(...values) / TOOLCRAFT_MOTION_ANALYSIS_COMPONENT_MAX;
+}
+
+export function validateToolcraftMotionScanRecordAgreement(records, expectedTimes) {
+  if (!Array.isArray(records) || !Array.isArray(expectedTimes) ||
+      records.length !== expectedTimes.length || records.length === 0 ||
+      records.some((record, index) => record?.frameIndex !== index ||
+        !toolcraftMotionTimestampsAgree(record?.timeSeconds, expectedTimes[index]))) {
+    fail("decoded frame count, index, timestamp, and score agreement is required");
+  }
+}
+
+export function createToolcraftMotionLoopSeamScore(decodedFrameCount, records) {
+  if (!Number.isInteger(decodedFrameCount) || decodedFrameCount <= 0) {
+    fail("a positive decoded frame count is required");
+  }
+  if (decodedFrameCount === 1) {
+    if (records !== undefined) fail("single-frame sources cannot include seam records");
+    return 0;
+  }
+  if (!Array.isArray(records) || records.length !== 2) {
+    fail("loop seam requires exactly two frame records");
+  }
+  if (records[0]?.frameIndex !== 0 || records[1]?.frameIndex !== 1 ||
+      !(records[1]?.timeSeconds > records[0]?.timeSeconds)) {
+    fail("loop seam frame indices must be 0 then 1 with increasing timestamps");
+  }
+  return toolcraftMotionAnalysisChangeScore(records[1]);
+}
+
+export function createToolcraftMotionScanResult(records, loopSeamScore) {
+  if (!Array.isArray(records) || records.length === 0 ||
+      typeof loopSeamScore !== "number" || !Number.isFinite(loopSeamScore) ||
+      loopSeamScore < 0 || loopSeamScore > 1) {
+    fail("scan records and a normalized loop seam score are required");
+  }
+  return {
+    changeMetric: TOOLCRAFT_MOTION_CHANGE_METRIC,
+    changeScores: records.map(toolcraftMotionAnalysisChangeScore),
+    componentDifferences: records,
+    loopSeamScore,
+    scannedFrameCount: records.length,
+  };
+}

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

@@ -0,0 +1,116 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  createToolcraftMotionAnalysisGraph,
+  createToolcraftMotionAnalysisOutputArguments,
+  createToolcraftMotionLoopSeamScore,
+  createToolcraftMotionProbeArguments,
+  createToolcraftMotionScanResult,
+  TOOLCRAFT_MOTION_ANALYSIS_COMPONENT_MAX,
+  TOOLCRAFT_MOTION_CHANGE_METRIC,
+  toolcraftMotionAnalysisChangeScore,
+  toolcraftMotionTimestampsAgree,
+  validateToolcraftMotionScanRecordAgreement,
+} from "./toolcraft-motion-reference-analysis-protocol.mjs";
+
+function record(frameIndex, timeSeconds, {
+  alphaDifference,
+  uDifference = 0,
+  vDifference = 0,
+  yDifference = 0,
+} = {}) {
+  return {
+    ...(alphaDifference === undefined ? {} : { alphaDifference }),
+    frameIndex,
+    timeSeconds,
+    uDifference,
+    vDifference,
+    yDifference,
+  };
+}
+
+test("owns the exact ffprobe visual metadata and descriptor request", () => {
+  assert.deepEqual(createToolcraftMotionProbeArguments("/refs/input.mov"), [
+    "-v", "error", "-select_streams", "v:0",
+    "-show_program_version", "-show_pixel_formats",
+    "-show_streams", "-show_format", "-show_frames",
+    "-show_entries",
+    "program_version=version:stream=codec_type,width,height,pix_fmt,avg_frame_rate,r_frame_rate,nb_frames,duration,start_time:format=duration,start_time:frame=best_effort_timestamp_time,pts_time:pixel_format=name,nb_components:pixel_format_flags=alpha:pixel_format_components=index,bit_depth",
+    "-of", "json", "/refs/input.mov",
+  ]);
+});
+
+test("owns exact 8-bit color and conditional alpha stdout analysis graphs", () => {
+  assert.equal(createToolcraftMotionAnalysisGraph("[decoded]", false),
+    "[decoded]format=yuv444p,signalstats," +
+    "metadata=mode=add:key=toolcraft.channel:value=color," +
+    "metadata=print:file=-[colorout]");
+  assert.equal(createToolcraftMotionAnalysisGraph("[decoded]", true),
+    "[decoded]split=2[colorSource][alphaSource];" +
+    "[colorSource]format=yuv444p,signalstats," +
+    "metadata=mode=add:key=toolcraft.channel:value=color," +
+    "metadata=print:file=-[colorout];" +
+    "[alphaSource]alphaextract,format=gray,signalstats," +
+    "metadata=mode=add:key=toolcraft.channel:value=alpha," +
+    "metadata=print:file=-[alphaout]");
+  assert.deepEqual(createToolcraftMotionAnalysisOutputArguments(false), [
+    "-map", "[colorout]", "-f", "null", "-",
+  ]);
+  assert.deepEqual(createToolcraftMotionAnalysisOutputArguments(true), [
+    "-map", "[colorout]", "-map", "[alphaout]", "-f", "null", "-",
+  ]);
+});
+
+test("owns the single 8-bit component normalization authority", () => {
+  assert.equal(TOOLCRAFT_MOTION_ANALYSIS_COMPONENT_MAX, 255);
+  assert.equal(toolcraftMotionAnalysisChangeScore(record(0, 0, {
+    alphaDifference: 102,
+    uDifference: 51,
+    vDifference: 12,
+  })), 102 / TOOLCRAFT_MOTION_ANALYSIS_COMPONENT_MAX);
+  assert.throws(() => toolcraftMotionAnalysisChangeScore(record(0, 0, {
+    yDifference: 256,
+  })), /between 0 and 255/iu);
+});
+
+test("validates scan count, indices, and authoritative timestamps with one tolerance", () => {
+  const records = [record(0, 0), record(1, 0.1250004), record(2, 0.5)];
+  assert.equal(toolcraftMotionTimestampsAgree(0.1250004, 0.125), true);
+  assert.doesNotThrow(() => validateToolcraftMotionScanRecordAgreement(
+    records, [0, 0.125, 0.5],
+  ));
+  assert.throws(() => validateToolcraftMotionScanRecordAgreement(
+    records.slice(0, 2), [0, 0.125, 0.5],
+  ), /agreement/iu);
+  assert.throws(() => validateToolcraftMotionScanRecordAgreement(
+    [records[0], { ...records[1], frameIndex: 2 }, records[2]], [0, 0.125, 0.5],
+  ), /agreement/iu);
+  assert.throws(() => validateToolcraftMotionScanRecordAgreement(
+    [records[0], { ...records[1], timeSeconds: 0.13 }, records[2]], [0, 0.125, 0.5],
+  ), /agreement/iu);
+});
+
+test("owns single-frame zero and exact last-to-first seam cardinality", () => {
+  assert.equal(createToolcraftMotionLoopSeamScore(1), 0);
+  const seam = [record(0, 0), record(1, 1, { vDifference: 51 })];
+  assert.equal(createToolcraftMotionLoopSeamScore(3, seam), 51 / 255);
+  assert.throws(() => createToolcraftMotionLoopSeamScore(3, seam.slice(0, 1)),
+    /exactly two/iu);
+  assert.throws(() => createToolcraftMotionLoopSeamScore(3, [...seam, record(2, 2)]),
+    /exactly two/iu);
+  assert.throws(() => createToolcraftMotionLoopSeamScore(3, [seam[1], seam[0]]),
+    /indices|increasing/iu);
+});
+
+test("assembles one canonical scan result", () => {
+  const records = [record(0, 0), record(1, 1, { uDifference: 51 })];
+  assert.deepEqual(createToolcraftMotionScanResult(records, 0.25), {
+    changeMetric: TOOLCRAFT_MOTION_CHANGE_METRIC,
+    changeScores: [0, 51 / 255],
+    componentDifferences: records,
+    loopSeamScore: 0.25,
+    scannedFrameCount: 2,
+  });
+  assert.equal(TOOLCRAFT_MOTION_CHANGE_METRIC, "max-yuva-diff-v1");
+});