MK Physical Scale Source Authority

• Status: CURRENT SOURCE-AUTHORITY MAP / POLICY AND RUNTIME ACCEPTANCE REQUIRED
• Capability: MK physical Scale ticket execution
• Process: PROC-YMS-SCALE-TICKET-EXECUTION-MK
• Operating profile: mk-order
• Source baseline: qa@4f6165bc4c53a7d98b0c246392dd9ed5bd75c21c
• Rebuild packet: MK_PHYSICAL_SCALE_CAPABILITY_REBUILD_PACKET.md
• Effect boundary: documentation only; no Runtime, DB, device, role, Wiki or deployment change

---

1. Authority Rule

Use the following ownership order.

Product/profile intent
-> approved Process meaning and policy
-> current source-reconciled behavior
-> current schema/data authority
-> operator Runbook and Wiki projection
-> target React/Next.js/TypeScript/device-adapter migration contract

Current PHP/JavaScript source proves current implementation behavior. It does not by itself approve:

• the Gross/Tare direction for every business flow;
• zero-weight policy;
• correction, void or reversal authority;
• direct BMS mutation of a YMS-owned ticket;
• physical-device integration;
• role/capability policy;
• target API/DB design.

Where the current Process document and current source disagree, this source-authority map records the discrepancy. The Process owner must then update the Process contract or accept an explicit compatibility disposition.

---

2. Current Source Families

2.1 Process and Product input

Source	Current use
docs/processes/MK_SCALE_TICKET_EXECUTION_WORKFLOW.md	Existing Process contract, reconstructed on 2026-07-17. Several current-source statements are now stale and require reconciliation.
docs/processes/MK_INBOUND_PURCHASE_WORKFLOW.md	Owns Purchase receipt finalization after Scale checkout.
docs/processes/MK_OUTBOUND_SALES_WORKFLOW.md	Owns Outbound order and post-Scale status/timestamp changes.
docs/tasks/P2-006.md	Defines Physical Scale as a later bounded implementation wave and requires device-independent intake, accepted units, correction/void/reversal lineage and CTC regression.

2.2 YMS Scale API and transaction wrapper

Source	Current use
app/systems/YMS/scale/api_routes.php	Schedule/ticket/detail/event queries, integrated Check-in, Check-out, Purchase finalize, walk-in and delete routes.
app/shared/api/route_helpers.php	apiRouteRunLegacyWrite() owns one local DB transaction around each API write callback.
app/systems/YMS/scale/query_handler.php	Routes YMS Scale reads to shared MK query helpers.
app/systems/OMS/inbound-order/mk_query_helper.php	Current Schedule, open-ticket and ticket-detail read models.
app/systems/OMS/inbound-order/mk_post_helper.php	Current ticket stage, event, correction, void/reversal, order-link and Purchase-finalize behavior.
app/systems/OMS/outbound-order/post_handler.php	Current atomic Outbound order Save used by integrated Check-in.

2.3 Current UI

Source	Current use
frontend/pages/system/YMS/scale/scale-portal.php	Current Scale Portal shell and static 00000 lb live-weight display.
public/assets/js/modules/yms/scale-portal.js	Flow schema, Schedule/Yard UI, integrated Check-in, sequential Check-out orchestration, Purchase branch selection, print and recovery messages.
public/assets/css/yms/scale-portal.css	Current presentation only.

2.4 Print/output

Source	Current use
frontend/pages/system/BMS/scale-ticket/scaleticket.php?IDS[]=...	Physical Scale Ticket browser output. Current source applies page-role access plus tenant and active-row predicates.
frontend/pages/system/BMS/scale-ticket/scaleticket.php?ORDER_ID=...	Separate Sales Weight Ticket projection, gated by MK document workflow config. It is not the physical-ticket owner.

2.5 Cross-surface BMS writers

Source	Current use
app/systems/BMS/scale-ticket/api_routes.php	Generic BMS create/PATCH/delete, Closing and Outbound Weight Apply routes against the same ticket family.
app/systems/BMS/scale-ticket/post_handler.php	Delegates generic ticket writes to BMS transaction helpers.
app/systems/BMS/transaction/post_helper.php	Generic ticket PATCH/delete and linked Transload metric synchronization. It does not use the full YMS stage/event/downstream-guard contract.

2.6 Schema and audit

Source	Current use
.agents/rules/DB_SCHEMA.md	Current data authority: T_SCALE_TICKET; T_SCALE_TICKET_EVENT owns append-only correction/void lineage.
scripts/migrations/2026-08-02_p2_006_scale_ticket_event_forward.sql	Event schema, identity and indexes.
T_LOAD.TICKET_NUMBER	Order-side ticket-number projection.
T_TRANSLOAD.SCALE_TICKET_ID	Purchase/transload ticket link.
T_EQUIPMENT_LOAD.SCALE_TICKET_ID	Sales/equipment-load ticket link.

2.7 Existing verification assets

Source	Current coverage
tests/yms_scale_checkin_execute_contract.test.mjs	Static contract that integrated Check-in uses one legacy transaction and currently forces WEIGHT_PREFIX='GROSS' for all flows.
scripts/p2_scale_safety_smoke.js	Local Playwright/DB coverage focused on Client-2 Purchase Gross-in/Tare-out, reweigh events, checkout, reversal and cleanup.
tests/basic_operations_continuity_contract.test.mjs	Static continuity assertions around P2 surfaces.

No current evidence in this wave proves Sales/Export physical flow, a real device feed, Production behavior or target-role field acceptance.

---

3. Current Source-Confirmed Behavior

3.1 Integrated Check-in

Current UI calls:

POST /api/yms/scale/check-in/execute

The server callback performs:

validate FLOW and item rows
-> save/create Purchase or Sales order and items
-> create/update Scale ticket
-> bind ticket to Transload or Equipment Load
-> flush local sync tasks
-> commit once

Because the complete callback runs inside apiRouteRunLegacyWrite(), current integrated Check-in is one local DB transaction. A callback exception rolls back the order/item/ticket/link work performed inside that request.

This replaces the older primary-path description in which the browser always performed independent pre-save requests before Check-in.

Important limit

A client timeout or connection loss still does not cancel an already executing server transaction. The client must reread the exact ticket/order/link before retry.

3.2 Check-out

Current Check-out is not one business transaction.

header PATCH
-> zero or more item PATCH/POST calls, sequentially
-> POST /api/yms/scale/check-out
-> for Sales/Export: later Outbound close PATCH
-> for Purchase/Doortrade: later branch/finalize command selected by user

Consequences:

• an earlier header/item update can commit before a later item or Scale Out failure;
• Scale Out can commit before Outbound close sync fails;
• Purchase checkout can commit while Purchase finalize remains pending or fails;
• retry must resume from the last confirmed owner boundary, not replay the whole screen.

3.3 Ticket stages and event lineage

T_SCALE_TICKET has no single lifecycle status. Current state is derived from:

GROSS_TIME and Gross axle weights
TARE_TIME and Tare axle weights
DELETED_AT

YMS stage writes currently include:

• first-stage create;
• same-stage repeat with identical values returning the existing ticket result;
• pre-checkout reweigh only with a required reason;
• compare-and-swap over the current stage snapshot;
• append-only REWEIGH_CORRECTION event;
• second-stage prerequisite checking;
• duplicate second-stage identical result handling;
• rejection of changed completed-stage replay;
• Gross/Tare total consistency validation;
• reasoned TICKET_VOID / TICKET_REVERSAL event;
• downstream-execution guard before delete/reversal;
• transactional link detachment and order ticket-number cleanup when allowed.

3.4 Read models

Current YMS reads are tenant scoped and active-row scoped.

GET /api/yms/scale/schedule
GET /api/yms/scale/tickets?OPEN_ONLY=1
GET /api/yms/scale/tickets/{id}
GET /api/yms/scale/tickets/{id}/events

The open-ticket query returns tickets with exactly one stage populated. A completed ticket leaves the open board, but exact detail remains queryable by known ticket ID while active.

3.5 Timeout

Current Scale Portal uses a 30-second AbortController timeout.

client abort after 30 seconds
!= server transaction cancellation

The visible client message correctly instructs the user to refresh before retry. No durable request token currently guarantees idempotent replay across a lost response.

3.6 Print

Current physical-ticket output now applies:

• requirePageRoleAccess('scaleticket') when directly entered;
• current CLIENT_ID predicate;
• DELETED_AT IS NULL predicate.

The older Process statement that the IDS[] path lacks tenant/deleted predicates is stale for the current qa source.

Print remains a nondurable browser output. It does not record a completed business effect.

3.7 Live weight

The current page renders:

00000 lb

No repository source in this wave establishes a physical-device adapter, device session, signed reading, polling channel or authoritative live-weight source. Any external call to window.setScaleLiveWeight() is not a durable device contract.

---

4. Critical Current Contract Discrepancy

SCALE-DISCREPANCY-001 — UI flow direction versus integrated Check-in

The current UI flow schema defines:

Flow	Intended UI first stage	Intended UI second stage
Doortrade	Gross	Tare
Purchase	Gross	Tare
Export	Tare	Gross
Sales	Tare	Gross
Other/Walk-In default	Tare	Gross

However, the current integrated Check-in path does all of the following for every accepted flow:

UI payload WEIGHT_PREFIX = GROSS
UI aggregates item Gross into GROSS_STEERING_WEIGHT
server overwrites WEIGHT_PREFIX = GROSS
server writes aggregate Gross to GROSS_STEERING_WEIGHT
static contract test explicitly requires the all-flow Gross behavior

The current board and Check-out use the flow schema to determine the expected entry stage. For Sales/Export, they expect TARE_TIME before Gross checkout.

Therefore the source contains a direct contract contradiction:

Sales/Export integrated Check-in writes Gross
but
Sales/Export board/checkout expects Tare first

Potential consequences requiring local Runtime characterization:

• an outbound ticket may not appear as IN_YARD;
• the active board may omit the ticket;
• Check-out may reject because the expected Tare first stage is absent;
• flow inference and operator labels may disagree with stored stage data;
• current static tests may preserve the defect instead of detecting it.

This document does not claim a Production incident without field evidence. It does classify the contradiction as a write-path activation blocker for any Scale migration and as a high-priority Runtime defect candidate.

Required evidence:

Purchase Gross -> Tare
Doortrade Gross -> Tare
Sales Tare -> Gross
Export Tare -> Gross

with exact UI, API, DB, board, detail, event and cleanup evidence.

---

5. Other Current Risks And Gaps

ID	Current source fact	Risk / required disposition
SCALE-GAP-010	Integrated Check-in has no durable request token.	Response-loss replay can create or reapply work; add request identity/readback.
SCALE-GAP-020	Ticket number generation reads the latest number and increments it.	Concurrent Check-in can collide; adopt tenant-scoped atomic sequence or retry under stable request identity.
SCALE-GAP-030	Check-out header/items are sequential API calls.	Partial owner Save can precede Scale Out; add an accepted checkout preparation command or explicit child result.
SCALE-GAP-040	Sales/Export Outbound close is later than Scale Out.	Ticket complete can coexist with order close failure; expose independent checkpoint and recovery.
SCALE-GAP-050	Purchase branch/finalize follows Scale Out.	Checkout complete does not imply receipt/lot completion; preserve owner handoff.
SCALE-GAP-060	BMS generic PATCH/delete writes the same ticket family through different logic.	Can bypass YMS stage CAS, reason/event lineage and complete downstream guard; reconcile/retire or strictly separate ownership.
SCALE-GAP-070	Per-action API capability is not explicit; routes use module/menu entry.	Map view/check-in/check-out/reweigh/reverse/print separately.
SCALE-GAP-080	Live weight has no accepted device source.	Manual input must remain explicit; future device data needs adapter/session/provenance.
SCALE-GAP-090	Completed ticket is removed from the normal open board.	Provide exact completed readback and event timeline in target UI.
SCALE-GAP-100	UI can inject nonpersistent demo cards when the yard is empty.	Prevent demo interaction from resembling Production work or move it to an explicit demo/test mode.
SCALE-GAP-110	Text fields are length-normalized and axle weights are integers.	Field/UOM/precision contract must be explicit before PostgreSQL.
SCALE-GAP-120	Browser timestamps are used for some order updates while ticket stages use DB time.	Clarify physical event time versus UI request time and canonical timezone.
SCALE-GAP-130	YMS and BMS update linked Transload/equipment/order projections differently.	Define one ticket owner and explicit projection commands.
SCALE-GAP-140	No real device/runtime evidence was run in this documentation wave.	Keep device/field claims NOT RUN.

---

6. Current Data Authority

Entity	Current authority	Important mirrors/links
Physical ticket	T_SCALE_TICKET	T_LOAD.TICKET_NUMBER
Correction/void/reversal lineage	T_SCALE_TICKET_EVENT	none; append-only evidence
Purchase ticket link	T_TRANSLOAD.SCALE_TICKET_ID	T_LOAD.TICKET_NUMBER
Sales ticket link	T_EQUIPMENT_LOAD.SCALE_TICKET_ID	T_LOAD.TICKET_NUMBER
Purchase receipt result	Inbound Purchase owner	ticket is evidence/input, not receipt owner
Outbound close result	Outbound Sales owner	ticket completion is not order completion
Physical device reading	UNKNOWN / NOT IMPLEMENTED AS ACCEPTED ADAPTER	page live-weight text is not authority
Physical-ticket print	browser projection	no durable print status

---

7. Current Actor And Access Evidence

Source-confirmed:

• YMS Scale API routes require module yms.scale and menu route scale-portal.
• Direct physical-ticket print requires page role scaleticket.
• Tenant context comes from the authenticated request/session.

Not source-confirmed as accepted policy:

• separate capability for view, Check-in, Check-out, reweigh, reverse, event history and print;
• manager/recovery owner;
• record-level assignment restriction;
• device operator identity;
• Client-1 versus Client-2 negative matrix;
• whether BMS Scale Ticket access may mutate MK YMS tickets.

Target capability names proposed for review:

yms.scale.view
yms.scale.check-in
yms.scale.check-out
yms.scale.reweigh
yms.scale.reverse
yms.scale.events.view
yms.scale.print
yms.scale.reconcile

Do not branch business logic on numeric role ID, username or CLIENT_ID.

---

8. Target Ownership Direction

React Scale Workspace
-> Next.js authenticated adapter
-> TypeScript Scale Application
-> Scale Flow/Stage Policy
-> Scale Ticket Repository
-> Ticket Event Repository
-> Order/Transload/Equipment link adapters
-> MySQL first

A future physical-device path, when approved, is separate:

Device Adapter
-> Device Session / Reading Envelope
-> operator-selected accepted reading
-> Scale Command

The device adapter does not directly mutate business tables.

Core Check-in/Check-out remains synchronous local work. A Node worker is not required unless a separately accepted asynchronous device/provider effect exists.

---

9. Migration Source Rule

Migration reads this source family in the following order:

1. Product/profile and Process policy
2. this source-authority map
3. complete capability packet
4. current schema and event migration
5. current YMS API and route transaction wrapper
6. current Scale Portal UI
7. current BMS competing writers
8. local Runtime/role/device evidence
9. one-writer/cutover packet

Do not copy:

• all-flow Gross Check-in without an accepted flow policy;
• browser-sequenced Check-out child writes;
• BMS generic mutation bypass;
• demo-row injection;
• static live-weight display as a device contract;
• numeric tenant/role assumptions.

---

10. Evidence Ceiling

Current source behavior:
SOURCE-RECONCILED

Current schema/event design:
SOURCE-RECONCILED

Purchase local smoke coverage:
EXISTING SCRIPT / NOT RUN IN THIS WAVE

Sales/Export flow:
CONTRACT CONTRADICTION / RUNTIME EVIDENCE REQUIRED

Physical device:
NOT ESTABLISHED

Target-role field acceptance:
NOT RUN

Current T_WIKI_PAGE:
NOT READ

M4 migration authorization:
NOT ESTABLISHED

---

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