Skip to content

CTC Street Turn Capability Rebuild Packet

  • Status: DETAILED CURRENT SOURCE-RECONCILED INPUT / POLICY AND EVIDENCE REQUIRED
  • Capability: create and safely revert a Street Turn between an empty import load and an export Booking
  • Process candidate: CTC_STREET_TURN_AND_REVERT_WORKFLOW.md
  • Current source baseline: qa/master@13991b627eb95b5b675a4eb05048d56f20538439
  • Current source owners: YMS container command, TMS export-container route, BMS compatibility transaction helper
  • Target stack: React + Next.js adapters + framework-independent TypeScript application/policy/repository + MySQL first
  • Worker requirement: none for the core local transaction
  • Phase implementation: USER HOLD
  • Effect boundary: documentation only

1. Rebuild Outcome

A future implementation must reproduce the accepted business result without copying current cross-module helper structure.

one eligible returned-empty import context
+ one eligible export Booking
-> one explicit Street Turn relation
-> original import load RETURNED
-> one generated export empty load
-> container pickup Booking and AVAILABLE state
-> exact readback

A guarded revert must compensate only the exact unprogressed relation.

exact active relation
+ generated export load unprogressed
+ prior import load still eligible
-> generated export load retired
-> prior import load restored EMPTY
-> container Booking/state cleared
-> immutable relation/reversal evidence

2. Actor And Capability Contract

Proposed semantic capabilities:

tms.street-turn.view
tms.street-turn.create
tms.street-turn.revert
tms.street-turn.reconcile
tms.street-turn.support
Actor Query Command Record restriction
Import Dispatch candidates, Booking options, result create selected tenant-owned import empty rows
Export/Container operations state/history revert when eligible exact generated export load
Manager/support state/history/decision trace reconcile; separately approved recovery tenant-bound, redacted evidence
Booking owner Booking eligibility/read no Street Turn mutation Booking-owned fields only
Yard/Driver downstream state no Street Turn mutation later physical work only

Target commands must derive Actor/Tenant from the authenticated context. The client must not supply a trusted tenant or unrestricted role override.

3. Current Data Model

3.1 T_EQUIPMENT

Field Current meaning Target preservation
ID container/equipment local identity repository identity
CLIENT_ID tenant scope strict tenant context
SHIPPING_LINE SSL used for Booking eligibility normalized policy input
SIZE container size used for Booking capacity column typed size
PICKUP_BOOKING_ID selected export Booking pointer relation projection or explicit relation
PICKUP_BOOKING_NUMBER compatibility/display pointer; revert clears it derived projection where possible
PICKUP_BOL_ID current revert guard evidence exact semantic meaning requires policy review
STREET_TURN_STATUS compatibility state, AVAILABLE or reset N/A derived relation state or typed projection
DELETED_AT active-row predicate lifecycle

3.2 T_EQUIPMENT_LOAD

Field Original import load Generated export load
ID selected source identity create result identity
EQUIPMENT_ID same equipment same equipment
DELIVERY_ORDER_ID positive import context in revert lookup zero at create
STATUS EMPTY before create; RETURNED after EMPTY while revertable
DELETED_AT remains active set on guarded revert

3.3 T_BOOKING

Required current eligibility:

same tenant
active
BOOKING_TYPE = EXPORT
SHIPPING_LINE = equipment shipping line
size-specific planned quantity > 0
CUTOFF >= current DB date

Current create does not establish a separate Booking-capacity reservation/consumption row.

3.4 Downstream blockers

T_DELIVERY.EQUIPMENT_LOAD_ID
T_TRANSLOAD.FINAL_EQUIPMENT_LOAD_ID

Any active child blocks current Revert.

4. Target Explicit Relation

Recommended logical entity:

StreetTurnRelation

Fields:

streetTurnId
UUID
localTenantId
globalTenantId
sourceImportEquipmentLoadId
sourceImportEquipmentLoadUuid
generatedExportEquipmentLoadId
generatedExportEquipmentLoadUuid
equipmentId
equipmentUuid
bookingId
bookingUuid
shippingLine
containerSize
createRequestToken
createPayloadFingerprint
createdByActor
createdAt
state
revertRequestToken
revertedByActor
revertedAt
revertReasonRef
version

State:

ACTIVE
PROGRESSED
REVERTED
CONFLICT
UNKNOWN

This is a target data contract, not authorization to add a table now. The selected migration may initially use an existing authoritative relation if it can meet identity, idempotency, correction, and audit requirements.

5. Current Create DTO

Current request body:

{
  "EQUIPMENT_LOAD_ID": 1001,
  "EQUIPMENT_ID": 501,
  "PICKUP_BOOKING_ID": 9001
}

Current success payload:

{
  "EQUIPMENT_LOAD_ID": 1002
}

Current response does not return the original source load, relation ID, state fingerprint, or idempotency token.

6. Target Create DTO

{
  "requestToken": "uuid",
  "sourceImportEquipmentLoadId": 1001,
  "equipmentId": 501,
  "bookingId": 9001,
  "expectedSource": {
    "status": "EMPTY",
    "updatedAt": "..."
  },
  "expectedEquipment": {
    "streetTurnState": "NONE",
    "updatedAt": "..."
  }
}

Target response:

{
  "streetTurnId": "uuid",
  "sourceImportEquipmentLoadId": 1001,
  "generatedExportEquipmentLoadId": 1002,
  "equipmentId": 501,
  "bookingId": 9001,
  "state": "ACTIVE",
  "readback": {
    "sourceLoadStatus": "RETURNED",
    "generatedLoadStatus": "EMPTY",
    "streetTurnStatus": "AVAILABLE"
  }
}

Duplicate behavior:

same tenant + same requestToken + same fingerprint
-> return existing result

same token + different fingerprint
-> STREET_TURN_REQUEST_CONFLICT

7. Target Revert DTO

{
  "requestToken": "uuid",
  "streetTurnId": "uuid",
  "generatedExportEquipmentLoadId": 1002,
  "expectedVersion": 3,
  "reasonRef": "..."
}

Target response:

{
  "streetTurnId": "uuid",
  "state": "REVERTED",
  "sourceImportEquipmentLoadId": 1001,
  "generatedExportEquipmentLoadId": 1002,
  "readback": {
    "sourceLoadStatus": "EMPTY",
    "generatedLoadActive": false,
    "streetTurnStatus": "N/A",
    "bookingId": null
  }
}

8. Semantic Queries

GetStreetTurnCandidates

Returns only tenant-scoped candidate rows with:

  • source load ID/UUID;
  • equipment ID/UUID;
  • current status;
  • SSL and size;
  • Booking/current Street Turn state;
  • freshness/version;
  • eligibility/denial reason;
  • current downstream child summary.

No mutation.

GetStreetTurnBookingOptions

Inputs:

shipping line
container size
operating date/timezone

Returns:

  • Booking ID/UUID/number;
  • customer/commodity;
  • ERD/cutoff;
  • size capacity;
  • active/inactive disposition;
  • exact eligibility reason.

GetStreetTurnState

Returns:

  • source import load;
  • generated export load;
  • equipment;
  • Booking;
  • Delivery/Transload blockers;
  • create/revert evidence;
  • current derived state;
  • safe actions.

GetStreetTurnCommandResult

Lookup by tenant plus request token. Required for response-loss recovery.

9. Semantic Commands

CreateStreetTurn

Transaction:

  1. acquire bounded equipment/relation concurrency protection;
  2. reread tenant-scoped source load/equipment/Booking;
  3. validate current eligibility and expected version;
  4. enforce request idempotency;
  5. create explicit relation or equivalent authoritative identity;
  6. source load EMPTY -> RETURNED;
  7. create one generated export empty load;
  8. update container relation/state projection;
  9. append transition evidence;
  10. commit;
  11. return exact readback.

RevertStreetTurn

Transaction:

  1. reread exact active relation;
  2. validate expected version;
  3. assert no Delivery/Transload/downstream blocker;
  4. assert source/generated/container states;
  5. retire generated load;
  6. restore source load;
  7. clear container projection;
  8. mark relation REVERTED;
  9. append transition/reversal evidence;
  10. commit;
  11. return exact readback.

ReconcileStreetTurnUnknownResult

Returns:

COMMITTED
NOT_COMMITTED_RETRY_ALLOWED
PARTIAL_OR_CONFLICT
MULTIPLE_MATCHES
UNKNOWN_MANUAL_REVIEW

It does not mutate business state.

10. Transaction And Concurrency

Current create/revert each use one local DB transaction for their own command. Multi-row UI create is not one transaction.

Target concurrency must protect:

  • the selected source import load;
  • the equipment/container;
  • the active Street Turn relation;
  • the selected Booking capacity policy if capacity becomes consumable;
  • the exact generated export load during Revert.

Possible mechanisms must follow current DB rules and may use conditional updates/CAS or a bounded advisory lock. Runtime row locking is not introduced by this packet.

11. Stable Errors

STREET_TURN_UNAUTHENTICATED
STREET_TURN_FORBIDDEN
STREET_TURN_PROFILE_NOT_APPLICABLE
STREET_TURN_SOURCE_NOT_FOUND
STREET_TURN_SOURCE_NOT_EMPTY
STREET_TURN_SOURCE_STALE
STREET_TURN_EQUIPMENT_NOT_FOUND
STREET_TURN_SIZE_UNSUPPORTED
STREET_TURN_MIXED_SELECTION
STREET_TURN_BOOKING_NOT_FOUND
STREET_TURN_BOOKING_MISMATCH
STREET_TURN_BOOKING_EXPIRED
STREET_TURN_REQUEST_DUPLICATE
STREET_TURN_REQUEST_CONFLICT
STREET_TURN_RESULT_UNKNOWN
STREET_TURN_RELATION_NOT_FOUND
STREET_TURN_GENERATED_LOAD_CHANGED
STREET_TURN_CONTAINER_CHANGED
STREET_TURN_PRIOR_IMPORT_NOT_FOUND
STREET_TURN_DOWNSTREAM_LOCKED
STREET_TURN_REVERT_CONFLICT
STREET_TURN_DATA_CONFLICT

Internal SQL/stack details must not be returned to ordinary operators.

12. UI Contract

Import Dispatch

States:

no selection
mixed selection
eligible selection
Booking options loading
Booking options empty
validation denied
submitting
per-row success/failure/unknown
readback complete

The UI must keep per-row results after a batch and prevent full-selection blind replay.

Export/Container view

Show Revert only when the current authoritative state says it may be attempted. Hidden UI is not the authorization boundary; the command repeats all checks.

Mobile/accessibility

  • keyboard/focus usable;
  • no color-only status;
  • selected container ID/reference visible;
  • error tied to each row;
  • confirmation names the generated export context and restored import result;
  • narrow-screen result table remains readable.

13. Operator Recovery Matrix

Symptom Reread Safe action Prohibited replay
Create response missing source load, equipment, generated loads, Booking pointer classify committed/not committed/conflict submit all rows again
One row fails in batch that row's source/equipment/Booking correct only rejected row rerun successful rows
Generated load exists but UI stale export list and relation state refresh/readback create another load
Revert denied by downstream child Delivery/Transload owner use downstream correction policy delete child to enable Revert
Revert response missing generated load active state, prior import, container state classify committed/conflict repeat without reread
State inconsistent all relation records and audit/evidence manager/support escalation direct DB edits

14. Audit And Evidence

Required evidence references:

source import equipment load
generated export equipment load
equipment/container
export Booking
create command request/correlation
revert command request/correlation
downstream blocker summary
transition/reversal result

Notification ACK or UI toast is not completion evidence.

15. React / Next.js / TypeScript Ownership

React

  • selection and Booking choice;
  • preview and per-row result;
  • unknown-result guidance;
  • Revert confirmation;
  • read-only history and blockers.

Next.js

  • session/tenant adapter;
  • request validation;
  • route/error mapping;
  • correlation ID;
  • no business SQL or eligibility policy.

TypeScript application/domain

  • eligibility;
  • idempotency;
  • transaction orchestration;
  • relation state;
  • blocker classification;
  • exact readback and semantic errors.

Repository

  • tenant-scoped equipment/load/Booking/child reads;
  • conditional writes;
  • relation/evidence persistence;
  • no UI concepts.

Worker

No worker is required for core create/revert. A worker may later reconcile separately approved asynchronous projections, not decide Street Turn business state.

16. Migration Waves

ST-W0 current source/schema/role/caller evidence
ST-W1 typed read model
ST-W2 React/Next.js read-only UI
ST-W3 request identity and relation shadow
ST-W4 one-writer create cohort
ST-W5 one-writer guarded revert
ST-W6 role/mobile/current-Wiki stabilization
ST-W7 old caller-zero
ST-W8 PostgreSQL later

No wave is active while Phase implementation is held.

17. Rollback

Application rollback must not delete an already created/reverted business result.

route rollback
-> old UI/adapter
-> same authoritative DB records
-> reconcile in-flight request tokens
-> preserve transition/reversal evidence

Do not implement rollback by:

  • recreating a generated export load;
  • changing status manually;
  • clearing Booking pointers without relation evidence;
  • replaying the original create;
  • restoring soft-deleted rows blindly.

18. Verification Scenarios

STREET-SCN-010 normal create
STREET-SCN-020 multi-row independent success
STREET-SCN-030 mixed SSL/size denial
STREET-SCN-040 source not empty
STREET-SCN-050 Booking mismatch/expiry
STREET-SCN-060 duplicate request token
STREET-SCN-070 create response loss
STREET-SCN-080 concurrent create
STREET-SCN-110 normal revert
STREET-SCN-120 Delivery blocker
STREET-SCN-130 Transload blocker
STREET-SCN-140 prior import missing
STREET-SCN-150 stale generated load
STREET-SCN-160 stale equipment state
STREET-SCN-170 revert response loss
STREET-SCN-180 tenant/role denial
STREET-SCN-190 mobile/accessibility
STREET-SCN-200 current Wiki/readback
STREET-MIG-SCN-010 read parity
STREET-MIG-SCN-020 one-writer create
STREET-MIG-SCN-030 one-writer revert
STREET-MIG-SCN-040 rollback without replay
STREET-MIG-SCN-050 caller-zero

19. Definition Of Ready

  • current role/page/API/record matrix accepted;
  • current DB relation/state evidence accepted;
  • durable relation/idempotency decision accepted;
  • Booking capacity/cutoff/timezone policy accepted;
  • downstream correction policy accepted;
  • exact target DTO/errors/repository transaction accepted;
  • rollback and observation defined;
  • current Runbook/Wiki reviewed;
  • Phase explicitly reactivated.

20. Current Completion

Current source map: DETAILED INPUT
Process semantics: DETAILED INPUT / PROCESS ID OPEN
Data/DTO/error/recovery: DETAILED TARGET INPUT
Role/DB/browser evidence: REQUIRED
Wiki: DRAFT ONLY
M3: NO
M4: NO
Implementation: USER HOLD

---

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