MK Inventory Allocation — Current Source Refresh — 2026-08-10¶

Status: CURRENT SOURCE-RECONCILED / READ-ONLY EVIDENCE NOT RUN
Task: CTC-CDOC-002
Process: PROC-OMS-INVENTORY-TO-OUTBOUND-ALLOCATION-MK
Operating profile: mk-order
Source baseline actually reviewed: master@f82a91f596e6d3ed636c102b458b3dd07d8475be
Prior focused refresh baseline: qa/master@a71386e3baf176534939a42397249bcd2b535c49
Baseline relationship: prior focused baseline is an ancestor; reviewed HEAD is 586 commits ahead in the repository comparison
Phase Transformation: USER HOLD
Runtime / database / role / provider / physical / Wiki effects: NONE
Read-only evidence definition: RBR-ALLOC-002-READONLY-PREFLIGHT.md

1. Scope And Evidence Level¶

This document refreshes the MK Inventory Allocation current-source contract only. It corrects stale route, UI, predicate and concurrency statements found in earlier packets without changing Runtime behavior or declaring environment verification.

repository source at master@f82a91f596e6d3ed636c102b458b3dd07d8475be
= SOURCE-RECONCILED

database rows / schema actually queried
= NOT RUN

target-role browser/API behavior
= NOT RUN

runtime concurrency / response-loss behavior
= NOT RUN

M3 / M4
= NO

Current source takes precedence over the earlier 2026-08-08 semantic packets where they disagree.

2. Exact Current Owner Set¶

Owner	Blob SHA	Current responsibility
`frontend/pages/system/OMS/allocation/mk-allocation-workbench.php`	`4e0af1183da1248f16cd934d8f9460f2142819ce`	Workbench shell, initial query-string context, current UI asset loading
`public/assets/js/modules/oms/allocation-workbench.js`	`21c9b03e8edf7bdc51a8f89591e29ecb24d3e01e`	browser query state, target selection, partial allocation drafts, Apply payload and readback refresh
`app/systems/OMS/allocation/api_routes.php`	`155667c3b43d1bbd5886f048b16ae2785645dac4`	current Allocation query and Apply route registration
`app/systems/OMS/allocation/query_handler.php`	`130d3d8b69594a3a55baa9e4cd610d21aacdf2f6`	Workbench and target-autocomplete query dispatch
`app/systems/OMS/allocation/allocation_query_helper.php`	`3b55d878c7f2d5d9d8e42a081c727a05c0d8fa78`	current source-lot, target-shipment and allocation read-model predicates
`app/systems/OMS/allocation/post_handler.php`	`035056fc74fa95f314b55c6710dc1e5da2fa5921`	`APPLY_WORKBENCH` command adapter
`app/systems/OMS/inbound-order/mk_post_helper.php`	`0b3310497bcb550290e14f508d9b52a0f96fc381`	shared MK write implementation: target item, allocation relation and source-lot weight mutation

The first six focused owners retain the blobs recorded by the earlier refresh. The shared writer does not: repository comparison from a71386e3... to the reviewed HEAD shows substantial later changes in mk_post_helper.php. Therefore the 2026-08-08 packet cannot be treated as a complete current command contract without this refresh.

3. Current Entry, APIs And Call Chain¶

Current page:

?page=mk-allocation-workbench

Current HTTP API family:

GET  /api/oms/allocations/workbench
GET  /api/oms/allocations/target-shipments
GET  /api/oms/allocations/allocatable-lots/search
POST /api/oms/allocations/apply

Current write chain:

Allocation Workbench browser
-> POST /api/oms/allocations/apply
-> apiRouteRunLegacyWrite()
-> omsAllocationPostHandle(..., APPLY_WORKBENCH, ...)
-> mk_sales_order_post_handle(..., APPLY_WORKBENCH, ...)
-> mk_sales_order_insert_allocated_item(...)
-> T_LOAD_ITEM
-> T_LOAD_ALLOCATION
-> conditional T_INVENTORY_LOT.REMAIN_NET_WEIGHT decrement
-> current bridge/projection synchronization
-> response ORDER_ID / ORDER_NUMBER / ITEM_IDS
-> Workbench reread

The browser uses the aggregate /oms/allocations/* routes. Older /api/oms/allocation-workbench/sources, /targets, and /apply names are not the current route contract.

4. Current Source Identity And Eligibility¶

4.1 Source lot identity¶

Persisted source authority is the inventory lot:

T_INVENTORY_LOT.ID

Its lineage includes SOURCE_ORDER_ID, SOURCE_ORDER_ITEM_ID, and SOURCE_TRANSLOAD_ID where present in the current schema/data. Browser row identity is not allocation authority.

Current source-list predicates include:

tenant match
IL.DELETED_AT IS NULL
IL.LOT_STATUS IN ('OPEN', 'PARTIAL')
IL.RECEIVED_DATE IS NOT NULL
IL.REMAIN_NET_WEIGHT > 0
source item absent/empty or not in ALLOCATED/COMPLETED/TRANSLOADED

Active allocation projections join only T_LOAD_ALLOCATION.DELETED_AT IS NULL.

4.2 PARTIAL lots¶

PARTIAL is a current list-eligible lot state when the other source predicates pass. The browser exposes partial-lot counts and stale-partial diagnostics, and current editable basket rows allow an operator to stage less than the full remaining weight.

This corrects the older packet statement that current UI was full-lot-only.

4.3 Target identity¶

The target authority is an existing Outbound Sales T_LOAD. Current read models additionally depend on the equipment/equipment-load bridge and container/size context. Apply creates a new target T_LOAD_ITEM; it does not create the target shipment.

The complete query predicate and the write predicate are not one shared policy object. A row being visible remains a projection, not proof that the command will or should accept the same state.

5. Allocation Field Semantics¶

5.1 `OUTBOUND_ORDER_ITEM_ID`¶

Current Apply creates a new T_LOAD_ITEM first. The generated T_LOAD_ITEM.ID is then persisted as T_LOAD_ALLOCATION.OUTBOUND_ORDER_ITEM_ID.

OUTBOUND_ORDER_ITEM_ID
= exact created target line identity
!= browser-selected target order ID
!= source order item ID
!= a client-supplied demand-line identity

5.2 `ALLOCATED_NET_WEIGHT`¶

The command DTO uses ALLOCATED_WEIGHT; the persisted relation uses ALLOCATED_NET_WEIGHT.

For an allocation write, current source requires positive allocated weight, verifies it does not exceed the read lot balance, sets the created target item's effective NET_WEIGHT to the allocated weight, inserts that weight into T_LOAD_ALLOCATION.ALLOCATED_NET_WEIGHT, and conditionally subtracts the same amount from T_INVENTORY_LOT.REMAIN_NET_WEIGHT.

These names must not be treated as interchangeable DTO/database field names even though they represent the same accepted weight at this command boundary.

5.3 Allocation quantity/weight identity¶

Current browser payload:

ALLOCATED_INVENTORY_LOT_ID
ALLOCATED_WEIGHT
QUANTITY
SOURCE_MODE = WAREHOUSE
UOM
REMARK
optional RATE

Current persisted allocation relation:

INVENTORY_LOT_ID
ALLOCATED_QUANTITY
ALLOCATED_NET_WEIGHT
ALLOCATED_RATE
REMARK

Important asymmetry:

Apply immediately decrements REMAIN_NET_WEIGHT
Apply does not immediately decrement REMAIN_QUANTITY

Quantity and weight are therefore separate persisted dimensions. No universal UOM conversion or quantity-to-weight invariant is accepted by this source review.

5.4 Source / leftover relationship¶

For this Allocation command, the source is an active received T_INVENTORY_LOT with source-order/source-item lineage. No separate LEFTOVER_* identity or separate leftover allocation record is used by the reviewed Allocation owners.

“Leftover” belongs to adjacent inventory-adjustment/final-loading semantics where source consumption can create or preserve inventory lots and ledger provenance. Allocation consumes the resulting current lot; it must not infer a second source from a historical “leftover” label.

current allocation source authority
= T_INVENTORY_LOT + source lineage

leftover terminology
= adjacent inventory provenance / historical business description
!= a second Allocation relation identity

Any stronger mapping between a particular leftover adjustment and an allocation requires current data/ledger evidence and is not inferred here.

5.5 Soft delete and state rules¶

Current source consistently treats active source lots and active allocation relations through DELETED_AT IS NULL. Current allocation readback must distinguish active relations from soft-deleted historical rows.

Current source does not establish a general public reverse/unallocate state transition. Soft deletion must not be assumed to be an authorized business reversal simply because DELETED_AT exists.

6. Persisted Authority Versus Derived UI State¶

Surface/value	Classification	Reason
`T_INVENTORY_LOT.ID`, source lineage	persisted authority	exact source lot and provenance
`REMAIN_NET_WEIGHT`	persisted current balance	conditionally mutated by Apply
`REMAIN_QUANTITY`	persisted/projection value	not immediately decremented by Apply
`T_LOAD_ALLOCATION.ID`	persisted allocation relation	exact accepted source-to-target relation
`OUTBOUND_ORDER_ITEM_ID`	persisted target-line identity	points to Apply-created `T_LOAD_ITEM`
`ALLOCATED_QUANTITY`, `ALLOCATED_NET_WEIGHT`	persisted allocation snapshot	accepted quantity/weight
Workbench `manualLotIds`, `rowDrafts`, selected commodity/target	browser-derived	convenience state only
displayed `PARTIAL_LOT_COUNT`, stale-partial badge	derived query/UI	diagnostic projection
target open-demand/progress bars	derived UI/query	not a command success predicate
success notice	transient UI	not authoritative readback
source/target list visibility	query projection	must be rechecked by command/evidence

7. Current Predicate And Effect Chain¶

Page/UI
-> GET /api/oms/allocations/workbench
   + GET /api/oms/allocations/target-shipments
   + optional GET /api/oms/allocations/allocatable-lots/search
-> browser stages editable allocation weight / quantity / rate / remark
-> POST /api/oms/allocations/apply
-> target order / bridge validation
-> source lot tenant + active row + remaining-weight validation
-> create target T_LOAD_ITEM
-> create active T_LOAD_ALLOCATION
-> conditional source-lot weight decrement
-> bridge/projection sync
-> ORDER_ID / ORDER_NUMBER / ITEM_IDS response
-> GET Workbench reread

The command does not re-express every source-list predicate. In particular, this review does not find one command-level predicate that identically rechecks all LOT_STATUS, received/source-item, target lifecycle/progress and demand conditions from the read model.

8. Duplicate, Concurrency, Partial And Response-Loss Semantics¶

8.1 Duplicate request¶

No durable allocation request token or idempotency key is present in the reviewed current command contract.

A complete replay after a committed response loss can create a second target item/allocation if enough source weight remains. If the repeated weight no longer fits, the conditional balance mutation can reject the request. Neither outcome is a safe substitute for idempotent reconciliation.

unknown result
-> reread target items + active allocations + exact lot balance
-> identify whether the intended relation already exists
-> do not blind replay

8.2 Concurrent same-lot Apply¶

Current shared writer contains a conditional update:

UPDATE T_INVENTORY_LOT
SET REMAIN_NET_WEIGHT = REMAIN_NET_WEIGHT - ?
WHERE ...
  AND REMAIN_NET_WEIGHT >= ?

and requires exactly one affected row.

This is a source-level weight oversubscription guard and corrects the older Process statement that no conditional balance predicate existed.

It does not prove the live database isolation mode, retry/deadlock behavior, or every multi-request outcome. Those remain NOT RUN.

8.3 Partial allocation¶

Current UI permits a positive ALLOCATED_WEIGHT up to current displayed REMAIN_NET_WEIGHT, an independent positive integer QUANTITY, optional rate/remark, and Use Full Remain as a convenience rather than a mandatory policy.

The source supports a partial-weight command shape. It does not establish a universal quantity/weight conversion policy or the required lot lifecycle status after partial consumption.

8.4 Response loss¶

The browser has no durable pending-command identity. A missing/error response does not prove rollback. Reconciliation must use persisted IDs and balances, not toast state or the draft basket.

9. Explicitly Stale Or Historical Statements¶

Earlier statement/reference	Current disposition
`/api/oms/allocation-workbench/sources`	`STALE ROUTE NAME`; current aggregate read route is `/api/oms/allocations/workbench`
`/api/oms/allocation-workbench/targets`	`STALE ROUTE NAME`; current target route is `/api/oms/allocations/target-shipments`
`/api/oms/allocation-workbench/apply`	`STALE ROUTE NAME`; current write route is `/api/oms/allocations/apply`
“UI has no partial-lot amount editor”	`STALE`; current UI has allocation-weight and quantity inputs
“UI copies full remaining quantity/weight and only full-lot Apply is possible”	`STALE`; full remain is optional
source eligibility `LOT_STATUS='OPEN'` only	`STALE`; current query accepts `OPEN` and `PARTIAL`
“no conditional balance predicate; concurrent Apply can overdraw”	`STALE AS SOURCE FACT`; current writer has conditional remaining-weight mutation; runtime concurrency remains unverified
target semantic request token	`TARGET DESIGN`, not current source
general reverse/unallocate command	`NOT SOURCE-CONFIRMED`; do not infer from soft delete columns

The older documents remain historical/reconstruction inputs. This task does not edit them because they are outside CTC-CDOC-002 ownership.

10. Open Policy And Evidence Gaps¶

Still open:

authoritative quantity-versus-weight consumption rule by UOM;
exact lot-status transition policy after partial or full allocation;
accepted correction/reversal owner and immutable lineage;
durable idempotency/request identity;
target lifecycle/progress predicates that must block Apply;
target open-demand enforcement;
role/capability and record-scope acceptance;
exact relationship between inventory-adjustment Source/Leftover ledger events and later MK allocation source lots;
current DB indexes/constraints/precision and active-row integrity;
runtime concurrency, timeout and response-loss evidence.

These gaps are evidence/policy gaps, not Phase implementation authorization.

11. Completion Statement¶

Exact current source baseline:
PINNED at master@f82a91f596e6d3ed636c102b458b3dd07d8475be

Current owner list:
RECONCILED

Current routes / UI / command DTO:
RECONCILED

OUTBOUND_ORDER_ITEM_ID / ALLOCATED_NET_WEIGHT:
RECONCILED FROM SOURCE

PARTIAL lot behavior:
CURRENT QUERY + UI SUPPORT CONFIRMED FROM SOURCE

persisted versus derived state:
SEPARATED

stale route / packet claims:
EXPLICITLY CLASSIFIED

read-only preflight:
DEFINED / NOT RUN

Runtime / DB / role effects:
NONE

Phase progress:
NONE

M3 / M4:
UNCHANGED / NO

---¶

Source: docs/reconstruction/MK_INVENTORY_ALLOCATION_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.