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

Yard Dispatch, Closing And Driver Policy Decision Matrix¶

Status: P6-007 DECISION INPUT / NOT USER-APPROVED
Source: YARD_DISPATCH_CLOSING_DRIVER_RECONCILIATION.md
Migration: YARD_DISPATCH_MIGRATION_PACKET.md
Source baseline: 4fc2f5a893765fbb95e0a2bdcb971322b0ec9fc0
Effect boundary: documentation only

1. Decision Summary¶

ID	Topic	Current source fact	Recommended target	M4 impact
YD-POL-001	Office authority	server derives Office override from broad menu decisions	semantic Yard planning/execution/override capabilities	blocking
YD-POL-002	Yard Driver roster	role data plus hardcoded personal names	role/capability/config assignment only	blocking
YD-POL-003	Active queue uniqueness	source validates, DB uniqueness/concurrency incomplete	one active logical queue per approved entity/work key with conditional command	blocking
YD-POL-004	Claim	compare-and-set exists; no full uniqueness/lease model	conditional claim, one active claimant, explicit Office override	blocking
YD-POL-005	Unclaim	status returns Scheduled while prior assignee may remain visible	separate assigned/suggested Driver from active claimant	blocking
YD-POL-006	Destination	Area/Stack planned instruction resolved to actual spot at execution	planned instruction and actual location are separate typed fields	blocking
YD-POL-007	Occupied target	deferred queue-after-clear	explicit deferred physical-work identity and idempotency	blocking
YD-POL-008	Pull Out	BMS closing then YMS Complete in two requests	durable checkpoint/resume saga; no distributed transaction fiction	blocking
YD-POL-009	Scale skip	UI supports skip path	explicit physical/business condition and authorization	blocking
YD-POL-010	Queue completion	helper may create/auto-complete related rows	one logical move identity and duplicate reconciliation	blocking
YD-POL-011	Yard history	no-op/insufficient operator history	audit/event evidence for material move/correction, without duplicating authority	blocking for M3/M4
YD-POL-012	Supporting events	operation event after commit	local success plus separate supporting-effect status	non-blocking if explicit
YD-POL-013	Yard Break	local event then QBO Time; hardcoded roster	workforce capability/policy and provider reconciliation	blocking
YD-POL-014	Yard-to-Driver correlation	equipment/current-location, no queue FK	explicit handoff correlation or accepted manual stable-ID bundle	blocking
YD-POL-015	Driver identity	key mutations improved, some list/log scope still caller-selected	authenticated Driver context and assigned-row enforcement everywhere	blocking
YD-POL-016	Yard-origin Driver Start	Yard vacate and delivery status can be separate	explicit two-checkpoint resume; no repeated vacate	blocking
YD-POL-017	Tenant-yard Finish	Yard move and delivery update can be separate	preserve physical result; resume only missing delivery boundary	blocking
YD-POL-018	Parking	request/assign/confirm and Telegram/local transaction mixed	separate parking state, Yard effect and notification intent	blocking
YD-POL-019	Undo	delivery status reset without full compensation	variant-specific correction/compensation, never “rollback”	blocking
YD-POL-020	Daily close	manual dispositions	preserve manual reconciliation labels; do not invent stored composite state	non-blocking

2. Yard Capabilities¶

Recommended semantic capabilities:

yms.yard.dispatch.view
yms.yard.dispatch.plan
yms.yard.dispatch.reorder
yms.yard.dispatch.cancel
yms.yard.instruction.view
yms.yard.instruction.claim
yms.yard.instruction.complete
yms.yard.closing.execute
yms.yard.override
yms.yard.map.view
yms.yard.location.correct
yms.yard.workforce.break
yms.yard.workforce.manage

Menu access may be one input to capability resolution during compatibility, but domain/application code does not infer authority from page visibility.

3. Roster Policy¶

Current defect¶

Dedicated Yard Truck visibility is partly selected by matching personal names.

Recommended target¶

active user
+ Yard Truck Driver role/capability
+ optional current shift/assignment/config
+ current Clock/work context where relevant

Do not preserve any name list. If specific employees require temporary inclusion, use explicit configuration with owner/expiry, not source branches.

4. Active Queue Identity¶

Define one business key for conflict detection. Candidate dimensions:

tenant
entity type + entity ID
movement purpose/type
active status set
optional delivery/transload/source relation

Recommendation:

no more than one active physical-move queue per entity unless a documented sequence permits multiple;
creation/update uses a conditional predicate or approved uniqueness strategy;
duplicate request returns the existing logical queue identity;
completed history rows remain separate from active uniqueness.

Do not use queue description or display reference as identity.

5. Claim And Unclaim¶

Claim¶

only Scheduled/eligible queue;
current source/physical location is still valid;
actor is intended Yard Driver or Office override;
conditional update accepts one claimant;
exact queue reread.

Office override¶

Requires semantic capability, selected actor/reason and audit. It does not derive from a caller-provided flag.

Unclaim¶

Recommended state fields:

assignedDriverId      optional suggested/planned assignee
claimedByDriverId     current active claimant or null
claimedAt

Unclaim clears active claim fields. Whether planned assignee remains is a separate policy and must be labeled accurately.

6. Planned Versus Actual Destination¶

Target contract:

plannedTarget:
  kind = SPOT | AREA | STACK_GROUP | PULL_OUT | DROP | OTHER
  value

actualLocation:
  stable location ID/code or null until execution

Area/Stack instruction is not occupancy.
actual location must be selected/validated at completion.
corrections use a separate location-correction command preserving prior move evidence.
React shows both planned instruction and actual result.

7. Pull Out Closing¶

Options¶

A. One endpoint tries to own BMS and YMS transaction¶

Not recommended; no shared database/service transaction guarantee and high coupling.

B. Explicit saga/checkpoint¶

CLOSING_REQUIRED
-> CLOSING_RECORDED
-> YARD_QUEUE_COMPLETED
-> RECONCILED

Each checkpoint has stable identity and resume.

C. Preserve two commands with only manual procedure¶

Lowest implementation change but weak recovery/automation.

Recommendation¶

Use B in the TypeScript application layer while keeping current MySQL owners:

BMS records closing checkpoint;
YMS completes queue/location;
orchestration stores or derives progress from existing stable records;
no new table unless existing identities cannot prove the checkpoint;
response exposes partial state and next owner;
retry resumes only missing checkpoint.

8. Scale Skip Policy¶

Define:

which Pull Out/load types may skip scale;
required role/capability;
reason/evidence;
whether skip changes closing completion or only weight input;
audit and later correction.

Do not leave skip as a browser checkbox without server policy.

9. Queue-After-Clear¶

Recommended target:

one deferred queue item has stable origin, blocking location and target;
auto-completion uses a conditional/idempotent command;
completed origin/delivery is not replayed;
duplicate worker/event execution rereads existing completion;
UI shows “Delivery/Business complete — Yard placement pending” explicitly;
Office can manually reconcile/cancel through a documented command.

10. Yard History And Correction¶

Required operator evidence for material moves:

queue/request identity;
entity/equipment identity;
from planned/current location;
planned and actual target;
actor and time;
completion/cancel/correction;
related delivery/transload/closing identity;
original and compensating action.

This may use process/audit events or existing rows. Do not add a parallel authoritative movement ledger without P6/P5 design.

11. Yard Workforce Break¶

Recommended policy mirrors the Loader workforce contract but with YARD_TRUCK context:

roster from role/capability/config;
Clocked In prerequisite;
paid 10-minute Break and unpaid Lunch only if Operations approves;
local event is source of truth;
QuickBooks Time is secondary;
duplicate/timeout resolved by event reread;
manager correction with reason;
no name branches.

12. Yard-To-Driver Correlation¶

Current compatibility¶

Correlation is by tenant + equipment/current location + delivery context. No queue ID is persisted on delivery.

Options¶

A. Continue manual correlation¶

Acceptable short term if stable equipment/load/delivery IDs are always present and field recovery is explicit.

B. Add durable handoff/correlation identity¶

Useful if repeated ambiguity, automation or migration parity requires it.

Recommendation¶

For initial React/Next.js migration use A with a typed YardDriverHandoffContext:

tenant
queueId if available
deliveryId
equipmentId / equipmentLoadId
currentLocation
handoffDisposition
correlationId

Only add persistence after source/field evidence proves a repeated gap.

13. Driver Identity And Assigned Work¶

Target rules:

Driver identity comes from authenticated actor/session context;
list defaults to assigned Driver scope;
Office-wide query requires explicit capability;
mutation validates assigned Driver or Office override;
caller-supplied userId/isAdmin never grants authority;
active Driver Log requirement is server-enforced where process requires it.

14. Yard-Origin Driver Start¶

Recommended checkpoint model:

Yard prerequisite verified
-> Yard vacate if required
-> Delivery Start
-> reconcile both

If Yard vacate succeeds and Start fails:

do not vacate again;
reread delivery/queue/location;
resume only Start after authorization/evidence.

A future application command may orchestrate both but must expose partial state and never claim atomic rollback.

15. Tenant-Yard Finish And Parking¶

Direct empty target¶

Yard move and delivery completion remain separate checkpoints unless a proven application orchestration coordinates them.

Occupied target¶

Delivery may complete while queue-after-clear remains pending. UI and Wiki must show that physical work remains.

Parking¶

Separate:

PARKING_REQUESTED
PARKING_ASSIGNED
YARD_PLACEMENT_CONFIRMED
DELIVERY_COMPLETED
NOTIFICATION_SENT / FAILED

Telegram should be post-commit/durable effect, not a reason to roll back an accepted parking state unless Product explicitly requires provider delivery as part of local acceptance.

16. Undo And Correction¶

Trouble is an exception state, not a complete diagnosis.
Undo returning delivery to Dispatched does not restore Yard, equipment, files or provider effects.
Each variant requires an explicit correction/compensation matrix.
Physical move correction must preserve original movement evidence.
Deployment rollback never changes business data automatically.

17. Wiki Structure¶

Current slugs:

yard-dispatch for Office/Yard Driver planning/execution;
driver-delivery for Truck Operator;
loader-yard for cross-process handoff;
errors-recovery for partial closing/provider/Undo;
ctc-daily summary.

Required split:

Office queue planning;
Yard Driver claim/physical completion;
Pull Out Closing and partial recovery;
Yard Map/current location;
Yard Truck Break;
Driver Start/Finish/Parking;
cross-process handoff and non-implication.

18. User Decision Package¶

Approve or revise:

Yard capabilities;
roster without names;
active queue uniqueness;
claim/assignee model;
planned/actual location model;
Pull Out saga/resume;
scale-skip policy;
queue-after-clear idempotency;
Yard history/correction evidence;
Yard Break/QBO policy;
Yard-to-Driver correlation;
Driver identity/list/mutation policy;
Start/Finish partial-checkpoint recovery;
Parking/Telegram separation;
Undo/compensation;
Wiki and migration wave.

---¶

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