@pixel-point/toolcraft 0.0.15 → 0.0.16

package/templates/runtime/testing/performance-fixture-validation-pure.test.ts

@@ -0,0 +1,378 @@
+import { describe, expect, it } from "vitest";
+
+import { getToolcraftPerformanceFixtureAdapterErrors } from "./performance-fixture-adapters";
+import {
+  compileToolcraftPerformanceFixturePlan,
+  defineToolcraftDiscreteFixtureAdapter,
+  executeToolcraftPerformanceFixtureCheckpoint,
+  validateToolcraftPerformanceCoverage,
+  type ToolcraftEnvelopePerformanceConfig,
+} from "./performance";
+import {
+  createCanonicalAdapter,
+  createCanonicalConfig,
+  createCanonicalDimension,
+  createCanonicalPass,
+  getCanonicalPath,
+} from "./performance-fixture-plan.test-fixtures";
+import { groupedSchema } from "./performance-paths.test-fixtures";
+
+describe("Toolcraft pure fixture registry validation", () => {
+  it.each([null, [], "registry", 42])(
+    "returns a stable error for malformed registry %j",
+    (fixtureAdapters) => {
+      const config = createCanonicalConfig({
+        adapters: { count: createCanonicalAdapter("count") },
+        dimensions: [createCanonicalDimension("count")],
+        passes: [createCanonicalPass("composite", ["count"], "linear")],
+      });
+      const malformed = {
+        ...config,
+        fixtureAdapters,
+      } as unknown as ToolcraftEnvelopePerformanceConfig;
+
+      expect(() =>
+        getToolcraftPerformanceFixtureAdapterErrors(malformed, [
+          getCanonicalPath(config),
+        ]),
+      ).not.toThrow();
+      expect(
+        getToolcraftPerformanceFixtureAdapterErrors(malformed, [
+          getCanonicalPath(config),
+        ]),
+      ).toEqual(["fixtureAdapters must be a non-null object."]);
+    },
+  );
+
+  it("sorts orphan adapter errors deterministically without executing callbacks", () => {
+    let callbackCount = 0;
+    const config = createCanonicalConfig({
+      adapters: {
+        zeta: createCanonicalAdapter("zeta", {
+          apply: (value) => {
+            callbackCount += 1;
+            return value;
+          },
+        }),
+        count: createCanonicalAdapter("count"),
+        alpha: createCanonicalAdapter("alpha"),
+      },
+      dimensions: [createCanonicalDimension("count")],
+      passes: [createCanonicalPass("composite", ["count"], "linear")],
+    });
+
+    expect(
+      getToolcraftPerformanceFixtureAdapterErrors(config, [getCanonicalPath(config)]),
+    ).toEqual([
+      'fixtureAdapters.dimensions["alpha"] does not match a workload dimension.',
+      'fixtureAdapters.dimensions["zeta"] does not match a workload dimension.',
+    ]);
+    expect(callbackCount).toBe(0);
+  });
+
+  it("returns stable errors for malformed adapter and pass metadata", () => {
+    const config = createCanonicalConfig({
+      adapters: { count: createCanonicalAdapter("count") },
+      dimensions: [createCanonicalDimension("count")],
+      passes: [createCanonicalPass("composite", ["count"], "linear")],
+    });
+    const malformed = {
+      ...config,
+      fixtureAdapters: {
+        dimensions: { count: null },
+        inverseCheckpoints: null,
+      },
+      rendererPipeline: {
+        ...config.rendererPipeline!,
+        passes: [null],
+      },
+    } as unknown as ToolcraftEnvelopePerformanceConfig;
+
+    expect(() =>
+      getToolcraftPerformanceFixtureAdapterErrors(malformed, []),
+    ).not.toThrow();
+    expect(getToolcraftPerformanceFixtureAdapterErrors(malformed, [])).toEqual([
+      'fixtureAdapters.dimensions["count"] must be a non-null object.',
+      "fixtureAdapters.inverseCheckpoints must be an array.",
+    ]);
+  });
+
+  it("surfaces adapter identity errors through direct coverage without callbacks", () => {
+    let callbackCount = 0;
+    const config = createCanonicalConfig({
+      adapters: {
+        count: createCanonicalAdapter("wrong-id", {
+          apply: (value) => {
+            callbackCount += 1;
+            return value;
+          },
+        }),
+      },
+      dimensions: [createCanonicalDimension("count")],
+      passes: [createCanonicalPass("composite", ["count"], "linear")],
+    });
+
+    expect(validateToolcraftPerformanceCoverage(groupedSchema, config)).toContain(
+      'fixtureAdapters.dimensions["count"].dimensionId must equal its registry key "count".',
+    );
+    expect(callbackCount).toBe(0);
+  });
+
+  it.each([
+    {
+      adapterPatch: { entries: "not-an-array" },
+      expected: 'fixtureAdapters.dimensions["count"].entries must be a non-empty exhaustive mapping.',
+    },
+    {
+      adapterPatch: { domain: null },
+      expected: 'fixtureAdapters.dimensions["count"].domain must declare exhaustive provenance.',
+    },
+    {
+      adapterPatch: { kind: "unknown-adapter-kind" },
+      expected: 'fixtureAdapters.dimensions["count"].kind must be "continuous" or "exhaustive-discrete".',
+    },
+    {
+      adapterPatch: {
+        domain: { kind: "runtime-state" },
+      },
+      expected: 'fixtureAdapters.dimensions["count"].domain.attestation must explain why the finite domain is exhaustive.',
+    },
+  ])(
+    "keeps malformed adapters out of the parsed registry: $expected",
+    ({ adapterPatch, expected }) => {
+      const validAdapter = defineToolcraftDiscreteFixtureAdapter({
+        dimensionId: "count",
+        domain: {
+          attestation: "All runtime fixture modes are enumerated.",
+          kind: "runtime-state",
+          path: "fixture.count",
+        },
+        entries: [20, 84, 100, 200].map((value) => ({
+          appliedValue: `option-${value}`,
+          value,
+        })),
+      });
+      const config = createCanonicalConfig({
+        adapters: { count: validAdapter },
+        dimensions: [createCanonicalDimension("count")],
+        passes: [createCanonicalPass("composite", ["count"], "linear")],
+      });
+      const malformed = {
+        ...config,
+        fixtureAdapters: {
+          dimensions: {
+            count: { ...validAdapter, ...adapterPatch },
+          },
+        },
+      } as unknown as ToolcraftEnvelopePerformanceConfig;
+      const path = getCanonicalPath(config);
+
+      expect(() =>
+        validateToolcraftPerformanceCoverage(groupedSchema, malformed),
+      ).not.toThrow();
+      expect(validateToolcraftPerformanceCoverage(groupedSchema, malformed)).toContain(
+        expected,
+      );
+      expect(() =>
+        compileToolcraftPerformanceFixturePlan(malformed, path),
+      ).toThrow(expected);
+    },
+  );
+
+  it("rejects disconnected reachableValues metadata", () => {
+    const config = createCanonicalConfig({
+      adapters: { count: createCanonicalAdapter("count") },
+      dimensions: [createCanonicalDimension("count")],
+      passes: [createCanonicalPass("composite", ["count"], "linear")],
+    });
+    const malformed = {
+      ...config,
+      fixtureAdapters: {
+        ...config.fixtureAdapters,
+        dimensions: {
+          count: {
+            ...config.fixtureAdapters!.dimensions.count,
+            reachableValues: [20, 100, 200],
+          },
+        },
+      },
+    } as unknown as ToolcraftEnvelopePerformanceConfig;
+
+    expect(
+      getToolcraftPerformanceFixtureAdapterErrors(malformed, [
+        getCanonicalPath(config),
+      ]),
+    ).toContain(
+      'fixtureAdapters.dimensions["count"].reachableValues is disconnected metadata; use an exhaustive-discrete adapter with canonical entries and domain provenance.',
+    );
+  });
+
+  it.each([
+    {
+      expected: "must be a non-empty exhaustive mapping",
+      values: [],
+    },
+    {
+      expected: "must not contain duplicate numeric values",
+      values: [20, 20, 100, 200],
+    },
+    {
+      expected: "must include dimension defaultValue 20",
+      values: [10, 100, 200],
+    },
+    {
+      expected: "must include dimension interactiveMax 100",
+      values: [20, 80, 200],
+    },
+    {
+      expected: "must include dimension batchMax 200",
+      values: [20, 80, 100],
+    },
+  ])("rejects invalid exhaustive entries: $expected", ({ expected, values }) => {
+    const config = createCanonicalConfig({
+      adapters: {
+        count: defineToolcraftDiscreteFixtureAdapter({
+          dimensionId: "count",
+          domain: {
+            attestation: "All fixture options are enumerated.",
+            kind: "runtime-state",
+            path: "fixture.count",
+          },
+          entries: values.map((value, index) => ({
+            appliedValue: `option-${index}`,
+            value,
+          })),
+        }),
+      },
+      dimensions: [createCanonicalDimension("count")],
+      passes: [createCanonicalPass("composite", ["count"], "linear")],
+    });
+
+    expect(
+      getToolcraftPerformanceFixtureAdapterErrors(config, [getCanonicalPath(config)]),
+    ).toContain(`fixtureAdapters.dimensions["count"].entries ${expected}.`);
+  });
+
+  it("sorts orphan inverse evidence by path and pass", () => {
+    const baseConfig = createCanonicalConfig({
+      adapters: { count: createCanonicalAdapter("count") },
+      dimensions: [createCanonicalDimension("count")],
+      passes: [createCanonicalPass("composite", ["count"], "linear")],
+    });
+    const config = {
+      ...baseConfig,
+      fixtureAdapters: {
+        ...baseConfig.fixtureAdapters!,
+        inverseCheckpoints: [
+          {
+            measuredResult: "orphan zeta",
+            normalizedPressure: 0.8,
+            passId: "zeta",
+            pathId: "unknown-zeta",
+            values: { count: 80 },
+          },
+          {
+            measuredResult: "orphan alpha",
+            normalizedPressure: 0.8,
+            passId: "alpha",
+            pathId: "unknown-alpha",
+            values: { count: 80 },
+          },
+        ],
+      },
+    };
+
+    expect(
+      getToolcraftPerformanceFixtureAdapterErrors(config, [getCanonicalPath(config)]),
+    ).toEqual([
+      'fixtureAdapters.inverseCheckpoints for path "unknown-alpha" pass "alpha" does not match a canonical evidence-required pass.',
+      'fixtureAdapters.inverseCheckpoints for path "unknown-zeta" pass "zeta" does not match a canonical evidence-required pass.',
+    ]);
+  });
+
+  it.each(["constructor", "toString"])(
+    "treats inherited prototype key %s as a missing adapter",
+    (dimensionId) => {
+      const config = createCanonicalConfig({
+        adapters: {},
+        dimensions: [createCanonicalDimension(dimensionId)],
+        passes: [createCanonicalPass("composite", [dimensionId], "linear")],
+      });
+      const path = getCanonicalPath(config);
+      const expected =
+        `fixtureAdapters.dimensions[${JSON.stringify(dimensionId)}] must apply and observe workload dimension "${dimensionId}".`;
+
+      expect(getToolcraftPerformanceFixtureAdapterErrors(config, [path])).toContain(
+        expected,
+      );
+      expect(() =>
+        compileToolcraftPerformanceFixturePlan(config, path),
+      ).toThrow(expected);
+    },
+  );
+
+  it.each(["constructor", "toString"])(
+    "accepts and executes an explicit own adapter for prototype key %s",
+    (dimensionId) => {
+      const config = createCanonicalConfig({
+        adapters: { [dimensionId]: createCanonicalAdapter(dimensionId) },
+        dimensions: [createCanonicalDimension(dimensionId)],
+        passes: [createCanonicalPass("composite", [dimensionId], "linear")],
+      });
+      const path = getCanonicalPath(config);
+
+      expect(getToolcraftPerformanceFixtureAdapterErrors(config, [path])).toEqual([]);
+      const result = executeToolcraftPerformanceFixtureCheckpoint(
+        config,
+        compileToolcraftPerformanceFixturePlan(config, path),
+        "maximum",
+      );
+
+      expect(Object.hasOwn(result.observed, dimensionId)).toBe(true);
+      expect(result.observed[dimensionId]).toBe(100);
+      expect(Object.getPrototypeOf(result.observed)).toBe(null);
+    },
+  );
+
+  it.each([
+    {
+      expected:
+        "workloadEnvelope.dimensions[0] must be a non-null object.",
+      rawDimension: null,
+    },
+    {
+      expected:
+        "workloadEnvelope.dimensions[0] must be a non-null object.",
+      rawDimension: 42,
+    },
+    {
+      expected:
+        "workloadEnvelope.dimensions[0].id must be trimmed and non-empty.",
+      rawDimension: {},
+    },
+  ])(
+    "returns stable public errors for malformed dimension $rawDimension",
+    ({ expected, rawDimension }) => {
+      const validConfig = createCanonicalConfig({
+        adapters: { count: createCanonicalAdapter("count") },
+        dimensions: [createCanonicalDimension("count")],
+        passes: [createCanonicalPass("composite", ["count"], "linear")],
+      });
+      const malformedConfig = {
+        ...validConfig,
+        workloadEnvelope: { dimensions: [rawDimension] },
+      } as unknown as ToolcraftEnvelopePerformanceConfig;
+      const path = getCanonicalPath(validConfig);
+
+      expect(() =>
+        validateToolcraftPerformanceCoverage(groupedSchema, malformedConfig),
+      ).not.toThrow();
+      expect(
+        validateToolcraftPerformanceCoverage(groupedSchema, malformedConfig),
+      ).toContain(expected);
+      expect(() =>
+        compileToolcraftPerformanceFixturePlan(malformedConfig, path),
+      ).toThrow(expected);
+    },
+  );
+});

package/templates/runtime/testing/performance-interaction-policy.test.ts

@@ -0,0 +1,35 @@
+import { describe, expect, it } from "vitest";
+
+import { getToolcraftPerformanceProfileForInteraction } from "./performance-interaction-policy";
+
+describe("Toolcraft performance interaction policy", () => {
+  it("assigns every pipeline interaction to a named profile", () => {
+    expect({
+      animationFrame: getToolcraftPerformanceProfileForInteraction("animation-frame"),
+      controlChange: getToolcraftPerformanceProfileForInteraction("control-change"),
+      controlDrag: getToolcraftPerformanceProfileForInteraction("control-drag"),
+      export: getToolcraftPerformanceProfileForInteraction("export"),
+      initialRender: getToolcraftPerformanceProfileForInteraction("initial-render"),
+      maskDrag: getToolcraftPerformanceProfileForInteraction("mask-drag"),
+      mediaImport: getToolcraftPerformanceProfileForInteraction("media-import"),
+      timelinePlayback: getToolcraftPerformanceProfileForInteraction(
+        "timeline-playback",
+      ),
+      timelineScrub: getToolcraftPerformanceProfileForInteraction("timeline-scrub"),
+      viewportDrag: getToolcraftPerformanceProfileForInteraction("viewport-drag"),
+      viewportZoom: getToolcraftPerformanceProfileForInteraction("viewport-zoom"),
+    }).toEqual({
+      animationFrame: "interactive-continuous",
+      controlChange: "interactive-discrete",
+      controlDrag: "interactive-continuous",
+      export: "batch-responsive",
+      initialRender: "initial-render",
+      maskDrag: "interactive-continuous",
+      mediaImport: "batch-responsive",
+      timelinePlayback: "interactive-continuous",
+      timelineScrub: "interactive-continuous",
+      viewportDrag: "interactive-continuous",
+      viewportZoom: "interactive-continuous",
+    });
+  });
+});

package/templates/runtime/testing/performance-interaction-policy.ts

@@ -0,0 +1,9 @@
+import type { ToolcraftPipelineInteraction } from "./performance-types";
+import type { ToolcraftPerformanceProfileName } from "./performance-workload-types";
+import { getToolcraftPerformanceProfileForInteractionId } from "./performance-path-codec.mjs";
+
+export function getToolcraftPerformanceProfileForInteraction(
+  interaction: ToolcraftPipelineInteraction,
+): ToolcraftPerformanceProfileName {
+  return getToolcraftPerformanceProfileForInteractionId(interaction);
+}

package/templates/runtime/testing/performance-no-legacy-semantics.test.ts

@@ -0,0 +1,109 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, extname, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { describe, expect, it } from "vitest";
+
+const testDirectory = dirname(fileURLToPath(import.meta.url));
+const repositoryRoot = resolve(testDirectory, "../../../..");
+
+const normativeRoots = [
+  "packages/toolcraft-runtime/src",
+  "apps/website/src/content/docs",
+  "starter/docs/toolcraft",
+  "starter/e2e",
+  "starter/scripts",
+  "starter/src",
+  "cli/fixtures/generated-product/docs",
+  "cli/fixtures/generated-product/e2e",
+  "cli/fixtures/generated-product/src",
+] as const;
+
+const supportedExtensions = new Set([".md", ".mjs", ".mts", ".ts", ".tsx"]);
+
+const forbiddenPatterns = [
+  ["large", "TextStressMinChars"].join(""),
+  ["large", "TextStressMinLines"].join(""),
+  ["media", "StressMinArea"].join(""),
+  ["media", "StressMinLongEdge"].join(""),
+  ["workload", "ControlPattern"].join(""),
+  ["renderer", "Workload"].join("") + String.raw`\s*[?:]`,
+  ["workload", "Targets"].join("") + String.raw`\s*[?:]`,
+  ["stress", "Fixture"].join(""),
+  ["workload", "Fixture"].join(""),
+  ["load", "Profile"].join(""),
+  ["smooth", "TargetRatio"].join(""),
+  ["measured", "AlternativeEvidence"].join(""),
+  ["expectToolcraft", "ScenarioPerformanceBudget"].join(""),
+  ["expectToolcraft", "DiscreteSliderDragSmoothness"].join(""),
+  ["deriveToolcraft", "PerformanceRuntimeRequirements"].join(""),
+  ["browser", "CheckPolicy"].join(""),
+  ["record", "-exemption"].join(""),
+  ["experimental", "-above-smooth"].join(""),
+  ["preview", "-render"].join(""),
+  ["viewport", "-zoom-stress"].join(""),
+  ["animation", "-viewport-drag"].join(""),
+  ["viewport", "-stability"].join(""),
+  ["max", "RenderMs"].join(""),
+  ["playwright", "-fallback"].join(""),
+  ["performance", "-stress-fixture"].join(""),
+] as const;
+
+const retiredRuntimeFiles = [
+  "performance-browser-policy.ts",
+  "performance-coverage-context.ts",
+  "performance-coverage-renderer-policy.ts",
+  "performance-coverage-scenario-policy.ts",
+  "performance-coverage-target-policy.ts",
+  "performance-fixture-validation.ts",
+  "performance-fixture-values.ts",
+  "performance-load-profile-validation.ts",
+  "performance-renderer-validation.ts",
+] as const;
+
+function collectNormativeFiles(directory: string): string[] {
+  return readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
+    const path = join(directory, entry.name);
+    if (entry.isDirectory()) {
+      return collectNormativeFiles(path);
+    }
+    if (
+      !entry.isFile() ||
+      !supportedExtensions.has(extname(entry.name)) ||
+      /(?:^|\.)test\.|(?:^|\.)spec\./u.test(entry.name)
+    ) {
+      return [];
+    }
+    return [path];
+  });
+}
+
+describe("Toolcraft canonical performance architecture", () => {
+  it("contains no legacy authored workload semantics", () => {
+    const violations = normativeRoots.flatMap((root) =>
+      collectNormativeFiles(resolve(repositoryRoot, root)).flatMap((path) => {
+        const source = readFileSync(path, "utf8");
+        return forbiddenPatterns.flatMap((pattern) =>
+          new RegExp(pattern, "u").test(source)
+            ? [`${relative(repositoryRoot, path)} contains /${pattern}/u`]
+            : [],
+        );
+      }),
+    );
+
+    expect(violations).toEqual([]);
+  });
+
+  it("does not restore retired parallel policy modules", () => {
+    const testingRoot = resolve(
+      repositoryRoot,
+      "packages/toolcraft-runtime/src/testing",
+    );
+
+    expect(
+      retiredRuntimeFiles.filter((fileName) =>
+        existsSync(join(testingRoot, fileName)),
+      ),
+    ).toEqual([]);
+  });
+});

package/templates/runtime/testing/performance-path-codec.d.mts

@@ -0,0 +1,42 @@
+export type ToolcraftPerformancePathSignature = Readonly<{
+  interaction:
+    | "animation-frame"
+    | "control-change"
+    | "control-drag"
+    | "export"
+    | "initial-render"
+    | "mask-drag"
+    | "media-import"
+    | "timeline-playback"
+    | "timeline-scrub"
+    | "viewport-drag"
+    | "viewport-zoom";
+  invalidates: readonly string[];
+  profile:
+    | "batch-responsive"
+    | "initial-render"
+    | "interactive-continuous"
+    | "interactive-discrete";
+  runsOn: readonly (
+    | "export-only"
+    | "gpu"
+    | "main"
+    | "worker"
+    | "worker-or-gpu"
+  )[];
+  workloadDimensions: readonly string[];
+}>;
+
+export declare const TOOLCRAFT_PIPELINE_INTERACTIONS: readonly ToolcraftPerformancePathSignature["interaction"][];
+
+export declare function getToolcraftPerformanceProfileForInteractionId(
+  interaction: ToolcraftPerformancePathSignature["interaction"],
+): ToolcraftPerformancePathSignature["profile"];
+
+export declare function decodeToolcraftPerformancePathId(
+  pathId: unknown,
+): ToolcraftPerformancePathSignature | undefined;
+
+export declare function createToolcraftPerformancePathId(
+  path: ToolcraftPerformancePathSignature,
+): string;

package/templates/runtime/testing/performance-path-codec.mjs

@@ -0,0 +1,112 @@
+import { TOOLCRAFT_PERFORMANCE_PROFILE_MANIFEST } from "../performance/profile-catalog-manifest.mjs";
+
+const interactionProfiles = Object.freeze({
+  "animation-frame": "interactive-continuous",
+  "control-change": "interactive-discrete",
+  "control-drag": "interactive-continuous",
+  export: "batch-responsive",
+  "initial-render": "initial-render",
+  "mask-drag": "interactive-continuous",
+  "media-import": "batch-responsive",
+  "timeline-playback": "interactive-continuous",
+  "timeline-scrub": "interactive-continuous",
+  "viewport-drag": "interactive-continuous",
+  "viewport-zoom": "interactive-continuous",
+});
+const runLocations = new Set([
+  "export-only",
+  "gpu",
+  "main",
+  "worker",
+  "worker-or-gpu",
+]);
+const profileNames = new Set(TOOLCRAFT_PERFORMANCE_PROFILE_MANIFEST.names);
+
+export const TOOLCRAFT_PIPELINE_INTERACTIONS = Object.freeze(
+  Object.keys(interactionProfiles),
+);
+
+function compareCodeUnits(left, right) {
+  return left < right ? -1 : left > right ? 1 : 0;
+}
+
+function isTrimmedString(value) {
+  return typeof value === "string" && value.length > 0 && value.trim() === value;
+}
+
+function isCanonicalStringArray(value, allowedValues) {
+  return (
+    Array.isArray(value) &&
+    value.every(
+      (item) =>
+        isTrimmedString(item) &&
+        (allowedValues === undefined || allowedValues.has(item)),
+    ) &&
+    new Set(value).size === value.length &&
+    value.every(
+      (item, index) =>
+        index === 0 || compareCodeUnits(value[index - 1], item) < 0,
+    )
+  );
+}
+
+export function getToolcraftPerformanceProfileForInteractionId(interaction) {
+  return interactionProfiles[interaction];
+}
+
+export function decodeToolcraftPerformancePathId(pathId) {
+  if (
+    !isTrimmedString(pathId) ||
+    !pathId.startsWith("performance-path:")
+  ) {
+    return undefined;
+  }
+  try {
+    const signature = JSON.parse(
+      decodeURIComponent(pathId.slice("performance-path:".length)),
+    );
+    if (!Array.isArray(signature) || signature.length !== 5) return undefined;
+    const [profile, interaction, invalidates, runsOn, workloadDimensions] =
+      signature;
+    if (
+      !profileNames.has(profile) ||
+      !isTrimmedString(interaction) ||
+      interactionProfiles[interaction] !== profile ||
+      !isCanonicalStringArray(invalidates) ||
+      !isCanonicalStringArray(runsOn, runLocations) ||
+      !isCanonicalStringArray(workloadDimensions) ||
+      `performance-path:${encodeURIComponent(JSON.stringify(signature))}` !==
+        pathId
+    ) {
+      return undefined;
+    }
+    return Object.freeze({
+      interaction,
+      invalidates: Object.freeze([...invalidates]),
+      profile,
+      runsOn: Object.freeze([...runsOn]),
+      workloadDimensions: Object.freeze([...workloadDimensions]),
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+export function createToolcraftPerformancePathId(path) {
+  const signature = [
+    path.profile,
+    path.interaction,
+    path.invalidates,
+    path.runsOn,
+    path.workloadDimensions,
+  ];
+  const pathId = `performance-path:${encodeURIComponent(
+    JSON.stringify(signature),
+  )}`;
+  if (!decodeToolcraftPerformancePathId(pathId)) {
+    throw new Error(
+      "Toolcraft performance paths require a canonical runtime signature.",
+    );
+  }
+  return pathId;
+}