edr-platform/integration/README.md

# Freight API integration suite

Headless, API-level tests for the freight API running against the **real**
`edr-payment-api`. Only the bank/wallet gateways are stubbed.

```
pnpm it:up      # build + start the stack (first run ~5 min)
pnpm it:test    # vitest run (auto-ups the stack if needed)
pnpm it:test -- --reporter=basic src/payment-happy.it.ts
pnpm it:logs payment-api-it
pnpm it:down    # -v, wipes the throwaway DB
```

## Stack

`docker-compose.it.yaml` is an **overlay** on `docker-compose.e2e.yaml` — same
freight API, Postgres (tmpfs), MinIO, Fayda/eTrade mocks; plus RabbitMQ, the
real payment API, and one gateway mock. It is a separate compose project
(`edr-freight-it`) on offset ports, so the Cypress e2e stack can run alongside.

```
freight-api-e2e :3111 ──HTTP──> payment-api-it :3113 ──HTTP──> gateway-mock-it :4600
        ^                              │
        └────────── RabbitMQ :5772 ─────┘   (outbox → payment.events → consumer)
```

Never `docker compose -f docker-compose.it.yaml` on its own — it needs the base
file first. Use `it.mjs`.

## Gateway mock

`gateway-mock/server.js` — one zero-dep `node:http` process serving every
provider under a path prefix, plus a control plane the tests drive:

| call | effect |
| --- | --- |
| `POST /__control/provider/:name` `{mode, times}` | `ok` / `fail` / `timeout` / `pending` / `paid` |
| `POST /__control/webhook` `{merchantOrderId, status, eventId, signature}` | fires a **correctly signed** callback at the payment API |
| `POST /__control/settle` `{merchantOrderId}` | pays at the bank with no callback (reconciliation path) |
| `GET /__control/calls` | every inbound provider call |
| `POST /__control/reset` | clear modes, orders and calls |

Signatures are real: the mock shares `CBE_SECRET_KEY` with the API, so
`verifyWebhookSignature` runs for real and `signature: "bad"` is a genuine
negative test. The suite drives **CBE Birr** end to end (plain HMAC, no key
material); other providers answer a generic stub until a scenario needs them.

Editing `server.js` needs a container restart (`docker compose … restart
gateway-mock-it`) — the code is a read-only mount, not baked into an image.

## Files

| file | covers |
| --- | --- |
| `src/payment-happy.it.ts` | initiate → webhook → outbox → broker → invoice PAID → booking advances |
| `src/payment-failure.it.ts` | provider down, decline, forged signature, reconciliation sweep, `unverifiable`, late capture |
| `src/concurrency.it.ts` | duplicate callbacks, two intents on one invoice, wagon budget, pay-window gate |
| `src/authz.it.ts` | cross-tenant isolation, login audience, service-token gates |
| `src/cbe-bill.it.ts` | inbound CBE Unified Bill: token → query (hops into freight) → payment |
| `src/bulk-import-full-train.it.ts` | six wheat bookings fill 54 wagons, then gate pass → T1 → dispatch → corridor → arrival → customs tail |
| `src/bulk-import-waiting-expiry.it.ts` | exact-fill trio selected, waiting three expire with the day |
| `src/bulk-import-split-promote.it.ts` | partial offer, split on settlement, expiry promotion, exact-remainder rebooking |
| `src/bulk-import-window-reopen.it.ts` | nobody pays → cycle 2 opens on the same train |
| `src/bulk-import-matrix.it.ts` | no-window day, sub-corridor, ride-along, whole-train giant |
| `src/bulk-export-full-train.it.ts` | FCFS accept = reservation, deadlines clamped to window close, export tail |
| `src/bulk-export-fcfs-space.it.ts` | reservations hold capacity, whole-or-nothing giant |
| `src/bulk-export-pay-or-lose.it.ts` | expiry frees space; window close expires the unpaid, no reopen |
| `src/bulk-export-matrix.it.ts` | mid-route boarding, leg occupancy, ride-along, sibling train windows |
| `src/bulk-b1-priority-expiry-refill.it.ts` | rule-engine priority band, expiry refill |
| `src/bulk-b2-per-item-floor.it.ts` | PER_ITEM wagon floor vs tonnage math |
| `src/bulk-b3-per-item-giant.it.ts` | PER_ITEM giant + line quantities (pins two defects) |
| `src/g1-s1-expiry-promotes-waitlist.it.ts` | 53-wagon built train: expiry frees exactly the waiting list's space |
| `src/g1-s2-exact-fill.it.ts` | exact 53/53 fill, every one of 68 containers mapped to a slot |
| `src/g1-s3-underfill-day-open.it.ts` | 28/53 is NOT FULL — the day still offers 25 wagons |
| `src/g1-s4-split-closes-gap.it.ts` | container split closes the last 3-wagon gap, 14-box remainder |
| `src/g1-s5-cascading-expiry.it.ts` | one settle promotes twice; expiries terminal, invoices closed |
| `src/g1-s6-s8-offers-government-tiers.it.ts` | ignored offer, government preemption, USD/customs/plain tiers |
| `src/g2-weight.it.ts` | weight before slots: base pull, overage tolerance, split sized on base only, light cargo |
| `src/flows.ts` | freight business steps, ported from `e2e/freight/cypress/e2e/flows/import-utils.ts` |

## Findings pinned by these tests

Where the platform's live behaviour differs from the scenario, the test asserts
what it actually does and says so in a comment, so a fix fails loudly:

- **Refill never supersedes an open partial offer** (`bulk-b1`, `g1-s5`). After
  the giant expires and frees 28 wagons, the offered booking is re-selected but
  keeps its stale 16-wagon offer; `applySplit` applies it, so the customer ships
  16 of 20 with room to spare. `g1-s5` pins the container half: an expiry frees
  8 more wagons and the 2-wagon offer beside them is never resized.
- **PER_ITEM bookings never get a partial offer** (`bulk-b3`). `sizeOffer` sizes
  bulk offers by weight off `cargoTotalWeightVgm`, which for PER_ITEM holds the
  ITEM COUNT — a 240-auto booking needing 60 wagons looks like 4, gets no offer,
  allocates nothing, and expires with the day.
- **The contract booking path drops bulk `hazardousQuantity` / `reeferQuantity`**
  (`bulk-b3`). Only `POST /api/bookings` maps and clamps them.
- **Paid intercity ride-alongs are unpinned back to the pool** (both matrices) —
  staff must place them again. The Cypress twin never sees this because its
  staff mark-paid shortcut leaves the reservation pinned.
- **Bulk priority is recomputed at doc-review** (`bulk-b1`), so writing
  `priority_score` directly is a no-op; ranking has to come from a WAGON
  priority config.
- **Freight sends a dev-shortcut amount** (1 minor unit, 10 for CAC) for every
  non-`CBE_BILL` provider, with no short-payment guard.
- **A BUILT train's batch is blind to the pull limit** (`g2-weight`, last
  describe). `remainingBudget` replaces the locomotive limits with
  `{wagons: physicalWagons, weightTons: Infinity, lengthMeters: Infinity}` the
  moment a schedule has a built train, so the batch reserves — and invoices —
  a load the locomotives cannot pull. The only check left is at wagon
  allocation, which then fails every tick with "Train set locomotives cannot
  pull the gross weight … limit 3500T incl. tolerance". The customer is PAID
  with zero wagons. Group 2 therefore runs its real weight scenarios on
  locomotive PAIRS, where the limits survive.
- **The allocator weighs the whole consist, the batch weighs the booking.**
  Allocation charges the tare of every wagon in the train set (53 × 22.4 T on
  the G2 consist), while `needFor` charges only the tare of the wagons the
  booking occupies — so the same 45-wagon load reads 3 528 T at reservation and
  3 707.2 T at allocation. Two capacity models, one train.
- **Government preemption cannot reach a FULL train** (`g1-s6-s8`). `isFillable`
  rejects a schedule whose `booking_window_status` is FULL before any budget or
  victim is considered, and `refreshWindowStatus` re-derives that flag from live
  capacity — so a genuinely full train is skipped and no commercial booking is
  ever displaced. S7 therefore commits 52 of 53 slots.
- **The CUSTOMS priority band is dead in the shipped fixture.** It applies only
  when the booking's SERVICE TYPE has `includes_customs`, and the corridor seed
  ships one service type that does not — so the two CUSTOMS bands never score.
  `seed-customs-service-type.sql` adds `RAIL_CUSTOMS` so the tier can be tested.
- **A customs SERVICE TYPE without a customs CONTRACT cannot finalize
  clearance.** `finalizeClearance` looks up `clearance_output_<op>_<freight>`,
  which the seeder deliberately leaves commented out, so `getByCode` 404s. Only
  the phased path (`customs_clearing_enabled` on the contract) avoids it — which
  is why S8's customs tenant is Path B.

## Gotchas

- **One unpaid hold per company.** `assertNoUnpaidHold` blocks a company with a
  `SELECTED_FOR_BATCH` booking from creating another. Every file starts with
  `releaseUnpaidHolds()`, which also hard-deletes retired
  `train_schedule_bookings` rows (`booking_id` is UNIQUE and the constraint
  ignores `deleted_at`, so a soft-unlinked booking can never be re-batched).
- **Arrange is slow.** Contract → booking → clearance → ops accept → batch is
  30–60s of real API work per booking, so files share one schedule day.
- Files run sequentially (one DB); concurrency is exercised inside a test with
  `Promise.all`.
- **A retired fixture keeps its shipment day at its peril.**
  `rescueStrandedPaidForDay` sweeps every unlinked booking whose
  `payment_status` is PAID and whose `scheduled_date` falls on the day being
  filled, and re-places it on the fresh train. A previous run's paid bookings
  therefore climb back aboard — 18 stowaway wagons on a 28-wagon day, until
  `releaseUnpaidHolds` / `resetCorridorDay` started nulling `scheduled_date`.
- **Only a FULL train rests at DONE.** An under-filled day CONCLUDES and
  REOPENS (`window_phase` back to OPEN, `booking_cycle_no` 2), so waiting for
  DONE there waits forever — use `pollCycleConcluded`.
- **Wagon stock is finite and shared.** Paid bookings keep their wagons, so
  `releaseUnpaidHolds()` also frees every earlier `CTR-IT-%` allocation —
  without it the fifth or sixth file on a warm stack silently gets a short
  consist.
- **One tenant per booking.** `seedTenantContracts` mints a company per booking
  because a company may hold only one unpaid reservation at a time; staff book
  and pay on their behalf, which is also the real Path B flow.
- **The weight axis is GROSS, but the column is not.**
  `wagon_booking_allocations.allocated_weight_tons` holds CARGO only;
  `allocatedGrossTons` adds each wagon type's tare, because the pull limit is
  spent on both. Two 20ft at 28 T ride one wagon at 78.4 T gross — 35 of those
  spend a 3 500 T locomotive pair, and reading the raw column would report
  1 960 T and hide it.
- **Group 1 rides a BUILT train, not a loco pair.** `maxWagonsPerTrain` is not a
  cap: `syncScheduleMaxWagons` recomputes it from locomotive length (54 here)
  every fill pass. A built train's coupled consist wins outright, so
  `seed-g1-train.sql`'s 53 wagons ARE the capacity — the number every G1
  scenario's arithmetic is written in. `createBuiltTrainSchedule` asserts it.
- **Customs bookings walk the phased chain** (`clearBookingPhasedCustoms`):
  transit assignee → declaration draft → accept → declaration → duty →
  transit permit → pre-clearance → delivery order. `clearance/finalize` refuses
  them outright.
- Freight sends a dev-shortcut amount (1 minor unit, 10 for CAC) for every
  non-`CBE_BILL` provider. The tests assert that as-is.