@tailor-platform/erp-kit 0.6.0 → 0.8.0

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.

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

@@ -0,0 +1,40 @@
+# RoutingOperation
+
+## Description
+
+RoutingOperation defines one ordered step within a Routing. It owns the sequence number, work-center assignment, standard setup and run time assumptions, optional operation description, and operator instructions that production-order release later snapshots into executable work orders.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [createRouting](../commands/CreateRouting.md) - Create draft routings including initial ordered operations.
+- [updateRouting](../commands/UpdateRouting.md) - Revise operation sequence, times, and work-center assignments while the routing is draft.
+- [activateRouting](../commands/ActivateRouting.md) - Validate ordered operations and make the routing eligible for production-order release.
+- [deactivateRouting](../commands/DeactivateRouting.md) - Retire the routing revision without mutating operations already snapshotted onto released orders.
+
+### Query Definitions
+
+- [getRouting](../queries/GetRouting.md) - Retrieve one routing revision with ordered operations.
+- [listRoutingsByItem](../queries/ListRoutingsByItem.md) - List routing revisions and operations for one parent item and scope.
+
+### Models
+
+- RoutingOperation
+
+### Invariants
+
+- Every RoutingOperation belongs to exactly one Routing.
+- `sequenceNumber` must be unique within its parent Routing.
+- `standardSetupTime` and `standardRunTime` must be zero or greater.
+- Each operation must reference an active work center valid for the same company and effective scope.
+- An active Routing must not reference an inactive work center through any of its operations.
+
+### Relationships
+
+- **Belongs To Routing**: each operation is subordinate to one [Routing](./Routing.md).
+- **References WorkCenter**: `workCenterId` points to the [WorkCenter](./WorkCenter.md) where the step executes.

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

@@ -0,0 +1,38 @@
+# WorkOrderExecutionEvent
+
+## Description
+
+WorkOrderExecutionEvent records one discrete execution action taken on a WorkOrder. It owns the event type, timestamp, and optional quantity, time, scrap, and notes values that together form the immutable audit trail for shop-floor progress, pauses, resumes, and completion.
+
+## Domain Model Definitions
+
+### Model type
+
+Standard
+
+### Command Definitions
+
+- [startWorkOrder](../commands/StartWorkOrder.md) - Append STARTED execution events when shop-floor work begins.
+- [reportWorkOrderProgress](../commands/ReportWorkOrderProgress.md) - Append PROGRESS_REPORTED events with quantities, time, scrap, and notes.
+- [pauseWorkOrder](../commands/PauseWorkOrder.md) - Append PAUSED execution events when work is interrupted.
+- [resumeWorkOrder](../commands/ResumeWorkOrder.md) - Append RESUMED execution events when work continues after a pause.
+- [completeWorkOrder](../commands/CompleteWorkOrder.md) - Append COMPLETED execution events when the operation finishes.
+
+### Query Definitions
+
+- [getWorkOrder](../queries/GetWorkOrder.md) - Retrieve execution events as part of one work order.
+
+### Models
+
+- WorkOrderExecutionEvent
+
+### Invariants
+
+- Every WorkOrderExecutionEvent belongs to exactly one WorkOrder.
+- `eventType` must be one of `STARTED`, `PAUSED`, `RESUMED`, `PROGRESS_REPORTED`, or `COMPLETED`.
+- `quantity`, `timeValue`, and `scrapValue`, when provided, must be zero or greater.
+- Events are append-only; existing events are never mutated after creation.
+
+### Relationships
+
+- **Belongs To WorkOrder**: each event is subordinate to one [WorkOrder](./WorkOrder.md).

package/src/modules/manufacturing/docs/queries/ExplodeBillOfMaterial.md

@@ -54,3 +54,4 @@ flowchart TD
 - returns error when the root BOM is not effective on the requested date
 - returns error when a required lower-level child BOM cannot be resolved
 - returns error when the explosion detects a circular BOM reference
+- resolves lower-level child BOMs using the applicable site scope

package/src/modules/manufacturing/docs/queries/ListWorkCentersBySite.md

@@ -36,3 +36,4 @@ flowchart TD
 - returns an empty list when the site has no work centers
 - returns error when company scope is missing
 - returns error when site scope is missing
+- filters work centers by work-center type and accepts name ordering

package/src/modules/organization/command/updateCompany.test.ts

@@ -89,7 +89,7 @@ describe("updateCompany", () => {
     }
   });
 
-  it("throws when company does not exist", async () => {
+  it("returns error when company does not exist", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(undefined);
 
@@ -109,7 +109,7 @@ describe("updateCompany", () => {
     }
   });
 
-  it("throws when legal name is empty", async () => {
+  it("returns error when legal name is empty", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(draftCompany);
 
@@ -129,7 +129,7 @@ describe("updateCompany", () => {
     }
   });
 
-  it("throws when changing base currency on ACTIVE company", async () => {
+  it("returns error when changing base currency on ACTIVE company", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(activeCompany);
 
@@ -149,7 +149,7 @@ describe("updateCompany", () => {
     }
   });
 
-  it("throws when changing base currency on INACTIVE company", async () => {
+  it("returns error when changing base currency on INACTIVE company", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select.mockReturnValueOnce(inactiveCompany);
 
@@ -169,7 +169,7 @@ describe("updateCompany", () => {
     }
   });
 
-  it("throws when new base currency does not exist", async () => {
+  it("returns error when new base currency does not exist", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select
       .mockReturnValueOnce(draftCompany) // company lookup
@@ -191,7 +191,7 @@ describe("updateCompany", () => {
     }
   });
 
-  it("throws when new base currency is inactive", async () => {
+  it("returns error when new base currency is inactive", async () => {
     const { db, spies } = createMockDb<Transaction>();
     spies.select
       .mockReturnValueOnce(draftCompany) // company lookup