Skip to content

MK Trade / Export Brokerage / Cost / Rate / Document Outputs — Current Lineage And Source Refresh — 2026-08-09

  • Status: CURRENT STATIC SOURCE REFRESH / ENVIRONMENT AND ROLE EVIDENCE REQUIRED
  • Historical packet baseline: d96498360bb9c3541a1b5f862284596a7ed217b9
  • Current refresh baseline: master@a71386e3baf176534939a42397249bcd2b535c49
  • Existing source authority: MK_TRADE_COST_RATE_DOCUMENT_OUTPUTS_SOURCE_AUTHORITY.md
  • Existing rebuild packet: MK_TRADE_COST_RATE_DOCUMENT_OUTPUTS_CAPABILITY_REBUILD_PACKET.md
  • Current effect matrix: MK_TRADE_CURRENT_CALLER_EFFECT_AND_OUTPUT_MATRIX_2026-08-09.md
  • Read-only evidence package: RBR-TRADE-001-READONLY-CURRENT-SURFACE-PREFLIGHT.md
  • Phase implementation: USER HOLD
  • Effects: repository source inspection and documentation only

1. Purpose

The original MK Trade packet was written while d964983... was being treated as a source baseline. That commit is not accepted as the current long-lived source authority. It belonged to a detached candidate line and must not be promoted merely because a detailed document referenced it.

This refresh re-anchors the family to the current long-lived lineage and separates:

current source fact
historical candidate observation
stable business meaning
open product policy
target reconstruction design
required environment evidence

The reviewed family contains several distinct capabilities:

Trade Summary projection
Export Brokerage orchestration
Outbound Order Cost
Packing Rate correction
Packing document
Purchase Local Invoice
Booking Confirmation
Sales Weight Ticket
Physical Scale Ticket evidence

They share references and UI entry points, but they do not share one transaction, one completion state, one role, or one recovery procedure.

2. Lineage Disposition

2.1 Historical candidate baseline

The historical packet baseline remains useful only as evidence of what was inspected at the time.

d964983...
= HISTORICAL CANDIDATE REFERENCE
!= current qa/master authority
!= current deployed source
!= accepted Runtime evidence

Candidate-only facts must be retained only when one of the following is true:

  1. the same source contract is independently present in current qa/master;
  2. the fact is explicitly labeled historical;
  3. the fact is a target design decision approved independently of the candidate.

2.2 Current authority

For this refresh, current facts are taken from the long-lived source lineage at the stated current baseline and from exact current owner files. A later source commit requires a new delta/refresh before this document is called current.

2.3 Current result

Original packet semantics:
MOSTLY REUSABLE AS DETAILED INPUT

Original baseline authority:
RETIRED AS CURRENT AUTHORITY

Candidate-only source assertions:
DO NOT INHERIT WITHOUT CURRENT SOURCE MATCH

Current environment data and role behavior:
NOT READ / NOT RUN

3. Capability Separation

3.1 Trade Summary

Trade Summary
= read-only, multi-source projection

It combines current commercial, order, booking, equipment, transaction, and shipping references. It does not own those records.

3.2 Export Brokerage

Export Brokerage
= composite local orchestration creating or compensating multiple child records

It can create a Purchase/Inbound side, inventory/equipment state, Booking relations, Outbound side, allocations, and compatibility markers. It does not become the permanent business owner of every child.

3.3 Outbound Cost

Outbound Cost
= AP transaction associated with an outbound order

Current source does not establish a standalone universal Cost aggregate merely because the UI presents one Cost panel.

3.4 Packing Rate

Packing Rate
= correction of Sales/Outbound load-item rate for Booking-linked items

It is not a document-only field and not a browser-only calculation.

3.5 Document outputs

Packing / Local Invoice / Booking Confirmation / Sales Weight Ticket
= browser-rendered output projections

Unless a separately approved owner stores a snapshot, file, email, or provider result, render/print is not durable completion.

4. Trade Summary — Current Contract

4.1 Current source family

Current navigation includes the Trade Summary/Deal Ledger surface and report-query helpers. The projection reads business sources rather than writing a Trade aggregate.

Representative source owners:

config/page_routes.php
frontend/pages/system/BMS/reports/mk-trade-summary.php
app/addons/reports/query_helper.php
related BMS/TMS/OMS query helpers

4.2 Derived status

The historical packet identified DEAL_STATUS as derived rather than persisted. Current reconstruction must preserve this distinction.

Conceptual current interpretation:

material AP or AR amount
-> CLOSED-like derived label

no amount + shipment markers
-> SHIPPED-like derived label

otherwise
-> OPEN-like derived label

The exact current threshold, included source classes, deleted-row policy, and shipment-marker precedence require current source and data evidence. The label must not be presented as accounting settlement, operational close, or irreversible workflow state unless a separately owned state proves it.

4.3 Claimed/exception filters

A negative-margin or claimed-style filter is a projection predicate, not a stored claim case. It must not be migrated as a durable claim workflow without an approved process owner.

4.4 Header/detail explainability

The current packet must continue to flag the following risk:

Header totals can aggregate more source classes
than the visible detail explains.

Target reconstruction must return a source breakdown with:

  • source class;
  • business record identity;
  • amount and sign;
  • included/excluded status;
  • deleted-row handling;
  • currency/UOM;
  • date policy;
  • selected order/booking/equipment relation;
  • conflict or ambiguity reason.

4.5 CSV boundary

Trade CSV
= a downloaded copy of the current projection
!= accounting export
!= immutable snapshot
!= provider delivery
!= reconciliation evidence

5. Export Brokerage — Current Contract

5.1 Current markers

Current source includes compatibility markers equivalent to:

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

These markers help identify generated records. They are not a durable orchestration identity.

marker present
!= Export Brokerage Job ID
!= immutable child manifest
!= idempotent request result
!= complete cancellation result

5.2 Current orchestration boundary

Representative current owners:

app/systems/OMS/export-brokerage/*
app/systems/OMS/inbound-order/*
app/systems/OMS/outbound-order/*
app/systems/TMS/booking/*
app/systems/BMS/transaction/*
app/shared/sync/*
frontend/pages/system/OMS/export-brokerage/mk-export-brokerage.php

The exact current create/cancel route and child list must be captured in the current caller/effect matrix and verified against current data before operational acceptance.

5.3 Response-loss risk

child set committed
-> response missing
-> operator repeats create
-> duplicate or conflicting child set possible

Likewise:

compensation committed or partially committed
-> response missing
-> operator repeats cancel
-> already-compensated child or balance can be processed again

The compatibility marker does not prove that a repeated request is the same command.

5.4 Target requirement retained

The future bounded aggregate remains:

ExportBrokerageJob
+ request token
+ input fingerprint
+ immutable/versioned child manifest
+ per-child disposition
+ create result
+ cancellation preview
+ compensation result
+ residual manifest

This is target design, not current Runtime.

5.5 Child authority

Export Brokerage may orchestrate a child, but each child retains its domain owner.

Child family Long-term owner
Inbound Purchase / Purchase Items OMS Inbound/Purchase
Booking TMS Booking
Outbound Sales / Items OMS Outbound/Sales
Inventory Lot / Allocation Inventory/Allocation
Equipment / Equipment Load YMS/TMS equipment owner
AP/AR Cost BMS Transaction
Scale evidence Scale owner

6. Outbound Order Cost — Current Contract

6.1 Persistence

The current implementation uses AP transaction records linked to an outbound order. The UI concept Outbound Cost is narrower than the general AP table but may not have a dedicated persisted subtype or unique owner constraint.

6.2 Ambiguity

When multiple active AP records exist for one outbound order, the system must answer:

Which AP is the outbound cost?
Which AP belongs to another expense process?
Which exact AP is updated or removed?

A compatibility fallback that chooses the latest AP when no transaction ID is supplied must not be copied into the target contract.

6.3 Update semantics

The historical packet identified replace-all line behavior and possible header-default loss. Current environment evidence must verify:

  • exact transaction ID selection;
  • allowed statuses;
  • line identity versus replace-all;
  • omitted header fields;
  • deleted-row behavior;
  • file-link behavior;
  • Trade Summary readback after save;
  • QBO/non-QBO independence.

6.4 Target command

CreateOutboundCost
UpdateOutboundCost
DeleteOutboundCost
CorrectOutboundCost

Each command requires:

  • exact outbound owner;
  • exact transaction identity;
  • expected version/status;
  • typed header patch or complete DTO;
  • explicit line intent;
  • decimal/UOM/rounding rules;
  • request token;
  • exact result reread;
  • unknown-result recovery.

7. Packing Rate — Current Contract

7.1 Current route

Current Booking API includes the Packing List rate correction surface for Booking-linked Sales/Outbound items.

PATCH /api/tms/bookings/{id}/packing-list/rates

Current access documentation records numeric route roles 1..6; current role acceptance remains unverified.

7.2 Current partial-result risk

The current handler validates candidate item IDs against:

same tenant
active Sales order item
active Sales/Outbound order
same Booking

Invalid or unrelated IDs can be skipped while valid IDs are updated. A single updated count does not prove that every intended row was processed.

7.3 Target result

Each requested item must return one disposition:

UPDATED
UNCHANGED
STALE
DENIED
NOT_FOUND
INVALID

A partially updated request must not be reported as complete merely because updated > 0.

7.4 Print/readback boundary

browser autosave requested
!= server commit confirmed
!= every item persisted
!= document ready

Print readiness requires a server reread of every intended rate and a source fingerprint for the rendered output.

8. Document Outputs — Current Contract

8.1 Common boundary

Rendered
!= Snapshot saved

Printed
!= Print acknowledged
!= Approved
!= Emailed
!= File stored
!= Process completed

8.2 Packing document

Current inputs can include:

  • Booking;
  • Sales/Outbound items;
  • Equipment Loads;
  • Equipment commodity/detail;
  • Rate;
  • editable browser-only notes or amount fields.

Current evidence must verify fallback behavior when equipment-level commodity coverage is incomplete and whether any browser input is actually persisted.

8.3 Purchase Local Invoice

Current formula behavior historically used unit-specific conversions and combined item amount, trucking fee, and credit. Current evidence must verify the exact formula, rounding, date/reference, guard, and whether the displayed invoice identity is a durable invoice lifecycle or an order-derived label.

8.4 Booking Confirmation

Current source includes a direct page guard, but the following remain policy/evidence questions:

  • Sales-reference precedence;
  • recipient/branding/template owner;
  • current-date use;
  • fixed versus tenant-configured text;
  • retention and file/email owner;
  • role/page/API parity.

8.5 Sales Weight Ticket

The current family has two meanings that must remain separate:

Order-derived Sales Weight Ticket
!= physical T_SCALE_TICKET evidence

A document can be rendered from Sales/Outbound information even when no physical scale record proves the measurement. The UI and Wiki must state the evidence source.

9. Current Source Drift Disposition

9.1 Directly retained current facts

The following remain valid current-source inputs after re-anchoring:

  • Trade Summary is a derived projection;
  • Export Brokerage is composite orchestration;
  • generated markers exist but are not job identity;
  • Outbound Cost uses general transaction infrastructure;
  • Packing Rate writes Sales/Outbound item rates;
  • document pages render current source data;
  • render/print does not establish durable delivery;
  • Sales Weight Ticket and physical Scale evidence are distinct.

9.2 Current-lineage changes requiring addenda

Current long-lived source contains changes after the historical packet around:

  • Booking and Packing API surfaces;
  • Street Turn create/revert and adjacent BMS/TMS helpers;
  • current Access decisions;
  • current Provider credential management;
  • Loader/Final Review operational surfaces.

These changes do not automatically alter Trade semantics, but they can change shared callers, route metadata, child ownership, and recovery evidence. They are therefore explicit cross-family handoffs.

9.3 Historical-only statements

Any statement that depends only on a detached candidate file or candidate-only caller must be marked:

HISTORICAL CANDIDATE EVIDENCE

It must not appear in a current Runbook or Wiki procedure.

10. Current Access And Effect Questions

The current route-level access packet must be applied separately to each consequential action.

Capability Access questions
Trade Summary page/menu/module and safe record disclosure
Export Brokerage create/cancel exact action role, child authority, tenant and state
Outbound Cost finance/office action role and exact transaction state
Packing Rate current numeric route roles versus accepted policy
Packing document read/render role and rate-edit separation
Local Invoice direct-page guard and business audience
Booking Confirmation page guard and document recipient authority
Sales Weight Ticket order-derived versus physical evidence access

No broad role restriction or broad role expansion is authorized by this refresh.

11. Unknown-Result Rules

11.1 Trade projection

Reread the projection and underlying source rows. Do not create a business row to make a report look complete.

11.2 Export Brokerage

response missing
-> search for the exact generated child set and markers
-> classify complete / partial / absent / conflict / unknown
-> do not repeat create or cancel while unknown

11.3 Outbound Cost

response missing
-> reread exact transaction ID and lines
-> reread outbound relation
-> repeat only when absence is proven

11.4 Packing Rate

response missing or partial count
-> reread every intended item rate
-> classify per item
-> correct only missing/stale items through the owner command

11.5 Documents

Rerender after authoritative source reread. A browser print dialog is not a durable result lookup.

12. Target React / Next.js / TypeScript Ownership

React
= display typed projections, per-child/per-item results, warnings, and recovery links

Next.js
= authenticated tenant-aware web/API adapter

TypeScript Application
= projection composition, command orchestration, policy, idempotency, result classification

Repositories
= explicit current MySQL source owners

Provider/File adapter
= only when a separately approved durable effect exists

Prohibited target structures:

  • one giant tradeService.ts owning all writes;
  • Route Handler SQL;
  • React-derived business status;
  • one generic JSON mutation endpoint;
  • one generic provider/outbox record for unrelated effects;
  • PHP and TypeScript dual writers;
  • simultaneous PostgreSQL cutover.

13. Evidence Required Before M3/M4

Source and caller

  • exact current files/blobs;
  • page/route/helper caller graph;
  • candidate-only fact register;
  • current generated-marker consumers;
  • current shared BMS/TMS/OMS helper dependencies.

Schema/data

  • current table/column/index inventory;
  • Trade source counts and source breakdown;
  • multi-AP outbound cases;
  • generated Export Brokerage child sets;
  • marker collisions/orphans;
  • Booking/Sales/Equipment relation integrity;
  • Packing Rate item coverage;
  • document source completeness;
  • file/link state where applicable.

Role/UI

  • intended and denied roles;
  • menu/page/direct URL;
  • read API and action API;
  • record/tenant/state denial;
  • mobile/keyboard/print behavior.

Recovery

  • create/cancel response loss;
  • partial child compensation;
  • ambiguous AP selection;
  • partial rate update;
  • browser save/print race;
  • document source change between preview and print.

Wiki

  • current named rows;
  • rendered content;
  • source/evidence labels;
  • role findability;
  • current versus target wording.

14. Current Disposition

Current-lineage re-anchor:
COMPLETE FOR DOCUMENTATION

Current source/caller static refresh:
COMPLETE FOR NAMED OWNERS

Candidate-only fact separation:
DEFINED

Current DB/schema/rows:
NOT READ

Current role/page/API behavior:
NOT RUN

Current browser/print behavior:
NOT RUN

Current Wiki:
NOT READ / NOT PUBLISHED

M3:
NO

M4:
NO

Phase progress:
NONE

15. Next Owner

Use the read-only RBR-TRADE-001 package to establish current source/data/role evidence. Do not select a canonical target writer or implement a migration until the current child identities, ambiguous transaction cases, rate partial-result behavior, and document-source boundaries are known.

---

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