Skip to content

Loader Work Assignment — Current Source Contract 2026-08-08

  • Status: CURRENT SOURCE-AUTHORITY CORRECTION / DUAL CONTRACT / EVIDENCE REQUIRED
  • Current source baseline: qa/master@13991b627eb95b5b675a4eb05048d56f20538439
  • Capability: Office-created Cleaning, Mechanical, Other Work, and Clock Out assignments in the Loader queue
  • Current Process umbrella: PROC-TMS-INBOUND-PLANNING
  • Current primary source:
  • app/systems/TMS/transload/api_routes.php
  • app/systems/TMS/transload/assignment_work_helper.php
  • current Assignment Board and Loader Page consumers
  • Historical decision/evidence:
  • docs/operations/2026-08-07-loader-assignment-work-and-clock-out-plan.md
  • docs/operations/loader-assignment-work-clock-out/*
  • Phase implementation: USER HOLD
  • Effect boundary: documentation only

1. Correction Summary

Current source contains two materially different representations for non-load Loader assignments.

Active route representation

T_LOADING_PLANNER.SPECIAL_INSTRUCTION = QUEUE_WORK_ASSIGNMENT
T_LOADING_PLANNER.COMMODITY_NAME = CLEANING / MECHANICAL / OTHER_WORK / CLOCK_OUT
T_LOADING_PLANNER.FINAL_DRAFT = JSON detail

Active routes:

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

Typed helper representation

T_LOADING_PLANNER.ASSIGNMENT_DATA = typed JSON
schemaVersion
requestToken
strict allowlists
Telegram attempt state
cancellation
Clock Out / Final Break fields

The current source includes both representations. Documentation must not describe either one as the sole current contract until caller and DB evidence establishes the authoritative path and migration state.

Correct status:

CURRENT SOURCE PRESENT
DUAL PERSISTENCE / HELPER CONTRACT
CURRENT CALLER AND DATA EVIDENCE REQUIRED
M3 NOT ESTABLISHED
M4 NO

2. Current Active Route Contract

2.1 Create input

Current active route accepts:

LOADERS / LOADER_IDS / LOADER_ID
ASSIGNMENT_TYPE / TYPE
OPTIONAL_DETAIL

Type-specific fields:

CLEANING
- CLEANING_AREAS
- CLEANING_OTHER

MECHANICAL
- MECHANICAL_TARGET

OTHER_WORK
- OTHER_WORK_TYPE
- OTHER_WORK_OTHER

CLOCK_OUT
- FORKLIFT_CLEANING_TYPE
- FINAL_BREAK

2.2 Current create behavior

For each Loader independently:

  1. resolve current Staff Time state;
  2. reject when not WORKING;
  3. reject when an active QUEUE_WORK_ASSIGNMENT Clock Out already exists;
  4. calculate the next shared Loader queue order;
  5. insert one T_LOADING_PLANNER row;
  6. store type in COMMODITY_NAME;
  7. store detail JSON in FINAL_DRAFT;
  8. use SPECIAL_INSTRUCTION='QUEUE_WORK_ASSIGNMENT';
  9. attempt Telegram separately;
  10. return a per-Loader result.

Current active create has no visible durable request token in the route contract.

response missing
!= safe to resubmit

2.3 Current Telegram boundary

Current active sender:

  • resolves T_USER.TELEGRAM_USER_ID;
  • sends a generic Loader Page message;
  • updates LAST_SENT_TIME only on send success;
  • returns sent/failed separately from assignment creation.
assignment created
!= Telegram delivered

Do not create a second assignment to recover an alert failure.

3. Typed Helper Contract

assignment_work_helper.php defines a stricter model:

  • canonical UUID requestToken;
  • schemaVersion=1;
  • typed assignment data;
  • approved area/work-type allowlists;
  • one Loader advisory lock;
  • duplicate lookup by request token;
  • Telegram attempt/persistence state;
  • cancellation metadata;
  • Clock Out cleaning/final-break fields;
  • conditional update/cancel semantics.

Rows are found through:

ASSIGNMENT_DATA IS NOT NULL

and type/request-token values are read from JSON paths.

The active /work-assignments route family shown above does not use this representation for its primary create/list/current contract.

4. Critical Terminal Guard Mismatch

The shared helper transload_assignment_work_assert_no_terminal_clock_out() checks:

JSON_EXTRACT(ASSIGNMENT_DATA, '$.type') = CLOCK_OUT

The active route creates Clock Out rows as:

SPECIAL_INSTRUCTION = QUEUE_WORK_ASSIGNMENT
COMMODITY_NAME = CLOCK_OUT
FINAL_DRAFT = JSON detail

Therefore a caller that uses the shared guard may fail to see an active Clock Out created by the active route unless the row also contains compatible ASSIGNMENT_DATA.

Potentially affected behavior includes creation of work or break queue items behind a terminal Clock Out.

This is a source-level integrity question, not a proven field incident in this documentation-only work.

Required evidence:

RBR-AWCO-002 — Current Dual-Contract Reconciliation

5. Shared Queue Contract

Current Work assignments share T_LOADING_PLANNER and Loader queue ordering with Load and Break rows.

The queue must preserve:

one current job per Loader
first eligible queue item only
Break/Clock/Work state compatibility
Clock Out terminal behavior
no concealed detail leak before Start

Current route query uses the existing queue resolver and only exposes a concealed next row:

ID
ASSIGNED status
CAN_START

when the next item is a work assignment and there is no current row.

Full detail is returned for a current/started work assignment.

6. Active Current/List Contract

Personal current query

GET /api/tms/transloads/work-assignments/current

Returns:

  • current work assignment with decoded detail when active;
  • concealed next work assignment when eligible;
  • no foreign Loader selection from the request body.

Office list query

GET /api/tms/transloads/work-assignments

Returns current and historical route-owned rows with decoded FINAL_DRAFT, mapped status, assigned time, Loader information, and queue order.

Exact Office role and record scope require current role/API evidence.

7. Current State Mapping

T_LOADING_PLANNER.JOB_STATUS
SCHEDULED -> ASSIGNED
STARTED   -> STARTED
FINISHED  -> COMPLETED
CANCELLED/CANCELED compatibility -> CANCELLED

Current route and typed helper use both CANCELLED and CANCELED spellings in different places. This is a current normalization/caller evidence question.

Do not add a new state until current persisted values and consumers are inventoried.

8. Clock Out Workflow

Current route-owned Clock Out detail includes:

forkliftCleaningType
finalBreak
optional detail / route-specific fields

The active route exposes separate commands to advance and complete the Clock Out workflow.

Required current boundaries remain:

Cleaning complete
!= local Clock Out

Final Break started
!= local Clock Out

local Clock Out committed
!= QuickBooks Time synchronized

The exact current event transaction, final-break timer, and provider behavior require RBR-AWCO-002 evidence against current active rows and callers.

9. Current Source Lineage

Relevant lineage includes:

  • original typed ASSIGNMENT_DATA plan and candidate;
  • accepted/released work-assignment source;
  • later route implementation using QUEUE_WORK_ASSIGNMENT/FINAL_DRAFT;
  • current clock-advice tooltip presentation update.

Historical evidence remains useful for the original design but cannot prove current active caller behavior.

historical candidate evidence
!= current route evidence

10. Current Operator Safety Rules

  • Submit assignment creation once.
  • On missing response, reread the Loader queue and Office list before another create.
  • A failed Telegram result does not remove a committed assignment.
  • Do not add normal work after an active Clock Out.
  • Do not manually reorder or delete planner rows to resolve a conflict.
  • Do not expose type/detail to the Loader before Start.
  • Do not use the normal self-service Clock Out path once the queued Clock Out workflow is active.
  • Reread Staff Time after local Clock Out; reconcile the provider separately.

11. Current Evidence Package

RBR-AWCO-002

Source/callers

  • all route and helper callers;
  • UI calls for create/list/current/start/complete/cancel/advance/clock-out;
  • any callers of typed helper functions;
  • Break and Load callers of the terminal guard;
  • queue resolver behavior for both row representations.

DB

  • ASSIGNMENT_DATA column state;
  • active/history rows using ASSIGNMENT_DATA;
  • active/history rows using QUEUE_WORK_ASSIGNMENT/FINAL_DRAFT;
  • rows containing both;
  • status spelling and JSON validity;
  • indexes/constraints;
  • duplicate current/terminal rows.

Role/UI

  • Office create/list/cancel;
  • intended manager roles;
  • Loader own-record current/start/complete;
  • foreign Loader denial;
  • pre-Start concealment;
  • mobile and keyboard behavior;
  • current advice tooltip visibility across assignment groups.

Integrity/recovery

  • response loss after create/start/complete/clock-out;
  • concurrent same-Loader create/start;
  • terminal Clock Out with later Work/Break attempts;
  • one-active-job guarantee;
  • cancel/reorder behavior;
  • local Clock Out rollback and event uniqueness.

Provider

  • assignment committed / Telegram failed or unknown;
  • local Clock Out committed / provider failed;
  • no assignment or event replay.

This package is defined but not authorized to execute.

12. Target Canonical Model

Before migration or further structural work, choose one accepted application contract.

Minimum target fields:

assignmentId
loaderUserId
type
detail
requestToken
state
queueOrder
assignedAt
startedAt
completedAt
cancellation
notification disposition
clock-out substate
version

Target storage may use the current table during compatibility, but the application contract must not expose both current JSON representations as independent authorities.

13. Target Queries And Commands

Queries:

GetLoaderQueue
GetMyCurrentAssignment
GetAssignmentBoard
GetAssignmentDetail
GetClockOutProgress
GetAssignmentCommandResult

Commands:

CreateLoaderAssignments
StartLoaderAssignment
CompleteLoaderWork
AdvanceClockOutWorkflow
CompleteClockOut
CancelLoaderAssignment
RetryAssignmentNotification
ReconcileAssignmentUnknownResult

Each command requires one canonical request identity, one state contract, one terminal guard, and one exact readback.

14. Current Versus Target Sequence

flowchart TB
    A[Current active routes]
    B[QUEUE_WORK_ASSIGNMENT + COMMODITY_NAME + FINAL_DRAFT]
    C[Current typed helper]
    D[ASSIGNMENT_DATA + requestToken]
    E[Caller/DB evidence]
    F[Accepted canonical application contract]
    G[One writer / compatibility adapter]

    A --> B
    C --> D
    B --> E
    D --> E
    E --> F --> G

Do not select the target by assuming the older detailed design is automatically the current implementation.

15. Migration And Cleanup Boundary

current source/DB/caller evidence
-> choose canonical contract
-> create compatibility read model
-> reconcile terminal guard
-> one create/start/complete/clock-out owner
-> role/field stabilization
-> current Wiki review
-> retire unused representation after row/caller-zero

No implementation is active while Phase work is held.

16. Current Completion

Active route source located: PASS
Typed helper source located: PASS
Dual-contract discrepancy documented: PASS
Current DB/caller/role/provider evidence: NOT_RUN
Canonical current contract accepted: NO
M3: NO
M4: NO

17. Maintenance

Update this document when active route callers, persistence representation, queue resolver, terminal guard, status spelling, event/provider behavior, role access, or canonical-contract decision changes.

---

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