Skip to content

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

CTC Yard Dispatch, Closing And Driver Handoff Source Reconciliation

  • Status: P6-007 SOURCE-RECONCILED PROCESS INPUT
  • Processes:
  • PROC-YMS-YARD-DISPATCH v0.4.0
  • PROC-OPS-YARD-TO-DRIVER-HANDOFF-CTC v0.4.0
  • PROC-TMS-DRIVER-DELIVERY v0.2.0
  • Lifecycle: all draft / partial
  • Source baseline: 4fc2f5a893765fbb95e0a2bdcb971322b0ec9fc0
  • Migration packet: YARD_DISPATCH_MIGRATION_PACKET.md
  • Policy decisions: YARD_DRIVER_POLICY_DECISION_MATRIX.md
  • Parity/cutover: YARD_DRIVER_PARITY_AND_CUTOVER_MATRIX.md
  • Does not authorize: Runtime/DB/role/config/provider/Wiki/deployment changes or lifecycle promotion

1. Source-Level Conclusion

The current Yard portfolio is correctly separated into:

Yard Dispatch
= queue planning + claim + physical move/closing + Yard occupancy

Driver Delivery
= assigned delivery + Driver Log + delivery state/evidence/parking

Yard-To-Driver Handoff
= conditional correlation and reconciliation only

However, current source contains distinct sub-boundaries that must remain explicit during migration:

Yard planning
Yard execution
Pull Out scale/closing
Yard workforce Break/time
Delivery Start/Finish
Parking/arrival/location/provider effects

A React page or Next.js route must not collapse these into one generic Yard command or one cross-process transaction.

2. Current User Surfaces

Yard Dispatch

Office/Dispatch planning surface:

  • active queue and schedule;
  • Reserve Move/Area/Drop/Stack Group;
  • create/update/reorder/cancel;
  • assigned/claimed Driver context;
  • equipment/location/entity context;
  • returning-empty reservation;
  • Yard Map and instruction links.

Yard Instruction

Yard Truck Driver execution surface:

  • eligible scheduled/claimed queue items;
  • claim/unclaim;
  • physical source/target instruction;
  • non-Pull-Out Complete;
  • redirect to Yard Closing for Pull Out;
  • current staff/Break state.

Yard Closing

Pull Out closing surface:

  • selected equipment/load;
  • closing photos;
  • Yard truck and tare/gross/scale inputs;
  • optional scale-skip path;
  • actual spot selection for area/stack instructions;
  • BMS closing save followed by Yard queue completion.

Yard Map

Physical-system occupancy projection:

  • T_YARD_LOCATION state;
  • current container/chassis/transload/equipment relationship;
  • queue/instruction overlays;
  • occupied/available/blocked location semantics.

Driver

Truck Operator surface:

  • personal Driver Log;
  • assigned delivery cards;
  • Start/Finish/Trouble/Undo;
  • photo and field evidence;
  • arrival/location ping;
  • parking request/assignment/confirmation;
  • tenant-yard Yard move/queue-after-clear integration.

3. Current Server Authority And Access

Strict tenant boundary

Yard move routes can apply an explicit TenantExecutionContext through ymsYardMoveTenantContext(). Legacy context remains for compatibility when explicit tenant metadata is not selected.

Migration target:

  • every Yard query/write uses one strict tenant/actor context;
  • current legacy adapter remains bounded during coexistence;
  • no caller-supplied tenant or equipment identity bypass.

Office planning capability

Current source derives Office authority server-side from allowed menu routes including Yard Dispatch, Yard Map, Inbound Planning and import/export dispatch surfaces.

Request OFFICE_OVERRIDE is treated as a compatibility hint; ymsYardMoveApplyHumanCommandAuthority() rewrites the effective override from server capability.

This corrects older documentation that described request-body override as authority.

Yard execution capability

Execution actions require either:

  • server-derived Office capability; or
  • Yard Instruction access.

Delivery-origin Yard move/vacate additionally validates:

  • delivery ID;
  • equipment ID matches the delivery load;
  • current actor is assigned Driver unless Office.

Remaining access gaps

  • menu-derived capability is not yet a stable Product capability contract;
  • exact target-role/command matrix remains P2-007 work;
  • some Delivery list/current-log reads still accept caller-supplied user/admin selectors;
  • current dedicated Yard Truck roster includes hardcoded names;
  • Administrator visibility is not field-role acceptance.

4. Current Records And Authority

Record Authority
T_YARD_DISPATCH_QUEUE Yard work request, ordering, assignment/claim, status and planned/actual movement context
T_YARD_LOCATION physical-system Yard occupancy/location authority
T_EQUIPMENT / T_EQUIPMENT_LOAD container/chassis/load identity and derived Yard/load mirrors
T_TRANSLOAD related operational work; not Yard queue authority
T_SCALE_TICKET and closing records Pull Out closing/weight checkpoint through BMS owner
T_STAFF_TIME_EVENT Yard Truck Clock/Break time authority
T_DELIVERY Driver assignment, delivery status, arrival and parking state
T_DRIVER_LOG Truck Operator workday/check-in authority
T_FILE delivery/closing photo evidence
T_OPERATION_EVENT supporting post-commit event/location ping; not physical completion authority
Telegram notification effect, not queue/delivery/parking authority
QuickBooks Time external workforce-time effect; local event remains authority

T_EQUIPMENT Yard-state fields remain derived compatibility mirrors. A migration packet must name the final occupancy owner and every mirror consumer before retirement.

5. Yard Queue State Model

Persisted queue statuses:

QUEUED
SCHEDULED
CLAIMED
COMPLETED
CANCELLED

Planning actions

Server-classified planning actions include:

  • Reserve Area/Drop/Stack Group/Move;
  • create relocate-before-pull-out;
  • create/update/reorder/cancel queue.

These require Office planning capability.

Execution actions

Server-classified execution actions include:

  • claim/unclaim/confirm queue;
  • queue-after-clear;
  • claim/cancel/complete dispatch.

These require Office or Yard Instruction capability.

Claim

Current source:

  • requires Scheduled or already-Claimed state;
  • prevents a non-Office Driver from taking a row claimed by another Driver;
  • uses a compare-and-set helper for conditional claim;
  • validates current physical/source location;
  • returns the claimed Driver and state.

Unclaim

Current behavior can return the queue to Scheduled while retaining the prior assigned/displayed Driver identity. Scheduled status, not retained display name, determines whether a row is actively claimed.

Target projection must distinguish:

assigned/suggested Driver
active claimed Driver
claim timestamp

Confirm/Complete

Current queue Confirm:

  • validates current claimed/authorized actor and actual target;
  • performs physical location move/vacate/area/stack behavior;
  • marks original queue Completed;
  • can trigger automatic queue-after-clear completion;
  • enqueues equipment-state sync after local result.

A successful queue response does not prove external event/provider completion.

6. Destination And Physical Occupancy

Current destination types include:

  • exact Yard spot;
  • Area instruction;
  • Stack Group/Lane instruction;
  • Drop;
  • Pull Out;
  • returning-empty/parking-related target.

For Area/Stack Group, current Yard Closing UI asks the operator to select the actual physical spot before completing the queue.

Required invariant:

planned destination/instruction
+ actual physical location
+ T_YARD_LOCATION readback
+ queue completion

A planned Area/Stack Group is not an actual occupancy location. The exact selected spot becomes occupancy authority only after the owner command commits and rereads.

7. Pull Out Closing Boundary

Current browser sequence

Current Yard Closing JavaScript performs:

POST /api/bms/scale-tickets/closing
-> if successful
POST /api/yms/yard-moves/dispatch/complete

The two calls do not share one cross-service transaction.

Partial result

Possible current state:

closing scale/weight data committed
+ queue still CLAIMED / not completed

A retry of the full form can duplicate or contradict scale/closing evidence.

Required recovery

  1. reread closing/scale data by stable equipment/load/ticket identity;
  2. reread Yard queue and actual location;
  3. if closing exists and queue remains active, resume only queue completion;
  4. do not recreate closing data;
  5. if queue completed and closing is absent, carry an explicit partial exception to the BMS/Office owner;
  6. record cleanup/correction separately from deployment rollback.

Migration implication

Pull Out is not safe as one client-orchestrated form without an application-level orchestration contract.

Target choices:

  • explicit cross-process saga/orchestration with durable checkpoints; or
  • preserve two commands with a first-class partial state and resume command.

Do not create an unsupported distributed transaction.

8. Queue-After-Clear And Occupied Targets

Current Yard/Driver flows can create deferred work when the intended target is occupied.

Queue-after-clear means:

business/delivery child may be complete
+ physical Yard placement remains pending

When the blocking location clears, current helper logic can automatically complete the waiting Yard movement and update occupancy.

Required identities:

  • waiting queue ID;
  • blocking/cleared location;
  • equipment/container/load identity;
  • planned/actual destination;
  • originating delivery or Yard work;
  • auto-completion result.

Automatic completion must be idempotent. A second similar Completed row must not be interpreted as a second physical movement without entity/route/time/location reconciliation.

9. Yard Workforce Time And Break

Current Yard Truck Break API:

  • identifies current Yard Truck Driver roster;
  • requires signed-in user in roster or Office selection;
  • requires Clocked In state;
  • supports 10MIN BREAK and LUNCH BREAK;
  • records local Break event;
  • commits;
  • attempts QuickBooks Time sync after commit.

Hardcoded roster defect

Current ymsYardTruckDriverIsDedicated() includes hardcoded usernames/display-name matching for:

ARMANDO
EZECK
EZEKIEL

This is a current source fact and prohibited target behavior.

Required target:

role/capability/configured staff assignment
-> Yard Truck Driver roster

Names may appear in evidence/diagnostics but cannot select business authority.

External effect

QuickBooks Time failure does not reverse the local Break event. User-visible reconciliation and manual fallback remain required.

10. Driver Handoff And Delivery Start

The Yard-to-Driver composite applies only to an exact conditional path:

  • scheduled default-yard Return/Relocate delivery;
  • same equipment/current location correlation;
  • applicable active Yard queue blocks Start;
  • Yard owner completes/cancels/corrects queue;
  • Driver projection is refreshed;
  • assigned Truck Operator with active Driver Log starts delivery;
  • delivery rereads DISPATCHED;
  • Yard queue/location have no unexplained partial state.

Not universal:

  • most Yard moves do not create/advance delivery;
  • many deliveries do not require prior Yard work;
  • no durable queue foreign key is stored on the delivery;
  • equipment/location correlation is current compatibility logic, not robust orchestration identity.

Current source improvement

Delivery status and delivery-origin Yard move paths now include assigned-Driver checks for important actions, with Office bypass. The current canonical Driver document's blanket statement that status writes lack assigned-driver enforcement is stale and requires update during its owner reconciliation.

Remaining Driver gaps

  • some list/log reads still accept caller-selected scope;
  • delivery Start can involve Yard vacate and delivery update across separate requests;
  • tenant-yard Finish can move Yard then update delivery separately;
  • occupied-target Finish creates deferred Yard work;
  • Parking request/assignment Telegram occurs inside the delivery transaction;
  • Parking confirmation and delivery completion can be separate requests;
  • Trouble/Undo is incomplete compensation;
  • no durable Yard queue correlation on delivery.

11. Provider And Post-Commit Effects

Equipment state sync / operation event

Current Yard write wrapper commits the local transaction and then may add an operation event. Operation-event failure is returned separately and does not roll back local queue/location state.

Telegram

Driver assignment/parking and other notifications may return sent/failed/skipped provider detail.

A current parking request/assignment can attempt Telegram inside the DB transaction. Provider success may occur before later DB rollback, and provider failure can fail the local request depending on current path.

Target effect contract must separate:

local business commit
notification intent
provider attempt/result
retry/reconciliation/manual fallback

QuickBooks Time

Yard workforce local event commits first; provider sync is separate.

12. Exception And Recovery Matrix

ID Boundary Detection Safe recovery
YARD-EXC-010 create/update another active queue exists for entity reread active queue; update/reuse through owner, no duplicate create
YARD-EXC-020 claim already claimed by another Driver do not override unless Office capability/reason; reread claim
YARD-EXC-030 concurrent claim compare-and-set conflict refresh queue; one logical claimant
YARD-EXC-040 unclaim Scheduled row still displays prior Driver use status/active claim evidence, not display name alone
YARD-EXC-050 destination planned/actual spot mismatch or occupied target stop; select valid actual spot or create approved deferred queue
YARD-EXC-060 non-Pull-Out Complete response unknown reread queue and Yard location before repeat
YARD-EXC-070 Pull Out closing saved, queue still active resume queue completion only after closing readback
YARD-EXC-080 Pull Out queue completed, closing absent/uncertain preserve Yard result; BMS/Office correction only
YARD-EXC-090 queue-after-clear duplicate/second completion evidence reconcile waiting queue/entity/location and accept one logical move
YARD-EXC-100 operation event local Yard commit succeeded, event failed retry/record supporting event only; no Yard replay
YARD-EXC-110 Yard Break local event saved, QBO Time failed preserve local event; provider/manual review
YARD-EXC-120 roster real Driver missing due to hardcoded/dynamic filter correct role/config roster; do not add another name branch
YARD-EXC-130 Driver Start Yard vacated, delivery still Scheduled do not vacate again; resume Driver status after reread
YARD-EXC-140 tenant-yard Finish Yard moved, delivery update failed keep physical Yard result; resume delivery command only
YARD-EXC-150 occupied Finish delivery complete, Yard queue pending carry pending Yard owner; no duplicate delivery Finish
YARD-EXC-160 parking Telegram provider/local state diverges reread parking and provider evidence before repeat
YARD-EXC-170 Undo delivery reset but Yard/equipment/file effects remain Office compares every owner; no full rollback claim

13. Current Structural Risks

  1. Pull Out closing is client-orchestrated across BMS and YMS requests.
  2. No durable cross-process queue/closing/delivery correlation exists.
  3. Yard queue and physical location can disagree after partial results.
  4. Queue-after-clear auto-completion and duplicate movement evidence require idempotency proof.
  5. Yard history helper remains insufficient for full operator audit.
  6. dedicated Yard Driver selection contains hardcoded personal names.
  7. Office authority is derived from broad menu-route access rather than stable semantic capability.
  8. Delivery list/log reads and some mutation families still have identity/access gaps.
  9. Parking provider call can occur inside local transaction.
  10. Trouble/Undo does not compensate every child effect.
  11. physical, local record, provider and supporting event completion are repeatedly separate.

These are migration inputs and policy decisions, not automatic authorization for a broad refactor.

14. Migration Readiness

Yard Dispatch: M2 source-reconciled input
Yard-to-Driver composite: M2 source-reconciled input
Driver Delivery: M2 update input; canonical contract partly stale
M3 target-role/physical recovery: incomplete
M4 migration ready: incomplete

M4 blockers include:

  • semantic planning/execution/override capabilities;
  • hardcoded roster removal policy;
  • active-entity uniqueness and claim concurrency;
  • Pull Out partial/saga policy;
  • queue-after-clear identity/idempotency;
  • Yard/Driver correlation;
  • parking/provider transaction separation;
  • assigned Driver/list/log parity;
  • full physical/role/recovery evidence;
  • Wiki content and field acceptance.

15. Wiki Projection Requirements

Current slugs:

  • yard-dispatch;
  • loader-yard;
  • driver-delivery;
  • errors-recovery;
  • ctc-daily.

User content must distinguish:

  • Office planning versus Yard Driver execution;
  • planned destination versus actual physical spot;
  • claim versus assigned/displayed Driver;
  • non-Pull-Out Complete versus Pull Out Closing;
  • closing scale saved versus queue completed;
  • queue-after-clear pending physical work;
  • Yard completion versus Driver Start/Finish;
  • local Break/time versus QuickBooks Time;
  • Telegram/provider failure versus local commit;
  • Undo versus actual compensation.

Current Wiki DB content has not been read or published by this reconciliation.

16. Required Decisions

  • stable semantic Yard planning/execution/override capabilities;
  • roster based on role/config, not names;
  • queue active-entity uniqueness and claim model;
  • retained assignee versus active claimant semantics;
  • actual-location selection and correction;
  • Pull Out orchestration/resume model;
  • queue-after-clear idempotency and completion identity;
  • Yard workforce Break policy;
  • Driver Start correlation and durable handoff identity;
  • parking/provider transaction order;
  • Undo/correction behavior;
  • target-role/API matrix;
  • React/Next.js migration wave and worker/effect ownership;
  • Wiki procedure structure and field acceptance.

---

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