@pixel-point/toolcraft 0.0.17 → 0.0.19

package/templates/starter/src/app/acceptance/control-layout-dependency-rules.ts

@@ -1,6 +1,9 @@
 import type {
   ToolcraftControlConditionSchema,
-  ToolcraftControlSchema,
+  ResolvedToolcraftControlSchema,
+} from "@repo/toolcraft-runtime";
+import {
+  getToolcraftApplicabilityPredicates,
 } from "@repo/toolcraft-runtime";
 
 import type { ToolcraftControlLayoutFacts } from "./control-layout-model";
@@ -17,7 +20,7 @@ function normalizeToolcraftConditionValue(value: unknown): string | null {
 
 function getToolcraftConditionBranchTexts(
   condition: ToolcraftControlConditionSchema,
-  gateControl: ToolcraftControlSchema,
+  gateControl: ResolvedToolcraftControlSchema,
 ): string[] {
   const rawValues =
     "equals" in condition
@@ -44,7 +47,7 @@ function sectionTitleLooksLikeDependencyBranch({
   sectionTitle,
 }: {
   condition: ToolcraftControlConditionSchema;
-  gateControl: ToolcraftControlSchema;
+  gateControl: ResolvedToolcraftControlSchema;
   sectionTitle: string | undefined;
 }): boolean {
   const sectionText = normalizeToolcraftSemanticText(sectionTitle);
@@ -68,10 +71,18 @@ export function getToolcraftControlDependencyGroupingErrors(
   const errors: string[] = [];
 
   for (const item of facts.visibleControls) {
-    for (const [conditionName, condition] of [
-      ["visibleWhen", item.control.visibleWhen],
-      ["disabledWhen", item.control.disabledWhen],
-    ] as const) {
+    const conditions = [
+      ...getToolcraftApplicabilityPredicates(
+        item.control.applicability,
+      ).map(
+        (condition) => ["applicability", condition] as const,
+      ),
+      ...(item.control.disabledWhen
+        ? [["disabledWhen", item.control.disabledWhen] as const]
+        : []),
+    ];
+
+    for (const [conditionName, condition] of conditions) {
       if (!condition || !item.loosePrefix) {
         continue;
       }
@@ -86,7 +97,7 @@ export function getToolcraftControlDependencyGroupingErrors(
         gateControl.loosePrefix !== null &&
         gateControl.loosePrefix === item.loosePrefix;
       const looksLikeBranchSection =
-        conditionName === "visibleWhen" &&
+        conditionName === "applicability" &&
         sectionTitleLooksLikeDependencyBranch({
           condition,
           gateControl: gateControl.control,
@@ -98,7 +109,7 @@ export function getToolcraftControlDependencyGroupingErrors(
       }
 
       errors.push(
-        `${item.sectionLabel} / ${item.controlId} is gated by ${conditionName} target "${condition.target}" in ${gateControl.sectionLabel}, but it belongs to the same dependency group. Keep selectors and their dependent controls in one semantic section when they describe one product entity or branch; use visibleWhen for branch-specific controls inside that section instead of splitting branch controls into their own section. Do not use disabledWhen for product controls.`,
+        `${item.sectionLabel} / ${item.controlId} is gated by ${conditionName} target "${condition.target}" in ${gateControl.sectionLabel}, but it belongs to the same dependency group. Keep selectors and their dependent controls in one semantic section when they describe one product entity or branch; use conditional applicability for branch-specific controls inside that section instead of splitting branch controls into their own section. Do not use disabledWhen for product controls.`,
       );
     }
   }

package/templates/starter/src/app/acceptance/control-layout-entity-rules.ts

@@ -2,10 +2,8 @@ import {
   getToolcraftFontPickerOwnedTypographyPart,
 } from "./control-labels";
 import type { ToolcraftControlLayoutFacts } from "./control-layout-model";
-import {
-  getToolcraftSectionInventoryById,
-  hasToolcraftInventorySplitEvidence,
-} from "./control-section-inventory";
+import { hasToolcraftInventoryEntityAgreement } from "./control-section-entity-cohesion";
+import { getToolcraftSectionInventoryById } from "./control-section-inventory";
 import { getControlLabelText } from "./controls";
 import type { ToolcraftControlSectionInventoryEntry } from "./types";
 
@@ -60,13 +58,13 @@ function getToolcraftProductEntitySplitErrors({
   for (const [prefix, sections] of facts.strictPrefixSections) {
     if (
       sections.size > 1 &&
-      !hasToolcraftInventorySplitEvidence({ sectionInventoryById, sections })
+      !hasToolcraftInventoryEntityAgreement({ sectionInventoryById, sections })
     ) {
       const sectionLabels = [...sections].map(
         (sectionId) => facts.sectionLabelsById.get(sectionId) ?? sectionId,
       );
       errors.push(
-        `Controls for product entity "${prefix}" are split across sections: ${sectionLabels.join(", ")}. Keep controls for the same product entity in one semantic section unless the Control Section Inventory declares workflowStage and splitReason for every split section.`,
+        `Controls for target family "${prefix}" are split across sections: ${sectionLabels.join(", ")}. Assign one shared entityId when the sections edit one logical entity; the entity cohesion validator decides whether that split is allowed.`,
       );
     }
   }

package/templates/starter/src/app/acceptance/control-layout-model.ts

@@ -1,6 +1,6 @@
 import type {
   ResolvedToolcraftAppSchema,
-  ToolcraftControlSchema,
+  ResolvedToolcraftControlSchema,
 } from "@repo/toolcraft-runtime";
 
 import { isToolcraftProductSectionControl } from "./controls";
@@ -12,7 +12,7 @@ import {
 } from "./semantic";
 
 export type ToolcraftControlLayoutControlEntry = {
-  control: ToolcraftControlSchema;
+  control: ResolvedToolcraftControlSchema;
   controlId: string;
   loosePrefix: string | null;
   sectionLabel: string;
@@ -21,7 +21,7 @@ export type ToolcraftControlLayoutControlEntry = {
 };
 
 export type ToolcraftControlLayoutSectionFact = {
-  controls: readonly [string, ToolcraftControlSchema][];
+  controls: readonly [string, ResolvedToolcraftControlSchema][];
   sectionLabel: string;
   sectionId: string;
   sectionLoosePrefixes: ReadonlySet<string>;
@@ -41,7 +41,7 @@ export type ToolcraftControlLayoutFacts = {
 };
 
 function getToolcraftControlSemanticCluster(
-  control: ToolcraftControlSchema,
+  control: ResolvedToolcraftControlSchema,
 ): string {
   return (
     control.semanticGroup?.trim() ||

package/templates/starter/src/app/acceptance/control-layout-section-rules.ts

@@ -2,11 +2,14 @@ import {
   getToolcraftColorBankDescriptionError,
   getToolcraftColorBankLabelErrors,
 } from "./color-bank-labels";
+import { getToolcraftColorRowGroupingErrors } from "./color-row-grouping";
 import {
   getToolcraftControlDescriptionError,
+  getToolcraftDuplicateSectionTitleLabelError,
   getToolcraftGenericControlLabelError,
 } from "./control-labels";
 import type { ToolcraftControlLayoutFacts } from "./control-layout-model";
+import { TOOLCRAFT_DENSE_SECTION_MIN_CONTROLS } from "./control-section-entity-cohesion";
 import {
   controlTypeSectionTitlePattern,
   genericControlSectionTitlePattern,
@@ -15,9 +18,6 @@ import {
 const broadControlSectionTitlePattern =
   /^(animation|export|flow|icon|logo|motion|output|scene|shape|shapes|text|typography|visual|visuals)$/i;
 
-const maxPreferredControlsPerSection = 7;
-const maxHardControlsPerSection = 10;
-
 export function getToolcraftControlLayoutSectionInvariantErrors(
   facts: ToolcraftControlLayoutFacts,
 ): string[] {
@@ -55,7 +55,7 @@ export function getToolcraftControlLayoutSectionInvariantErrors(
       .map(([controlId]) => controlId);
 
     if (
-      controls.length > maxPreferredControlsPerSection &&
+      controls.length >= TOOLCRAFT_DENSE_SECTION_MIN_CONTROLS &&
       missingSemanticGroups.length > 0
     ) {
       errors.push(
@@ -63,6 +63,10 @@ export function getToolcraftControlLayoutSectionInvariantErrors(
       );
     }
     errors.push(
+      ...getToolcraftColorRowGroupingErrors({
+        controls,
+        sectionLabel,
+      }),
       ...getToolcraftColorBankLabelErrors({
         controls,
         sectionLabel,
@@ -71,6 +75,18 @@ export function getToolcraftControlLayoutSectionInvariantErrors(
     );
 
     for (const [controlId, control] of controls) {
+      const duplicateSectionTitleLabelError =
+        getToolcraftDuplicateSectionTitleLabelError({
+          control,
+          controlId,
+          sectionLabel,
+          sectionTitle,
+        });
+
+      if (duplicateSectionTitleLabelError) {
+        errors.push(duplicateSectionTitleLabelError);
+      }
+
       const genericLabelError = getToolcraftGenericControlLabelError({
         control,
         controlId,
@@ -135,7 +151,7 @@ export function getToolcraftControlLayoutSectionHeuristicErrors(
       sectionTitle !== undefined && broadControlSectionTitlePattern.test(sectionTitle);
 
     if (
-      controls.length > maxPreferredControlsPerSection &&
+      controls.length >= TOOLCRAFT_DENSE_SECTION_MIN_CONTROLS &&
       hasBroadSectionTitle &&
       semanticClusters.size >= 3
     ) {
@@ -144,11 +160,6 @@ export function getToolcraftControlLayoutSectionHeuristicErrors(
       );
     }
 
-    if (controls.length > maxHardControlsPerSection && semanticClusters.size > 1) {
-      errors.push(
-        `${sectionLabel} has ${controls.length} controls across ${semanticClusters.size} semantic clusters (${clusterList}). Controls-panel sections should stay discrete; split sections that grow past ${maxHardControlsPerSection} controls unless every control edits one tightly scoped entity.`,
-      );
-    }
   }
 
   return errors;

package/templates/starter/src/app/acceptance/control-parts.ts

@@ -10,6 +10,12 @@ export function getRequiredToolcraftControlPartCoverage(
       return ["anchorGrid.position"];
     case "channelMixer":
       return ["channelMixer.activeChannel", "channelMixer.values"];
+    case "collectionActions":
+      return [
+        "collectionActions.add",
+        "collectionActions.remove",
+        "collectionActions.items",
+      ];
     case "curves":
       return control.variant === "single"
         ? ["curves.points"]
@@ -39,6 +45,8 @@ export function getRequiredToolcraftControlPartCoverage(
       return ["rangeInput.start", "rangeInput.end"];
     case "rangeSlider":
       return ["rangeSlider.lower", "rangeSlider.upper"];
+    case "sourceCollection":
+      return ["sourceCollection.items"];
     case "vector":
       return ["vector.x", "vector.y"];
     default:

package/templates/starter/src/app/acceptance/control-section-entity-cohesion.test.ts

@@ -0,0 +1,215 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  getToolcraftControlSectionEntityCohesionErrors,
+  hasToolcraftInventoryEntityAgreement,
+} from "./control-section-entity-cohesion";
+import type { ToolcraftControlSectionInventoryEntry } from "./types";
+
+function makeSection({
+  count,
+  entity = "Renderable object",
+  entityId = "renderable-object",
+  id = "object",
+  splitReason,
+  workflowStage,
+}: {
+  count: number;
+  entity?: string;
+  entityId?: string;
+  id?: string;
+  splitReason?: string;
+  workflowStage?: string;
+}): ToolcraftControlSectionInventoryEntry {
+  return {
+    entity,
+    entityId,
+    groupingReason: `The ${id} controls edit one coherent part of the entity.`,
+    id,
+    splitReason,
+    targets: Array.from(
+      { length: count },
+      (_, index) => `${id}.value${index + 1}`,
+    ),
+    title: id,
+    workflowStage,
+  };
+}
+
+describe("Toolcraft control section entity cohesion", () => {
+  it.each([1, 7, 8, 10])(
+    "accepts one entity in one section with %s controls",
+    (count) => {
+      expect(
+        getToolcraftControlSectionEntityCohesionErrors([
+          makeSection({ count }),
+        ]),
+      ).toEqual([]);
+    },
+  );
+
+  it("rejects splitting an entity that fits in one section", () => {
+    const errors = getToolcraftControlSectionEntityCohesionErrors([
+      makeSection({ count: 3, id: "object-source" }),
+      makeSection({ count: 4, id: "object-style" }),
+    ]);
+
+    expect(errors).toContain(
+      'Control Section Inventory entity "renderable-object" owns 7 controls across 2 sections (object-source, object-style). Entities with 10 or fewer controls must stay in one section.',
+    );
+  });
+
+  it("rejects an entity above the hard maximum left in one section", () => {
+    expect(
+      getToolcraftControlSectionEntityCohesionErrors([
+        makeSection({ count: 11 }),
+      ]),
+    ).toContain(
+      'Control Section Inventory entity "renderable-object" owns 11 controls in section object. Split entities above 10 controls into explicit workflow stages.',
+    );
+  });
+
+  it("accepts a balanced large-entity workflow split", () => {
+    expect(
+      getToolcraftControlSectionEntityCohesionErrors([
+        makeSection({
+          count: 5,
+          id: "object-structure",
+          splitReason: "Structure is authored before the finishing workflow.",
+          workflowStage: "structure",
+        }),
+        makeSection({
+          count: 6,
+          id: "object-finish",
+          splitReason: "Finish is authored after the structural workflow.",
+          workflowStage: "finish",
+        }),
+      ]),
+    ).toEqual([]);
+  });
+
+  it("rejects a one-control tail in a split entity", () => {
+    expect(
+      getToolcraftControlSectionEntityCohesionErrors([
+        makeSection({
+          count: 10,
+          id: "object-primary",
+          splitReason: "Primary editing precedes the final workflow stage.",
+          workflowStage: "primary",
+        }),
+        makeSection({
+          count: 1,
+          id: "object-final",
+          splitReason: "The final workflow follows primary editing.",
+          workflowStage: "final",
+        }),
+      ]),
+    ).toContain(
+      'Control Section Inventory entity "renderable-object" section object-final owns 1 control. Every section in a split entity must own between 2 and 10 controls.',
+    );
+  });
+
+  it("rejects a split section above the per-section maximum", () => {
+    expect(
+      getToolcraftControlSectionEntityCohesionErrors([
+        makeSection({
+          count: 11,
+          id: "object-primary",
+          splitReason: "Primary editing precedes the final workflow stage.",
+          workflowStage: "primary",
+        }),
+        makeSection({
+          count: 2,
+          id: "object-final",
+          splitReason: "The final workflow follows primary editing.",
+          workflowStage: "final",
+        }),
+      ]),
+    ).toContain(
+      'Control Section Inventory entity "renderable-object" section object-primary owns 11 controls. Every section in a split entity must own between 2 and 10 controls.',
+    );
+  });
+
+  it("requires a workflow stage on every section of a split entity", () => {
+    expect(
+      getToolcraftControlSectionEntityCohesionErrors([
+        makeSection({
+          count: 6,
+          id: "object-primary",
+          splitReason: "Primary editing precedes the final workflow stage.",
+        }),
+        makeSection({
+          count: 6,
+          id: "object-final",
+          splitReason: "The final workflow follows primary editing.",
+          workflowStage: "final",
+        }),
+      ]),
+    ).toContain(
+      'Control Section Inventory entity "renderable-object" section object-primary must declare workflowStage because the entity is split across sections.',
+    );
+  });
+
+  it("requires complete, unique split evidence and a consistent entity name", () => {
+    const errors = getToolcraftControlSectionEntityCohesionErrors([
+      makeSection({ count: 6, id: "object-a", workflowStage: "edit" }),
+      makeSection({
+        count: 6,
+        entity: "Different label",
+        id: "object-b",
+        splitReason: "This section follows the first editing stage.",
+        workflowStage: "edit",
+      }),
+    ]);
+
+    expect(errors).toEqual(
+      expect.arrayContaining([
+        expect.stringContaining("uses inconsistent entity names"),
+        expect.stringContaining("object-a must declare splitReason"),
+        expect.stringContaining('repeats workflowStage "edit"'),
+      ]),
+    );
+  });
+
+  it("keeps independent entities independent", () => {
+    expect(
+      getToolcraftControlSectionEntityCohesionErrors([
+        makeSection({ count: 4, entityId: "entity-a", id: "entity-a" }),
+        makeSection({ count: 4, entityId: "entity-b", id: "entity-b" }),
+      ]),
+    ).toEqual([]);
+  });
+
+  it("requires one shared entityId for target-prefix corroboration", () => {
+    const first = makeSection({ count: 6, id: "first" });
+    const second = makeSection({
+      count: 6,
+      entityId: "different-entity",
+      id: "second",
+    });
+    const sectionInventoryById = new Map([
+      [first.id, first],
+      [second.id, second],
+    ]);
+    const sections = new Set([first.id, second.id]);
+
+    expect(
+      hasToolcraftInventoryEntityAgreement({
+        sectionInventoryById,
+        sections,
+      }),
+    ).toBe(false);
+
+    sectionInventoryById.set(second.id, {
+      ...second,
+      entityId: first.entityId,
+    });
+
+    expect(
+      hasToolcraftInventoryEntityAgreement({
+        sectionInventoryById,
+        sections,
+      }),
+    ).toBe(true);
+  });
+});

package/templates/starter/src/app/acceptance/control-section-entity-cohesion.ts

@@ -0,0 +1,132 @@
+import type { ToolcraftControlSectionInventoryEntry } from "./types";
+
+export const TOOLCRAFT_DENSE_SECTION_MIN_CONTROLS = 8;
+
+const TOOLCRAFT_MAX_CONTROLS_PER_SECTION = 10;
+const TOOLCRAFT_MIN_CONTROLS_PER_SPLIT_SECTION = 2;
+const TOOLCRAFT_MIN_SPLIT_REASON_LENGTH = 12;
+
+export function hasToolcraftInventoryEntityAgreement({
+  sectionInventoryById,
+  sections,
+}: {
+  sectionInventoryById: ReadonlyMap<
+    string,
+    ToolcraftControlSectionInventoryEntry
+  >;
+  sections: ReadonlySet<string>;
+}): boolean {
+  const entries = [...sections].map((sectionId) =>
+    sectionInventoryById.get(sectionId),
+  );
+  const entityIds = entries.map((entry) => entry?.entityId?.trim() ?? "");
+
+  return entityIds.every(Boolean) && new Set(entityIds).size === 1;
+}
+
+export function getToolcraftControlSectionEntityCohesionErrors(
+  sectionInventory: readonly ToolcraftControlSectionInventoryEntry[],
+): string[] {
+  const errors: string[] = [];
+  const entriesByEntityId = new Map<
+    string,
+    ToolcraftControlSectionInventoryEntry[]
+  >();
+
+  for (const entry of sectionInventory) {
+    const entityId = entry.entityId?.trim() ?? "";
+    const entity = entry.entity?.trim() ?? "";
+
+    if (
+      !entityId ||
+      !entity ||
+      (entry.id?.trim().length ?? 0) === 0 ||
+      !Array.isArray(entry.targets) ||
+      entry.targets.length === 0
+    ) {
+      continue;
+    }
+
+    const entries = entriesByEntityId.get(entityId) ?? [];
+    entries.push(entry);
+    entriesByEntityId.set(entityId, entries);
+  }
+
+  for (const [entityId, entries] of entriesByEntityId) {
+    const controlCount = entries.reduce(
+      (total, entry) => total + entry.targets.length,
+      0,
+    );
+    const sectionNames = entries.map((entry) => entry.title.trim() || entry.id);
+    const entityNames = new Set(entries.map((entry) => entry.entity.trim()));
+
+    if (entityNames.size > 1) {
+      errors.push(
+        `Control Section Inventory entity "${entityId}" uses inconsistent entity names: ${[
+          ...entityNames,
+        ].join(", ")}. Reuse one human-readable entity name for every section in the entity.`,
+      );
+    }
+
+    if (controlCount <= TOOLCRAFT_MAX_CONTROLS_PER_SECTION) {
+      if (entries.length > 1) {
+        errors.push(
+          `Control Section Inventory entity "${entityId}" owns ${controlCount} controls across ${entries.length} sections (${sectionNames.join(", ")}). Entities with ${TOOLCRAFT_MAX_CONTROLS_PER_SECTION} or fewer controls must stay in one section.`,
+        );
+      }
+      continue;
+    }
+
+    if (entries.length === 1) {
+      errors.push(
+        `Control Section Inventory entity "${entityId}" owns ${controlCount} controls in section ${sectionNames[0]}. Split entities above ${TOOLCRAFT_MAX_CONTROLS_PER_SECTION} controls into explicit workflow stages.`,
+      );
+      continue;
+    }
+
+    const sectionsByStage = new Map<string, string[]>();
+
+    for (const entry of entries) {
+      const sectionName = entry.title.trim() || entry.id;
+      const sectionControlCount = entry.targets.length;
+      const workflowStage = entry.workflowStage?.trim() ?? "";
+      const splitReason = entry.splitReason?.trim() ?? "";
+
+      if (
+        sectionControlCount < TOOLCRAFT_MIN_CONTROLS_PER_SPLIT_SECTION ||
+        sectionControlCount > TOOLCRAFT_MAX_CONTROLS_PER_SECTION
+      ) {
+        errors.push(
+          `Control Section Inventory entity "${entityId}" section ${sectionName} owns ${sectionControlCount} ${sectionControlCount === 1 ? "control" : "controls"}. Every section in a split entity must own between ${TOOLCRAFT_MIN_CONTROLS_PER_SPLIT_SECTION} and ${TOOLCRAFT_MAX_CONTROLS_PER_SECTION} controls.`,
+        );
+      }
+
+      if (!workflowStage) {
+        errors.push(
+          `Control Section Inventory entity "${entityId}" section ${sectionName} must declare workflowStage because the entity is split across sections.`,
+        );
+      } else {
+        const normalizedStage = workflowStage.toLowerCase();
+        const stageSections = sectionsByStage.get(normalizedStage) ?? [];
+        stageSections.push(sectionName);
+        sectionsByStage.set(normalizedStage, stageSections);
+      }
+
+      if (splitReason.length < TOOLCRAFT_MIN_SPLIT_REASON_LENGTH) {
+        errors.push(
+          `Control Section Inventory entity "${entityId}" section ${sectionName} must declare splitReason of at least ${TOOLCRAFT_MIN_SPLIT_REASON_LENGTH} characters because the entity is split across sections.`,
+        );
+      }
+    }
+
+    for (const [stage, stageSections] of sectionsByStage) {
+      if (stageSections.length > 1) {
+        errors.push(
+          `Control Section Inventory entity "${entityId}" repeats workflowStage "${stage}" across sections ${stageSections.join(", ")}. Workflow stages must be unique within one entity.`,
+        );
+      }
+    }
+  }
+
+  return errors;
+}

package/templates/starter/src/app/acceptance/control-section-inventory.test.ts

@@ -40,6 +40,7 @@ function createSchema({
 
 const inventoryEntry = {
   entity: "Appearance",
+  entityId: "appearance",
   groupingReason: "These controls define the visible appearance of the output.",
   id: "appearance",
   targets: ["appearance.opacity"],
@@ -56,6 +57,53 @@ describe("Toolcraft Control Section Inventory identity", () => {
     ).toEqual([]);
   });
 
+  it("preserves inventory ownership when runtime Setup relocates product background controls", () => {
+    const schema = defineToolcraft({
+      canvas: { enabled: true },
+      panels: {
+        controls: {
+          sections: [
+            {
+              controls: {
+                background: {
+                  applicability: { mode: "always" },
+                  defaultValue: "#101010",
+                  target: "appearance.background",
+                  type: "color",
+                },
+                includeBackground: {
+                  applicability: { mode: "always" },
+                  defaultValue: true,
+                  target: "export.includeBackground",
+                  type: "switch",
+                },
+              },
+              id: "background",
+              title: "Background",
+            },
+          ],
+          title: "Controls",
+        },
+      },
+    });
+    const backgroundInventory = {
+      entity: "Output background",
+      entityId: "output-background",
+      groupingReason:
+        "Inclusion and color jointly define the exported background.",
+      id: "background",
+      targets: ["export.includeBackground", "appearance.background"],
+      title: "Background",
+    } as const;
+
+    expect(schema.panels.controls?.sections[0]?.id).toBe("runtime.setup");
+    expect(
+      getToolcraftControlSectionInventoryErrors(schema, [
+        backgroundInventory,
+      ]),
+    ).toEqual([]);
+  });
+
   it("rejects an inventory id that does not match the schema section", () => {
     const errors = getToolcraftControlSectionInventoryErrors(createSchema(), [
       { ...inventoryEntry, id: "different-section" },
@@ -80,6 +128,45 @@ describe("Toolcraft Control Section Inventory identity", () => {
     );
   });
 
+  it.each([
+    [
+      "blank entityId",
+      { ...inventoryEntry, entityId: "" },
+      'Control Section Inventory entry "Original title" must declare a non-empty stable entityId.',
+    ],
+    [
+      "blank entity",
+      { ...inventoryEntry, entity: "" },
+      'Control Section Inventory entry "Original title" must declare a human-readable entity name.',
+    ],
+  ])("rejects %s", (_label, entry, expectedMessage) => {
+    expect(
+      getToolcraftControlSectionInventoryErrors(createSchema(), [entry]),
+    ).toContain(expectedMessage);
+  });
+
+  it("rejects a missing entityId without throwing", () => {
+    const { entityId: _entityId, ...entryWithoutEntityId } = inventoryEntry;
+    const malformedInventory = [
+      entryWithoutEntityId,
+    ] as unknown as readonly ToolcraftControlSectionInventoryEntry[];
+
+    expect(() =>
+      getToolcraftControlSectionInventoryErrors(
+        createSchema(),
+        malformedInventory,
+      ),
+    ).not.toThrow();
+    expect(
+      getToolcraftControlSectionInventoryErrors(
+        createSchema(),
+        malformedInventory,
+      ),
+    ).toContain(
+      'Control Section Inventory entry "Original title" must declare a non-empty stable entityId.',
+    );
+  });
+
   it.each([
     ["missing", undefined],
     ["non-string", 42],