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

Physical Scale — Current Source Operator And Support Addendum¶

Status: CURRENT-SOURCE REPOSITORY RUNBOOK / ENVIRONMENT AND ROLE EVIDENCE REQUIRED
Current source ref: qa/master@a71386e3baf176534939a42397249bcd2b535c49
Trade refresh: MK_TRADE_CURRENT_LINEAGE_AND_SOURCE_REFRESH_2026-08-08.md
Allocation refresh: MK_INVENTORY_ALLOCATION_CURRENT_BASELINE_AND_CALLER_REFRESH_2026-08-08.md
Scale refresh: MK_PHYSICAL_SCALE_CURRENT_BASELINE_AND_CALLER_REFRESH_2026-08-08.md
Phase implementation: USER HOLD
Important: this is a repository procedure draft, not proof of current Wiki publication or role acceptance.

1. Scope¶

Use this addendum when investigating or recovering current MK issues involving:

Trade Summary / Deal Ledger
Export Brokerage
Outbound Cost
Packing Rate and browser outputs
Inventory Allocation Workbench
Physical Scale Portal and ticket lineage

It does not authorize a source, DB, role, provider, device or Wiki change.

2. Shared Investigation Contract¶

For every issue, record first:

source/deployed SHA
environment/database
CLIENT_ID and profile
actor/subject/role
page and API route
record IDs
before state
reported action/time
response/error/request ID
expected result

Then follow:

stop replay
-> reread authoritative local rows
-> identify last committed owner boundary
-> classify missing / committed / partial / conflicting / unknown
-> resume only the missing owner step after separate authorization

Do not repair by direct row editing merely because a query or page looks inconsistent.

3. Trade Summary / Deal Ledger¶

3.1 Current meaning¶

Trade Summary is a derived read model.

CLOSED
= AP or AR amount exists under current query rules
!= accounting close
!= settlement

SHIPPED
= shipping evidence exists and no current AP/AR amount

CLAIMED filter
= negative derived margin plus amount evidence
!= stored claim state

3.2 Investigation¶

identify the Equipment ID;
reread the Deal Link row;
reread Equipment AP/AR transactions and active lines;
reread Outbound AP cost rows;
compare confirmed/closed status predicates;
compare deleted-row treatment;
recalculate totals and derived state;
correct only the owning source record when separately authorized.

3.3 Do not¶

edit a Trade row as if it were authoritative;
call CLOSED an accounting close;
use CSV as durable evidence;
conceal missing source classes by adjusting a displayed total.

4. Export Brokerage¶

4.1 Current boundary¶

Export Brokerage creates or compensates several child families in a local transaction, but current source has no durable Job/request identity or immutable child manifest.

Generated marker presence helps provenance:

[EB:generated]
[EB:generated-booking]

Marker presence alone does not prove a complete child set.

4.2 Create response missing¶

stop resubmission;
identify expected Container/Booking/Order inputs;
search generated Equipment and Booking markers;
reread Purchase, Transload, Lot, Outbound, Equipment Load and Allocation children;
classify:

NO CHILD EVIDENCE
COMPLETE CHILD SET
PARTIAL OR AMBIGUOUS CHILD SET

retry only when absence is proven and separately authorized.

4.3 Cancel response missing¶

reread every known child;
check Delivery/Transload/Inventory progression;
identify which compensation steps committed;
do not repeat a complete cancel blindly;
escalate when a downstream owner has progressed.

4.4 Do not¶

delete children by hand;
treat markers as a Job ledger;
compensate Delivery, physical work or consumed Inventory from the parent page;
recreate the entire child set after a timeout.

5. Outbound Cost¶

5.1 Current meaning¶

Outbound Cost is a local AP transaction linked to an Outbound Order. It is not a universal Cost subtype in schema.

Current mutable status set:

CREATED
OPEN
DRAFT

5.2 Safe investigation¶

identify exact Outbound Order ID;
list all active AP transaction candidates;
identify the exact Transaction ID shown/edited;
reread active lines and file links;
check current status;
compare submitted header/line set with current rows.

5.3 Response missing¶

exact transaction exists with expected complete line set
-> treat local Cost as committed

no candidate exists
-> missing may be considered after full reread

multiple mutable candidates
-> stop and escalate

5.4 Do not¶

assume latest AP is always Outbound Cost;
repeat Create while the first result is unknown;
edit confirmed/closed rows through a compatibility path;
infer file or QBO state from local Cost state.

6. Packing Rate And Browser Outputs¶

6.1 Rate update result¶

Current API can skip invalid item IDs and still succeed when at least one item updates.

Required verification:

intended unique item IDs
returned updated count
exact rate reread for every intended ID

Only when every intended item matches the expected rate is the output ready for print review.

6.2 Browser output boundary¶

rendered/printed
!= saved file
!= approved
!= emailed
!= confirmed
!= provider delivered

6.3 Do not¶

print immediately after an unresolved autosave;
treat a browser amount as persisted when it is transient;
treat Purchase order number as an Invoice lifecycle state;
treat Sales Weight ORDER_ID output as physical Scale evidence.

7. Inventory Allocation¶

7.1 Current source identity¶

Inventory Lot
+ source Order Item

Current target identity:

Outbound Sales Order
+ target Item
+ Equipment/Equipment Load bridge

Current accepted relation:

T_LOAD_ALLOCATION

7.2 Before an Apply issue investigation¶

Reread:

source Lot status and received date;
inbound and remaining quantity/weight;
current active allocation rows;
target order/item/container bridge;
target item state;
current allocated sums.

Current source list can include OPEN and PARTIAL Lots with positive remaining net weight.

7.3 Apply response missing¶

stop replay;
search target items created at/after the request;
search matching allocation relations;
reread Lot remaining weight and quantity;
classify:

NO COMMIT EVIDENCE
COMPLETE SINGLE COMMIT
DUPLICATE OR CONFLICTING COMMIT
PARTIAL ADJACENT CONFLICT
UNKNOWN

do not repair balance in the same investigation.

7.4 Balance mismatch¶

Current Apply immediately decrements remaining net weight but not necessarily remaining quantity.

A mismatch requires classification:

expected deferred synchronization
source correction after allocation
active relation missing/deleted
true integrity conflict
unknown

Do not normalize quantity/weight based on a guessed ratio.

7.5 Adjacent writer conflict¶

When Inbound, Outbound or Booking was changed after Allocation:

preserve the allocation relation;
identify the owning correction command;
verify allocated-item delete/update guards;
do not use ordinary Outbound Save as an allocation correction tool.

8. Physical Scale¶

8.1 Current first-stage warning¶

Current source contains a contradiction:

integrated Check-in writes Gross for every flow

Scale Portal expects:
Purchase/Doortrade Gross first
Sales/Export Tare first

Do not describe either side as accepted target policy until four-flow evidence is completed.

8.2 Check-in response missing¶

Reread:

order and items;
Scale ticket ID/number;
Gross/Tare stage timestamps and weights;
Transload or Equipment Load link;
event history;
request correlation if safely available.

Do not create a second order/ticket while the first result is unknown.

8.3 Check-out partial result¶

The current browser sequence can commit in multiple API requests.

Classify separately:

header committed
items committed
Scale-out committed
downstream Outbound close committed
Purchase finalization committed

Resume only the missing owner step.

8.4 Reweigh/reversal¶

Current YMS flow requires reasoned event lineage and downstream guards. Generic BMS update/delete paths do not represent the full YMS correction contract.

Do not use generic BMS writes to bypass:

event history;
compare-and-swap checks;
downstream execution guards;
transactional link detachment.

8.5 Device boundary¶

The displayed live weight is not proof of a current device adapter.

Before claiming live integration, verify:

device/service identity
connection type
unit/precision
calibration owner
reading timestamp
loss/reconnect behavior
manual-entry distinction

Do not connect, command or calibrate a device under this documentation procedure.

9. Role And Access Diagnosis¶

For every reviewed action build one row:

module
menu/page
read API
write API
actor predicate
record predicate
state predicate
visible control
expected allow/deny

Do not solve a mismatch by:

granting Administrator broadly;
copying Client 1 numeric roles to another tenant;
enabling all modules;
bypassing state guards;
testing permission by executing a consequential action.

10. Evidence Packages¶

RBR-TRADE-001
RBR-ALLOC-001
RBR-SCALE-001

Current state:

DEFINED
NOT AUTHORIZED
NOT RUN

Completion of a static source refresh does not change M3/M4.

11. Escalation Packet¶

Collect:

source/deployed SHA
environment/DB/CLIENT_ID
actor/subject/role
page/API
record IDs
current rows/states
request/correlation ID
last confirmed owner boundary
partial/unknown classification
provider/file/device boundary
cleanup/reversal owner
current Wiki procedure if known

Exclude credentials, signatures, broad customer data, session payloads and unapproved document content.

12. Current State¶

Trade lineage/current source:
REFRESHED

Allocation baseline/current callers:
REFRESHED

Physical Scale baseline/current callers:
REFRESHED

Current DB/role/browser/physical evidence:
NOT RUN

Accepted policy:
OPEN / PARTIAL

M3:
NO

M4:
NO

---¶

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