@tailor-platform/erp-kit 0.7.0 → 0.9.0

package/src/modules/manufacturing/command/reviewManufacturingCostSummary.ts

@@ -133,5 +133,5 @@ export async function run<CF extends Record<string, unknown>>(
     .returningAll()
     .executeTakeFirst();
 
-  return ok({ costSummary: updatedSummary! });
+  return ok({ manufacturingCostSummary: updatedSummary! });
 }

package/src/modules/manufacturing/command/updateBillOfMaterial.ts

@@ -16,7 +16,7 @@ export interface UpdateBillOfMaterialLineInput {
   isSubassembly?: boolean | null;
 }
 
-export interface UpdateBillOfMaterialInput {
+export type UpdateBillOfMaterialInput = {
   id: string;
   bomType?: string | null;
   effectivityStartDate?: Date | null;
@@ -24,8 +24,7 @@ export interface UpdateBillOfMaterialInput {
   defaultSelection?: boolean | null;
   revisionNumber?: string | null;
   lines?: UpdateBillOfMaterialLineInput[];
-}
-
+};
 /**
  * Function: updateBillOfMaterial
  *
@@ -35,7 +34,7 @@ export interface UpdateBillOfMaterialInput {
  */
 export async function run<CF extends Record<string, unknown>>(
   db: Transaction,
-  input: UpdateBillOfMaterialInput & CF,
+  input: UpdateBillOfMaterialInput & Omit<Partial<CF>, "status">,
   _ctx: CommandContext,
 ) {
   const {

package/src/modules/manufacturing/command/updateProductionOrder.ts

@@ -8,7 +8,7 @@ import {
 } from "../lib/errors.generated";
 import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
 
-export interface UpdateProductionOrderInput {
+export type UpdateProductionOrderInput = {
   id: string;
   plannedQuantity?: number | null;
   plannedStartDate?: Date | null;
@@ -18,8 +18,7 @@ export interface UpdateProductionOrderInput {
   orderedItemId?: string | null;
   companyId?: string | null;
   siteId?: string | null;
-}
-
+};
 /**
  * Function: updateProductionOrder
  *
@@ -28,7 +27,7 @@ export interface UpdateProductionOrderInput {
  */
 export async function run<CF extends Record<string, unknown>>(
   db: Transaction,
-  input: UpdateProductionOrderInput & CF,
+  input: UpdateProductionOrderInput & Omit<Partial<CF>, "status">,
   _ctx: CommandContext,
 ) {
   const {

package/src/modules/manufacturing/command/updateRouting.ts

@@ -18,12 +18,11 @@ export interface UpdateRoutingOperationInput {
   operatorInstructions?: string | null;
 }
 
-export interface UpdateRoutingInput {
+export type UpdateRoutingInput = {
   id: string;
   revisionNumber?: string | null;
   operations: UpdateRoutingOperationInput[];
-}
-
+};
 /**
  * Function: updateRouting
  *
@@ -32,7 +31,7 @@ export interface UpdateRoutingInput {
  */
 export async function run<CF extends Record<string, unknown>>(
   db: Transaction,
-  input: UpdateRoutingInput & CF,
+  input: UpdateRoutingInput & Omit<Partial<CF>, "status">,
   _ctx: CommandContext,
 ) {
   const { id, revisionNumber, operations, ...customFields } = input;
@@ -120,5 +119,5 @@ export async function run<CF extends Record<string, unknown>>(
     createdOperations.push(operation!);
   }
 
-  return ok({ routing: updatedRouting!, operations: createdOperations });
+  return ok({ routing: updatedRouting!, routingOperations: createdOperations });
 }

package/src/modules/manufacturing/command/updateWorkCenter.test.ts

@@ -7,7 +7,6 @@ import {
   InvalidRateError,
   InvalidOverheadMethodError,
   OverheadCurrencyRequiredError,
-  ImmutableScopeFieldError,
 } from "../lib/errors.generated";
 import { baseActiveWorkCenter } from "../testing/fixtures";
 import { run } from "./updateWorkCenter";
@@ -56,18 +55,28 @@ describe("updateWorkCenter", () => {
     }
   });
 
-  it("returns error when immutable scope fields are changed", async () => {
-    const { db } = createMockDb<Transaction>();
+  it("looks up a work center by companyId, siteId, and code", async () => {
+    const { db, spies } = createMockDb<Transaction>();
+    spies.select.mockReturnValueOnce(baseActiveWorkCenter);
+    spies.update.mockReturnValue({
+      ...baseActiveWorkCenter,
+      capacityAssumptions: 220,
+    });
 
     const result = await run(
       db,
-      { ...validInput, companyId: "other-company" } as Parameters<typeof run>[1],
+      {
+        companyId: baseActiveWorkCenter.companyId,
+        siteId: baseActiveWorkCenter.siteId,
+        code: baseActiveWorkCenter.code,
+        capacityAssumptions: 220,
+      },
       ctx,
     );
 
-    expect(result.ok).toBe(false);
-    if (!result.ok) {
-      expect(result.error).toBeInstanceOf(ImmutableScopeFieldError);
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.value.workCenter.capacityAssumptions).toBe(220);
     }
   });
 

package/src/modules/manufacturing/command/updateWorkCenter.ts

@@ -5,7 +5,6 @@ import {
   InvalidRateError,
   InvalidOverheadMethodError,
   OverheadCurrencyRequiredError,
-  ImmutableScopeFieldError,
 } from "../lib/errors.generated";
 import { ok, err, type CommandContext } from "@tailor-platform/erp-kit/module";
 
@@ -15,18 +14,17 @@ const VALID_OVERHEAD_METHODS = [
   "FIXED_AMOUNT_PER_GOOD_UNIT",
 ] as const;
 
-const IMMUTABLE_FIELDS = ["companyId", "siteId", "code"] as const;
-
-export interface UpdateWorkCenterInput {
-  id: string;
+export type UpdateWorkCenterInput = (
+  | { id: string }
+  | { companyId: string; siteId: string; code: string }
+) & {
   capacityAssumptions?: number | null;
   laborRate?: number | null;
   machineRate?: number | null;
   calendarReference?: string | null;
   overheadAbsorptionMethod?: string | null;
   overheadAbsorptionCurrency?: string | null;
-}
-
+};
 /**
  * Function: updateWorkCenter
  *
@@ -36,11 +34,10 @@ export interface UpdateWorkCenterInput {
  */
 export async function run<CF extends Record<string, unknown>>(
   db: Transaction,
-  input: UpdateWorkCenterInput & CF,
+  input: UpdateWorkCenterInput & Omit<Partial<CF>, "status">,
   _ctx: CommandContext,
 ) {
   const {
-    id,
     capacityAssumptions,
     laborRate,
     machineRate,
@@ -49,42 +46,48 @@ export async function run<CF extends Record<string, unknown>>(
     overheadAbsorptionCurrency,
     ...customFields
   } = input;
-
-  // 1. Reject immutable scope fields
-  for (const field of IMMUTABLE_FIELDS) {
-    if (field in customFields) {
-      return err(new ImmutableScopeFieldError(field));
-    }
+  delete (customFields as Record<string, unknown>).id;
+  delete (customFields as Record<string, unknown>).companyId;
+  delete (customFields as Record<string, unknown>).siteId;
+  delete (customFields as Record<string, unknown>).code;
+
+  // 1. Check work center exists
+  let workCenterQuery = db.selectFrom("WorkCenter").selectAll();
+  if ("id" in input) {
+    workCenterQuery = workCenterQuery.where("id", "=", (input as { id: string }).id);
+  } else {
+    const lookup = input as { companyId: string; siteId: string; code: string };
+    workCenterQuery = workCenterQuery
+      .where("companyId", "=", lookup.companyId)
+      .where("siteId", "=", lookup.siteId)
+      .where("code", "=", lookup.code);
   }
-
-  // 2. Check work center exists
-  const workCenter = await db
-    .selectFrom("WorkCenter")
-    .selectAll()
-    .where("id", "=", id)
-    .forUpdate()
-    .executeTakeFirst();
+  const workCenter = await workCenterQuery.forUpdate().executeTakeFirst();
 
   if (!workCenter) {
-    return err(new WorkCenterNotFoundError(id));
+    const key =
+      "id" in input
+        ? (input as { id: string }).id
+        : `${(input as { companyId: string; siteId: string; code: string }).companyId}:${(input as { companyId: string; siteId: string; code: string }).siteId}:${(input as { companyId: string; siteId: string; code: string }).code}`;
+    return err(new WorkCenterNotFoundError(key));
   }
 
-  // 3. Only DRAFT or ACTIVE allowed
+  // 2. Only DRAFT or ACTIVE allowed
   if (workCenter.status !== "DRAFT" && workCenter.status !== "ACTIVE") {
-    return err(new WorkCenterNotFoundError(id));
+    return err(new WorkCenterNotFoundError(workCenter.id));
   }
 
-  // 4. Validate capacity if provided
+  // 3. Validate capacity if provided
   if (capacityAssumptions != null && capacityAssumptions <= 0) {
-    return err(new InvalidCapacityError(id));
+    return err(new InvalidCapacityError(workCenter.id));
   }
 
-  // 5. Validate rates if provided
+  // 4. Validate rates if provided
   if (laborRate != null && laborRate < 0) {
-    return err(new InvalidRateError(id));
+    return err(new InvalidRateError(workCenter.id));
   }
   if (machineRate != null && machineRate < 0) {
-    return err(new InvalidRateError(id));
+    return err(new InvalidRateError(workCenter.id));
   }
 
   // Resolve the effective overhead method after update
@@ -97,20 +100,20 @@ export async function run<CF extends Record<string, unknown>>(
       ? overheadAbsorptionCurrency
       : workCenter.overheadAbsorptionCurrency;
 
-  // 6. Validate overhead method
+  // 5. Validate overhead method
   if (
     effectiveMethod != null &&
     !VALID_OVERHEAD_METHODS.includes(effectiveMethod as (typeof VALID_OVERHEAD_METHODS)[number])
   ) {
-    return err(new InvalidOverheadMethodError(id));
+    return err(new InvalidOverheadMethodError(workCenter.id));
   }
 
-  // 7. Overhead currency required for FIXED_AMOUNT_PER_GOOD_UNIT
+  // 6. Overhead currency required for FIXED_AMOUNT_PER_GOOD_UNIT
   if (effectiveMethod === "FIXED_AMOUNT_PER_GOOD_UNIT" && !effectiveCurrency) {
-    return err(new OverheadCurrencyRequiredError(id));
+    return err(new OverheadCurrencyRequiredError(workCenter.id));
   }
 
-  // 8. Build update set
+  // 7. Build update set
   const updateSet: Record<string, unknown> = {
     ...(customFields as Record<string, unknown>),
     updatedAt: new Date(),
@@ -125,11 +128,11 @@ export async function run<CF extends Record<string, unknown>>(
   if (overheadAbsorptionCurrency !== undefined)
     updateSet.overheadAbsorptionCurrency = overheadAbsorptionCurrency;
 
-  // 9. Persist changes
+  // 8. Persist changes
   const updated = await db
     .updateTable("WorkCenter")
     .set(updateSet)
-    .where("id", "=", id)
+    .where("id", "=", workCenter.id)
     .returningAll()
     .executeTakeFirstOrThrow();
 

package/src/modules/manufacturing/docs/commands/ActivateWorkCenter.md

@@ -47,3 +47,5 @@ flowchart TD
 - returns error when the status does not allow activation
 - returns error when required calendar context is missing
 - returns error when capacity is not positive
+- returns error when a configured rate is negative
+- returns error when fixed overhead is missing its currency

package/src/modules/manufacturing/docs/commands/CompleteWorkOrder.md

@@ -64,3 +64,5 @@ flowchart TD
 - returns error when a lot-tracked receipt omits finishedGoodLotReference
 - returns error when a serial-tracked receipt omits serialReferences
 - rolls up completion to the parent order
+- allows zero-quantity completion only under an explicit bypass policy
+- emits a backflush handoff when completion requires backflush consumption

package/src/modules/manufacturing/docs/commands/CreateBillOfMaterial.md

@@ -52,3 +52,4 @@ flowchart TD
 - returns error when a component item is inactive
 - returns error when a component item exists but is inactive
 - returns error when the version identity already exists in scope
+- returns error when the parent item is inactive

package/src/modules/manufacturing/docs/commands/ReviewManufacturingCostSummary.md

@@ -50,3 +50,4 @@ flowchart TD
 - returns error when the review result cannot represent all required variance types
 - returns error when reviewer identity is missing
 - keeps all required variance types distinct during review
+- returns error when final variance cannot be recalculated consistently

package/src/modules/manufacturing/docs/commands/UpdateWorkCenter.md

@@ -2,13 +2,13 @@
 
 ## Overview
 
-UpdateWorkCenter revises mutable work-center master data such as capacity, calendar, rate assumptions, and overhead policy. The command keeps existing production-order cost snapshots immutable even when active master data changes.
+UpdateWorkCenter revises mutable work-center master data such as capacity, calendar, rate assumptions, and overhead policy. The target work center can be looked up by `id` or by `companyId` + `siteId` + `code`. The command keeps existing production-order cost snapshots immutable even when active master data changes.
 
 ## Business Rules
 
-- Target work center must exist.
+- Target work center must exist (looked up by `id` or `companyId` + `siteId` + `code`).
 - Draft and active work centers may be updated.
-- Scope identity and unique code remain immutable after creation.
+- Scope identity and unique code are fixed by the existing record and are used only for lookup.
 - Capacity must remain positive.
 - Labor and machine rates must be zero or greater.
 - Fixed-amount overhead requires a currency.
@@ -32,7 +32,6 @@ flowchart TD
 ## Error Scenarios
 
 - **WORK_CENTER_NOT_FOUND**: Target work center does not exist.
-- **IMMUTABLE_SCOPE_FIELD**: The request attempts to change immutable scope or code fields.
 - **INVALID_CAPACITY**: Capacity is zero or negative.
 - **INVALID_RATE**: Labor or machine rate is negative.
 - **INVALID_OVERHEAD_METHOD**: Overhead method is not supported.
@@ -42,7 +41,9 @@ flowchart TD
 
 - updates an active work center without changing scope identity
 - returns error when the work center does not exist
-- returns error when immutable scope fields are changed
+- looks up a work center by companyId, siteId, and code
 - returns error when capacity is not positive
 - returns error when a rate is negative
 - preserves released cost baselines after update
+- returns error when the overhead method is not supported
+- returns error when fixed-amount overhead omits currency

package/src/modules/manufacturing/docs/models/BillOfMaterialLine.md

@@ -0,0 +1,42 @@
+# BillOfMaterialLine
+
+## Description
+
+BillOfMaterialLine stores one component entry within a BillOfMaterial version. It owns the component item reference, required quantity, unit of measure, scrap assumption, and subassembly flag that drive BOM explosion and production-order material requirements at release time.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createBillOfMaterial](../commands/CreateBillOfMaterial.md) - Create draft BOM versions including initial component lines.
+- [updateBillOfMaterial](../commands/UpdateBillOfMaterial.md) - Revise component lines while the BOM remains draft.
+- [activateBillOfMaterial](../commands/ActivateBillOfMaterial.md) - Validate and freeze the component line structure for selection at release.
+- [deactivateBillOfMaterial](../commands/DeactivateBillOfMaterial.md) - Retire the BOM version without mutating lines on existing production-order snapshots.
+
+### Query Definitions
+
+- [getBillOfMaterial](../queries/GetBillOfMaterial.md) - Retrieve one BOM version with its component lines.
+- [explodeBillOfMaterial](../queries/ExplodeBillOfMaterial.md) - Expand component lines into multi-level requirements for planning.
+- [listBillOfMaterialsByItem](../queries/ListBillOfMaterialsByItem.md) - List BOM versions and lines for one parent item and scope.
+- [detectBillOfMaterialCircularReference](../queries/DetectBillOfMaterialCircularReference.md) - Validate component line references for circular manufactured-item loops.
+
+### Models
+
+- BillOfMaterialLine
+
+### Invariants
+
+- Every BillOfMaterialLine belongs to exactly one BillOfMaterial version.
+- `requiredQuantity` must be greater than zero.
+- Component item must be a valid item reference.
+- Inactive items cannot appear as component lines on a draft or active BOM.
+- `scrapAssumption`, when provided, must be zero or greater.
+
+### Relationships
+
+- **Belongs To BillOfMaterial**: each line is subordinate to one [BillOfMaterial](./BillOfMaterial.md) version.
+- **References Item (cross-module)**: `itemId` points to a component [Item](../../../item-management/docs/models/Item.md).

package/src/modules/manufacturing/docs/models/CostVarianceLine.md

@@ -0,0 +1,36 @@
+# CostVarianceLine
+
+## Description
+
+CostVarianceLine stores one classified variance entry within a ManufacturingCostSummary. It owns the variance type, computed amount, optional account reference for settlement handoff, and an optional variance percentage that together express the planned-versus-actual deviation for one cost category.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [technicallyCompleteProductionOrder](../commands/TechnicallyCompleteProductionOrder.md) - Move the parent summary toward variance review where variance lines are produced.
+- [reviewManufacturingCostSummary](../commands/ReviewManufacturingCostSummary.md) - Recalculate, classify, and freeze variance lines on the parent summary.
+
+### Query Definitions
+
+- [getManufacturingCostSummary](../queries/GetManufacturingCostSummary.md) - Retrieve variance lines as part of the parent manufacturing cost summary.
+- [listManufacturingCostSummariesByStatus](../queries/ListManufacturingCostSummariesByStatus.md) - List summaries whose variance lines await review or settlement.
+
+### Models
+
+- CostVarianceLine
+
+### Invariants
+
+- Every CostVarianceLine belongs to exactly one ManufacturingCostSummary.
+- `varianceType` must be one of `MATERIAL_PRICE`, `MATERIAL_USAGE`, `LABOR_RATE`, `LABOR_EFFICIENCY`, `MACHINE_RATE`, `MACHINE_EFFICIENCY`, `SCRAP`, or `YIELD`.
+- Variance lines are frozen when the parent summary reaches `VARIANCE_REVIEWED`.
+- Each named variance type appears at most once per summary.
+
+### Relationships
+
+- **Belongs To ManufacturingCostSummary**: each line is subordinate to one [ManufacturingCostSummary](./ManufacturingCostSummary.md).

package/src/modules/manufacturing/docs/models/ManufacturingCostLine.md

@@ -0,0 +1,37 @@
+# ManufacturingCostLine
+
+## Description
+
+ManufacturingCostLine stores one planned-versus-actual cost entry within a ManufacturingCostSummary. It owns the cost type category, planned amount frozen at release, and accumulated actual amount updated through execution evidence.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [releaseProductionOrder](../commands/ReleaseProductionOrder.md) - Initialize planned cost lines when the production order is released.
+- [recordInventoryIssueOutcome](../commands/RecordInventoryIssueOutcome.md) - Update actual material amounts on cost lines from inventory-valued outcomes.
+- [reviewManufacturingCostSummary](../commands/ReviewManufacturingCostSummary.md) - Recalculate and freeze variance context that references planned versus actual cost lines.
+
+### Query Definitions
+
+- [getManufacturingCostSummary](../queries/GetManufacturingCostSummary.md) - Retrieve cost lines as part of the parent manufacturing cost summary.
+- [listManufacturingCostSummariesByStatus](../queries/ListManufacturingCostSummariesByStatus.md) - List summaries whose cost lines appear in review or settlement queues.
+
+### Models
+
+- ManufacturingCostLine
+
+### Invariants
+
+- Every ManufacturingCostLine belongs to exactly one ManufacturingCostSummary.
+- `costType` identifies one cost category such as `MATERIAL`, `LABOR`, `MACHINE`, or `OVERHEAD`.
+- `plannedAmount` is frozen at production-order release and never recomputed from later master-data changes.
+- `actualAmount` accumulates from execution evidence only while the parent summary is in `COLLECTING`.
+
+### Relationships
+
+- **Belongs To ManufacturingCostSummary**: each line is subordinate to one [ManufacturingCostSummary](./ManufacturingCostSummary.md).

package/src/modules/manufacturing/docs/models/ManufacturingCostSettlementRecord.md

@@ -0,0 +1,34 @@
+# ManufacturingCostSettlementRecord
+
+## Description
+
+ManufacturingCostSettlementRecord stores the downstream settlement acknowledgment evidence for a ManufacturingCostSummary. It owns the settlement date, settlement reference identifier, and an optional acknowledged date that together confirm that the variance review has been accepted by the downstream accounting or financial close process.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [recordManufacturingCostSettlementAcknowledgment](../commands/RecordManufacturingCostSettlementAcknowledgment.md) - Persist settlement acknowledgment evidence on the parent manufacturing cost summary.
+
+### Query Definitions
+
+- [getManufacturingCostSummary](../queries/GetManufacturingCostSummary.md) - Retrieve the settlement record as part of the parent cost summary.
+
+### Models
+
+- ManufacturingCostSettlementRecord
+
+### Invariants
+
+- Every ManufacturingCostSettlementRecord belongs to exactly one ManufacturingCostSummary.
+- `settlementDate` and `settlementReference` are required.
+- A valid settlement record enables the parent ManufacturingCostSummary to transition to `SETTLED`.
+- Settlement reference, order, summary, and currency must match the reviewed handoff.
+
+### Relationships
+
+- **Belongs To ManufacturingCostSummary**: each record is subordinate to one [ManufacturingCostSummary](./ManufacturingCostSummary.md).

package/src/modules/manufacturing/docs/models/ProductionOrderBomSnapshot.md

@@ -0,0 +1,35 @@
+# ProductionOrderBomSnapshot
+
+## Description
+
+ProductionOrderBomSnapshot stores the immutable BOM state frozen at production-order release. It owns the parent item reference, BOM type, and a serialized representation of the full BOM structure so that later BOM edits never affect released work.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [releaseProductionOrder](../commands/ReleaseProductionOrder.md) - Freeze the BOM snapshot when the production order is released.
+
+### Query Definitions
+
+- [getProductionOrder](../queries/GetProductionOrder.md) - Retrieve the BOM snapshot as part of the parent production order.
+
+### Models
+
+- ProductionOrderBomSnapshot
+
+### Invariants
+
+- Every ProductionOrder has at most one ProductionOrderBomSnapshot, created at release.
+- The snapshot is immutable once created; later BOM updates do not affect it.
+- `bomType` reflects the BOM type semantics frozen at release time.
+- The snapshot exists only on orders in `RELEASED`, `IN_PROGRESS`, `COMPLETED`, `TECHNICALLY_COMPLETE`, or `CLOSED`.
+
+### Relationships
+
+- **Belongs To ProductionOrder**: the snapshot is owned by one [ProductionOrder](./ProductionOrder.md).
+- **Derived From BillOfMaterial**: the snapshot captures the state of a resolved [BillOfMaterial](./BillOfMaterial.md) version at release time.

package/src/modules/manufacturing/docs/models/ProductionOrderCostBaseline.md

@@ -0,0 +1,36 @@
+# ProductionOrderCostBaseline
+
+## Description
+
+ProductionOrderCostBaseline stores the frozen planned cost figures established at production-order release. It owns the planned material, labor, machine, and overhead cost totals along with the currency code so that variance analysis always compares actuals against an immutable release-time plan.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [releaseProductionOrder](../commands/ReleaseProductionOrder.md) - Create the frozen cost baseline when the production order is released.
+
+### Query Definitions
+
+- [getProductionOrder](../queries/GetProductionOrder.md) - Retrieve the cost baseline as part of the parent production order.
+
+### Models
+
+- ProductionOrderCostBaseline
+
+### Invariants
+
+- Every ProductionOrder has at most one ProductionOrderCostBaseline, created at release.
+- The baseline is immutable once created; later work-center rate or BOM changes do not affect it.
+- All planned cost fields are zero or greater.
+- `currencyCode` is required and must be a valid ISO 4217 code.
+- The baseline exists only on orders in `RELEASED`, `IN_PROGRESS`, `COMPLETED`, `TECHNICALLY_COMPLETE`, or `CLOSED`.
+
+### Relationships
+
+- **Belongs To ProductionOrder**: the baseline is owned by one [ProductionOrder](./ProductionOrder.md).
+- **Feeds ManufacturingCostSummary**: the frozen baseline drives planned totals in [ManufacturingCostSummary](./ManufacturingCostSummary.md) variance calculations.

package/src/modules/manufacturing/docs/models/ProductionOrderMaterialRequirement.md

@@ -0,0 +1,35 @@
+# ProductionOrderMaterialRequirement
+
+## Description
+
+ProductionOrderMaterialRequirement stores one exploded component requirement derived from the BOM snapshot at production-order release. It owns the component item reference, required quantity, unit of measure, and optional planned unit cost that drive material staging and inventory issue planning for the order.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [releaseProductionOrder](../commands/ReleaseProductionOrder.md) - Explode the BOM snapshot into material requirements when the production order is released.
+
+### Query Definitions
+
+- [getProductionOrder](../queries/GetProductionOrder.md) - Retrieve material requirements as part of the parent production order.
+
+### Models
+
+- ProductionOrderMaterialRequirement
+
+### Invariants
+
+- Every ProductionOrderMaterialRequirement belongs to exactly one ProductionOrder.
+- `requiredQuantity` must be greater than zero.
+- Requirements are created at release and reflect the BOM snapshot; later BOM edits do not affect them.
+- `plannedUnitCost`, when provided, is zero or greater.
+
+### Relationships
+
+- **Belongs To ProductionOrder**: each requirement is owned by one [ProductionOrder](./ProductionOrder.md).
+- **References Item (cross-module)**: `itemId` points to the required component [Item](../../../item-management/docs/models/Item.md).

package/src/modules/manufacturing/docs/models/ProductionOrderRoutingSnapshot.md

@@ -0,0 +1,34 @@
+# ProductionOrderRoutingSnapshot
+
+## Description
+
+ProductionOrderRoutingSnapshot stores the immutable routing state frozen at production-order release. It owns the routing reference and a serialized representation of the full routing structure so that later routing revisions never affect released work orders.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [releaseProductionOrder](../commands/ReleaseProductionOrder.md) - Freeze the routing snapshot when the production order is released.
+
+### Query Definitions
+
+- [getProductionOrder](../queries/GetProductionOrder.md) - Retrieve the routing snapshot as part of the parent production order.
+
+### Models
+
+- ProductionOrderRoutingSnapshot
+
+### Invariants
+
+- Every ProductionOrder has at most one ProductionOrderRoutingSnapshot, created at release.
+- The snapshot is immutable once created; later routing revisions do not affect it.
+- The snapshot exists only on orders in `RELEASED`, `IN_PROGRESS`, `COMPLETED`, `TECHNICALLY_COMPLETE`, or `CLOSED`.
+
+### Relationships
+
+- **Belongs To ProductionOrder**: the snapshot is owned by one [ProductionOrder](./ProductionOrder.md).
+- **Derived From Routing**: the snapshot captures the state of a resolved [Routing](./Routing.md) revision at release time.