edr-platform/e2e/freight/SCENARIO_ENGINE_NOTES.md

Scenario ↔ engine reconciliation (S1–S40)

Verified against the API source while writing the Group 1 specs. Every claim below carries a file:line; re-check them before trusting this file, it is a snapshot of the code as of the freight_feature/usermanagement branch.

The point of this file: several scenarios in the original 40-case document describe behaviour the engine does not implement. Those are not spec bugs to code around — they are either product gaps worth a ticket, or scenarios whose premise needs restating. Writing a green test against a premise the code contradicts is worse than having no test.

Capacity: 53 vs 54

The scenarios are written for a 53-wagon train. A loco-pair schedule cannot hold 53 on this corridor: syncScheduleMaxWagons recomputes max_wagons as floor(locoLength / shortest active wagon length), and seed-import-corridor.sql deliberately pins that at floor(760 / 13.966) = 54.

A built train is exempt — booking-batch.service.ts:4152:

const maxWagons = physicalWagons ?? capacityLimits(loco).base.wagons;

So Group 1 runs on TRN-G1-1, a 53-wagon built consist (seed-g1-train.sql). Note train-capacity.util.ts:107 calls 53 "the marshalling figure" and says the slot count is "never a fixed 53" — the number is real, it just has to come from a consist rather than from locomotive length.

Confirmed — scenario matches the engine

Scenario	Engine fact	Where
S1/S5 cascading promotion	fillFromWaitingList loops up to 10 rounds until a pass reserves nothing	booking-batch.service.ts:2788
S4/S6 split offers	booking_batch_offers, status defaults OFFERED, offered_wagons	booking-batch-offer.entity.ts:27,46,73
S9 heavy VGM	NW5 tare 22.4T → 2×28 + 22.4 = 78.4T gross, exactly as the scenario computes	train-capacity.util.ts:16,82
S11 split ignores tolerance	tolerance "spendable only by admitting a booking whole, never by a split"	train-capacity.util.ts:58, booking-batch.service.ts:4109
S13 holds occupy space	reserved = SELECTED_FOR_BATCH/AWAITING_PAYMENT, subtracted from capacity until the deadline lapses	bookings.repository.ts:1372, booking-batch.service.ts:4487
S18 oversized export rejected	409 at requestOperation with a sized message	booking-transition.service.ts:1016, booking-batch.service.ts:900
S25 per-station arrival	checkpoint at an intermediate yard auto-unloads bookings destined there	booking-journey.service.ts:261
S30 cancel snapshot	train_schedules.wagon_allocation_snapshot jsonb, frozen before wagons are released; holds wagon numbers + per-slot weights	train-scheduling.service.ts:3984, 4647
S31 wagon transfer	statuses PENDING/PARTIALLY_FULFILLED/FULFILLED/CLOSED_SHORT/CANCELLED	packages/types/src/freight/index.ts:353
S31 movement ledger	wagon_movements, kind EMPTY_REPOSITION, carries transfer_request_id	wagon-movement.entity.ts:16,49,55
S37 risk history	clearance_milestones.metadata → riskLevel + append-only riskHistory (oldest-first)	clearance-milestone.entity.ts:38, clearance-milestone.service.ts:250
S38 max 2 per truck	MAX_CONTAINERS_PER_TRUCK = 2, error A truck carries at most 2 containers	truck-load.util.ts:5,36
S38 duplicate container	409 Container X is already loaded onto another truck	truck-load.util.ts:52
S40 re-price parks the booking	batch pool is status = 'PAID' exactly, so PRICE_CHANGED_PENDING_CONFIRM holds zero capacity	bookings.repository.ts:1136

Corrected — same intent, different mechanism

S7 government. The scenario says government "jumps the queue" via an institution field and a +50,000 priority. Two corrections:

• the bonus is real (GOVERNMENT_PRIORITY_BONUS = 50_000, rule-engine.service.ts:258) but keys off bookings.is_government, set from contracts.is_government — there is no institution lookup;
• government does not merely outrank, it preempts: it displaces the lowest-priority already-reserved commercial booking and rides unpaid (preemptForGovernment, and see flows/government_preemption.cy.ts). Created via POST /bookings + POST /bookings/:id/government-expedite against a kind='government' company, not through the contract wizard.

S8 priority tiers. USD_PAYER / RAIL_AND_FORWARDING no longer exist as priority types — migration 1783000000000-ReplacePriorityRulesWithPriorityConfigs replaced priority_rules with priority_configs, whose type is only WAGON | CURRENCY | CUSTOMS, scored by wagon-count range (priority-config.entity.ts, applied at rule-engine.service.ts:247). The scenario's ordering intent survives as: a CURRENCY(USD) config, a CUSTOMS config, and a plain booking that matches neither.

S3 "day stays open". Best asserted through GET /bookings/:id/day-availability?date= → { fits, freeWagons, trainsForDay } (booking-transition.service.ts:1078), which is what the portal calendar reads.

Contradicted — the engine does NOT do this

These need a product decision before a test can be written honestly.

S26 — mid-corridor intercity is NOT blocked. The scenario expects Dire Dawa → GMP (both Ethiopian) to be rejected as disabled intercity. It is the opposite: DOMESTIC is a first-class direction derived from yard countries (bookings.service.ts:270), and the guard rejects non-Ethiopian endpoints — 'Intercity bookings only run between Ethiopian yards' (bookings.service.ts:218). The only related rejections are 'Intercity bookings cannot pin a date or schedule' (:771) and 'No route passes through this origin and destination in order'. → Either the scenario is stale, or intercity was meant to be disabled and is not. Ticket, not a test.

S29 — there is no out-of-order checkpoint guard. recordCheckpoint (train-scheduling.service.ts:3681) validates only: schedule exists, status is DISPATCHED, and the station is on the route. Nothing compares sequenceNo against the highest already logged, so "Arrived Adama" before "Passed Meiso" is accepted. currentSequenceNo is a Math.max (:3643) so the timeline does not visibly regress — which masks the real damage: the position fix at :3741 moves the locomotives, every wagon on the schedule, and the built train to that station's yard. A stray backward checkpoint silently relocates rolling stock. → Real bug. Worth a spec that documents current behaviour as .skip plus a ticket, rather than an assertion that pretends the guard exists.

S36 — importReleaseGranted is NOT gated on the second duty. The scenario expects release to stay false until the second duty settles. importReleaseGranted is computed from the IMPORT_RELEASE_GRANTED milestone (booking-clearance.service.ts:368), which completes purely by uploading a file with fieldname import_release. completeByDocTrigger (clearance-milestone.service.ts:430) performs no precondition check, and assertPriorCompleteOnMilestones only walks pre-booking milestones (clearance-workflow.service.ts:119) — so all 17 post-DO_COLLECTED codes, including the whole T1_CLOSED → RISK_ASSIGNED → SECOND_DUTY_* → IMPORT_RELEASE_GRANTED tail, are unordered. → Release can be granted with SECOND_DUTY_PAID still PENDING. Real gap.

S40 — hazardous quantity is NOT rejected, it is silently clamped. The scenario expects hazardousQuantity=12 on a quantity=10 line to be rejected. The DTO has @Min(0) and no @Max (create-booking.dto.ts:60), and the repository clamps to 0..quantity (bookings.repository.ts:217): the booking is created 201 with the value truncated, no warning. Reefer behaves identically. Note returnQuantity — same layer, same shape of data — does throw (contract-booking.service.ts:1740), so the pattern exists and these two just do not use it. → Real gap. A test asserting rejection would fail today.

S40 — reefer is NOT derived from container type. The scenario expects reeferQuantity forced to 0 for DRY types. No such logic exists; a DRY type with reeferQuantity > 0 is an explicitly supported state and applies the surcharge anyway (booking.entity.ts:384, booking-pricing.service.ts:402).

Flag-dependent — assert the flag, or the test is vacuous

S13/S14/S18 "export never splits" holds only while FREIGHT_EXPORT_SPLIT !== "true" (booking-batch.service.ts:394). With the flag on, isSplitEligible admits EXPORT (:2558) and tryExportPartialOffer (:1240) runs. The export specs must assert the flag is off, or they silently stop testing whole-or-nothing the day someone flips it.

Known type hole (not scenario-blocking)

Last-mile and first-mile billing write the literal 'last_mile' / 'first_mile' cast past the type checker (last-mile-invoice.service.ts:41), while Freight.InvoiceSource.LastMile is "lastmile". invoices.source is a plain varchar with no constraint, so both spellings persist. Writes and reads agree within each module so billing works — but S39's "invoice source LASTMILE" assertion must match 'last_mile', not the enum value.