Skip to content

Loader Work Assignment — Current Caller And Guard Inventory 2026-08-08

  • Status: CURRENT SOURCE-RECONCILED CALLER INVENTORY / RUNTIME AND DATA EVIDENCE REQUIRED
  • Repository baseline: qa/master@e18aa7e5ab64b626b525d46d5db074f26e10fa06
  • Runtime source lineage reviewed through: 13991b627eb95b5b675a4eb05048d56f20538439
  • Parent source authority: LOADER_WORK_ASSIGNMENT_CURRENT_SOURCE_CONTRACT_2026-08-08.md
  • Evidence worksheet: RBR-AWCO-002-EVIDENCE-WORKSHEET.md
  • Process umbrella: PROC-TMS-INBOUND-PLANNING
  • Program state: PHASE IMPLEMENTATION USER HOLD
  • Effects: documentation and source inspection only; no Runtime, DB, role, provider, Wiki, deployment, or physical effect

1. Purpose

The current repository contains two materially different Loader Work Assignment implementations in the same Runtime family.

Current Board / Loader Route implementation
= QUEUE_WORK_ASSIGNMENT
+ COMMODITY_NAME
+ FINAL_DRAFT

Typed helper implementation
= ASSIGNMENT_DATA
+ requestToken
+ advisory lock
+ typed notification and Clock Out metadata

The earlier source-authority document established that the two contracts coexist. This inventory answers the next question:

Which current source files include, call, read, write, guard, or present each contract?

This is required before any operational correction or later migration because a function can be:

  • present but not registered as a Route;
  • included by Runtime but called only as a compatibility helper;
  • used by current guards while its main command family is not used;
  • exercised only by scripts or source-string tests;
  • current in source but absent from the deployed database;
  • current for one writer and invisible to another writer.

No field incident is declared from source inspection alone.

2. Source Set Reviewed

Current Route and UI family

app/systems/TMS/transload/api_routes.php
frontend/pages/system/TMS/transload/loader-assignment-board.php
frontend/pages/system/TMS/transload/inbound-loader.php

Typed helper and current compatibility consumers

app/systems/TMS/transload/assignment_work_helper.php
app/systems/TMS/transload/post_helper.php
app/systems/TMS/staff-time/api_routes.php

app/systems/TMS/transload/loader_transition_evidence.php
app/platform/process/TransitionAuditStore.php
app/utils/KJDatabase.php

Supporting checks and historical evidence

tests/unit/loader_work_assignment_contract_test.php
tests/unit/loader_assignment_work_contract_test.php
scripts/loader_assignment_work_concurrency_smoke.php
scripts/loader_assignment_work_final_break_smoke.php
docs/operations/loader-assignment-work-clock-out/*

Repository symbol search was used to locate direct static references. Dynamic calls, database state, deployed source identity, route execution, and field behavior still require separate evidence.

3. Inclusion And Ownership Matrix

File Includes typed helper Owns active Route or command Reads/writes Route representation Reads/writes typed representation Current significance
transload/api_routes.php Yes Yes Yes Uses selected shared helper functions Current API owner plus compatibility consumer
transload/post_helper.php Yes Yes, for legacy/current transload commands Current Load/Planner rows Uses terminal guard/locking helpers Current cross-writer compatibility surface
staff-time/api_routes.php Yes Yes General Clock events Reads typed assignment rows for Clock Out bypass guard Current Staff Time owner with one-contract visibility
assignment_work_helper.php self Defines typed command/query family No primary Route-row create Yes Mixed: reusable guards are current; full typed command family has no direct Route/UI caller located
loader-assignment-board.php N/A UI caller Yes No direct typed contract call located Current Office Board presentation
inbound-loader.php N/A UI caller Yes No direct typed contract call located Current Loader mobile/workflow presentation
smoke scripts Yes Test fixture only Limited/fixture-dependent Yes Historical/local engineering evidence, not Runtime caller proof

Source-level disposition

assignment_work_helper.php
!= safely dead code

It is included by current Runtime owners, and selected lock/guard/read helpers are called by current source.

assignment_work_helper.php full typed command family
!= proven current application owner

Repository symbol search did not locate direct current Route/UI registrations for its create, admin-update, admin-list, loader-read, transition, or typed Clock Out command functions. This does not prove that no dynamic invocation exists, but no direct static application caller was located in this review.

4. Active Route Contract And Callers

The current Route family is registered under:

POST   /api/tms/transloads/work-assignments
GET    /api/tms/transloads/work-assignments
GET    /api/tms/transloads/work-assignments/current
POST   /api/tms/transloads/work-assignments/{id}/start
POST   /api/tms/transloads/work-assignments/{id}/complete
DELETE /api/tms/transloads/work-assignments/{id}
POST   /api/tms/transloads/work-assignments/{id}/advance-clock-out
POST   /api/tms/transloads/work-assignments/{id}/clock-out

Office caller

loader-assignment-board.php presents current Office actions and calls the active Route family.

The visible Board workflow includes:

  • select Loader(s);
  • select Cleaning, Mechanical, Other Work, or Clock Out;
  • send and assign;
  • inspect per-Loader result;
  • list current/historical Route-owned assignments.

Loader caller

inbound-loader.php presents the current Loader assignment panel and calls:

  • current assignment read;
  • Start;
  • Work Complete;
  • Clock Out advancement;
  • Clock Out completion.

The page maintains a workAssignment state and a dedicated Loader assignment section.

Active persistence

The Route family writes:

T_LOADING_PLANNER.SPECIAL_INSTRUCTION = 'QUEUE_WORK_ASSIGNMENT'
T_LOADING_PLANNER.COMMODITY_NAME = assignment type
T_LOADING_PLANNER.FINAL_DRAFT = JSON detail
T_LOADING_PLANNER.ASSIGNMENT_DATA = not used as primary Route payload

The Route create contract does not expose the typed helper's durable canonical request token.

5. Typed Helper Contract And Located Consumers

assignment_work_helper.php defines a complete typed model with:

  • schemaVersion=1;
  • canonical UUID requestToken;
  • typed assignment payload;
  • type-specific allowlists;
  • per-Loader advisory lock;
  • duplicate lookup by request token;
  • Telegram attempt metadata;
  • cancellation metadata;
  • typed Clock Out cleaning and Final Break state;
  • conditional state transitions.

Functions with no direct current Route/UI caller located

Repository symbol search found no direct current Route/UI caller for:

transload_assignment_work_create
transload_assignment_work_admin_update
transload_assignment_work_admin_list
transload_assignment_work_loader_read
transload_assignment_work_transition
transload_assignment_clock_out_cleaning_complete
transload_assignment_clock_out_final_break
transload_assignment_clock_out_complete

Some are called by helper-local functions or smoke scripts. Their existence and source tests do not prove that the current Board or Loader page executes them.

Shared functions used by current Runtime owners

Current source does call selected helper functions, including:

transload_assignment_work_assert_no_terminal_clock_out
transload_assignment_work_with_lock
transload_assignment_work_with_loader_locks
transload_assignment_work_for_loader

This creates a mixed dependency:

current Route writer
+ typed-only guard/read implementation
= cross-contract visibility risk

6. Guard And Visibility Matrix

Guard / reader Called by Rows it can see Rows it cannot prove it sees Risk
transload_assignment_work_assert_no_terminal_clock_out Work helper, Break queue creation, current Transload writers ASSIGNMENT_DATA.type='CLOCK_OUT' Route-owned COMMODITY_NAME='CLOCK_OUT' rows without matching ASSIGNMENT_DATA Work/Break/Load can be admitted after a Route-owned terminal Clock Out
transload_assignment_work_for_loader Typed Loader query and general Staff Time Clock Out guard ASSIGNMENT_DATA IS NOT NULL active rows Route-owned QUEUE_WORK_ASSIGNMENT rows without ASSIGNMENT_DATA General Clock Out guard can miss a Started Route-owned Clock Out
tmsTransloadApiWorkAssignmentHasQueuedClockOut Active Route create QUEUE_WORK_ASSIGNMENT plus COMMODITY_NAME='CLOCK_OUT' Typed Clock Out rows with blank Route markers Active Route create can miss a typed terminal Clock Out
active Route current/list readers Board/Loader Route family Route-owned markers and FINAL_DRAFT Typed rows without Route markers Current UI can omit typed rows
typed helper admin/Loader readers typed helper family ASSIGNMENT_DATA IS NOT NULL Route-owned rows without typed payload Typed UI/commands, if activated, can omit Route rows

Required invariant

Every current and future writer that can place Work, Load, Break, or Clock Out into the shared Loader queue must use one terminal decision that recognizes every accepted current representation.

Current source does not establish that invariant across both representations.

7. Confirmed Source Discrepancy A — Terminal Clock Out Guard

Typed guard predicate

JSON_UNQUOTE(JSON_EXTRACT(ASSIGNMENT_DATA, '$.type')) = 'CLOCK_OUT'
AND JOB_STATUS IN ('SCHEDULED', 'STARTED')

Active Route Clock Out identity

SPECIAL_INSTRUCTION = 'QUEUE_WORK_ASSIGNMENT'
COMMODITY_NAME = 'CLOCK_OUT'
FINAL_DRAFT = JSON detail

Current callers affected by the typed-only guard

Source search locates the guard in:

  • assignment_work_helper.php;
  • transload/api_routes.php, including Break queue creation;
  • transload/post_helper.php, including current Load/Planner writers.

Source-level conclusion

Route-owned Clock Out
may be invisible to current writers that call the typed-only terminal guard.

Potential effects:

  • Break queued after terminal Clock Out;
  • ordinary Work or Load placed after terminal Clock Out;
  • queue ordering and end-of-shift assumptions diverge;
  • later cleanup has to interpret multiple terminal rows.

Evidence boundary

source discrepancy: CONFIRMED
current DB occurrence: NOT READ
field reproduction: NOT RUN
operator impact: NOT ESTABLISHED

Evidence scenario:

AWCO-RUN-031

8. Confirmed Source Discrepancy B — General Clock Out Bypass Guard

The general Staff Time Clock Out endpoint performs this protection:

  1. call transload_assignment_work_for_loader();
  2. inspect active rows returned from ASSIGNMENT_DATA IS NOT NULL;
  3. block when a typed Clock Out is STARTED;
  4. otherwise proceed with the general local Clock Out and release scheduled assignments.

A Started active Route-owned Clock Out uses QUEUE_WORK_ASSIGNMENT and FINAL_DRAFT, not the typed row predicate.

Source-level conclusion

Started Route-owned Clock Out
may be invisible to the general Staff Time Clock Out bypass guard.

This can violate the accepted workflow invariant:

Started Clock Out assignment
-> workflow-owned Clock Out action only
-> general Clock Out must not bypass cleaning/final-Break prerequisites

Evidence boundary

source discrepancy: CONFIRMED
current DB occurrence: NOT READ
API/browser reproduction: NOT RUN
local event duplication or cleanup effect: NOT ESTABLISHED

Priority evidence scenarios:

AWCO-RUN-050 — general Clock Out while Route-owned Clock Out is Started
AWCO-RUN-051 — cleaning prerequisite bypass attempt
AWCO-RUN-052 — final-Break prerequisite bypass attempt

These IDs are reserved by this inventory and should be added to the worksheet result ledger when executed.

9. Confirmed Source Discrepancy C — Final Break Representation

Active Route implementation

The active Route Clock Out flow creates a separate Planner Break row:

SPECIAL_INSTRUCTION = 'QUEUE_BREAK'
COMMODITY_NAME = '10MIN BREAK'
FINAL_DRAFT.clockOutAssignmentId = Route Clock Out planner ID
Route Clock Out FINAL_DRAFT.finalBreakId = Break planner ID

Clock Out completion waits for the linked Break planner row to reach FINISHED.

Typed helper implementation

The typed Clock Out flow does not require a separate Break planner row. It writes and reads:

T_STAFF_TIME_EVENT.BREAK_IN
T_STAFF_TIME_EVENT.BREAK_OUT
JOB_SOURCE_TYPE = 'LOADING_PLANNER'
JOB_SOURCE_ID = typed Clock Out planner ID

The ten-minute state is derived directly from Staff Time events.

Source-level conclusion

Final Break identity and completion authority differ by contract.

This affects:

  • Break visibility;
  • timer ownership;
  • auto-close behavior;
  • duplicate detection;
  • recovery after response loss;
  • event and planner cleanup;
  • future migration read model.

A canonical contract cannot simply combine the JSON payloads; it must choose the authoritative Break identity and define compatibility for the other representation.

10. Confirmed Source Discrepancy D — Cancellation State

The typed helper persists:

JOB_STATUS = 'CANCELED'

The active Route family persists and queries:

JOB_STATUS = 'CANCELLED'

The active Route list is also scoped to Route-owned markers, so typed rows can be absent for both representation and state reasons.

Required decision

Do not add a third status. The canonical application contract must:

  1. inventory current persisted values;
  2. normalize both spellings at the application boundary;
  3. choose one new-write value only after caller and query review;
  4. preserve old-row readability until row and caller cleanup is accepted.

11. Confirmed Source Discrepancy E — Request Identity And Duplicate Recovery

Typed helper

requestToken = canonical UUID
same Loader + same requestToken -> EXISTING
per-Loader advisory lock

Active Route

The current create handler accepts Loader/type/detail fields but does not expose the typed durable request token in its primary contract.

It inserts per Loader and attempts Telegram after the row is created.

Source-level conclusion

active create response loss
!= demonstrably safe blind retry

The operator/support procedure must continue to require current queue/list reread before another create.

A later correction should not introduce a separate duplicate system. It should choose one canonical command identity and apply it to the accepted writer.

12. Confirmed Source Discrepancy F — Notification Evidence

Active Route

  • sends through the current Telegram sender;
  • returns sent/failed separately from assignment creation;
  • updates LAST_SENT_TIME after success;
  • does not persist the typed helper's full attempt state in the Route payload.

Typed helper

Stores in ASSIGNMENT_DATA:

status
attemptCount
attemptedAt
lastError

and defines an explicit retry function.

Source-level conclusion

assignment state and notification-attempt evidence use different persistence contracts.

The later canonical command must preserve:

assignment commit
!= notification result

and provide one retry/reconciliation owner without creating another assignment.

13. Transition Audit Boundary

loader_transition_evidence.php defines a selected Business Transition writer for:

START_TRANSLOADING
Undo transition paths

It uses:

  • strict TenantExecutionContext;
  • PROC-TMS-INBOUND-PLANNING / 0.5.0;
  • BUSINESS_RECORD and KJ_MUTATION references;
  • TransitionAuditStore::appendInCallerTransaction().

This writer does not establish Transition Audit coverage for the non-load Work Assignment Route or typed helper command families.

selected Loader Transload transition evidence
!= all Loader assignment transitions audited

Current Work Assignment evidence remains primarily Planner, Staff Time, provider metadata, request diagnostics, and later accepted transition evidence.

14. Current Static Caller Classification

Symbol / surface Static current application caller located Classification
active /work-assignments Route functions Yes Current application path
Board Route calls Yes Current Office UI path
Loader Route calls Yes Current Loader UI path
typed create No direct Route/UI caller located Present source / candidate or compatibility command
typed admin_update No direct Route/UI caller located Present source / no current registration located
typed admin_list No direct Route/UI caller located Present source / no current registration located
typed loader_read No direct Route/UI caller located Present source / no current registration located
typed transition smoke scripts and helper-local use Engineering evidence, not current Route proof
typed terminal guard Yes Current compatibility dependency
typed per-Loader lock helpers Yes Current compatibility dependency
typed active-row reader Yes, Staff Time general Clock Out guard Current safety dependency with incomplete visibility

Interpretation rule

no static caller located
!= proven unreachable

A final retirement decision requires:

  • complete repository caller search;
  • dynamic registration review;
  • deployed source review;
  • database row inventory;
  • target-role and command evidence;
  • old-row compatibility plan.

15. Required Evidence Order

The detailed worksheet remains authoritative for execution. Based on this preflight, the first source/data sequence should be:

A. Read-only caller confirmation

AWCO-SRC-001 — Route registrations and UI calls
AWCO-SRC-002 — typed helper static/dynamic consumers
AWCO-SRC-003 — terminal guard callers
AWCO-SRC-004 — general Clock Out bypass guard
AWCO-SRC-005 — Final Break identity writers/readers
AWCO-SRC-006 — cancellation status readers/writers

B. Read-only DB population

counts by Route representation
counts by typed representation
counts containing both
active Clock Out rows by representation
CANCELED / CANCELLED counts
Final Break planner/event linkage
orphan/duplicate current rows

C. Smallest controlled runtime scenarios

AWCO-RUN-031 — later Break after Route-owned Clock Out
AWCO-RUN-032 — later Load/Work after Route-owned Clock Out
AWCO-RUN-050 — general Clock Out bypass against Started Route-owned Clock Out
AWCO-RUN-051 — cleaning prerequisite bypass attempt
AWCO-RUN-052 — final-Break prerequisite bypass attempt
AWCO-RUN-060 — missing create response and queue reread
AWCO-RUN-061 — Telegram failure recovery on existing row

No runtime scenario is authorized by this document.

16. Later Smallest-Safe Correction Sequence

Only after a named operational correction is explicitly authorized:

1. read current deployed source and DB population
2. reproduce one confirmed unsafe path in a disposable non-Production fixture
3. define one canonical current read predicate across both representations
4. repair terminal and general Clock Out guards first
5. add exact focused regression for both row representations
6. preserve current Board and Loader visible behavior
7. normalize read state before changing persisted status values
8. add durable request identity only through the accepted create owner
9. reconcile Final Break identity and notification evidence separately
10. observe target-role result and rollback
11. retire unused functions/rows only after caller-zero and row migration

Do not solve the discrepancy by:

  • merging all TMS logic into one larger shared helper;
  • adding a new generic Assignment table or framework;
  • dual-writing both JSON representations indefinitely;
  • rewriting current pages as part of the guard correction;
  • deleting the typed helper before current guard/read consumers are replaced;
  • declaring the Route representation canonical solely because the current UI calls it.

17. Target Canonical Contract Inputs

The later canonical application contract needs one answer for each:

Question Current divergence
Assignment identity planner ID plus optional request token
Create idempotency typed token versus Route reread/manual recovery
Type/detail ASSIGNMENT_DATA versus COMMODITY_NAME + FINAL_DRAFT
Terminal decision typed-only guard versus Route-only helper
Final Break separate Planner row versus Staff Time events on Clock Out row
Cancellation CANCELED versus CANCELLED
Notification attempt typed persisted attempt versus Route LAST_SENT_TIME and response
Current/list projection separate readers by representation
General Clock Out bypass typed rows only
Transition evidence selected Transload transition writer, not Work Assignment coverage

The target should expose one typed application model while compatibility adapters read current rows until migration and caller-zero are accepted.

18. Current Completion

Active Route registrations located: PASS
Current Board caller located: PASS
Current Loader caller located: PASS
Typed helper Runtime inclusion located: PASS
Typed full-command static caller search: PASS — no direct current Route/UI caller located
Terminal guard mismatch: CONFIRMED IN SOURCE
General Clock Out bypass mismatch: CONFIRMED IN SOURCE
Final Break representation divergence: CONFIRMED IN SOURCE
Cancellation spelling divergence: CONFIRMED IN SOURCE
Request/notification contract divergence: CONFIRMED IN SOURCE
Current DB population: NOT READ
Runtime reproduction: NOT RUN
Target-role evidence: NOT RUN
Provider evidence: NOT RUN
Canonical contract decision: OPEN
M3: NO
M4: NO

19. Maintenance

Update this inventory when:

  • Route registrations change;
  • Board or Loader UI callers change;
  • typed helper functions gain or lose callers;
  • terminal/general Clock Out guards change;
  • Final Break ownership changes;
  • cancellation/request/notification contracts are normalized;
  • current DB population is accepted;
  • the canonical application contract is selected;
  • compatibility functions or rows reach caller-zero.

---

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