@pixel-point/toolcraft 0.0.17 → 0.0.19

package/templates/starter/src/app/starter-acceptance.motion-reference-identity.test.ts

@@ -0,0 +1,163 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  alternateMotionReferenceId,
+  alternateMotionSourceSha256,
+  createMotionReferenceBehavior,
+  createMotionReferenceInput,
+  createOrdinalMotionReferenceStudy,
+  createPassiveMotionReferenceInput,
+  createTimedMotionReferenceStudy,
+  getMotionReferenceErrors,
+  motionReferenceId,
+  motionSourceSha256,
+} from "./starter-acceptance.motion-reference-test-utils";
+
+describe("Toolcraft motion reference identity", () => {
+  it("rejects duplicate semantic ids", () => {
+    const input = createMotionReferenceInput();
+    const study = input.studies[0];
+
+    expect(
+      getMotionReferenceErrors([
+        {
+          ...input,
+          studies: [
+            {
+              ...study,
+              phases: [
+                study.phases[0],
+                { ...study.phases[1], id: study.phases[0].id },
+              ],
+            },
+          ],
+        },
+      ]),
+    ).toContain(
+      'motion reference study "study-main" phase id "phase-before" is duplicated.',
+    );
+  });
+
+  it("rejects duplicate reference ids even when source identities differ", () => {
+    expect(
+      getMotionReferenceErrors([
+        createMotionReferenceInput(),
+        createPassiveMotionReferenceInput({
+          referenceId: motionReferenceId,
+          sourceSha256: alternateMotionSourceSha256,
+        }),
+      ]),
+    ).toContain(`motion reference id "${motionReferenceId}" is duplicated.`);
+  });
+
+  it("reports mixed source identities canonically for every study permutation", () => {
+    const primary = createTimedMotionReferenceStudy();
+    const alternate = createTimedMotionReferenceStudy({
+      framePrefix: "alternate-",
+      pathId: "study-alternate",
+      sourceBasename: "alternate.mp4",
+      sourceSha256: alternateMotionSourceSha256,
+      studyId: "study-alternate",
+    });
+    const forward = getMotionReferenceErrors([
+      createMotionReferenceInput({ studies: [primary, alternate] }),
+    ]);
+    const reverse = getMotionReferenceErrors([
+      createMotionReferenceInput({ studies: [alternate, primary] }),
+    ]);
+
+    expect(forward).toEqual(reverse);
+    expect(forward).toContain(
+      `motion reference "${motionReferenceId}" studies must share one sourceSha256; found ${motionSourceSha256}, ${alternateMotionSourceSha256}.`,
+    );
+  });
+
+  it("rejects duplicate inputs for one source identity", () => {
+    expect(
+      getMotionReferenceErrors([
+        createMotionReferenceInput(),
+        createPassiveMotionReferenceInput({
+          referenceId: alternateMotionReferenceId,
+        }),
+      ]),
+    ).toContain(
+      `motion reference sourceSha256 "${motionSourceSha256}" is declared by multiple reference inputs; merge their studies under one input.`,
+    );
+  });
+
+  it("keeps duplicate study ids ambiguous in every input permutation", () => {
+    const timed = createTimedMotionReferenceStudy({ pathId: "timed-study" });
+    const ordinal = createOrdinalMotionReferenceStudy({
+      framePrefix: "ordinal-",
+      pathId: "ordinal-study",
+    });
+    const errors = [
+      getMotionReferenceErrors([
+        createMotionReferenceInput({ studies: [timed, ordinal] }),
+      ]),
+      getMotionReferenceErrors([
+        createMotionReferenceInput({ studies: [ordinal, timed] }),
+      ]),
+    ];
+
+    expect(errors[0]).toEqual(errors[1]);
+    expect(errors[0]).toContain(
+      'motion reference behavior "delayed-retarget" timing claim "duration" studyId "study-main" resolves to 2 studies; expected exactly one.',
+    );
+  });
+
+  it("validates every duplicate behavior while relational uses remain ambiguous", () => {
+    const valid = createMotionReferenceBehavior();
+    const malformed = createMotionReferenceBehavior({ description: "" });
+    const errors = [
+      getMotionReferenceErrors([
+        createMotionReferenceInput({ behaviors: [valid, malformed] }),
+      ]),
+      getMotionReferenceErrors([
+        createMotionReferenceInput({ behaviors: [malformed, valid] }),
+      ]),
+    ];
+
+    expect(errors[0]).toEqual(errors[1]);
+    expect(errors[0]).toContain(
+      `motion reference "${motionReferenceId}" behavior id "delayed-retarget" is duplicated.`,
+    );
+    expect(errors[0]).toContain(
+      'motion reference behavior "delayed-retarget" must include a non-empty description.',
+    );
+    expect(errors[0]).toContain(
+      'motion reference study "study-main" phase "phase-before" cites ambiguous behaviorId "delayed-retarget" with 2 definitions.',
+    );
+    expect(errors[0]).toContain(
+      `acceptance "reference.anchor-retarget" motion reference coverage for "${motionReferenceId}" behavior "delayed-retarget" resolves to 2 behavior definitions; expected exactly one.`,
+    );
+  });
+
+  it("keeps control characters in timing study ids collision-proof", () => {
+    const controlStudyId = "study\u0000left";
+    const studies = [
+      createTimedMotionReferenceStudy({
+        framePrefix: "control-",
+        pathId: "control-study",
+        studyId: controlStudyId,
+      }),
+      createTimedMotionReferenceStudy({
+        framePrefix: "plain-",
+        pathId: "plain-study",
+        studyId: "study-right",
+      }),
+    ];
+    const behavior = createMotionReferenceBehavior({
+      timingClaims: [
+        { claim: "duration", studyId: controlStudyId },
+        { claim: "duration", studyId: "study-right" },
+      ],
+    });
+
+    expect(
+      getMotionReferenceErrors([
+        createMotionReferenceInput({ behaviors: [behavior], studies }),
+      ]),
+    ).toEqual([]);
+  });
+});

package/templates/starter/src/app/starter-acceptance.motion-reference-mapping.test.ts

@@ -0,0 +1,133 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  createMotionReferenceInput,
+  createOrdinalMotionReferenceStudy,
+  getMotionReferenceErrors,
+} from "./starter-acceptance.motion-reference-test-utils";
+
+describe("Toolcraft motion reference semantic coverage", () => {
+  it("accepts one normalized input with exact behavior and acceptance ownership", () => {
+    expect(getMotionReferenceErrors([createMotionReferenceInput()])).toEqual([]);
+  });
+
+  it("rejects phase gaps and overlaps across the ordered overview", () => {
+    const input = createMotionReferenceInput();
+    const study = input.studies[0];
+    const [firstPhase, secondPhase] = study.phases;
+
+    expect(
+      getMotionReferenceErrors([
+        {
+          ...input,
+          studies: [
+            {
+              ...study,
+              phases: [{ ...firstPhase, toFrameId: "f0" }, secondPhase],
+            },
+          ],
+        },
+      ]),
+    ).toContain(
+      'motion reference study "study-main" phases must be contiguous; "phase-after" starts at overview index 2 after index 0.',
+    );
+
+    expect(
+      getMotionReferenceErrors([
+        {
+          ...input,
+          studies: [
+            {
+              ...study,
+              phases: [{ ...firstPhase, toFrameId: "f2" }, secondPhase],
+            },
+          ],
+        },
+      ]),
+    ).toContain(
+      'motion reference study "study-main" phases must be contiguous; "phase-after" starts at overview index 2 after index 2.',
+    );
+  });
+
+  it("rejects machine events without exactly one authored classification", () => {
+    const input = createMotionReferenceInput();
+    const study = input.studies[0];
+
+    expect(
+      getMotionReferenceErrors([
+        { ...input, studies: [{ ...study, events: [] }] },
+      ]),
+    ).toContain(
+      'motion reference study "study-main" evidence event "machine-retarget" must have exactly one authored event; found 0.',
+    );
+  });
+
+  it("requires a non-empty reason for every nonproduct event", () => {
+    const input = structuredClone(createMotionReferenceInput());
+    Object.defineProperties(input.studies[0].events[0], {
+      behaviorIds: { configurable: true, value: [] },
+      classification: { configurable: true, value: "irrelevant-change" },
+      reason: { configurable: true, value: "   " },
+    });
+
+    expect(getMotionReferenceErrors([input])).toContain(
+      'motion reference study "study-main" event "event-retarget" classification "irrelevant-change" requires a non-empty reason.',
+    );
+  });
+
+  it("requires every nonproduct event to have zero behavior ids", () => {
+    const input = structuredClone(createMotionReferenceInput());
+    Object.defineProperties(input.studies[0].events[0], {
+      behaviorIds: { configurable: true, value: ["delayed-retarget"] },
+      classification: { configurable: true, value: "irrelevant-change" },
+      reason: {
+        configurable: true,
+        value: "The event is outside product scope.",
+      },
+    });
+
+    expect(getMotionReferenceErrors([input])).toContain(
+      'motion reference study "study-main" event "event-retarget" classification "irrelevant-change" must not cite behaviorIds.',
+    );
+  });
+
+  it("rejects product events that cite unknown behavior ids", () => {
+    const input = createMotionReferenceInput();
+    const study = input.studies[0];
+
+    expect(
+      getMotionReferenceErrors([
+        {
+          ...input,
+          studies: [
+            {
+              ...study,
+              events: [
+                {
+                  behaviorIds: ["unknown-behavior"],
+                  classification: "product-behavior",
+                  evidenceEventId: "machine-retarget",
+                  id: "event-retarget",
+                },
+              ],
+            },
+          ],
+        },
+      ]),
+    ).toContain(
+      'motion reference study "study-main" event "event-retarget" cites unknown behaviorId "unknown-behavior".',
+    );
+  });
+
+  it("rejects timing claims owned by ordinal evidence", () => {
+    expect(
+      getMotionReferenceErrors([
+        createMotionReferenceInput({
+          studies: [createOrdinalMotionReferenceStudy()],
+        }),
+      ]),
+    ).toContain(
+      'motion reference behavior "delayed-retarget" timing claim "duration" must name a seconds-timed study; "study-main" is ordinal.',
+    );
+  });
+});

package/templates/starter/src/app/starter-acceptance.motion-reference-ownership.test.ts

@@ -0,0 +1,121 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  createMotionReferenceAcceptance,
+  createMotionReferenceBehavior,
+  createMotionReferenceInput,
+  createTimedMotionReferenceStudy,
+  getMotionReferenceErrors,
+  motionReferenceAcceptance,
+  motionReferenceId,
+} from "./starter-acceptance.motion-reference-test-utils";
+
+describe("Toolcraft motion reference acceptance ownership", () => {
+  it("requires one exact reverse acceptance coverage record", () => {
+    const input = createMotionReferenceInput();
+
+    expect(
+      getMotionReferenceErrors([input], [
+        createMotionReferenceAcceptance({ motionReferenceCoverage: [] }),
+      ]),
+    ).toContain(
+      'motion reference behavior "delayed-retarget" acceptance "reference.anchor-retarget" must own exactly one reverse coverage pair; found 0.',
+    );
+
+    const duplicateOwner = createMotionReferenceAcceptance({
+      id: "reference.anchor-retarget-duplicate",
+    });
+    expect(
+      getMotionReferenceErrors(
+        [input],
+        [motionReferenceAcceptance, duplicateOwner],
+      ),
+    ).toContain(
+      'motion reference behavior "delayed-retarget" coverage pair has 2 acceptance owners; expected exactly one.',
+    );
+  });
+
+  it("rejects dangling reverse acceptance coverage", () => {
+    const danglingAcceptance = createMotionReferenceAcceptance({
+      id: "reference.dangling-motion",
+      motionReferenceCoverage: [
+        { behaviorId: "missing-behavior", referenceId: motionReferenceId },
+      ],
+    });
+
+    expect(
+      getMotionReferenceErrors(
+        [createMotionReferenceInput()],
+        [motionReferenceAcceptance, danglingAcceptance],
+      ),
+    ).toContain(
+      `acceptance "reference.dangling-motion" has dangling motion reference coverage for "${motionReferenceId}" behavior "missing-behavior".`,
+    );
+  });
+
+  it("never selects a representative from ambiguous acceptance ids", () => {
+    const valid = createMotionReferenceAcceptance();
+    const malformed = createMotionReferenceAcceptance({
+      automated: false,
+      automatedTestName: "",
+      browser: false,
+      browserTestName: "",
+      expectedObservable: "",
+      motionReferenceCoverage: [],
+    });
+    const expected = [
+      'motion reference behavior "delayed-retarget" acceptance "reference.anchor-retarget" must describe its observable result.',
+      'motion reference behavior "delayed-retarget" acceptance "reference.anchor-retarget" must have automated coverage.',
+      'motion reference behavior "delayed-retarget" acceptance "reference.anchor-retarget" must have browser coverage.',
+      'motion reference behavior "delayed-retarget" acceptanceId "reference.anchor-retarget" resolves to 2 acceptance rows; expected exactly one.',
+    ];
+
+    expect(
+      getMotionReferenceErrors(
+        [createMotionReferenceInput()],
+        [valid, malformed],
+      ),
+    ).toEqual(expected);
+    expect(
+      getMotionReferenceErrors(
+        [createMotionReferenceInput()],
+        [malformed, valid],
+      ),
+    ).toEqual(expected);
+  });
+
+  it("does not let delimiter-shaped coverage pairs hide dangling ownership", () => {
+    const ownedReferenceId = "motion-reference-v1-control\u0000suffix" as const;
+    const danglingReferenceId = "motion-reference-v1-control" as const;
+    const ownedBehaviorId = "tail";
+    const danglingBehaviorId = "suffix\u0000tail";
+    const ownedAcceptance = createMotionReferenceAcceptance({
+      id: "reference.control-owner",
+      motionReferenceCoverage: [
+        { behaviorId: ownedBehaviorId, referenceId: ownedReferenceId },
+      ],
+    });
+    const danglingAcceptance = createMotionReferenceAcceptance({
+      id: "reference.control-dangling",
+      motionReferenceCoverage: [
+        { behaviorId: danglingBehaviorId, referenceId: danglingReferenceId },
+      ],
+    });
+    const behavior = createMotionReferenceBehavior({
+      acceptanceId: ownedAcceptance.id,
+      id: ownedBehaviorId,
+    });
+    const study = createTimedMotionReferenceStudy({ behaviorId: ownedBehaviorId });
+    const input = createMotionReferenceInput({
+      behaviors: [behavior],
+      referenceId: ownedReferenceId,
+      studies: [study],
+    });
+
+    expect(
+      getMotionReferenceErrors([input], [ownedAcceptance, danglingAcceptance]),
+    ).toContain(
+      `acceptance "reference.control-dangling" has dangling motion reference coverage for "${danglingReferenceId}" behavior "${danglingBehaviorId}".`,
+    );
+  });
+});

package/templates/starter/src/app/starter-acceptance.motion-reference-partitions.test.ts

@@ -0,0 +1,210 @@
+import { describe, expect, it } from "vitest";
+
+import type { ToolcraftMotionReferenceStudy } from "./acceptance/types";
+import {
+  createMotionReferenceInput,
+  createTimedMotionReferenceStudy,
+  getMotionReferenceErrors,
+  type MotionReviewPartition,
+  type MotionSegment,
+} from "./starter-acceptance.motion-reference-test-utils";
+
+const partitionBase = {
+  count: 2,
+  groupId: "motion-group-v1-partitioned-reference",
+  planSha256:
+    "dddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddddd",
+  scope: { endSeconds: 4, startSeconds: 0 },
+} satisfies Omit<MotionReviewPartition, "index">;
+
+function createPartitionStudy({
+  count = partitionBase.count,
+  detectedLoopSeam = false,
+  index,
+  planSha256 = partitionBase.planSha256,
+  reviewPartition = true,
+  scope = partitionBase.scope,
+  segment,
+}: {
+  count?: number;
+  detectedLoopSeam?: boolean;
+  index: number;
+  planSha256?: string;
+  reviewPartition?: boolean;
+  scope?: MotionReviewPartition["scope"];
+  segment: MotionSegment;
+}): ToolcraftMotionReferenceStudy {
+  const studyId = `study-partition-${index}`;
+  return createTimedMotionReferenceStudy({
+    behaviorId: null,
+    detectedLoopSeam,
+    framePrefix: `p${index}-`,
+    pathId: studyId,
+    reviewPartition: reviewPartition
+      ? { count, groupId: partitionBase.groupId, index, planSha256, scope }
+      : undefined,
+    segment,
+    studyId,
+    withEvent: detectedLoopSeam,
+  });
+}
+
+function getPartitionErrors(
+  studies: readonly ToolcraftMotionReferenceStudy[],
+): string[] {
+  return getMotionReferenceErrors(
+    [createMotionReferenceInput({ behaviors: [], studies })],
+    [],
+  );
+}
+
+function createCompletePartition(): readonly ToolcraftMotionReferenceStudy[] {
+  return [
+    createPartitionStudy({
+      index: 0,
+      segment: { endSeconds: 2, startSeconds: 0 },
+    }),
+    createPartitionStudy({
+      index: 1,
+      segment: { endSeconds: 4, startSeconds: 2 },
+    }),
+  ];
+}
+
+describe("Toolcraft motion reference partitions", () => {
+  it("accepts an exact contiguous partition group in every input order", () => {
+    const studies = createCompletePartition();
+
+    expect(getPartitionErrors(studies)).toEqual([]);
+    expect(getPartitionErrors([...studies].reverse())).toEqual([]);
+  });
+
+  it("rejects an incomplete partition group", () => {
+    expect(getPartitionErrors([createCompletePartition()[0]])).toContain(
+      'motion reference partition "motion-group-v1-partitioned-reference" count 2 cannot exceed group cardinality 1.',
+    );
+  });
+
+  it("rejects overlapping partition segments", () => {
+    expect(
+      getPartitionErrors([
+        createPartitionStudy({
+          index: 0,
+          segment: { endSeconds: 2, startSeconds: 0 },
+        }),
+        createPartitionStudy({
+          index: 1,
+          segment: { endSeconds: 4, startSeconds: 1.5 },
+        }),
+      ]),
+    ).toContain(
+      'motion reference partition "motion-group-v1-partitioned-reference" segments must be contiguous and non-overlapping; index 1 starts at 1.5 after 2.',
+    );
+  });
+
+  it("validates count before deriving an index range or allocating by it", () => {
+    const invalidCounts = [0, 1.5, Number.POSITIVE_INFINITY];
+    for (const count of invalidCounts) {
+      expect(
+        getPartitionErrors([
+          createPartitionStudy({
+            count,
+            index: 0,
+            segment: { endSeconds: 4, startSeconds: 0 },
+          }),
+        ]),
+      ).toContain(
+        `motion reference partition "motion-group-v1-partitioned-reference" count must be a finite safe positive integer; received ${String(count)}.`,
+      );
+    }
+
+    expect(
+      getPartitionErrors([
+        createPartitionStudy({
+          count: Number.MAX_SAFE_INTEGER,
+          index: 0,
+          segment: { endSeconds: 4, startSeconds: 0 },
+        }),
+      ]),
+    ).toContain(
+      `motion reference partition "motion-group-v1-partitioned-reference" count ${Number.MAX_SAFE_INTEGER} cannot exceed group cardinality 1.`,
+    );
+  });
+
+  it("reports conflicting metadata canonically and skips dependent range checks", () => {
+    const studies = [
+      createPartitionStudy({
+        count: 2,
+        index: 0,
+        segment: { endSeconds: 3, startSeconds: 0 },
+      }),
+      createPartitionStudy({
+        count: 3,
+        index: 1,
+        planSha256:
+          "eeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
+        scope: { endSeconds: 5, startSeconds: 0 },
+        segment: { endSeconds: 4, startSeconds: 1 },
+      }),
+      createPartitionStudy({
+        count: 2,
+        index: 2,
+        segment: { endSeconds: 4, startSeconds: 3 },
+      }),
+    ];
+    const forward = getPartitionErrors(studies);
+    const reverse = getPartitionErrors([...studies].reverse());
+
+    expect(forward).toEqual(reverse);
+    expect(forward).toContain(
+      'motion reference partition "motion-group-v1-partitioned-reference" studies must declare one shared count.',
+    );
+    expect(forward).toContain(
+      'motion reference partition "motion-group-v1-partitioned-reference" studies must declare one shared planSha256.',
+    );
+    expect(forward).toContain(
+      'motion reference partition "motion-group-v1-partitioned-reference" studies must declare one shared scope.',
+    );
+    expect(forward.some((error) => error.includes("segments must"))).toBe(false);
+  });
+
+  it("accepts semantically equal scopes regardless of key insertion order", () => {
+    expect(
+      getPartitionErrors([
+        createCompletePartition()[0],
+        createPartitionStudy({
+          index: 1,
+          scope: { startSeconds: 0, endSeconds: 4 },
+          segment: { endSeconds: 4, startSeconds: 2 },
+        }),
+      ]),
+    ).toEqual([]);
+  });
+
+  it("allows the original full-source loop seam only in partition index zero", () => {
+    expect(
+      getPartitionErrors([
+        createCompletePartition()[0],
+        createPartitionStudy({
+          detectedLoopSeam: true,
+          index: 1,
+          segment: { endSeconds: 4, startSeconds: 2 },
+        }),
+      ]),
+    ).toContain(
+      'motion reference partition "motion-group-v1-partitioned-reference" original loop-seam evidence must appear only in index 0.',
+    );
+  });
+
+  it("accepts one explicit unpartitioned segment as an intentional excerpt", () => {
+    expect(
+      getPartitionErrors([
+        createPartitionStudy({
+          index: 0,
+          reviewPartition: false,
+          segment: { endSeconds: 2, startSeconds: 1 },
+        }),
+      ]),
+    ).toEqual([]);
+  });
+});