@comity/order 0.9.0 → 0.9.1

package/README.md

@@ -30,7 +30,7 @@ This package does NOT:
 
 ## Public API
 
-- `Order` — order entity with lifecycle and item mutations (`addItem`, `removeItem`, `updateItemQuantity`, `submit`, `confirm`, `fulfill`, `cancel`)
+- `Order` — order entity with lifecycle and item mutations (`setItems`, `addItem`, `removeItem`, `updateItemQuantity`, `submit`, `confirm`, `fulfill`, `cancel`)
 - `OrderId` — order identifier value object
 - `OrderRepository` — persistence-boundary contract (`getById`, `search`, `save`)
 - `OrderState`, `OrderCreate`, `OrderUpdate`, `OrderSnapshot`, `OrderData`, `OrderStatus` — domain contracts
@@ -68,6 +68,3 @@ No exhaustive reference; see docs for constraints.
 ## Status
 
 Stable
-
-_Review Completed: 2026-08-01_
-_Compliance Score: N/A% (Green)_

package/dist/cjs/entities/order.js

@@ -42,6 +42,32 @@ function copyProductSnapshot(snapshot) {
         ...(snapshot.metadata !== undefined ? { metadata: { ...snapshot.metadata } } : {}),
     };
 }
+/**
+ * Returns a defensive copy of an order item so later mutations of the input
+ * cannot leak into the order.
+ *
+ * @param item - The order item to copy.
+ *
+ * @returns A defensive copy of the item.
+ */
+function copyOrderItem(item) {
+    return {
+        ...item,
+        product: copyProductSnapshot(item.product),
+        ...(item.meta !== undefined ? { meta: { ...item.meta } } : {}),
+    };
+}
+/**
+ * Returns whether a quantity is a valid order item quantity: an integer
+ * greater than or equal to 1.
+ *
+ * @param quantity - The quantity to validate.
+ *
+ * @returns `true` when the quantity is a positive integer, otherwise `false`.
+ */
+function isValidItemQuantity(quantity) {
+    return Number.isInteger(quantity) && quantity >= 1;
+}
 /**
  * Returns a defensive copy of a contact so later mutations of the input cannot
  * leak into the order.
@@ -126,17 +152,22 @@ class Order {
     #updatedAt;
     /**
      * @param fields - The fields used to create or hydrate the order.
-     * @param id - The unique identifier of the order, if it has been assigned.
+     * @param id - The unique identifier of the order, supplied by the caller.
+     * The Order never generates its own aggregate ID; hydration preserves the
+     * persisted ID verbatim.
      */
     constructor(fields, id) {
         this.#id = id;
         this.#status = fields.status ?? "draft";
-        this.#items = [...fields.items];
+        this.#items = fields.items.map(copyOrderItem);
         this.#price = fields.price;
         this.#channelId = fields.channelId;
-        this.#customer = fields.customer !== undefined ? copyCustomerSnapshot(fields.customer) : undefined;
+        this.#customer =
+            fields.customer !== undefined ? copyCustomerSnapshot(fields.customer) : undefined;
         this.#addresses =
-            fields.addresses !== undefined ? fields.addresses.map((address) => copyAddressSnapshot(address)) : undefined;
+            fields.addresses !== undefined
+                ? fields.addresses.map((address) => copyAddressSnapshot(address))
+                : undefined;
         this.#payments =
             fields.payments !== undefined
                 ? fields.payments.map((payment) => ({ ...payment }))
@@ -146,7 +177,7 @@ class Order {
         this.#updatedAt = fields.updatedAt ?? this.#createdAt;
     }
     /**
-     * @returns The unique identifier of the order, if it has been assigned.
+     * @returns The unique identifier of the order.
      */
     get id() {
         return this.#id;
@@ -167,7 +198,7 @@ class Order {
      * @returns The order items.
      */
     get items() {
-        return [...this.#items];
+        return this.#items.map(copyOrderItem);
     }
     /**
      * @returns The order price.
@@ -224,7 +255,7 @@ class Order {
      * Updates the applied pricing result and metadata.
      *
      * Status transitions are performed through the domain methods; items are
-     * mutated through `addItem`/`removeItem`/`updateItemQuantity`.
+     * mutated through `setItems`/`addItem`/`removeItem`/`updateItemQuantity`.
      *
      * @param changes - The changes to apply to the order.
      */
@@ -248,10 +279,7 @@ class Order {
      * @param snapshot - The payment fact to record.
      */
     attachPayment(snapshot) {
-        this.#payments = [
-            ...(this.#payments ?? []),
-            { ...snapshot },
-        ];
+        this.#payments = [...(this.#payments ?? []), { ...snapshot }];
         this.#updatedAt = time_1.Instant.now();
     }
     /**
@@ -275,7 +303,7 @@ class Order {
         if (this.#status !== "draft" && this.#status !== "pending") {
             return (0, result_1.failure)(new order_js_1.OrderError("shipping_destination_immutable", {
                 details: {
-                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    orderId: this.#id.toString(),
                 },
             }));
         }
@@ -285,43 +313,108 @@ class Order {
         if (current === undefined || addresses === undefined) {
             return (0, result_1.failure)(new order_js_1.OrderError("ambiguous_shipping_destination", {
                 details: {
-                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    orderId: this.#id.toString(),
                 },
             }));
         }
         if (isSameShippingDestination(current, destination)) {
             return (0, result_1.success)(undefined);
         }
-        this.#addresses = addresses.map((address) => address.role === "shipping" ? copyAddressSnapshot({ ...destination, role: "shipping" }) : address);
+        this.#addresses = addresses.map((address) => address.role === "shipping"
+            ? copyAddressSnapshot({ ...destination, role: "shipping" })
+            : address);
+        this.#updatedAt = time_1.Instant.now();
+        return (0, result_1.success)(undefined);
+    }
+    /**
+     * Replaces the entire item collection with the supplied one (ADR-030).
+     *
+     * The supplied collection is the complete desired collection: items omitted
+     * from it are removed, and no merging, appending, or quantity aggregation
+     * occurs. The supplied order is the resulting order and an empty collection
+     * is valid. Every entry is validated before any state changes — quantity
+     * (integer `>= 1`) first, then ID uniqueness against the IDs already seen —
+     * and the first violation rejects the whole operation, leaving the aggregate
+     * unchanged. Every successful replacement refreshes `updatedAt`, including
+     * identical replacements. Supplied item IDs are preserved verbatim and
+     * caller-owned data is defensively copied. Item mutation is not status-gated.
+     *
+     * @param items - The complete desired item collection.
+     *
+     * @returns A result indicating the success or failure of the replacement.
+     */
+    setItems(items) {
+        const seen = new Set();
+        for (const item of items) {
+            if (!isValidItemQuantity(item.quantity)) {
+                return (0, result_1.failure)(new order_js_1.OrderError("invalid_quantity", {
+                    details: {
+                        orderId: this.#id.toString(),
+                        itemId: item.id,
+                        field: "quantity",
+                    },
+                }));
+            }
+            if (seen.has(item.id)) {
+                return (0, result_1.failure)(new order_js_1.OrderError("duplicate_item_id", {
+                    details: {
+                        orderId: this.#id.toString(),
+                        itemId: item.id,
+                    },
+                }));
+            }
+            seen.add(item.id);
+        }
+        this.#items = items.map(copyOrderItem);
         this.#updatedAt = time_1.Instant.now();
         return (0, result_1.success)(undefined);
     }
     /**
-     * Adds an item to the order.
+     * Appends one item occurrence to the order.
      *
-     * @param input - The item data to add.
+     * The occurrence ID is supplied by the caller in the input: the Order never
+     * mints occurrence IDs itself. The ID must be unique within the order —
+     * appending an already-used ID is rejected so the `setItems` duplicate-ID
+     * invariant cannot be bypassed through this path. Validation runs before
+     * any mutation — quantity (integer `>= 1`) first, then ID uniqueness — and
+     * failures leave the aggregate unchanged. A successful append refreshes
+     * `updatedAt`. Occurrence IDs carry no product meaning: identical
+     * product/configuration data may coexist under distinct IDs.
      *
-     * @returns The created item, or an `invalid_quantity` error when the
-     * quantity is not a positive integer.
+     * @param input - The item data to add, including the caller-assigned
+     * occurrence ID.
+     *
+     * @returns The created item copy, an `invalid_quantity` error when the
+     * quantity is not a positive integer, or a `duplicate_item_id` error when
+     * the ID is already used within the order.
      */
     addItem(input) {
-        if (!Number.isInteger(input.quantity) || input.quantity < 1) {
+        if (!isValidItemQuantity(input.quantity)) {
             return (0, result_1.failure)(new order_js_1.OrderError("invalid_quantity", {
                 details: {
-                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    orderId: this.#id.toString(),
+                    itemId: input.id,
                     field: "quantity",
                 },
             }));
         }
+        if (this.#items.some((existing) => existing.id === input.id)) {
+            return (0, result_1.failure)(new order_js_1.OrderError("duplicate_item_id", {
+                details: {
+                    orderId: this.#id.toString(),
+                    itemId: input.id,
+                },
+            }));
+        }
         const item = {
-            id: crypto.randomUUID(),
+            id: input.id,
             product: copyProductSnapshot(input.product),
             quantity: input.quantity,
             price: input.price,
         };
         this.#items.push(item);
         this.#updatedAt = time_1.Instant.now();
-        return (0, result_1.success)(item);
+        return (0, result_1.success)(copyOrderItem(item));
     }
     /**
      * Removes an item from the order.
@@ -335,7 +428,7 @@ class Order {
         if (index === -1) {
             return (0, result_1.failure)(new order_js_1.OrderError("invalid_item", {
                 details: {
-                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    orderId: this.#id.toString(),
                     itemId,
                 },
             }));
@@ -353,10 +446,10 @@ class Order {
      * @returns A result indicating the success or failure of the update.
      */
     updateItemQuantity(itemId, quantity) {
-        if (!Number.isInteger(quantity) || quantity < 1) {
+        if (!isValidItemQuantity(quantity)) {
             return (0, result_1.failure)(new order_js_1.OrderError("invalid_quantity", {
                 details: {
-                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    orderId: this.#id.toString(),
                     itemId,
                     field: "quantity",
                 },
@@ -366,7 +459,7 @@ class Order {
         if (index === -1) {
             return (0, result_1.failure)(new order_js_1.OrderError("invalid_item", {
                 details: {
-                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    orderId: this.#id.toString(),
                     itemId,
                 },
             }));
@@ -412,7 +505,6 @@ class Order {
     }
     /**
      * Creates a snapshot of the current state of the order.
-     * Requires the order to have an assigned identifier.
      *
      * @returns A snapshot representing the current state of the order.
      */
@@ -420,7 +512,7 @@ class Order {
         return {
             id: this.#id,
             status: this.#status,
-            items: [...this.#items],
+            items: this.#items.map(copyOrderItem),
             price: this.#price,
             channelId: this.#channelId,
             ...(this.#customer !== undefined ? { customer: copyCustomerSnapshot(this.#customer) } : {}),

package/dist/cjs/errors/order.js

@@ -8,6 +8,7 @@ const REASON_MESSAGES = {
     invalid_status_transition: "Invalid order status transition",
     shipping_destination_immutable: "Shipping destination cannot be changed in the current order status",
     ambiguous_shipping_destination: "Order must contain exactly one shipping destination",
+    duplicate_item_id: "Duplicate order item identifier",
 };
 const REASON_HTTP_STATUS = {
     invalid_quantity: 400,
@@ -15,6 +16,7 @@ const REASON_HTTP_STATUS = {
     invalid_status_transition: 409,
     shipping_destination_immutable: 409,
     ambiguous_shipping_destination: 409,
+    duplicate_item_id: 400,
 };
 /**
  * Order operation error with typed reasons.

package/dist/esm/entities/order.js

@@ -39,6 +39,32 @@ function copyProductSnapshot(snapshot) {
         ...(snapshot.metadata !== undefined ? { metadata: { ...snapshot.metadata } } : {}),
     };
 }
+/**
+ * Returns a defensive copy of an order item so later mutations of the input
+ * cannot leak into the order.
+ *
+ * @param item - The order item to copy.
+ *
+ * @returns A defensive copy of the item.
+ */
+function copyOrderItem(item) {
+    return {
+        ...item,
+        product: copyProductSnapshot(item.product),
+        ...(item.meta !== undefined ? { meta: { ...item.meta } } : {}),
+    };
+}
+/**
+ * Returns whether a quantity is a valid order item quantity: an integer
+ * greater than or equal to 1.
+ *
+ * @param quantity - The quantity to validate.
+ *
+ * @returns `true` when the quantity is a positive integer, otherwise `false`.
+ */
+function isValidItemQuantity(quantity) {
+    return Number.isInteger(quantity) && quantity >= 1;
+}
 /**
  * Returns a defensive copy of a contact so later mutations of the input cannot
  * leak into the order.
@@ -123,17 +149,22 @@ export class Order {
     #updatedAt;
     /**
      * @param fields - The fields used to create or hydrate the order.
-     * @param id - The unique identifier of the order, if it has been assigned.
+     * @param id - The unique identifier of the order, supplied by the caller.
+     * The Order never generates its own aggregate ID; hydration preserves the
+     * persisted ID verbatim.
      */
     constructor(fields, id) {
         this.#id = id;
         this.#status = fields.status ?? "draft";
-        this.#items = [...fields.items];
+        this.#items = fields.items.map(copyOrderItem);
         this.#price = fields.price;
         this.#channelId = fields.channelId;
-        this.#customer = fields.customer !== undefined ? copyCustomerSnapshot(fields.customer) : undefined;
+        this.#customer =
+            fields.customer !== undefined ? copyCustomerSnapshot(fields.customer) : undefined;
         this.#addresses =
-            fields.addresses !== undefined ? fields.addresses.map((address) => copyAddressSnapshot(address)) : undefined;
+            fields.addresses !== undefined
+                ? fields.addresses.map((address) => copyAddressSnapshot(address))
+                : undefined;
         this.#payments =
             fields.payments !== undefined
                 ? fields.payments.map((payment) => ({ ...payment }))
@@ -143,7 +174,7 @@ export class Order {
         this.#updatedAt = fields.updatedAt ?? this.#createdAt;
     }
     /**
-     * @returns The unique identifier of the order, if it has been assigned.
+     * @returns The unique identifier of the order.
      */
     get id() {
         return this.#id;
@@ -164,7 +195,7 @@ export class Order {
      * @returns The order items.
      */
     get items() {
-        return [...this.#items];
+        return this.#items.map(copyOrderItem);
     }
     /**
      * @returns The order price.
@@ -221,7 +252,7 @@ export class Order {
      * Updates the applied pricing result and metadata.
      *
      * Status transitions are performed through the domain methods; items are
-     * mutated through `addItem`/`removeItem`/`updateItemQuantity`.
+     * mutated through `setItems`/`addItem`/`removeItem`/`updateItemQuantity`.
      *
      * @param changes - The changes to apply to the order.
      */
@@ -245,10 +276,7 @@ export class Order {
      * @param snapshot - The payment fact to record.
      */
     attachPayment(snapshot) {
-        this.#payments = [
-            ...(this.#payments ?? []),
-            { ...snapshot },
-        ];
+        this.#payments = [...(this.#payments ?? []), { ...snapshot }];
         this.#updatedAt = Instant.now();
     }
     /**
@@ -272,7 +300,7 @@ export class Order {
         if (this.#status !== "draft" && this.#status !== "pending") {
             return failure(new OrderError("shipping_destination_immutable", {
                 details: {
-                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    orderId: this.#id.toString(),
                 },
             }));
         }
@@ -282,43 +310,108 @@ export class Order {
         if (current === undefined || addresses === undefined) {
             return failure(new OrderError("ambiguous_shipping_destination", {
                 details: {
-                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    orderId: this.#id.toString(),
                 },
             }));
         }
         if (isSameShippingDestination(current, destination)) {
             return success(undefined);
         }
-        this.#addresses = addresses.map((address) => address.role === "shipping" ? copyAddressSnapshot({ ...destination, role: "shipping" }) : address);
+        this.#addresses = addresses.map((address) => address.role === "shipping"
+            ? copyAddressSnapshot({ ...destination, role: "shipping" })
+            : address);
+        this.#updatedAt = Instant.now();
+        return success(undefined);
+    }
+    /**
+     * Replaces the entire item collection with the supplied one (ADR-030).
+     *
+     * The supplied collection is the complete desired collection: items omitted
+     * from it are removed, and no merging, appending, or quantity aggregation
+     * occurs. The supplied order is the resulting order and an empty collection
+     * is valid. Every entry is validated before any state changes — quantity
+     * (integer `>= 1`) first, then ID uniqueness against the IDs already seen —
+     * and the first violation rejects the whole operation, leaving the aggregate
+     * unchanged. Every successful replacement refreshes `updatedAt`, including
+     * identical replacements. Supplied item IDs are preserved verbatim and
+     * caller-owned data is defensively copied. Item mutation is not status-gated.
+     *
+     * @param items - The complete desired item collection.
+     *
+     * @returns A result indicating the success or failure of the replacement.
+     */
+    setItems(items) {
+        const seen = new Set();
+        for (const item of items) {
+            if (!isValidItemQuantity(item.quantity)) {
+                return failure(new OrderError("invalid_quantity", {
+                    details: {
+                        orderId: this.#id.toString(),
+                        itemId: item.id,
+                        field: "quantity",
+                    },
+                }));
+            }
+            if (seen.has(item.id)) {
+                return failure(new OrderError("duplicate_item_id", {
+                    details: {
+                        orderId: this.#id.toString(),
+                        itemId: item.id,
+                    },
+                }));
+            }
+            seen.add(item.id);
+        }
+        this.#items = items.map(copyOrderItem);
         this.#updatedAt = Instant.now();
         return success(undefined);
     }
     /**
-     * Adds an item to the order.
+     * Appends one item occurrence to the order.
      *
-     * @param input - The item data to add.
+     * The occurrence ID is supplied by the caller in the input: the Order never
+     * mints occurrence IDs itself. The ID must be unique within the order —
+     * appending an already-used ID is rejected so the `setItems` duplicate-ID
+     * invariant cannot be bypassed through this path. Validation runs before
+     * any mutation — quantity (integer `>= 1`) first, then ID uniqueness — and
+     * failures leave the aggregate unchanged. A successful append refreshes
+     * `updatedAt`. Occurrence IDs carry no product meaning: identical
+     * product/configuration data may coexist under distinct IDs.
      *
-     * @returns The created item, or an `invalid_quantity` error when the
-     * quantity is not a positive integer.
+     * @param input - The item data to add, including the caller-assigned
+     * occurrence ID.
+     *
+     * @returns The created item copy, an `invalid_quantity` error when the
+     * quantity is not a positive integer, or a `duplicate_item_id` error when
+     * the ID is already used within the order.
      */
     addItem(input) {
-        if (!Number.isInteger(input.quantity) || input.quantity < 1) {
+        if (!isValidItemQuantity(input.quantity)) {
             return failure(new OrderError("invalid_quantity", {
                 details: {
-                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    orderId: this.#id.toString(),
+                    itemId: input.id,
                     field: "quantity",
                 },
             }));
         }
+        if (this.#items.some((existing) => existing.id === input.id)) {
+            return failure(new OrderError("duplicate_item_id", {
+                details: {
+                    orderId: this.#id.toString(),
+                    itemId: input.id,
+                },
+            }));
+        }
         const item = {
-            id: crypto.randomUUID(),
+            id: input.id,
             product: copyProductSnapshot(input.product),
             quantity: input.quantity,
             price: input.price,
         };
         this.#items.push(item);
         this.#updatedAt = Instant.now();
-        return success(item);
+        return success(copyOrderItem(item));
     }
     /**
      * Removes an item from the order.
@@ -332,7 +425,7 @@ export class Order {
         if (index === -1) {
             return failure(new OrderError("invalid_item", {
                 details: {
-                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    orderId: this.#id.toString(),
                     itemId,
                 },
             }));
@@ -350,10 +443,10 @@ export class Order {
      * @returns A result indicating the success or failure of the update.
      */
     updateItemQuantity(itemId, quantity) {
-        if (!Number.isInteger(quantity) || quantity < 1) {
+        if (!isValidItemQuantity(quantity)) {
             return failure(new OrderError("invalid_quantity", {
                 details: {
-                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    orderId: this.#id.toString(),
                     itemId,
                     field: "quantity",
                 },
@@ -363,7 +456,7 @@ export class Order {
         if (index === -1) {
             return failure(new OrderError("invalid_item", {
                 details: {
-                    ...(this.#id !== undefined ? { orderId: this.#id.toString() } : {}),
+                    orderId: this.#id.toString(),
                     itemId,
                 },
             }));
@@ -409,7 +502,6 @@ export class Order {
     }
     /**
      * Creates a snapshot of the current state of the order.
-     * Requires the order to have an assigned identifier.
      *
      * @returns A snapshot representing the current state of the order.
      */
@@ -417,7 +509,7 @@ export class Order {
         return {
             id: this.#id,
             status: this.#status,
-            items: [...this.#items],
+            items: this.#items.map(copyOrderItem),
             price: this.#price,
             channelId: this.#channelId,
             ...(this.#customer !== undefined ? { customer: copyCustomerSnapshot(this.#customer) } : {}),

package/dist/esm/errors/order.js

@@ -5,6 +5,7 @@ const REASON_MESSAGES = {
     invalid_status_transition: "Invalid order status transition",
     shipping_destination_immutable: "Shipping destination cannot be changed in the current order status",
     ambiguous_shipping_destination: "Order must contain exactly one shipping destination",
+    duplicate_item_id: "Duplicate order item identifier",
 };
 const REASON_HTTP_STATUS = {
     invalid_quantity: 400,
@@ -12,6 +13,7 @@ const REASON_HTTP_STATUS = {
     invalid_status_transition: 409,
     shipping_destination_immutable: 409,
     ambiguous_shipping_destination: 409,
+    duplicate_item_id: 400,
 };
 /**
  * Order operation error with typed reasons.

package/dist/types/contracts/item.d.ts

@@ -81,7 +81,14 @@ export interface OrderProductSnapshot {
  * identity, lifecycle, or repository.
  */
 export interface OrderItem {
-    /** Unique item identifier within the order. */
+    /**
+     * Stable technical key for one occurrence within the order.
+     *
+     * The key identifies the occurrence, not the product: it carries no
+     * commercial equivalence meaning and must never be derived by comparing
+     * product data. Occurrence keys are unique within the order, preserved
+     * across retention/updates, and never reassigned after removal.
+     */
     readonly id: string;
     /** Associated product snapshot. */
     readonly product: OrderProductSnapshot;

package/dist/types/contracts/order.d.ts

@@ -63,7 +63,9 @@ export type OrderSnapshot = Readonly<OrderState & {
 /**
  * Data required to create a new order.
  *
- * The identifier and the initial status are managed by the entity: an order
+ * The identifier is supplied separately as the entity constructor's `id`
+ * argument: the caller (application service or hydration path) owns ID
+ * generation and the Order never generates its own aggregate ID. An order
  * without a supplied status starts as {@link OrderStatus."draft"}. Lifecycle
  * timestamps are optional so the same contract supports both creation and
  * hydration from persisted state (ADR-001).
@@ -81,7 +83,7 @@ export type OrderCreate = OrderData & {
  *
  * Status transitions are not part of the update contract: they must pass
  * through the entity's domain methods (`submit`, `confirm`, `fulfill`,
- * `cancel`). Items are mutated through `addItem`/`removeItem`/
+ * `cancel`). Items are mutated through `setItems`/`addItem`/`removeItem`/
  * `updateItemQuantity`, which protect the order's invariants.
  */
 export interface OrderUpdate {
@@ -99,6 +101,16 @@ export interface OrderUpdate {
  * from `ProductProjection`: the Order never depends on `@comity/catalog`.
  */
 export interface OrderItemInput {
+    /**
+     * Caller-assigned technical key for the new occurrence within the order.
+     *
+     * The ID identifies one occurrence, not a product: two occurrences may
+     * carry identical product/configuration data under distinct IDs. It must be
+     * unique within the order; the aggregate rejects duplicates. The ID is
+     * generated outside the Order (application service or caller); the Order
+     * never mints occurrence IDs itself.
+     */
+    readonly id: string;
     /** Product snapshot to add to the order. */
     readonly product: OrderProductSnapshot;
     /** Quantity to add. */

package/dist/types/entities/order.d.ts

@@ -23,13 +23,15 @@ export declare class Order {
     #private;
     /**
      * @param fields - The fields used to create or hydrate the order.
-     * @param id - The unique identifier of the order, if it has been assigned.
+     * @param id - The unique identifier of the order, supplied by the caller.
+     * The Order never generates its own aggregate ID; hydration preserves the
+     * persisted ID verbatim.
      */
-    constructor(fields: OrderCreate, id?: OrderId);
+    constructor(fields: OrderCreate, id: OrderId);
     /**
-     * @returns The unique identifier of the order, if it has been assigned.
+     * @returns The unique identifier of the order.
      */
-    get id(): OrderId | undefined;
+    get id(): OrderId;
     /**
      * @returns The commercial channel through which the order was placed.
      */
@@ -74,7 +76,7 @@ export declare class Order {
      * Updates the applied pricing result and metadata.
      *
      * Status transitions are performed through the domain methods; items are
-     * mutated through `addItem`/`removeItem`/`updateItemQuantity`.
+     * mutated through `setItems`/`addItem`/`removeItem`/`updateItemQuantity`.
      *
      * @param changes - The changes to apply to the order.
      */
@@ -109,12 +111,41 @@ export declare class Order {
      */
     changeShippingDestination(destination: Omit<OrderAddressSnapshot, "role">): Result<void, OrderError>;
     /**
-     * Adds an item to the order.
+     * Replaces the entire item collection with the supplied one (ADR-030).
      *
-     * @param input - The item data to add.
+     * The supplied collection is the complete desired collection: items omitted
+     * from it are removed, and no merging, appending, or quantity aggregation
+     * occurs. The supplied order is the resulting order and an empty collection
+     * is valid. Every entry is validated before any state changes — quantity
+     * (integer `>= 1`) first, then ID uniqueness against the IDs already seen —
+     * and the first violation rejects the whole operation, leaving the aggregate
+     * unchanged. Every successful replacement refreshes `updatedAt`, including
+     * identical replacements. Supplied item IDs are preserved verbatim and
+     * caller-owned data is defensively copied. Item mutation is not status-gated.
      *
-     * @returns The created item, or an `invalid_quantity` error when the
-     * quantity is not a positive integer.
+     * @param items - The complete desired item collection.
+     *
+     * @returns A result indicating the success or failure of the replacement.
+     */
+    setItems(items: ReadonlyArray<OrderItem>): Result<void, OrderError>;
+    /**
+     * Appends one item occurrence to the order.
+     *
+     * The occurrence ID is supplied by the caller in the input: the Order never
+     * mints occurrence IDs itself. The ID must be unique within the order —
+     * appending an already-used ID is rejected so the `setItems` duplicate-ID
+     * invariant cannot be bypassed through this path. Validation runs before
+     * any mutation — quantity (integer `>= 1`) first, then ID uniqueness — and
+     * failures leave the aggregate unchanged. A successful append refreshes
+     * `updatedAt`. Occurrence IDs carry no product meaning: identical
+     * product/configuration data may coexist under distinct IDs.
+     *
+     * @param input - The item data to add, including the caller-assigned
+     * occurrence ID.
+     *
+     * @returns The created item copy, an `invalid_quantity` error when the
+     * quantity is not a positive integer, or a `duplicate_item_id` error when
+     * the ID is already used within the order.
      */
     addItem(input: OrderItemInput): Result<OrderItem, OrderError>;
     /**
@@ -160,7 +191,6 @@ export declare class Order {
     cancel(): Result<void, OrderError>;
     /**
      * Creates a snapshot of the current state of the order.
-     * Requires the order to have an assigned identifier.
      *
      * @returns A snapshot representing the current state of the order.
      */

package/dist/types/errors/order.d.ts

@@ -8,7 +8,7 @@ import { BaseError } from "@comity/primitives/errors";
  * cross-module failures (`repository_error`, `insufficient_stock`,
  * `product_not_available`, coupon validation) belong to other layers/modules.
  */
-export type OrderErrorReason = "invalid_quantity" | "invalid_item" | "invalid_status_transition" | "shipping_destination_immutable" | "ambiguous_shipping_destination";
+export type OrderErrorReason = "invalid_quantity" | "invalid_item" | "invalid_status_transition" | "shipping_destination_immutable" | "ambiguous_shipping_destination" | "duplicate_item_id";
 /**
  * Order error metadata.
  */

package/dist/types/index.d.ts

@@ -2,7 +2,7 @@ export type { OrderAddressRole, OrderAddressSnapshot } from "./contracts/address
 export type { OrderContact } from "./contracts/contact.js";
 export type { OrderCustomerSnapshot } from "./contracts/customer-snapshot.js";
 export type { OrderItem, OrderProductAttribute, OrderProductOption, OrderProductSnapshot, OrderVariantSnapshot, } from "./contracts/item.js";
-export type { OrderRepository, OrderRepositoryContext, OrderSearchCriteria, OrderSearchResult } from "./contracts/order-repository.js";
+export type { OrderRepository, OrderRepositoryContext, OrderSearchCriteria, OrderSearchResult, } from "./contracts/order-repository.js";
 export type { OrderCreate, OrderData, OrderItemInput, OrderSnapshot, OrderState, OrderStatus, OrderUpdate, } from "./contracts/order.js";
 export type { OrderPaymentSnapshot, OrderPaymentStatus } from "./contracts/payment-snapshot.js";
 export { Order } from "./entities/order.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@comity/order",
-  "version": "0.9.0",
+  "version": "0.9.1",
   "description": "Order domain contracts for Comity commerce modules.",
   "type": "module",
   "private": false,
@@ -84,12 +84,12 @@
   },
   "sideEffects": false,
   "dependencies": {
-    "@comity/pricing": "0.9.0",
-    "@comity/organization": "0.9.0",
-    "@comity/primitives": "0.9.0"
+    "@comity/organization": "0.9.1",
+    "@comity/pricing": "0.9.1",
+    "@comity/primitives": "0.9.1"
   },
   "devDependencies": {
-    "@types/node": "^24.13.4",
+    "@types/node": "^24.19.1",
     "typescript": "^5.9.3"
   },
   "scripts": {