Skip to content

Open-source manufacturing ERP, MES and QMS. Quoting, MRP, inventory, shop floor, quality and lot/serial traceability on one Postgres schema, with a REST API and MCP server. Self-host or use Carbon Cloud.

51.7 KB
Raw Blame
// SPDX-License-Identifier: AGPL-3.0-only
// Carbon (github.com/crbnos/carbon). Modified or adapted versions of this file,
// including ports, remain AGPLv3; serving them over a network requires releasing their source.

import type { PostgrestError } from "@supabase/supabase-js";
import { z } from "zod";
import { zfd } from "zod-form-data";
import { nonConformancePriority } from "../quality/quality.models";
import {
  methodItemType,
  methodOperationOrders,
  methodType,
  operationTypes,
  sourcingType,
  standardFactorType
} from "../shared/shared.models";

export const batchPropertyDataTypes = [
  "text",
  "numeric",
  "boolean",
  "list",
  "date"
] as const;

export const configurationParameterDataTypes = [
  "text",
  "numeric",
  "boolean",
  "list",
  "material"
] as const;

export const itemTrackingTypes = [
  "Inventory",
  "Non-Inventory",
  "Serial",
  "Batch"
] as const;

export const ItemTrackingType = {
  Inventory: "Inventory",
  NonInventory: "Non-Inventory",
  Serial: "Serial",
  Batch: "Batch"
} as const satisfies Record<string, (typeof itemTrackingTypes)[number]>;

export const itemCostingMethods = [
  "Standard",
  "Average",
  "FIFO",
  "LIFO"
] as const;

export const itemReorderingPolicies = [
  "Manual Reorder",
  "Demand-Based Reorder",
  "Fixed Reorder Quantity",
  "Maximum Quantity"
] as const;

export const itemReplenishmentSystems = [
  "Buy",
  "Make",
  "Buy and Make"
] as const;

/** The fields the item tables' bulk Update sets on many items at once. */
export const itemBulkUpdateFields = [
  "itemPostingGroupId",
  "replenishmentSystem",
  "defaultMethodType",
  "sourcingType",
  "itemTrackingType"
] as const;

export type ItemBulkUpdateField = (typeof itemBulkUpdateFields)[number];

export function isItemBulkUpdateField(
  field: unknown
): field is ItemBulkUpdateField {
  return itemBulkUpdateFields.some((allowed) => allowed === field);
}

/** One field set on many items (the items tables' Update): the field and a
 *  value it takes. Any item group id, or none, is a value. */
export const itemBulkUpdateValidator = z.discriminatedUnion("field", [
  z.object({
    field: z.literal("itemTrackingType"),
    value: z.enum(itemTrackingTypes)
  }),
  z.object({
    field: z.literal("replenishmentSystem"),
    value: z.enum(itemReplenishmentSystems)
  }),
  z.object({
    field: z.literal("defaultMethodType"),
    value: z.enum(methodType)
  }),
  z.object({ field: z.literal("sourcingType"), value: z.enum(sourcingType) }),
  z.object({ field: z.literal("itemPostingGroupId"), value: z.string() })
]);

export type ItemBulkUpdate = z.infer<typeof itemBulkUpdateValidator>;

// Maps an edit of ONE of the three interlocked item-level fields
// (replenishmentSystem, defaultMethodType, sourcingType) to the columns that must
// change together on the item, plus the values to mirror down to method materials.
// Pure — no DB access — so the interlock rule lives in ONE place, shared by the
// inline item-update route (x+/items+/update.tsx) and the change-order attributes
// editor. Keeping them in sync via a hand-copied mapping is exactly the drift this
// avoids.
export function deriveItemMethodUpdate(
  field: "replenishmentSystem" | "defaultMethodType" | "sourcingType",
  value: string
): {
  itemUpdate: {
    replenishmentSystem?: (typeof itemReplenishmentSystems)[number];
    defaultMethodType?: (typeof methodType)[number];
    sourcingType?: (typeof sourcingType)[number];
  };
  cascade: {
    sourcingType?: (typeof sourcingType)[number];
    methodType?: (typeof methodType)[number];
  };
} {
  switch (field) {
    case "replenishmentSystem": {
      const replenishmentSystem =
        value as (typeof itemReplenishmentSystems)[number];
      // Picking a concrete replenishment system pins the default method type.
      if (value !== "Buy and Make") {
        const defaultMethodType: (typeof methodType)[number] =
          value === "Make"
            ? "Make to Order"
            : value === "Buy"
              ? "Purchase to Order"
              : "Pull from Inventory";
        return {
          itemUpdate: { replenishmentSystem, defaultMethodType },
          cascade: { methodType: defaultMethodType }
        };
      }
      return { itemUpdate: { replenishmentSystem }, cascade: {} };
    }
    case "defaultMethodType": {
      const defaultMethodType = value as (typeof methodType)[number];
      // A concrete method type pins the replenishment system to match.
      if (value !== "Pull from Inventory") {
        const replenishmentSystem: (typeof itemReplenishmentSystems)[number] =
          value === "Make to Order"
            ? "Make"
            : value === "Purchase to Order"
              ? "Buy"
              : "Buy and Make";
        return {
          itemUpdate: { defaultMethodType, replenishmentSystem },
          cascade: { methodType: defaultMethodType }
        };
      }
      return {
        itemUpdate: { defaultMethodType },
        cascade: { methodType: defaultMethodType }
      };
    }
    case "sourcingType": {
      const sourcingTypeValue = value as (typeof sourcingType)[number];
      // Sourcing drives method type: Drop Ship → Purchase to Order, Ship from
      // Inventory → Pull from Inventory, Specified → leave method type as-is.
      const derivedMethodType: (typeof methodType)[number] | undefined =
        value === "Drop Ship"
          ? "Purchase to Order"
          : value === "Ship from Inventory"
            ? "Pull from Inventory"
            : undefined;
      return {
        itemUpdate: {
          sourcingType: sourcingTypeValue,
          ...(derivedMethodType ? { defaultMethodType: derivedMethodType } : {})
        },
        cascade: {
          sourcingType: sourcingTypeValue,
          methodType: derivedMethodType
        }
      };
    }
  }
}

export const shelfLifeModes = [
  "NotManaged",
  "Fixed Duration",
  "Calculated",
  "Set on Receipt"
] as const;

export const shelfLifeTriggerTimings = ["Before", "After"] as const;

export const partManufacturingPolicies = [
  "Make to Stock",
  "Make to Order"
] as const;

// Services are Buy or Make only — never "Buy and Make", and never stocked
// ("Pull from Inventory" is not a valid method for a Non-Inventory item).
export const serviceReplenishmentSystems = ["Buy", "Make"] as const;

export const supplierPartPriceSourceTypes = [
  "Quote",
  "Purchase Order",
  "Manual Entry"
] as const;

export const itemValidator = z.object({
  id: z.string().min(1, { message: "Item ID is required" }).max(255),
  readableId: zfd.text(z.string().optional()),
  name: z
    .string()
    .min(1, { message: "Short description is required" })
    .max(255),
  description: zfd.text(z.string().optional()),
  // Manufacturer Part Number — the manufacturer's catalog number for a
  // purchased item. Only surfaced/edited for Buy items in the Properties panel.
  mpn: zfd.text(z.string().optional()),
  replenishmentSystem: z.enum(itemReplenishmentSystems, {
    error: "Replenishment system is required"
  }),
  defaultMethodType: z.enum(methodType, {
    error: "Default method is required"
  }),
  itemTrackingType: z.enum(itemTrackingTypes, {
    error: "Part type is required"
  }),
  postingGroupId: zfd.text(z.string().optional()),
  unitOfMeasureCode: z
    .string()
    .min(1, { message: "Unit of Measure is required" }),
  unitCost: zfd.numeric(z.number().nonnegative().optional()),
  // Default storage unit (form-only; persisted to pickMethod via
  // upsertItemDefaultPickMethod). Can point at any level of the
  // storageUnit hierarchy since storageUnit nests via parentId. The
  // locationId is derived server-side from storageUnit.locationId -
  // the form itself does not capture a location.
  defaultStorageUnitId: zfd.text(z.string().optional()),
  // Shelf life. The UI Select only surfaces "Fixed Duration" / "Calculated";
  // clearing it (X button) submits an empty string, which we preprocess to
  // the sentinel "NotManaged" so the server deletes any existing
  // itemShelfLife row. Truly absent fields (non-form callers like MCP that
  // don't set shelfLifeMode at all) remain undefined, which the upsert
  // helper treats as a no-op.
  shelfLifeMode: z
    .union([z.literal(""), z.enum(shelfLifeModes)])
    .transform((v) => (v === "" ? "NotManaged" : v))
    .optional(),
  shelfLifeDays: zfd.numeric(z.number().positive().optional()),
  shelfLifeTriggerProcessId: zfd.text(z.string().optional()),
  // Whether the clock starts when the trigger process begins ('Before') or
  // completes ('After'). Only meaningful with Fixed Duration + a trigger
  // process; ignored otherwise. Defaults to 'After' to preserve legacy
  // behavior on items that pre-date this column.
  shelfLifeTriggerTiming: z.enum(shelfLifeTriggerTimings).optional(),
  // Fixed Duration + Make items only: when true, the produced expiry is
  // capped by the earliest input expiry — the output cannot outlast its
  // raw materials. Falls back to today + days when no input has a date.
  // Mirrors the inventory-settings "Calculate from BOM" copy.
  shelfLifeCalculateFromBom: zfd.checkbox()
});

// Common storage / shelf-life refines. Shared across all item-type
// validators. Default Storage Unit is optional for every type - users can
// set it later via the pickMethod UI once they know where the item lives.
export const applyStorageAndShelfLifeRefines = <T extends z.ZodObject>(
  schema: T
) => {
  const refined: z.ZodType<z.infer<T>, z.input<T>> = schema
    .refine(
      (data: z.infer<T>) =>
        data.shelfLifeDays === undefined ||
        data.shelfLifeMode === "Fixed Duration",
      {
        message:
          "Shelf-life days can only be set when shelf-life management is Fixed Duration",
        path: ["shelfLifeDays"]
      }
    )
    .refine(
      (data: z.infer<T>) =>
        data.shelfLifeMode !== "Fixed Duration" ||
        data.shelfLifeDays !== undefined,
      {
        message:
          "Shelf-life days is required when shelf-life management is Fixed Duration",
        path: ["shelfLifeDays"]
      }
    )
    .refine(
      (data: z.infer<T>) =>
        !data.shelfLifeTriggerProcessId ||
        data.shelfLifeMode === "Fixed Duration",
      {
        message:
          "Trigger process can only be set when shelf-life management is Fixed Duration",
        path: ["shelfLifeTriggerProcessId"]
      }
    )
    .refine(
      (data: z.infer<T>) =>
        !data.shelfLifeMode ||
        data.shelfLifeMode === "NotManaged" ||
        data.itemTrackingType === "Serial" ||
        data.itemTrackingType === "Batch",
      {
        message:
          "Shelf-life can only be managed on items tracked by Serial or Batch - there's no per-unit record to set the expiry on otherwise",
        path: ["shelfLifeMode"]
      }
    )
    .refine(
      (data: z.infer<T>) =>
        data.shelfLifeMode !== "Calculated" ||
        data.replenishmentSystem !== "Buy",
      {
        message:
          "Component minimum shelf-life requires a BoM - only Make or Buy and Make items qualify",
        path: ["shelfLifeMode"]
      }
    )
    .refine(
      (data: z.infer<T>) =>
        data.shelfLifeMode !== "Set on Receipt" ||
        data.replenishmentSystem !== "Make",
      {
        message:
          "Set on receipt applies at goods-in - only Buy or Buy and Make items qualify",
        path: ["shelfLifeMode"]
      }
    )
    .refine(
      (data: z.infer<T>) =>
        !data.shelfLifeCalculateFromBom ||
        data.shelfLifeMode === "Fixed Duration",
      {
        message: "Calculate from BOM only applies to Fixed Duration shelf life",
        path: ["shelfLifeCalculateFromBom"]
      }
    )
    .refine(
      (data: z.infer<T>) =>
        !data.shelfLifeCalculateFromBom || data.replenishmentSystem !== "Buy",
      {
        message:
          "Calculate from BOM requires a BoM - only Make or Buy and Make items qualify",
        path: ["shelfLifeCalculateFromBom"]
      }
    ) as unknown as z.ZodType<z.infer<T>, z.input<T>>;

  return refined;
};

export const configurationParameterGroupValidator = z.object({
  id: zfd.text(z.string().optional()),
  name: z.string().trim().min(1, { message: "Name is required" })
});

export const configurationParameterGroupOrderValidator = z.object({
  id: z.string().min(1, { message: "ID is required" }),
  sortOrder: zfd.numeric(z.number().min(0))
});

export const configurationParameterOrderValidator = z.object({
  id: z.string().min(1, { message: "ID is required" }),
  sortOrder: zfd.numeric(z.number().min(0)),
  configurationParameterGroupId: zfd.text(z.string().nullable())
});

export const configurationParameterValidator = z
  .object({
    id: zfd.text(z.string().optional()),
    itemId: z.string().min(1, { message: "Item ID is required" }),
    key: zfd.text(z.string().optional()),
    label: z.string().min(1, { message: "Label is required" }),
    dataType: z.enum([...configurationParameterDataTypes, "date"]),
    listOptions: z.string().min(1).array().optional(),
    configurationParameterGroupId: z.string().optional(),
    materialFormFilterId: zfd.text(z.string().optional())
  })
  .refine(
    (data) => {
      if (data.dataType === "list") {
        return !!data.listOptions;
      }
      return true;
    },
    { message: "List options are required", path: ["listOptions"] }
  )

  .refine(
    (data) => {
      return data.key?.match(/^[a-zA-Z0-9]+(_[a-zA-Z0-9]+)*$/);
    },
    { message: "Key must be lowercase and underscore separated" }
  );

export const configurationRuleValidator = z.object({
  field: z.string().min(1, { message: "Field is required" }),
  code: z.string().min(1, { message: "Code is required" })
});

export const consumableValidator = applyStorageAndShelfLifeRefines(
  itemValidator.merge(
    z.object({
      id: z.string().min(1, { message: "Consumable ID is required" }).max(255),
      unitOfMeasureCode: z
        .string()
        .min(1, { message: "Unit of Measure is required" })
    })
  )
);

export const customerPartValidator = z.object({
  id: zfd.text(z.string().optional()),
  itemId: z.string().min(1, { message: "Item ID is required" }),
  customerId: z.string().min(1, { message: "Customer is required" }),
  customerPartId: z.string(),
  customerPartRevision: zfd.text(z.string().optional())
});

export const getMethodValidator = z.object({
  targetId: z.string().min(1, { message: "Please select a target method" }),
  sourceId: z.string().min(1, { message: "Please select a source method" }),
  billOfMaterial: zfd.checkbox(),
  billOfProcess: zfd.checkbox(),
  parameters: zfd.checkbox(),
  tools: zfd.checkbox(),
  steps: zfd.checkbox(),
  workInstructions: zfd.checkbox()
});

export const makeMethodVersionValidator = z.object({
  copyFromId: z.string().min(1, { message: "Please select a source method" }),
  activeVersionId: zfd.text(z.string().optional()),
  version: zfd.numeric(z.number().min(0, { message: "Please enter a version" }))
});

export const materialValidator = applyStorageAndShelfLifeRefines(
  itemValidator.merge(
    z.object({
      id: z.string().min(1, { message: "Material ID is required" }).max(255),
      materialSubstanceId: zfd.text(z.string().optional()),
      materialFormId: zfd.text(z.string().optional()),
      materialTypeId: zfd.text(z.string().optional()),
      finishId: zfd.text(z.string().optional()),
      gradeId: zfd.text(z.string().optional()),
      dimensionId: zfd.text(z.string().optional()),
      sizes: z.array(z.string()).optional()
    })
  )
);

export const materialValidatorWithGeneratedIds = z.object({
  id: z.string().min(1, { message: "" }),
  materialSubstanceId: z.string().min(1, { message: "Substance is required" }),
  materialFormId: z.string().min(1, { message: "Shape is required" }),
  materialTypeId: zfd.text(z.string().optional()),
  finishId: zfd.text(z.string().optional()),
  gradeId: zfd.text(z.string().optional()),
  dimensionId: zfd.text(z.string().optional()),
  sizes: z.array(z.string()).optional()
});

export const methodMaterialValidator = z.object({
  id: z.string().trim().min(1, { message: "Material ID is required" }),
  makeMethodId: z.string().min(1, { message: "Make method is required" }),
  order: zfd.numeric(z.number().min(0)),
  itemType: z.enum(methodItemType, {
    error: "Item type is required"
  }),
  kit: zfd.text(z.string().optional()).transform((value) => value === "true"),
  methodType: z.enum(methodType, {
    error: "Method type is required"
  }),
  sourcingType: z.enum(sourcingType, {
    error: "Sourcing type is required"
  }),
  itemId: z.string().optional(),
  methodOperationId: zfd.text(z.string().optional()),
  // description: z.string().min(1, { message: "Description is required" }),
  quantity: zfd.numeric(z.number().min(0)),
  unitOfMeasureCode: z
    .string()
    .min(1, { message: "Unit of Measure is required" }),
  // A location → storageUnitId map. The BoM web form submits it as a JSON string
  // (`<Hidden value={JSON.stringify(...)} />`); the MCP/API layer sends the object
  // map directly. `preprocess` accepts both — a string is JSON-parsed (a malformed
  // string stays a string and is REJECTED by the record below, never silently
  // stored) — and the input JSON Schema published to MCP is a clean object map.
  // `nullish` lets a caller omit it or send `null` to clear (the service applies
  // the create/update semantics: omitted → preserve on update / {} on create,
  // explicit null/{} → clear).
  storageUnitIds: z
    .preprocess(
      (val) => {
        if (typeof val !== "string") return val;
        try {
          return JSON.parse(val);
        } catch {
          return val;
        }
      },
      z.record(z.string(), z.string())
    )
    .nullish()
});

export const methodOperationValidator = z
  .object({
    id: z.string().min(1, { message: "Operation ID is required" }),
    makeMethodId: z.string().min(0, { message: "Make method is required" }),
    order: zfd.numeric(z.number().min(0)),
    operationOrder: z.enum(methodOperationOrders, {
      error: "Operation order is required"
    }),
    operationType: z.enum(operationTypes, {
      error: "Operation type is required"
    }),
    processId: z.string().min(1, { message: "Process is required" }),
    workCenterId: zfd.text(z.string().optional()),
    procedureId: zfd.text(z.string().optional()),
    assemblyInstructionId: zfd.text(z.string().optional()),
    inspectionDocumentId: zfd.text(z.string().optional()),
    description: zfd.text(
      z.string().min(0, { message: "Description is required" })
    ),
    setupUnit: z
      .enum(standardFactorType, {
        error: "Setup unit is required"
      })
      .optional(),
    setupTime: zfd.numeric(z.number().min(0).optional()),
    laborUnit: z
      .enum(standardFactorType, {
        error: "Labor unit is required"
      })
      .optional(),
    laborTime: zfd.numeric(z.number().min(0).optional()),
    machineUnit: z
      .enum(standardFactorType, {
        error: "Machine unit is required"
      })
      .optional(),
    machineTime: zfd.numeric(z.number().min(0).optional()),
    operationSupplierProcessId: zfd.text(z.string().optional()),
    operationMinimumCost: zfd.numeric(z.number().min(0).optional()),
    operationUnitCost: zfd.numeric(z.number().min(0).optional()),
    operationLeadTime: zfd.numeric(z.number().min(0).optional())
  })
  .refine(
    (data) => {
      if (data.operationType !== "Outside Processing") {
        return !!data.setupUnit;
      }
      return true;
    },
    {
      message: "Setup unit is required",
      path: ["setupUnit"]
    }
  )
  .refine(
    (data) => {
      if (data.operationType !== "Outside Processing") {
        return !!data.laborUnit;
      }
      return true;
    },
    {
      message: "Labor unit is required",
      path: ["laborUnit"]
    }
  )
  .refine(
    (data) => {
      // Machine only applies to Process operations — Assembly and Inspection
      // are setup + labor work.
      if (data.operationType === "Process") {
        return !!data.machineUnit;
      }
      return true;
    },
    {
      message: "Machine unit is required",
      path: ["machineUnit"]
    }
  )
  .refine(
    (data) => {
      if (data.operationType !== "Outside Processing") {
        return Number.isFinite(data.setupTime);
      }
      return true;
    },
    {
      message: "Setup time is required",
      path: ["setupTime"]
    }
  )
  .refine(
    (data) => {
      if (data.operationType !== "Outside Processing") {
        return Number.isFinite(data.laborTime);
      }
      return true;
    },
    {
      message: "Labor time is required",
      path: ["laborTime"]
    }
  )
  .refine(
    (data) => {
      if (data.operationType === "Process") {
        return Number.isFinite(data.machineTime);
      }
      return true;
    },
    {
      message: "Machine time is required",
      path: ["machineTime"]
    }
  )
  .refine(
    (data) => {
      if (data.operationType === "Inspection") {
        return !!data.inspectionDocumentId;
      }
      return true;
    },
    {
      message: "Inspection Plan is required",
      path: ["inspectionDocumentId"]
    }
  );

export const itemCostValidator = z.object({
  itemId: z.string().min(1, { message: "Item ID is required" }),
  itemPostingGroupId: zfd.text(z.string().optional()),
  costingMethod: z.enum(itemCostingMethods, {
    error: "Costing method is required"
  }),
  // standardCost: zfd.numeric(z.number().min(0)),
  unitCost: zfd.numeric(z.number().min(0))
  // costIsAdjusted: zfd.checkbox(),
});

export const itemManufacturingValidator = z.object({
  itemId: z.string().min(1, { message: "Item ID is required" }),
  // manufacturingBlocked: zfd.checkbox(),
  requiresConfiguration: zfd.checkbox().optional(),
  lotSize: zfd.numeric(z.number().min(0)),
  scrapPercentage: zfd.numeric(z.number().min(0)),
  leadTime: zfd.numeric(z.number().min(0))
});

export const itemPostingGroupValidator = z.object({
  id: zfd.text(z.string().optional()),
  name: z.string().trim().min(1, { message: "Name is required" }).max(255),
  description: z.string().optional()
});

export const itemPlanningValidator = z
  .object({
    itemId: z.string().min(1, { message: "Item ID is required" }),
    locationId: z.string().min(1, { message: "Location is required" }),
    reorderingPolicy: z.enum(itemReorderingPolicies, {
      error: "Reordering policy is required"
    }),
    demandAccumulationPeriod: zfd.numeric(z.number().min(1).optional()),
    demandAccumulationSafetyStock: zfd.numeric(z.number().min(0).optional()),
    reorderPoint: zfd.numeric(z.number().min(0).optional()).optional(),
    reorderQuantity: zfd.numeric(z.number().min(0)).optional(),
    maximumInventoryQuantity: zfd.numeric(z.number().min(0)).optional(),
    minimumOrderQuantity: zfd.numeric(z.number().min(0)).optional(),
    maximumOrderQuantity: zfd.numeric(z.number().min(0)).optional(),
    orderMultiple: zfd.numeric(z.number().min(1)).optional(),
    // The planning horizon (time fence) in days from today: the planning grids
    // surface only the actions and suggested orders that fall inside it. Empty
    // = inherit the company default, else no fence; 0 = no fence for this item
    // even when the company has a default.
    planningHorizonDays: zfd.numeric(z.number().int().min(0).optional()),
    // the ownership ladder's leaf override (spec §P1.3): this item at this
    // location; empty = inherit item group → location → company default
    responsibleEmployee: zfd.text(z.string().optional())
    // critical: zfd.checkbox(),
  })
  .refine(
    (data) => {
      if (data.reorderingPolicy === "Maximum Quantity") {
        return (
          data.maximumInventoryQuantity &&
          data.reorderPoint &&
          data.maximumInventoryQuantity > data.reorderPoint
        );
      }
      return true;
    },
    {
      message: "Maximum inventory quantity must be greater than reorder point",
      path: ["maximumInventoryQuantity"]
    }
  )
  .refine(
    (data) => {
      if (data.reorderingPolicy === "Fixed Reorder Quantity") {
        return data.reorderQuantity && data.reorderQuantity > 0;
      }
      return true;
    },
    {
      message: "Reorder quantity must be greater than 0",
      path: ["reorderQuantity"]
    }
  );

export const supersessionModes = [
  "Consume First",
  "Prefer New",
  "Stock Only",
  "No Stock"
] as const;

export type SupersessionMode = (typeof supersessionModes)[number];

// Single source of truth for how each supersession mode is presented — the same
// color + description is reused everywhere the mode shows up (the item
// supersession picker, the item lifecycle badge, and the change-order cutover),
// so they never drift.
export const supersessionModeMeta: Record<
  SupersessionMode,
  { color: "green" | "blue" | "orange" | "red"; description: string }
> = {
  "Consume First": {
    color: "green",
    description: "Use remaining stock before switching to the successor"
  },
  "Prefer New": {
    color: "blue",
    description:
      "Plan and build with the successor; picking falls back to the old part only while the successor is out of stock"
  },
  "Stock Only": {
    color: "orange",
    description: "Hold a minimum reserve for service; no production use"
  },
  "No Stock": {
    color: "red",
    description: "Fully obsolete — do not plan or stock"
  }
};

export const itemSupersessionValidator = z
  .object({
    itemId: z.string().min(1, { message: "Item ID is required" }),
    // Absent mode = no supersession; saving without a mode clears it.
    supersessionMode: zfd.text(z.enum(supersessionModes).optional()),
    successorItemId: zfd.text(z.string().optional()),
    discontinuationDate: zfd.text(z.string().optional()),
    successorEffectivityDate: zfd.text(z.string().optional()),
    // How many of the successor replace one old part (1 old = N new).
    conversionFactor: zfd.numeric(z.number().positive().optional()),
    // The minimum service-stock floor is per-location (stored on itemPlanning).
    locationId: zfd.text(z.string().optional()),
    minimumReserveQuantity: zfd.numeric(z.number().min(0).optional())
  })
  .refine(
    (data) =>
      data.supersessionMode && data.supersessionMode !== "Consume First"
        ? !!data.discontinuationDate
        : true,
    {
      message: "Discontinuation date is required",
      path: ["discontinuationDate"]
    }
  )
  .refine(
    (data) =>
      data.supersessionMode && data.supersessionMode !== "No Stock"
        ? !!data.successorItemId
        : true,
    {
      message: "Successor part is required",
      path: ["successorItemId"]
    }
  )
  .refine((data) => data.successorItemId !== data.itemId, {
    message: "A part cannot be its own successor",
    path: ["successorItemId"]
  })
  .refine(
    (data) =>
      data.successorEffectivityDate && data.discontinuationDate
        ? data.successorEffectivityDate >= data.discontinuationDate
        : true,
    {
      message:
        "Successor effectivity date must be on or after the discontinuation date",
      path: ["successorEffectivityDate"]
    }
  );

export const predecessorSupersessionValidator = z
  .object({
    predecessorItemId: z.string().min(1, { message: "Part is required" }),
    supersessionMode: z.enum(supersessionModes),
    discontinuationDate: zfd.text(z.string().optional()),
    successorEffectivityDate: zfd.text(z.string().optional()),
    conversionFactor: zfd.numeric(z.number().positive().optional())
  })
  .refine((data) => data.supersessionMode !== "No Stock", {
    message: "No Stock has no successor; set it on the part itself",
    path: ["supersessionMode"]
  })
  .refine(
    (data) =>
      data.supersessionMode !== "Consume First"
        ? !!data.discontinuationDate
        : true,
    {
      message: "Discontinuation date is required",
      path: ["discontinuationDate"]
    }
  )
  .refine(
    (data) =>
      data.successorEffectivityDate && data.discontinuationDate
        ? data.successorEffectivityDate >= data.discontinuationDate
        : true,
    {
      message:
        "Successor effectivity date must be on or after the discontinuation date",
      path: ["successorEffectivityDate"]
    }
  );
export const itemPurchasingValidator = z.object({
  itemId: z.string().min(1, { message: "Item ID is required" }),
  preferredSupplierId: zfd.text(z.string().optional()),
  conversionFactor: zfd.numeric(z.number().min(0)),
  leadTime: zfd.numeric(z.number().min(0)),
  purchasingUnitOfMeasureCode: zfd.text(z.string().optional())
  // purchasingBlocked: zfd.checkbox(),
});

export const itemUnitSalePriceValidator = z.object({
  itemId: z.string().min(1, { message: "Item ID is required" }),
  unitSalePrice: zfd.numeric(z.number().min(0))
  // currencyCode: z.string().min(1, { message: "Currency is required" }),
  // salesUnitOfMeasureCode: z
  //   .string()
  //   .min(1, { message: "Unit of Measure is required" }),
  // salesBlocked: zfd.checkbox(),
  // priceIncludesTax: zfd.checkbox(),
  // allowInvoiceDiscount: zfd.checkbox(),
});

export const materialDimensionValidator = z.object({
  id: zfd.text(z.string().optional()),
  name: z.string().trim().min(1, { message: "Name is required" }).max(255),
  materialFormId: z.string().min(1, { message: "Shape is required" })
});

export const materialFinishValidator = z.object({
  id: zfd.text(z.string().optional()),
  materialSubstanceId: z.string().min(1, { message: "Substance is required" }),
  name: z.string().trim().min(1, { message: "Name is required" }).max(255)
});

export const materialFormValidator = z.object({
  id: zfd.text(z.string().optional()),
  name: z.string().trim().min(1, { message: "Name is required" }).max(255),
  code: z.string().trim().min(1, { message: "Code is required" }).max(10)
});

export const materialGradeValidator = z.object({
  id: zfd.text(z.string().optional()),
  materialSubstanceId: z.string().min(1, { message: "Substance is required" }),
  name: z.string().trim().min(1, { message: "Name is required" }).max(255)
});

export const materialSubstanceValidator = z.object({
  id: zfd.text(z.string().optional()),
  name: z.string().trim().min(1, { message: "Name is required" }).max(255),
  code: z.string().trim().min(1, { message: "Code is required" }).max(10)
});

export const materialTypeValidator = z.object({
  id: zfd.text(z.string().optional()),
  materialSubstanceId: z.string().min(1, { message: "Substance is required" }),
  materialFormId: z.string().min(1, { message: "Shape is required" }),
  name: z.string().trim().min(1, { message: "Name is required" }).max(255),
  code: z.string().trim().min(1, { message: "Code is required" }).max(10)
});

/** A part's fields before the storage and shelf-life rules (`partValidator`). */
export const partFields = itemValidator.merge(
  z.object({
    id: z.string().min(1, { message: "Part ID is required" }).max(255),
    revision: z.string().min(1, { message: "Revision is required" }),
    modelUploadId: zfd.text(z.string().optional()),
    lotSize: zfd.numeric(z.number().min(0).optional())
  })
);

export const partValidator = applyStorageAndShelfLifeRefines(partFields);

// Tracked-entity pick order surfaced on the item's per-location Inventory
// card. 'Default' = the picker's smart order (expiring soonest, then oldest).
// Mirrors "pickMethodSortMethod" Postgres enum.
export const pickMethodSortMethods = [
  "Default",
  "FEFO",
  "FIFO",
  "LIFO"
] as const;

export const pickMethodValidator = z.object({
  itemId: z.string().min(1, { message: "Item ID is required" }),
  locationId: z.string().min(1, { message: "Location is required" }),
  defaultStorageUnitId: zfd.text(z.string().optional()),
  sortMethod: z.enum(pickMethodSortMethods).optional()
});

// pickMethod form + shelf-life policy in one submit. Shelf-life itself is
// item-level (stored on itemShelfLife keyed by itemId), not per-location,
// but we surface the controls on the per-location "Inventory" card so
// users editing the item's stocking defaults can also manage its shelf-
// life policy without navigating elsewhere. The server-side action is
// responsible for routing each subset of fields to its own upsert helper.
//
// Note: this validator does NOT reference itemTrackingType (pickMethod
// doesn't carry it). The UI gates visibility of the shelf-life fields on
// tracking type via a prop, and the itemValidator chain already enforces
// the Serial-or-Batch prerequisite at item creation. If a caller somehow
// posts shelfLifeMode on an item without Serial/Batch tracking, the
// itemShelfLife table's CHECK constraints still stand - but it's easier
// UX to not render the fields at all in that case.
export const pickMethodWithShelfLifeValidator = pickMethodValidator
  .merge(
    z.object({
      shelfLifeMode: z.preprocess(
        (v) => (v === "" ? "NotManaged" : v),
        z.enum(shelfLifeModes).optional()
      ),
      shelfLifeDays: zfd.numeric(z.number().positive().optional()),
      shelfLifeTriggerProcessId: zfd.text(z.string().optional()),
      shelfLifeTriggerTiming: z.enum(shelfLifeTriggerTimings).optional(),
      shelfLifeCalculateFromBom: zfd.checkbox()
    })
  )
  .refine(
    (data) =>
      data.shelfLifeDays === undefined ||
      data.shelfLifeMode === "Fixed Duration",
    {
      message:
        "Shelf-life days can only be set when shelf-life management is Fixed Duration",
      path: ["shelfLifeDays"]
    }
  )
  .refine(
    (data) =>
      data.shelfLifeMode !== "Fixed Duration" ||
      data.shelfLifeDays !== undefined,
    {
      message:
        "Shelf-life days is required when shelf-life management is Fixed Duration",
      path: ["shelfLifeDays"]
    }
  )
  .refine(
    (data) =>
      !data.shelfLifeTriggerProcessId ||
      data.shelfLifeMode === "Fixed Duration",
    {
      message:
        "Trigger process can only be set when shelf-life management is Fixed Duration",
      path: ["shelfLifeTriggerProcessId"]
    }
  )
  .refine(
    (data) =>
      !data.shelfLifeCalculateFromBom ||
      data.shelfLifeMode === "Fixed Duration",
    {
      message: "Calculate from BOM only applies to Fixed Duration shelf life",
      path: ["shelfLifeCalculateFromBom"]
    }
  );

export const revisionValidator = z
  .object({
    id: zfd.text(z.string().optional()),
    type: z.enum(["Part", "Material", "Tool", "Consumable", "Service"]),
    copyFromId: zfd.text(z.string().optional()),
    revision: z.string().min(1, { message: "Revision is required" })
  })
  .refine(
    (data) => {
      return data.id || data.copyFromId;
    },
    { message: "Revision or copy from is required" }
  );

export const SERVICE_NAME_MAX_LENGTH = 100;

/**
 * The built-in "Each" unit of measure. Every company has it and the database
 * refuses to rename, deactivate or delete it; a service is always counted in it.
 */
export const EACH_UNIT_OF_MEASURE_CODE = "EA";

export const serviceValidator = applyStorageAndShelfLifeRefines(
  itemValidator.merge(
    z.object({
      // A service is identified by its name: it is the readable id, so
      // neither an id nor a revision is asked for. `id` is only the key of the
      // service to update.
      id: zfd.text(z.string().max(255).optional()),
      name: z
        .string()
        .trim()
        .min(1, { message: "Name is required" })
        .max(SERVICE_NAME_MAX_LENGTH),
      revision: zfd.text(z.string().optional()),
      // Ignored: a service is always counted in Each (EA).
      unitOfMeasureCode: zfd.text(z.string().optional()),
      replenishmentSystem: z.enum(serviceReplenishmentSystems, {
        error: "Replenishment system is required"
      }),
      // Services can never be shipped, received, or stocked
      itemTrackingType: z.literal("Non-Inventory")
    })
  )
);

export const supplierPartValidator = z.object({
  id: zfd.text(z.string().optional()),
  itemId: z.string().min(1, { message: "Item ID is required" }),
  supplierId: z.string().min(1, { message: "Supplier ID is required" }),
  supplierPartId: z.string().optional(),
  supplierUnitOfMeasureCode: zfd.text(z.string().optional()),
  minimumOrderQuantity: zfd.numeric(z.number().min(0)),
  orderMultiple: zfd.numeric(z.number().min(1)).optional(),
  conversionFactor: zfd.numeric(z.number().min(0)),
  // Per purchase unit, in currencyCode — the price as the supplier quoted it.
  currencyCode: zfd.text(z.string().optional()),
  supplierUnitPrice: zfd.numeric(z.number().min(0).optional())
});

/** A supplier part's price breaks, per purchase unit in its currency. */
export const supplierPartPriceBreaksValidator = z.array(
  z.object({
    quantity: z.number(),
    supplierUnitPrice: z.number(),
    leadTime: z.number().optional()
  })
);

/** The supplier part drawer's post: the part, and its price breaks as JSON. */
export const supplierPartFormValidator = supplierPartValidator.extend({
  priceBreaks: zfd.json(supplierPartPriceBreaksValidator.optional())
});

/** A tool's fields before the storage and shelf-life rules (`toolValidator`). */
export const toolFields = itemValidator.merge(
  z.object({
    id: z.string().min(1, { message: "Tool ID is required" }).max(255),
    revision: z.string().min(1, { message: "Revision is required" }),
    modelUploadId: zfd.text(z.string().optional()),
    unitOfMeasureCode: z
      .string()
      .min(1, { message: "Unit of Measure is required" }),
    lotSize: zfd.numeric(z.number().min(0).optional())
  })
);

export const toolValidator = applyStorageAndShelfLifeRefines(toolFields);

export const unitOfMeasureValidator = z.object({
  id: zfd.text(z.string().optional()),
  code: z.string().trim().min(1, { message: "Code is required" }).max(10),
  name: z.string().trim().min(1, { message: "Name is required" }).max(50)
});

export const itemRevisionStatus = [
  "Design",
  "Prototype",
  "Production",
  "Obsolete"
] as const;

// companySettings.plmReleaseControl
export const plmReleaseControl = ["off", "warn", "enforce"] as const;

// Error shape returned by the change notice service functions: either a real
// Supabase PostgrestError or a hand-built message (sequence/lookup failures that
// don't originate from a query). One alias so callers get a consistent contract.
export type ChangeNoticeError = PostgrestError | { message: string };

// =============================================================================
// Change Notices — validators, enums, and the stage state machine.
//
// A sub-area of the Items module, modeled on Quality. The header evolves the
// existing `changeOrder` table. v2: a CO's per-affected-item edits live on a
// REAL CO-owned Draft make method (no staged mirror tables); the change type
// drives the release action. Validators here cover the header, affected items +
// change type, cutover, manual supersession, and freeform actions.
// =============================================================================

// changeOrder.type — the legacy category enum on the header. Retained (the
// column still exists); the primary "Category" is `changeOrderTypeId` (a row in
// the changeNoticeType lookup, reseeded to Design improvement / Obsolescence /
// Cost reduction).
export const changeNoticeType = [
  "Engineering",
  "Manufacturing",
  "Documentation"
] as const;

// V1 stage flow (forward, one step at a time). Notifies on Start /
// Implementation / Done; silent on Draft / Engineering Complete. "Cancelled" is
// the off-ramp: a CO can be closed from any open stage and reopened to Draft.
export const changeNoticeStatus = [
  "Draft",
  "Start",
  "Engineering Complete",
  "Implementation",
  "Done",
  "Cancelled"
] as const;

// The forward progress stages only (excludes the "Cancelled" off-ramp). Drives
// the read-only status-flow progress bar so a cancelled CO doesn't render as a
// sixth step.
export const changeNoticeStageFlow: (typeof changeNoticeStatus)[number][] = [
  "Draft",
  "Start",
  "Engineering Complete",
  "Implementation",
  "Done"
];

export const changeNoticeTaskStatus = [
  "Pending",
  "In Progress",
  "Completed",
  "Skipped"
] as const;

// v2 per-affected-item change type. Drives the release action + which editing
// surface is shown. Two axes — is there a predecessor, and same part number?
//   Version          = new method version on the SAME item (BoM/BoP, no supersession)
//   Revision         = new revision item, same #, new rev (BoM/BoP + attrs, auto
//                      old-rev→new-rev supersession)
//   Replacement Part = new P/N derived from + auto-superseding the affected part
//                      (BoM/BoP + attrs) — the 1:1 replacement, renamed from the old
//                      "New Part"
//   New Part         = net-new part, NO predecessor, NO supersession — introduced by
//                      the CO (Make or Buy). Used to introduce a part under change
//                      control, incl. the consolidated "1" in an N→1 assembly BOM
//                      change.
// BoM/BoP is editable on ANY change type for a manufactured (non-Buy) draft; only
// Version's extra editing scope differs (no attributes/docs/cutover surface).
export const changeNoticeChangeTypes = [
  "Version",
  "Revision",
  "Replacement Part",
  "New Part"
] as const;
export type ChangeNoticeChangeType = (typeof changeNoticeChangeTypes)[number];

// changeOrder.priority reuses quality's nonConformancePriority DB enum.
export const changeNoticePriority = nonConformancePriority;

// -----------------------------------------------------------------------------
// Stage state machine (G8 — one place). Forward, single step, plus the Cancel /
// Reopen off-ramp. This map only encodes the allowed shape of a transition.
// IMPORTANT: the forward stage is always index 0 — the header's "Advance" action
// reads `transitions[status][0]`, so "Cancelled" must never be first.
// -----------------------------------------------------------------------------
export const changeNoticeStatusTransitions: Record<
  (typeof changeNoticeStatus)[number],
  (typeof changeNoticeStatus)[number][]
> = {
  Draft: ["Start", "Cancelled"],
  Start: ["Engineering Complete", "Cancelled"],
  "Engineering Complete": ["Implementation", "Cancelled"],
  // Last entry is the reopen edge — "Done" stays first so the header still advances/releases.
  Implementation: ["Done", "Cancelled", "Engineering Complete"],
  Done: [],
  // Reopen a closed CO back to Draft (fully editable). Done stays terminal.
  Cancelled: ["Draft"]
};

export function isAllowedChangeNoticeTransition(
  from: string | null | undefined,
  to: string | null | undefined
): boolean {
  if (!from || !to || from === to) return false;
  const allowed =
    changeNoticeStatusTransitions[from as (typeof changeNoticeStatus)[number]];
  if (!allowed) return false;
  return (allowed as readonly string[]).includes(to);
}

// The stages that notify the CO assignee + action-task assignees on entry.
export const changeNoticeNotifyStages: (typeof changeNoticeStatus)[number][] = [
  "Start",
  "Implementation",
  "Done"
];

// "Open" = every stage before the record is closed at Done. Used by the item
// open-CO alert and the single-open-CO guard.
export const changeNoticeOpenStatuses: (typeof changeNoticeStatus)[number][] = [
  "Draft",
  "Start",
  "Engineering Complete",
  "Implementation"
];

export function isChangeNoticeOpen(status: string | null | undefined): boolean {
  return changeNoticeOpenStatuses.some((s) => s === status);
}

// Locked once closed — Done (released, part of the audit trail) or Cancelled
// (abandoned). Reopen a Cancelled CO to Draft to edit it again.
export function isChangeNoticeLocked(
  status: string | null | undefined
): boolean {
  return status === "Done" || status === "Cancelled";
}

// Engineering content — affected items, BOM/BOP drafts, cutover, reason/description.
// Frozen from Implementation onward: what is being implemented must not shift underneath.
export function canEditChangeNoticeEngineering(
  status: string | null | undefined
): boolean {
  return !isChangeNoticeLocked(status) && status !== "Implementation";
}

// Why a change notice is locked, for whichever surface is asking: server guards
// flash it, the affected-item UI shows it in the read-only tooltip. One wording,
// so the two never drift.
export function changeNoticeLockedMessage(status: string | null | undefined) {
  return status === "Implementation"
    ? "This change notice is being implemented, so its changes are locked. Reopen it to make changes."
    : "This change notice is closed, so its changes are read-only.";
}

// Engineering content is also frozen while an approval request is pending: the
// approver signs off on exactly what they reviewed.
export const changeNoticeAwaitingApprovalMessage =
  "This change notice is waiting for approval. Engineering changes are locked until it is approved or rejected.";

// Workflow content — action tasks, assignee, dates, priority. Editable until closed.
export function canEditChangeNoticeWorkflow(
  status: string | null | undefined
): boolean {
  return !isChangeNoticeLocked(status);
}

// -----------------------------------------------------------------------------
// Header
// -----------------------------------------------------------------------------
export const changeNoticeValidator = z.object({
  id: zfd.text(z.string().optional()),
  changeOrderId: zfd.text(z.string().optional()),
  name: z.string().trim().min(1, { message: "Name is required" }),
  reasonForChange: zfd.text(z.string().optional()),
  description: zfd.text(z.string().optional()),
  type: z.enum(changeNoticeType).optional(),
  priority: z.enum(nonConformancePriority).optional(),
  changeOrderTypeId: zfd.text(z.string().optional()),
  nonConformanceId: zfd.text(z.string().optional()),
  openDate: z.string().min(1, { message: "Open date is required" }),
  dueDate: zfd.text(z.string().optional()),
  assignee: zfd.text(z.string().optional()),
  // Optional affected Parts/Tools to attach at create time — each is added as a
  // Version affected item (Buy items coerced to Revision service-side). More can
  // be added later on the CO detail. Only consumed by the create action.
  affectedItemIds: zfd.repeatableOfType(z.string()).optional()
});

// Status transition (used by the $id.status route). fromStatus drives a
// compare-and-swap so a stale/concurrent transition is rejected.
export const changeNoticeStatusValidator = z.object({
  id: z.string().min(1, { message: "Id is required" }),
  fromStatus: z.enum(changeNoticeStatus),
  status: z.enum(changeNoticeStatus),
  assignee: zfd.text(z.string().optional())
});

// =============================================================================
// Top-to-bottom change content (v2) — affected items + per-item change type +
// cutover + manual supersession. The user selects affected parts first; each
// part's edits live on a REAL CO-owned Draft make method edited via the normal
// BillOfMaterial/BillOfProcess/PartProperties editors (no staged mirror tables).
// All validators are flat objects (no discriminated unions / heavy generics) to
// stay clear of TS2589 when threaded through @carbon/form's `validator()`.
// =============================================================================

// Affected item — the part the user selects to change. Adding one creates a
// CO-owned Draft make method per the change type (service side).
export const changeNoticeAffectedItemValidator = z.object({
  id: zfd.text(z.string().optional()),
  changeOrderId: z.string().min(1, { message: "Change notice is required" }),
  itemId: z.string().min(1, { message: "Item is required" }),
  changeType: z.enum(changeNoticeChangeTypes).default("Version"),
  // Optional revision label for a Revision change (e.g. "A"). Blank → the next
  // revision is auto-computed server-side (createChangeNoticeDraftMethod).
  revision: zfd.text(z.string().optional())
});

// Add-affected-item path for a net-new "New Part" (no existing itemId): the CO
// mints a brand-new inactive Part and adds it as a New Part affected item. Always
// a Part (no Part/Tool choice in the modal).
export const changeNoticeNewPartValidator = z.object({
  changeOrderId: z.string().min(1, { message: "Change notice is required" }),
  // The route branches on this raw FormData value; also seeds the change-type
  // Select so it reads "New Part" after the form remounts (see AffectedItemForm).
  changeType: z.enum(changeNoticeChangeTypes).default("New Part"),
  readableId: z.string().min(1, { message: "Part number is required" }),
  name: z.string().trim().min(1, { message: "Name is required" }),
  replenishmentSystem: z.enum(["Buy", "Make", "Buy and Make"]).default("Make"),
  itemTrackingType: z.enum(itemTrackingTypes).default("Inventory")
});

// Switch the change type on an existing affected item (rebuilds its CO-owned
// Draft make method for the new type — see updateChangeNoticeAffectedItemChangeType).
export const changeNoticeAffectedItemChangeTypeValidator = z.object({
  id: z.string().min(1, { message: "Id is required" }),
  changeType: z.enum(changeNoticeChangeTypes)
});

// Per-item revision cutover config (Q3): existence of the oldRev→newRev
// supersession is automatic at release; the user only tunes mode + dates here.
export const changeNoticeAffectedItemCutoverValidator = z.object({
  id: z.string().min(1, { message: "Id is required" }),
  supersessionMode: z.enum(supersessionModes),
  discontinuationDate: zfd.text(z.string().optional()),
  successorEffectivityDate: zfd.text(z.string().optional())
});

// Action task status transition (Start / Complete / Reopen). Actions are
// instantiated from templates (see changeOrderRequiredAction); there's no
// freeform-create validator.
export const changeNoticeActionStatusValidator = z.object({
  id: z.string().min(1, { message: "Id is required" }),
  status: z.enum(changeNoticeTaskStatus)
});

// Configurable default actions (changeOrderRequiredAction templates) — the
// per-company set a new change notice is seeded from. Configured like Issue Types.
export const changeNoticeRequiredActionValidator = z.object({
  id: zfd.text(z.string().optional()),
  name: z.string().trim().min(1, { message: "Name is required" }),
  active: zfd.checkbox()
});

// -----------------------------------------------------------------------------
// Diff types (Q5 git-style) — one shape reused for the pre-release "tips"
// (staged-vs-live) and the post-release revision redline (oldRev-vs-newRev).
// -----------------------------------------------------------------------------
export type MethodDiffStatus = "added" | "removed" | "modified" | "unchanged";

export type MethodDiffEntry<T> = {
  status: MethodDiffStatus;
  before: T | null;
  after: T | null;
  // Field-level changes for a "modified" entry: { field: { before, after } }.
  changedFields?: Record<string, { before: unknown; after: unknown }>;
};

// One operation's child-level diff (steps / parameters / tools), each bucket
// classified added/removed/modified/unchanged. Defined here (not in
// items.service.ts) so ChangeNoticeItemDiff can carry the operation tree
// without a circular import; items.service.ts re-exports these for its own
// callers.
export type OperationChildrenDiff = {
  steps: MethodDiffEntry<Record<string, unknown>>[];
  parameters: MethodDiffEntry<Record<string, unknown>>[];
  tools: MethodDiffEntry<Record<string, unknown>>[];
};

// An operation diff entry, optionally carrying its child-level diff. A superset
// of MethodDiffEntry, so consumers typed against the base entry keep working.
export type OperationDiffEntry = MethodDiffEntry<Record<string, unknown>> & {
  children?: OperationChildrenDiff;
};

export type ChangeNoticeItemDiff = {
  affectedItemId: string;
  itemId: string;
  materials: MethodDiffEntry<Record<string, unknown>>[];
  // Operations carry the optional child (steps/parameters/tools) diff so the
  // read-only diff viewer can render the BOP as a tree.
  operations: OperationDiffEntry[];
  attributes: MethodDiffEntry<Record<string, unknown>>[];
  // Supplier parts on a draft item. A Revision draft starts with a copy of its
  // source revision's, so its entries are a real diff against the source; a
  // Replacement Part / New Part draft starts with none, so its are all `added`.
  supplierParts: MethodDiffEntry<Record<string, unknown>>[];
};

// -----------------------------------------------------------------------------
// Change Notice Types (the "Category" lookup — configured like Issue Types)
// -----------------------------------------------------------------------------
export const changeNoticeTypeValidator = z.object({
  id: zfd.text(z.string().optional()),
  name: z.string().trim().min(1, { message: "Name is required" })
});