MK Physical Scale — Current Source Refresh — 2026-08-10¶
- Status:
CURRENT SOURCE-RECONCILED DOCUMENTATION / RUNTIME, DB, ROLE AND PHYSICAL EVIDENCE NOT RUN - Task:
CTC-CDOC-003 - Process:
PROC-YMS-SCALE-TICKET-EXECUTION-MK - Operating profile:
mk-order - Packet baseline:
qa@4f6165bc4c53a7d98b0c246392dd9ed5bd75c21c - Queue creation baseline:
qa/master@44a8866954075787c3d3a696460a4b7c26484325 - Current source baseline reviewed:
master@8981a02f7b2a2fa256a7365d6921f3d7636f1fe2 - Baseline relation:
8981a02f7b2a2fa256a7365d6921f3d7636f1fe2is one documentation-only commit ahead of44a886...; the only changed path isdocs/tasks/CTC_CLOUD_PARALLEL_DOCUMENTATION_QUEUE_2026-08-10.md. - Effects performed: repository source/history inspection and documentation only.
- Phase impact:
NONE
1. Current-source precedence¶
This refresh supersedes stale Scale statements in older packets where they conflict with current source.
current source @ 8981a02...
> accepted business policy
> source-reconciled packet
> historical packet / old smoke expectation
The current source establishes the implemented direction and route shape. It does not prove deployed Runtime identity, database contents, target-role access, device behavior, field acceptance, M3 or M4.
2. Source files reviewed¶
Primary current owners:
| Source | Current responsibility |
|---|---|
app/systems/YMS/scale/api_routes.php |
integrated Check-in/Check-out routes, ticket reads, relationship guard, Purchase finalize/walk-in adapters |
app/systems/YMS/scale/query_handler.php |
Scale query dispatch |
app/systems/OMS/inbound-order/mk_query_helper.php |
schedule, ticket and order-side read models |
app/systems/OMS/inbound-order/mk_post_helper.php |
ticket creation/update, stage guards, events, reweigh, void/reversal and links |
app/systems/OMS/outbound-order/post_handler.php |
Outbound order atomic Save used by integrated flow |
public/assets/js/modules/yms/scale-portal.js |
four-flow UI schema, entry/exit stage labels, request orchestration and recovery messaging |
frontend/pages/system/YMS/scale/scale-portal.php |
current Scale Portal shell/live-weight presentation |
app/systems/BMS/scale-ticket/api_routes.php |
competing generic BMS ticket writer surface |
app/systems/BMS/scale-ticket/post_handler.php |
BMS write dispatch |
tests/yms_scale_checkin_execute_contract.test.mjs |
current static route/transaction/relationship contract |
scripts/p2_client2_scale_workflow_crud_smoke.js |
historical/runtime-oriented smoke asset; not executed here |
Documentation/history reviewed includes the current rebuild packet, source-authority map, 2026-08-08 current-baseline refresh, 2026-08-09 post-refresh branch delta, Process workflow and queue instructions.
3. Four-flow current implementation¶
| Flow | Business direction | Check-in stage | Check-out stage | Current integrated command |
|---|---|---|---|---|
PURCHASE |
inbound purchase | GROSS |
TARE |
/check-in/execute then /check-out/execute |
DOORTRADE |
inbound/local | GROSS |
TARE |
/check-in/execute then /check-out/execute |
SALES |
outbound/local | TARE |
GROSS |
/check-in/execute then /check-out/execute |
EXPORT |
outbound/ocean | TARE |
GROSS |
/check-in/execute then /check-out/execute |
Current scale-portal.js and api_routes.php agree on these four stage directions.
Inbound Check-in¶
For Purchase/Doortrade, ymsScaleApiExecuteCheckin():
validate flow and items
-> save/create inbound order + items
-> assert persisted active item count
-> set WEIGHT_PREFIX=GROSS
-> aggregate commodity Gross into GROSS_STEERING_WEIGHT
-> SCALE_IN
-> create/reuse ticket link
-> return ORDER_ID + SCALE_TICKET_ID + TICKET_NUMBER
This request executes inside one apiRouteRunLegacyWrite() transaction.
Outbound Check-in¶
For Sales/Export:
save/create outbound order + items
-> set WEIGHT_PREFIX=TARE
-> do not overwrite ticket TARE from commodity Gross in the current route
-> SCALE_IN
-> create/reuse Equipment Load ticket link
-> return exact IDs
This closes the old “Gross for every flow” source contradiction. It does not prove the entered Tare is physically correct.
Check-out¶
Current source exposes:
POST /api/yms/scale/check-out/execute
The command validates the order-ticket bridge before order mutation:
Purchase/Doortrade -> T_TRANSLOAD.INBOUND_ORDER_ID + SCALE_TICKET_ID
Sales/Export -> T_EQUIPMENT_LOAD.OUTBOUND_ORDER_ID + SCALE_TICKET_ID
Then it saves the order/items and performs SCALE_OUT in the same local request transaction.
For non-Export flows the route derives the exit prefix and axle aggregate from item rows:
Purchase/Doortrade -> TARE
Sales -> GROSS
Export keeps GROSS as the UI/flow exit stage, but the server-side integrated Check-out deliberately does not synthesize the Gross axle value from commodity items. The submitted ticket payload therefore remains material and requires Runtime/field evidence.
Purchase finalization and any later outbound business completion remain separate owning-process outcomes; Scale ticket completion does not imply receipt, inventory, packing, delivery or booking completion.
4. GROSS, TARE and NET semantics¶
GROSS / TARE¶
T_SCALE_TICKET stores separate Gross and Tare stage timestamps and axle-weight columns. Current YMS stage guards require:
- no negative axle value;
- at least one positive axle value for the submitted stage;
- first/second-stage ordering;
- same-stage compare-and-swap protection for correction;
- identical completed-stage replay can return the existing result;
- changed completed-stage replay is rejected.
NET¶
For order commodity rows, non-Export integrated Check-in validates when weight values are present:
Gross > 0
Tare >= 0
Tare < Gross
Net > 0
Net == Gross - Tare
Ticket-stage authority remains Gross/Tare axle evidence. NET is not a third physical ticket stage. Any business NET value is a derived/order-item result and must not be confused with completion of either physical Scale stage.
5. Weight and unit contract¶
Current Scale evidence is pound-based:
- UI live-weight presentation is
lb; - ticket event rows record
INPUT_UOM='LB',CANONICAL_UOM='LB',DISPLAY_UOM='LB'; - ticket axle weights are normalized as integers.
No current Scale source reviewed here establishes a KG-to-LB or other physical-unit conversion adapter. T_LOAD_ITEM.UOM may carry order-item units, but that is not evidence that the Scale ticket converts arbitrary item UOM values into pounds.
Therefore:
physical Scale ticket canonical unit = LB in current source
cross-UOM conversion = NOT SOURCE-CONFIRMED
A future non-LB reading requires explicit conversion/provenance policy rather than silent arithmetic.
6. Same-ticket update versus new ticket¶
Current YMS helper behavior is lineage-preserving:
- a Scale-in command first resolves the order and any existing ticket identity/link;
- when an active existing ticket is found for the order, the helper routes to
CHECKIN_UPDATErather than blindly generating another ticket; - otherwise a new ticket number/ticket row is created and linked;
- stage correction uses the existing ticket ID, requires the applicable reason, and records immutable event evidence.
This is not a durable request-token idempotency contract. A lost response can leave the caller uncertain whether a new ticket or an update committed.
7. Record/state guards¶
Current source guards include:
- tenant-scoped active ticket reads;
- required
scale-portalmenu route on YMS routes; - valid four-flow classification for integrated commands;
- active commodity/item requirements;
- order-ticket bridge ownership before integrated Check-out mutation;
- first-stage-before-second-stage;
- stage snapshot compare-and-swap for correction;
- required correction/reversal reason where applicable;
- downstream execution checks before ticket delete/reversal;
- active-row predicates on ticket/event reads.
The derived ticket states remain evidence-oriented rather than a persisted single lifecycle status:
no stage -> NOT_STARTED
entry stage only -> ENTRY_RECORDED
entry + exit -> COMPLETED
soft-deleted pre-complete-> VOIDED
soft-deleted complete -> REVERSED
inconsistent lineage -> CONFLICT / evidence required
unknown response result -> UNKNOWN until reread
Flow policy is required to decide which timestamp is entry versus exit.
8. Response loss and retry¶
The Scale Portal has a client timeout; client abort does not prove server rollback.
Required recovery rule:
timeout / connection loss
-> do not blind replay
-> reread exact order
-> reread exact ticket by stable ID/number when known
-> reread T_TRANSLOAD or T_EQUIPMENT_LOAD link
-> reread ticket events
-> classify committed boundary
-> retry only the missing command
No durable request token was located for the integrated Scale commands. In-process identical stage behavior helps only after the ticket identity is known; it does not replace lost-response reconciliation.
9. Correction, void and reversal¶
Current YMS source provides:
- pre-checkout reweigh with required reason;
- stage compare-and-swap;
- append-only
REWEIGH_CORRECTIONevidence; - reasoned
TICKET_VOID/TICKET_REVERSAL; - downstream execution guard;
- transactional link detachment and order ticket-number cleanup when reversal is allowed.
The generic BMS ticket writer still targets the same ticket family through different semantics. This remains a one-writer/correction-authority conflict for future migration and must not be “resolved” by this documentation task.
10. Physical-versus-system boundary¶
No accepted physical device adapter is established by current repository source.
operator/device produced a physical reading
!= browser displayed a number
!= API request submitted
!= DB transaction committed
!= downstream business process completed
The 00000 lb/live-weight presentation is not physical provenance. A DB-complete Scale stage does not prove the truck/equipment actually entered, exited, was positioned correctly, or that a device reading was authoritative.
11. Stale/historical statements retired from current interpretation¶
The following statements are now historical/stale for current source:
| Older statement | Current disposition |
|---|---|
Integrated Check-in forces GROSS for all four flows |
STALE; current server uses inbound GROSS, outbound TARE |
| Sales/Export direction conflict is still present in current source | STALE AS CURRENT FACT; original discrepancy closed in source |
/api/yms/scale/check-out/execute is absent |
STALE; route exists in current source |
| Check-out always requires separate header/item browser writes before Scale Out | STALE FOR CURRENT PRIMARY INTEGRATED PATH; current integrated route owns order/item Save + Scale Out in one request |
| current static contract requires all-flow Gross | STALE; test now asserts inbound Gross/outbound Tare and integrated Check-out route |
| Scale smoke route expectation is necessarily mismatched with source | STALE; current test/source route align |
Historical documents remain useful evidence of the evolution and must not be deleted by this task.
12. Open policy and evidence gaps¶
Still open:
- exact target-role permission for view/check-in/check-out/reweigh/reverse/print;
- whether generic BMS mutation remains an authorized compatibility writer;
- physical-device identity, calibration, reading session and provenance;
- canonical handling for non-LB physical readings;
- exact Export Check-out Gross source and operator expectations;
- field policy for reweigh/reversal authority;
- database installation/current population of event schema;
- deployed Runtime identity;
- physical observation for all four flows;
- Client 1 non-regression and Client 2 expected-role behavior.
13. Current disposition¶
documentation: SOURCE-RECONCILED
current source: four-flow direction reconciled
runtime: NOT RUN
database: NOT READ
role: NOT VERIFIED
physical/device: NOT VERIFIED
field acceptance: NOT ESTABLISHED
M3/M4: NOT CLAIMED
Phase progress: NONE
---¶
Source:
docs/reconstruction/MK_PHYSICAL_SCALE_CURRENT_SOURCE_REFRESH_2026-08-10.md— ctc repository · This page is an English translation of the source document. Identifiers, file paths and code symbols are unchanged.