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 Physical Scale Parity And Cutover Matrix¶

Status: MIGRATION INPUT / NO WAVE ACTIVATED
Process: PROC-YMS-SCALE-TICKET-EXECUTION-MK
Rebuild packet: MK_PHYSICAL_SCALE_CAPABILITY_REBUILD_PACKET.md
Reconciliation: MK_PHYSICAL_SCALE_RECONCILIATION.md
Policy: MK_PHYSICAL_SCALE_POLICY_DECISION_MATRIX.md
Diagrams: MK_PHYSICAL_SCALE_SEQUENCE_DIAGRAMS.md
Operating profile: mk-order
Current DB: MySQL
Target first DB: MySQL
Later DB: PostgreSQL after accepted application stabilization
Important: this matrix does not authorize Runtime writes, role changes, device effects, deployment, Production observation or caller retirement.

1. Migration Objective¶

Replace current PHP/JavaScript Scale orchestration with:

React Scale Workspace
+ Next.js authenticated adapters
+ TypeScript Scale applications and policies
+ typed MySQL repositories
+ explicit owner-child results
+ one authoritative writer
+ rollback and caller-zero

while preserving or deliberately improving:

flow/stage meaning;
ticket/order/link identity;
accepted Gross/Tare/Net values;
transaction boundaries;
correction/reversal lineage;
role/tenant/record scope;
duplicate/timeout recovery;
current CTC behavior;
physical operator continuity.

The migration must not copy the current Sales/Export stage contradiction into the target.

2. Gate Vocabulary¶

NOT STARTED
CHARACTERIZED
PARITY INPUT READY
READ SHADOW
WRITE SHADOW
ONE WRITER
STABILIZING
CALLER ZERO
ROLLED BACK
BLOCKED

A wave can advance only with named evidence and an explicit owner decision.

3. Global Activation Blockers¶

ID	Blocker	Required resolution
`SCALE-CUT-010`	Sales/Export entry-stage contradiction	accepted flow matrix plus all-flow Runtime scenarios
`SCALE-CUT-020`	action-level role policy incomplete	P2-007 page/API/record capability matrix
`SCALE-CUT-030`	no durable request token	schema/application request identity and duplicate semantics
`SCALE-CUT-040`	ticket number concurrency	atomic request-bound reservation
`SCALE-CUT-050`	Check-out browser-sequential owner Save	accepted owner preparation contract or explicit bounded child results
`SCALE-CUT-060`	BMS competing writer	exact retained scope or caller-zero plan
`SCALE-CUT-070`	reversal owner/downstream policy open	accepted recovery role and blocker matrix
`SCALE-CUT-080`	current Wiki/role/device evidence absent	named review and evidence plan
`SCALE-CUT-090`	CTC regression not selected	exact Client-1 reference scenarios

Device integration can remain out of the first write migration when manual-entry scope is explicitly accepted.

4. Read Parity Matrix¶

Read	Current source	Target contract	Required parity/evidence
Schedule	`/api/yms/scale/schedule`	`GetScaleSchedule`	same eligible order/ticket identities, explicit flow reason, stable sort/filter
Open tickets	`/api/yms/scale/tickets?OPEN_ONLY=1`	`GetOpenScaleTickets`	accepted flow-aware entry/exit classification; detect current contradiction
Ticket detail	`/api/yms/scale/tickets/{id}`	`GetScaleTicketDetail`	exact fields, totals, link, state, warnings and allowed actions
Event timeline	`/api/yms/scale/tickets/{id}/events`	`GetScaleTicketTimeline`	exact event order, before/after values, reason, actor and request
Order context	Inbound/Outbound detail helpers	owner query adapters	exact order/items/version and role scope
Purchase link	`T_TRANSLOAD.SCALE_TICKET_ID`	typed Purchase/Transload link	exact same accepted link and conflicts
Sales link	`T_EQUIPMENT_LOAD.SCALE_TICKET_ID`	typed Sales/Equipment link	exact same accepted link and conflicts
Ticket number projection	`T_LOAD.TICKET_NUMBER`	compatibility projection	same visible value until caller-zero; not canonical target link
Completed ticket	exact detail by ID	completed readback/timeline	target retains discoverable completion even after active-board removal
Physical print	PHP `IDS[]` projection	target read adapter or stable compatibility route	tenant/active/role parity and field parity

Read parity stop conditions¶

target flow classification hides a current valid row without accepted policy;
target exposes another tenant’s record;
Gross/Tare/Net differs beyond accepted precision;
link or event history differs;
target cannot explain a current conflict/unknown state;
current UI contradiction is silently treated as parity.

5. Write Parity Matrix¶

Write	Current source	Target command	Preserve	Improve before cutover
integrated Check-in	`/check-in/execute`	`ExecuteScaleCheckIn`	one local transaction, owner reuse, returned IDs	correct flow stage, request token, version, exact readback, number reservation
entry repeat	`CHECKIN_UPDATE` same values	idempotent command result	no duplicate stage/event	bind to request token/result
reweigh	`CHECKIN_UPDATE` changed values + reason	`CorrectScaleEntryStage`	reason, CAS, event	semantic capability, stable errors, result token
Check-out owner Save	sequential Owner API requests	`PrepareScaleCheckOut`	allowed field edits	one accepted owner transaction/result
Scale Out	`/check-out`	`CompleteScaleCheckOut`	entry prerequisite, stage CAS, total validation	flow stage, token, exact completed result
Purchase finalize	`/purchase-inbound/finalize`	owner `FinalizePurchaseReceiptFromScale`	separate child authority	stable child result and finalize-only recovery
Outbound close	later Outbound PATCH	owner `CloseOutboundFromScale`	separate child authority	server time/version and close-only recovery
Void/reversal	YMS ticket DELETE	`VoidOrReverseScaleTicket`	reason, broad blocker, event, rollback	semantic action name, token/version, exact residual readback
physical print	browser GET	query/output adapter	nondurable effect	stable active/role/tenant contract
BMS PATCH/delete	generic BMS writer	no equivalent target Scale owner path	only accepted disjoint behavior	retire/route to owner command

6. UI Parity Matrix¶

Surface/state	Current	Target requirement	Evidence
Schedule list	top table	React ScheduleView	target-role browser, filters, exact row identity
open yard board	active ticket cards + demo fallback	ActiveTicketBoard with real empty state	no demo row in operational mode
Check-in	top panel	typed CheckInForm	all flows, field validation, double-submit, unknown result
Check-out	bottom panel	typed CheckOutForm	owner preparation, stage validation, child results
Purchase branch	post-Scale bottom panel	explicit Inbound child handoff	finalize success/failure/reopen
completed ticket	disappears from active board	CompletedTicketReadback	exact known-ID and search/readback
reweigh	reopen Check-in prompt	dedicated correction action	reason, stale conflict, timeline
reversal	delete/reverse prompt	Void/Reversal recovery UI	blocker list, reason, event/result
print	popup	stable print action	popup blocked/error/no mutation
live weight	static/manual	manual source plus optional DeviceStatus	source/stability/age explicit
denied	route/menu behavior	dedicated denied state	no copied-ID bypass
timeout	alert refresh before retry	unknown-result state	request/ticket reread, no replay
partial child	generic alerts	independent child dispositions	Scale complete + child failed visible

7. Role And Record Parity¶

Required roles/fixtures:

Scale Operator
Receiving/Inbound
Shipping/Outbound
Manager/Recovery
Support
unauthorized same-tenant user
foreign-tenant user
superadmin/impersonation only where accepted

Required matrix:

Action	Menu/page	API	Record	Expected
view Schedule	assigned route	query allowed	same tenant	allowed
view Schedule	no route/capability	query denied	same tenant	denied without global outage
Check-in	view-only role	command denied	same tenant	stable forbidden
Check-out	Check-in-only role	command denied	same tenant	stable forbidden
reweigh	normal operator without recovery capability	command denied	same tenant	stable forbidden
reversal	normal operator	command denied	same tenant	stable forbidden
events	summary/full roles	bounded result	same tenant	accepted scope
print	authorized role	active ticket	same tenant	allowed
direct ticket ID	assigned role	query/command	foreign tenant	not found/forbidden
BMS route	MK YMS ticket	generic writer	same tenant	denied/retired per policy

Do not gate by numeric role ID or client ID in target domain logic.

8. Data Parity Matrix¶

Data	Current	Target parity/decision
ticket identity	integer ID + UUID + ticket number	preserve all; request token added separately
tenant scope	`CLIENT_ID`	typed tenant context; later UUID bridge
stage time	DB stage timestamp	canonical `stageAcceptedAt`; device captured time separate
axle values	integer LB columns	exact parity initially; typed decimal/string contract
Gross/Tare/Net	sum columns	identical accepted calculation
commodity/quantity	ticket snapshots	exact owner/source policy and UOM
order link	ticket number projection plus Transload/Equipment link	typed relationship; ticket number projection compatibility only
correction lineage	`T_SCALE_TICKET_EVENT`	preserve append-only event and all fields
request identity	request trace only	durable command request token/result
deletion	`DELETED_AT` + event on YMS path	semantic Void/Reversal only
signatures/bad bale	legacy shared columns	explicit include/defer decision
audit	KJDatabase plus event	preserve bounded business event; target request/correlation

Schema verification before write activation¶

Verify exact current environment:

table/column existence;
UUID nullability/uniqueness;
event table and indexes;
ticket number unique key behavior;
precision/types/defaults;
link indexes;
lifecycle columns;
request-token schema;
migration identity/checksum.

9. Flow Direction Parity Gate¶

This gate is not ordinary parity because current source is contradictory.

Required accepted scenarios:

Purchase: Gross entry, Tare exit
Doortrade: Gross entry, Tare exit
Sales: Tare entry, Gross exit
Export: Tare entry, Gross exit

For each flow record:

UI label/input;
command payload;
policy result;
DB stage fields;
active board state after entry;
Check-out eligibility;
exact completed detail;
owner link;
cleanup.

A target that reproduces current all-flow Gross behavior does not pass.

10. Transaction And Partial-Result Parity¶

10.1 Check-in¶

Required:

order/items/ticket/link
= one target transaction

Failure injection:

invalid middle item;
owner save conflict;
ticket number conflict;
ticket insert failure;
link failure;
response loss after commit.

Expected:

no partial local rows on definite failure;
same token returns existing result after committed response loss;
exact zero residue after fixture cleanup.

10.2 Check-out¶

Target may improve current behavior but must preserve explicit boundaries.

Owner preparation
-> Scale Out
-> child finalize/close

Failure injection:

owner header conflict;
one owner item invalid;
Scale stage stale;
Scale response loss;
Outbound close failure;
Purchase finalize failure.

Expected UI:

exact last successful boundary;
only missing child action available;
no automatic full retry.

10.3 Reversal¶

Failure injection:

Transload progressed;
Inventory Lot exists;
Ledger exists;
Equipment/Delivery link exists;
concurrent stage change;
event write failure;
link cleanup failure;
response loss.

Expected:

allowed YMS transaction is all-or-nothing;
blocked reversal leaves ticket active;
response loss returns existing event/result by request token;
no generic BMS bypass.

11. Performance And Operational Parity¶

Do not claim performance improvement without measurement.

Measure at least:

Schedule query latency and result count;
active-board load latency;
exact detail/timeline latency;
Check-in submit-to-readback latency;
Check-out submit-to-ticket result latency;
child finalize/close latency separately;
request-token lookup latency;
device reading age/update rate when activated;
error/unknown-result rate;
duplicate-prevention count;
operator steps and repeated searches.

Guardrails:

no hidden cache with stale physical state;
no delayed ticket visibility after commit;
no unbounded event/ticket query;
no device polling that overloads the business API;
no performance work that weakens tenant/state predicates.

12. Migration Waves¶

`SCALE-W0` — characterization¶

Deliver:

current callers and screens;
exact schema/indexes;
current role/page/API/record matrix;
all four flow fixtures;
BMS writer inventory;
current Wiki content;
actual device scope/status;
CTC regression selection.

No new writer.

`SCALE-W1` — flow policy and current defect disposition¶

Deliver:

accepted SCALE-POL-010;
current Sales/Export reproduction or contrary evidence;
bounded current Runtime correction if separately approved;
corrected static/browser/API tests;
no unintended Purchase/CTC regression.

This is a prerequisite for target write migration.

`SCALE-W2` — TypeScript reads¶

Deliver:

Schedule/ticket/detail/timeline queries;
typed states and flow reasons;
exact parity report;
read-only support conflict diagnostics.

`SCALE-W3` — React/Next.js read-only¶

Deliver:

Schedule and active board;
completed readback;
timeline;
current/future stable links;
target-role view/denied evidence;
no mutation.

`SCALE-W4` — integrated Check-in one writer¶

Deliver:

request token/result store;
ticket number reservation;
owner Save adapter;
flow-stage validation;
exact readback;
selected cohort one-writer;
rollback.

`SCALE-W5` — Check-out preparation and Scale Out¶

Deliver:

owner preparation contract;
Check-out request token/version;
completed ticket readback;
partial-result UI;
selected cohort one-writer.

`SCALE-W6` — child owner dispositions¶

Deliver:

Purchase finalize child result;
Outbound close child result;
finalize/close-only recovery;
Process/Runbook/Wiki updates.

`SCALE-W7` — correction/reversal¶

Deliver:

semantic reweigh/reversal capability;
event parity;
downstream blocker parity;
unknown-result recovery;
support view.

`SCALE-W8` — optional device¶

Only when approved:

device adapter/session/reading envelope;
stable/unstable/disconnect behavior;
manual fallback marking;
hardware/field evidence;
device rollback.

`SCALE-W9` — BMS competing-writer retirement¶

Deliver:

accepted BMS retained scope or removal;
caller migration;
API/role rejection for MK YMS tickets;
data conflict reconciliation;
caller-zero.

`SCALE-W10` — stabilization and Wiki¶

Deliver:

target-role all-flow browser evidence;
support/recovery rehearsal;
current T_WIKI_PAGE named updates and readback under separate authorization;
observation metrics;
no open critical conflict.

`SCALE-W11` — PHP caller-zero¶

Deliver:

no current PHP Scale business writer for migrated cohort;
no browser string-action dependency;
stable compatibility redirects where required;
source deletion candidate separately reviewed.

`SCALE-W12` — PostgreSQL later¶

After accepted MySQL stabilization:

type/precision/index/constraint parity;
idempotency/event/link migration;
dual-read/reconciliation as approved;
one DB writer;
rollback/failback;
MySQL caller-zero.

13. One-Writer Matrix¶

Cohort state	PHP YMS	TypeScript Scale	BMS generic	Allowed
pre-cutover	write	read shadow	current bounded behavior	temporary current state
selected target cohort	read only	write	denied/disjoint	required
rollback	write for new requests	stop new writes/read diagnostics	prior accepted bounded scope only	required
stabilized	no write	write	denied/disjoint	required
caller-zero	removed/compat only	write	no overlapping writer	final target

No dual write for one request/ticket/cohort.

14. Rollback Matrix¶

Failure	Immediate action	Preserve	Reconcile before resume
read mismatch	stop expansion	current data and target diagnostics	query/flow/link differences
Check-in write mismatch	route new cohort requests to prior writer	committed target ticket/order/link	request tokens and exact rows
Check-out mismatch	stop target Check-out	completed ticket and owner rows	last successful child boundary
child finalize/close mismatch	keep Scale result	ticket and owner evidence	child-only state
event/reversal mismatch	disable target recovery writes	ticket/event/link evidence	active/soft-deleted/residual state
role leak	disable affected target route	data/evidence	access logs and scope
device defect	disable device input	manual path and business tickets	device sessions/readings
BMS conflict	freeze both recovery paths for affected tickets	audit/events/links	exact writer result and residuals

Rollback does not erase committed physical evidence or replay unknown work.

15. Caller-Zero Inventory¶

Required current families:

frontend/pages/system/YMS/scale/scale-portal.php
public/assets/js/modules/yms/scale-portal.js
app/systems/YMS/scale/*
app/systems/OMS/inbound-order/mk_post_helper.php Scale functions
app/systems/OMS/inbound-order/mk_query_helper.php Scale reads
app/systems/BMS/scale-ticket/*
app/systems/BMS/transaction/post_helper.php Scale functions
frontend/pages/system/BMS/scale-ticket/scaleticket.php
reports/history/billing consumers
Inbound/Outbound/Transload/Equipment/Inventory link consumers
Wiki/menu/page routes
tests/scripts and operational documentation

Caller-zero proves:

no overlapping current writer;
no direct table business mutation;
no stale PHP route in menu/Wiki;
no unknown report/provider/device dependency;
stable redirect/print contract where retained;
all target-role and recovery paths use the accepted owner.

16. Stable Migration Scenarios¶

SCALE-MIG-SCN-010 Schedule parity
SCALE-MIG-SCN-020 flow classification parity and accepted deviation
SCALE-MIG-SCN-030 open/completed/detail/event parity
SCALE-MIG-SCN-040 Check-in one-writer
SCALE-MIG-SCN-050 Check-in rollback and response loss
SCALE-MIG-SCN-060 Check-out preparation one-writer
SCALE-MIG-SCN-070 Scale Out one-writer
SCALE-MIG-SCN-080 Purchase child recovery
SCALE-MIG-SCN-090 Outbound child recovery
SCALE-MIG-SCN-100 reweigh/reversal parity
SCALE-MIG-SCN-110 BMS competing-writer rejection
SCALE-MIG-SCN-120 rollback without physical replay
SCALE-MIG-SCN-130 target-role stabilization
SCALE-MIG-SCN-140 PHP caller-zero
SCALE-MIG-SCN-150 PostgreSQL parity

17. Evidence Packet¶

Every migration evidence packet records:

wave/scenario
source and target SHAs
environment/DB identity
tenant/profile/cohort
actor/role/capability
current and target routes
flow and stage policy version
request token
order/item/ticket/link/event IDs
manual/device source
before state
command payload fingerprint
current result
target result
field/state/link/event diff
UI/network/console evidence
child disposition
rollback result
cleanup/zero residue
PASS / FAIL / BLOCKED / NOT RUN

18. Cutover Definition Of Ready¶

Before SCALE-W4:

flow policy accepted;
Sales/Export contradiction resolved in plan and tests;
roles/capabilities accepted;
schema/indexes/request store ready;
ticket number reservation ready;
Check-in all-flow fixtures pass;
BMS writer scope known;
rollback/cohort router ready;
CTC regression pass;
no unverified device dependency.

Before SCALE-W5:

owner preparation contract accepted;
Scale Out all-flow fixtures pass;
child result UI accepted;
timeout/partial-result recovery pass.

Before caller-zero:

BMS overlapping writer retired;
all target roles pass;
Wiki current under separate effect approval;
observation has no critical defect;
rollback rehearsal passed;
exact caller search is zero or accepted compatibility-only.

19. Stop Conditions¶

Stop the wave when:

flow/stage direction is being guessed;
a device contract is invented from the “Live Weight” label;
one request would dual-write;
BMS and YMS both remain authoritative for the same MK ticket;
request idempotency or rollback is missing;
target role/tenant/record scope is unproven;
owner child failure would be hidden behind Scale success;
correction/reversal loses event lineage;
current CTC behavior regresses;
Production/device/DB/Wiki effect lacks explicit authorization.

---¶

Source: docs/processes/MK_PHYSICAL_SCALE_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.

MK Physical Scale Parity And Cutover Matrix¶

1. Migration Objective¶

2. Gate Vocabulary¶

3. Global Activation Blockers¶

4. Read Parity Matrix¶

Read parity stop conditions¶

5. Write Parity Matrix¶

6. UI Parity Matrix¶

7. Role And Record Parity¶

8. Data Parity Matrix¶

Schema verification before write activation¶

9. Flow Direction Parity Gate¶

10. Transaction And Partial-Result Parity¶

10.1 Check-in¶

10.2 Check-out¶

10.3 Reversal¶

11. Performance And Operational Parity¶

12. Migration Waves¶

SCALE-W0 — characterization¶

SCALE-W1 — flow policy and current defect disposition¶

SCALE-W2 — TypeScript reads¶

SCALE-W3 — React/Next.js read-only¶

SCALE-W4 — integrated Check-in one writer¶

SCALE-W5 — Check-out preparation and Scale Out¶

SCALE-W6 — child owner dispositions¶

SCALE-W7 — correction/reversal¶

SCALE-W8 — optional device¶

SCALE-W9 — BMS competing-writer retirement¶

SCALE-W10 — stabilization and Wiki¶

SCALE-W11 — PHP caller-zero¶

SCALE-W12 — PostgreSQL later¶

13. One-Writer Matrix¶

14. Rollback Matrix¶

15. Caller-Zero Inventory¶

16. Stable Migration Scenarios¶

17. Evidence Packet¶

18. Cutover Definition Of Ready¶

19. Stop Conditions¶

---¶

`SCALE-W0` — characterization¶

`SCALE-W1` — flow policy and current defect disposition¶

`SCALE-W2` — TypeScript reads¶

`SCALE-W3` — React/Next.js read-only¶

`SCALE-W4` — integrated Check-in one writer¶

`SCALE-W5` — Check-out preparation and Scale Out¶

`SCALE-W6` — child owner dispositions¶

`SCALE-W7` — correction/reversal¶

`SCALE-W8` — optional device¶

`SCALE-W9` — BMS competing-writer retirement¶

`SCALE-W10` — stabilization and Wiki¶

`SCALE-W11` — PHP caller-zero¶

`SCALE-W12` — PostgreSQL later¶