--- id: CAP-COM-FUL-014 title: Record goods leaving with a carrier or collector feature: FEAT-COM-FUL-03 product_area: commerce module: fulfillment revision: 1 status: draft product_intent: proposed implementation_evidence: observed supersedes: - CAP-COM-SHP-014 - CAP-COM-SHP-017 - CAP-COM-SHP-024 - CAP-COM-INV-030 source_sha: services-commerce: c8b66a98e2490617aec38ba5c8165dd9bd0a8f9b intent_sources: - >- services-commerce:docs/migrations/shipping/README.md#D-P8S-14 (decision L, Andrew 2026-10-18) purpose: >- Warehouse handover aligns physical departure with delivery, stock and order records. outcomes: - 'Physical departure connects stock, delivery and cost processing.' - >- Cancellation contention prevents the same unit from both shipping and cancelling. concepts: - CON-COM-FUL-004 - CON-COM-FUL-005 - CON-COM-FUL-001 actors: - ACT-COM-010 surfaces: - api preconditions: [] postconditions: [] permissions: - key: commerce.shipments.handoff where_checked: api scope: tenant - key: commerce.shipments.handover where_checked: api scope: tenant rules: - id: BR-CAP-COM-FUL-014-01 statement: >- Carrier handoff atomically advances a manifested shipment's whole line quantities, ships allocations, reduces on-hand through shipment movements, completes unit obligations, invokes cost relief and updates order shipping quantities and summary. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#hands off: the line handed to the carrier with its whole quantity shipped, the units shipped in the ledger, one shipment movement of minus three on the item, three fewer on hand origin: none - id: BR-CAP-COM-FUL-014-02 statement: >- Handoff rejects units without register authorization, moves no stock and records a refusal finding and shipment-history entry. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#refuses units_not_authorized, naming the obligation still pending, and moves nothing: the unit committed, nothing shipped, the shipment still manifested origin: none - id: BR-CAP-COM-FUL-014-03 statement: >- Only manifested shipments accept carrier handoff, and repeated handoff is rejected and recorded. kind: validation enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#refuses a second handoff of the same shipment (not manifested any more) and records the refusal origin: none - id: BR-CAP-COM-FUL-014-04 statement: >- Cancellation fences the shipment line's entire unit range, causing handoff to reject the shipment without movement and require parcel removal. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#refuses the handoff shipment_cancelled_pull_package, naming the fenced line, and moves nothing origin: none - id: BR-CAP-COM-FUL-014-05 statement: >- Shipment-line locking determines whether cancellation or handoff wins a race, and goods already handed over require a return. kind: invariant enforced_at: - service - database must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#lets the handoff commit, and the cancellation that waited finds the line already handed off: refused, nothing fenced origin: none - id: BR-CAP-COM-FUL-014-06 statement: >- Committed cancellation cancels fenced lines, removes shipment stamps while retaining picked order allocations, voids labels on parcels carrying no retained lines and pulls those parcels so retained units can use a new shipment. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#cancels the fenced line at the cancel step: the units unstamped (still the order’s, picked), the label voided and the package pulled, the shipment cancelled origin: none - id: BR-CAP-COM-FUL-014-07 statement: >- Counter handover of a packed pickup records the collector and applies the same stock, obligation, cost-relief and order-quantity changes as carrier handoff. kind: lifecycle enforced_at: - service must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#moves the stock as the handoff does: the units shipped, one shipment movement of minus two (reason handover), two fewer on hand origin: >- Decision L, Andrew 2026-10-18 ("add it now"): services-commerce:docs/migrations/shipping/README.md#D-P8S-14 - id: BR-CAP-COM-FUL-014-08 statement: >- Counter handover rejects missing collector identity, carrier shipments, shipments no longer packed and cancellation-fenced lines. kind: validation enforced_at: - api - service must_prove: true provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#refuses the handover of a pick-up whose line the cancellation fenced, shipment_cancelled_pull_package, and moves nothing origin: >- Decision L, Andrew 2026-10-18 ("add it now"): services-commerce:docs/migrations/shipping/README.md#D-P8S-14 - id: BR-CAP-COM-FUL-014-09 statement: >- Carrier handoff requires its handoff permission, while counter handover requires sensitive administrator authority. kind: permission enforced_at: - api must_prove: true provenance: observed source: 'services-commerce:modules/shipping/aws/api/shipping.routes.ts' origin: >- Decision L, Andrew 2026-10-18 ("add it now"): services-commerce:docs/migrations/shipping/README.md#D-P8S-14 - id: BR-CAP-COM-FUL-014-10 statement: >- Handoff invokes the selected cost-relief provider within its transaction; the fixture permits deferred relief and the running layers provider determines actual cost relief. kind: policy enforced_at: - service must_prove: false provenance: observed source: >- services-commerce:modules/shipping/services/cost/cost-relief-port.ts:commerceCostReliefPort origin: >- Decision O, Andrew 2026-10-18 (as built, not contested): services-commerce:docs/migrations/shipping/README.md#Section 9 walkthrough scenarios: - id: SC-CAP-COM-FUL-014-01 given: A manifested shipment carries three shirts in two parcels. when: Confirm departure with the carrier. then: >- Stock decreases by three, obligations complete, deferred cost facts are emitted and shipped quantities update. provenance: test source: >- services-commerce:modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js#completes every unit’s obligation through the register (the allocation as the record), and emits one deferred cost relief fact per item - id: SC-CAP-COM-FUL-014-02 given: A pickup shipment is packed for collection. when: Record the collecting buyer and confirm handover. then: The line records shipment and the order's shipping work becomes complete. provenance: test source: >- services-commerce:modules/shipping/tests/e2e/shipping.e2e.spec.js#hands the pick-up over through the route: collected by the buyer, the line shipped, the order’s shipping complete edge_cases: [] constraints: [] depends_on: - CAP-COM-FUL-012 - CAP-COM-FUL-004 related: - CAP-COM-FUL-018 journeys: - JNY-COM-FUL-003 open_questions: - OQ-COM-FUL-002 evidence: - repository: services-commerce paths: - >- modules/shipping/tests/integration/services/fulfillment/shipping-flow.integration.spec.js - modules/shipping/aws/api/shipping.routes.ts - modules/shipping/services/cost/cost-relief-port.ts controls: [TC-AZ-001, TC-AZ-002, TC-AZ-003, TC-AZ-004, TC-AZ-005, TC-AZ-006, TC-TEN-001, TC-TEN-002, TC-TEN-003, TC-CRY-001, TC-DAT-001, TC-DAT-002, TC-DAT-003, TC-DAT-004, TC-LOG-001, TC-LOG-002, TC-LOG-003, TC-LOG-004, TC-LOG-005, TC-PI-001, TC-PI-002, TC-PI-003, TC-PI-005, TC-VEN-001, TC-VEN-002, TC-VEN-003, TC-PRV-001, TC-PRV-002] --- # Record goods leaving with a carrier or collector ## Purpose Warehouse handover aligns physical departure with delivery, stock and order records. ## How It Works Staff confirm carrier handoff after manifesting or pickup handover after packing. Commerce checks the shipment's units against delivery authorization and cancellation fencing. The successful step changes the stock ledger, obligations and order shipping view together. It also calls the configured cost-relief provider within that transaction. A refusal records the problem without moving units. Collection additionally records the person receiving the goods. The product should give warehouse staff a visible departure confirmation and an actionable refusal explanation. ## Relationships - Prepare an order's goods for dispatch supplies or consumes related delivery records. - Carry authorized work to its delivering application supplies or consumes related delivery records. - Allocate stock and explain what buyers can obtain supplies or consumes related delivery records.