@comity/order 0.9.2 → 0.10.0

package/README.md

@@ -6,7 +6,7 @@ Order domain contracts for Comity commerce modules.
 
 ## Purpose
 
-Defines order contracts and models consumed by commerce and storefront modules. Unifies cart and order into a single domain where a cart is an order in draft status. Provides repositories, item models, and structured errors without binding to a specific commerce backend.
+Defines the generic order commitment contract consumed by commerce and storefront modules. Unifies cart and order into a single domain where a cart is an order in draft status. Provides the aggregate, repositories, line models and structured errors without binding to a specific commerce backend.
 
 ---
 
@@ -14,57 +14,114 @@ Defines order contracts and models consumed by commerce and storefront modules.
 
 This package:
 
-- ✅ defines the order entity with lifecycle and item mutations
-- ✅ defines order, item, and product contracts with status lifecycle
+- ✅ defines the order entity with lifecycle, validating creation, and the single atomic draft-only priced-content operation
+- ✅ defines generic order, line and subject contracts
 - ✅ defines order repository contracts
-- ✅ exposes the `error` subpath for order-specific error types
+- ✅ exposes the `errors` subpath for order-specific error types
 
 This package does NOT:
 
+- ❌ classify the purchased subject (product/asset/licence/service/plan)
+- ❌ own commercial, billing, legal or fiscal buyer facts
+- ❌ manage inventory, price composition or promotion rules
 - ❌ implement checkout orchestration or payment processing
-- ❌ manage inventory or pricing logic
-- ❌ validate coupons or apply promotion rules
 - ❌ render order UI
 
 ---
 
 ## Public API
 
-- `Order` — order entity with lifecycle and item mutations (`setItems`, `addItem`, `removeItem`, `updateItemQuantity`, `submit`, `confirm`, `fulfill`, `cancel`)
+- `Order` — aggregate with lifecycle, `Order.create`, `setPricedContent`, `update`, `changeShippingDestination`, `attachPayment`, `submit`, `confirm`, `fulfill`, `cancel`, `snapshot`
 - `OrderId` — order identifier value object
 - `OrderRepository` — persistence-boundary contract (`getById`, `search`, `save`)
 - `OrderState`, `OrderCreate`, `OrderUpdate`, `OrderSnapshot`, `OrderData`, `OrderStatus` — domain contracts
-- `OrderItem`, `OrderProductSnapshot` (with `OrderVariantSnapshot`, `OrderProductAttribute`, `OrderProductOption`) — embedded item value structures
+- `OrderLine`, `OrderLineSubject` — generic embedded line value structures
+- `OrderCustomerSnapshot` — generic historical buyer fact
 - Error types (`@comity/order/errors`)
 
-The product data in an order is an **owned, immutable snapshot**
-(`OrderProductSnapshot`): it is self-contained and never references the
-catalog after order creation. The application/checkout maps
-`ProductProjection` into the snapshot at creation time.
+A line subject is an owned, immutable, generic snapshot: an opaque
+`reference?`, a required `name` and an optional `description`. It makes the line
+renderable and traceable without any external system, and it never classifies
+the purchase. Commercial taxonomy, catalog identity and commercial attributes
+belong to Commerce.
 
-Price composition is owned by `@comity/pricing`: orders store the immutable
-`Price` value (line item and order level) and do not store modifiers
-separately — modifiers are accessed only through `price.modifiers`.
+Prices are owned by `@comity/pricing`: lines and the order store the immutable
+`PriceRecord`, and `OrderData.currency` is the structural `PriceCurrency`.
+The order derives its own record through `PriceRecord.combine`; it never
+performs pricing arithmetic.
 
 No exhaustive reference; see docs for constraints.
 
 ---
 
+## Migrating from 0.9.3
+
+`0.9.3` is the current published release. `0.10.0` is the target of this
+migration and is **not published yet**. The complete guide is
+`docs/migration.md` in the repository; because the npm tarball contains the
+README and `dist` only, this section is the npm-visible summary.
+
+| `0.9.3`                                                      | `0.10.0`                                                                                            |
+| ------------------------------------------------------------ | --------------------------------------------------------------------------------------------------- |
+| `OrderData.items`                                            | `OrderData.lines`                                                                                   |
+| `OrderItem { id, product, ... }`                             | `OrderLine { lineId, subject, ... }`                                                                |
+| `OrderItemInput` for `addItem`                               | no direct replacement; build `OrderLine` and call `setPricedContent`                                |
+| `OrderProductSnapshot` (SKU/variant/options/attributes)      | `OrderLineSubject { reference?, name, description? }`; commercial detail in Commerce or `line.meta` |
+| `Price` on lines/order                                       | `PriceRecord`                                                                                       |
+| no order currency                                            | required `OrderData.currency: PriceCurrency`                                                        |
+| `new Order(data, id)` for creation                           | `Order.create(data, id) → Result`; constructor hydrates only                                        |
+| `setItems` / `addItem` / `removeItem` / `updateItemQuantity` | `setPricedContent(lines, adjustments)`                                                              |
+| `update({ price })`                                          | `update({ meta })` only                                                                             |
+| six error reasons                                            | ten reasons (four additions; no `invalid_buyer`)                                                    |
+
+Key steps:
+
+1. Map each legacy line to `OrderLine`: `id` → `lineId`, `product` → `subject`.
+   Put SKU/variant/options/attributes in a Commerce-owned type or `line.meta`;
+   the generic subject has no commercial taxonomy.
+2. Create every line and order price as a `PriceRecord`. Use
+   `PriceRecord.from(price)` for a computed line price and
+   `PriceRecord.combine(lineRecords, adjustments)` for the order record.
+3. Supply `currency` from `currentPriceCurrency(code)`.
+4. Replace all priced-content mutation with the atomic, draft-only
+   `setPricedContent`; `update` changes metadata only.
+5. Handle `Result` values from `create`, `setPricedContent`, `submit`,
+   `update` and `attachPayment`; the four new reasons are
+   `currency_mismatch`, `price_incoherent`, `commitment_immutable` and
+   `payment_fact_conflict`.
+6. Persist `PriceRecord.toPlain(record)` and hydrate with
+   `PriceRecord.restore(plain)`; never `JSON.stringify` a live record. Do not
+   recompute or reprice on load.
+
+An empty order requires the canonical zero `PriceRecord` (`0` subtotal, `0`
+total, no modifiers, current format/semantics, order currency).
+`combine([])` is forbidden and `setPricedContent([], ...)` is rejected; clearing
+all priced content is not supported.
+
+The five-kind subject union, `priceBasis`, `term`, `invalid_buyer` and the
+intermediate line mutators were never part of published `0.9.3`; consumers
+migrating from `0.9.3` must not add them just to remove them.
+
+---
+
 ## Documentation
 
 - docs/overview.md
 - docs/conventions.md
+- docs/design.md
+- docs/migration.md
 
 ---
 
 ## Related Packages
 
-- @comity/pricing — price and money models (`order → pricing`, registered in ADR-008)
-- @comity/catalog — source of `ProductProjection`, mapped by the application into owned `OrderProductSnapshot` (no direct dependency)
+- @comity/pricing — `PriceRecord`/`PriceCurrency` and `combine` (`order → pricing`, registered in ADR-008)
+- @comity/catalog — source of subject data, mapped by the application into the generic `OrderLineSubject` (no direct dependency)
 - @comity/kernel — module lifecycle runtime
 
 ---
 
 ## Status
 
-Stable
+`0.9.3` is the current published release. `0.10.0` — the breaking contract in
+this README — is in preparation and is **not published yet**.

package/dist/contracts/customer-snapshot.d.ts

@@ -6,11 +6,11 @@ import type { OrderContact } from "./contact.js";
  * A plain, owned representation of the customer as it was at purchase time.
  * It is NOT `Customer` from `@comity/customer` and it is not a reference to
  * the customer module: once the order is created it MUST NOT depend on the
- * customer for its content. Historical order rendering, customer support, and
- * invoice generation rely exclusively on this record.
+ * customer for its content.
  *
- * Only identity and display facts are preserved. Operational customer state
- * (preferences, lifecycle metadata) is not copied.
+ * Only generic counterparty facts are preserved. Commercial, billing, legal
+ * and fiscal facts (party kind, legal name, tax identifier) belong to
+ * Commerce; they are never part of the generic Order contract.
  */
 export interface OrderCustomerSnapshot {
     /** Reference to the customer identifier, if still known. */

package/dist/contracts/line.d.ts

@@ -0,0 +1,51 @@
+import type { PriceRecord } from "@comity/pricing";
+/**
+ * Owned, immutable snapshot of what a line bought.
+ *
+ * Generic by construction: the Order preserves a displayable, traceable
+ * description of the purchased subject and never classifies it. Commercial
+ * taxonomy (product/asset/licence/service/plan), catalog identity, variants
+ * and options belong to Commerce.
+ *
+ * Guarantees:
+ * - `reference` is opaque and caller-owned; the Order never parses, resolves
+ *   or compares it. It exists so a reader can trace the line back to its
+ *   source when that is still known.
+ * - `name` (required) and optional `description` make the line renderable
+ *   without any external system.
+ * - The value is an owned snapshot, defensively copied on creation and on
+ *   `snapshot()`.
+ * - Only JSON-representable strings are used.
+ */
+export interface OrderLineSubject {
+    /** Opaque, application-owned reference to what was bought, when known. */
+    readonly reference?: string;
+    /** Human-readable label. */
+    readonly name: string;
+    /** Optional additional display text. */
+    readonly description?: string;
+}
+/**
+ * A committed line: an occurrence within the order.
+ *
+ * Embedded value structure: identity only as `lineId`, no lifecycle, no
+ * repository. The full line price is a `PriceRecord` owned by
+ * `@comity/pricing`; the Order stores it and never recomputes it.
+ */
+export interface OrderLine {
+    /**
+     * Caller-assigned technical key for one occurrence within the order.
+     *
+     * The key identifies the occurrence, not the subject, is unique within the
+     * order, and is generated outside the Order.
+     */
+    readonly lineId: string;
+    /** Self-contained snapshot of what was bought. */
+    readonly subject: OrderLineSubject;
+    /** Integer quantity, `>= 1`. */
+    readonly quantity: number;
+    /** Frozen committed price for the entire line. */
+    readonly price: PriceRecord;
+    /** Non-semantic metadata; the domain never reads it. */
+    readonly meta?: Record<string, unknown>;
+}

package/dist/contracts/line.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=line.js.map

package/dist/contracts/order.d.ts

@@ -1,16 +1,16 @@
-import type { Price } from "@comity/pricing";
+import type { PriceCurrency, PriceRecord } from "@comity/pricing";
 import type { Instant } from "@comity/primitives/time";
 import type { OrderId } from "../value-objects/order-id.js";
 import type { ChannelId } from "@comity/organization";
 import type { OrderAddressSnapshot } from "./address-snapshot.js";
 import type { OrderCustomerSnapshot } from "./customer-snapshot.js";
-import type { OrderItem, OrderProductSnapshot } from "./item.js";
+import type { OrderLine } from "./line.js";
 import type { OrderPaymentSnapshot } from "./payment-snapshot.js";
 /**
  * Order status.
  *
- * An order starts in {@link OrderStatus."draft"} and progresses through a linear lifecycle.
- * Each transition is explicit; the status cannot move backwards.
+ * An order starts in `draft` and progresses through a linear lifecycle. Each
+ * transition is explicit; the status cannot move backwards.
  *
  * Transitions:
  * - `draft` → `pending` (submit)
@@ -19,16 +19,35 @@ import type { OrderPaymentSnapshot } from "./payment-snapshot.js";
  * - `draft | pending | confirmed` → `cancelled` (cancel)
  *
  * `fulfilled` and `cancelled` are terminal.
+ *
+ * - `draft`: terms are being assembled; nothing is owed.
+ * - `pending`: submitted for acceptance.
+ * - `confirmed`: terms accepted; delivery obligations exist.
+ * - `fulfilled`: every delivery obligation has been discharged.
+ * - `cancelled`: the commitment is terminated.
  */
 export type OrderStatus = "draft" | "pending" | "confirmed" | "fulfilled" | "cancelled";
 /**
  * Business data of an order, independent of identity and lifecycle metadata.
  */
 export interface OrderData {
-    /** Order items. */
-    readonly items: ReadonlyArray<OrderItem>;
-    /** Order price. `@comity/pricing` owns price composition: modifiers are accessed through `price.modifiers`. */
-    readonly price: Price;
+    /** Committed lines. */
+    readonly lines: ReadonlyArray<OrderLine>;
+    /**
+     * Frozen order-level price composed by `@comity/pricing`.
+     *
+     * The aggregate derives `price.subtotal` (the sum of the line totals) and
+     * `price.total` (after order-level adjustments) through
+     * `PriceRecord.combine`; it never performs pricing arithmetic itself (O-7).
+     */
+    readonly price: PriceRecord;
+    /**
+     * Monetary unit of the order and of every line and amount in `price`.
+     *
+     * A structural `PriceCurrency`, recorded verbatim. O-6 compares `(code,
+     * exponent)` exactly.
+     */
+    readonly currency: PriceCurrency;
     /** The commercial channel through which the order was placed. */
     readonly channelId: ChannelId;
     /** Historical buyer fact, captured at purchase time. */
@@ -52,6 +71,14 @@ export interface OrderState extends OrderData {
     readonly createdAt: Instant;
     /** Last update timestamp. */
     readonly updatedAt: Instant;
+    /**
+     * Persisted-version token.
+     *
+     * `0` while the aggregate has never been persisted; restored verbatim on
+     * hydration. The aggregate NEVER increments it — the repository does, once
+     * per successful save. ADVISORY until ADR-029 is accepted.
+     */
+    readonly version: number;
 }
 /**
  * Immutable point-in-time snapshot of an existing order.
@@ -61,14 +88,13 @@ export type OrderSnapshot = Readonly<OrderState & {
     readonly capturedAt: Instant;
 }>;
 /**
- * Data required to create a new order.
+ * Data required to create or hydrate 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).
+ * The identifier is supplied separately (`Order.create(data, id)` for
+ * creation, the constructor `id` argument for hydration): the caller owns ID
+ * generation. Creation ignores the lifecycle fields and always produces a
+ * `draft` order with `version: 0`; hydration restores `status`, timestamps
+ * and `version` verbatim (ADR-001).
  */
 export type OrderCreate = OrderData & {
     /** Order lifecycle status, used to restore persisted state during hydration. */
@@ -77,44 +103,18 @@ export type OrderCreate = OrderData & {
     readonly createdAt?: Instant;
     /** The timestamp when the order was last updated. */
     readonly updatedAt?: Instant;
+    /** Persisted-version token restored during hydration. Defaults to `0`. */
+    readonly version?: number;
 };
 /**
  * Partial mutation data for an order.
  *
- * Status transitions are not part of the update contract: they must pass
+ * Only non-semantic metadata is updatable here. Status transitions pass
  * through the entity's domain methods (`submit`, `confirm`, `fulfill`,
- * `cancel`). Items are mutated through `setItems`/`addItem`/`removeItem`/
- * `updateItemQuantity`, which protect the order's invariants.
+ * `cancel`); priced content is replaced atomically through
+ * `setPricedContent`.
  */
 export interface OrderUpdate {
-    /** Order price. Modifiers are updated through `price`; see `@comity/pricing`. */
-    readonly price?: Price;
     /** Custom metadata. */
     readonly meta?: Record<string, unknown>;
 }
-/**
- * Input for adding an item to the order.
- *
- * The item price is supplied by the caller as a complete `Price` value:
- * price computation belongs to `@comity/pricing` orchestration, not to the
- * Order aggregate. The product data is an owned snapshot mapped by the caller
- * 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. */
-    readonly quantity: number;
-    /** Full line price (subtotal, applied modifiers, total). */
-    readonly price: Price;
-}

package/dist/entities/order.d.ts

@@ -1,28 +1,58 @@
-import type { Price } from "@comity/pricing";
+import type { PriceCurrency, PriceModifier } from "@comity/pricing";
 import type { Result } from "@comity/primitives/result";
 import type { OrderAddressSnapshot } from "../contracts/address-snapshot.js";
 import type { OrderCustomerSnapshot } from "../contracts/customer-snapshot.js";
-import type { OrderItem } from "../contracts/item.js";
-import type { OrderCreate, OrderItemInput, OrderSnapshot, OrderStatus, OrderUpdate } from "../contracts/order.js";
+import type { OrderLine } from "../contracts/line.js";
+import type { OrderCreate, OrderData, OrderSnapshot, OrderStatus, OrderUpdate } from "../contracts/order.js";
 import type { OrderPaymentSnapshot } from "../contracts/payment-snapshot.js";
 import type { OrderId } from "../value-objects/order-id.js";
 import type { ChannelId } from "@comity/organization";
+import { PriceRecord } from "@comity/pricing";
 import { Instant } from "@comity/primitives/time";
 import { OrderError } from "../errors/order.js";
 /**
  * Represents an order entity in the system.
  *
  * @remark
- * An order is a lifecycle aggregate: it owns its status transitions, its line
- * items, the applied pricing result, and its historical facts (buyer,
- * addresses, payment). It does not validate coupons, does not know promotion
- * rules, and does not orchestrate external services — those concerns belong
- * to `@comity/pricing`, other Core Modules, and application/domain services.
+ * An order is a lifecycle aggregate: it owns its status transitions, its
+ * committed lines, the applied pricing result, its advisory version token, and
+ * its historical facts (buyer, addresses, payments). It does not validate
+ * coupons, does not know promotion rules, and does not orchestrate external
+ * services — those concerns belong to `@comity/pricing`, other Core Modules,
+ * and application/domain services.
+ *
+ * @remark
+ * The version token is ADVISORY: the aggregate carries it and never increments
+ * it. Optimistic concurrency belongs to the repository (Comity precondition
+ * ADR-029) and is not implemented here.
  */
 export declare class Order {
     #private;
     /**
-     * @param fields - The fields used to create or hydrate the order.
+     * Creates a new, validated order (ADR-001, ADR-032 AM-5a).
+     *
+     * Applies the invariants decidable from creation data — O-1 (integer
+     * quantity `>= 1`), O-2 (unique line ids), O-6 (one currency on `(code,
+     * exponent)`), O-7 (exact `PriceRecord` commitment equality against
+     * `combine`) and O-9 (supplied payment facts) — before any state exists. An
+     * empty order is accepted only with the canonical zero record. A new order
+     * is `draft` with `version: 0`.
+     *
+     * @param data - The business data of the order.
+     * @param id - The unique identifier of the order, supplied by the caller.
+     *
+     * @returns The order, or `invalid_quantity` / `duplicate_item_id` /
+     * `currency_mismatch` / `price_incoherent` / `payment_fact_conflict`.
+     */
+    static create(data: OrderData, id: OrderId): Result<Order, OrderError>;
+    /**
+     * Hydrates an existing order (ADR-001).
+     *
+     * The constructor performs NO validation: it restores persisted state
+     * verbatim, including `version`. Use {@link Order.create} for the validating
+     * creation path.
+     *
+     * @param fields - The persisted fields of the order.
      * @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.
@@ -41,13 +71,17 @@ export declare class Order {
      */
     get status(): OrderStatus;
     /**
-     * @returns The order items.
+     * @returns The committed lines.
      */
-    get items(): ReadonlyArray<OrderItem>;
+    get lines(): ReadonlyArray<OrderLine>;
     /**
      * @returns The order price.
      */
-    get price(): Price;
+    get price(): PriceRecord;
+    /**
+     * @returns The monetary unit of the order and of every amount it stores.
+     */
+    get currency(): PriceCurrency;
     /**
      * @returns The historical buyer fact, if captured.
      */
@@ -73,14 +107,24 @@ export declare class Order {
      */
     get updatedAt(): Instant;
     /**
-     * Updates the applied pricing result and metadata.
+     * Returns the persisted-version token (read-only; advisory, never
+     * incremented by the aggregate).
+     *
+     * @returns The version token: `0` while unpersisted.
+     */
+    get version(): number;
+    /**
+     * Updates non-semantic metadata.
      *
-     * Status transitions are performed through the domain methods; items are
-     * mutated through `setItems`/`addItem`/`removeItem`/`updateItemQuantity`.
+     * Status transitions pass through the domain methods; priced content is
+     * replaced atomically through {@link setPricedContent}. Metadata is
+     * updatable in any status.
      *
      * @param changes - The changes to apply to the order.
+     *
+     * @returns Success.
      */
-    update(changes: OrderUpdate): void;
+    update(changes: OrderUpdate): Result<void, OrderError>;
     /**
      * Appends a historical payment fact to the order.
      *
@@ -89,20 +133,28 @@ export declare class Order {
      * This records a historical fact only: it performs no payment logic, knows
      * no payment module, and does not coordinate, authorize, or capture.
      *
+     * Facts dedupe on `(paymentId, status)`: an identical repeat is an idempotent
+     * no-op that touches nothing; the same key with a different amount, and an
+     * illegal progression for a known `paymentId`, are conflicts. A fact without
+     * a `paymentId` is always appended.
+     *
      * @param snapshot - The payment fact to record.
+     *
+     * @returns Success (including an idempotent no-op), or
+     * `payment_fact_conflict`.
      */
-    attachPayment(snapshot: OrderPaymentSnapshot): void;
+    attachPayment(snapshot: OrderPaymentSnapshot): Result<void, OrderError>;
     /**
      * Replaces the shipping destination of the order.
      *
      * Allowed only while the order is `draft | pending`; in later statuses the
-     * shipping destination is immutable (ADR-018). The order must hold exactly
-     * one shipping address fact; a missing or ambiguous one is an error rather
-     * than a guess. A structurally identical destination is a successful no-op
-     * that leaves timestamps untouched. The operation never reaches the generic
-     * `update()` path, never touches billing, customer, item, price, or payment
-     * facts, and records no history: the aggregate retains only the current
-     * shipping destination.
+     * shipping destination is immutable. The order must hold exactly one shipping
+     * address fact; a missing or ambiguous one is an error rather than a guess. A
+     * structurally identical destination is a successful no-op that leaves
+     * timestamps untouched. The operation never reaches the generic `update()`
+     * path, never touches billing, customer, line, price, or payment facts, and
+     * records no history: the aggregate retains only the current shipping
+     * destination.
      *
      * @param destination - The replacement shipping destination. The address
      * role is owned by this operation and is always stored as `"shipping"`.
@@ -111,63 +163,31 @@ export declare class Order {
      */
     changeShippingDestination(destination: Omit<OrderAddressSnapshot, "role">): Result<void, OrderError>;
     /**
-     * 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: 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>;
-    /**
-     * Removes an item from the order.
-     *
-     * @param itemId - The order item ID.
+     * Atomically replaces the priced content of the order.
      *
-     * @returns A result indicating the success or failure of the removal.
-     */
-    removeItem(itemId: string): Result<void, OrderError>;
-    /**
-     * Updates the quantity of an order item.
+     * `lines` and `adjustments` are the complete desired priced content. The
+     * order-level `PriceRecord` is derived with `PriceRecord.combine`; line
+     * modifiers are provenance and are never reapplied or copied. All validation
+     * happens before any state changes, so a failure leaves the aggregate
+     * completely unchanged. Allowed only while the order is `draft`.
      *
-     * @param itemId - The order item ID.
-     * @param quantity - The new quantity.
+     * @param lines - The complete desired line collection; must be non-empty.
+     * @param adjustments - The order-level adjustments, in application order.
      *
-     * @returns A result indicating the success or failure of the update.
+     * @returns Success, or `commitment_immutable` outside `draft` /
+     * `currency_mismatch` / `price_incoherent` / `invalid_quantity` /
+     * `duplicate_item_id`.
      */
-    updateItemQuantity(itemId: string, quantity: number): Result<void, OrderError>;
+    setPricedContent(lines: ReadonlyArray<OrderLine>, adjustments: ReadonlyArray<PriceModifier>): Result<void, OrderError>;
     /**
      * Submits the order: `draft` → `pending`.
      *
+     * Before leaving `draft`, re-derives the order-level record from the stored
+     * line records and the stored order-level modifiers and requires exact
+     * commitment equality (ADR-032 AM-5c). An empty draft is validated against
+     * the canonical zero record. Reconciliation uses only `PriceRecord.combine`,
+     * never `verify()` and never an aggregate-side `PriceRecord.from()`.
+     *
      * @returns A result indicating the success or failure of the transition.
      */
     submit(): Result<void, OrderError>;
@@ -186,6 +206,9 @@ export declare class Order {
     /**
      * Cancels the order: `draft | pending | confirmed` → `cancelled`.
      *
+     * Takes no argument: the Order is business-model neutral and the application
+     * records why the commitment ended.
+     *
      * @returns A result indicating the success or failure of the transition.
      */
     cancel(): Result<void, OrderError>;