Skip to content

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 Parity, Cutover, Rollback And Caller-Zero Matrix

  • Status: MIGRATION DESIGN INPUT / NOT ACTIVATED
  • Scope: Commercial Agreement, Inbound Purchase, Outbound Sales and Booking
  • Rebuild packet: MK_ORDER_FIRST_CORE_CAPABILITY_REBUILD_PACKET.md
  • Policy decisions: MK_ORDER_FIRST_CORE_POLICY_DECISION_MATRIX.md
  • Diagrams: MK_ORDER_FIRST_CORE_SEQUENCE_DIAGRAMS.md
  • Target: React + Next.js + framework-independent TypeScript + MySQL first; separate worker only for durable asynchronous effects; PostgreSQL later

This matrix does not authorize migration. It defines the evidence and boundaries required before a bounded P12 wave can be activated.

1. Global Migration Invariants

  1. One authoritative writer per capability and cohort.
  2. Old and new implementations may read the same MySQL records during parity.
  3. No independent PHP/TypeScript dual write.
  4. Booking Save must not hide target inventory/allocation mutation.
  5. Scale remains Scale-owned; Allocation remains Allocation-owned.
  6. Manual header labels remain distinct from derived execution/readiness.
  7. Every command returns exact authoritative readback.
  8. Timeout/unknown result is reread before retry.
  9. Rollback preserves committed business, inventory and physical evidence.
  10. PostgreSQL does not start with the first React/Next.js writer wave.
  11. Stable Wiki topics survive route changes where practical.
  12. UNKNOWN caller or consumer blocks deletion.

2. Read Parity Matrix

2.1 Commercial

Read capability Current source Target query Parity dimensions Required negative cases
Agreement list Commercial list API/query helper GetCommercialAgreementList row count, date/type/status filters, number/reference/counterparty/commodity search, linked reverse display foreign tenant, deleted row, cancelled-link option exclusion
Agreement detail current detail query GetCommercialAgreementDetail every consequential header field, lines, totals, signatures, relation, execution references missing/foreign ID, absent signature columns, item-level execution pointer
Next number preview current number preview/reservation GetCommercialNumberPreview prefix/date/type, preview versus actual reserved number concurrent reservation, stale preview
Print projection PHP print page GetCommercialConfirmationProjection Purchase/Sales labels, fields, lines, signatures, reverse link inaccessible module/tenant, stale data after render

2.2 Inbound

Read capability Current source Target query Parity dimensions Required negative cases
Inbound list current list query GetInboundPurchaseList filters, order classification, header label, item summary, current references foreign/deleted/misclassified order
Detail current detail query GetInboundPurchaseDetail header, all items, Commercial links, operational state, ticket/transload/lot references multi-line, item-only Commercial reference, stale/foreign direct ID
Schedule/calendar current projections GetInboundSchedule dates, rows, statuses and no hidden mutation missing data, filter boundary, cancelled/terminal rows
Receipt reconciliation multiple current reads GetReceiptReconciliation ticket, order/items, transload, lot, placement, allocation blockers checked-out/finalize-pending, cardinality conflict, missing lot, partial source state

2.3 Outbound

Read capability Current source Target query Parity dimensions Required negative cases
Outbound list current query handler GetOutboundSalesList filters, type/status, booking/container, requested totals incomplete Ocean row, foreign/missing references
Detail current detail query GetOutboundSalesDetail header/items, Commercial/Booking, equipment bridge, allocation, Scale/Delivery/Packing/Cost projections stale Booking reverse pointer, multiple equipment bridge candidates
Schedule current projection GetOutboundSchedule row classification, dates, operational mapping cancelled/deleted/partial allocation
Readiness current derived flags GetOutboundReadiness each source flag and exact blocker no allocation, partial allocation, scale absent, bridge conflict

2.4 Booking

Read capability Current source Target query Parity dimensions Required negative cases
Booking list/search current Booking list/search GetBookingList active/inactive filtering, cutoffs, invoice, counts, flags inactive exact-ID search, deleted row, foreign tenant
Booking detail current detail/query helpers GetBookingDetail header, parties, ports, planned containers, invoice, flags, Sales link invalid retained link, foreign company/terminal/inspector
Handoff/children current scattered projections GetBookingHandoffStatus Sales order, equipment/load, Packing, compatibility child IDs partial compatibility, missing reverse link, stale lot/allocation
Clone reconciliation suffix/detail search GetBookingCloneResult created IDs/numbers, carried/omitted fields lost response, existing suffix, no-Shipper source

3. Write Parity Matrix

3.1 Commercial commands

Command Current behavior to characterize Target requirement Cutover blocker
Create one header + items transaction, generated number, normalization request-token idempotency, same field/precision semantics or approved change, exact detail schema/number/field parity; role matrix
Update header current full/basic field behavior and last-write-wins explicit field allowlist, version predicate and exact readback post-execution field policy
Update lines pre-execution replacement; post-execution preserve accepted stable-line or replacement command line identity decision and execution-reference inventory
Relate same-tenant opposite type, one stored pointer accepted direction/cardinality/cycle/status rule and two-sided readback MKPOL-CO-030/040/050
Set status allowed-list value accepted transition/actor/reason/audit status policy
Delete block header-linked execution, unlink counterpart, soft delete include all accepted execution refs and exact counterpart disposition execution detection and restore policy

3.2 Inbound commands

Command Current behavior to characterize Target requirement Cutover blocker
Create scheduled generated PO, current normalization and optional commercial link idempotent create and exact detail field/reference/role parity
Atomic save one request transaction for header/items/deletions versioned full-set command with blocker query post-progress policy and direct caller inventory
Finalize from Scale checked-out ticket then separate finalize; exact lot/cardinality behavior idempotent receipt transaction and full readback multi-line policy and lot owner
Complete without Scale current Brokerage/OCEAN_FREIGHT restrictions explicit profile/config eligibility and idempotent receipt no-scale policy
Correct received item unsafe generic current behavior inventory-aware correction/reversal quantity/weight/allocation/ledger/placement policy
Delete order guard stronger than item guard central blocker query and exact child IDs correction/delete policy

3.3 Outbound commands

Command Current behavior to characterize Target requirement Cutover blocker
Create generated SO, requested UNMAPPED lines, optional bridge idempotent demand create; no allocation Ocean/Local required-field policy
Atomic save header/items/deletions through shared MK helper versioned scheduled command; no allocation drift progressed-field policy
Link Booking current pointer/bridge synchronization canonical relation and two-sided readback link direction/cardinality
Correct allocated item current update can diverge allocation-aware command or explicit rejection unallocate/reversal policy
Delete child blockers; potential stale Booking pointer exact blocker list and accepted link cleanup pointer cleanup policy

3.4 Booking commands

Command Current behavior to characterize Target requirement Cutover blocker
Create Booking write, generated invoice, optional link, compatibility sync Booking-only transaction + explicit child handoff results compatibility characterization
Update Booking fields/link and compatibility work versioned Booking-only update link and inactive/flag policy
Clone suffix generation, broad carry, no child clone, no IDs request-token idempotency and exact created IDs/carry policy clone policy
Mark inactive manual flag only explicit marker command and active-child warning inactive policy
Sales link invalid create/update can clear/retain inconsistently canonical link command and exact two-sided readback link policy
Compatibility reconcile current hidden broad sync temporary explicit command or retirement owner mapping and caller-zero

4. UI Parity Matrix

Surface Current user result Target React result Acceptance
Commercial list/detail current filters, editor, relation, print same business information with separate status/utilization and blocked reasons target-role can find, create, reopen and reconcile exact record
Inbound editor header/items, operational state, receipt paths scheduled editor plus receipt checkpoint panel and child readback operator can distinguish scale, finalize and lot
Outbound editor requested demand, bridge/readiness demand, allocation, bridge and child dispositions shown independently no readiness-as-completion confusion
Booking list/editor fields, flags, links, clone Booking-owned editor plus explicit handoff/partial results no hidden child success; clone result IDs visible
Order-first overview current dashboard/manual navigation cross-child reconciliation query and stable links each child has disposition and next owner

Every target surface must implement:

loading
empty
no exact match
denied
validation
stale conflict
partial result
unknown result
completed readback
next owner

5. Role And Access Parity

For each command/query, capture:

profile
tenant
role/account
menu visibility
page entry
API query allowed/denied
API command allowed/denied
record scope
foreign record behavior
no-mutation evidence
exact visible reason

Minimum matrix:

Actor group Commercial Inbound Outbound Booking Allocation/Scale handoff
MK Commercial/Office view/create/update/relation/status per policy view linked view linked view linked no direct child mutation unless separately assigned
MK Receiving view commercial Purchase create/update/finalize per policy read relevant demand read relevant Booking Scale/Inventory handoff only
MK Shipping/Booking view commercial Sales read relevant receipts/lots create/update/link create/update/clone/inactivate allocation/scale read and assigned commands
Inventory operator read source/demand read received source read demand read Booking/container allocation commands
Scale operator read required source Scale + finalization handoff per role Scale handoff read container context no commercial/booking mutation
Manager/Admin bounded recovery bounded recovery bounded recovery bounded recovery no raw data forcing

Numeric role IDs are evidence inputs, not target policy.

6. Transaction And Idempotency Parity

Boundary Current Target Evidence required
Commercial create/update one local request transaction one semantic command transaction before/after header/items/relation, duplicate and response-loss
Inbound atomic save one transaction one versioned scheduled command rollback on item/delete error
Scale checkout → finalize separate commands remain separate, with finalize idempotency checked-out/finalize-pending recovery
receipt → lot helper chain in local transaction where successful accepted owner transaction and exact lot result duplicate, cardinality, rollback
Outbound save one local request transaction, no allocation same semantic separation zero allocation/lot effect
Booking save local transaction plus compatibility tasks Booking-only transaction plus explicit child commands child partial/unknown behavior
clone current suffix/search recovery request-token idempotency and returned IDs lost response and duplicate

7. Migration Waves And Activation Gates

Wave 0 — Characterization

Entry requirements:

  • exact branch/source/schema/role/profile pinned;
  • current Process and Wiki read;
  • no competing writer;
  • stable scenario fixtures and cleanup plan.

Exit requirements:

  • current caller map;
  • field/state/query/write evidence;
  • compatibility sync affected-child matrix;
  • accepted/explicitly deferred critical policy list.

Wave 1 — Read-only React/Next.js

Activate:

  • GetMkOrderFirstOverview;
  • Commercial list/detail;
  • Inbound list/detail/receipt projection;
  • Outbound list/detail/allocation/readiness projection;
  • Booking list/detail/handoff projection.

Gate:

  • old/new field and count parity;
  • no writes from new Runtime;
  • target-role findability and access parity.

Rollback:

  • route/navigation back to PHP read surface; no data change.

Wave 2 — Commercial writer

Recommended first write because it has no provider/physical effect and a bounded local data family.

Gate:

  • status/relation/line identity decisions;
  • role matrix;
  • idempotency/version;
  • create/update/relation/delete scenarios;
  • rollback selector.

Wave 3 — Inbound scheduled writer

Gate:

  • exact scheduled fields and references;
  • atomic-save parity;
  • no receipt/lot writer activation;
  • direct compatibility caller plan.

Wave 4 — Receipt finalization

Gate:

  • Scale handoff contract;
  • no-scale policy;
  • multi-line/lot identity decision;
  • post-receipt correction and duplicate handling;
  • active ticket/receipt rollback rehearsal.

Wave 5 — Outbound scheduled writer

Gate:

  • required-field policy;
  • no allocation effect;
  • Booking/equipment bridge semantics;
  • progressed/allocated edit blockers.

Wave 6 — Booking writer

Gate:

  • Sales link, clone, inactive and flag policies;
  • new writer demonstrably does not run hidden compatibility mutation;
  • explicit child result contract;
  • current compatibility cohort remains on PHP.

Wave 7 — Compatibility replacement/retirement

Gate:

  • every current compatibility outcome assigned to an owner command or rejected as obsolete;
  • read/business parity;
  • in-flight partial-result reconciliation;
  • no unknown caller.

Wave 8 — Role/Wiki stabilization

Gate:

  • current role/field acceptance;
  • Wiki named-slug read/update/readback;
  • stable current/future links;
  • observation and support Runbook.

Wave 9 — Caller-zero

Gate:

  • source search;
  • browser/network/runtime observation;
  • scripts/jobs/tests/reports/docs/bookmarks classified;
  • retained compatibility explicitly owned;
  • unknown count zero.

8. Rollback Matrix

Wave Disable Preserve Reconcile before resume Prohibited rollback
Read-only new routes/components no data changes cache/session/navigation data rollback
Commercial TypeScript commercial commands all agreements/lines/links in-flight request tokens and last versions recreate/delete accepted agreements
Inbound scheduled new scheduled commands orders/items/bridges in-flight atomic saves source reset
Receipt new finalize/no-scale commands Scale tickets, received items/transloads/lots pending tickets and partial/unknown receipts repeat physical weighing or delete lots blindly
Outbound new outbound commands demand/items/bridges/allocations in-flight saves and link state dual write or allocation recreation
Booking new Booking commands Booking, flags, links, children in-flight saves/clones/handoffs hidden compatibility replay
Compatibility new explicit compatibility routes/worker every existing child row/balance pending/unknown child commands full Booking Save replay

Rollback switches writer routing. It does not reverse physical/business history merely to restore old code.

9. Caller-Zero Inventory

Commercial

  • list/detail/editor/print page calls;
  • API routes and helper calls;
  • execution reference queries;
  • reports/exports;
  • direct links/bookmarks;
  • tests and migration scripts.

Inbound

  • shared editor and Doortrade route;
  • header/item/atomic-save APIs;
  • Scale purchase paths;
  • no-scale path;
  • WMS lot/transload/warehouse calls;
  • Export Brokerage and allocation consumers;
  • reports, schedule/calendar and tests.

Outbound

  • shared editor/list/detail/schedule;
  • header/item/atomic-save APIs;
  • allocation workbench;
  • Scale/Delivery/Packing/Cost consumers;
  • Booking pointer consumers;
  • reports/tests.

Booking

  • Booking list/editor/search/clone;
  • generic form mutation callers;
  • Sales/Equipment/OUT REF integrations;
  • Packing and output pages;
  • compatibility sync task/caller;
  • reports/tests/bookmarks/Wiki links.

Statuses:

ACTIVE
COMPATIBILITY
TEST_ONLY
HISTORICAL
UNKNOWN
REMOVED_AND_VERIFIED

10. Scenario-To-Test-Layer Map

Scenario family Unit/policy Repository/DB API Browser/role Migration/observation
MKCO-* required required required required selected
MKIN-* scheduled required required required required selected
MKIN-* receipt required required required required required for cutover
MKOUT-* required required required required selected
MKBK-* required required required required compatibility scenarios required
MKMIG-* as applicable required required required required

Source-string tests do not replace behavior evidence.

11. Evidence Record Template

wave/capability/scenario ID
old source revision
new source revision
database/schema identity
tenant/profile/account/role
feature/cohort selector
fixture IDs
old query result
new query result
old command result where safe
new command result
before/after authoritative rows
child/effect disposition
visible UI result
negative/denied result
rollback result
cleanup
observed caller traffic
remaining discrepancy and owner

12. Cutover Stop Conditions

Stop activation when:

  • role/record scope is unknown;
  • a critical policy remains invented rather than accepted;
  • old/new reads materially disagree without disposition;
  • Booking writer still mutates Inventory/Allocation invisibly;
  • receipt finalization cannot prove idempotency and lot identity;
  • allocated/progressed outbound correction is unsafe;
  • PHP and TypeScript can both write the same cohort;
  • rollback has not been rehearsed;
  • current active caller is UNKNOWN;
  • Wiki/operator procedure would instruct a nonexistent or unsafe path;
  • PostgreSQL work is coupled to first writer cutover.

13. Migration Completion Criteria

A capability reaches migrated-and-stabilized status only when:

  • target writer owns all accepted commands;
  • old/new read parity is accepted;
  • target-role normal/denied/duplicate/timeout/recovery scenarios pass;
  • rollback is proven;
  • observation window is completed;
  • operator Runbook and Wiki are current and readable;
  • old caller count is zero or explicitly retained compatibility;
  • PHP source/helper is removed only after caller-zero;
  • no unexplained child/data discrepancy remains.

---

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