This is an internal working record, not an everyday instruction. It was written while the system was being rebuilt, for whoever maintains it. If you are here to do today's work, use the everyday documents instead: Procedures · Processes · Runbooks · The working day, step by step

MK Order-First Core Sequence, State And Migration Diagrams

• Status: SOURCE-RECONCILED DIAGRAM INPUT / OWNER REVIEW REQUIRED
• Scope: Commercial Agreement, Inbound Purchase, Outbound Sales and Booking
• Rebuild packet: MK_ORDER_FIRST_CORE_CAPABILITY_REBUILD_PACKET.md
• Process assembly: MK_ORDER_FIRST_CORE_RECONCILIATION.md
• Operator Runbook: MK_COMMERCIAL_INBOUND_OUTBOUND_BOOKING_OPERATOR_RUNBOOK.md
• Purpose: preserve current child boundaries, partial results and target migration order in editable form

A diagram explains sequence or ownership. It does not override the owning Process, source or accepted policy.

---

1. MK Order-First Value Stream

flowchart LR
    CP[Commercial Purchase]
    IN[Inbound Purchase]
    SCALEIN[Optional Scale Receipt]
    LOT[Inventory Lot]
    ALLOC[Allocation]
    CS[Commercial Sales]
    OUT[Outbound Sales]
    BK[Optional Booking]
    PHYS[Optional Scale / Delivery]
    DOCS[Optional Packing / Cost / Outputs]
    CLOSE[Order-First Reconciliation]

    CP --> IN
    IN --> SCALEIN
    IN --> LOT
    SCALEIN --> LOT
    LOT --> ALLOC
    CS --> OUT
    OUT --> BK
    ALLOC --> OUT
    OUT --> PHYS
    BK --> DOCS
    PHYS --> DOCS
    CP --> CLOSE
    CS --> CLOSE
    IN --> CLOSE
    LOT --> CLOSE
    ALLOC --> CLOSE
    OUT --> CLOSE
    BK --> CLOSE
    PHYS --> CLOSE
    DOCS --> CLOSE

Optional children are entered only when the actual commercial/physical/output work requires them.

---

2. Commercial Purchase/Sales Relation

sequenceDiagram
    actor Operator
    participant UI as Commercial Workspace
    participant App as Commercial Application
    database DB as Commercial Tables

    Operator->>UI: Search existing Purchase and Sales agreements
    UI->>App: Query exact number/reference/counterparty
    App->>DB: Read same-tenant active agreements and lines
    DB-->>UI: Candidate details
    Operator->>UI: Select Purchase and Sales relation
    UI->>App: RelateCommercialAgreements(Purchase, Sales, version)
    App->>DB: Validate opposite type, non-self, tenant, cardinality policy
    App->>DB: Write canonical relation
    DB-->>App: Two-sided readback
    App-->>UI: Purchase link + Sales reverse projection

---

3. Commercial Update And Execution Guard

flowchart TB
    Edit[Operator submits Commercial update]
    Read[Read header, lines and all execution references]
    Executed{Any accepted execution reference?}
    Header[Apply accepted header-only fields]
    Lines[Apply explicit line command]
    Block[Reject type/line/delete action]
    Save[Conditional transaction]
    Reread[Exact detail and execution readback]

    Edit --> Read --> Executed
    Executed -- No --> Lines --> Save --> Reread
    Executed -- Yes, header field allowed --> Header --> Save
    Executed -- Yes, protected field/line/delete --> Block --> Reread

The target must include item-level execution references, not only header-level links.

---

4. Commercial Status And Execution Utilization

flowchart LR
    Manual[Manual agreement status]
    Execution[Execution references and quantities]
    Status[OPEN / PARTIAL / FULFILLED / CANCELLED]
    Utilization[UNREFERENCED / PARTIAL / FULL / CONFLICT]
    Review[Operator reconciliation]

    Manual --> Status
    Execution --> Utilization
    Status --> Review
    Utilization --> Review

Manual status and derived utilization remain separate until an accepted automatic policy exists.

---

5. Inbound Scheduled Save

sequenceDiagram
    actor Receiving
    participant UI as Inbound Workspace
    participant App as Inbound Application
    database DB as Order Tables

    Receiving->>UI: Edit header and complete item set
    UI->>App: AtomicSaveInboundPurchase(version, items, deletions)
    App->>DB: Read current order/items and blockers
    App->>DB: Begin transaction
    App->>DB: Update header
    App->>DB: Add/update eligible scheduled items
    App->>DB: Delete eligible staged items
    App->>DB: Commit
    App->>DB: Reread exact header/items/bridge projection
    App-->>UI: One local result

Compatibility callers that still use separate header/item routes require separate characterization and caller-zero.

---

6. Physical Scale Receipt

sequenceDiagram
    actor ScaleOperator as Scale Operator
    actor Receiving as Receiving Operator
    participant Scale as Scale Owner
    participant Inbound as Inbound Receipt Owner
    database DB as MySQL
    participant Inventory as Inventory Owner

    ScaleOperator->>Scale: Check in / record Gross
    Scale->>DB: Persist Scale evidence
    ScaleOperator->>Scale: Check out / record Tare
    Scale->>DB: Persist completed ticket
    Scale-->>Receiving: Ticket completed; receipt not yet finalized
    Receiving->>Inbound: FinalizeInboundReceiptFromScale(order, ticket, distribution)
    Inbound->>DB: Reread ticket/order/items and prior finalization
    Inbound->>DB: Begin receipt transaction
    Inbound->>DB: Update item and transload receipt state
    Inbound->>Inventory: Materialize exact source lot(s)
    Inventory->>DB: Persist lot/source/balance
    Inbound->>DB: Commit
    Inbound->>DB: Reread ticket/order/items/transload/lot
    Inbound-->>Receiving: Receipt finalized with exact IDs

Scale checkout != receipt finalize != lot materialization until exact reread.

---

7. Scale Checkout Complete, Finalize Failed

sequenceDiagram
    actor Receiving
    participant Scale as Scale Owner
    participant Inbound as Inbound Owner
    database DB

    Scale-->>Receiving: Completed ticket exists
    Receiving->>Inbound: Finalize receipt
    Inbound->>DB: Begin transaction
    Inbound->>DB: Update item/transload/lot work
    DB--xInbound: Cardinality or integrity error
    Inbound->>DB: Roll back accepted receipt transaction
    Inbound-->>Receiving: FINALIZE_FAILED; ticket preserved
    Receiving->>Inbound: Reread receipt reconciliation
    Inbound->>DB: Read ticket + item + transload + lot
    alt receipt absent and inputs corrected
        Receiving->>Inbound: Retry finalize only
    else partial/conflicting state exists
        Inbound-->>Receiving: Stop and escalate exact IDs
    end

Never repeat Scale checkout to repair a finalize-only failure.

---

8. Complete Without Scale

flowchart TB
    Start[Eligible Inbound Purchase]
    Policy[Evaluate profile/config and current progress]
    Valid{No-scale conditions satisfied?}
    Reject[Reject with exact blocker]
    Commit[One receipt transaction]
    Items[Promote item receipt state]
    Transload[Update execution bridge]
    Lot[Materialize exact source lot]
    Branch[Return navigation intent]
    Readback[Order/items/transload/lot readback]

    Start --> Policy --> Valid
    Valid -- No --> Reject
    Valid -- Yes --> Commit --> Items --> Transload --> Lot --> Readback --> Branch

The returned branch is not durable unless a separate accepted intent/event contract is introduced.

---

9. Inbound Receipt State

stateDiagram-v2
    [*] --> SCHEDULED_ONLY
    SCHEDULED_ONLY --> SCALE_IN_PROGRESS: Gross or Tare work begins
    SCALE_IN_PROGRESS --> SCALE_CHECKED_OUT_FINALIZE_PENDING: Ticket completed
    SCALE_CHECKED_OUT_FINALIZE_PENDING --> RECEIPT_FINALIZED: Inbound finalize commits
    SCHEDULED_ONLY --> RECEIPT_FINALIZED: Eligible no-scale completion
    RECEIPT_FINALIZED --> LOT_MATERIALIZED: Exact source lot verified
    SCALE_CHECKED_OUT_FINALIZE_PENDING --> RECEIPT_CONFLICT: Finalize fails/unknown
    RECEIPT_FINALIZED --> RECEIPT_CONFLICT: Item/transload/lot disagree

---

10. Received Lot To Outbound Allocation

sequenceDiagram
    actor InventoryOperator as Inventory Operator
    participant Lot as Inventory Lot Owner
    participant Allocation as Allocation Owner
    participant Outbound as Outbound Demand Owner
    database DB

    InventoryOperator->>Lot: Query eligible lots and current balances
    Lot->>DB: Read active lot/source/UOM/quantity/weight
    InventoryOperator->>Outbound: Query exact demand item
    Outbound->>DB: Read requested demand and existing allocations
    InventoryOperator->>Allocation: Allocate lot to demand
    Allocation->>DB: Conditional balance and demand validation
    Allocation->>DB: Persist allocation and update balance/ledger
    Allocation->>DB: Commit
    Allocation->>DB: Reread allocation + lot balance + demand projection
    Allocation-->>InventoryOperator: Exact result

Direct Outbound Save does not perform this sequence.

---

11. Outbound Scheduled Save

sequenceDiagram
    actor Shipping
    participant UI as Outbound Workspace
    participant App as Outbound Sales Application
    database DB

    Shipping->>UI: Enter Sales order and requested items
    UI->>App: Create/AtomicSaveOutboundSales
    App->>DB: Validate Commercial/Booking/reference scope
    App->>DB: Begin transaction
    App->>DB: Write header/items and accepted bridge metadata
    App->>DB: Commit
    App->>DB: Reread order/items/bridge/allocation projection
    App-->>UI: Requested demand + explicit UNALLOCATED/UNMAPPED state

---

12. Outbound Allocation-Aware Correction

flowchart TB
    Edit[Edit progressed outbound item]
    Read[Read item, allocations, lots, Scale/Delivery/Packing/Cost]
    Allocated{Allocation exists?}
    Safe{Requested field is safe metadata?}
    Direct[Apply conditional metadata update]
    Reconcile[Use allocation-aware correction/unallocate command]
    Block[Reject normal edit with child IDs]
    Reread[Exact child readback]

    Edit --> Read --> Allocated
    Allocated -- No --> Safe
    Allocated -- Yes --> Reconcile --> Reread
    Safe -- Yes --> Direct --> Reread
    Safe -- No --> Block --> Reread

---

13. Outbound To Booking Link

sequenceDiagram
    actor Shipping
    participant Outbound as Outbound Owner
    participant Booking as Booking Owner
    database DB

    Shipping->>Outbound: Select exact Outbound Sales
    Shipping->>Booking: Select/create exact Booking
    Shipping->>Outbound: LinkOutboundBooking(order, booking, versions)
    Outbound->>DB: Validate both sides, tenant, class and policy
    Outbound->>DB: Write accepted canonical relation
    DB-->>Outbound: Forward/reverse readback
    Outbound-->>Shipping: Link result and bridge warnings

Delete/correction must return the exact disposition of both pointers.

---

14. Current Booking Save And Hidden Compatibility Work

sequenceDiagram
    actor Operator
    participant UI as Current Booking UI
    participant Route as Booking API
    database DB as MySQL
    participant MK as MK Shared Helper
    participant Children as Order / Item / Lot / Allocation

    Operator->>UI: Save Booking
    UI->>Route: Create/Update
    Route->>DB: Begin transaction
    Route->>DB: Persist Booking fields/link
    Route->>MK: Run compatibility sync task
    MK->>Children: Upsert, reset or delete related state
    alt all work returns normally
        Route->>DB: Commit
        Route-->>UI: Success
    else helper logs/swallows a later error
        Children-->>MK: Partial or stale child state
        MK-->>Route: Incomplete apparent result
        Route->>DB: Commit may still occur
        Route-->>UI: Booking success without complete child result
    end

---

15. Target Booking Save

sequenceDiagram
    actor Operator
    participant UI as React Booking Workspace
    participant Next as Next.js Adapter
    participant Booking as Booking Application
    database DB
    participant Handoff as Explicit Child Owner

    Operator->>UI: Save Booking
    UI->>Next: Typed Booking command + request token
    Next->>Booking: Authenticated tenant/actor command
    Booking->>DB: Conditional Booking-owned transaction
    Booking->>DB: Commit and exact readback
    Booking-->>Next: Booking result + explicit handoff requests
    opt accepted child handoff required
        Next->>Handoff: Invoke named owner command
        Handoff-->>Next: SUCCEEDED / PARTIAL / FAILED / UNKNOWN
    end
    Next-->>UI: Booking result plus per-child dispositions

No hidden inventory/allocation mutation occurs inside UpdateBooking.

---

16. Booking Clone

sequenceDiagram
    actor Operator
    participant Booking as Booking Application
    database DB

    Operator->>Booking: CloneBooking(source, count, carry policy, request token)
    Booking->>DB: Read source Booking and allowed fields
    Booking->>DB: Check duplicate request/result
    Booking->>DB: Create each clone with generated identity
    Booking->>DB: Commit
    Booking->>DB: Reread created IDs/numbers/fields
    Booking-->>Operator: Exact clone list + omitted child list

Clone Booking != clone containers/files/allocations/physical work.

---

17. Cross-Child Unknown Result Recovery

flowchart TB
    Unknown[Response lost / partial / unexpected error]
    Identify[Identify owning command and stable IDs]
    Child[Read owning header/items]
    Related[Read only affected child records]
    Result{Committed result?}
    Complete[Use existing result]
    Missing[Retry only missing owner command]
    Conflict[Stop and reconcile exact mismatch]

    Unknown --> Identify --> Child --> Related --> Result
    Result -- Complete --> Complete
    Result -- Clearly absent --> Missing
    Result -- Partial/ambiguous --> Conflict

---

18. Target Component Diagram

flowchart TB
    subgraph React
      CommercialUI[Commercial Workspace]
      InboundUI[Inbound Workspace]
      OutboundUI[Outbound Workspace]
      BookingUI[Booking Workspace]
      ReconcileUI[Order-First Reconciliation]
    end

    subgraph NextJS
      RSC[Server Components]
      Routes[Route Handlers / bounded Server Actions]
    end

    subgraph TypeScript
      COApp[Commercial Application]
      INApp[Inbound Application]
      OUTApp[Outbound Application]
      BKApp[Booking Application]
      Policy[Handoff / State / Capability Policies]
    end

    subgraph Infra
      CORepo[Commercial Repository]
      OrderRepo[Order Repository]
      BookingRepo[Booking Repository]
      MySQL[(MySQL)]
    end

    subgraph OtherOwners
      Scale[Scale Application]
      Inventory[Inventory / Allocation Application]
      Worker[Node Worker for durable effects]
    end

    CommercialUI --> RSC
    InboundUI --> RSC
    OutboundUI --> RSC
    BookingUI --> RSC
    ReconcileUI --> RSC
    RSC --> COApp
    RSC --> INApp
    RSC --> OUTApp
    RSC --> BKApp
    Routes --> COApp
    Routes --> INApp
    Routes --> OUTApp
    Routes --> BKApp
    COApp --> Policy
    INApp --> Policy
    OUTApp --> Policy
    BKApp --> Policy
    COApp --> CORepo
    INApp --> OrderRepo
    OUTApp --> OrderRepo
    BKApp --> BookingRepo
    CORepo --> MySQL
    OrderRepo --> MySQL
    BookingRepo --> MySQL
    INApp --> Scale
    INApp --> Inventory
    OUTApp --> Inventory
    Policy --> Worker

---

19. One-Writer Migration

sequenceDiagram
    participant Selector as Capability/Cohort Selector
    participant PHP as Current PHP Writer
    participant TS as TypeScript Writer
    database DB as MySQL

    Selector->>PHP: Legacy cohort/capability
    Selector->>TS: Migration cohort/capability
    Note over PHP,TS: Exactly one writer for a given capability/cohort.
    PHP->>DB: Current command
    TS->>DB: New command
    DB-->>PHP: Exact readback
    DB-->>TS: Exact readback
    alt rollback
        Selector->>PHP: Resume accepted PHP writer
        Selector--xTS: Disable new commands
        Note over DB: Preserve all committed rows and child evidence.
    end

---

20. Migration Wave Diagram

flowchart LR
    W0[W0 Characterize / policy]
    W1[W1 Read-only React + TS]
    W2[W2 Commercial writer]
    W3[W3 Inbound scheduled writer]
    W4[W4 Receipt finalize writer]
    W5[W5 Outbound scheduled writer]
    W6[W6 Booking-owned writer]
    W7[W7 Compatibility retirement]
    W8[W8 Role/Wiki stabilization]
    W9[W9 PHP caller-zero]
    PG[Later PostgreSQL]

    W0 --> W1 --> W2 --> W3 --> W4 --> W5 --> W6 --> W7 --> W8 --> W9 --> PG

---

21. Diagram Maintenance Triggers

Review the applicable diagrams when any of these changes:

• Commercial status or relation policy;
• Commercial line identity/update behavior;
• Inbound receipt/no-scale/multi-line behavior;
• item/transload/lot transaction ownership;
• Outbound allocation or bridge correction;
• Booking/Sales link direction;
• Booking clone/inactive behavior;
• Booking compatibility sync responsibility;
• role/capability/profile mapping;
• target React/Next.js/TypeScript component boundary;
• one-writer selector, rollback or caller-zero;
• PostgreSQL repository representation.

---

Source: docs/processes/MK_ORDER_FIRST_CORE_SEQUENCE_DIAGRAMS.md — ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.