Merge branch 'dev' into reschedule

apps/edr-freight-api/.env.example

@@ -202,14 +202,13 @@ EIMS_NATURE_OF_SUPPLIES=service
 EIMS_PAYMENT_MODE=CASH
 EIMS_PAYMENT_TERM=IMMIDIATE
 EIMS_UNIT_DEFAULT=PCS
-# MoR numeric country code for the buyer; our companies store the country name.
-EIMS_BUYER_COUNTRY_CODE=
-# Buyer region name -> MoR numeric code. companies.region holds names; MoR wants ^[0-9]{1,3}$.
-# An unmapped region fails locally rather than being filed with a guess.
-EIMS_BUYER_REGION_CODES=Addis Ababa=13
-# Same mechanism for Wereda. MoR has never named a Wereda regex in an error (only Region's is
-# confirmed), so this is precautionary — but an unmapped name still fails locally, not filed as a guess.
-EIMS_BUYER_WEREDA_CODES=
+# Buyer Country/Region/City/Wereda are NOT configured here any more. They are resolved from the
+# Ministry's own location master (EIMS_COUNTRY_REGION_VW), committed as
+# src/config/mor-locations.data.ts and regenerated with:
+#   pnpm --filter @edr/freight-api eims:import-locations <workbook.xlsx>
+# The removed EIMS_BUYER_COUNTRY_CODE / _COUNTRY_CODES / _REGION_CODES / _CITY_CODES /
+# _WEREDA_CODES maps are ignored if still set — MoR reference data is the only source, and an env
+# var must not be able to override an official code. Delete them from your deployment config.
 EIMS_CASHIER_NAME=
 EIMS_SALESPERSON_NAME=
 # Automatic filing of issued invoices (@Cron sweep, one invoice per tick).

apps/edr-freight-api/package.json

@@ -38,7 +38,8 @@
     "iam:migration:show": "pnpm run iam:typeorm:cli migration:show",
     "migration:run": "nest build && node dist/scripts/migrate.js",
     "script": "ts-node -r tsconfig-paths/register src/scripts/main.ts",
-    "eims:login": "ts-node -r tsconfig-paths/register src/scripts/eims-login.ts"
+    "eims:login": "ts-node -r tsconfig-paths/register src/scripts/eims-login.ts",
+    "eims:import-locations": "ts-node -r tsconfig-paths/register src/scripts/import-mor-locations.ts"
   },
   "dependencies": {
     "@edr/api-common": "workspace:*",

apps/edr-freight-api/scripts/run-legboard-tests.ts

@@ -0,0 +1,339 @@
+/**
+ * 10 scenarios against the REAL S-2026-00045 consist (42 NW5 + 10 PW2) on the
+ * real DCT -> DIRE_DAWA -> GMP corridor, checking the three reported issues:
+ *
+ *   1. LEG BOARD truthfulness — can you tell which booking rides which leg?
+ *   2. CONSIST DIAGRAM — does a shared wagon expose one row per load?
+ *   3. PARTIAL OFFER — when only the 10 PW2 are free, is the customer offered
+ *      the part that fits instead of being dropped silently?
+ *
+ * Read-only. Run:  npx ts-node -T scripts/run-legboard-tests.ts
+ */
+import { DataSource } from 'typeorm';
+
+import {
+  planWagonsWithStock,
+  type AllowedWagonTypeMap,
+  type WagonStock,
+} from '../src/modules/train-scheduling/wagon-plan-flex.util';
+import { validateWagonCargoExclusivity } from '../src/modules/train-scheduling/utils/wagon-plan.util';
+import { sizePartialOfferWagons, bulkTonsPerWagon } from '../src/modules/train-scheduling/train-capacity.util';
+import type { Booking } from '../src/modules/bookings/entities/booking.entity';
+import type { WagonType } from '../src/modules/wagon-types/entities/wagon-type.entity';
+
+const YARD = {
+  DCT: 'fc558b95-da28-4fc3-8348-311a290c34ae',
+  DIRE: 'f7b1686f-d43e-42aa-bc6a-d3d5849296c9',
+  GMP: '61ae1e66-c229-4dcd-9851-b2b9424f3a95',
+};
+const STOPS = [YARD.DCT, YARD.DIRE, YARD.GMP];
+const STOP_NAME = ['DCT', 'DIRE', 'GMP'];
+const NW5 = '8f717b09-eec1-46ad-be3d-2dc0a56e55e7';
+const PW2 = '8eec3a7d-8482-4397-96b6-59a028210722';
+const PERISHABLE = 'a5991d3a-d690-4b7e-98fd-ea3333aa16e7';
+const FT40 = '349072e7-8a90-4c03-b682-08976abfd7e8';
+
+const ds = new DataSource({
+  type: 'postgres',
+  host: process.env.DB_HOST || '10.18.7.207',
+  port: Number(process.env.DB_PORT || 5432),
+  database: process.env.DB_NAME || 'edr_dev',
+  username: process.env.DB_USER || 'postgres',
+  password: process.env.DB_PASSWORD || 'dcba@1234',
+});
+
+type Check = { name: string; pass: boolean; detail: string };
+const groups: Array<{ scenario: string; checks: Check[] }> = [];
+const add = (l: Check[], name: string, pass: boolean, detail: string) =>
+  l.push({ name, pass, detail });
+
+let TYPES: WagonType[] = [];
+let ALLOWED: AllowedWagonTypeMap;
+let CODES = new Map<string, string>();
+let CARGO: any;
+
+async function loadConfig() {
+  TYPES = await ds.query(
+    `SELECT id, code, name, capacity_tons AS "capacityTons",
+            length_meters AS "lengthMeters", tare_weight_tons AS "tareWeightTons",
+            supports_container AS "supportsContainer", is_active AS "isActive"
+       FROM freight.wagon_types WHERE is_active IS NOT FALSE`);
+  const byId = new Map(TYPES.map((t) => [t.id, t]));
+  CODES = new Map(TYPES.map((t) => [t.id, t.code]));
+  const rows = async (sql: string) => {
+    const r: Array<{ typeId: string; wagonTypeId: string }> = await ds.query(sql);
+    const m = new Map<string, WagonType[]>();
+    for (const x of r) {
+      const wt = byId.get(x.wagonTypeId);
+      if (wt) m.set(x.typeId, [...(m.get(x.typeId) ?? []), wt]);
+    }
+    return m;
+  };
+  ALLOWED = {
+    byCargoTypeId: await rows(
+      `SELECT cargo_type_id AS "typeId", wagon_type_id AS "wagonTypeId" FROM freight.cargo_type_wagon_types`),
+    byContainerTypeId: await rows(
+      `SELECT container_type_id AS "typeId", wagon_type_id AS "wagonTypeId" FROM freight.container_type_wagon_types`),
+  };
+  const [c] = await ds.query(
+    `SELECT id, cargo_type_name AS "cargoTypeName", code, unit_of_measure AS "unitOfMeasure",
+            tons_per_wagon_map AS "tonsPerWagonMap", items_per_wagon_map AS "itemsPerWagonMap"
+       FROM freight.cargo_types WHERE id=$1`, [PERISHABLE]);
+  CARGO = { ...c, wagonTypes: ALLOWED.byCargoTypeId.get(PERISHABLE) ?? [] };
+}
+
+let seq = 0;
+const bulk = (ref: string, tons: number, from: string, to: string, paid = false): Booking =>
+  ({
+    id: `bulk-${(seq += 1)}`, reference: ref, freightType: 'BULK',
+    cargoTotalWeightVgm: tons, cargoTypeId: PERISHABLE, cargoType: CARGO,
+    originYardId: from, destinationYardId: to, bookingContainers: [],
+    status: paid ? 'PAID' : 'CLEARANCE_READY',
+    paymentStatus: paid ? 'PAID' : 'PENDING',
+  }) as unknown as Booking;
+
+const cont = (ref: string, qty: number, from: string, to: string, paid = false): Booking =>
+  ({
+    id: `cont-${(seq += 1)}`, reference: ref, freightType: 'CONTAINER',
+    cargoTotalWeightVgm: qty * 26, originYardId: from, destinationYardId: to,
+    status: paid ? 'PAID' : 'CLEARANCE_READY',
+    paymentStatus: paid ? 'PAID' : 'PENDING',
+    bookingContainers: [{
+      id: `line-${seq}`, containerTypeId: FT40, quantity: qty,
+      vgmPerUnitTons: 26, wagonsRequired: qty,
+      containerType: { id: FT40, code: '40FT', sizeFt: 40 }, units: [],
+    }],
+  }) as unknown as Booking;
+
+const stockOf = (nw5: number, pw2: number): WagonStock => ({
+  mode: 'TRAIN',
+  remainingByTypeId: new Map([[NW5, nw5], [PW2, pw2]]),
+  codesByTypeId: CODES,
+});
+
+const legsOf = (bs: Booking[]) =>
+  new Map(bs.map((b: any) => [b.id,
+    { from: STOPS.indexOf(b.originYardId), to: STOPS.indexOf(b.destinationYardId) }]));
+
+const plan = (bs: Booking[], stock: WagonStock) =>
+  planWagonsWithStock({
+    bookings: bs, allowed: ALLOWED, stock, legs: legsOf(bs),
+    edgeCount: 2, stops: STOPS,
+  });
+
+const byType = (p: any[]) => {
+  const c = new Map<string, number>();
+  for (const s of p) c.set(s.wagonTypeCode, (c.get(s.wagonTypeCode) ?? 0) + 1);
+  return [...c.entries()].map(([k, n]) => `${n}x ${k}`).join(', ') || 'none';
+};
+
+/**
+ * What the LEG BOARD can actually say about a slot, given only the fields it
+ * reads (boardYardId / alightYardId) — this is the UI's own view.
+ */
+const stampSpan = (slot: any, bs: Booking[]) => {
+  const byId = new Map(bs.map((b: any) => [b.id, b]));
+  const sb = [...new Set(slot.allocations.map((a: any) => a.bookingId))]
+    .map((id) => byId.get(id as string)).filter(Boolean) as any[];
+  if (!sb.length) return null;
+  const first = sb[0];
+  const same = sb.every((b) =>
+    b.originYardId === first.originYardId && b.destinationYardId === first.destinationYardId);
+  if (same) {
+    return {
+      from: STOPS.indexOf(first.originYardId),
+      to: STOPS.indexOf(first.destinationYardId),
+      union: false,
+    };
+  }
+  let from = Infinity, to = -Infinity;
+  for (const b of sb) {
+    from = Math.min(from, STOPS.indexOf(b.originYardId));
+    to = Math.max(to, STOPS.indexOf(b.destinationYardId));
+  }
+  return { from, to, union: true };
+};
+
+async function main() {
+  await ds.initialize();
+  await loadConfig();
+
+  console.log('\n=== REAL CONSIST (S-2026-00045): 42 NW5 + 10 PW2 ===');
+  console.log('Corridor: DCT -> DIRE -> GMP   (edge 0 = DCT->DIRE, edge 1 = DIRE->GMP)\n');
+
+  // ============================================================ SCENARIO 1
+  // The reported shape: 42x40ft intercity Dire->GMP + bulk DCT->GMP.
+  {
+    const checks: Check[] = [];
+    const bs = [cont('IC-42', 42, YARD.DIRE, YARD.GMP), bulk('BULK-695', 695, YARD.DCT, YARD.GMP, true)];
+    const r = plan(bs, stockOf(42, 10));
+    console.log('── S1: 42x40ft Dire->GMP (intercity) + 695T bulk DCT->GMP (paid)');
+    console.log(`   plan ${r.plan.length} wagons — ${byType(r.plan)}`);
+    for (const d of r.deferred) console.log(`   DEFERRED ${d.reference}: ${d.reason}`);
+
+    // Every slot must say, truthfully, which legs it is busy on.
+    const shared = r.plan.filter((s) => {
+      const refs = new Set(s.allocations.map((a) => a.bookingReference));
+      return refs.size > 1;
+    });
+    add(checks, 'shared wagons expose EVERY load (diagram can stack them)',
+      shared.every((s) => s.allocations.length >= 2),
+      `${shared.length} shared wagon(s); allocations per shared wagon: ${
+        shared.map((s) => s.allocations.length).join(',') || 'n/a'}`);
+
+    // The leg-board reads ONE span per slot. For a mixed-corridor wagon that
+    // span is the UNION, which cannot say which load rides which leg.
+    const mixed = r.plan.map((s) => stampSpan(s, bs)).filter((x) => x?.union);
+    add(checks, 'no wagon needs a UNION span (leg board stays truthful)',
+      mixed.length === 0,
+      mixed.length
+        ? `${mixed.length} wagon(s) carry different corridors -> leg board shows one merged bar`
+        : 'every wagon carries a single corridor');
+    add(checks, 'per-edge exclusivity holds',
+      validateWagonCargoExclusivity(r.plan, legsOf(bs), 2).length === 0, 'clean');
+    groups.push({ scenario: 'S1 — intercity 42x40ft + paid bulk (the reported case)', checks });
+  }
+
+  // ============================================================ SCENARIO 2
+  // Only the 10 PW2 are free — the staging complaint.
+  {
+    const checks: Check[] = [];
+    const b = bulk('BULK-695', 695, YARD.DCT, YARD.GMP, true);
+    const r = plan([b], stockOf(0, 10));
+    console.log('\n── S2: 695T bulk, ONLY 10 PW2 free (0 NW5)');
+    console.log(`   plan ${r.plan.length} wagons — ${byType(r.plan)}`);
+    for (const d of r.deferred) console.log(`   DEFERRED ${d.reference}: ${d.reason}`);
+
+    add(checks, 'whole booking correctly refused (10 PW2 x 20T = 200T < 695T)',
+      r.deferred.length === 1 && r.fitting.length === 0,
+      r.deferred[0]?.reason ?? 'unexpectedly fitted');
+
+    // What SHOULD happen: offer the part that fits on those 10 PW2.
+    const perWagonTons = bulkTonsPerWagon(CARGO, PW2, 70);
+    const pw2Type = TYPES.find((t) => t.id === PW2)!;
+    const wholeWagons = Math.ceil(695 / perWagonTons);
+    const offer = sizePartialOfferWagons(
+      { wagons: 10, weightTons: 3500, lengthMeters: 1520 },
+      wholeWagons,
+      { capacityTons: perWagonTons,
+        tareWeightTons: Number(pw2Type.tareWeightTons),
+        lengthMeters: Number(pw2Type.lengthMeters) },
+      { fullWagonsOnly: true },
+    );
+    console.log(`   partial offer sizing: ${offer ? `${offer.wagons} PW2 = ${offer.maxCargoTons}T of 695T` : 'NONE'}`);
+    add(checks, 'a partial offer of 10 PW2 (200T) is sizeable for the customer',
+      offer != null && offer.wagons === 10 && offer.maxCargoTons === 200,
+      offer ? `${offer.wagons} PW2 x ${perWagonTons}T = ${offer.maxCargoTons}T` : 'no offer could be sized');
+    groups.push({ scenario: 'S2 — only 10 PW2 free: split offer instead of silent drop', checks });
+  }
+
+  // ============================================================ SCENARIO 3-10
+  const cases: Array<{ name: string; bookings: Booking[]; stock: WagonStock; expectFit?: string[] }> = [
+    { name: 'S3 — bulk DCT->DIRE + bulk DIRE->GMP (disjoint, reuse expected)',
+      bookings: [bulk('B-L1', 200, YARD.DCT, YARD.DIRE), bulk('B-L2', 200, YARD.DIRE, YARD.GMP)],
+      stock: stockOf(7, 0) },
+    { name: 'S4 — container DCT->DIRE then bulk DIRE->GMP on same wagons',
+      bookings: [cont('C-L1', 7, YARD.DCT, YARD.DIRE), bulk('B-L2', 210, YARD.DIRE, YARD.GMP)],
+      stock: stockOf(7, 0) },
+    { name: 'S5 — three corridors at once (DCT->DIRE, DIRE->GMP, DCT->GMP)',
+      bookings: [cont('C-A', 5, YARD.DCT, YARD.DIRE), cont('C-B', 5, YARD.DIRE, YARD.GMP),
+                 bulk('B-FULL', 150, YARD.DCT, YARD.GMP, true)],
+      stock: stockOf(12, 10) },
+    { name: 'S6 — paid bulk vs unpaid containers, scarce NW5',
+      bookings: [cont('C-UNPAID', 20, YARD.DCT, YARD.GMP), bulk('B-PAID', 300, YARD.DCT, YARD.GMP, true)],
+      stock: stockOf(20, 10) },
+    { name: 'S7 — two paid bulks competing for the same PW2',
+      bookings: [bulk('B-P1', 200, YARD.DCT, YARD.GMP, true), bulk('B-P2', 200, YARD.DCT, YARD.GMP, true)],
+      stock: stockOf(5, 10) },
+    { name: 'S8 — bulk exactly filling the PW2 (200T)',
+      bookings: [bulk('B-EXACT', 200, YARD.DCT, YARD.GMP, true)],
+      stock: stockOf(0, 10) },
+    { name: 'S9 — 1T over the PW2 capacity (201T)',
+      bookings: [bulk('B-OVER', 201, YARD.DCT, YARD.GMP, true)],
+      stock: stockOf(0, 10) },
+    { name: 'S10 — full train: containers both legs + bulk through',
+      bookings: [cont('C-1', 42, YARD.DCT, YARD.DIRE), cont('C-2', 42, YARD.DIRE, YARD.GMP),
+                 bulk('B-THRU', 200, YARD.DCT, YARD.GMP, true)],
+      stock: stockOf(42, 10) },
+  ];
+
+  for (const c of cases) {
+    const checks: Check[] = [];
+    const r = plan(c.bookings, c.stock);
+    const legs = legsOf(c.bookings);
+    console.log(`\n── ${c.name}`);
+    console.log(`   plan ${r.plan.length} wagons — ${byType(r.plan)}`);
+    console.log(`   fitting: ${r.fitting.map((b) => b.reference).join(', ') || 'none'}`);
+    for (const d of r.deferred) console.log(`   DEFERRED ${d.reference}: ${d.reason}`);
+    for (const s of r.plan.filter((x) => x.allocations.length > 1)) {
+      const spans = s.allocations.map((a) => {
+        const l = legs.get(a.bookingId)!;
+        return `${a.bookingReference}[${STOP_NAME[l.from]}->${STOP_NAME[l.to]}]`;
+      });
+      console.log(`   wagon #${s.sequenceNo} ${s.wagonTypeCode}: ${spans.join(' + ')}`);
+    }
+
+    add(checks, 'per-edge cargo exclusivity holds',
+      validateWagonCargoExclusivity(r.plan, legs, 2).length === 0,
+      validateWagonCargoExclusivity(r.plan, legs, 2).join('; ') || 'clean');
+    add(checks, 'every planned wagon carries at least one allocation',
+      r.plan.every((s) => s.allocations.length > 0),
+      `${r.plan.filter((s) => !s.allocations.length).length} empty slot(s)`);
+    // Per-EDGE cap: a wagon reused on two disjoint legs carries its cap on
+    // each leg, so assignedWeightTons (the whole-journey sum) may exceed one
+    // leg's cap legitimately. Check the heaviest single leg instead.
+    const overCap = r.plan.filter((s) => s.slotLoadType === 'BULK').filter((s) => {
+      const cap = bulkTonsPerWagon(CARGO, s.wagonTypeId, Number(s.capacityTons));
+      const perEdge = [0, 0];
+      for (const a of s.allocations) {
+        const l = legs.get(a.bookingId)!;
+        for (let e = l.from; e < l.to; e += 1) perEdge[e] += a.allocatedWeightTons;
+      }
+      return Math.max(...perEdge) > cap + 0.001;
+    });
+    add(checks, 'no bulk wagon exceeds its cargo cap on any single leg',
+      overCap.length === 0,
+      overCap.length ? `${overCap.length} wagon(s) over cap` : 'caps respected per leg');
+    // Leg-board truthfulness for every shared wagon.
+    // The leg board no longer relies on the slot's union span: each allocation
+    // carries its booking's own yards, so the UI splits a shared wagon into one
+    // bar per corridor. Assert that data IS derivable for every shared wagon.
+    const unionSpans = r.plan.map((s) => stampSpan(s, c.bookings)).filter((x) => x?.union);
+    const splittable = r.plan
+      .filter((s) => s.allocations.length > 1)
+      .every((s) => {
+        const corridors = new Set(
+          s.allocations.map((a) => {
+            const l = legs.get(a.bookingId);
+            return l ? `${l.from}-${l.to}` : 'unknown';
+          }),
+        );
+        return !corridors.has('unknown');
+      });
+    add(checks, 'leg board can name the leg of every load (per-allocation corridors)',
+      splittable,
+      unionSpans.length
+        ? `${unionSpans.length} wagon(s) span a union — UI splits them into ${
+            [...new Set(r.plan.flatMap((s) => s.allocations.map((a) => {
+              const l = legs.get(a.bookingId)!;
+              return `${STOP_NAME[l.from]}->${STOP_NAME[l.to]}`;
+            })))].join(' | ')} bars`
+        : 'no shared wagons; spans already exact');
+    groups.push({ scenario: c.name, checks });
+  }
+
+  console.log('\n\n================ REPORT ================');
+  let pass = 0, fail = 0;
+  for (const g of groups) {
+    console.log(`\n${g.scenario}`);
+    for (const c of g.checks) {
+      console.log(`  ${c.pass ? 'PASS' : 'FAIL'}  ${c.name}\n        ${c.detail}`);
+      c.pass ? (pass += 1) : (fail += 1);
+    }
+  }
+  console.log(`\n----------------------------------------`);
+  console.log(`TOTAL: ${pass} passed, ${fail} failed`);
+  await ds.destroy();
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

apps/edr-freight-api/scripts/run-s45-scenario.ts

@@ -0,0 +1,236 @@
+/**
+ * Reproduces the reported S-2026-00045 failure: three DCT->Dire container
+ * bookings + one Dire->GMP container booking are allocated, but the
+ * DCT->GMP 695T bulk booking is never selected even though PW2 and NW5
+ * wagons are free.
+ *
+ * Runs the REAL planner against the REAL 42 NW5 + 10 PW2 consist, in several
+ * booking orders (= different window cycles / arrival orders).
+ *
+ *   npx ts-node -T scripts/run-s45-scenario.ts
+ */
+import { DataSource } from 'typeorm';
+
+import {
+  planWagonsWithStock,
+  type AllowedWagonTypeMap,
+  type WagonStock,
+} from '../src/modules/train-scheduling/wagon-plan-flex.util';
+import { validateWagonCargoExclusivity } from '../src/modules/train-scheduling/utils/wagon-plan.util';
+import type { Booking } from '../src/modules/bookings/entities/booking.entity';
+import type { WagonType } from '../src/modules/wagon-types/entities/wagon-type.entity';
+
+const YARD = {
+  DCT: 'fc558b95-da28-4fc3-8348-311a290c34ae',
+  DIRE: 'f7b1686f-d43e-42aa-bc6a-d3d5849296c9',
+  GMP: '61ae1e66-c229-4dcd-9851-b2b9424f3a95',
+};
+const STOPS = [YARD.DCT, YARD.DIRE, YARD.GMP];
+const NW5 = '8f717b09-eec1-46ad-be3d-2dc0a56e55e7';
+const PW2 = '8eec3a7d-8482-4397-96b6-59a028210722';
+const TRAIN_ID = '56eec969-55ec-4bc5-aad6-f4b7b6d17292';
+
+const ds = new DataSource({
+  type: 'postgres',
+  host: process.env.DB_HOST || '10.18.7.207',
+  port: Number(process.env.DB_PORT || 5432),
+  database: process.env.DB_NAME || 'edr_dev',
+  username: process.env.DB_USER || 'postgres',
+  password: process.env.DB_PASSWORD || 'dcba@1234',
+});
+
+async function loadConfig(): Promise<{
+  allowed: AllowedWagonTypeMap;
+  codes: Map<string, string>;
+}> {
+  const types: WagonType[] = await ds.query(
+    `SELECT id, code, name, capacity_tons AS "capacityTons",
+            length_meters AS "lengthMeters", tare_weight_tons AS "tareWeightTons",
+            supports_container AS "supportsContainer", is_active AS "isActive"
+       FROM freight.wagon_types WHERE is_active IS NOT FALSE`,
+  );
+  const byId = new Map(types.map((t) => [t.id, t]));
+  const rows = async (sql: string) => {
+    const r: Array<{ typeId: string; wagonTypeId: string }> = await ds.query(sql);
+    const map = new Map<string, WagonType[]>();
+    for (const row of r) {
+      const wt = byId.get(row.wagonTypeId);
+      if (wt) map.set(row.typeId, [...(map.get(row.typeId) ?? []), wt]);
+    }
+    return map;
+  };
+  return {
+    allowed: {
+      byCargoTypeId: await rows(
+        `SELECT cargo_type_id AS "typeId", wagon_type_id AS "wagonTypeId" FROM freight.cargo_type_wagon_types`),
+      byContainerTypeId: await rows(
+        `SELECT container_type_id AS "typeId", wagon_type_id AS "wagonTypeId" FROM freight.container_type_wagon_types`),
+    },
+    codes: new Map(types.map((t) => [t.id, t.code])),
+  };
+}
+
+async function loadBookings(allowed: AllowedWagonTypeMap): Promise<Map<string, Booking>> {
+  const rows = await ds.query(
+    `SELECT b.id, b.reference, b.freight_type AS "freightType",
+            b.cargo_total_weight_vgm AS "cargoTotalWeightVgm",
+            b.bulk_total_weight_tons AS "bulkTotalWeightTons",
+            b.cargo_type_id AS "cargoTypeId", b.origin_yard_id AS "originYardId",
+            b.destination_yard_id AS "destinationYardId",
+            b.is_government AS "isGovernment", b.priority_score AS "priorityScore",
+            b.status, b.payment_status AS "paymentStatus",
+            b.created_at AS "createdAt"
+       FROM freight.bookings b
+      WHERE b.reference LIKE 'SF45-%' AND b.deleted_at IS NULL`);
+  const cargo = await ds.query(
+    `SELECT id, cargo_type_name AS "cargoTypeName", code,
+            unit_of_measure AS "unitOfMeasure",
+            tons_per_wagon_map AS "tonsPerWagonMap",
+            items_per_wagon_map AS "itemsPerWagonMap" FROM freight.cargo_types`);
+  const cargoById = new Map(cargo.map((c: any) => [c.id, c]));
+  const lines = await ds.query(
+    `SELECT bc.id, bc.booking_id AS "bookingId", bc.container_type_id AS "containerTypeId",
+            bc.quantity, bc.vgm_per_unit_tons AS "vgmPerUnitTons",
+            bc.wagons_required AS "wagonsRequired", ct.code, ct.size_ft AS "sizeFt"
+       FROM freight.booking_container bc
+       JOIN freight.container_types ct ON ct.id = bc.container_type_id
+      WHERE bc.booking_id = ANY($1) AND bc.deleted_at IS NULL`,
+    [rows.map((r: any) => r.id)]);
+
+  return new Map(rows.map((r: any) => {
+    const ct = r.cargoTypeId ? cargoById.get(r.cargoTypeId) : null;
+    return [r.reference, {
+      ...r,
+      cargoType: ct
+        ? { ...ct, wagonTypes: allowed.byCargoTypeId.get(r.cargoTypeId) ?? [] }
+        : null,
+      bookingContainers: lines.filter((l: any) => l.bookingId === r.id).map((l: any) => ({
+        ...l,
+        containerType: { id: l.containerTypeId, code: l.code, sizeFt: l.sizeFt },
+        units: [],
+      })),
+    } as unknown as Booking];
+  }));
+}
+
+/** The train's real consist, as TRAIN-mode stock. */
+async function consistStock(codes: Map<string, string>): Promise<WagonStock> {
+  const rows = await ds.query(
+    `SELECT wagon_type_id AS "wagonTypeId", count(*)::int AS n
+       FROM freight.wagons
+      WHERE train_id = $1 AND deleted_at IS NULL
+      GROUP BY wagon_type_id`, [TRAIN_ID]);
+  return {
+    mode: 'TRAIN',
+    remainingByTypeId: new Map(rows.map((r: any) => [r.wagonTypeId, r.n])),
+    codesByTypeId: codes,
+  };
+}
+
+const planByType = (plan: any[]) => {
+  const c = new Map<string, number>();
+  for (const s of plan) c.set(s.wagonTypeCode, (c.get(s.wagonTypeCode) ?? 0) + 1);
+  return [...c.entries()].map(([k, n]) => `${n}x ${k}`).join(', ') || 'none';
+};
+
+/** Gross tons riding each corridor edge — the locomotive pull check. */
+const perEdgeGross = (plan: any[], legs: Map<string, { from: number; to: number }>) => {
+  const edges = [0, 0];
+  for (const slot of plan) {
+    const spans = slot.allocations.map((a: any) => legs.get(a.bookingId) ?? { from: 0, to: 2 });
+    const from = Math.min(...spans.map((s: any) => s.from));
+    const to = Math.max(...spans.map((s: any) => s.to));
+    for (let e = from; e < to; e += 1) {
+      edges[e] += Number(slot.tareWeightTons) + Number(slot.assignedWeightTons);
+    }
+  }
+  return edges.map((t) => Math.round(t));
+};
+
+async function main() {
+  await ds.initialize();
+  const { allowed, codes } = await loadConfig();
+  const byRef = await loadBookings(allowed);
+  const stock = await consistStock(codes);
+
+  console.log('\n=== S-2026-00045 CONSIST (real) ===');
+  console.table([...stock.remainingByTypeId.entries()].map(([id, n]) => ({
+    wagonType: codes.get(id), wagons: n })));
+  console.log('Route: DCT -> DIRE_DAWA -> GMP (2 edges)   Loco pull: 3500T / 1520m\n');
+
+  const ORDERS: Array<{ name: string; refs: string[] }> = [
+    { name: '1. STAGING ORDER (containers first, bulk last)',
+      refs: ['SF45-5', 'SF45-3', 'SF45-2', 'SF45-1', 'SF45-4'] },
+    { name: '2. BULK FIRST (bulk books earliest window)',
+      refs: ['SF45-4', 'SF45-1', 'SF45-2', 'SF45-3', 'SF45-5'] },
+    { name: '3. BULK IN THE MIDDLE',
+      refs: ['SF45-1', 'SF45-2', 'SF45-4', 'SF45-3', 'SF45-5'] },
+    { name: '4. SEQUENTIAL (as listed by the user)',
+      refs: ['SF45-1', 'SF45-2', 'SF45-3', 'SF45-4', 'SF45-5'] },
+    { name: '5. BULK ONLY (nothing competing)',
+      refs: ['SF45-4'] },
+    { name: '6. BULK + the Dire->GMP leg only',
+      refs: ['SF45-5', 'SF45-4'] },
+  ];
+
+  const summary: Array<Record<string, unknown>> = [];
+  // Second pass models the staging reality: the bulk booking is PAID (the
+  // customer's money is already taken) while the containers are not.
+  const PAID_BULK = process.env.PAID_BULK === '1';
+
+  for (const order of ORDERS) {
+    const bookings = order.refs.map((r) => {
+      const b = byRef.get(r)!;
+      if (!b) return b;
+      return PAID_BULK && r === 'SF45-4'
+        ? ({ ...b, status: 'PAID', paymentStatus: 'PAID' } as Booking)
+        : b;
+    }).filter(Boolean);
+    const legs = new Map(bookings.map((b: any) => [
+      b.id,
+      { from: STOPS.indexOf(b.originYardId), to: STOPS.indexOf(b.destinationYardId) },
+    ]));
+    const result = planWagonsWithStock({
+      bookings, allowed,
+      stock: {
+        ...stock,
+        remainingByTypeId: new Map(stock.remainingByTypeId),
+      },
+      legs, edgeCount: 2, stops: STOPS,
+    });
+
+    const refOf = (id: string) =>
+      bookings.find((b: any) => b.id === id)?.reference ?? id;
+    const bulkFitted = result.fitting.some((b) => b.reference === 'SF45-4');
+    const bulkDeferred = result.deferred.find((d) => d.reference === 'SF45-4');
+    const gross = perEdgeGross(result.plan, legs);
+    const excl = validateWagonCargoExclusivity(result.plan, legs, 2);
+
+    console.log(`\n──────── ${order.name} ────────`);
+    console.log(`order: ${order.refs.join(' -> ')}`);
+    console.log(`plan: ${result.plan.length} wagons — ${planByType(result.plan)}`);
+    console.log(`gross per edge: DCT->Dire ${gross[0]}T | Dire->GMP ${gross[1]}T  (limit 3500T)`);
+    console.log(`fitting:  ${result.fitting.map((b) => b.reference).join(', ') || 'none'}`);
+    for (const d of result.deferred) console.log(`DEFERRED: ${d.reference} — ${d.reason}`);
+    if (excl.length) console.log(`EXCLUSIVITY VIOLATION: ${excl.join('; ')}`);
+    const bulkSlots = result.plan.filter((s) =>
+      s.allocations.some((a) => refOf(a.bookingId) === 'SF45-4'));
+    if (bulkSlots.length) {
+      console.log(`  bulk seated on: ${planByType(bulkSlots)}`);
+    }
+
+    summary.push({
+      order: order.name.slice(0, 34),
+      wagons: result.plan.length,
+      'bulk SF45-4': bulkFitted ? 'SELECTED' : 'NOT SELECTED',
+      deferred: result.deferred.map((d) => d.reference).join(',') || '-',
+      reason: bulkDeferred ? bulkDeferred.reason.slice(0, 60) : '-',
+    });
+  }
+
+  console.log('\n\n================ SUMMARY ================');
+  console.table(summary);
+  await ds.destroy();
+}
+
+main().catch((e) => { console.error(e); process.exit(1); });

apps/edr-freight-api/scripts/run-wagon-gate-tests.ts

@@ -0,0 +1,362 @@
+/**
+ * Runs the REAL planner (planWagonsWithStock) against the WGT-* bookings and
+ * the REAL wagon stock standing in edr_dev. Read-only: it plans, asserts, and
+ * reports — it writes nothing.
+ *
+ *   npx ts-node -T scripts/run-wagon-gate-tests.ts
+ */
+import { DataSource } from 'typeorm';
+
+import { planWagonsWithStock } from '../src/modules/train-scheduling/wagon-plan-flex.util';
+import type { AllowedWagonTypeMap, WagonStock } from '../src/modules/train-scheduling/wagon-plan-flex.util';
+import { validateWagonCargoExclusivity } from '../src/modules/train-scheduling/utils/wagon-plan.util';
+import type { Booking } from '../src/modules/bookings/entities/booking.entity';
+import type { WagonType } from '../src/modules/wagon-types/entities/wagon-type.entity';
+
+const YARD = {
+  DCT: 'fc558b95-da28-4fc3-8348-311a290c34ae',
+  DIRE: 'f7b1686f-d43e-42aa-bc6a-d3d5849296c9',
+  KALITY: '61ae1e66-c229-4dcd-9851-b2b9424f3a95',
+};
+
+const ds = new DataSource({
+  type: 'postgres',
+  host: process.env.DB_HOST || '10.18.7.207',
+  port: Number(process.env.DB_PORT || 5432),
+  database: process.env.DB_NAME || 'edr_dev',
+  username: process.env.DB_USER || 'postgres',
+  password: process.env.DB_PASSWORD || 'dcba@1234',
+});
+
+type Check = { name: string; pass: boolean; detail: string };
+const results: Array<{ testCase: string; checks: Check[] }> = [];
+
+const check = (list: Check[], name: string, pass: boolean, detail: string) => {
+  list.push({ name, pass, detail });
+};
+
+/** Wagon types keyed by id, and the allowed-type map read from the join tables. */
+async function loadConfig(): Promise<{
+  allowed: AllowedWagonTypeMap;
+  byId: Map<string, WagonType>;
+  codes: Map<string, string>;
+}> {
+  const types: WagonType[] = await ds.query(
+    `SELECT id, code, name, capacity_tons AS "capacityTons",
+            length_meters AS "lengthMeters", tare_weight_tons AS "tareWeightTons",
+            supports_container AS "supportsContainer", is_active AS "isActive"
+       FROM freight.wagon_types WHERE is_active IS NOT FALSE`,
+  );
+  const byId = new Map(types.map((t) => [t.id, t]));
+  const codes = new Map(types.map((t) => [t.id, t.code]));
+
+  const cargoRows: Array<{ typeId: string; wagonTypeId: string }> = await ds.query(
+    `SELECT cargo_type_id AS "typeId", wagon_type_id AS "wagonTypeId"
+       FROM freight.cargo_type_wagon_types`,
+  );
+  const containerRows: Array<{ typeId: string; wagonTypeId: string }> = await ds.query(
+    `SELECT container_type_id AS "typeId", wagon_type_id AS "wagonTypeId"
+       FROM freight.container_type_wagon_types`,
+  );
+  const collect = (rows: Array<{ typeId: string; wagonTypeId: string }>) => {
+    const map = new Map<string, WagonType[]>();
+    for (const row of rows) {
+      const wt = byId.get(row.wagonTypeId);
+      if (!wt) continue;
+      map.set(row.typeId, [...(map.get(row.typeId) ?? []), wt]);
+    }
+    return map;
+  };
+  return {
+    allowed: {
+      byCargoTypeId: collect(cargoRows),
+      byContainerTypeId: collect(containerRows),
+    },
+    byId,
+    codes,
+  };
+}
+
+/** The WGT-* bookings, hydrated the way the planner expects them. */
+async function loadBookings(refs: string[]): Promise<Booking[]> {
+  const rows = await ds.query(
+    `SELECT b.id, b.reference, b.freight_type AS "freightType",
+            b.cargo_total_weight_vgm AS "cargoTotalWeightVgm",
+            b.bulk_total_weight_tons AS "bulkTotalWeightTons",
+            b.cargo_type_id AS "cargoTypeId",
+            b.origin_yard_id AS "originYardId",
+            b.destination_yard_id AS "destinationYardId",
+            b.is_government AS "isGovernment", b.priority_score AS "priorityScore",
+            b.created_at AS "createdAt"
+       FROM freight.bookings b
+      WHERE b.reference = ANY($1) AND b.deleted_at IS NULL`,
+    [refs],
+  );
+  const cargoTypes = await ds.query(
+    `SELECT ct.id, ct.cargo_type_name AS "cargoTypeName", ct.code,
+            ct.unit_of_measure AS "unitOfMeasure",
+            ct.tons_per_wagon_map AS "tonsPerWagonMap",
+            ct.items_per_wagon_map AS "itemsPerWagonMap"
+       FROM freight.cargo_types ct`,
+  );
+  const cargoById = new Map(cargoTypes.map((c: any) => [c.id, c]));
+  const { allowed } = await loadConfig();
+
+  const lines = await ds.query(
+    `SELECT bc.id, bc.booking_id AS "bookingId", bc.container_type_id AS "containerTypeId",
+            bc.quantity, bc.vgm_per_unit_tons AS "vgmPerUnitTons",
+            bc.wagons_required AS "wagonsRequired", bc.container_number AS "containerNumber",
+            ct.code, ct.size_ft AS "sizeFt"
+       FROM freight.booking_container bc
+       JOIN freight.container_types ct ON ct.id = bc.container_type_id
+      WHERE bc.booking_id = ANY($1) AND bc.deleted_at IS NULL`,
+    [rows.map((r: any) => r.id)],
+  );
+
+  return rows.map((r: any) => {
+    const cargoType = r.cargoTypeId ? cargoById.get(r.cargoTypeId) : null;
+    return {
+      ...r,
+      cargoType: cargoType
+        ? { ...cargoType, wagonTypes: allowed.byCargoTypeId.get(r.cargoTypeId) ?? [] }
+        : null,
+      bookingContainers: lines
+        .filter((l: any) => l.bookingId === r.id)
+        .map((l: any) => ({
+          ...l,
+          containerType: { id: l.containerTypeId, code: l.code, sizeFt: l.sizeFt },
+          units: [],
+        })),
+    } as unknown as Booking;
+  });
+}
+
+/** Real AVAILABLE wagons standing at a yard, by type. */
+async function stockAtYard(yardId: string, codes: Map<string, string>): Promise<WagonStock> {
+  const rows = await ds.query(
+    `SELECT wagon_type_id AS "wagonTypeId", count(*)::int AS n
+       FROM freight.wagons
+      WHERE current_yard_id = $1 AND deleted_at IS NULL
+        AND status = 'AVAILABLE' AND train_id IS NULL
+        AND current_train_schedule_id IS NULL
+      GROUP BY wagon_type_id`,
+    [yardId],
+  );
+  return {
+    mode: 'YARD',
+    remainingByTypeId: new Map(rows.map((r: any) => [r.wagonTypeId, r.n])),
+    codesByTypeId: codes,
+  };
+}
+
+/** Per-type slot counts of a plan, as a readable "10x PW2, 17x NW5". */
+const planByType = (plan: any[]): string => {
+  const counts = new Map<string, number>();
+  for (const slot of plan) {
+    counts.set(slot.wagonTypeCode, (counts.get(slot.wagonTypeCode) ?? 0) + 1);
+  }
+  return [...counts.entries()].map(([code, n]) => `${n}x ${code}`).join(', ') || 'none';
+};
+
+async function main() {
+  await ds.initialize();
+  const { allowed, codes } = await loadConfig();
+  const dctStock = await stockAtYard(YARD.DCT, codes);
+
+  console.log('\n=== REAL FLEET AT DORALEH_FREEZONE (AVAILABLE, unpinned) ===');
+  console.table(
+    [...dctStock.remainingByTypeId.entries()].map(([id, n]) => ({
+      wagonType: codes.get(id),
+      available: n,
+    })),
+  );
+
+  // ---------------------------------------------------------------- CASE A
+  {
+    const checks: Check[] = [];
+    const bookings = await loadBookings(['WGT-A1', 'WGT-A2', 'WGT-A3']);
+    // Constrain the fleet to make the contest real: 20 NW5 + 10 PW2.
+    const stock: WagonStock = {
+      mode: 'TRAIN',
+      remainingByTypeId: new Map([
+        ['8f717b09-eec1-46ad-be3d-2dc0a56e55e7', 20], // NW5
+        ['8eec3a7d-8482-4397-96b6-59a028210722', 10], // PW2
+      ]),
+      codesByTypeId: codes,
+    };
+    const result = planWagonsWithStock({ bookings, allowed, stock });
+    const bulkSlots = result.plan.filter((s) => s.slotLoadType === 'BULK');
+    const pw2Bulk = bulkSlots.filter((s) => s.wagonTypeCode === 'PW2').length;
+    const nw5Bulk = bulkSlots.filter((s) => s.wagonTypeCode === 'NW5').length;
+
+    check(checks, 'bulk fills bulk-only PW2 first', pw2Bulk === 10,
+      `${pw2Bulk}/10 PW2 used by bulk`);
+    check(checks, 'PW2 bulk wagons respect the 20T cargo cap',
+      bulkSlots.filter((s) => s.wagonTypeCode === 'PW2')
+        .every((s) => s.assignedWeightTons <= 20),
+      `max PW2 load ${Math.max(0, ...bulkSlots.filter((s) => s.wagonTypeCode === 'PW2').map((s) => s.assignedWeightTons))}T (cap 20T)`);
+    check(checks, 'NW5 bulk wagons respect the 30T cargo cap',
+      bulkSlots.filter((s) => s.wagonTypeCode === 'NW5')
+        .every((s) => s.assignedWeightTons <= 30),
+      `max NW5 bulk load ${Math.max(0, ...bulkSlots.filter((s) => s.wagonTypeCode === 'NW5').map((s) => s.assignedWeightTons))}T (cap 30T)`);
+    check(checks, 'no wagon mixes bulk with other cargo',
+      validateWagonCargoExclusivity(result.plan).length === 0,
+      validateWagonCargoExclusivity(result.plan).join('; ') || 'clean');
+    check(checks, 'plan is honest about who fits',
+      result.fitting.length + result.deferred.length === 3,
+      `fitting=[${result.fitting.map((b) => b.reference)}] deferred=[${result.deferred.map((d) => d.reference)}]`);
+
+    results.push({ testCase: 'A — bulk vs container contest for NW5 (20 NW5 + 10 PW2)', checks });
+    console.log('\n=== CASE A: 695T Perishable + 12x40ft + 16x20ft, stock 20 NW5 / 10 PW2 ===');
+    console.log(`plan: ${result.plan.length} wagons — ${planByType(result.plan)}`);
+    console.log(`  bulk: ${pw2Bulk}x PW2 + ${nw5Bulk}x NW5`);
+    console.log(`fitting: ${result.fitting.map((b) => b.reference).join(', ') || 'none'}`);
+    for (const d of result.deferred) console.log(`deferred: ${d.reference} — ${d.reason}`);
+  }
+
+  // ---------------------------------------------------------------- CASE B
+  {
+    const checks: Check[] = [];
+    const bookings = await loadBookings(['WGT-B1', 'WGT-B2']);
+    const stops = [YARD.DCT, YARD.DIRE, YARD.KALITY];
+    const legs = new Map(
+      bookings.map((b: any) => [
+        b.id,
+        { from: stops.indexOf(b.originYardId), to: stops.indexOf(b.destinationYardId) },
+      ]),
+    );
+    const stock: WagonStock = {
+      mode: 'TRAIN',
+      remainingByTypeId: new Map([
+        ['8f717b09-eec1-46ad-be3d-2dc0a56e55e7', 3], // NW5 — only 3, forces reuse
+        ['8eec3a7d-8482-4397-96b6-59a028210722', 0],
+      ]),
+      codesByTypeId: codes,
+    };
+    const result = planWagonsWithStock({
+      bookings, allowed, stock, legs, edgeCount: 2, stops,
+    });
+    check(checks, 'both disjoint-leg bookings fit on 3 wagons',
+      result.fitting.length === 2 && result.plan.length <= 3,
+      `fitting=${result.fitting.length}/2, wagons=${result.plan.length}`);
+    const legIssues = validateWagonCargoExclusivity(result.plan, legs, 2);
+    check(checks, 'no wagon carries bulk + container on the SAME leg',
+      legIssues.length === 0, legIssues.join('; ') || 'clean');
+    // …and the leg-blind reading WOULD flag it, proving the reuse is real.
+    check(checks, 'the same wagon does carry both kinds across DIFFERENT legs',
+      validateWagonCargoExclusivity(result.plan).length > 0,
+      'leg-blind check sees bulk+container on one wagon (legal: disjoint legs)');
+    const reused = result.plan.filter((s) => s.allocations.length > 1);
+    check(checks, 'leg-disjoint reuse actually happens',
+      reused.length > 0,
+      `${reused.length} wagon(s) carry both bookings on different legs`);
+
+    results.push({ testCase: 'B — leg-disjoint reuse (container leg 1, bulk leg 2), only 3 NW5', checks });
+    console.log('\n=== CASE B: 6x20ft DCT->Dire + 120T bulk Dire->Kality, only 3 NW5 ===');
+    console.log(`plan: ${result.plan.length} wagons — ${planByType(result.plan)}`);
+    for (const slot of result.plan) {
+      console.log(`  wagon #${slot.sequenceNo} (${slot.wagonTypeCode}): ${slot.allocations
+        .map((a) => `${a.bookingReference}/${a.loadType} ${a.allocatedWeightTons}T`).join(' + ')}`);
+    }
+    for (const d of result.deferred) console.log(`deferred: ${d.reference} — ${d.reason}`);
+  }
+
+  // ---------------------------------------------------------------- CASE C
+  {
+    const checks: Check[] = [];
+    const bookings = await loadBookings(['WGT-C1']);
+    const stock: WagonStock = {
+      mode: 'TRAIN',
+      remainingByTypeId: new Map([
+        ['8f717b09-eec1-46ad-be3d-2dc0a56e55e7', 20], // NW5 (40T cap for steel)
+        ['8eec3a7d-8482-4397-96b6-59a028210722', 20], // PW2 (10T cap for steel!)
+      ]),
+      codesByTypeId: codes,
+    };
+    const result = planWagonsWithStock({ bookings, allowed, stock });
+    const nw5 = result.plan.filter((s) => s.wagonTypeCode === 'NW5').length;
+    const pw2 = result.plan.filter((s) => s.wagonTypeCode === 'PW2').length;
+    check(checks, 'inverted caps: uses the 40T NW5, not the 10T PW2',
+      nw5 === 10 && pw2 === 0,
+      `${nw5}x NW5 (40T cap) + ${pw2}x PW2 (10T cap) for 400T`);
+    check(checks, 'wagon count matches the cap math (400/40 = 10)',
+      result.plan.length === 10, `${result.plan.length} wagons`);
+    results.push({ testCase: 'C — cap inversion (Steel Billet: NW5 40T vs PW2 10T)', checks });
+    console.log('\n=== CASE C: 400T Steel Billet, caps NW5=40T PW2=10T, both in stock ===');
+    console.log(`plan: ${result.plan.length} wagons — ${planByType(result.plan)}`);
+  }
+
+  // ---------------------------------------------------------------- CASE D
+  {
+    const checks: Check[] = [];
+    const bookings = await loadBookings(['WGT-D1', 'WGT-D2']);
+    const stock = await stockAtYard(YARD.DCT, codes);
+    const result = planWagonsWithStock({ bookings, allowed, stock });
+    const d1 = result.plan.filter((s) =>
+      s.allocations.some((a) => a.bookingReference === 'WGT-D1'));
+    const d2 = result.plan.filter((s) =>
+      s.allocations.some((a) => a.bookingReference === 'WGT-D2'));
+    check(checks, 'Beans (PW2-only) is deferred — no PW2 free at DCT',
+      result.deferred.some((d) => d.reference === 'WGT-D1'),
+      result.deferred.find((d) => d.reference === 'WGT-D1')?.reason ?? `planned on ${planByType(d1)}`);
+    check(checks, 'Sand rides only its configured CW3/CW4',
+      d2.length > 0 && d2.every((s) => ['CW3', 'CW4'].includes(s.wagonTypeCode)),
+      `Sand on ${planByType(d2)}`);
+    results.push({ testCase: 'D — exclusive-type cargo against REAL DCT stock', checks });
+    console.log('\n=== CASE D: 200T Beans (PW2-only) + 300T Sand (CW3/CW4-only), REAL stock ===');
+    console.log(`plan: ${result.plan.length} wagons — ${planByType(result.plan)}`);
+    for (const d of result.deferred) console.log(`deferred: ${d.reference} — ${d.reason}`);
+  }
+
+  // ---------------------------------------------------------------- CASE E
+  {
+    const checks: Check[] = [];
+    const bookings = await loadBookings(['WGT-E1', 'WGT-E2']);
+    const stock: WagonStock = {
+      mode: 'TRAIN',
+      remainingByTypeId: new Map([
+        ['8f717b09-eec1-46ad-be3d-2dc0a56e55e7', 30],
+        ['8eec3a7d-8482-4397-96b6-59a028210722', 5],
+      ]),
+      codesByTypeId: codes,
+    };
+    const result = planWagonsWithStock({ bookings, allowed, stock });
+    check(checks, '3000T booking is deferred, not silently truncated',
+      result.deferred.some((d) => d.reference === 'WGT-E1'),
+      result.deferred.find((d) => d.reference === 'WGT-E1')?.reason ?? 'FITTED (unexpected)');
+    const e2 = result.plan.filter((s) =>
+      s.allocations.some((a) => a.bookingReference === 'WGT-E2'));
+    check(checks, 'the 45T booking never shares a wagon with another booking',
+      e2.every((s) => new Set(s.allocations.map((a) => a.bookingId)).size === 1),
+      `${e2.length} wagon(s), all single-booking`);
+    check(checks, 'exclusivity holds across the whole plan',
+      validateWagonCargoExclusivity(result.plan).length === 0,
+      validateWagonCargoExclusivity(result.plan).join('; ') || 'clean');
+    results.push({ testCase: 'E — overload one leg (3000T) + small bulk beside it', checks });
+    console.log('\n=== CASE E: 3000T + 45T Perishable, stock 30 NW5 / 5 PW2 ===');
+    console.log(`plan: ${result.plan.length} wagons — ${planByType(result.plan)}`);
+    console.log(`fitting: ${result.fitting.map((b) => b.reference).join(', ') || 'none'}`);
+    for (const d of result.deferred) console.log(`deferred: ${d.reference} — ${d.reason}`);
+  }
+
+  // ---------------------------------------------------------------- REPORT
+  console.log('\n\n================ TEST REPORT ================');
+  let passed = 0;
+  let failed = 0;
+  for (const group of results) {
+    console.log(`\n${group.testCase}`);
+    for (const c of group.checks) {
+      console.log(`  ${c.pass ? 'PASS' : 'FAIL'}  ${c.name}\n        ${c.detail}`);
+      c.pass ? (passed += 1) : (failed += 1);
+    }
+  }
+  console.log(`\n---------------------------------------------`);
+  console.log(`TOTAL: ${passed} passed, ${failed} failed`);
+  await ds.destroy();
+  process.exit(failed > 0 ? 1 : 0);
+}
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

apps/edr-freight-api/scripts/seed-s45-scenario.cjs

@@ -0,0 +1,96 @@
+/**
+ * Seeds the S-2026-00045 reported scenario into edr_dev (idempotent).
+ * References SF45-* ("Scenario Fortyfive"). Rows are kept as evidence.
+ *
+ *   SELECT * FROM freight.bookings WHERE reference LIKE 'SF45-%';
+ */
+const { Client } = require('pg');
+
+const YARD = {
+  DCT: 'fc558b95-da28-4fc3-8348-311a290c34ae',
+  DIRE: 'f7b1686f-d43e-42aa-bc6a-d3d5849296c9',
+  GMP: '61ae1e66-c229-4dcd-9851-b2b9424f3a95', // KALITY = GMP (Gelan)
+};
+const PERISHABLE = 'a5991d3a-d690-4b7e-98fd-ea3333aa16e7'; // NW5 30T / PW2 20T
+const FT40 = '349072e7-8a90-4c03-b682-08976abfd7e8';
+const COMPANY = '300d5510-e3a5-4858-bc28-6e3beda8ca80';
+
+const BOOKINGS = [
+  { ref: 'SF45-1', type: 'CONTAINER', from: 'DCT', to: 'DIRE', qty: 9,
+    note: 'S45: DCT->Dire 9x40ft' },
+  { ref: 'SF45-2', type: 'CONTAINER', from: 'DCT', to: 'DIRE', qty: 19,
+    note: 'S45: DCT->Dire 19x40ft' },
+  { ref: 'SF45-3', type: 'CONTAINER', from: 'DCT', to: 'DIRE', qty: 19,
+    note: 'S45: DCT->Dire 19x40ft (second)' },
+  { ref: 'SF45-4', type: 'BULK', from: 'DCT', to: 'GMP', tons: 695,
+    note: 'S45: DCT->GMP 695T Perishable - THE ONE NOT BEING SELECTED' },
+  { ref: 'SF45-5', type: 'CONTAINER', from: 'DIRE', to: 'GMP', qty: 42,
+    note: 'S45: Dire->GMP 42x40ft' },
+];
+
+async function main() {
+  const client = new Client({
+    host: process.env.DB_HOST || '10.18.7.207',
+    port: Number(process.env.DB_PORT || 5432),
+    database: process.env.DB_NAME || 'edr_dev',
+    user: process.env.DB_USER || 'postgres',
+    password: process.env.DB_PASSWORD || 'dcba@1234',
+  });
+  await client.connect();
+  const out = [];
+
+  for (const b of BOOKINGS) {
+    const isBulk = b.type === 'BULK';
+    const vgmPerUnit = 26;
+    const totalVgm = isBulk ? b.tons : b.qty * vgmPerUnit;
+
+    const existing = await client.query(
+      `SELECT id FROM freight.bookings WHERE reference = $1`, [b.ref]);
+    let id;
+    if (existing.rows.length) {
+      id = existing.rows[0].id;
+      await client.query(
+        `UPDATE freight.bookings
+            SET cargo_total_weight_vgm=$2, cargo_type_id=$3, origin_yard_id=$4,
+                destination_yard_id=$5, freight_type=$6, trade_direction='IMPORT',
+                status='CLEARANCE_READY', payment_status='PENDING',
+                scheduling_status='ELIGIBLE', train_schedule_id=NULL,
+                cargo_free_text=$7, updated_at=now()
+          WHERE id=$1`,
+        [id, totalVgm, isBulk ? PERISHABLE : null, YARD[b.from], YARD[b.to],
+         b.type, b.note]);
+    } else {
+      const res = await client.query(
+        `INSERT INTO freight.bookings (
+           reference, status, total_amount, payment_status, contract_type,
+           trade_direction, equipment_return, cargo_total_weight_vgm, is_hazardous,
+           payment_currency, version_number, priority_score, origin_yard_id,
+           destination_yard_id, cargo_type_id, cargo_free_text, freight_type,
+           scheduling_status, is_government, customs_clearing_enabled, is_reefer,
+           booking_type, is_split, company_id, created_at, updated_at
+         ) VALUES ($1,'CLEARANCE_READY',0,'PENDING','NEW','IMPORT','WITHOUT_RETURN',
+                   $2,false,'ETB',1,0,$3,$4,$5,$6,$7,'ELIGIBLE',false,false,false,
+                   'ONE_TIME',false,$8, now(), now())
+         RETURNING id`,
+        [b.ref, totalVgm, YARD[b.from], YARD[b.to],
+         isBulk ? PERISHABLE : null, b.note, b.type, COMPANY]);
+      id = res.rows[0].id;
+    }
+
+    await client.query(`DELETE FROM freight.booking_container WHERE booking_id=$1`, [id]);
+    if (!isBulk) {
+      await client.query(
+        `INSERT INTO freight.booking_container
+           (booking_id, container_type_id, quantity, vgm_per_unit_tons,
+            total_vgm_tons, wagons_required, container_size, created_at, updated_at)
+         VALUES ($1,$2,$3,$4,$5,$6,'40ft', now(), now())`,
+        [id, FT40, b.qty, vgmPerUnit, b.qty * vgmPerUnit, b.qty]);
+    }
+    out.push({ ref: b.ref, id, note: b.note });
+  }
+
+  console.table(out);
+  await client.end();
+}
+
+main().catch((e) => { console.error(e.message); process.exit(1); });

apps/edr-freight-api/scripts/seed-wagon-gate-testcases.cjs

@@ -0,0 +1,142 @@
+/**
+ * Seeds the wagon-allocation test bookings into edr_dev (idempotent) and
+ * prints their ids. Rows are kept — they are the evidence for the report.
+ *
+ * References are prefixed WGT- (Wagon Gate Test) so they are easy to find:
+ *   SELECT * FROM freight.bookings WHERE reference LIKE 'WGT-%';
+ */
+const { Client } = require('pg');
+
+const YARD = {
+  DORALEH_FREEZONE: 'fc558b95-da28-4fc3-8348-311a290c34ae',
+  DIRE_DAWA: 'f7b1686f-d43e-42aa-bc6a-d3d5849296c9',
+  KALITY: '61ae1e66-c229-4dcd-9851-b2b9424f3a95',
+  DMP: '7b658678-ce2b-41aa-8dc5-b38ba4a76e9b',
+};
+const CARGO = {
+  PERISHABLE: 'a5991d3a-d690-4b7e-98fd-ea3333aa16e7', // NW5 30T / PW2 20T
+  STEEL_BILLET: '8291ccc3-0dd9-4d78-aa44-284d028a19ce', // NW5 40T / PW2 10T (inverted)
+  BEANS: '9afd8eb3-975b-4ea7-a7db-04eb2c20a04d', // PW2 only, no cap
+  SAND: '8942884d-9991-42bb-87f7-a70930f8c43c', // CW3/CW4 only, no cap
+};
+const CONTAINER = {
+  '20FT': '77cf24ec-e74b-4bdb-b1cc-6f336379cc58',
+  '40FT': '349072e7-8a90-4c03-b682-08976abfd7e8',
+};
+const COMPANY = '300d5510-e3a5-4858-bc28-6e3beda8ca80';
+
+/** Test bookings: 4 corridors, bulk + container, contested and uncontested. */
+const BOOKINGS = [
+  // --- Case A: DORALEH_FREEZONE -> KALITY (full leg), bulk vs container contest
+  { ref: 'WGT-A1', dir: 'IMPORT', type: 'BULK', from: 'DORALEH_FREEZONE', to: 'KALITY',
+    cargo: 'PERISHABLE', tons: 695, note: 'A: 695T Perishable, contends with containers for NW5' },
+  { ref: 'WGT-A2', dir: 'IMPORT', type: 'CONTAINER', from: 'DORALEH_FREEZONE', to: 'KALITY',
+    containers: [{ type: '40FT', qty: 12, vgm: 26 }], note: 'A: 12x40ft, needs 12 container wagons' },
+  { ref: 'WGT-A3', dir: 'IMPORT', type: 'CONTAINER', from: 'DORALEH_FREEZONE', to: 'KALITY',
+    containers: [{ type: '20FT', qty: 16, vgm: 12 }], note: 'A: 16x20ft = 8 wagons (TEU paired)' },
+
+  // --- Case B: sub-corridor legs on the same 3-stop route (leg overlap)
+  { ref: 'WGT-B1', dir: 'IMPORT', type: 'CONTAINER', from: 'DORALEH_FREEZONE', to: 'DIRE_DAWA',
+    containers: [{ type: '20FT', qty: 6, vgm: 14 }], note: 'B: leg 1 only (DCT->Dire), 3 wagons' },
+  { ref: 'WGT-B2', dir: 'IMPORT', type: 'BULK', from: 'DIRE_DAWA', to: 'KALITY',
+    cargo: 'PERISHABLE', tons: 120, note: 'B: leg 2 only (Dire->Kality) - may reuse leg-1 wagons' },
+
+  // --- Case C: cap inversion - Steel Billet is CHEAPER on NW5 (40T) than PW2 (10T)
+  { ref: 'WGT-C1', dir: 'IMPORT', type: 'BULK', from: 'DORALEH_FREEZONE', to: 'KALITY',
+    cargo: 'STEEL_BILLET', tons: 400, note: 'C: inverted caps - must NOT blindly take PW2' },
+
+  // --- Case D: exclusive-type cargo (Beans=PW2 only, Sand=CW3/CW4 only)
+  { ref: 'WGT-D1', dir: 'IMPORT', type: 'BULK', from: 'DORALEH_FREEZONE', to: 'KALITY',
+    cargo: 'BEANS', tons: 200, note: 'D: PW2-only cargo, no alternative' },
+  { ref: 'WGT-D2', dir: 'IMPORT', type: 'BULK', from: 'DORALEH_FREEZONE', to: 'KALITY',
+    cargo: 'SAND', tons: 300, note: 'D: CW3/CW4-only cargo' },
+
+  // --- Case E: overload one leg (way beyond any train)
+  { ref: 'WGT-E1', dir: 'IMPORT', type: 'BULK', from: 'DORALEH_FREEZONE', to: 'KALITY',
+    cargo: 'PERISHABLE', tons: 3000, note: 'E: 3000T - must overflow the loco pull limit' },
+  { ref: 'WGT-E2', dir: 'IMPORT', type: 'BULK', from: 'DORALEH_FREEZONE', to: 'KALITY',
+    cargo: 'PERISHABLE', tons: 45, note: 'E: small bulk - must NOT share a wagon with A1' },
+];
+
+async function main() {
+  const client = new Client({
+    host: process.env.DB_HOST || '10.18.7.207',
+    port: Number(process.env.DB_PORT || 5432),
+    database: process.env.DB_NAME || 'edr_dev',
+    user: process.env.DB_USER || 'postgres',
+    password: process.env.DB_PASSWORD || 'dcba@1234',
+  });
+  await client.connect();
+
+  const out = [];
+  for (const b of BOOKINGS) {
+    const isBulk = b.type === 'BULK';
+    const totalVgm = isBulk
+      ? b.tons
+      : b.containers.reduce((s, l) => s + l.qty * l.vgm, 0);
+
+    const existing = await client.query(
+      `SELECT id FROM freight.bookings WHERE reference = $1`,
+      [b.ref],
+    );
+    let id;
+    if (existing.rows.length) {
+      id = existing.rows[0].id;
+      await client.query(
+        `UPDATE freight.bookings
+            SET cargo_total_weight_vgm = $2, cargo_type_id = $3,
+                origin_yard_id = $4, destination_yard_id = $5,
+                freight_type = $6, trade_direction = $7,
+                status = 'CLEARANCE_READY', payment_status = 'PENDING',
+                scheduling_status = 'ELIGIBLE', train_schedule_id = NULL,
+                cargo_free_text = $8, updated_at = now()
+          WHERE id = $1`,
+        [id, totalVgm, isBulk ? CARGO[b.cargo] : null,
+         YARD[b.from], YARD[b.to], b.type, b.dir, b.note],
+      );
+    } else {
+      const res = await client.query(
+        `INSERT INTO freight.bookings (
+           reference, status, total_amount, payment_status, contract_type,
+           trade_direction, equipment_return, cargo_total_weight_vgm,
+           is_hazardous, payment_currency, version_number, priority_score,
+           origin_yard_id, destination_yard_id, cargo_type_id, cargo_free_text,
+           freight_type, scheduling_status, is_government,
+           customs_clearing_enabled, is_reefer, booking_type, is_split,
+           company_id, created_at, updated_at
+         ) VALUES ($1,'CLEARANCE_READY',0,'PENDING','NEW',$2,'WITHOUT_RETURN',$3,
+                   false,'ETB',1,0,$4,$5,$6,$7,$8,'ELIGIBLE',false,
+                   false,false,'ONE_TIME',false,$9, now(), now())
+         RETURNING id`,
+        [b.ref, b.dir, totalVgm, YARD[b.from], YARD[b.to],
+         isBulk ? CARGO[b.cargo] : null, b.note, b.type, COMPANY],
+      );
+      id = res.rows[0].id;
+    }
+
+    // Container lines
+    await client.query(`DELETE FROM freight.booking_container WHERE booking_id = $1`, [id]);
+    if (!isBulk) {
+      for (const line of b.containers) {
+        await client.query(
+          `INSERT INTO freight.booking_container
+             (booking_id, container_type_id, quantity, vgm_per_unit_tons,
+              total_vgm_tons, wagons_required, container_size, created_at, updated_at)
+           VALUES ($1,$2,$3,$4,$5,$6,$7, now(), now())`,
+          [id, CONTAINER[line.type], line.qty, line.vgm, line.qty * line.vgm,
+           line.type === '40FT' ? line.qty : Math.ceil(line.qty / 2),
+           line.type === '40FT' ? '40ft' : '20ft'],
+        );
+      }
+    }
+    out.push({ ref: b.ref, id, note: b.note });
+  }
+
+  console.table(out);
+  await client.end();
+}
+
+main().catch((err) => {
+  console.error(err.message);
+  process.exit(1);
+});

apps/edr-freight-api/src/app.module.ts

@@ -51,6 +51,7 @@ import { SupportChatModule } from "./modules/support-chat/support-chat.module";
 import { FileUploadSettingsModule } from "./modules/file-upload-settings/file-upload-settings.module";
 import { DropdownSettingsModule } from "./modules/dropdown-settings/dropdown-settings.module";
 import { ExchangeSettingsModule } from "./modules/exchange-settings/exchange-settings.module";
+import { OperationsReportingModule } from "./modules/operations-reporting/operations-reporting.module";
 import { PaymentSettingsModule } from "./modules/payment-settings/payment-settings.module";
 import { StampSettingsModule } from "./modules/stamp-settings/stamp-settings.module";
 import { LogoSettingsModule } from "./modules/logo-settings/logo-settings.module";
@@ -101,6 +102,7 @@ import { RoutesModule } from "./modules/routes/routes.module";
 import { WarehousesModule } from "./modules/warehouses/warehouses.module";
 import { OverviewModule } from "./modules/overview/overview.module";
 import { ReportsModule } from "./modules/reports/reports.module";
+import { ExportsModule } from "./modules/exports/exports.module";
 import { UserTradeAccessModule } from "./modules/user-trade-access/user-trade-access.module";
 import { VehiclesModule } from "./modules/vehicles/vehicles.module";
 import { DriversModule } from "./modules/drivers/drivers.module";
@@ -219,6 +221,7 @@ if (!process.env.APPLICATION_NAME) {
     FileUploadSettingsModule,
     DropdownSettingsModule,
     ExchangeSettingsModule,
+    OperationsReportingModule,
     PaymentSettingsModule,
     StampSettingsModule,
     LogoSettingsModule,
@@ -239,6 +242,7 @@ if (!process.env.APPLICATION_NAME) {
     WarehousesModule,
     OverviewModule,
     ReportsModule,
+    ExportsModule,
     UserTradeAccessModule,
     VehiclesModule,
     DriversModule,

apps/edr-freight-api/src/common/booking-guards.ts

@@ -1,5 +1,5 @@
 import { applyDecorators, UseGuards } from '@nestjs/common';
-import { JwtGuard } from '@tria-plc/api-common/modules/auth/services/jwt.guard';
+import { FreightJwtGuard } from './freight-jwt.guard';
 
 import {
   FreightPermissionGuard,
@@ -11,7 +11,7 @@ import { FREIGHT_PERMS } from '../seed/freight-permissions.registry';
 export const BookingStaff = (permission: string | string[]) =>
   applyDecorators(
     UseGuards(
-      JwtGuard,
+      FreightJwtGuard,
       FreightPermissionGuard(
         Array.isArray(permission) ? permission : [permission],
       ),
@@ -26,11 +26,11 @@ export const BookingStaff = (permission: string | string[]) =>
  * BookingStaff(<view key>) or MixedAudience(); kept for routes not yet swept.
  */
 export const StaffReference = () =>
-  applyDecorators(UseGuards(JwtGuard, FreightPermissionGuard([])));
+  applyDecorators(UseGuards(FreightJwtGuard, FreightPermissionGuard([])));
 
 /** Portal routes: customer accounts only; ownership scoping stays in services. */
 export const PortalCustomer = () =>
-  applyDecorators(UseGuards(JwtGuard, PortalCustomerGuard));
+  applyDecorators(UseGuards(FreightJwtGuard, PortalCustomerGuard));
 
 /**
  * Routes both audiences call (sign, shared document reads, handover): staff
@@ -40,7 +40,7 @@ export const PortalCustomer = () =>
 export const MixedAudience = (permission: string | string[]) =>
   applyDecorators(
     UseGuards(
-      JwtGuard,
+      FreightJwtGuard,
       MixedAudienceGuard(
         Array.isArray(permission) ? permission : [permission],
       ),
@@ -75,7 +75,7 @@ export const TrainSchedulingView = () =>
   BookingStaff(FREIGHT_PERMS.trainScheduling.view);
 
 // Granular train-scheduling actions replace the retired coarse manage:
-// create a schedule, update (assign/consist/loading/finalize/dispatch/arrive…),
+// create a schedule, update (assign/consist/finalize/dispatch/arrive…),
 // cancel a schedule, reschedule (+ maintenance), and manage global rules.
 export const TrainSchedulingCreate = () =>
   BookingStaff(FREIGHT_PERMS.trainScheduling.create);
@@ -83,6 +83,36 @@ export const TrainSchedulingCreate = () =>
 export const TrainSchedulingUpdate = () =>
   BookingStaff(FREIGHT_PERMS.trainScheduling.update);
 
+/**
+ * Confirm a booking's cargo loaded/unloaded at a yard — carved out of the
+ * coarse `update` so it can be granted independently of general schedule
+ * editing. Same two keys gate import, export, and intercity movements alike:
+ * the generic per-booking route and the intercity-specific one both use them.
+ */
+export const TrainSchedulingLoad = () =>
+  BookingStaff(FREIGHT_PERMS.trainScheduling.load);
+
+export const TrainSchedulingUnload = () =>
+  BookingStaff(FREIGHT_PERMS.trainScheduling.unload);
+
+/**
+ * Per-station loading/unloading time windows — the four buttons are four
+ * permissions so start and end can be granted to different people. The same
+ * endpoint that records a click also edits it (explicit `at`), so each
+ * permission covers editing its own timestamp too.
+ */
+export const TrainSchedulingLoadingStart = () =>
+  BookingStaff(FREIGHT_PERMS.trainScheduling.loadingStart);
+
+export const TrainSchedulingLoadingEnd = () =>
+  BookingStaff(FREIGHT_PERMS.trainScheduling.loadingEnd);
+
+export const TrainSchedulingUnloadingStart = () =>
+  BookingStaff(FREIGHT_PERMS.trainScheduling.unloadingStart);
+
+export const TrainSchedulingUnloadingEnd = () =>
+  BookingStaff(FREIGHT_PERMS.trainScheduling.unloadingEnd);
+
 export const TrainSchedulingCancel = () =>
   BookingStaff(FREIGHT_PERMS.trainScheduling.cancel);
 

apps/edr-freight-api/src/common/dto/id-list.transform.spec.ts

@@ -0,0 +1,57 @@
+import { plainToInstance } from 'class-transformer';
+import { validateSync } from 'class-validator';
+
+import { FilterBookingDto } from '../../modules/bookings/dto/filter-booking.dto';
+import { ListTrainSchedulesQueryDto } from '../../modules/train-scheduling/dto/list-train-schedules-query.dto';
+
+/**
+ * The route filters carry one id, `a,b`, or a repeated param, and the
+ * repositories then branch on `?.length` before emitting `IN (:...ids)`.
+ * Two things have to hold or that breaks at runtime, not compile time:
+ * the value must always arrive as an array (a bare string would make
+ * `.length` count characters), and an absent/blank param must arrive as
+ * `undefined`, never `[]` — TypeORM turns `[]` into the syntax error `IN ()`.
+ */
+// Real-shaped v4s: the variant nibble must be 8/9/a/b, so `1111…` is NOT a
+// valid UUID and would fail `@IsUUID` for reasons that have nothing to do
+// with the list transform under test.
+const A = '0a5d4b1e-1b2c-4d3e-8f90-1234567890ab';
+const B = '7c9e6679-7425-40de-944b-e07fc1f90ae7';
+
+const parse = <T>(cls: new () => T, query: Record<string, unknown>): T =>
+  plainToInstance(cls, query);
+
+describe('route id-list query params', () => {
+  it('accepts a single id, still as an array', () => {
+    const dto = parse(FilterBookingDto, { originYardId: A });
+    expect(dto.originYardId).toEqual([A]);
+    expect(validateSync(dto)).toHaveLength(0);
+  });
+
+  it('splits a comma-separated list', () => {
+    const dto = parse(FilterBookingDto, { originYardId: `${A}, ${B}` });
+    expect(dto.originYardId).toEqual([A, B]);
+    expect(validateSync(dto)).toHaveLength(0);
+  });
+
+  it('accepts the repeated-param form', () => {
+    const dto = parse(ListTrainSchedulesQueryDto, { destinationStationId: [A, B] });
+    expect(dto.destinationStationId).toEqual([A, B]);
+    expect(validateSync(dto)).toHaveLength(0);
+  });
+
+  it.each([undefined, '', ','])('yields undefined, never [], for %p', (raw) => {
+    expect(parse(FilterBookingDto, { originYardId: raw }).originYardId).toBeUndefined();
+  });
+
+  it('leaves the two ends independent — one side set, the other absent', () => {
+    const dto = parse(FilterBookingDto, { originYardId: A });
+    expect(dto.originYardId).toEqual([A]);
+    expect(dto.destinationYardId).toBeUndefined();
+  });
+
+  it('still rejects a non-uuid inside the list', () => {
+    const dto = parse(FilterBookingDto, { originYardId: `${A},not-a-uuid` });
+    expect(validateSync(dto)).not.toHaveLength(0);
+  });
+});

apps/edr-freight-api/src/common/dto/id-list.transform.ts

@@ -0,0 +1,29 @@
+import { Transform } from 'class-transformer';
+
+/**
+ * A query param that carries one id, a comma-separated list (`a,b,c`), or the
+ * same key repeated — and always lands on the DTO as a `string[]`.
+ *
+ * Two details matter:
+ *
+ * - It yields `undefined`, never `[]`, when nothing usable is left. `@IsOptional`
+ *   then short-circuits, and — more importantly — a repository that does
+ *   `if (ids?.length)` can never be handed an empty array, which TypeORM turns
+ *   into the syntax error `IN ()`.
+ * - It is backwards compatible with the single-value form these params used to
+ *   take, so existing deep links and saved views keep working unchanged.
+ *
+ * Pair it with `@IsUUID(undefined, { each: true })` (or the relevant `each`
+ * validator) — this only reshapes the value, it does not validate it.
+ */
+export const IdListParam = () =>
+  Transform(({ value }: { value: unknown }) => {
+    const raw = Array.isArray(value) ? value : [value];
+    const ids = raw
+      .flatMap((entry) =>
+        entry === undefined || entry === null ? [] : String(entry).split(','),
+      )
+      .map((s) => s.trim())
+      .filter(Boolean);
+    return ids.length ? ids : undefined;
+  });

apps/edr-freight-api/src/common/dto/page-size-cap.spec.ts

@@ -0,0 +1,32 @@
+import { plainToInstance } from 'class-transformer';
+import { validateSync } from 'class-validator';
+
+import { PaginationQueryDto } from './pagination-query.dto';
+import { ListWagonsQueryDto } from '../../modules/wagons/dto/list-wagons-query.dto';
+import { normalizePagination } from '../utils/pagination.util';
+
+/**
+ * The page-size ceiling is stated in three places that must agree: `@Max` on
+ * PaginationQueryDto, the same `@Max` repeated on ListWagonsQueryDto (which
+ * doesn't extend it), and `MAX_PAGE_SIZE` in pagination.util. A fourth copy
+ * lives outside this package — `MAX_PAGE_SIZE` in @edr/ui-common's data-table
+ * footer, which is what actually asks for the number. Drift between any of
+ * them shows up as a 400 on the largest rows-per-page option, so pin them.
+ */
+const errorsFor = (cls: any, pageSize: unknown) =>
+  validateSync(plainToInstance(cls, { pageSize }), { whitelist: false });
+
+describe('page size ceiling', () => {
+  it.each([PaginationQueryDto, ListWagonsQueryDto])('accepts 500 on %p', (cls) => {
+    expect(errorsFor(cls, 500)).toHaveLength(0);
+  });
+
+  it.each([PaginationQueryDto, ListWagonsQueryDto])('rejects 501 on %p', (cls) => {
+    expect(errorsFor(cls, 501)).not.toHaveLength(0);
+  });
+
+  it('does not truncate 500 in the service-side clamp', () => {
+    expect(normalizePagination({ page: 1, pageSize: 500 }).take).toBe(500);
+    expect(normalizePagination({ page: 1, pageSize: 501 }).take).toBe(500);
+  });
+});

apps/edr-freight-api/src/common/dto/pagination-query.dto.ts

@@ -19,12 +19,18 @@ export class PaginationQueryDto {
   @Min(1)
   page?: number;
 
-  @ApiPropertyOptional({ default: 20, minimum: 1, maximum: 100 })
+  /**
+   * Ceiling is 500, matching `MAX_PAGE_SIZE` in `common/utils/pagination.util.ts`
+   * and the backoffice table footer's largest option. The three have to agree:
+   * a lower value here turns the footer's top preset into a 400, a higher one
+   * lets a request through that the util then silently truncates.
+   */
+  @ApiPropertyOptional({ default: 20, minimum: 1, maximum: 500 })
   @IsOptional()
   @Transform(({ value }) => parseInt(String(value), 10) || 20)
   @IsInt()
   @Min(1)
-  @Max(100)
+  @Max(500)
   pageSize?: number;
 
   @ApiPropertyOptional({

apps/edr-freight-api/src/common/freight-jwt.guard.ts

@@ -0,0 +1,101 @@
+import { CanActivate, ExecutionContext, Injectable } from '@nestjs/common';
+import { Reflector } from '@nestjs/core';
+import { InjectDataSource } from '@nestjs/typeorm';
+import { JwtGuard as IamJwtGuard } from '@tria-plc/api-common/modules/auth/services/jwt.guard';
+import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
+import { DataSource } from 'typeorm';
+
+/** One position as the login snapshot stores it (`iam.sessions.userInfo`). */
+type SnapshotPosition = { id?: string; [key: string]: unknown };
+
+type SessionUserInfo = {
+  employee?: { id?: string; positions?: SnapshotPosition[] }[];
+};
+
+/**
+ * Like the IAM JwtGuard, but keeps the caller's SECONDARY positions.
+ *
+ * IAM models an employee as holding many positions, and the login snapshot in
+ * `iam.sessions.userInfo` carries all of them. `JwtGuard.parseToken` then
+ * collapses that to a single `employee.position` — whichever the request
+ * headers select, else `positions[0]` — and drops the rest. Non-delegate
+ * secondary positions vanish entirely, so staff holding two posts resolve to
+ * only one post's permissions and every check on the other one rejects them.
+ *
+ * This re-attaches the full list as `employee.positions`. `employee.position`
+ * is left exactly as the parent set it, so everything reading the single
+ * position today (audit log, delegation deadline) is unaffected; only the
+ * permission utils, which prefer the array, see the difference.
+ */
+@Injectable()
+export class FreightJwtGuard extends IamJwtGuard implements CanActivate {
+  // ponytail: unbounded-until-TTL map, cleared wholesale when it gets big.
+  // Sessions are few and the value is small; swap for an LRU if that changes.
+  private static readonly CACHE_TTL_MS = 30_000;
+  private static readonly CACHE_MAX_ENTRIES = 5_000;
+  private readonly cache = new Map<
+    string,
+    { positions: SnapshotPosition[]; expiresAt: number }
+  >();
+
+  constructor(
+    reflector: Reflector,
+    @InjectDataSource() private readonly ds: DataSource,
+  ) {
+    super(reflector, ds);
+  }
+
+  async canActivate(context: ExecutionContext): Promise<boolean> {
+    if (!(await super.canActivate(context))) return false;
+
+    const user = context.switchToHttp().getRequest().user as
+      | TCurrentUser
+      | undefined;
+    const employee = user?.employee;
+    if (!employee || !user?.sessionId) return true;
+
+    const positions = await this.positionsForSession(
+      user.sessionId,
+      employee.id,
+    );
+    // Never blank out what the parent resolved: an unreadable session or a
+    // snapshot without positions must degrade to the single-position
+    // behaviour, not to no positions at all.
+    if (positions.length) {
+      (employee as { positions?: SnapshotPosition[] }).positions = positions;
+    }
+    return true;
+  }
+
+  /** Every position the login snapshot holds for this employee. */
+  private async positionsForSession(
+    sessionId: string,
+    employeeId: string | undefined,
+  ): Promise<SnapshotPosition[]> {
+    const now = Date.now();
+    const hit = this.cache.get(sessionId);
+    if (hit && hit.expiresAt > now) return hit.positions;
+
+    let positions: SnapshotPosition[] = [];
+    try {
+      const rows: { userInfo: SessionUserInfo | null }[] = await this.ds.query(
+        `SELECT "userInfo" FROM iam.sessions WHERE id = $1`,
+        [sessionId],
+      );
+      const employees = rows[0]?.userInfo?.employee ?? [];
+      const match =
+        employees.find((e) => e?.id && e.id === employeeId) ?? employees[0];
+      positions = match?.positions ?? [];
+    } catch {
+      return []; // iam unreachable — caller keeps the parent's single position
+    }
+
+    if (this.cache.size >= FreightJwtGuard.CACHE_MAX_ENTRIES)
+      this.cache.clear();
+    this.cache.set(sessionId, {
+      positions,
+      expiresAt: now + FreightJwtGuard.CACHE_TTL_MS,
+    });
+    return positions;
+  }
+}

apps/edr-freight-api/src/common/freight-permission.util.spec.ts

@@ -2,6 +2,7 @@ import {
   assertCanApproveContractStep,
   canEditContractStep,
   collectPermissionKeys,
+  collectPositionTypeKeys,
   hasFreightPermission,
   setPositionTypePermissionResolver,
 } from './freight-permission.util';
@@ -121,3 +122,66 @@ describe('collectPermissionKeys — position-type grants', () => {
     expect(hasFreightPermission(direct, CLEARANCE)).toBe(true);
   });
 });
+
+/**
+ * IAM lets an employee hold several positions, but the vendored `JwtGuard`
+ * collapses `employee.positions[]` down to a single `employee.position` and
+ * drops the rest — so staff on two posts resolved to one post's permissions
+ * and every check on the other rejected them. `FreightJwtGuard` restores the
+ * full list as `employee.positions`; these cover the union that depends on it.
+ */
+describe('multiple positions', () => {
+  // Shaped like the real two-post employee: GL chief AND GL director.
+  const twoPost = {
+    employee: {
+      // What the vendored guard leaves behind — one of the two, arbitrarily.
+      position: {
+        positionType: { key: 'djibouti-gl-chief' },
+        permissions: [{ key: FREIGHT_PERMS.contracts.view }],
+      },
+      // What FreightJwtGuard puts back.
+      positions: [
+        {
+          positionType: { key: 'djibouti-gl-chief' },
+          permissions: [{ key: FREIGHT_PERMS.contracts.view }],
+        },
+        {
+          positionType: { key: 'djibouti-gl-director' },
+          permissions: [{ key: FREIGHT_PERMS.bookings.view }],
+        },
+      ],
+    },
+  };
+
+  it('unions permissions across every position', () => {
+    const keys = collectPermissionKeys(twoPost);
+    expect(keys).toContain(FREIGHT_PERMS.contracts.view);
+    expect(keys).toContain(FREIGHT_PERMS.bookings.view);
+  });
+
+  it('grants the secondary position’s permission, not just the first', () => {
+    expect(hasFreightPermission(twoPost, FREIGHT_PERMS.bookings.view)).toBe(true);
+  });
+
+  it('answers to both position types', () => {
+    expect(collectPositionTypeKeys(twoPost)).toEqual(
+      expect.arrayContaining(['djibouti-gl-chief', 'djibouti-gl-director']),
+    );
+  });
+
+  it('does not double-count the position the guard also left singular', () => {
+    const keys = collectPermissionKeys(twoPost);
+    expect(keys.filter((k) => k === FREIGHT_PERMS.contracts.view)).toHaveLength(1);
+  });
+
+  it('still resolves the single position when the array is absent', () => {
+    // A request that skipped FreightJwtGuard must degrade to the old behaviour,
+    // not to no permissions at all.
+    const onePost = {
+      employee: {
+        position: { permissions: [{ key: FREIGHT_PERMS.contracts.view }] },
+      },
+    };
+    expect(hasFreightPermission(onePost, FREIGHT_PERMS.contracts.view)).toBe(true);
+  });
+});

apps/edr-freight-api/src/common/freight-permission.util.ts

@@ -17,6 +17,15 @@ type MeLikeUser = {
           permissions?: PermissionLike[];
           positionType?: PositionTypeLike | null;
         };
+        /**
+         * Every position the employee holds, restored by `FreightJwtGuard`
+         * from the login snapshot. The IAM guard only ever sets the singular
+         * `position` above; without this, a second post's grants are invisible.
+         */
+        positions?: {
+          permissions?: PermissionLike[];
+          positionType?: PositionTypeLike | null;
+        }[];
         delegatedPositions?: { permissions?: PermissionLike[] }[];
       }
     | {
@@ -98,10 +107,15 @@ export function collectPermissionKeys(user: MeLikeUser | null | undefined): stri
     return [...keys];
   }
 
-  for (const p of employee.position?.permissions ?? []) {
-    if (p.key) keys.add(p.key);
+  // `position` is whichever single post the IAM guard selected; `positions` is
+  // the full set FreightJwtGuard restores. Walk both — the array is absent on
+  // a session the guard could not re-read, and the two overlap harmlessly.
+  for (const pos of [employee.position, ...(employee.positions ?? [])]) {
+    for (const p of pos?.permissions ?? []) {
+      if (p.key) keys.add(p.key);
+    }
+    addTypePermissions(pos?.positionType);
   }
-  addTypePermissions(employee.position?.positionType);
   for (const delegated of employee.delegatedPositions ?? []) {
     for (const p of delegated.permissions ?? []) {
       if (p.key) keys.add(p.key);
@@ -158,8 +172,10 @@ export function collectPositionTypeKeys(
     return [...keys];
   }
 
-  if (employee.position?.positionType?.key) {
-    keys.add(employee.position.positionType.key);
+  // Both shapes, same reason as collectPermissionKeys: an employee holding two
+  // posts answers to both their position types.
+  for (const pos of [employee.position, ...(employee.positions ?? [])]) {
+    if (pos?.positionType?.key) keys.add(pos.positionType.key);
   }
   return [...keys];
 }

apps/edr-freight-api/src/common/rule-engine-guards.ts

@@ -1,5 +1,5 @@
 import { applyDecorators, UseGuards } from '@nestjs/common';
-import { JwtGuard } from '@tria-plc/api-common/modules/auth/services/jwt.guard';
+import { FreightJwtGuard } from './freight-jwt.guard';
 
 import { FreightPermissionGuard } from './freight-permission.guard';
 import {
@@ -10,7 +10,7 @@ import {
 
 export const RuleEngineView = (slug: RuleEngineResourceSlug) =>
   applyDecorators(
-    UseGuards(JwtGuard, FreightPermissionGuard([FREIGHT_PERMS.ruleEngine.view(slug)])),
+    UseGuards(FreightJwtGuard, FreightPermissionGuard([FREIGHT_PERMS.ruleEngine.view(slug)])),
   );
 
 // Granular CRUD replaces the retired coarse RuleEngineManage. Each write
@@ -18,17 +18,17 @@ export const RuleEngineView = (slug: RuleEngineResourceSlug) =>
 // update on PATCH / reorder / move-order, delete on DELETE.
 export const RuleEngineCreate = (slug: RuleEngineResourceSlug) =>
   applyDecorators(
-    UseGuards(JwtGuard, FreightPermissionGuard([FREIGHT_PERMS.ruleEngine.create(slug)])),
+    UseGuards(FreightJwtGuard, FreightPermissionGuard([FREIGHT_PERMS.ruleEngine.create(slug)])),
   );
 
 export const RuleEngineUpdate = (slug: RuleEngineResourceSlug) =>
   applyDecorators(
-    UseGuards(JwtGuard, FreightPermissionGuard([FREIGHT_PERMS.ruleEngine.update(slug)])),
+    UseGuards(FreightJwtGuard, FreightPermissionGuard([FREIGHT_PERMS.ruleEngine.update(slug)])),
   );
 
 export const RuleEngineDelete = (slug: RuleEngineResourceSlug) =>
   applyDecorators(
-    UseGuards(JwtGuard, FreightPermissionGuard([FREIGHT_PERMS.ruleEngine.delete(slug)])),
+    UseGuards(FreightJwtGuard, FreightPermissionGuard([FREIGHT_PERMS.ruleEngine.delete(slug)])),
   );
 
 /**
@@ -38,5 +38,5 @@ export const RuleEngineDelete = (slug: RuleEngineResourceSlug) =>
  */
 export const RuleEngineApprove = (slug: RuleEngineApprovableSlug) =>
   applyDecorators(
-    UseGuards(JwtGuard, FreightPermissionGuard([FREIGHT_PERMS.ruleEngine.approve(slug)])),
+    UseGuards(FreightJwtGuard, FreightPermissionGuard([FREIGHT_PERMS.ruleEngine.approve(slug)])),
   );

apps/edr-freight-api/src/common/utils/pagination.util.ts

@@ -20,7 +20,12 @@ export interface NormalizedPage {
 }
 
 const DEFAULT_PAGE_SIZE = 20;
-const MAX_PAGE_SIZE = 100;
+/**
+ * Must stay in step with `@Max` on `PaginationQueryDto.pageSize` and with
+ * `MAX_PAGE_SIZE` in the backoffice's data-table footer — the DTO rejects,
+ * this clamps, and the footer is what actually asks for the number.
+ */
+const MAX_PAGE_SIZE = 500;
 
 /** Clamp raw query values into a safe page window (page ≥ 1, pageSize capped). */
 export function normalizePagination(

apps/edr-freight-api/src/config/eims.config.spec.ts

@@ -70,62 +70,3 @@ describe("eims.config — private key / certificate resolution", () => {
     );
   });
 });
-
-describe("eims.config — baked-in Ethiopia region/zone/woreda codes", () => {
-  it("resolves a known region/wereda/zone with no env var set at all", () => {
-    withEnv(
-      { ...REQUIRED, EIMS_PRIVATE_KEY: "x", EIMS_CERTIFICATE_PATH: "/dev/null" },
-      () => {
-        const cfg = eimsConfigFactory();
-        expect(cfg.invoice.buyerRegionCodes.Somali).toBe("05");
-        expect(cfg.invoice.buyerWeredaCodes["Jijiga Town"]).toBe("02");
-        expect(cfg.invoice.buyerCityCodes.Fafan).toBe("01");
-      },
-    );
-  });
-
-  it("an env var entry overrides the baked-in code for the same name", () => {
-    withEnv(
-      {
-        ...REQUIRED,
-        EIMS_PRIVATE_KEY: "x",
-        EIMS_CERTIFICATE_PATH: "/dev/null",
-        EIMS_BUYER_REGION_CODES: "Somali=99",
-      },
-      () => {
-        expect(eimsConfigFactory().invoice.buyerRegionCodes.Somali).toBe("99");
-      },
-    );
-  });
-
-  it("an env var still adds a name the baked-in table doesn't have (a spelling variant)", () => {
-    withEnv(
-      {
-        ...REQUIRED,
-        EIMS_PRIVATE_KEY: "x",
-        EIMS_CERTIFICATE_PATH: "/dev/null",
-        EIMS_BUYER_CITY_CODES: "Fafen=01",
-      },
-      () => {
-        const codes = eimsConfigFactory().invoice.buyerCityCodes;
-        expect(codes.Fafen).toBe("01");
-        expect(codes.Fafan).toBe("01"); // baked-in entry still present alongside it
-      },
-    );
-  });
-
-  it("resolves the bare Addis Ababa sub-city name a buyer profile actually stores, not the CSV's example-woreda name", () => {
-    withEnv(
-      { ...REQUIRED, EIMS_PRIVATE_KEY: "x", EIMS_CERTIFICATE_PATH: "/dev/null" },
-      () => {
-        const codes = eimsConfigFactory().invoice.buyerWeredaCodes;
-        expect(codes.Bole).toBe("01");
-        expect(codes.Arada).toBe("01");
-        expect(codes.Kirkos).toBe("01");
-        expect(codes.Yeka).toBe("01");
-        expect(codes["Nifas Silk Lafto"]).toBe("13");
-        expect(codes["Nefas Silk-Lafto"]).toBe("13");
-      },
-    );
-  });
-});

apps/edr-freight-api/src/config/eims.config.ts

@@ -1,6 +1,5 @@
 import { registerAs } from "@nestjs/config";
 
-import { ETHIOPIA_REGION_CODES, ETHIOPIA_WOREDA_CODES, ETHIOPIA_ZONE_CODES } from "./ethiopia-geo-codes";
 
 /**
  * Ethiopian MoR EIMS e-invoicing gateway.
@@ -99,35 +98,6 @@ export interface EimsInvoiceConfig {
   paymentMode: string;
   paymentTerm: string;
   unitDefault: string;
-  /**
-   * Domestic fallback only — used when the buyer's `Company.country` is empty or "Ethiopia" (the
-   * column's own default) and not already listed in `buyerCountryCodes`. A genuinely foreign
-   * buyer must be in `buyerCountryCodes` by name or the mapping fails locally; this value is never
-   * applied to them, so an unconfigured foreign country can't silently be filed as Ethiopia.
-   */
-  buyerCountryCode: string | null;
-  /**
-   * Country name → MoR code, from `EIMS_BUYER_COUNTRY_CODES` ("Ethiopia=231,Djibouti=071"). Format
-   * unconfirmed (unlike Region/Wereda, MoR has never named a Country regex), so — unlike them —
-   * this is not validated against a fixed digit pattern, only looked up by name.
-   */
-  buyerCountryCodes: Record<string, string>;
-  /**
-   * Buyer region name → MoR numeric code, from `EIMS_BUYER_REGION_CODES`
-   * ("Addis Ababa=13,Oromia=4"). A buyer whose region is neither a code nor in this map fails
-   * locally rather than being filed with a guessed one.
-   */
-  buyerRegionCodes: Record<string, string>;
-  /** Same mechanism as `buyerRegionCodes`, for `EIMS_BUYER_WEREDA_CODES` ("Yeka=574"). */
-  buyerWeredaCodes: Record<string, string>;
-  /**
-   * Buyer *zone* name → MoR City code, from `EIMS_BUYER_CITY_CODES` ("Kirkos=101"). `Company` has
-   * no dedicated city column — Zone is the closest match in EDR's own data. Optional, unlike
-   * Region/Wereda: MoR has never required City on a live buyer (confirmed — filing already
-   * succeeds with it null), so an unmapped zone falls back to null rather than failing the
-   * mapping.
-   */
-  buyerCityCodes: Record<string, string>;
   /**
    * Per-`chargeType` tax treatment, e.g. `EIMS_TAX_CODE_BY_CHARGE_TYPE=RAIL_FREIGHT=VAT0` +
    * `EIMS_TAX_RATE_BY_CHARGE_TYPE=RAIL_FREIGHT=0`. A charge type not listed here falls back to
@@ -258,13 +228,6 @@ export default registerAs("eims", (): EimsConfig => {
       paymentMode: process.env.EIMS_PAYMENT_MODE ?? "",
       paymentTerm: process.env.EIMS_PAYMENT_TERM ?? "",
       unitDefault: process.env.EIMS_UNIT_DEFAULT ?? "",
-      buyerCountryCode: process.env.EIMS_BUYER_COUNTRY_CODE || null,
-      buyerCountryCodes: parseCodeMap(process.env.EIMS_BUYER_COUNTRY_CODES),
-      // Baked-in Ethiopia reference table first, env var entries win on a name collision — lets a
-      // deployment override or add to it without a redeploy. See ethiopia-geo-codes.ts.
-      buyerRegionCodes: { ...ETHIOPIA_REGION_CODES, ...parseCodeMap(process.env.EIMS_BUYER_REGION_CODES) },
-      buyerWeredaCodes: { ...ETHIOPIA_WOREDA_CODES, ...parseCodeMap(process.env.EIMS_BUYER_WEREDA_CODES) },
-      buyerCityCodes: { ...ETHIOPIA_ZONE_CODES, ...parseCodeMap(process.env.EIMS_BUYER_CITY_CODES) },
       taxCodeByChargeType: parseCodeMap(process.env.EIMS_TAX_CODE_BY_CHARGE_TYPE),
       taxRateByChargeType: parseCodeMap(process.env.EIMS_TAX_RATE_BY_CHARGE_TYPE),
       exciseByChargeType: parseCodeMap(process.env.EIMS_EXCISE_BY_CHARGE_TYPE),

apps/edr-freight-api/src/config/ethiopia-geo-codes.ts

@@ -1,160 +0,0 @@
-/**
- * MoR EIMS region/zone/woreda codes, by name — the baked-in fallback under
- * `EIMS_BUYER_REGION_CODES`/`EIMS_BUYER_WEREDA_CODES`/`EIMS_BUYER_CITY_CODES` (zone is the closest
- * match to EIMS's "City", per `eims-invoice.mapper.ts`).
- *
- * Before this existed, every buyer from a not-yet-seen region/zone/woreda crashed EIMS filing until
- * someone hunted down the code and added it to an env var by hand — happened three times in one
- * afternoon (2026-08-17: Somali region, Fafan zone, Jigjiga woreda, even the Ethiopia country code
- * itself were all unset). Ethiopia's administrative divisions are fixed, known, reference data, not
- * something that should be maintained reactively per buyer. Source: `ethiopia_administrative_
- * hierarchy_master.csv`, supplied 2026-08-17 — NOT exhaustive (a representative sample per region,
- * not all ~1000 real woredas), extend as new gaps surface.
- *
- * The env vars stay wired in ahead of this table (see `eims.config.ts`) — for a quick correction
- * without a redeploy, or a name spelled differently in a buyer's profile than in this table (already
- * hit live: DB has zone "Fafen", this table's official spelling is "Fafan" — same zone, matching is
- * case/space-insensitive but not spelling-tolerant, so the env var override is still how that buyer
- * actually resolves; this table mainly helps the *next* buyer whose profile spelling matches).
- *
- * ponytail: region names are unique nationwide (only ~15), safe as a flat map. Zone and woreda names
- * are not always unique across different regions (e.g. "North Shewa" is both an Amhara zone and an
- * Oromia zone, different codes) — `Company` stores region/zone/woreda as three independent strings,
- * no parent linkage, so a flat name lookup can't disambiguate. First occurrence in the source data
- * wins on a collision. Only affects the optional `City` field (zone) — never blocks filing, unlike
- * Region/Wereda. A correct fix needs `Company` to store a linked hierarchy, not just three strings;
- * out of scope here. Upgrade path: key this by `${region}/${zone}` once that linkage exists.
- */
-const ROWS: Array<[region: string, zone: string, woreda: string, regionCode: string, zoneCode: string, woredaCode: string]> = [
-  ["Tigray", "Western Tigray", "Humera", "01", "01", "01"],
-  ["Tigray", "Western Tigray", "Kafta Humera", "01", "01", "02"],
-  ["Tigray", "Western Tigray", "Tsegede", "01", "01", "03"],
-  ["Tigray", "North Western Tigray", "Shire Endaselassie", "01", "02", "01"],
-  ["Tigray", "North Western Tigray", "Sheraro", "01", "02", "02"],
-  ["Tigray", "Central Tigray", "Axum", "01", "03", "01"],
-  ["Tigray", "Central Tigray", "Adwa", "01", "03", "02"],
-  ["Tigray", "Eastern Tigray", "Adigrat", "01", "04", "01"],
-  ["Tigray", "Southern Tigray", "Maychew", "01", "05", "01"],
-  ["Tigray", "Mekelle Special Zone", "Mekelle City", "01", "06", "01"],
-  ["Afar", "Awusi Rasu (Zone 1)", "Asayita", "02", "01", "01"],
-  ["Afar", "Awusi Rasu (Zone 1)", "Semera-Logiya", "02", "01", "02"],
-  ["Afar", "Kilbet Rasu (Zone 2)", "Abala", "02", "02", "01"],
-  ["Afar", "Gabi Rasu (Zone 3)", "Awash Fentale", "02", "03", "01"],
-  ["Afar", "Fantena Rasu (Zone 4)", "Yalo", "02", "04", "01"],
-  ["Afar", "Hari Rasu (Zone 5)", "Telalak", "02", "05", "01"],
-  ["Amhara", "North Gondar", "Debark", "03", "01", "01"],
-  ["Amhara", "South Gondar", "Debre Tabor", "03", "02", "01"],
-  ["Amhara", "North Wollo", "Woldiya", "03", "03", "01"],
-  ["Amhara", "South Wollo", "Dessie Town", "03", "04", "01"],
-  ["Amhara", "North Shewa", "Debre Berhan", "03", "05", "01"],
-  ["Amhara", "East Gojjam", "Debre Markos", "03", "06", "01"],
-  ["Amhara", "West Gojjam", "Finote Selam", "03", "07", "01"],
-  ["Amhara", "Wag Hemra", "Sekota", "03", "08", "01"],
-  ["Amhara", "Awi", "Injibara", "03", "09", "01"],
-  ["Amhara", "Oromia Special Zone", "Kemise", "03", "10", "01"],
-  ["Amhara", "Bahir Dar Special Zone", "Bahir Dar City", "03", "11", "01"],
-  ["Amhara", "Gondar Special Zone", "Gondar City", "03", "12", "01"],
-  ["Oromia", "North Shewa", "Fiche", "04", "01", "01"],
-  ["Oromia", "South West Shewa", "Waliso", "04", "02", "01"],
-  ["Oromia", "East Shewa", "Adama Town", "04", "03", "01"],
-  ["Oromia", "East Shewa", "Bishoftu Town", "04", "03", "02"],
-  ["Oromia", "West Shewa", "Ambo", "04", "04", "01"],
-  ["Oromia", "Arsi", "Asella", "04", "05", "01"],
-  ["Oromia", "West Arsi", "Shashemene", "04", "06", "01"],
-  ["Oromia", "Bale", "Robe", "04", "07", "01"],
-  ["Oromia", "East Hararghe", "Harar Outskirts", "04", "08", "01"],
-  ["Oromia", "West Hararghe", "Chiro", "04", "09", "01"],
-  ["Oromia", "Jimma", "Jimma Town", "04", "10", "01"],
-  ["Oromia", "Illubabor", "Mettu", "04", "11", "01"],
-  ["Oromia", "Buno Bedele", "Bedele", "04", "12", "01"],
-  ["Oromia", "Welega (West)", "Gimbi", "04", "13", "01"],
-  ["Oromia", "Welega (East)", "Nekemte", "04", "14", "01"],
-  ["Oromia", "Horo Guduru Welega", "Shambu", "04", "15", "01"],
-  ["Oromia", "Kelam Welega", "Dembidolo", "04", "16", "01"],
-  ["Oromia", "Borena", "Yabelo", "04", "17", "01"],
-  ["Oromia", "Guji", "Negele Borana", "04", "18", "01"],
-  ["Oromia", "West Guji", "Bule Hora", "04", "19", "01"],
-  ["Oromia", "East Bale", "Ginir", "04", "20", "01"],
-  ["Oromia", "Sheger City", "Sululta", "04", "21", "01"],
-  ["Somali", "Fafan", "Jijiga Woreda", "05", "01", "01"],
-  ["Somali", "Fafan", "Jijiga Town", "05", "01", "02"],
-  ["Somali", "Fafan", "Awbare", "05", "01", "03"],
-  ["Somali", "Sitti", "Shinile", "05", "02", "01"],
-  ["Somali", "Erer", "Fiq", "05", "03", "01"],
-  ["Somali", "Jarar", "Degehabur", "05", "04", "01"],
-  ["Somali", "Nogob", "Segeg", "05", "05", "01"],
-  ["Somali", "Korahe", "Kebridehar", "05", "06", "01"],
-  ["Somali", "Shabelle", "Gode", "05", "07", "01"],
-  ["Somali", "Afder", "Afder Woreda", "05", "08", "01"],
-  ["Somali", "Liben", "Filtu", "05", "09", "01"],
-  ["Somali", "Dhawa", "Mubarak", "05", "10", "01"],
-  ["Somali", "Dollo", "Warder", "05", "11", "01"],
-  ["Benishangul-Gumuz", "Asosa", "Asosa Woreda", "06", "01", "01"],
-  ["Benishangul-Gumuz", "Kamasashi", "Kamasashi Woreda", "06", "02", "01"],
-  ["Benishangul-Gumuz", "Metekel", "Gilgel Beles", "06", "03", "01"],
-  ["Southern Ethiopia", "Wolayta", "Sodo Zuria", "07", "01", "01"],
-  ["Southern Ethiopia", "Wolayta", "Sodo Town", "07", "01", "02"],
-  ["Southern Ethiopia", "Gamo", "Arba Minch Town", "07", "02", "01"],
-  ["Southern Ethiopia", "Gofa", "Sawla", "07", "03", "01"],
-  ["Southern Ethiopia", "Konso", "Konso Woreda", "07", "04", "01"],
-  ["Southern Ethiopia", "South Omo", "Jinka", "07", "05", "01"],
-  ["Gambela", "Anywaa", "Gambela Zuria", "08", "01", "01"],
-  ["Gambela", "Nuer", "Lare", "08", "02", "01"],
-  ["Gambela", "Majang", "Metu Zuria part", "08", "03", "01"],
-  ["Harari", "Harar Hundanee", "Amir Nur Woreda", "09", "01", "01"],
-  ["Harari", "Harar Hundanee", "Abadir Woreda", "09", "01", "02"],
-  ["Addis Ababa", "Bole Sub-City", "Bole Woreda 01", "10", "01", "01"],
-  ["Addis Ababa", "Kirkos Sub-City", "Kirkos Woreda 01", "10", "02", "01"],
-  ["Addis Ababa", "Nifas Silk Lafto", "NSL Woreda 13", "10", "03", "13"],
-  ["Addis Ababa", "Yeka Sub-City", "Yeka Woreda 01", "10", "04", "01"],
-  ["Addis Ababa", "Arada Sub-City", "Arada Woreda 01", "10", "05", "01"],
-  ["Dire Dawa", "Dire Dawa Urban", "Melka Jebdu", "11", "01", "01"],
-  ["Dire Dawa", "Dire Dawa Rural", "Gurgura", "11", "02", "01"],
-  ["Sidama", "Hawassa City Admin", "Hayek Chereka", "12", "01", "01"],
-  ["Sidama", "Sidama Zuria", "Yirgalem Town", "12", "02", "01"],
-  ["Sidama", "Sidama Zuria", "Aleta Wendo", "12", "02", "02"],
-  ["Southwest Ethiopia", "Keffa", "Bonga Town", "13", "01", "01"],
-  ["Southwest Ethiopia", "Sheka", "Mappi Zuria", "13", "02", "01"],
-  ["Southwest Ethiopia", "Bench Sheko", "Mizan Aman", "13", "03", "01"],
-  ["Central Ethiopia", "Gurage", "Wolkite", "14", "01", "01"],
-  ["Central Ethiopia", "Hadiya", "Hosaina", "14", "02", "01"],
-  ["Central Ethiopia", "Silte", "Worabe", "14", "03", "01"],
-  ["Gedeo State", "Gedeo Zone", "Dilla Zuria", "15", "01", "01"],
-  ["Gedeo State", "Gedeo Zone", "Yirgacheffe", "15", "01", "02"],
-];
-
-/** First occurrence wins on a name collision — see the class comment. */
-const buildMap = (pick: (row: (typeof ROWS)[number]) => [string, string]): Record<string, string> => {
-  const map: Record<string, string> = {};
-  for (const row of ROWS) {
-    const [name, code] = pick(row);
-    if (!(name in map)) map[name] = code;
-  }
-  return map;
-};
-
-export const ETHIOPIA_REGION_CODES: Record<string, string> = buildMap((r) => [r[0], r[3]]);
-/** Zone name → code. Fed into `buyerCityCodes` — EIMS's "City" is really the buyer's zone. */
-export const ETHIOPIA_ZONE_CODES: Record<string, string> = buildMap((r) => [r[1], r[4]]);
-export const ETHIOPIA_WOREDA_CODES: Record<string, string> = buildMap((r) => [r[2], r[5]]);
-
-/**
- * Buyer records commonly store just the bare Addis Ababa sub-city name ("Bole", "Arada") as their
- * woreda, not the source CSV's specific example-woreda name ("Bole Woreda 01") — confirmed live
- * 2026-08-17 across three different buyers before any of them actually got past this check. Since
- * the CSV lists exactly one representative woreda per Addis sub-city, alias the bare name to that
- * same code rather than wait on a fuller table.
- */
-const ADDIS_SUBCITY_ALIASES: Array<[bareName: string, csvZoneName: string]> = [
-  ["Bole", "Bole Sub-City"],
-  ["Kirkos", "Kirkos Sub-City"],
-  ["Nifas Silk Lafto", "Nifas Silk Lafto"],
-  // Matches EIMS_BUYER_WEREDA_CODES' own existing spelling in .env — same zone, different hyphenation.
-  ["Nefas Silk-Lafto", "Nifas Silk Lafto"],
-  ["Yeka", "Yeka Sub-City"],
-  ["Arada", "Arada Sub-City"],
-];
-for (const [bareName, csvZoneName] of ADDIS_SUBCITY_ALIASES) {
-  const row = ROWS.find((r) => r[1] === csvZoneName);
-  if (row && !(bareName in ETHIOPIA_WOREDA_CODES)) ETHIOPIA_WOREDA_CODES[bareName] = row[5];
-}

apps/edr-freight-api/src/config/mor-location.resolver.spec.ts

@@ -0,0 +1,275 @@
+import { MorLocationTuple } from "./mor-locations.data";
+import {
+  MorGeoMappingError,
+  normalizeName,
+  resolveMorGeo,
+  tryResolveMorGeo,
+} from "./mor-location.resolver";
+
+/**
+ * Rows copied verbatim out of the Ministry sheet (`EIMS_COUNTRY_REGION_VW`), chosen for the traps
+ * the real data contains rather than for tidiness:
+ *
+ *  - BABILE and KERSA each exist in two different zones with different LOCALITY_NOs — the reason a
+ *    global name lookup is unsafe and the hierarchy is mandatory.
+ *  - ILLUBABOR has BURE twice under the same zone with different LOCALITY_NOs (691 and 890, the
+ *    second with the Ministry's own trailing space) — a genuine ambiguity that must never be
+ *    silently resolved to the first row.
+ *  - "Wal-Mera" and "Akaki woreda" carry the sheet's mixed casing and punctuation.
+ */
+const FIXTURE: MorLocationTuple[] = [
+  [70, "Ethiopia", 6, "SOMALI", 31, "FAAFAN ZONE", 190, "JIJIGA"],
+  [70, "Ethiopia", 6, "SOMALI", 31, "FAAFAN ZONE", 194, "BABILE"],
+  [70, "Ethiopia", 6, "SOMALI", 30, "SITI ZONE", 197, "DENBEL"],
+  [70, "Ethiopia", 2, "OROMIA", 8, "MISRAK HARARGE", 495, "BABILE"],
+  [70, "Ethiopia", 2, "OROMIA", 8, "MISRAK HARARGE", 482, "KERSA"],
+  [70, "Ethiopia", 2, "OROMIA", 72, "JIMMA ZONE", 503, "KERSA"],
+  [70, "Ethiopia", 2, "OROMIA", 73, "ILLUBABOR", 691, "BURE"],
+  [70, "Ethiopia", 2, "OROMIA", 73, "ILLUBABOR", 890, "BURE "],
+  [70, "Ethiopia", 2, "OROMIA", 86, "FINFINE VIC SPEC", 976, "Wal-Mera"],
+  [70, "Ethiopia", 2, "OROMIA", 86, "FINFINE VIC SPEC", 909, "Akaki woreda"],
+  [70, "Ethiopia", 13, "ADDIS ABABA", 78, "BOLE", 1100, "WOREDA 1"],
+  [253, "Djibouti", 1, "DJIBOUTI", 1, "DJIBOUTI VILLE", 1, "BALBALA"],
+];
+
+const JIJIGA = {
+  country: "Ethiopia",
+  region: "SOMALI",
+  zone: "FAAFAN ZONE",
+  woreda: "JIJIGA",
+};
+
+describe("normalizeName", () => {
+  it("collapses whitespace, trims, and compares case-insensitively", () => {
+    expect(normalizeName("  FAAFAN   ZONE ")).toBe("FAAFAN ZONE");
+    expect(normalizeName("faafan zone")).toBe("FAAFAN ZONE");
+    expect(normalizeName("  FAAFAN   ZONE ")).toBe(normalizeName("faafan zone"));
+  });
+
+  it("normalizes harmless punctuation and hyphen/space differences", () => {
+    expect(normalizeName("Wal-Mera")).toBe("WAL MERA");
+    expect(normalizeName("Wal Mera")).toBe("WAL MERA");
+    expect(normalizeName("ZONE 1 (AYSSAITA)")).toBe("ZONE 1 AYSSAITA");
+    expect(normalizeName("Ber'ano")).toBe("BERANO");
+    expect(normalizeName("KEAHORE/HADAT/")).toBe("KEAHORE HADAT");
+  });
+
+  it("keeps digits, which several MoR locality names depend on", () => {
+    expect(normalizeName(" woreda  10 ")).toBe("WOREDA 10");
+    expect(normalizeName("WOREDA 1")).not.toBe(normalizeName("WOREDA 10"));
+  });
+});
+
+describe("resolveMorGeo", () => {
+  it("resolves the exact MoR spelling to the Ministry's own codes", () => {
+    expect(resolveMorGeo(JIJIGA, FIXTURE)).toEqual({
+      Country: "70",
+      Region: "6",
+      City: "31",
+      Wereda: "190",
+    });
+  });
+
+  it("resolves the EDR/e-Trade spellings through the alias layer", () => {
+    expect(
+      resolveMorGeo(
+        {
+          country: "Ethiopia",
+          region: "Somali",
+          zone: "Fafen",
+          woreda: "Jigjiga",
+        },
+        FIXTURE,
+      ),
+    ).toEqual({ Country: "70", Region: "6", City: "31", Wereda: "190" });
+  });
+
+  it("is case-insensitive", () => {
+    expect(
+      resolveMorGeo(
+        {
+          country: "ethiopia",
+          region: "somali",
+          zone: "faafan zone",
+          woreda: "jijiga",
+        },
+        FIXTURE,
+      ),
+    ).toEqual({ Country: "70", Region: "6", City: "31", Wereda: "190" });
+  });
+
+  it("ignores leading, trailing and repeated whitespace on every level", () => {
+    expect(
+      resolveMorGeo(
+        {
+          country: "  Ethiopia ",
+          region: " SOMALI  ",
+          zone: "  FAAFAN   ZONE ",
+          woreda: "\tJIJIGA  ",
+        },
+        FIXTURE,
+      ),
+    ).toEqual({ Country: "70", Region: "6", City: "31", Wereda: "190" });
+  });
+
+  it("treats a hyphen as a space, in either direction", () => {
+    const expected = { Country: "70", Region: "2", City: "86", Wereda: "976" };
+    const base = {
+      country: "Ethiopia",
+      region: "Oromia",
+      zone: "Finfine Vic Spec",
+    };
+    expect(resolveMorGeo({ ...base, woreda: "Wal-Mera" }, FIXTURE)).toEqual(expected);
+    expect(resolveMorGeo({ ...base, woreda: "wal mera" }, FIXTURE)).toEqual(expected);
+  });
+
+  it("matches a zone whose MoR label carries the ' ZONE' suffix EDR does not store", () => {
+    expect(resolveMorGeo({ ...JIJIGA, zone: "Faafan" }, FIXTURE).City).toBe("31");
+    expect(
+      resolveMorGeo(
+        {
+          country: "Ethiopia",
+          region: "Somali",
+          zone: "Siti",
+          woreda: "Denbel",
+        },
+        FIXTURE,
+      ),
+    ).toEqual({ Country: "70", Region: "6", City: "30", Wereda: "197" });
+  });
+
+  describe("a locality name that exists in more than one zone", () => {
+    it("picks BABILE by its full hierarchy, never by name alone", () => {
+      expect(resolveMorGeo({ ...JIJIGA, woreda: "BABILE" }, FIXTURE).Wereda).toBe("194");
+      expect(
+        resolveMorGeo(
+          {
+            country: "Ethiopia",
+            region: "OROMIA",
+            zone: "MISRAK HARARGE",
+            woreda: "BABILE",
+          },
+          FIXTURE,
+        ).Wereda,
+      ).toBe("495");
+    });
+
+    it("picks KERSA by its full hierarchy", () => {
+      const oromia = { country: "Ethiopia", region: "OROMIA" };
+      expect(
+        resolveMorGeo({ ...oromia, zone: "MISRAK HARARGE", woreda: "KERSA" }, FIXTURE).Wereda,
+      ).toBe("482");
+      expect(
+        resolveMorGeo({ ...oromia, zone: "JIMMA ZONE", woreda: "KERSA" }, FIXTURE).Wereda,
+      ).toBe("503");
+    });
+
+    it("does not let a locality leak across regions", () => {
+      // DENBEL exists under SOMALI/SITI ZONE only — asking for it under OROMIA must fail, not
+      // fall back to the nationwide match the old flat maps would have found.
+      expect(() =>
+        resolveMorGeo(
+          {
+            country: "Ethiopia",
+            region: "OROMIA",
+            zone: "MISRAK HARARGE",
+            woreda: "DENBEL",
+          },
+          FIXTURE,
+        ),
+      ).toThrow(/no MoR LOCALITY_DESC match/);
+    });
+  });
+
+  describe("failures happen locally, before anything is filed", () => {
+    const cases: Array<[string, Record<string, string>, RegExp]> = [
+      ["unknown country", { ...JIJIGA, country: "Wakanda" }, /no MoR COUNTRY_NAME match/],
+      ["unknown region", { ...JIJIGA, region: "Atlantis" }, /no MoR PARISH_NAME match/],
+      ["unknown zone", { ...JIJIGA, zone: "Nowhere Zone" }, /no MoR CITY_NAME match/],
+      ["unknown woreda", { ...JIJIGA, woreda: "Example" }, /no MoR LOCALITY_DESC match/],
+    ];
+
+    it.each(cases)("%s fails with an actionable validation error", (_label, input, pattern) => {
+      expect(() => resolveMorGeo(input, FIXTURE)).toThrow(MorGeoMappingError);
+      expect(() => resolveMorGeo(input, FIXTURE)).toThrow(pattern);
+    });
+
+    it("names the offending address in the message so the company record can be corrected", () => {
+      expect(() => resolveMorGeo({ ...JIJIGA, woreda: "Example" }, FIXTURE)).toThrow(
+        /country="Ethiopia", region="SOMALI", zone="FAAFAN ZONE", woreda="Example"/,
+      );
+    });
+
+    it("refuses an ambiguous locality instead of taking the first row", () => {
+      const input = {
+        country: "Ethiopia",
+        region: "OROMIA",
+        zone: "ILLUBABOR",
+        woreda: "BURE",
+      };
+      expect(() => resolveMorGeo(input, FIXTURE)).toThrow(MorGeoMappingError);
+      expect(() => resolveMorGeo(input, FIXTURE)).toThrow(/ambiguous/);
+      // Both colliding codes are named, and neither is silently selected.
+      expect(() => resolveMorGeo(input, FIXTURE)).toThrow(/691, 890/);
+      expect(tryResolveMorGeo(input, FIXTURE)).toBeNull();
+    });
+
+    it("fails loudly when the MoR master has not been generated yet", () => {
+      expect(() => resolveMorGeo(JIJIGA, [])).toThrow(/MoR location master is empty/);
+    });
+  });
+
+  it("reproduces MoR's numeric values unchanged, as strings", () => {
+    const codes = resolveMorGeo(JIJIGA, FIXTURE);
+    expect(codes).toEqual({
+      Country: "70",
+      Region: "6",
+      City: "31",
+      Wereda: "190",
+    });
+    for (const value of Object.values(codes)) {
+      expect(typeof value).toBe("string");
+      expect(value).toMatch(/^[0-9]+$/);
+    }
+    // The source row is the only origin of every code — no renumbering, no derivation.
+    const [countryNo, , parishNo, , cityNo, , localityNo] = FIXTURE[0];
+    expect(codes).toEqual({
+      Country: String(countryNo),
+      Region: String(parishNo),
+      City: String(cityNo),
+      Wereda: String(localityNo),
+    });
+  });
+
+  it("never emits an Open Admin Data ETxx identifier", () => {
+    for (const value of Object.values(resolveMorGeo(JIJIGA, FIXTURE))) {
+      expect(value).not.toMatch(/^ET/i);
+    }
+  });
+
+  it("treats a blank country as domestic, matching the column default", () => {
+    expect(resolveMorGeo({ ...JIJIGA, country: "" }, FIXTURE).Country).toBe("70");
+    expect(resolveMorGeo({ ...JIJIGA, country: null }, FIXTURE).Country).toBe("70");
+  });
+
+  it("resolves a named foreign country rather than defaulting it to Ethiopia", () => {
+    expect(
+      resolveMorGeo(
+        {
+          country: "Djibouti",
+          region: "DJIBOUTI",
+          zone: "DJIBOUTI VILLE",
+          woreda: "BALBALA",
+        },
+        FIXTURE,
+      ),
+    ).toEqual({ Country: "253", Region: "1", City: "1", Wereda: "1" });
+  });
+
+  it("accepts a company record that already holds a MoR code, but only a real one", () => {
+    expect(resolveMorGeo({ ...JIJIGA, region: "6" }, FIXTURE).Region).toBe("6");
+    expect(() => resolveMorGeo({ ...JIJIGA, region: "999" }, FIXTURE)).toThrow(
+      /no MoR PARISH_NAME match/,
+    );
+  });
+});

apps/edr-freight-api/src/config/mor-location.resolver.ts

@@ -0,0 +1,255 @@
+import { BadRequestException } from "@nestjs/common";
+
+import { MOR_LOCATIONS, MorLocationTuple } from "./mor-locations.data";
+
+/**
+ * Resolves an EDR company address to the Ministry of Revenues' own EIMS location codes, using the
+ * MoR location master (`EIMS_COUNTRY_REGION_VW`) shipped in `mor-locations.data.ts`.
+ *
+ * MoR's field names do not line up with either EDR's or generic Ethiopian administrative datasets,
+ * so the mapping is fixed by the Ministry sheet, not by interpretation:
+ *
+ *   Company.country -> COUNTRY_NAME  -> COUNTRY_NO  -> BuyerDetails.Country
+ *   Company.region  -> PARISH_NAME   -> PARISH_NO   -> BuyerDetails.Region
+ *   Company.zone    -> CITY_NAME     -> CITY_NO     -> BuyerDetails.City
+ *   Company.woreda  -> LOCALITY_DESC -> LOCALITY_NO -> BuyerDetails.Wereda
+ *
+ * This replaces the previous `EIMS_BUYER_*_CODES` environment maps and the `ethiopia-geo-codes.ts`
+ * table they layered over. Both invented their codes (sequential "01".."15" per region, from a
+ * generic administrative CSV) and both looked names up **globally**, which cannot be correct:
+ * KERSA, GORO, BABILE and BURE each occur in several different zones with different LOCALITY_NOs.
+ * A global name lookup silently picked the first, i.e. filed a real invoice against whichever tax
+ * jurisdiction happened to sort first. Resolution here is strictly hierarchical — each level is
+ * searched only within the rows its parent already selected.
+ *
+ * Open Admin Data identifiers (`ET14`, `ET0407`, …) are unrelated to this code system and must
+ * never appear in an EIMS payload; nothing in this module can emit one, since every returned value
+ * comes from a numeric column of the Ministry sheet.
+ */
+
+export interface MorGeoCodes {
+  /** COUNTRY_NO as a string — `BuyerDetails.Country`. */
+  Country: string;
+  /** PARISH_NO as a string — `BuyerDetails.Region`. */
+  Region: string;
+  /** CITY_NO as a string — `BuyerDetails.City`. MoR calls the zone level "City". */
+  City: string;
+  /** LOCALITY_NO as a string — `BuyerDetails.Wereda`. */
+  Wereda: string;
+}
+
+export interface MorAddressInput {
+  country?: string | null;
+  region?: string | null;
+  zone?: string | null;
+  woreda?: string | null;
+}
+
+type Level = "country" | "region" | "zone" | "woreda";
+
+/** Which tuple slots hold the name and the code at each level. */
+const SLOTS: Record<Level, { name: 1 | 3 | 5 | 7; no: 0 | 2 | 4 | 6; column: string }> = {
+  country: { name: 1, no: 0, column: "COUNTRY_NAME" },
+  region: { name: 3, no: 2, column: "PARISH_NAME" },
+  zone: { name: 5, no: 4, column: "CITY_NAME" },
+  woreda: { name: 7, no: 6, column: "LOCALITY_DESC" },
+};
+
+/**
+ * One normalized form for both sides of every comparison. Deliberately conservative: it removes
+ * differences that cannot change which jurisdiction is meant (case, stray and repeated whitespace,
+ * hyphen/slash/parenthesis/apostrophe punctuation, combining accents) and nothing else. There is
+ * no fuzzy or edit-distance matching anywhere in this module — a near-miss must fail loudly rather
+ * than file an invoice against a neighbouring woreda.
+ *
+ *   "  FAAFAN   ZONE " -> "FAAFAN ZONE"
+ *   "Wal-Mera"         -> "WAL MERA"
+ *   "Ber'ano"          -> "BERANO"
+ *   "ZONE 1 (AYSSAITA)"-> "ZONE 1 AYSSAITA"
+ */
+const normalizeCache = new Map<string, string>();
+export function normalizeName(value: string | null | undefined): string {
+  const raw = value ?? "";
+  const hit = normalizeCache.get(raw);
+  if (hit !== undefined) return hit;
+  const normalized = raw
+    .normalize("NFKD")
+    .replace(/[\u0300-\u036f]/g, "")
+    .toUpperCase()
+    .replace(/['\u2018\u2019`]/g, "")
+    .replace(/[^A-Z0-9]+/g, " ")
+    .trim();
+  normalizeCache.set(raw, normalized);
+  return normalized;
+}
+
+/**
+ * Reviewed spelling differences between what EDR/e-Trade store and what the Ministry sheet calls
+ * the same place. Every entry is scoped to the administrative level it applies to, and to its
+ * parent where the name is not unique nationwide — so an alias can never reach across into another
+ * region's jurisdiction. `from`/`to` are compared normalized, so casing and spacing here are
+ * cosmetic.
+ *
+ * Add an entry only after confirming the two names are the same place in the Ministry sheet. This
+ * is the only sanctioned place for spelling compatibility; `mor-locations.data.ts` stays verbatim.
+ */
+interface MorAlias {
+  level: Exclude<Level, "country">;
+  /** Parent scope, normalized-compared. Omit a level to leave the alias unscoped at that level. */
+  region?: string;
+  zone?: string;
+  from: string;
+  to: string;
+}
+
+const ALIASES: MorAlias[] = [
+  // e-Trade and the customer portal both spell the Somali zone "Fafen"; MoR spells it "FAAFAN
+  // ZONE". Confirmed same zone (CITY_NO 31) — this is the buyer that first exposed the whole
+  // fabricated-code problem.
+  { level: "zone", region: "SOMALI", from: "Fafen", to: "FAAFAN ZONE" },
+  // MoR's own capital of that zone is "JIJIGA"; every other source spells it "Jigjiga".
+  {
+    level: "woreda",
+    region: "SOMALI",
+    zone: "FAAFAN ZONE",
+    from: "Jigjiga",
+    to: "JIJIGA",
+  },
+];
+
+/**
+ * MoR suffixes many zone labels with " ZONE" ("JIMMA ZONE", "FAAFAN ZONE", "SITI ZONE") while EDR
+ * stores the bare name. Retrying the suffixed spelling is an exact match against a second candidate
+ * string, scoped to the already-resolved region — not fuzzy matching — and it removes a long tail
+ * of otherwise hand-maintained aliases. Applied to the zone level only: locality suffixes
+ * ("WOREDA", "TOWN ADMINISTRATION") are not mechanical and could select a different place.
+ */
+const zoneSuffixCandidates = (normalized: string): string[] =>
+  normalized.endsWith(" ZONE") ? [] : [`${normalized} ZONE`];
+
+export class MorGeoMappingError extends BadRequestException {
+  constructor(code: "EIMS_GEO_MAPPING_FAILED" | "EIMS_GEO_AMBIGUOUS", message: string) {
+    super({ code, message });
+  }
+}
+
+/** Renders the address being resolved for an error message. No customer-identifying data. */
+const describe = (input: MorAddressInput): string =>
+  `country="${input.country ?? ""}", region="${input.region ?? ""}", ` +
+  `zone="${input.zone ?? ""}", woreda="${input.woreda ?? ""}"`;
+
+function matchLevel(
+  rows: MorLocationTuple[],
+  level: Level,
+  raw: string | null | undefined,
+  parents: { region?: string; zone?: string },
+  input: MorAddressInput,
+): { no: number; rows: MorLocationTuple[] } {
+  const { name: nameSlot, no: noSlot, column } = SLOTS[level];
+  const wanted = normalizeName(raw);
+
+  const candidates: string[] = [];
+  if (wanted) {
+    candidates.push(wanted);
+    for (const alias of ALIASES) {
+      if (alias.level !== level) continue;
+      if (alias.region && normalizeName(alias.region) !== parents.region) continue;
+      if (alias.zone && normalizeName(alias.zone) !== parents.zone) continue;
+      if (normalizeName(alias.from) === wanted) candidates.push(normalizeName(alias.to));
+    }
+    if (level === "zone") candidates.push(...zoneSuffixCandidates(wanted));
+  }
+
+  let matched: MorLocationTuple[] = [];
+  for (const candidate of candidates) {
+    matched = rows.filter((row) => normalizeName(row[nameSlot] as string) === candidate);
+    if (matched.length > 0) break;
+  }
+
+  // A company record that already holds the MoR code itself resolves too — but only when that code
+  // genuinely exists at this level under this parent. An unvalidated numeric pass-through is how a
+  // wrong code reaches MoR without anything noticing.
+  if (matched.length === 0 && /^[0-9]{1,6}$/.test((raw ?? "").trim())) {
+    const asCode = Number((raw ?? "").trim());
+    matched = rows.filter((row) => row[noSlot] === asCode);
+  }
+
+  if (matched.length === 0) {
+    throw new MorGeoMappingError(
+      "EIMS_GEO_MAPPING_FAILED",
+      `EIMS geographic mapping failed: no MoR ${column} match for ${describe(input)}.`,
+    );
+  }
+
+  const distinct = [...new Set(matched.map((row) => row[noSlot] as number))];
+  if (distinct.length > 1) {
+    throw new MorGeoMappingError(
+      "EIMS_GEO_AMBIGUOUS",
+      `EIMS geographic mapping is ambiguous: MoR ${column} "${(raw ?? "").trim()}" matches ` +
+        `${distinct.length} different codes (${distinct.sort((a, b) => a - b).join(", ")}) for ` +
+        `${describe(input)}. Correct the company address or the MoR reference data; an ambiguous ` +
+        "location is never filed.",
+    );
+  }
+
+  return { no: distinct[0], rows: matched };
+}
+
+/**
+ * Resolves the full hierarchy, or throws a `BadRequestException` naming the level that failed.
+ *
+ * Never guesses and never returns a partial result: an unknown or ambiguous location must stop the
+ * filing here, locally, before any MoR request and before an EIMS counter is consumed.
+ */
+export function resolveMorGeo(
+  input: MorAddressInput,
+  rows: MorLocationTuple[] = MOR_LOCATIONS,
+): MorGeoCodes {
+  if (rows.length === 0) {
+    throw new MorGeoMappingError(
+      "EIMS_GEO_MAPPING_FAILED",
+      "EIMS geographic mapping failed: the MoR location master is empty. Generate it with " +
+        "`pnpm --filter @edr/freight-api eims:import-locations <workbook.xlsx>`.",
+    );
+  }
+
+  // `companies.country` defaults to 'Ethiopia' and is often left blank on older rows; blank means
+  // domestic here, exactly as the column default says. A *named* foreign country is resolved like
+  // any other and fails if MoR does not list it — it is never quietly filed as Ethiopia.
+  const country = (input.country ?? "").trim() || "Ethiopia";
+
+  const inCountry = matchLevel(rows, "country", country, {}, input);
+  const inRegion = matchLevel(inCountry.rows, "region", input.region, {}, input);
+  const regionScope = normalizeName(inRegion.rows[0][SLOTS.region.name] as string);
+  const inZone = matchLevel(inRegion.rows, "zone", input.zone, { region: regionScope }, input);
+  const zoneScope = normalizeName(inZone.rows[0][SLOTS.zone.name] as string);
+  const inWoreda = matchLevel(
+    inZone.rows,
+    "woreda",
+    input.woreda,
+    {
+      region: regionScope,
+      zone: zoneScope,
+    },
+    input,
+  );
+
+  return {
+    Country: String(inCountry.no),
+    Region: String(inRegion.no),
+    City: String(inZone.no),
+    Wereda: String(inWoreda.no),
+  };
+}
+
+/** Non-throwing variant for callers that already have a working fallback (the seller identity). */
+export function tryResolveMorGeo(
+  input: MorAddressInput,
+  rows: MorLocationTuple[] = MOR_LOCATIONS,
+): MorGeoCodes | null {
+  try {
+    return resolveMorGeo(input, rows);
+  } catch {
+    return null;
+  }
+}

apps/edr-freight-api/src/contracts/contract-document-view-model.builder.ts

@@ -122,6 +122,8 @@ export class ContractDocumentViewModelBuilder {
         contract.customsClearingEnabled,
         // Bulk templates are keyed by the contract's cargo type.
         (contract.cargoScope ?? []).find((c) => c.cargoTypeId)?.cargoTypeId,
+        // Ethiopian-customs-only service types resolve to the Ethiopian variant.
+        contract.serviceType?.includesEthiopianCustomsOnly,
       );
       dynamicTemplate = dynamicSource
         ? {

apps/edr-freight-api/src/contracts/contract-rate-schedule.builder.ts

@@ -67,6 +67,7 @@ const TRIGGER_ROUTE_LABELS: Partial<Record<Rate['trigger'], string>> = {
   DEMURRAGE: 'Demurrage / wagon detention',
   PIL_EXTRA_FEE: 'PIL shipping line extra fee',
   CUSTOMS_CLEARANCE: 'Customs clearance service',
+  ETHIOPIAN_CUSTOMS_CLEARANCE: 'Ethiopian customs clearance service',
   FUEL: 'Fuel surcharge',
 };
 

apps/edr-freight-api/src/migrations/3580000000000-EimsBulkRegistration.ts

@@ -0,0 +1,35 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Columns for `POST /v1/bulkRegister` — see `EimsBulkRegistrationService`.
+ *
+ * `eims_system_state.in_flight_conversation_id` is the bulk equivalent of `in_flight_invoice_id`:
+ * a whole batch, not one invoice, is what's outstanding while MoR processes it asynchronously.
+ * `invoices.eims_bulk_conversation_id` tags which batch an invoice was submitted in, so a stuck
+ * batch (webhook never arrived) can be found and reconciled by conversation id.
+ */
+export class EimsBulkRegistration3580000000000 implements MigrationInterface {
+  name = "EimsBulkRegistration3580000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.eims_system_state
+      ADD COLUMN IF NOT EXISTS in_flight_conversation_id text
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+      ADD COLUMN IF NOT EXISTS eims_bulk_conversation_id text
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.eims_system_state
+      DROP COLUMN IF EXISTS in_flight_conversation_id
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.invoices
+      DROP COLUMN IF EXISTS eims_bulk_conversation_id
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3580000000000-OperationsReporting.ts

@@ -0,0 +1,114 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Reference data for the operations reporting suite (turnaround, delay,
+ * trainset, TEU, cargo volume).
+ *
+ * Two new tables and two new columns:
+ *
+ * - `operations_standards` — single-row settings table, same shape as
+ *   `logo_settings` / `exchange_settings`. Holds the railway's standard times
+ *   and charged-tonnage factors. Editable in the backoffice because the
+ *   business calls the corridor standard "flexible".
+ * - `operations_targets` — the planned side of every "Plan / Operated /
+ *   Implement Rate" table in the spec. One row per period × metric ×
+ *   dimension value.
+ * - `yard_distances.standard_hours` — the per-corridor standard transit time
+ *   (Negad→GMP 21h, →Adama 20h, →Modjo 20.5h, →Sebeta 22h). Null falls back to
+ *   `operations_standards.default_leg_standard_hours`.
+ * - `cargo_types.full_trainset_wagons` — wagons in a full trainset of this
+ *   cargo (37 for vehicles, 22 for sand). Null falls back to
+ *   `operations_standards.default_full_trainset_wagons`.
+ *
+ * The seed row is inserted only when the table is empty, so re-running this
+ * never overwrites values an operator has since edited.
+ */
+export class OperationsReporting3580000000000 implements MigrationInterface {
+  name = "OperationsReporting3580000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.operations_standards (
+        id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        station_standard_hours_ethiopia numeric(6,2) NOT NULL DEFAULT 10,
+        station_standard_hours_djibouti numeric(6,2) NOT NULL DEFAULT 13,
+        cycle_standard_hours_container numeric(6,2) NOT NULL DEFAULT 65,
+        cycle_standard_hours_bulk_dmp numeric(6,2) NOT NULL DEFAULT 88,
+        cycle_standard_hours_bulk_nagad numeric(6,2) NOT NULL DEFAULT 96,
+        cycle_standard_hours_bulk_bcc numeric(6,2) NOT NULL DEFAULT 96,
+        default_leg_standard_hours numeric(6,2) NOT NULL DEFAULT 21,
+        delay_tolerance_minutes integer NOT NULL DEFAULT 30,
+        charged_tons_full_20ft numeric(8,2) NOT NULL DEFAULT 20,
+        charged_tons_full_40ft numeric(8,2) NOT NULL DEFAULT 40,
+        charged_tons_empty_20ft numeric(8,2) NOT NULL DEFAULT 2.24,
+        charged_tons_empty_40ft numeric(8,2) NOT NULL DEFAULT 3.88,
+        charged_tons_per_wagon_general numeric(8,2) NOT NULL DEFAULT 70,
+        charged_tons_per_wagon_perishable numeric(8,2) NOT NULL DEFAULT 38,
+        default_full_trainset_wagons integer NOT NULL DEFAULT 50,
+        updated_by_id uuid,
+        created_at timestamptz NOT NULL DEFAULT now(),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        deleted_at timestamptz
+      );
+    `);
+
+    // Column defaults carry every value — the seed only needs the row to exist.
+    await queryRunner.query(`
+      INSERT INTO freight.operations_standards (id)
+      SELECT gen_random_uuid()
+       WHERE NOT EXISTS (SELECT 1 FROM freight.operations_standards WHERE deleted_at IS NULL);
+    `);
+
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.operations_targets (
+        id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        period_type varchar(10) NOT NULL,
+        period_start date NOT NULL,
+        metric varchar(20) NOT NULL,
+        dimension varchar(20) NOT NULL,
+        dimension_key varchar(60) NOT NULL,
+        planned_value numeric(14,3) NOT NULL,
+        note text,
+        created_at timestamptz NOT NULL DEFAULT now(),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        deleted_at timestamptz
+      );
+    `);
+
+    // Partial unique index rather than a table constraint, so a soft-deleted
+    // target can be re-created — same choice as yard_distances.
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS ux_operations_targets_slot
+        ON freight.operations_targets (period_type, period_start, metric, dimension, dimension_key)
+        WHERE deleted_at IS NULL;
+    `);
+
+    // The reports look targets up by period and metric, never by id.
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_operations_targets_lookup
+        ON freight.operations_targets (metric, period_type, period_start)
+        WHERE deleted_at IS NULL;
+    `);
+
+    await queryRunner.query(`
+      ALTER TABLE freight.yard_distances
+        ADD COLUMN IF NOT EXISTS standard_hours numeric(6,2);
+    `);
+
+    await queryRunner.query(`
+      ALTER TABLE freight.cargo_types
+        ADD COLUMN IF NOT EXISTS full_trainset_wagons integer;
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE freight.cargo_types DROP COLUMN IF EXISTS full_trainset_wagons;`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE freight.yard_distances DROP COLUMN IF EXISTS standard_hours;`,
+    );
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.operations_targets;`);
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.operations_standards;`);
+  }
+}

apps/edr-freight-api/src/migrations/3590000000000-OperationsTargetCargoCategory.ts

@@ -0,0 +1,51 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * A station's plan is per station AND per cargo type, not per station.
+ *
+ * The OCC monthly report plans "Nagad–Mojo multimodal container 122,010 t" and
+ * "Nagad–Mojo fertilizer 18,000 t" as separate lines against the same station,
+ * which the single `dimension_key` column cannot express: a station-keyed target
+ * would apply the whole station's plan to each of its cargo types.
+ *
+ * `cargo_category` is nullable, so `cargo_category` and `container_class`
+ * targets are unaffected — they leave it null and stay keyed on
+ * `dimension_key` alone. The uniqueness index moves to include it, since
+ * (station, category) is now the slot.
+ */
+export class OperationsTargetCargoCategory3590000000000 implements MigrationInterface {
+  name = "OperationsTargetCargoCategory3590000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.operations_targets
+        ADD COLUMN IF NOT EXISTS cargo_category varchar(60);
+    `);
+
+    await queryRunner.query(`DROP INDEX IF EXISTS freight.ux_operations_targets_slot;`);
+
+    // COALESCE rather than a plain column list: a partial unique index treats
+    // NULLs as distinct, which would let the same category target be entered
+    // twice over.
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS ux_operations_targets_slot
+        ON freight.operations_targets (
+          period_type, period_start, metric, dimension, dimension_key,
+          COALESCE(cargo_category, '')
+        )
+        WHERE deleted_at IS NULL;
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP INDEX IF EXISTS freight.ux_operations_targets_slot;`);
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS ux_operations_targets_slot
+        ON freight.operations_targets (period_type, period_start, metric, dimension, dimension_key)
+        WHERE deleted_at IS NULL;
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.operations_targets DROP COLUMN IF EXISTS cargo_category;
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3600000000000-BookingClearanceEvent.ts

@@ -0,0 +1,37 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/** Per-booking clearance action history — drives the History tab. */
+export class BookingClearanceEvent3600000000000 implements MigrationInterface {
+  name = 'BookingClearanceEvent3600000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS "freight"."booking_clearance_event" (
+        "id" uuid NOT NULL DEFAULT uuid_generate_v4(),
+        "created_at" timestamptz NOT NULL DEFAULT now(),
+        "updated_at" timestamptz NOT NULL DEFAULT now(),
+        "deleted_at" timestamptz,
+        "booking_id" uuid NOT NULL,
+        "action" character varying(64) NOT NULL,
+        "label" character varying(500) NOT NULL,
+        "actor_type" character varying(16) NOT NULL DEFAULT 'STAFF',
+        "actor_id" uuid,
+        "actor_name" character varying(150),
+        "metadata" jsonb,
+        CONSTRAINT "pk_booking_clearance_event" PRIMARY KEY ("id"),
+        CONSTRAINT "fk_booking_clearance_event_booking" FOREIGN KEY ("booking_id")
+          REFERENCES "freight"."bookings"("id") ON DELETE CASCADE
+      )
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "idx_booking_clearance_event_booking_created"
+        ON "freight"."booking_clearance_event" ("booking_id", "created_at")
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `DROP TABLE IF EXISTS "freight"."booking_clearance_event"`,
+    );
+  }
+}

apps/edr-freight-api/src/migrations/3610000000000-MultipleMiscClearanceCharges.ts

@@ -0,0 +1,38 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Clearance charges are no longer one-of-each in a fixed order: GL Ethiopia
+ * may raise several MISCELLANEOUS charges, and either level may be created
+ * first. Port charges stay unique per booking (one port bill per shipment),
+ * enforced by a partial index instead of the old blanket (booking_id, type)
+ * uniqueness that also capped miscellaneous at one.
+ */
+export class MultipleMiscClearanceCharges3610000000000
+  implements MigrationInterface
+{
+  name = 'MultipleMiscClearanceCharges3610000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      DROP INDEX IF EXISTS "freight"."uq_booking_clearance_charge_booking_type"
+    `);
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS "uq_booking_clearance_charge_port"
+        ON "freight"."booking_clearance_charge" ("booking_id")
+        WHERE "type" = 'PORT_CHARGES' AND "deleted_at" IS NULL
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "idx_booking_clearance_charge_booking"
+        ON "freight"."booking_clearance_charge" ("booking_id")
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    // No-op on the uniqueness: restoring the blanket (booking_id, type) index
+    // would fail on any booking that has since raised a second miscellaneous
+    // charge, which is exactly what this migration set out to allow.
+    await queryRunner.query(`
+      DROP INDEX IF EXISTS "freight"."uq_booking_clearance_charge_port"
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3620000000000-AdditionalCharge.ts

@@ -0,0 +1,43 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/** Ad-hoc customer charges finance raises against a booking — Additional Payments tab. */
+export class AdditionalCharge3620000000000 implements MigrationInterface {
+  name = 'AdditionalCharge3620000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS "freight"."additional_charge" (
+        "id" uuid NOT NULL DEFAULT uuid_generate_v4(),
+        "created_at" timestamptz NOT NULL DEFAULT now(),
+        "updated_at" timestamptz NOT NULL DEFAULT now(),
+        "deleted_at" timestamptz,
+        "booking_id" uuid NOT NULL,
+        "reason" text NOT NULL,
+        "status" character varying(20) NOT NULL DEFAULT 'DRAFT',
+        "amount" numeric(14,2) NOT NULL,
+        "currency" character varying(8) NOT NULL,
+        "file_record_id" uuid,
+        "invoice_id" uuid,
+        "payment_reference" character varying(64),
+        "created_by_staff_id" uuid,
+        "sent_by_staff_id" uuid,
+        "sent_at" timestamptz,
+        "paid_at" timestamptz,
+        "cancelled_by_staff_id" uuid,
+        "cancelled_at" timestamptz,
+        "cancel_reason" text,
+        CONSTRAINT "pk_additional_charge" PRIMARY KEY ("id"),
+        CONSTRAINT "fk_additional_charge_booking" FOREIGN KEY ("booking_id")
+          REFERENCES "freight"."bookings"("id") ON DELETE CASCADE
+      )
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS "idx_additional_charge_booking"
+        ON "freight"."additional_charge" ("booking_id")
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS "freight"."additional_charge"`);
+  }
+}

apps/edr-freight-api/src/migrations/3620000000000-SchedulePlannedWagonYards.ts

@@ -0,0 +1,29 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Per-schedule wagon yard plan — where THIS departure expects each consist
+ * wagon to board, independent of where the wagon physically stands today.
+ *
+ * `wagons.current_yard_id` is one physical fact shared by every schedule of a
+ * built train, so a train standing in Mojo could not be sold from Dire for a
+ * departure next week. The plan is a sparse jsonb map `{ wagonId: yardId }`
+ * on the schedule: a wagon missing from the map boards from its physical yard.
+ * Booking capacity, fleet availability and wagon pinning all read the plan;
+ * dispatch refuses to leave until the plan and the physical yards agree.
+ */
+export class SchedulePlannedWagonYards3620000000000 implements MigrationInterface {
+  name = 'SchedulePlannedWagonYards3620000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.train_schedules
+        ADD COLUMN IF NOT EXISTS planned_wagon_yards jsonb
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.train_schedules DROP COLUMN IF EXISTS planned_wagon_yards
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3630000000000-ClearanceChargeCustomerDecision.ts

@@ -0,0 +1,49 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * The customer now approves a clearance charge before it becomes an invoice:
+ * GL describes the price, SENDs it, the customer ACCEPTs (invoice issued, charge
+ * locked) or REJECTs with a note (GL revises and re-sends). Charges that were
+ * already sent as invoices under the old flow are carried over as ACCEPTED so
+ * their invoices stay payable.
+ */
+export class ClearanceChargeCustomerDecision3630000000000
+  implements MigrationInterface
+{
+  name = 'ClearanceChargeCustomerDecision3630000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE "freight"."booking_clearance_charge"
+        ADD COLUMN IF NOT EXISTS "description" text,
+        ADD COLUMN IF NOT EXISTS "customer_note" text,
+        ADD COLUMN IF NOT EXISTS "customer_decided_at" timestamptz,
+        ADD COLUMN IF NOT EXISTS "customer_decided_by" uuid
+    `);
+    await queryRunner.query(`
+      UPDATE "freight"."booking_clearance_charge"
+         SET "status" = 'ACCEPTED'
+       WHERE "status" = 'SENT' AND "invoice_id" IS NOT NULL
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      UPDATE "freight"."booking_clearance_charge"
+         SET "status" = 'SENT'
+       WHERE "status" = 'ACCEPTED'
+    `);
+    await queryRunner.query(`
+      UPDATE "freight"."booking_clearance_charge"
+         SET "status" = 'BILLED'
+       WHERE "status" = 'REJECTED'
+    `);
+    await queryRunner.query(`
+      ALTER TABLE "freight"."booking_clearance_charge"
+        DROP COLUMN IF EXISTS "description",
+        DROP COLUMN IF EXISTS "customer_note",
+        DROP COLUMN IF EXISTS "customer_decided_at",
+        DROP COLUMN IF EXISTS "customer_decided_by"
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3640000000000-EthiopianCustomsClearance.ts

@@ -0,0 +1,69 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Ethiopian-side-only customs clearance:
+ *
+ * - service_types.includes_ethiopian_customs_only marks a customs service that
+ *   EDR clears on the Ethiopian side only. Same clearance flow; only the fee
+ *   differs — pricing looks up the ETHIOPIAN_CUSTOMS_CLEARANCE rate instead of
+ *   CUSTOMS_CLEARANCE.
+ * - rates.trigger widens to 30 chars to fit the new trigger value.
+ * - CK_rates_yard_scope gains ETHIOPIAN_CUSTOMS_CLEARANCE in its yard-carrying
+ *   branch: it is priced per origin → destination leg like customs clearance.
+ */
+export class EthiopianCustomsClearance3640000000000 implements MigrationInterface {
+  name = 'EthiopianCustomsClearance3640000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.service_types
+        ADD COLUMN IF NOT EXISTS includes_ethiopian_customs_only boolean NOT NULL DEFAULT false
+    `);
+
+    await queryRunner.query(
+      `ALTER TABLE freight.rates ALTER COLUMN trigger TYPE varchar(30)`,
+    );
+
+    await queryRunner.query(
+      `ALTER TABLE freight.rates DROP CONSTRAINT IF EXISTS "CK_rates_yard_scope"`,
+    );
+    await queryRunner.query(`
+      ALTER TABLE freight.rates ADD CONSTRAINT "CK_rates_yard_scope" CHECK (
+        deleted_at IS NOT NULL OR status = 'SUPERSEDED' OR
+        CASE
+          WHEN (trigger = 'ALWAYS' AND applies_to IN ('BULK', 'CONTAINER', 'INTERCITY'))
+            OR trigger IN ('CUSTOMS_CLEARANCE', 'ETHIOPIAN_CUSTOMS_CLEARANCE', 'WITH_RETURN', 'FUEL')
+          THEN origin_yard_id IS NOT NULL AND destination_yard_id IS NOT NULL
+          ELSE origin_yard_id IS NULL AND destination_yard_id IS NULL
+        END
+      )
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE freight.rates DROP CONSTRAINT IF EXISTS "CK_rates_yard_scope"`,
+    );
+    await queryRunner.query(`
+      ALTER TABLE freight.rates ADD CONSTRAINT "CK_rates_yard_scope" CHECK (
+        deleted_at IS NOT NULL OR status = 'SUPERSEDED' OR
+        CASE
+          WHEN (trigger = 'ALWAYS' AND applies_to IN ('BULK', 'CONTAINER', 'INTERCITY'))
+            OR trigger IN ('CUSTOMS_CLEARANCE', 'WITH_RETURN', 'FUEL')
+          THEN origin_yard_id IS NOT NULL AND destination_yard_id IS NOT NULL
+          ELSE origin_yard_id IS NULL AND destination_yard_id IS NULL
+        END
+      )
+    `);
+    // Rows on the new trigger would not fit varchar(20) — drop them first.
+    await queryRunner.query(
+      `DELETE FROM freight.rates WHERE trigger = 'ETHIOPIAN_CUSTOMS_CLEARANCE'`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE freight.rates ALTER COLUMN trigger TYPE varchar(20)`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE freight.service_types DROP COLUMN IF EXISTS includes_ethiopian_customs_only`,
+    );
+  }
+}

apps/edr-freight-api/src/migrations/3650000000000-AdditionalChargeDueAt.ts

@@ -0,0 +1,19 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/** Optional payment due date finance can set on an additional charge. */
+export class AdditionalChargeDueAt3650000000000 implements MigrationInterface {
+  name = 'AdditionalChargeDueAt3650000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE "freight"."additional_charge"
+      ADD COLUMN IF NOT EXISTS "due_at" timestamptz
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE "freight"."additional_charge" DROP COLUMN IF EXISTS "due_at"
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3650000000000-SchedulePlannedWagonCutYards.ts

@@ -0,0 +1,29 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Per-schedule wagon CUT plan — the mid-route stop where THIS departure
+ * detaches each consist wagon and leaves it behind (10 wagons cut at Mojo,
+ * the rest ride to Djibouti).
+ *
+ * Sparse jsonb map `{ wagonId: yardId }` on the schedule: a wagon missing
+ * from the map rides to the schedule destination — exactly today's behavior,
+ * so no backfill. The cut is a cap, not a promise: cargo may still alight
+ * earlier, but never past the cut. Booking capacity debits every edge at or
+ * after the cut; checkpoint logging settles the wagon there physically.
+ */
+export class SchedulePlannedWagonCutYards3650000000000 implements MigrationInterface {
+  name = 'SchedulePlannedWagonCutYards3650000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.train_schedules
+        ADD COLUMN IF NOT EXISTS planned_wagon_cut_yards jsonb
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.train_schedules DROP COLUMN IF EXISTS planned_wagon_cut_yards
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3660000000000-SchedulePlannedWagonCouples.ts

@@ -0,0 +1,37 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Per-schedule consist-change plan, executed automatically as the trip
+ * proceeds (dispatch / checkpoint logs):
+ *
+ * - `planned_wagon_couples` `{ wagonId: pickupYardId }` — LOOSE wagons this
+ *   departure couples onto the train at a route stop. They join the built
+ *   train permanently when the train reaches that stop.
+ * - `planned_wagon_real_cuts` `[wagonId, ...]` — cut wagons (see
+ *   planned_wagon_cut_yards) flagged as REAL cuts: the built train
+ *   permanently loses the wagon at its cut yard, instead of the default
+ *   soft cut where it stays in the build and only sits out this trip.
+ */
+export class SchedulePlannedWagonCouples3660000000000 implements MigrationInterface {
+  name = 'SchedulePlannedWagonCouples3660000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.train_schedules
+        ADD COLUMN IF NOT EXISTS planned_wagon_couples jsonb
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.train_schedules
+        ADD COLUMN IF NOT EXISTS planned_wagon_real_cuts jsonb
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.train_schedules DROP COLUMN IF EXISTS planned_wagon_couples
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.train_schedules DROP COLUMN IF EXISTS planned_wagon_real_cuts
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3670000000000-AdjustmentLogNullableSchedule.ts

@@ -0,0 +1,24 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * A consist adjustment made from the TRAIN BUILDER on a train with no live
+ * schedule still belongs in the wagon adjustment history — it just has no
+ * schedule to point at. Relax the NOT NULL so builder detaches/attaches can
+ * be recorded; every existing reader filters BY train_schedule_id or
+ * train_id, so nullable rows are invisible to them.
+ */
+export class AdjustmentLogNullableSchedule3670000000000 implements MigrationInterface {
+  name = 'AdjustmentLogNullableSchedule3670000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.schedule_wagon_adjustment_logs
+        ALTER COLUMN train_schedule_id DROP NOT NULL
+    `);
+  }
+
+  public async down(_queryRunner: QueryRunner): Promise<void> {
+    // No-op: restoring NOT NULL would fail on any builder-origin rows written
+    // while this migration was live, re-introducing the outage it fixed.
+  }
+}

apps/edr-freight-api/src/migrations/3680000000000-WagonAllocationSlotIndex.ts

@@ -0,0 +1,24 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Every slot → allocations lookup (allocator, journey load/unload, settle,
+ * per-leg weight guard) filters wagon_booking_allocations by
+ * train_set_wagon_id, which had no index — only booking_id and the pkey.
+ * Sequential scans grow with every allocation ever written.
+ */
+export class WagonAllocationSlotIndex3680000000000 implements MigrationInterface {
+  name = 'WagonAllocationSlotIndex3680000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_wagon_booking_allocations_slot
+        ON freight.wagon_booking_allocations (train_set_wagon_id)
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      DROP INDEX IF EXISTS freight.idx_wagon_booking_allocations_slot
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3690000000000-AuditLogReference.ts

@@ -0,0 +1,45 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Adds `reference` to freight.audit_logs — the human identifier of the entity
+ * the action touched (booking reference, schedule number, train number, …),
+ * resolved at write time by the audit interceptor. `resource_id` stays the
+ * machine id; this column is what staff actually type into the search box.
+ *
+ * Production safety:
+ *  - `ADD COLUMN ... NOT NULL DEFAULT ''` is metadata-only on Postgres 11+:
+ *    no table rewrite, no long lock, existing rows read '' without being
+ *    touched. Rows written before this migration keep '' permanently —
+ *    capture starts from deploy, by design (no backfill).
+ *  - Everything is IF NOT EXISTS so a hand-patched database converges
+ *    instead of failing the deploy.
+ *  - No existing column is altered and nothing is dropped: zero data-loss
+ *    surface.
+ *
+ * The index is an expression index on upper(reference) with
+ * text_pattern_ops so the search endpoint's case-insensitive prefix match
+ * (`upper(reference) LIKE upper($1) || '%'`) is indexed. '' rows are
+ * excluded to keep it small — they are never searched for.
+ */
+export class AuditLogReference3690000000000 implements MigrationInterface {
+  name = 'AuditLogReference3690000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.audit_logs
+        ADD COLUMN IF NOT EXISTS reference varchar(64) NOT NULL DEFAULT ''
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_audit_logs_reference_upper
+        ON freight.audit_logs (upper(reference) text_pattern_ops)
+        WHERE reference <> ''
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    // Down discards every captured reference — acceptable only because down
+    // migrations are never run against production here.
+    await queryRunner.query(`DROP INDEX IF EXISTS freight.idx_audit_logs_reference_upper`);
+    await queryRunner.query(`ALTER TABLE freight.audit_logs DROP COLUMN IF EXISTS reference`);
+  }
+}

apps/edr-freight-api/src/migrations/3690000000000-CheckpointHandlingTimes.ts

@@ -0,0 +1,41 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Loading and unloading times, on the stop that already records the train
+ * standing at a station.
+ *
+ * The OCC report publishes, per train, "total loading and unloading time" and
+ * the "other activity" left over from the station stay. Nothing recorded when
+ * handling started or ended — the July 2026 seed had to write the figure into
+ * a checkpoint's note — so the staying-time report could only ever publish the
+ * whole stay.
+ *
+ * These four go on `train_checkpoint_events` rather than a table of their own:
+ * a stop is already one row there, keyed (schedule, sequence_no), and the
+ * arrival row is the one the staying-time report builds a stay from. All four
+ * are nullable — a stop where nobody logged the handling still reports its
+ * staying time, with the handling columns empty rather than zero.
+ */
+export class CheckpointHandlingTimes3690000000000 implements MigrationInterface {
+  name = "CheckpointHandlingTimes3690000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.train_checkpoint_events
+        ADD COLUMN IF NOT EXISTS unloading_started_at timestamptz,
+        ADD COLUMN IF NOT EXISTS unloading_completed_at timestamptz,
+        ADD COLUMN IF NOT EXISTS loading_started_at timestamptz,
+        ADD COLUMN IF NOT EXISTS loading_completed_at timestamptz;
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.train_checkpoint_events
+        DROP COLUMN IF EXISTS unloading_started_at,
+        DROP COLUMN IF EXISTS unloading_completed_at,
+        DROP COLUMN IF EXISTS loading_started_at,
+        DROP COLUMN IF EXISTS loading_completed_at;
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3700000000000-HandlingStandards.ts

@@ -0,0 +1,31 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Standard loading-and-unloading time, so the handling figure can be reported
+ * the way the OCC scorecard reports it — hours against a target, with a rate.
+ *
+ * Nullable with NO default, unlike every other column in this table. The
+ * reporting spec publishes standards for a station stay (10h / 13h) and for a
+ * turn-around cycle (65 / 88 / 96) but none for handling, so there is no
+ * honest figure to seed. Until a planner enters one in Operating standards the
+ * rate reads empty rather than judging trains against an invented number.
+ */
+export class HandlingStandards3700000000000 implements MigrationInterface {
+  name = "HandlingStandards3700000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.operations_standards
+        ADD COLUMN IF NOT EXISTS handling_standard_hours_container numeric(6,2),
+        ADD COLUMN IF NOT EXISTS handling_standard_hours_bulk numeric(6,2);
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.operations_standards
+        DROP COLUMN IF EXISTS handling_standard_hours_container,
+        DROP COLUMN IF EXISTS handling_standard_hours_bulk;
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3710000000000-BookingClearingAgentContact.ts

@@ -0,0 +1,30 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Adds the customs clearing agent's contact details to freight.bookings.
+ *
+ * The agent moved from the contract to the booking: on a without-customs
+ * service the customer now names their agent (name, email, phone) when
+ * completing each booking, instead of once at contract creation. The existing
+ * `customs_clearing_agent` column keeps the name; these two columns add the
+ * contact info. Nullable — customs-bundled and legacy bookings have none.
+ */
+export class BookingClearingAgentContact3710000000000 implements MigrationInterface {
+  name = 'BookingClearingAgentContact3710000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings
+        ADD COLUMN IF NOT EXISTS customs_clearing_agent_email varchar(200),
+        ADD COLUMN IF NOT EXISTS customs_clearing_agent_phone varchar(50)
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings
+        DROP COLUMN IF EXISTS customs_clearing_agent_email,
+        DROP COLUMN IF EXISTS customs_clearing_agent_phone
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3720000000000-ScheduleStationWorkLogs.ts

@@ -0,0 +1,24 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Per-station loading/unloading time windows on a schedule, operator-clicked:
+ * { [yardId]: { loading?: { startedAt, endedAt, startedByUserId, endedByUserId },
+ *               unloading?: { same } } }
+ * Booking load/unload is gated on the matching window having been started.
+ */
+export class ScheduleStationWorkLogs3720000000000 implements MigrationInterface {
+  name = 'ScheduleStationWorkLogs3720000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.train_schedules
+        ADD COLUMN IF NOT EXISTS station_work_logs jsonb
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.train_schedules DROP COLUMN IF EXISTS station_work_logs
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3730000000000-WagonDetachRequests.ts

@@ -0,0 +1,74 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Approval gate for detaching a wagon (or sending it to maintenance) from a
+ * train whose run is already SCHEDULED.
+ *
+ * Before scheduling, the consist is the builder's to edit. After scheduling,
+ * pulling a wagon changes a departure customers booked against, so it becomes
+ * a two-person action: one staffer files a request with a reason, another
+ * staffer (with trains:approve_wagon_detach) approves it — approval executes
+ * the detach on the spot. Rows are never deleted; decided rows are the audit
+ * trail of who asked, who decided, and why.
+ *
+ * One PENDING row per (train, wagon) at a time — a second request while one is
+ * undecided is a coordination failure, not a workflow (partial unique index).
+ */
+export class WagonDetachRequests3730000000000 implements MigrationInterface {
+  name = 'WagonDetachRequests3730000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      DO $$ BEGIN
+        CREATE TYPE freight.wagon_detach_requests_status_enum
+          AS ENUM ('PENDING', 'APPROVED', 'REJECTED');
+      EXCEPTION WHEN duplicate_object THEN NULL; END $$
+    `);
+
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.wagon_detach_requests (
+        id uuid PRIMARY KEY DEFAULT uuid_generate_v4(),
+        train_id uuid NOT NULL REFERENCES freight.trains (id),
+        wagon_id uuid NOT NULL REFERENCES freight.wagons (id),
+        -- Snapshot: the audit trail must still read correctly after the wagon
+        -- is renumbered or deleted.
+        wagon_number varchar(50) NOT NULL,
+        action varchar(20) NOT NULL,
+        reason varchar(500) NOT NULL,
+        status freight.wagon_detach_requests_status_enum NOT NULL DEFAULT 'PENDING',
+        -- Who asked and who decided. Both recorded: the point of the gate is
+        -- that they are different people.
+        requested_by uuid,
+        decided_by uuid,
+        decided_at timestamptz,
+        decision_note varchar(500),
+        created_at timestamptz NOT NULL DEFAULT now(),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        deleted_at timestamptz
+      )
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_wagon_detach_requests_train
+        ON freight.wagon_detach_requests (train_id)
+    `);
+
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_wagon_detach_requests_train_status
+        ON freight.wagon_detach_requests (train_id, status)
+    `);
+
+    // The workflow invariant, enforced where it cannot race: at most one
+    // undecided request per wagon per train.
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS uq_wagon_detach_requests_one_pending
+        ON freight.wagon_detach_requests (train_id, wagon_id)
+        WHERE status = 'PENDING' AND deleted_at IS NULL
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`DROP TABLE IF EXISTS freight.wagon_detach_requests`);
+    await queryRunner.query(`DROP TYPE IF EXISTS freight.wagon_detach_requests_status_enum`);
+  }
+}

apps/edr-freight-api/src/migrations/3740000000000-BookingBulkRequestedWagons.ts

@@ -0,0 +1,27 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * NUMBER_OF_WAGONS cargo unit: the customer books a wagon COUNT alongside the
+ * bulk weight. `bulk_requested_wagons` drives allocation and PER_WAGON pricing;
+ * `bulk_item_count` is the optional informational item count entered with it.
+ * Nullable — every other cargo unit leaves both empty.
+ */
+export class BookingBulkRequestedWagons3740000000000 implements MigrationInterface {
+  name = 'BookingBulkRequestedWagons3740000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings
+        ADD COLUMN IF NOT EXISTS bulk_requested_wagons int,
+        ADD COLUMN IF NOT EXISTS bulk_item_count int
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.bookings
+        DROP COLUMN IF EXISTS bulk_requested_wagons,
+        DROP COLUMN IF EXISTS bulk_item_count
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3750000000000-EthiopianCustomsContractTemplates.ts

@@ -0,0 +1,118 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+import { CONTRACT_TEMPLATE_DEFAULTS } from '../seed/data/contract-template-defaults';
+
+/**
+ * Third customs-clearing option on contract templates: Ethiopian-customs-only
+ * (the Service Provider clears the Ethiopian side only, Djibouti stays with
+ * the Client), matching service types with includes_ethiopian_customs_only.
+ *
+ * - ethiopian_customs_only column on contract_templates (bulk variant flag;
+ *   the seeded container variants carry it in the code suffix instead, like
+ *   the existing _CUSTOMS/_NO_CUSTOMS pair).
+ * - The bulk unique index and intercity check widen to the new flag.
+ * - Seeds the two new system container templates from the defaults pack.
+ */
+const SEEDED_CODES = [
+  'IMPORT_CONTAINER_ETHIOPIAN_CUSTOMS',
+  'EXPORT_CONTAINER_ETHIOPIAN_CUSTOMS',
+] as const;
+
+export class EthiopianCustomsContractTemplates3750000000000 implements MigrationInterface {
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.contract_templates
+        ADD COLUMN IF NOT EXISTS ethiopian_customs_only boolean
+    `);
+
+    await queryRunner.query(
+      `DROP INDEX IF EXISTS freight.uq_contract_templates_cargo_dir_customs`,
+    );
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS uq_contract_templates_cargo_dir_customs
+        ON freight.contract_templates
+           (cargo_type_id, trade_direction,
+            COALESCE(with_customs, false), COALESCE(ethiopian_customs_only, false))
+        WHERE deleted_at IS NULL AND cargo_type_id IS NOT NULL
+    `);
+
+    await queryRunner.query(`
+      ALTER TABLE freight.contract_templates
+        DROP CONSTRAINT IF EXISTS ck_bulk_intercity_no_customs
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.contract_templates
+        ADD CONSTRAINT ck_bulk_intercity_no_customs CHECK (
+          cargo_type_id IS NULL
+          OR (
+            trade_direction IN ('IMPORT', 'EXPORT', 'INTERCITY')
+            AND (trade_direction = 'INTERCITY') = (with_customs IS NULL)
+            AND (ethiopian_customs_only IS NOT TRUE OR with_customs IS TRUE)
+          )
+        )
+    `);
+
+    for (const code of SEEDED_CODES) {
+      const seed = CONTRACT_TEMPLATE_DEFAULTS.find((t) => t.code === code);
+      if (!seed) throw new Error(`Missing contract template default for ${code}`);
+      await queryRunner.query(
+        `INSERT INTO freight.contract_templates
+           (id, code, name, description, document_title, whereas_clauses, articles,
+            is_active, is_system, created_at, updated_at)
+         SELECT gen_random_uuid(), $1::varchar, $2, $3, $4, $5::jsonb, $6::jsonb,
+                true, true, now(), now()
+         WHERE NOT EXISTS (
+           SELECT 1 FROM freight.contract_templates
+           WHERE code = $1::varchar AND deleted_at IS NULL
+         )`,
+        [
+          seed.code,
+          seed.name,
+          seed.description,
+          seed.documentTitle,
+          JSON.stringify(seed.whereasClauses),
+          JSON.stringify(
+            seed.articles.map((article, index) => ({ ...article, order: index + 1 })),
+          ),
+        ],
+      );
+    }
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `DELETE FROM freight.contract_templates WHERE code = ANY($1) AND is_system = true`,
+      [[...SEEDED_CODES]],
+    );
+
+    await queryRunner.query(`
+      ALTER TABLE freight.contract_templates
+        DROP CONSTRAINT IF EXISTS ck_bulk_intercity_no_customs
+    `);
+    await queryRunner.query(`
+      ALTER TABLE freight.contract_templates
+        ADD CONSTRAINT ck_bulk_intercity_no_customs CHECK (
+          cargo_type_id IS NULL
+          OR (
+            trade_direction IN ('IMPORT', 'EXPORT', 'INTERCITY')
+            AND (trade_direction = 'INTERCITY') = (with_customs IS NULL)
+          )
+        )
+    `);
+
+    await queryRunner.query(
+      `DROP INDEX IF EXISTS freight.uq_contract_templates_cargo_dir_customs`,
+    );
+    await queryRunner.query(`
+      CREATE UNIQUE INDEX IF NOT EXISTS uq_contract_templates_cargo_dir_customs
+        ON freight.contract_templates
+           (cargo_type_id, trade_direction, COALESCE(with_customs, false))
+        WHERE deleted_at IS NULL AND cargo_type_id IS NOT NULL
+    `);
+
+    await queryRunner.query(`
+      ALTER TABLE freight.contract_templates
+        DROP COLUMN IF EXISTS ethiopian_customs_only
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3760000000000-CompanyProfileEtradeBusiness.ts

@@ -0,0 +1,36 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Attaches an eTrade business licence to each operational profile.
+ *
+ * A TIN routinely holds a dozen or more licences, split by activity ("Export
+ * trade in coffee", "Freight Forwarders"), and until now the company picked one
+ * for the whole record — every role shared it. Each profile now names the
+ * business it actually operates as.
+ *
+ * Stored as a snapshot ({@link ETradeBusinessOption}: licenceNumber, tradeName,
+ * activity, renewedTo) rather than a bare licence number, so the portal and the
+ * backoffice can show which business is attached without an eTrade round-trip —
+ * eTrade is slow, serves a broken TLS chain, and is regularly down.
+ *
+ * Nullable: existing profiles have none until the customer attaches one, and a
+ * co-operative or investor-licence company has no eTrade record at all.
+ * Deliberately NOT unique — one business can back several profiles.
+ */
+export class CompanyProfileEtradeBusiness3760000000000 implements MigrationInterface {
+  name = 'CompanyProfileEtradeBusiness3760000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.company_profiles
+        ADD COLUMN IF NOT EXISTS etrade_business jsonb
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.company_profiles
+        DROP COLUMN IF EXISTS etrade_business
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3760000000000-PerWagonLoading.ts

@@ -0,0 +1,65 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Per-wagon loading. Staff may confirm loading wagon-by-wagon instead of the
+ * whole booking at once:
+ *  - bookings.loading_started_at — first wagon loaded; the booking stays PAID
+ *    until every remaining wagon is LOADED (remaining = allocated − cancelled).
+ *    Also shields a mid-load booking from the dispatch "left behind" unassign.
+ *  - wagon_booking_allocations.loaded_at / loaded_by_user_id — per-wagon
+ *    confirmation audit.
+ *  - booking_wagon_cancellations.fault — who caused an at-loading cancel of
+ *    the never-loaded remainder: CUSTOMER (fee applies) or EDR (no fee, credit
+ *    rebookable in full).
+ */
+export class PerWagonLoading3760000000000 implements MigrationInterface {
+  name = 'PerWagonLoading3760000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE freight.bookings
+         ADD COLUMN IF NOT EXISTS loading_started_at timestamptz`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE freight.wagon_booking_allocations
+         ADD COLUMN IF NOT EXISTS loaded_at timestamptz`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE freight.wagon_booking_allocations
+         ADD COLUMN IF NOT EXISTS loaded_by_user_id uuid`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE freight.wagon_booking_allocations
+         ADD COLUMN IF NOT EXISTS unloaded_at timestamptz`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE freight.wagon_booking_allocations
+         ADD COLUMN IF NOT EXISTS unloaded_by_user_id uuid`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE freight.booking_wagon_cancellations
+         ADD COLUMN IF NOT EXISTS fault varchar(16)`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE freight.booking_wagon_cancellations DROP COLUMN IF EXISTS fault`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE freight.wagon_booking_allocations DROP COLUMN IF EXISTS loaded_by_user_id`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE freight.wagon_booking_allocations DROP COLUMN IF EXISTS unloaded_by_user_id`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE freight.wagon_booking_allocations DROP COLUMN IF EXISTS unloaded_at`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE freight.wagon_booking_allocations DROP COLUMN IF EXISTS loaded_at`,
+    );
+    await queryRunner.query(
+      `ALTER TABLE freight.bookings DROP COLUMN IF EXISTS loading_started_at`,
+    );
+  }
+}

apps/edr-freight-api/src/migrations/3770000000000-WagonAdjustmentReason.ts

@@ -0,0 +1,27 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Why a wagon left (or joined) the consist, on the adjustment log itself.
+ *
+ * SCHEDULED-run detach / send-to-maintenance now requires a reason instead of
+ * a second staffer's approval, so the reason has to read back where the change
+ * reads back: the train-builder History tab. Nullable — every other writer
+ * (trip cuts, couples, arrival returns) keeps logging without one.
+ */
+export class WagonAdjustmentReason3770000000000 implements MigrationInterface {
+  name = 'WagonAdjustmentReason3770000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE freight.schedule_wagon_adjustment_logs
+         ADD COLUMN IF NOT EXISTS reason varchar(500)`,
+    );
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `ALTER TABLE freight.schedule_wagon_adjustment_logs
+         DROP COLUMN IF EXISTS reason`,
+    );
+  }
+}

apps/edr-freight-api/src/migrations/3780000000000-ScheduleCancellationReason.ts

@@ -0,0 +1,28 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Why a train schedule was cancelled, captured at cancel time. Staff pick a
+ * reason in the cancel dialog and every view of the cancelled schedule reads it
+ * back — a cancelled train on the board used to say nothing about why it died.
+ */
+export class ScheduleCancellationReason3780000000000 implements MigrationInterface {
+  name = 'ScheduleCancellationReason3780000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE "freight"."train_schedules"
+        ADD COLUMN IF NOT EXISTS "cancellation_reason" varchar(500),
+        ADD COLUMN IF NOT EXISTS "cancelled_at" timestamptz,
+        ADD COLUMN IF NOT EXISTS "cancelled_by_user_id" uuid
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE "freight"."train_schedules"
+        DROP COLUMN IF EXISTS "cancellation_reason",
+        DROP COLUMN IF EXISTS "cancelled_at",
+        DROP COLUMN IF EXISTS "cancelled_by_user_id"
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/3790000000000-EmptyContainerReturnCompanyName.ts

@@ -0,0 +1,24 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Empties backfilled into the yard belong to a company that may not be a
+ * registered customer yet, so `customer_id` cannot hold it. `company_name` is
+ * the typed fallback, and the display label when the customer IS registered.
+ */
+export class EmptyContainerReturnCompanyName3790000000000 implements MigrationInterface {
+  name = 'EmptyContainerReturnCompanyName3790000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.empty_container_returns
+        ADD COLUMN IF NOT EXISTS company_name varchar(200)
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.empty_container_returns
+        DROP COLUMN IF EXISTS company_name
+    `);
+  }
+}

apps/edr-freight-api/src/modules/audit/audit-endpoints.ts

@@ -12,7 +12,7 @@
  * humanized handler name where a route has none.
  *
  * Excludes the AI Assist and Account entities.
- * Generated from the controllers under src/ — 517 endpoints.
+ * Generated from the controllers under src/ — 528 endpoints.
  */
 /** [title, method, entity] for one auditable route. */
 export type AuditEndpointMeta = readonly [title: string, method: string, entity: string];
@@ -38,6 +38,7 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/bookings/:id/clearance/draft-declaration": ["GL ET sends a draft customs declaration (multi-file) with an estimated price for the customer to review", "POST", "Booking"],
   "POST /api/bookings/:id/clearance/draft-declaration/accept": ["Customer accepts the draft customs declaration — unlocks the real customs declaration step for GL Ethiopia", "POST", "Booking"],
   "POST /api/bookings/:id/clearance/draft-declaration/change": ["Customer requests a change to the draft customs declaration with a reason — GL Ethiopia sends a corrected draft (repeatable)", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/draft-declaration/skip": ["GL ET skips the draft-declaration round: no estimate is sent to the customer, the real declaration is filed directly and duty & tax passes by default", "POST", "Booking"],
   "POST /api/bookings/:id/clearance/duty": ["GL ET sets duty/tax on booking with notice attachment", "POST", "Booking"],
   "POST /api/bookings/:id/clearance/duty-slip": ["Customer uploads duty/tax payment slip on booking", "POST", "Booking"],
   "POST /api/bookings/:id/clearance/export-release": ["Confirm Booking Export Release", "POST", "Booking"],
@@ -47,6 +48,16 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/bookings/:id/clearance/proceed": ["Customer requests operation with a schedule day", "POST", "Booking"],
   "POST /api/bookings/:id/clearance/release-order": ["Upload Booking Release Order", "POST", "Booking"],
   "POST /api/bookings/:id/clearance/review": ["GL reviews a clearance document (Approve | Query)", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/doc-requests": ["GL asks the customer for additional clearance documents", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/charges/port-document": ["GL Djibouti uploads the port-charges document", "POST", "Booking"],
+  "PATCH /api/bookings/:id/clearance/charges/:chargeId/bill": ["GL Ethiopia sets or revises a clearance charge's amount + currency", "PATCH", "Booking"],
+  "POST /api/bookings/:id/clearance/charges/:chargeId/send": ["GL Ethiopia issues the clearance charge invoice to the customer", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/charges/:chargeId/accept": ["Customer accepts a proposed clearance charge — issues the payable invoice and locks the charge", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/charges/:chargeId/reject": ["Customer rejects a proposed clearance charge with a reason — GL Ethiopia revises and re-sends", "POST", "Booking"],
+  "POST /api/bookings/:id/clearance/charges/miscellaneous": ["GL Ethiopia creates the miscellaneous clearance charge", "POST", "Booking"],
+  "POST /api/bookings/:id/additional-charges": ["Finance raises a new additional charge — draft, or send to the customer immediately", "POST", "Booking"],
+  "POST /api/bookings/:id/additional-charges/:chargeId/send": ["Issue the draft charge's payable invoice and notify the customer", "POST", "Booking"],
+  "POST /api/bookings/:id/additional-charges/:chargeId/cancel": ["Withdraw a draft or unpaid additional charge", "POST", "Booking"],
   "POST /api/bookings/:id/clearance/ro-amendment": ["Request Booking RO Amendment", "POST", "Booking"],
   "POST /api/bookings/:id/clearance/transit-assignee/assign": ["GL Djibouti picks the transit officer from the roster — unblocks the customs declaration; calling again reassigns", "POST", "Booking"],
   "POST /api/bookings/:id/clearance/transit-assignee/request": ["GL ET asks GL Djibouti to name the transit officer — required before the import customs declaration", "POST", "Booking"],
@@ -68,7 +79,7 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/bookings/:id/documents": ["Upload documents for a booking (DRAFT only)", "POST", "Booking"],
   "PATCH /api/bookings/:id/export-handover-mode": ["Export only: choose direct truck-to-train (no warehouse, no GRN) or warehouse first", "PATCH", "Booking"],
   "POST /api/bookings/:id/generate-grn": ["Generate a GRN over the received containers (all received, or a subset) — one GRN per batch", "POST", "Booking"],
-  "POST /api/bookings/:id/generate-price": ["Generate price preview (DRAFT or CHANGES_REQUESTED)", "POST", "Booking"],
+  // "POST /api/bookings/:id/generate-price": ["Generate price preview (DRAFT or CHANGES_REQUESTED)", "POST", "Booking"],
   "POST /api/bookings/:id/government-expedite": ["Expedite government booking to PAID / ELIGIBLE for scheduling", "POST", "Booking"],
   "POST /api/bookings/:id/marketing/approve": ["Staff contract signature and fully execute (use contract/sign STAFF preferred)", "POST", "Booking"],
   "POST /api/bookings/:id/operation/review": ["Operations reviews an operation request: ACCEPT (→ batch pool),", "POST", "Booking"],
@@ -80,7 +91,7 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/bookings/:id/staff/request-changes": ["Staff return booking for customer updates", "POST", "Booking"],
   "POST /api/bookings/:id/submit": ["Customer submit booking", "POST", "Booking"],
   "POST /api/bookings/:id/wagon-cancellations": ["Request a partial wagon cancellation on a PAID booking — opens the cancellation-fee invoice; wagons are released only once the fee settles", "POST", "Booking"],
-  "POST /api/bookings/:id/wagon-cancellations/preview": ["Preview the fee/credit of a partial wagon cancellation (no writes)", "POST", "Booking"],
+  // "POST /api/bookings/:id/wagon-cancellations/preview": ["Preview the fee/credit of a partial wagon cancellation (no writes)", "POST", "Booking"],
   "POST /api/bookings/wagon-cancellations/:cancellationId/rebook": ["Rebook a wagon-cancellation credit: pick a shipment day only — the new booking is created under the contract and marked PAID (freight already paid; contract must still be valid)", "POST", "Booking"],
   "POST /api/bookings/wagon-cancellations/:cancellationId/withdraw": ["Withdraw a fee-pending wagon cancellation (owner, or staff with the void permission)", "POST", "Booking"],
   "POST /api/bookings/consolidation-approvals/:approvalId/approve": ["Approve a shared wagon: both bookings leave the gate and continue to Operations together.", "POST", "Booking"],
@@ -202,7 +213,7 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/contracts/:id/staff/request-changes": ["Staff return contract for customer updates", "POST", "Contract"],
   "POST /api/contracts/:id/submit": ["Customer submit contract (freezes contract_rate_snapshots)", "POST", "Contract"],
   "POST /api/contracts/:id/suspend": ["Staff freeze a signed contract (reversible, any post-signature step)", "POST", "Contract"],
-  "POST /api/contracts/:id/validate-shipment": ["Pre-create validation + authoritative price preview: full booking price breakdown (rail, first/last mile, surcharges), overweight lines and 20ft weight-pairing errors for a shipment payload (no booking created)", "POST", "Contract"],
+  // "POST /api/contracts/:id/validate-shipment": ["Pre-create validation + authoritative price preview: full booking price breakdown (rail, first/last mile, surcharges), overweight lines and 20ft weight-pairing errors for a shipment payload (no booking created)", "POST", "Contract"],
   "POST /api/contracts/booking-requests/:reqId/accept": ["GL marks a shipment request accepted + links the created booking", "POST", "Contract"],
   "POST /api/contracts/booking-requests/:reqId/cancel": ["Customer cancels their own pending shipment request", "POST", "Contract"],
   "POST /api/contracts/booking-requests/:reqId/reject": ["GL rejects a shipment request", "POST", "Contract"],
@@ -235,7 +246,7 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "PUT /api/contract-templates/:code/articles": ["Replace the full ordered article list (used for reorder)", "PUT", "Contract Template"],
   "PATCH /api/contract-templates/:code/articles/:articleId": ["Update an article's title or body", "PATCH", "Contract Template"],
   "DELETE /api/contract-templates/:code/articles/:articleId": ["Remove an article from the template", "DELETE", "Contract Template"],
-  "POST /api/contract-templates/:code/preview": ["Render an HTML preview of the template against mock contract data", "POST", "Contract Template"],
+  // "POST /api/contract-templates/:code/preview": ["Render an HTML preview of the template against mock contract data", "POST", "Contract Template"],
 
   // Driver
   "POST /api/drivers": ["Create a new driver", "POST", "Driver"],
@@ -261,6 +272,8 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/invoices/:id/eims/receipt/sales": ["Register a sales receipt with MoR EIMS against a registered invoice", "POST", "EIMS Invoice"],
   "POST /api/invoices/:id/eims/receipt/withholding": ["Register a withholding receipt with MoR EIMS against a registered invoice", "POST", "EIMS Invoice"],
   "POST /api/invoices/eims/bulk-cancel": ["Cancel multiple invoices", "POST", "EIMS Invoice"],
+  "POST /api/invoices/eims/bulk-register": ["Submit multiple invoices to MoR EIMS in one call. Asynchronous — this only confirms MoR", "POST", "EIMS Invoice"],
+  "POST /api/eims/webhook/bulk-register": ["EIMS bulk-register webhook callback (MoR reports per-invoice results)", "POST", "EIMS Invoice"],
 
   // Exchange Setting
   "PATCH /api/exchange-settings": ["Set the USD→ETB fallback by hand (used only while CBE is unreachable)", "PATCH", "Exchange Setting"],
@@ -368,6 +381,14 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "PATCH /api/notifications/:id/read": ["Mark one of my notifications as read", "PATCH", "Notification Inbox"],
   "POST /api/notifications/read-all": ["Mark all my notifications as read", "POST", "Notification Inbox"],
 
+  // Operations Standard
+  "PATCH /api/operations-standards": ["Change one or more operating standards", "PATCH", "Operations Standard"],
+
+  // Operations Target
+  "POST /api/operations-targets": ["Create a planned target", "POST", "Operations Target"],
+  "PATCH /api/operations-targets/:id": ["Update a planned target", "PATCH", "Operations Target"],
+  "DELETE /api/operations-targets/:id": ["Soft-delete a planned target", "DELETE", "Operations Target"],
+
   // Organization User
   "PUT /api/backoffice/organizations/:orgId/employee-users/:userId/roles": ["Replace org-scoped roles assigned to an employee user", "PUT", "Organization User"],
   "POST /api/backoffice/organizations/:orgId/users": ["Create an organization user without assigning positions", "POST", "Organization User"],
@@ -440,7 +461,8 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   // Two controllers register this same path; Nest serves whichever module loads first.
   "POST /api/train-scheduling/schedules/:id/maintenance": ["Reschedule train for maintenance (new departure + rebalance)", "POST", "Schedule"],
   "POST /api/train-scheduling/schedules/:id/reschedule/execute": ["Execute a confirmed reschedule plan", "POST", "Schedule"],
-  "POST /api/train-scheduling/schedules/:id/reschedule/preview": ["Preview reschedule / government preempt plan", "POST", "Schedule"],
+  "POST /api/train-scheduling/schedules/:id/reschedule/maintenance": ["Reschedule train for maintenance (new departure + rebalance)", "POST", "Schedule"],
+  // "POST /api/train-scheduling/schedules/:id/reschedule/preview": ["Preview reschedule / government preempt plan", "POST", "Schedule"],
 
   // Service Type
   "POST /api/service-types": ["Create a service type", "POST", "Service Type"],
@@ -458,7 +480,7 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   // Shipping Line Booking
   "POST /api/shipping-line-bookings/initiate": ["Initiate a bare booking (no contract). Starts at AWAITING_DOCUMENTS so the shipping line can upload its documents for Operations to approve.", "POST", "Shipping Line Booking"],
   "POST /api/shipping-line-bookings/:id/cancel": ["Cancel one of the signed-in shipping line's own bookings. Allowed only before the booking is priced.", "POST", "Shipping Line Booking"],
-  "POST /api/shipping-line-bookings/:id/price-preview": ["Authoritative price quote for the completion payload — same compute as /complete, saved as the booking's breakdown + rate snapshots (refreshed on every re-preview). Persists nothing else.", "POST", "Shipping Line Booking"],
+  // "POST /api/shipping-line-bookings/:id/price-preview": ["Authoritative price quote for the completion payload — same compute as /complete, saved as the booking's breakdown + rate snapshots (refreshed on every re-preview). Persists nothing else.", "POST", "Shipping Line Booking"],
   "POST /api/shipping-line-bookings/:id/complete": ["Complete an approved (CLEARANCE_READY) booking: cargo + binding shipment day.", "POST", "Shipping Line Booking"],
 
   // Shipping Line Credit
@@ -505,6 +527,8 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "PATCH /api/train-builder/:id/details": ["Edit the train's name and fixed import/export run numbers", "PATCH", "Train Build"],
   "PUT /api/train-builder/:id/locomotives": ["Replace the locomotive set (minimum 1, same yard)", "PUT", "Train Build"],
   "POST /api/train-builder/:id/reorder-wagons": ["Persist a drag-reorder of the full consist", "POST", "Train Build"],
+  "PATCH /api/train-builder/:id/wagons/:wagonId/yard": ["Move one coupled wagon to another yard — refused while any live schedule has the wagon allocated", "PATCH", "Train Build"],
+  "PATCH /api/train-builder/:id/wagons/yard": ["Move several coupled wagons to another yard in one transaction — refused outright if any is allocated to a live schedule", "PATCH", "Train Build"],
   "POST /api/train-builder/:id/wagons": ["Append AVAILABLE wagons from the train's yard to the consist", "POST", "Train Build"],
   "DELETE /api/train-builder/:id/wagons/:wagonId": ["Detach one wagon from the consist", "DELETE", "Train Build"],
   "POST /api/train-builder/:id/wagons/:wagonId/maintenance": ["Detach one wagon and move it to MAINTENANCE status", "POST", "Train Build"],
@@ -515,16 +539,16 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/train-scheduling/bookings/:bookingId/expire": ["Staff: expire a reservation and free its capacity", "POST", "Train Schedule"],
   "POST /api/train-scheduling/bookings/:bookingId/mark-paid": ["Staff: mark a reserved booking paid and allocate it now", "POST", "Train Schedule"],
   "POST /api/train-scheduling/bookings/:bookingId/move-schedule": ["Re-point a booking to another OPEN same-route schedule", "POST", "Train Schedule"],
-  "POST /api/train-scheduling/bulk/preview": ["Preview a bulk train schedule", "POST", "Train Schedule"],
+  // "POST /api/train-scheduling/bulk/preview": ["Preview a bulk train schedule", "POST", "Train Schedule"],
   "POST /api/train-scheduling/bulk/schedules": ["Create a bulk train schedule", "POST", "Train Schedule"],
   "POST /api/train-scheduling/bulk/schedules/:id/assign-bookings": ["Assign bulk bookings to a train schedule", "POST", "Train Schedule"],
   "POST /api/train-scheduling/bulk/schedules/:id/cancel": ["Cancel bulk train schedule", "POST", "Train Schedule"],
-  "POST /api/train-scheduling/container/preview": ["Preview a container train schedule", "POST", "Train Schedule"],
+  // "POST /api/train-scheduling/container/preview": ["Preview a container train schedule", "POST", "Train Schedule"],
   "POST /api/train-scheduling/container/schedules": ["Create a container train schedule", "POST", "Train Schedule"],
   "POST /api/train-scheduling/container/schedules/:id/assign-bookings": ["Assign container bookings to a train schedule", "POST", "Train Schedule"],
   "POST /api/train-scheduling/container/schedules/:id/cancel": ["Cancel container train schedule", "POST", "Train Schedule"],
   "PATCH /api/train-scheduling/global-rules": ["Update global train scheduling rules (singleton)", "PATCH", "Train Schedule"],
-  "POST /api/train-scheduling/preview": ["Preview a mixed-capable train schedule", "POST", "Train Schedule"],
+  // "POST /api/train-scheduling/preview": ["Preview a mixed-capable train schedule", "POST", "Train Schedule"],
   "POST /api/train-scheduling/schedules/:id/adjust-consist": ["Permanently trim free wagons off / couple yard wagons onto the schedule's built train (weight & length limits incl. tolerance enforced, every change logged)", "POST", "Train Schedule"],
   "POST /api/train-scheduling/schedules/:id/arrive": ["Mark a dispatched train arrived (move assets to destination yard, free assets)", "POST", "Train Schedule"],
   "POST /api/train-scheduling/schedules/:id/assign-bookings": ["Assign bookings to a train schedule (mixed-capable)", "POST", "Train Schedule"],
@@ -559,6 +583,7 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "DELETE /api/train-scheduling/schedules/:id/wagons/:trainSetWagonId": ["Remove an empty wagon slot from a train", "DELETE", "Train Schedule"],
   "POST /api/train-scheduling/schedules/:id/wagons/:wagonId/move-load": ["Move a wagon's whole load to another wagon (empty → move/repin, loaded → swap loads)", "POST", "Train Schedule"],
   "PATCH /api/train-scheduling/schedules/:id/window-rule": ["Override the booking-window rule for one schedule (open/close hour, duration, doc-review, payment, lead days) — only before the window opens", "PATCH", "Train Schedule"],
+  "PATCH /api/train-scheduling/schedules/:id/wagon-yards": ["Re-plan the yard this departure boards wagons from and/or cuts them at (schedule-only; physical yards untouched, dispatch requires alignment)", "PATCH", "Train Schedule"],
   "POST /api/train-scheduling/schedules/:id/merge": ["Merge another train into this schedule: its wagons join this consist, a same-day schedule on it is absorbed, and the emptied train is deactivated", "POST", "Train Schedule"],
   "PATCH /api/train-scheduling/schedules/:id/checkpoints/:sequenceNo": ["Edit a logged leg", "PATCH", "Train Schedule"],
 
@@ -606,7 +631,7 @@ export const AUDIT_ENDPOINTS: Readonly<Record<string, AuditEndpointMeta>> = {
   "POST /api/warehouse-allocation-rules": ["Create a warehouse allocation rule", "POST", "Warehouse"],
   "PATCH /api/warehouse-allocation-rules/:id": ["Update a warehouse allocation rule", "PATCH", "Warehouse"],
   "DELETE /api/warehouse-allocation-rules/:id": ["Delete a warehouse allocation rule", "DELETE", "Warehouse"],
-  "POST /api/warehouse-allocation/preview": ["Preview the yard/warehouse/zone a booking would be allocated to", "POST", "Warehouse"],
+  // "POST /api/warehouse-allocation/preview": ["Preview the yard/warehouse/zone a booking would be allocated to", "POST", "Warehouse"],
   "POST /api/warehouse-fee-rules": ["Create a storage / demurrage fee rule", "POST", "Warehouse"],
   "PATCH /api/warehouse-fee-rules/:id": ["Update a fee rule", "PATCH", "Warehouse"],
   "DELETE /api/warehouse-fee-rules/:id": ["Delete a fee rule", "DELETE", "Warehouse"],

apps/edr-freight-api/src/modules/audit/audit-log.repository.ts

@@ -1,10 +1,11 @@
 import { Injectable } from '@nestjs/common';
 import { BaseRepository } from '@edr/api-common';
 import { InjectRepository } from '@nestjs/typeorm';
-import { Between, FindOptionsWhere, LessThanOrEqual, MoreThanOrEqual, Repository } from 'typeorm';
+import { Repository } from 'typeorm';
 import type { QueryDeepPartialEntity } from 'typeorm/query-builder/QueryPartialEntity';
 
 import { AuditLog } from './entities/audit-log.entity';
+import type { AuditReferenceSource } from './audit-reference.registry';
 
 export interface AuditLogQuery {
   type?: string;
@@ -12,6 +13,10 @@ export interface AuditLogQuery {
   method?: string;
   isSuccess?: boolean;
   resourceId?: string;
+  reference?: string;
+  userName?: string;
+  title?: string;
+  q?: string;
   from?: Date;
   to?: Date;
   skip: number;
@@ -40,30 +45,91 @@ export class AuditLogRepository extends BaseRepository<AuditLog> {
     );
   }
 
+  /**
+   * Resolve the human identifier for one entity row (`WHERE id = $1`).
+   *
+   * `source` comes from the static `AUDIT_REFERENCE_SOURCES` registry — never
+   * from user input — so interpolating its table/column is safe; the id is
+   * bound as a parameter. Returns null when the row doesn't exist or the
+   * identifier column is empty.
+   */
+  async lookupReference(
+    source: AuditReferenceSource,
+    id: string,
+  ): Promise<string | null> {
+    const rows = await this.auditLogRepository.manager.query<
+      { reference: string | null }[]
+    >(
+      `SELECT ${source.column}::varchar AS reference FROM ${source.table} WHERE id = $1::uuid`,
+      [id],
+    );
+    return rows[0]?.reference || null;
+  }
+
   /**
    * Paginated, filtered read. Newest first — every index on this table is
    * ordered `created_at DESC` to match.
+   *
+   * Query builder rather than `findAndCount`: `q` needs an OR across four
+   * columns, and `reference` needs the `upper(...) LIKE` shape that matches
+   * the expression index — neither fits `FindOptionsWhere`.
    */
   async search(query: AuditLogQuery): Promise<[AuditLog[], number]> {
-    const where: FindOptionsWhere<AuditLog> = {};
+    const qb = this.auditLogRepository.createQueryBuilder('audit_log');
 
-    if (query.type) where.type = query.type;
-    if (query.userId) where.userId = query.userId;
-    if (query.method) where.method = query.method;
-    if (query.resourceId) where.resourceId = query.resourceId;
-    if (query.isSuccess !== undefined) where.isSuccess = query.isSuccess;
+    if (query.type) qb.andWhere('audit_log.type = :type', { type: query.type });
+    if (query.userId) qb.andWhere('audit_log.user_id = :userId', { userId: query.userId });
+    if (query.method) qb.andWhere('audit_log.method = :method', { method: query.method });
+    if (query.resourceId) {
+      qb.andWhere('audit_log.resource_id = :resourceId', { resourceId: query.resourceId });
+    }
+    if (query.isSuccess !== undefined) {
+      qb.andWhere('audit_log.is_success = :isSuccess', { isSuccess: query.isSuccess });
+    }
+
+    // Case-insensitive prefix match, shaped to hit idx_audit_logs_reference_upper.
+    // The explicit <> '' repeats the index's partial predicate — without it the
+    // planner cannot prove the partial index applies and falls back to a scan.
+    if (query.reference) {
+      qb.andWhere("audit_log.reference <> ''").andWhere(
+        "upper(audit_log.reference) LIKE upper(:reference) || '%'",
+        { reference: escapeLike(query.reference) },
+      );
+    }
+    if (query.userName) {
+      qb.andWhere('audit_log.user_name ILIKE :userName', {
+        userName: `%${escapeLike(query.userName)}%`,
+      });
+    }
+    if (query.title) {
+      qb.andWhere('audit_log.title ILIKE :title', {
+        title: `%${escapeLike(query.title)}%`,
+      });
+    }
+
+    // One search box across the columns staff actually search by.
+    // ponytail: ILIKE %…% scans the time-bounded window; add pg_trgm GIN
+    // indexes if the table grows past a few million rows.
+    if (query.q) {
+      const q = `%${escapeLike(query.q)}%`;
+      qb.andWhere(
+        `(audit_log.reference ILIKE :q
+          OR audit_log.resource_id ILIKE :q
+          OR audit_log.user_name ILIKE :q
+          OR audit_log.title ILIKE :q)`,
+        { q },
+      );
+    }
 
     // Date range: either bound may be supplied alone.
-    if (query.from && query.to) where.createdAt = Between(query.from, query.to);
-    else if (query.from) where.createdAt = MoreThanOrEqual(query.from);
-    else if (query.to) where.createdAt = LessThanOrEqual(query.to);
+    if (query.from) qb.andWhere('audit_log.created_at >= :from', { from: query.from });
+    if (query.to) qb.andWhere('audit_log.created_at <= :to', { to: query.to });
 
-    return this.auditLogRepository.findAndCount({
-      where,
-      order: { createdAt: 'DESC' },
-      skip: query.skip,
-      take: query.take,
-    });
+    return qb
+      .orderBy('audit_log.created_at', 'DESC')
+      .skip(query.skip)
+      .take(query.take)
+      .getManyAndCount();
   }
 
   /** Distinct entity types present, for populating a filter dropdown. */
@@ -76,4 +142,20 @@ export class AuditLogRepository extends BaseRepository<AuditLog> {
 
     return rows.map((row) => row.type);
   }
+
+  /** Distinct action titles present, for the action filter dropdown. */
+  async distinctTitles(): Promise<string[]> {
+    const rows = await this.auditLogRepository
+      .createQueryBuilder('audit_log')
+      .select('DISTINCT audit_log.title', 'title')
+      .orderBy('audit_log.title', 'ASC')
+      .getRawMany<{ title: string }>();
+
+    return rows.map((row) => row.title);
+  }
+}
+
+/** Escape LIKE wildcards so a literal `%`/`_` in the search text stays literal. */
+function escapeLike(value: string): string {
+  return value.replace(/[\\%_]/g, (ch) => `\\${ch}`);
 }

apps/edr-freight-api/src/modules/audit/audit-reference.registry.ts

@@ -0,0 +1,39 @@
+/**
+ * Where each audited entity type keeps its human identifier — the value staff
+ * search by (booking reference, train number, invoice number).
+ *
+ * Used by `AuditService.record` for a single indexed primary-key lookup at
+ * write time. Types not listed simply get `reference = ''`; the lookup is
+ * best-effort and an audit row is never lost over it.
+ *
+ * Table and column names are static values from this file — never user input —
+ * so interpolating them into SQL is safe. Ids are always bound as parameters.
+ */
+export interface AuditReferenceSource {
+  /** Schema-qualified table holding the entity. */
+  readonly table: string;
+  /** Column with the human identifier. */
+  readonly column: string;
+}
+
+export const AUDIT_REFERENCE_SOURCES: Readonly<Record<string, AuditReferenceSource>> = {
+  Booking: { table: 'freight.bookings', column: 'reference' },
+  Contract: { table: 'freight.contracts', column: 'reference' },
+  // "Schedule" (reschedule module) and "Train Schedule" are the same table.
+  Schedule: { table: 'freight.train_schedules', column: 'reference' },
+  'Train Schedule': { table: 'freight.train_schedules', column: 'reference' },
+  Train: { table: 'freight.trains', column: 'train_number' },
+  // Train Build routes carry the train id in :id.
+  'Train Build': { table: 'freight.trains', column: 'train_number' },
+  Wagon: { table: 'freight.wagons', column: 'wagon_number' },
+  Locomotive: { table: 'freight.locomotives', column: 'code' },
+  'EIMS Invoice': { table: 'freight.invoices', column: 'invoice_number' },
+  // Payment paths mostly carry an invoice id; the ones that don't (e.g.
+  // redirect-success/:bookingId) miss the lookup and fall back to ''.
+  Payment: { table: 'freight.invoices', column: 'invoice_number' },
+  Vehicle: { table: 'freight.vehicles', column: 'plate_number' },
+  Company: { table: 'freight.companies', column: 'name' },
+};
+
+/** Lookups run `WHERE id = $1::uuid` — guard non-uuid ids (template codes…). */
+export const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;

apps/edr-freight-api/src/modules/audit/audit.controller.ts

@@ -43,4 +43,13 @@ export class AuditController {
   types(): Promise<string[]> {
     return this.auditService.listTypes();
   }
+
+  @Get('actions')
+  @BookingStaff(FREIGHT_PERMS.auditLog.view)
+  @ApiOperation({
+    summary: 'Distinct action titles present in the audit log (filter dropdown)',
+  })
+  actions(): Promise<string[]> {
+    return this.auditService.listActions();
+  }
 }

apps/edr-freight-api/src/modules/audit/audit.service.ts

@@ -4,6 +4,10 @@ import { PaginatedResponse } from '@edr/types';
 import { AuditLog } from './entities/audit-log.entity';
 import { AuditLogRepository } from './audit-log.repository';
 import { AuditLogQueryDto } from './dto/audit-log-query.dto';
+import {
+  AUDIT_REFERENCE_SOURCES,
+  UUID_PATTERN,
+} from './audit-reference.registry';
 import {
   buildPaginationMeta,
   normalizePagination,
@@ -25,6 +29,7 @@ export class AuditService {
    */
   async record(entry: Partial<AuditLog>): Promise<void> {
     try {
+      entry.reference = await this.resolveReference(entry.type, entry.resourceId);
       await this.auditLogRepository.record(entry);
     } catch (error) {
       this.logger.error(
@@ -35,6 +40,34 @@ export class AuditService {
     }
   }
 
+  /**
+   * Best-effort human identifier (booking reference, train number, …) for the
+   * entity the action touched — one primary-key lookup against the table
+   * registered for the type. Always returns a string: '' when the type has no
+   * registered source, the id isn't a uuid (template codes), the row is gone,
+   * or the lookup itself fails. A missing reference must never cost the audit
+   * row, so failures degrade to '' rather than throwing.
+   */
+  private async resolveReference(
+    type: string | undefined,
+    resourceId: string | null | undefined,
+  ): Promise<string> {
+    const source = type ? AUDIT_REFERENCE_SOURCES[type] : undefined;
+    if (!source || !resourceId || !UUID_PATTERN.test(resourceId)) return '';
+
+    try {
+      const reference = await this.auditLogRepository.lookupReference(source, resourceId);
+      return reference?.slice(0, 64) ?? '';
+    } catch (error) {
+      this.logger.warn(
+        `Reference lookup failed for ${type} ${resourceId}: ${
+          error instanceof Error ? error.message : String(error)
+        }`,
+      );
+      return '';
+    }
+  }
+
   /** Paginated, filtered audit history, newest first. */
   async search(query: AuditLogQueryDto): Promise<PaginatedResponse<AuditLog>> {
     const { page, pageSize, skip, take } = normalizePagination(query);
@@ -53,6 +86,10 @@ export class AuditService {
       userId: query.userId,
       method: query.method,
       resourceId: query.resourceId,
+      reference: query.reference,
+      userName: query.userName,
+      title: query.title,
+      q: query.q,
       isSuccess:
         query.isSuccess === undefined ? undefined : query.isSuccess === 'true',
       from,
@@ -68,4 +105,9 @@ export class AuditService {
   async listTypes(): Promise<string[]> {
     return this.auditLogRepository.distinctTypes();
   }
+
+  /** Distinct action titles, for the action filter dropdown. */
+  async listActions(): Promise<string[]> {
+    return this.auditLogRepository.distinctTitles();
+  }
 }

apps/edr-freight-api/src/modules/audit/dto/audit-log-query.dto.ts

@@ -39,6 +39,44 @@ export class AuditLogQueryDto extends PaginationQueryDto {
   @MaxLength(64)
   resourceId?: string;
 
+  @ApiPropertyOptional({
+    description:
+      'Human identifier of the affected record — booking reference, schedule number, train number. Case-insensitive prefix match.',
+    example: 'S-2026-00045',
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(64)
+  reference?: string;
+
+  @ApiPropertyOptional({
+    description: 'Staff name, case-insensitive substring match.',
+    example: 'Mulu',
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(150)
+  userName?: string;
+
+  @ApiPropertyOptional({
+    description: 'Action title, case-insensitive substring match.',
+    example: 'Cancel booking',
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(255)
+  title?: string;
+
+  @ApiPropertyOptional({
+    description:
+      'Free-text search across reference, resource id, staff name and action title.',
+    example: 'B-2026-00120',
+  })
+  @IsOptional()
+  @IsString()
+  @MaxLength(100)
+  q?: string;
+
   @ApiPropertyOptional({
     description: 'Filter by outcome: true = succeeded, false = failed.',
   })

apps/edr-freight-api/src/modules/audit/entities/audit-log.entity.ts

@@ -86,6 +86,20 @@ export class AuditLog {
   @Column({ name: 'resource_id', type: 'varchar', length: 64, nullable: true })
   resourceId?: string | null;
 
+  /**
+   * Human identifier of the affected record — booking reference, schedule
+   * number, train number — resolved at write time from
+   * `AUDIT_REFERENCE_SOURCES`. This is what staff type into the search box;
+   * `resourceId` stays the machine id.
+   *
+   * `''` (never NULL) when the entity type has no registered source, the
+   * lookup found nothing, or the row predates the column. Empty string keeps
+   * search SQL to one shape and matches how pre-existing rows read after the
+   * metadata-only migration.
+   */
+  @Column({ name: 'reference', type: 'varchar', length: 64, default: '' })
+  reference!: string;
+
   /**
    * Sanitized request body. Secrets are replaced with `[REDACTED]` and uploads
    * are reduced to `{ __file, originalName, mimeType, size }` descriptors —

apps/edr-freight-api/src/modules/auth/account.controller.ts

@@ -1,7 +1,7 @@
 import { Body, Controller, Patch, Post, UseGuards } from "@nestjs/common";
 import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
 import { CurrentUser } from "@tria-plc/api-common/modules/auth/decorators/current-user.decorator";
-import { JwtGuard } from "@tria-plc/api-common/modules/auth/services/jwt.guard";
+import { FreightJwtGuard } from "../../common/freight-jwt.guard";
 import type { TCurrentUser } from "@tria-plc/api-common/modules/auth/types/current-user.type";
 
 import { AccountService } from "./account.service";
@@ -19,7 +19,7 @@ import {
 @ApiTags("auth")
 @Controller("me")
 @ApiBearerAuth()
-@UseGuards(JwtGuard)
+@UseGuards(FreightJwtGuard)
 export class AccountController {
   constructor(private readonly accountService: AccountService) {}
 

apps/edr-freight-api/src/modules/auth/customer-accounts.service.ts

@@ -0,0 +1,112 @@
+import { Injectable } from "@nestjs/common";
+import { InjectRepository } from "@nestjs/typeorm";
+import { In, Repository } from "typeorm";
+
+import { User } from "@tria-plc/iamapi-common/entities/iam/user/user.entity";
+
+import { ExternalProfile } from "../companies/entities/external-profile.entity";
+
+/**
+ * One portal login belonging to a customer company: the company-side profile
+ * joined to the IAM account that actually signs in.
+ *
+ * The two halves drift apart routinely — `company.email` is business contact
+ * detail, while `email` here is the credential a reset link goes to — which is
+ * exactly why staff need to see the IAM side rather than the company row.
+ */
+export interface CustomerAccount {
+  /** external_profiles.id */
+  profileId: string;
+  userId: string;
+  firstName: string;
+  lastName: string;
+  jobTitle: string | null;
+  isPrimaryContact: boolean;
+  onboardingStep: string | null;
+  onboardingCompleted: boolean;
+  /** Null when the profile points at a user row that no longer exists. */
+  username: string | null;
+  email: string | null;
+  phoneNumber: string | null;
+  phoneVerified: boolean | null;
+  /** IAM account status (`EUserStatus`), surfaced as-is. */
+  status: string | null;
+  isActive: boolean | null;
+  /** False means the account was created but never activated by its owner. */
+  hasSetPassword: boolean | null;
+  createdAt: Date;
+}
+
+@Injectable()
+export class CustomerAccountsService {
+  constructor(
+    @InjectRepository(ExternalProfile)
+    private readonly profiles: Repository<ExternalProfile>,
+    @InjectRepository(User)
+    private readonly users: Repository<User>,
+  ) {}
+
+  /**
+   * Every portal account for a company, primary contact first.
+   *
+   * Deliberately NOT filtered to active accounts: a suspended or never-activated
+   * login is the case staff are usually looking into, and hiding it would leave
+   * "the customer says they can't log in" unanswerable from this screen.
+   */
+  async listForCompany(companyId: string): Promise<CustomerAccount[]> {
+    const profiles = await this.profiles.find({ where: { companyId } });
+    if (profiles.length === 0) return [];
+
+    const userIds = profiles.map((p) => p.userId).filter(Boolean);
+    // Explicit select: the User entity's relations include credentials and
+    // sessions, and this response goes to a browser.
+    const users = userIds.length
+      ? await this.users
+        .createQueryBuilder("user")
+        .select([
+          "user.id",
+          "user.username",
+          "user.email",
+          "user.phoneNumber",
+          "user.isPhoneNumberVerified",
+          "user.status",
+          "user.isActive",
+          "user.hasSetPassword",
+        ])
+        .where({ id: In(userIds) })
+        .getMany()
+      : [];
+    const byId = new Map(users.map((u) => [u.id, u]));
+
+    return profiles
+      .map((p) => {
+        const user = byId.get(p.userId);
+        return {
+          profileId: p.id,
+          userId: p.userId,
+          firstName: p.firstName,
+          lastName: p.lastName,
+          jobTitle: p.jobTitle ?? null,
+          isPrimaryContact: p.isPrimaryContact,
+          onboardingStep: p.onboardingStep ?? null,
+          onboardingCompleted: p.onboardingCompleted ?? false,
+          username: user?.username ?? null,
+          email: user?.email ?? null,
+          phoneNumber: user?.phoneNumber ?? null,
+          phoneVerified: user?.isPhoneNumberVerified ?? null,
+          status: user?.status ?? null,
+          isActive: user?.isActive ?? null,
+          hasSetPassword: user?.hasSetPassword ?? null,
+          createdAt: p.createdAt,
+        };
+      })
+      .sort((a, b) => {
+        // Primary contact first — it is the account every staff action
+        // (password reset, notifications) actually targets.
+        if (a.isPrimaryContact !== b.isPrimaryContact) {
+          return a.isPrimaryContact ? -1 : 1;
+        }
+        return a.createdAt.getTime() - b.createdAt.getTime();
+      });
+  }
+}

apps/edr-freight-api/src/modules/auth/customer-reset.controller.ts

@@ -12,6 +12,10 @@ import { ApiBearerAuth, ApiOperation, ApiTags } from "@nestjs/swagger";
 import { BookingStaff } from "../../common/booking-guards";
 import { FREIGHT_PERMS } from "../../seed/freight-permissions.registry";
 import { BackofficeResetPasswordDto } from "./dto/forgot-password.dto";
+import {
+  CustomerAccount,
+  CustomerAccountsService,
+} from "./customer-accounts.service";
 import {
   CustomerResetService,
   CustomerResetTarget,
@@ -25,7 +29,22 @@ import {
 @Controller("backoffice/customers")
 @ApiBearerAuth()
 export class CustomerResetController {
-  constructor(private readonly customerResetService: CustomerResetService) {}
+  constructor(
+    private readonly customerResetService: CustomerResetService,
+    private readonly customerAccountsService: CustomerAccountsService,
+  ) {}
+
+  @Get(":companyId/accounts")
+  @BookingStaff(FREIGHT_PERMS.customers.view)
+  @ApiOperation({
+    summary:
+      "The portal login accounts belonging to a customer, primary contact first",
+  })
+  async accounts(
+    @Param("companyId", ParseUUIDPipe) companyId: string,
+  ): Promise<CustomerAccount[]> {
+    return this.customerAccountsService.listForCompany(companyId);
+  }
 
   @Get(":companyId/reset-target")
   @BookingStaff(FREIGHT_PERMS.customers.resetPassword)

apps/edr-freight-api/src/modules/auth/freight-auth.module.ts

@@ -13,6 +13,7 @@ import { AccountController } from './account.controller';
 import { AccountService } from './account.service';
 import { CheckAvailabilityController } from './check-availability.controller';
 import { CheckAvailabilityService } from './check-availability.service';
+import { CustomerAccountsService } from './customer-accounts.service';
 import { CustomerResetController } from './customer-reset.controller';
 import { CustomerResetService } from './customer-reset.service';
 import { ForgotPasswordController } from './forgot-password.controller';
@@ -50,6 +51,7 @@ import { ListUsersService } from './list-users.service';
     CheckAvailabilityService,
     ForgotPasswordService,
     CustomerResetService,
+    CustomerAccountsService,
   ],
   // Shipping-line registration mints activation links through the same
   // staff-triggered reset path customers use.

apps/edr-freight-api/src/modules/auth/freight-me.controller.ts

@@ -1,7 +1,7 @@
 import { Controller, Get, UseGuards } from '@nestjs/common';
 import { ApiBearerAuth, ApiOperation, ApiTags } from '@nestjs/swagger';
 import { CurrentUser } from '@tria-plc/api-common/modules/auth/decorators/current-user.decorator';
-import { JwtGuard } from '@tria-plc/api-common/modules/auth/services/jwt.guard';
+import { FreightJwtGuard } from '../../common/freight-jwt.guard';
 import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
 
 import { FreightMeService } from './freight-me.service';
@@ -13,7 +13,7 @@ export class FreightMeController {
   constructor(private readonly freightMeService: FreightMeService) {}
 
   @Get()
-  @UseGuards(JwtGuard)
+  @UseGuards(FreightJwtGuard)
   @ApiOperation({
     summary: 'Current user with flat permissionKeys for backoffice gating',
   })

apps/edr-freight-api/src/modules/auth/freight-me.service.ts

@@ -9,6 +9,9 @@ import {
 } from '../../common/freight-permission.util';
 import { PERMISSIONS_CATALOG } from '../../seed/freight-permissions.registry';
 
+/** One position as the session snapshot carries it. */
+type TokenPosition = NonNullable<TCurrentUser['employee']>['position'];
+
 @Injectable()
 export class FreightMeService {
   constructor(@InjectDataSource() private readonly dataSource: DataSource) {}
@@ -65,49 +68,63 @@ export class FreightMeService {
   }
 
   async getEnrichedProfile(user: TCurrentUser) {
-    const positionId = user.employee?.position?.id;
-    const [positionType, positionTypePermissionKeys] = await Promise.all([
-      this.lookupPositionType(positionId),
-      this.lookupPositionTypePermissions(positionId),
-    ]);
+    const employeeRecord = user.employee as
+      | (typeof user.employee & { positions?: TokenPosition[] })
+      | undefined;
 
-    // Merge the type-level grants into the position's own permission list so
-    // BOTH consumers see them: `collectPermissionKeys` below, and the
-    // backoffice's `getPermissionKeys`, which walks this same nested array.
-    const positionPermissions = [
-      ...(user.employee?.position?.permissions ?? []),
-    ];
-    const seenPermissionKeys = new Set(
-      positionPermissions.map((p) => p?.key).filter(Boolean),
+    // `FreightJwtGuard` restores every position the login snapshot holds; the
+    // stock IAM guard only ever leaves the single `position`. Fall back to it
+    // so a request that somehow skipped our guard still resolves one post
+    // rather than none.
+    const rawPositions: TokenPosition[] = employeeRecord?.positions?.length
+      ? employeeRecord.positions
+      : employeeRecord?.position
+        ? [employeeRecord.position]
+        : [];
+
+    const enrichedPositions = await Promise.all(
+      rawPositions.map(async (position) => {
+        const [positionType, positionTypePermissionKeys] = await Promise.all([
+          this.lookupPositionType(position.id),
+          this.lookupPositionTypePermissions(position.id),
+        ]);
+
+        // Merge the type-level grants into this position's own permission list
+        // so BOTH consumers see them: `collectPermissionKeys` below, and the
+        // backoffice's `getPermissionKeys`, which walks this nested array.
+        const permissions = [...(position.permissions ?? [])];
+        const seen = new Set(permissions.map((p) => p?.key).filter(Boolean));
+        for (const key of positionTypePermissionKeys) {
+          if (!seen.has(key)) {
+            seen.add(key);
+            permissions.push({ key } as (typeof permissions)[number]);
+          }
+        }
+
+        return {
+          positionTypePermissionKeys,
+          position: {
+            id: position.id,
+            key: position.key,
+            employeePositionId: position.employeePositionId,
+            name: position.name,
+            isDelegate: position.isDelegate,
+            parentPositionId: position.parentPositionId,
+            permissions,
+            positionType,
+          },
+        };
+      }),
     );
-    for (const key of positionTypePermissionKeys) {
-      if (!seenPermissionKeys.has(key)) {
-        seenPermissionKeys.add(key);
-        positionPermissions.push({ key } as (typeof positionPermissions)[number]);
-      }
-    }
 
-    const employee = user.employee
+    const employee = employeeRecord
       ? [
           {
-            id: user.employee.id,
-            organizationId: user.employee.organizationId,
-            unitId: user.employee.unitId,
-            name: user.employee.name,
-            positions: user.employee.position
-              ? [
-                  {
-                    id: user.employee.position.id,
-                    key: user.employee.position.key,
-                    employeePositionId: user.employee.position.employeePositionId,
-                    name: user.employee.position.name,
-                    isDelegate: user.employee.position.isDelegate,
-                    parentPositionId: user.employee.position.parentPositionId,
-                    permissions: positionPermissions,
-                    positionType,
-                  },
-                ]
-              : [],
+            id: employeeRecord.id,
+            organizationId: employeeRecord.organizationId,
+            unitId: employeeRecord.unitId,
+            name: employeeRecord.name,
+            positions: enrichedPositions.map((p) => p.position),
           },
         ]
       : [];
@@ -118,7 +135,7 @@ export class FreightMeService {
     const permissionKeys = [
       ...new Set([
         ...collectPermissionKeys(user),
-        ...positionTypePermissionKeys,
+        ...enrichedPositions.flatMap((p) => p.positionTypePermissionKeys),
       ]),
     ];
 

apps/edr-freight-api/src/modules/billing/billing.service.spec.ts

@@ -1,5 +1,6 @@
 import { Freight } from "@edr/types";
 
+import { WAGON_CANCEL_FEE_INVOICE_TYPE } from "../bookings/entities/booking-wagon-cancellation.entity";
 import { BillingService } from "./billing.service";
 
 /**
@@ -938,8 +939,12 @@ describe("BillingService.document", () => {
   const build = (invoice: Record<string, unknown>) => {
     const render = jest.fn().mockResolvedValue({ filename: "x.pdf", buffer: Buffer.from("") });
     const renderThermal = jest.fn().mockResolvedValue({ filename: "x-thermal.pdf", buffer: Buffer.from("") });
+    // `toDocumentModel` reads the booking (route/wagons, PNR) straight off the
+    // data source for a booking-sourced invoice — a stub that answers "no such
+    // booking" keeps these summary assertions about the invoice itself.
+    const dataSource = { getRepository: () => ({ findOne: jest.fn().mockResolvedValue(null) }) };
     const service = new BillingService(
-      {} as never,
+      dataSource as never,
       { findById: jest.fn().mockResolvedValue(invoice) } as never,
       { findAll: jest.fn().mockResolvedValue([]) } as never,
       {} as never,
@@ -1013,6 +1018,34 @@ describe("BillingService.document", () => {
     expect(model.qrImageUrl).toBe("data:image/png;base64,signed-payload");
   });
 
+  it("prints the provider transaction reference of a settled invoice", async () => {
+    const { service, render } = build(
+      invoiceRow({
+        status: Freight.InvoiceStatus.Paid,
+        paidAmount: 100,
+        balanceAmount: 0,
+        payments: [{ amount: 100, method: "GATEWAY", reference: "FT26082700123", paidAt: "2026-08-27T09:00:00.000Z" }],
+        payment: { transactionId: "FT26082700123" },
+      }),
+    );
+
+    await service.document("inv-1");
+
+    const model = render.mock.calls[0][0];
+    expect(model.summary).toContainEqual({ label: "Transaction ref", value: "FT26082700123" });
+  });
+
+  it("adds no transaction reference row to an unpaid invoice", async () => {
+    const { service, render } = build(invoiceRow());
+
+    await service.document("inv-1");
+
+    const model = render.mock.calls[0][0];
+    expect(
+      model.summary.find((r: { label: string }) => r.label === "Transaction ref"),
+    ).toBeUndefined();
+  });
+
   it("calls render (not renderThermal) for the default format", async () => {
     const { service, render, renderThermal } = build(invoiceRow());
     jest.spyOn(service as never, "toDocumentModel").mockResolvedValue({} as never);
@@ -1033,3 +1066,73 @@ describe("BillingService.document", () => {
     expect(render).not.toHaveBeenCalled();
   });
 });
+
+/**
+ * The pay-window guard belongs to the freight invoice. A wagon-cancellation fee
+ * rides source=booking but is raised on an already-PAID booking, so it inherits
+ * a deadline that has long passed — guarding it would make the fee permanently
+ * unsettleable.
+ */
+describe("BillingService.confirmOfflinePayment pay-window guard", () => {
+  const PAST = new Date(Date.now() - 86_400_000);
+
+  function makeService(invoiceType: string) {
+    const invoice = {
+      id: "inv-1",
+      source: Freight.InvoiceSource.Booking,
+      sourceId: "booking-1",
+      type: invoiceType,
+      currency: "ETB",
+      status: Freight.InvoiceStatus.Issued,
+      balanceAmount: 500,
+    };
+    const recordPayment = jest.fn().mockResolvedValue(invoice);
+    const dataSource = {
+      getRepository: () => ({
+        findOne: async () => ({ id: "booking-1", paymentDeadline: PAST }),
+      }),
+    };
+    const service = new BillingService(
+      dataSource as never,
+      { findById: async () => invoice } as never,
+      {} as never,
+      makeEvents() as never,
+      {} as never,
+      {} as never,
+      {} as never,
+      { upload: async () => ({ id: "file-1", name: "slip.pdf" }) } as never,
+      { get: () => undefined } as never,
+      { isEnabled: async () => true } as never,
+    );
+    (service as unknown as { recordPayment: unknown }).recordPayment =
+      recordPayment;
+    return { service, recordPayment };
+  }
+
+  const slip = { originalname: "slip.pdf" } as never;
+
+  it("refuses a freight invoice once the pay window has closed", async () => {
+    const { service } = makeService("PREPAID");
+    await expect(
+      service.confirmOfflinePayment("inv-1", slip, {}),
+    ).rejects.toThrow(/payment window has closed/i);
+  });
+
+  it("settles a wagon-cancellation fee despite the closed window", async () => {
+    const { service, recordPayment } = makeService(
+      WAGON_CANCEL_FEE_INVOICE_TYPE,
+    );
+    await service.confirmOfflinePayment("inv-1", slip, {});
+    expect(recordPayment).toHaveBeenCalledWith(
+      "inv-1",
+      expect.objectContaining({ amount: 500, method: "BANK_TRANSFER" }),
+    );
+  });
+
+  it("still requires the bank slip for a cancellation fee", async () => {
+    const { service } = makeService(WAGON_CANCEL_FEE_INVOICE_TYPE);
+    await expect(
+      service.confirmOfflinePayment("inv-1", undefined, {}),
+    ).rejects.toThrow(/slip file is required/i);
+  });
+});

apps/edr-freight-api/src/modules/billing/billing.service.ts

@@ -13,6 +13,8 @@ import { logCtx } from "@edr/api-common";
 import { DataSource, EntityManager, In, SelectQueryBuilder } from "typeorm";
 
 import { Booking } from "../bookings/entities/booking.entity";
+import { AdditionalCharge } from "../bookings/entities/additional-charge.entity";
+import { WAGON_CANCEL_FEE_INVOICE_TYPE } from "../bookings/entities/booking-wagon-cancellation.entity";
 // Entity-only import (no module edge): portal reads resolve shipping-line
 // payers straight off the table.
 import { ShippingLineCompany } from "../shipping-lines/entities/shipping-line-company.entity";
@@ -27,14 +29,21 @@ import { PaymentService } from "../payment/payment.service";
 import { InitiateResponseDto, IntentStatusDto } from "../payment/payments.dto";
 import {
   InvoiceDocumentModel,
+  sameCompanyName,
   InvoiceDocumentService,
   pngDataUrl,
 } from "./documents/invoice-document.service";
+import { INVOICE_SORT_COLUMNS } from "./dto/filter-invoice.dto";
 import { InvoiceLine } from "./entities/invoice-line.entity";
 import { Invoice, InvoicePayment } from "./entities/invoice.entity";
 import { InvoiceLineRepository } from "./invoice-line.repository";
 import { nextDailyInvoiceNumber } from "./invoice-numbering.util";
-import { applySettlement, round2 } from "./invoice-settlement.util";
+import {
+  applySettlement,
+  invoicePaymentMethodExpr,
+  round2,
+  settlementReferences,
+} from "./invoice-settlement.util";
 import { InvoiceRepository } from "./invoice.repository";
 
 /** Options forwarded to the payment gateway when settling an invoice. */
@@ -46,6 +55,29 @@ export interface PayInvoiceOptions {
   failureUrl?: string;
 }
 
+/**
+ * What an invoice's `sourceId` actually points at, resolved for display.
+ *
+ * `source` alone ("warehouse", "booking", …) says which subsystem raised the
+ * invoice but nothing about *which* record, and `sourceId` is a raw UUID. Every
+ * source except a shipping-line credit hangs off a booking — directly
+ * (booking/clearance) or through the warehouse/first-mile/last-mile record —
+ * so the booking reference is the one label that identifies almost any row.
+ */
+export interface InvoiceSourceRef {
+  /** Booking behind the invoice, when there is one. Null for shipping-line credits. */
+  bookingId: string | null;
+  bookingReference: string | null;
+  tradeDirection: string | null;
+  /** Warehouse-sourced rows: the goods-received note the fees were raised against. */
+  grnNumber: string | null;
+  /** Shipping-line credit rows: `sourceId` is the line's own id, not a record's. */
+  shippingLineName: string | null;
+}
+
+/** Row shape of the backoffice invoice list: the entity plus its resolved source. */
+export type InvoiceListRow = Invoice & { sourceRef: InvoiceSourceRef | null };
+
 /** Booking context attached to a finance offline-USD invoice row. */
 export interface OfflineUsdBookingInfo {
   id: string;
@@ -74,6 +106,42 @@ export interface RecordPaymentInput {
 }
 
 /** Default invoice payment-term window, in days, used to compute `dueAt`. */
+/**
+ * Every dimension the backoffice invoice list narrows by. `findAllPaginated`
+ * and `collectedSummary` share it so the summary card can never total a
+ * different set of invoices than the table below it shows.
+ */
+export interface InvoiceListFilters {
+  companyId?: string;
+  status?: Freight.InvoiceStatus;
+  statuses?: Freight.InvoiceStatus[];
+  sources?: string[];
+  /** What the invoice bills for (`PREPAID`, `DEMURRAGE`, …) — free-form per source. */
+  types?: string[];
+  eimsStatuses?: string[];
+  /** Settled payment method, normalised UPPER_SNAKE — see `invoicePaymentMethodExpr`. */
+  paymentMethods?: string[];
+  currency?: string;
+  search?: string;
+  issuedFrom?: string;
+  issuedTo?: string;
+  dueFrom?: string;
+  dueTo?: string;
+  minAmount?: number;
+  maxAmount?: number;
+  hasBalance?: boolean;
+  overdue?: boolean;
+  /** Per-user trade-direction scope, applied via the source booking. */
+  tradeDirections?: string[];
+}
+
+/**
+ * The list/summary query builders both alias the invoice as `invoice` and the
+ * joined gateway payment as `payment`; TypeORM rewrites those alias.property
+ * references into real quoted columns.
+ */
+const PAYMENT_METHOD_EXPR = invoicePaymentMethodExpr("invoice", "payment");
+
 const DEFAULT_DUE_DAYS = 14;
 
 /** Statuses an invoice can still be settled (paid/refunded/cancelled) from. */
@@ -203,7 +271,7 @@ export class BillingService {
     private readonly files: FilesService,
     private readonly config: ConfigService,
     private readonly manualPaymentSettings: ManualPaymentSettingsService,
-  ) { }
+  ) {}
 
   // ── Reads ──────────────────────────────────────────────────────────────────
 
@@ -220,12 +288,7 @@ export class BillingService {
   /** Same list filters `findAllPaginated` and `collectedSummary` both narrow by. */
   private applyInvoiceFilters(
     qb: SelectQueryBuilder<Invoice>,
-    filter: {
-      companyId?: string;
-      status?: Freight.InvoiceStatus;
-      search?: string;
-      tradeDirections?: string[];
-    },
+    filter: InvoiceListFilters,
   ) {
     if (filter.companyId) {
       qb.andWhere("invoice.companyId = :companyId", {
@@ -235,9 +298,102 @@ export class BillingService {
     if (filter.status) {
       qb.andWhere("invoice.status = :status", { status: filter.status });
     }
+    if (filter.statuses?.length) {
+      qb.andWhere("invoice.status IN (:...statuses)", {
+        statuses: filter.statuses,
+      });
+    }
+    if (filter.sources?.length) {
+      qb.andWhere("invoice.source IN (:...sources)", {
+        sources: filter.sources,
+      });
+    }
+    if (filter.types?.length) {
+      qb.andWhere("invoice.type IN (:...types)", { types: filter.types });
+    }
+    if (filter.eimsStatuses?.length) {
+      qb.andWhere("invoice.eimsStatus IN (:...eimsStatuses)", {
+        eimsStatuses: filter.eimsStatuses,
+      });
+    }
+    if (filter.paymentMethods?.length) {
+      // Requires the `payment` alias to be joined by the caller — both call
+      // sites do, unconditionally, so this can never reference a missing alias.
+      qb.andWhere(`${PAYMENT_METHOD_EXPR} IN (:...paymentMethods)`, {
+        paymentMethods: filter.paymentMethods,
+      });
+    }
+    if (filter.currency) {
+      // Stored casing has drifted ("usd" rows exist) — compare normalised.
+      qb.andWhere("UPPER(invoice.currency) = :currency", {
+        currency: filter.currency.toUpperCase(),
+      });
+    }
+    if (filter.issuedFrom) {
+      qb.andWhere("invoice.issuedAt >= :issuedFrom", {
+        issuedFrom: filter.issuedFrom,
+      });
+    }
+    if (filter.issuedTo) {
+      qb.andWhere("invoice.issuedAt <= :issuedTo", {
+        issuedTo: filter.issuedTo,
+      });
+    }
+    if (filter.dueFrom) {
+      qb.andWhere("invoice.dueAt >= :dueFrom", { dueFrom: filter.dueFrom });
+    }
+    if (filter.dueTo) {
+      qb.andWhere("invoice.dueAt <= :dueTo", { dueTo: filter.dueTo });
+    }
+    if (filter.minAmount !== undefined) {
+      qb.andWhere("invoice.totalAmount >= :minAmount", {
+        minAmount: filter.minAmount,
+      });
+    }
+    if (filter.maxAmount !== undefined) {
+      qb.andWhere("invoice.totalAmount <= :maxAmount", {
+        maxAmount: filter.maxAmount,
+      });
+    }
+    if (filter.hasBalance) {
+      qb.andWhere("invoice.balanceAmount > 0");
+    }
+    if (filter.overdue) {
+      // Computed, not `status = OVERDUE`: nothing sweeps PENDING rows into
+      // that status, so reading the column alone under-reports the arrears.
+      qb.andWhere("invoice.balanceAmount > 0 AND invoice.dueAt < now()");
+    }
     if (filter.search) {
+      // Searches what the row actually shows: its number, who it bills, the
+      // source record behind it (booking reference, PNR, GRN, shipping line)
+      // and the payment references a customer or a provider support desk would
+      // quote back — the gateway transaction id and our merchant order id.
+      // The raw `sourceId` stays matchable so a pasted UUID still resolves.
+      // Requires the `company` and `payment` aliases — every caller joins both.
       qb.andWhere(
-        "(invoice.invoiceNumber ILIKE :search OR invoice.sourceId ILIKE :search)",
+        `(invoice.invoiceNumber ILIKE :search
+          OR invoice.sourceId ILIKE :search
+          OR company.name ILIKE :search
+          OR payment.transactionId ILIKE :search
+          OR payment.merchantOrderId ILIKE :search
+          OR EXISTS (
+               SELECT 1 FROM freight.bookings b
+               LEFT JOIN freight.warehouse_inventory wi ON wi.booking_id = b.id
+               LEFT JOIN freight.first_mile fm ON fm.booking_id = b.id
+               LEFT JOIN freight.last_mile lm ON lm.booking_id = b.id
+               WHERE (b.reference ILIKE :search OR b.pnr_code ILIKE :search)
+                 AND (b.id::text = invoice.source_id
+                      OR wi.id::text = invoice.source_id
+                      OR fm.id::text = invoice.source_id
+                      OR lm.id::text = invoice.source_id))
+          OR EXISTS (
+               SELECT 1 FROM freight.warehouse_inventory wi2
+               WHERE wi2.id::text = invoice.source_id
+                 AND wi2.grn_number ILIKE :search)
+          OR EXISTS (
+               SELECT 1 FROM freight.shipping_line_companies slc
+               WHERE slc.id::text = invoice.source_id
+                 AND slc.name ILIKE :search))`,
         { search: `%${filter.search}%` },
       );
     }
@@ -252,16 +408,13 @@ export class BillingService {
   }
 
   async findAllPaginated(
-    filter: {
-      companyId?: string;
-      status?: Freight.InvoiceStatus;
-      search?: string;
+    filter: InvoiceListFilters & {
       page?: number;
       pageSize?: number;
-      /** Per-user trade-direction scope, applied via the source booking. */
-      tradeDirections?: string[];
+      sortBy?: string;
+      sortOrder?: "ASC" | "DESC";
     } = {},
-  ): Promise<{ items: Invoice[]; total: number }> {
+  ): Promise<{ items: InvoiceListRow[]; total: number }> {
     const page = filter.page && filter.page > 0 ? filter.page : 1;
     const pageSize =
       filter.pageSize && filter.pageSize > 0 ? filter.pageSize : 20;
@@ -270,14 +423,109 @@ export class BillingService {
       .getRepository(Invoice)
       .createQueryBuilder("invoice")
       .leftJoinAndSelect("invoice.company", "company")
-      .orderBy("invoice.issuedAt", "DESC")
+      // The gateway payment behind the invoice: the settled method and the
+      // provider's transaction reference both live on it, and nowhere else.
+      .leftJoinAndSelect("invoice.payment", "payment")
+      // sortBy is whitelisted through INVOICE_SORT_COLUMNS, never interpolated
+      // raw. The id tiebreaker keeps paging stable when the sort column ties
+      // (issuedAt is null on every DRAFT row).
+      .orderBy(
+        INVOICE_SORT_COLUMNS[filter.sortBy ?? ""] ?? "invoice.issuedAt",
+        filter.sortOrder ?? "DESC",
+      )
+      .addOrderBy("invoice.id", "ASC")
       .skip((page - 1) * pageSize)
       .take(pageSize);
 
     this.applyInvoiceFilters(qb, filter);
 
     const [items, total] = await qb.getManyAndCount();
-    return { items: await this.attachShippingLineCompanies(items), total };
+    const withLines = await this.attachShippingLineCompanies(items);
+    return { items: await this.attachSourceRefs(withLines), total };
+  }
+
+  /**
+   * Resolve each row's `sourceId` to the record it points at, in one query for
+   * the whole page. `sourceId` is a bare varchar pointer with no FK and no
+   * relation to eager-load, and which table it addresses depends on `source` —
+   * so this walks every candidate table at once and lands on the booking
+   * through whichever one matched.
+   *
+   * `sourceId` is not always a UUID (EIMS self-test rows carry a slug), hence
+   * the shape guard before every cast — an unguarded `::uuid` throws on those.
+   */
+  private async attachSourceRefs<T extends Invoice>(
+    invoices: T[],
+  ): Promise<(T & { sourceRef: InvoiceSourceRef | null })[]> {
+    const sourceIds = [
+      ...new Set(invoices.map((i) => i.sourceId).filter(Boolean)),
+    ];
+    if (!sourceIds.length) {
+      return invoices.map((invoice) => ({ ...invoice, sourceRef: null }));
+    }
+
+    const rows: {
+      sourceId: string;
+      bookingId: string | null;
+      bookingReference: string | null;
+      tradeDirection: string | null;
+      grnNumber: string | null;
+      shippingLineName: string | null;
+    }[] = await this.dataSource.query(
+      `SELECT s.source_id           AS "sourceId",
+              b.id::text            AS "bookingId",
+              b.reference           AS "bookingReference",
+              b.trade_direction     AS "tradeDirection",
+              wi.grn_number         AS "grnNumber",
+              slc.name              AS "shippingLineName"
+       FROM unnest($1::text[]) AS s(source_id)
+       LEFT JOIN freight.warehouse_inventory wi
+              ON wi.id = (CASE WHEN s.source_id ~ '^[0-9a-fA-F-]{36}$'
+                               THEN s.source_id::uuid END)
+             AND wi.deleted_at IS NULL
+       LEFT JOIN freight.first_mile fm
+              ON fm.id = (CASE WHEN s.source_id ~ '^[0-9a-fA-F-]{36}$'
+                               THEN s.source_id::uuid END)
+             AND fm.deleted_at IS NULL
+       LEFT JOIN freight.last_mile lm
+              ON lm.id = (CASE WHEN s.source_id ~ '^[0-9a-fA-F-]{36}$'
+                               THEN s.source_id::uuid END)
+             AND lm.deleted_at IS NULL
+       LEFT JOIN freight.bookings b
+              ON b.id = COALESCE(wi.booking_id, fm.booking_id, lm.booking_id,
+                                 CASE WHEN s.source_id ~ '^[0-9a-fA-F-]{36}$'
+                                      THEN s.source_id::uuid END)
+             AND b.deleted_at IS NULL
+       LEFT JOIN freight.shipping_line_companies slc
+              ON slc.id = (CASE WHEN s.source_id ~ '^[0-9a-fA-F-]{36}$'
+                                THEN s.source_id::uuid END)
+             AND slc.deleted_at IS NULL`,
+      [sourceIds],
+    );
+
+    const bySourceId = new Map(rows.map((r) => [r.sourceId, r]));
+    return invoices.map((invoice) => {
+      const row = bySourceId.get(invoice.sourceId);
+      const sourceRef: InvoiceSourceRef | null = row
+        ? {
+            bookingId: row.bookingId,
+            bookingReference: row.bookingReference,
+            tradeDirection: row.tradeDirection,
+            grnNumber: row.grnNumber,
+            shippingLineName: row.shippingLineName,
+          }
+        : null;
+      // Nothing resolved (an EIMS self-test row, a deleted record) → null,
+      // and the UI falls back to the plain source label.
+      const resolved =
+        sourceRef &&
+        (sourceRef.bookingId ||
+          sourceRef.grnNumber ||
+          sourceRef.shippingLineName)
+          ? sourceRef
+          : null;
+      return { ...invoice, sourceRef: resolved };
+    });
   }
 
   /**
@@ -326,16 +574,15 @@ export class BillingService {
    * visible page.
    */
   async collectedSummary(
-    filter: {
-      companyId?: string;
-      status?: Freight.InvoiceStatus;
-      search?: string;
-      tradeDirections?: string[];
-    } = {},
+    filter: InvoiceListFilters = {},
   ): Promise<Record<string, number>> {
     const qb = this.dataSource
       .getRepository(Invoice)
       .createQueryBuilder("invoice")
+      // Joined, not selected: `applyInvoiceFilters` searches the customer name,
+      // so the alias has to exist even though the summary only sums money.
+      .leftJoin("invoice.company", "company")
+      .leftJoin("invoice.payment", "payment")
       .select("invoice.currency", "currency")
       .addSelect("SUM(invoice.paidAmount)", "collected")
       .groupBy("invoice.currency");
@@ -353,21 +600,28 @@ export class BillingService {
   /**
    * Finance's manual-settlement worklist: USD invoices (paid by bank transfer,
    * never through the gateway) and ETB invoices Finance settles by hand (bank
-   * transfer / counter) instead of the customer paying online. Open ones by
-   * default or a single status when filtered; both currencies unless
-   * `currency` narrows it. Booking-sourced rows carry the booking's reference,
-   * trade direction and pay-window deadline so the UI can show the countdown
-   * and link to the booking.
+   * transfer / counter) instead of the customer paying online. Both currencies
+   * unless `currency` narrows it, and only ones whose manual-payment channel is
+   * switched on. Open ones by default — pin `status` or `statuses` to widen
+   * that. Every other dimension is the invoice list's own (`applyInvoiceFilters`
+   * + `INVOICE_SORT_COLUMNS`), so the two screens filter and sort alike.
+   * Booking-sourced rows carry the booking's reference, trade direction and
+   * pay-window deadline so the UI can show the countdown and link to the
+   * booking.
    */
   async findOfflineUsdPaginated(
-    filter: {
-      status?: Freight.InvoiceStatus;
-      search?: string;
-      currency?: "USD" | "ETB";
+    filter: InvoiceListFilters & {
       page?: number;
       pageSize?: number;
+      sortBy?: string;
+      sortOrder?: "ASC" | "DESC";
     } = {},
-  ): Promise<{ items: OfflineUsdInvoiceRow[]; total: number }> {
+  ): Promise<{
+    items: OfflineUsdInvoiceRow[];
+    total: number;
+    /** Sum of `balanceAmount` over the WHOLE filtered set, by currency. */
+    outstanding: Record<string, number>;
+  }> {
     const page = filter.page && filter.page > 0 ? filter.page : 1;
     const pageSize =
       filter.pageSize && filter.pageSize > 0 ? filter.pageSize : 20;
@@ -376,33 +630,75 @@ export class BillingService {
     // a row Finance cannot act on is noise, and the confirm endpoint would
     // refuse it anyway. All off → nothing to work.
     const enabled = await this.manualPaymentSettings.enabledCurrencies();
-    if (!enabled.length) return { items: [], total: 0 };
-    const currencies = filter.currency
-      ? enabled.filter((c) => c === filter.currency)
-      : enabled;
-    if (!currencies.length) return { items: [], total: 0 };
+    const empty = { items: [], total: 0, outstanding: {} };
+    if (!enabled.length) return empty;
+    const wanted = filter.currency?.toUpperCase();
+    const currencies = wanted ? enabled.filter((c) => c === wanted) : enabled;
+    if (!currencies.length) return empty;
 
-    const qb = this.dataSource
-      .getRepository(Invoice)
-      .createQueryBuilder("invoice")
-      .leftJoinAndSelect("invoice.company", "company")
-      .where("UPPER(invoice.currency) IN (:...currencies)", { currencies })
-      .orderBy("invoice.issuedAt", "DESC")
+    /**
+     * The worklist narrows by the same vocabulary as the main invoice list, so
+     * both share `applyInvoiceFilters` — which references the `company` and
+     * `payment` aliases, hence the unconditional joins. `select` is false for
+     * the aggregate pass, where joined columns would break the GROUP BY.
+     */
+    const buildQb = (select: boolean) => {
+      const qb = this.dataSource
+        .getRepository(Invoice)
+        .createQueryBuilder("invoice");
+      if (select) {
+        qb.leftJoinAndSelect("invoice.company", "company").leftJoinAndSelect(
+          "invoice.payment",
+          "payment",
+        );
+      } else {
+        qb.leftJoin("invoice.company", "company").leftJoin(
+          "invoice.payment",
+          "payment",
+        );
+      }
+      qb.where("UPPER(invoice.currency) IN (:...currencies)", { currencies });
+      // "What still needs settling" is the default cut, but only until the
+      // caller pins a status — either the single-status param or the filter
+      // bar's multi-select.
+      if (!filter.status && !filter.statuses?.length) {
+        qb.andWhere("invoice.status IN (:...open)", { open: OPEN_STATUSES });
+      }
+      // `currency` is already enforced by the enabled-currency IN above, and
+      // re-applying it would only repeat the same predicate.
+      this.applyInvoiceFilters(qb, { ...filter, currency: undefined });
+      return qb;
+    };
+
+    const qb = buildQb(true)
+      // sortBy is whitelisted through INVOICE_SORT_COLUMNS, never interpolated
+      // raw; the id tiebreaker keeps paging stable when the column ties.
+      .orderBy(
+        INVOICE_SORT_COLUMNS[filter.sortBy ?? ""] ?? "invoice.issuedAt",
+        filter.sortOrder ?? "DESC",
+      )
+      .addOrderBy("invoice.id", "ASC")
       .skip((page - 1) * pageSize)
       .take(pageSize);
-    if (filter.status) {
-      qb.andWhere("invoice.status = :status", { status: filter.status });
-    } else {
-      qb.andWhere("invoice.status IN (:...open)", { open: OPEN_STATUSES });
-    }
-    if (filter.search) {
-      qb.andWhere(
-        "(invoice.invoiceNumber ILIKE :search OR invoice.sourceId ILIKE :search)",
-        { search: `%${filter.search}%` },
-      );
-    }
 
     const [rawItems, total] = await qb.getManyAndCount();
+
+    // Outstanding across the whole filtered set, not the visible page — the
+    // KPI must not change as Finance pages through the worklist.
+    const outstandingRows: { currency: string; outstanding: string }[] =
+      await buildQb(false)
+        .select("invoice.currency", "currency")
+        .addSelect("SUM(invoice.balanceAmount)", "outstanding")
+        .groupBy("invoice.currency")
+        .getRawMany();
+    // Folded case-insensitively on the way out: stored casing has drifted
+    // ("usd" rows exist), so two groups can address the same currency.
+    const outstanding: Record<string, number> = {};
+    for (const row of outstandingRows) {
+      const key = (row.currency ?? "").toUpperCase();
+      outstanding[key] =
+        (outstanding[key] ?? 0) + (Number(row.outstanding) || 0);
+    }
     const items = await this.attachShippingLineCompanies(rawItems);
 
     const bookingIds = items
@@ -466,6 +762,7 @@ export class BillingService {
         } as OfflineUsdInvoiceRow;
       }),
       total,
+      outstanding,
     };
   }
 
@@ -503,7 +800,14 @@ export class BillingService {
       throw new BadRequestException("The bank payment slip file is required.");
     }
 
-    if (invoice.source === "booking") {
+    // The pay window belongs to the freight invoice. A wagon-cancellation fee
+    // rides source=booking but is raised on an ALREADY-PAID booking, so it
+    // inherits a deadline that has long passed — guarding it would make the fee
+    // permanently unsettleable.
+    if (
+      invoice.source === "booking" &&
+      invoice.type !== WAGON_CANCEL_FEE_INVOICE_TYPE
+    ) {
       const booking = await this.dataSource.getRepository(Booking).findOne({
         where: { id: invoice.sourceId },
         select: ["id", "paymentDeadline"],
@@ -542,7 +846,7 @@ export class BillingService {
   /** Invoice header plus its line items. */
   async findById(id: string): Promise<Invoice & { lines: InvoiceLine[] }> {
     const invoice = await this.invoices.findById(id, {
-      relations: { company: true, companyProfile: true },
+      relations: { company: true, companyProfile: true, payment: true },
     });
     if (!invoice) throw new NotFoundException(`Invoice ${id} not found`);
     const [hydrated] = await this.attachShippingLineCompanies([invoice]);
@@ -605,7 +909,9 @@ export class BillingService {
       {
         label: "Wagons",
         value:
-          booking.wagonsRequired != null ? String(booking.wagonsRequired) : null,
+          booking.wagonsRequired != null
+            ? String(booking.wagonsRequired)
+            : null,
       },
     ];
   }
@@ -632,10 +938,21 @@ export class BillingService {
     totals.push({ label: "Paid", amount: Number(invoice.paidAmount) });
     totals.push({ label: "Balance", amount: Number(invoice.balanceAmount) });
 
+    const tradeName = invoice.companyProfile?.etradeBusiness?.tradeName?.trim();
+
     const summary: InvoiceDocumentModel["summary"] = [
       // Buyer identity — was missing entirely; a MoR-registered invoice must show who it was
       // filed against, not just the seller. VatNumber shown only when the company has one.
       { label: "Buyer", value: invoice.company?.name ?? null },
+      // The trade name of the eTrade licence THIS profile operates as. A TIN
+      // holds many licences and the invoiced role (importer/exporter/forwarder)
+      // is usually a different business from the one the company registered
+      // under, so the buyer's name alone doesn't say which one was billed.
+      // Suppressed when it just repeats the buyer name — most companies trade
+      // under their registered name and a duplicate row helps nobody.
+      ...(tradeName && !sameCompanyName(tradeName, invoice.company?.name)
+        ? [{ label: "Buyer trade name", value: tradeName }]
+        : []),
       { label: "Buyer TIN", value: invoice.company?.tin ?? null },
       ...(invoice.company?.vatNumber
         ? [{ label: "Buyer VAT No.", value: invoice.company.vatNumber }]
@@ -664,11 +981,24 @@ export class BillingService {
     const eimsCfg = this.config.get<EimsConfig>("eims");
     if (eimsCfg?.tin) summary.push({ label: "Seller TIN", value: eimsCfg.tin });
     if (eimsCfg?.invoice?.sellerVatNumber) {
-      summary.push({ label: "Seller VAT No.", value: eimsCfg.invoice.sellerVatNumber });
+      summary.push({
+        label: "Seller VAT No.",
+        value: eimsCfg.invoice.sellerVatNumber,
+      });
     }
 
     // MoR EIMS reference — only once actually registered, never a placeholder row.
-    if (invoice.eimsIrn) summary.push({ label: "EIMS IRN", value: invoice.eimsIrn });
+    if (invoice.eimsIrn)
+      summary.push({ label: "EIMS IRN", value: invoice.eimsIrn });
+
+    // The provider's transaction number for the money actually received — CBE's `FT…`,
+    // telebirr's receipt number, or the bank-slip reference a teller recorded manually.
+    // It is what a payer holding a receipt can match this invoice against, and what
+    // finance reconciles a bank statement with; without it a PAID invoice proves only
+    // that EDR says it was paid. `findById` already loads the `payment` relation, so both
+    // sources are in hand here — see settlementReferences for why both are read.
+    const txnRefs = settlementReferences(invoice);
+    if (txnRefs) summary.push({ label: "Transaction ref", value: txnRefs });
 
     // PNR — the CBE_BILL reference the customer pays against, written onto the booking at
     // payment-initiation time (see initiatePayment()). Not a column on Invoice/Payment, so
@@ -678,7 +1008,8 @@ export class BillingService {
         where: { id: invoice.sourceId },
         select: ["id", "pnrCode"],
       });
-      if (booking?.pnrCode) summary.push({ label: "PNR", value: booking.pnrCode });
+      if (booking?.pnrCode)
+        summary.push({ label: "PNR", value: booking.pnrCode });
     }
 
     return {
@@ -699,7 +1030,9 @@ export class BillingService {
         currency: l.currency,
       })),
       totals,
-      qrImageUrl: invoice.eimsSignedQr ? pngDataUrl(invoice.eimsSignedQr) : null,
+      qrImageUrl: invoice.eimsSignedQr
+        ? pngDataUrl(invoice.eimsSignedQr)
+        : null,
     };
   }
 
@@ -958,7 +1291,9 @@ export class BillingService {
       metadata: l.metadata ?? null,
     }));
 
-    const total = round2(lines.reduce((sum, l) => sum + Number(l.amount ?? 0), 0));
+    const total = round2(
+      lines.reduce((sum, l) => sum + Number(l.amount ?? 0), 0),
+    );
     if (!(total > 0)) {
       throw new BadRequestException("A memo must have a positive total.");
     }
@@ -988,7 +1323,9 @@ export class BillingService {
           subtotalAmount: total,
           taxAmount: 0,
           totalAmount: total,
-          ...(settled ? { status: Freight.InvoiceStatus.Paid, dueAt: new Date() } : {}),
+          ...(settled
+            ? { status: Freight.InvoiceStatus.Paid, dueAt: new Date() }
+            : {}),
         },
         mg,
         code,
@@ -999,7 +1336,11 @@ export class BillingService {
         eimsReason: reason,
         relatedInvoiceId: original.id,
         ...(settled
-          ? { paidAmount: memo.totalAmount, balanceAmount: 0, paidAt: new Date() }
+          ? {
+              paidAmount: memo.totalAmount,
+              balanceAmount: 0,
+              paidAt: new Date(),
+            }
           : {}),
       };
       await mg.update(Invoice, memo.id, patch);
@@ -1059,7 +1400,7 @@ export class BillingService {
       input.dueAt ??
       new Date(
         Date.now() +
-        (input.dueInDays ?? DEFAULT_DUE_DAYS) * 24 * 60 * 60 * 1000,
+          (input.dueInDays ?? DEFAULT_DUE_DAYS) * 24 * 60 * 60 * 1000,
       );
 
     const invoiceNumber = await this.nextInvoiceNumber(mg, code);
@@ -1580,9 +1921,9 @@ export class BillingService {
       dueAt,
       ...(issuing
         ? {
-          status: Freight.InvoiceStatus.Pending,
-          issuedAt: invoice.issuedAt ?? new Date(),
-        }
+            status: Freight.InvoiceStatus.Pending,
+            issuedAt: invoice.issuedAt ?? new Date(),
+          }
         : {}),
     };
     await mg.update(Invoice, { id: invoice.id }, patch);
@@ -1646,10 +1987,7 @@ export class BillingService {
     const repo = this.dataSource.getRepository(Invoice);
     const invoices = await repo.findBy({
       paymentId,
-      status: In([
-        Freight.InvoiceStatus.Issued,
-        Freight.InvoiceStatus.Pending,
-      ]),
+      status: In([Freight.InvoiceStatus.Issued, Freight.InvoiceStatus.Pending]),
     });
     for (const invoice of invoices) {
       await repo.update(
@@ -1823,6 +2161,17 @@ export class BillingService {
         .getRepository(Booking)
         .update({ id: invoice.sourceId }, { pnrCode: billReference });
     }
+    // Same reference, for an ad-hoc additional charge — its own column, since
+    // an AdditionalCharge doesn't own a Booking-scoped `pnrCode` and a booking
+    // can carry many of these at once.
+    if (
+      billReference &&
+      invoice.source === Freight.InvoiceSource.AdditionalCharge
+    ) {
+      await this.dataSource
+        .getRepository(AdditionalCharge)
+        .update({ id: invoice.sourceId }, { paymentReference: billReference });
+    }
 
     // Settlement is driven by the payment API (webhook/outbox → payment.succeeded);
     // billing must not simulate it. Kept for local demos only.

apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.spec.ts

@@ -1,4 +1,4 @@
-import { InvoiceDocumentModel, InvoiceDocumentService } from "./invoice-document.service";
+import { InvoiceDocumentModel, InvoiceDocumentService, sameCompanyName } from "./invoice-document.service";
 
 const model = (over: Partial<InvoiceDocumentModel> = {}): InvoiceDocumentModel => ({
   kind: "INVOICE",
@@ -87,3 +87,38 @@ describe("InvoiceDocumentService.buildThermalHtml", () => {
     expect(html).not.toContain("right: 160px");
   });
 });
+
+describe("sameCompanyName", () => {
+  it("treats eTrade's legal-suffix spellings as the same name", () => {
+    expect(sameCompanyName("ABIJOEL PLC", "ABIJOEL P L C")).toBe(true);
+    expect(
+      sameCompanyName(
+        "WISH TRADING PLC",
+        "WISH  TRADING  PRIVATE LIMITED COMPANY",
+      ),
+    ).toBe(true);
+    expect(
+      sameCompanyName("TUTA TRADING PLC", "TUTA TRADING ONE MEMBER PLC"),
+    ).toBe(true);
+  });
+
+  it("keeps a genuinely different trade name distinct", () => {
+    // Real pairs from eTrade: the licence trades under a different name than
+    // the company registered under, which is exactly the row worth printing.
+    expect(
+      sameCompanyName("Cozy Coffee Grower and Exporter", "ABIJOEL P L C"),
+    ).toBe(false);
+    expect(sameCompanyName("MENNA PRODUCTION", "ICOFFEE TRADING PLC")).toBe(
+      false,
+    );
+    expect(
+      sameCompanyName("YUNABEK TRADING PLC", "YUNABEK INVESTMENT PLC"),
+    ).toBe(false);
+  });
+
+  it("is false when either side is missing, so no row is printed", () => {
+    expect(sameCompanyName("", "ABIJOEL P L C")).toBe(false);
+    expect(sameCompanyName(null, null)).toBe(false);
+    expect(sameCompanyName("ABIJOEL P L C", undefined)).toBe(false);
+  });
+});

apps/edr-freight-api/src/modules/billing/documents/invoice-document.service.ts

@@ -48,6 +48,34 @@ function formatDate(value: unknown): string {
   return value ? new Date(value as string | Date).toLocaleDateString("en-GB") : "-";
 }
 
+/**
+ * Is this trade name just the company name again?
+ *
+ * Compared loosely on purpose: eTrade spells the same legal suffix as "PLC",
+ * "P L C" and "PRIVATE LIMITED COMPANY", and pads names with double spaces, so
+ * an exact comparison would call two spellings of one name different and print
+ * a redundant row. Used only to decide whether a trade-name row is worth
+ * showing — never to decide that two businesses ARE the same.
+ */
+export function sameCompanyName(
+  a: string | null | undefined,
+  b: string | null | undefined,
+): boolean {
+  const norm = (v: string | null | undefined) =>
+    (v ?? "")
+      .toUpperCase()
+      .replace(/[.,]/g, "")
+      .replace(/\s+/g, " ")
+      .trim()
+      .replace(/\bPRIVATE LIMITED COMPANY\b/g, "PLC")
+      .replace(/\bP L C\b/g, "PLC")
+      .replace(/\bONE (MEMBER|PERSON) PLC\b/g, "PLC")
+      .replace(/\s+/g, " ")
+      .trim();
+  const left = norm(a);
+  return left !== "" && left === norm(b);
+}
+
 /** One billed line on the document (charge type / fee type agnostic). */
 export interface InvoiceDocumentLine {
   description: string | null;
@@ -309,7 +337,11 @@ export class InvoiceDocumentService {
     let y = 700;
     const colX = [36, 300];
     const colW = 250;
-    model.summary.slice(0, 16).forEach((row, i) => {
+    // 20, not 16: a booking invoice already fills 16 rows with every optional one present
+    // (buyer trade name, buyer VAT, seller TIN/VAT, IRN, PNR) and the transaction ref is the
+    // 17th — the old cap silently dropped whichever row landed last. Still fits: 20 rows end
+    // at y=423, leaving the line-item table its full run down to the y<190 cut-off.
+    model.summary.slice(0, 20).forEach((row, i) => {
       const x = colX[i % 2];
       if (i % 2 === 0 && i > 0) y -= 27;
       ops.push(textOp((row.label ?? "").toUpperCase(), x, y, 7, "F1", PdfColor.gray));

apps/edr-freight-api/src/modules/billing/dto/filter-invoice.dto.spec.ts

@@ -0,0 +1,55 @@
+import { plainToInstance } from "class-transformer";
+import { validateSync } from "class-validator";
+
+import { FilterInvoiceDto } from "./filter-invoice.dto";
+
+/**
+ * The list endpoint runs under `forbidNonWhitelisted`, so every param the
+ * backoffice filter bar sends has to survive transform + validation here or
+ * the whole request 400s. The CSV filters are the fragile part: they arrive as
+ * one string and must come out as a validated array.
+ */
+const parse = (query: Record<string, string>) => {
+  const dto = plainToInstance(FilterInvoiceDto, query);
+  return { dto, errors: validateSync(dto).map((e) => e.property) };
+};
+
+describe("FilterInvoiceDto", () => {
+  it("accepts the full filter-bar query and splits the CSV filters", () => {
+    const { dto, errors } = parse({
+      page: "2",
+      pageSize: "10",
+      search: "INV-2026",
+      statuses: "PENDING,OVERDUE",
+      sources: "booking,warehouse",
+      types: "PREPAID,WAGON_CANCEL_FEE",
+      eimsStatuses: "NOT_SUBMITTED",
+      currency: "etb",
+      issuedFrom: "2026-08-01T00:00:00.000Z",
+      issuedTo: "2026-08-20T20:59:59.999Z",
+      dueFrom: "2026-08-01T00:00:00.000Z",
+      dueTo: "2026-09-01T20:59:59.999Z",
+      minAmount: "100",
+      maxAmount: "5000",
+      hasBalance: "true",
+      overdue: "false",
+      sortBy: "balanceAmount",
+      sortOrder: "asc",
+    });
+
+    expect(errors).toEqual([]);
+    expect(dto.statuses).toEqual(["PENDING", "OVERDUE"]);
+    expect(dto.sources).toEqual(["booking", "warehouse"]);
+    expect(dto.types).toEqual(["PREPAID", "WAGON_CANCEL_FEE"]);
+    expect(dto.currency).toBe("ETB");
+    expect(dto.minAmount).toBe(100);
+    expect(dto.hasBalance).toBe(true);
+    expect(dto.overdue).toBe(false);
+    expect(dto.sortOrder).toBe("ASC");
+  });
+
+  it("rejects a value outside the enum and an unsortable column", () => {
+    expect(parse({ statuses: "PENDING,NOT_A_STATUS" }).errors).toEqual(["statuses"]);
+    expect(parse({ sortBy: "eimsIrn" }).errors).toEqual(["sortBy"]);
+  });
+});

apps/edr-freight-api/src/modules/billing/dto/filter-invoice.dto.ts

@@ -2,14 +2,44 @@ import { Freight } from "@edr/types";
 import { ApiPropertyOptional } from "@nestjs/swagger";
 import { Transform } from "class-transformer";
 import {
+  IsArray,
+  IsBoolean,
+  IsDateString,
   IsIn,
   IsInt,
+  IsNumber,
   IsOptional,
   IsString,
   IsUUID,
   Min,
 } from "class-validator";
 
+import { EimsInvoiceStatus } from "../../eims/eims-registration.types";
+import { INVOICE_PAYMENT_METHODS } from "../invoice-settlement.util";
+
+/** Columns the invoice list may be ordered by -> their query-builder expression. */
+export const INVOICE_SORT_COLUMNS: Record<string, string> = {
+  issuedAt: "invoice.issuedAt",
+  dueAt: "invoice.dueAt",
+  createdAt: "invoice.createdAt",
+  totalAmount: "invoice.totalAmount",
+  balanceAmount: "invoice.balanceAmount",
+  invoiceNumber: "invoice.invoiceNumber",
+};
+
+/** `?statuses=A,B` -> `["A","B"]`. A bare value stays a one-element list. */
+const csv = ({ value }: { value: unknown }) =>
+  typeof value === "string"
+    ? value
+        .split(",")
+        .map((v) => v.trim())
+        .filter(Boolean)
+    : value;
+
+const bool = ({ value }: { value: unknown }) => value === "true" || value === true;
+
+const num = ({ value }: { value: unknown }) => Number(value);
+
 export class FilterInvoiceDto {
   @ApiPropertyOptional({ default: 1 })
   @IsOptional()
@@ -40,10 +70,122 @@ export class FilterInvoiceDto {
   @IsIn(Object.values(Freight.InvoiceStatus))
   status?: Freight.InvoiceStatus;
 
-  /** Manual-payments worklist only: restrict to one currency. */
+  /**
+   * Multi-select status (`?statuses=PENDING,OVERDUE`). ANDed with `status`
+   * when both are sent, so the single-status worklists keep their meaning.
+   */
+  @ApiPropertyOptional({ isArray: true, enum: Freight.InvoiceStatus })
+  @IsOptional()
+  @Transform(csv)
+  @IsArray()
+  @IsIn(Object.values(Freight.InvoiceStatus), { each: true })
+  statuses?: Freight.InvoiceStatus[];
+
+  /** Originating subsystem (`booking`, `warehouse`, `shipping_line_credit`, …). */
+  @ApiPropertyOptional({ isArray: true, enum: Freight.InvoiceSource })
+  @IsOptional()
+  @Transform(csv)
+  @IsArray()
+  @IsIn(Object.values(Freight.InvoiceSource), { each: true })
+  sources?: Freight.InvoiceSource[];
+
+  /**
+   * What the invoice bills for (`?types=PREPAID,WAGON_CANCEL_FEE`). Free-form
+   * like `paymentMethods`: every billing source mints its own `type` string, so
+   * an `IsIn` here would silently drop a real value.
+   */
+  @ApiPropertyOptional({ isArray: true, example: ["PREPAID"] })
+  @IsOptional()
+  @Transform(csv)
+  @IsArray()
+  @IsString({ each: true })
+  types?: string[];
+
+  /** MoR filing state — Finance's "what still needs registering" cut. */
+  @ApiPropertyOptional({ isArray: true, enum: EimsInvoiceStatus })
+  @IsOptional()
+  @Transform(csv)
+  @IsArray()
+  @IsIn(Object.values(EimsInvoiceStatus), { each: true })
+  eimsStatuses?: EimsInvoiceStatus[];
+
+  /**
+   * Settled payment method (`?paymentMethods=CBE_BILL,BANK_TRANSFER`). Values are
+   * the normalised UPPER_SNAKE vocabulary of `invoicePaymentMethodExpr`. Not
+   * validated against a fixed list — the manual pay endpoint takes a free-form
+   * method, so an `IsIn` here would silently drop a real value.
+   */
+  @ApiPropertyOptional({ isArray: true, enum: INVOICE_PAYMENT_METHODS })
+  @IsOptional()
+  @Transform(csv)
+  @IsArray()
+  @IsString({ each: true })
+  paymentMethods?: string[];
+
+  /** Manual-payments worklist and the invoice list: restrict to one currency. */
   @ApiPropertyOptional({ enum: ["USD", "ETB"] })
   @IsOptional()
   @Transform(({ value }: { value: unknown }) => String(value).toUpperCase())
   @IsIn(["USD", "ETB"])
   currency?: "USD" | "ETB";
+
+  @ApiPropertyOptional({ description: "Issued at or after this instant (ISO)." })
+  @IsOptional()
+  @IsDateString()
+  issuedFrom?: string;
+
+  @ApiPropertyOptional({ description: "Issued at or before this instant (ISO)." })
+  @IsOptional()
+  @IsDateString()
+  issuedTo?: string;
+
+  @ApiPropertyOptional({ description: "Due at or after this instant (ISO)." })
+  @IsOptional()
+  @IsDateString()
+  dueFrom?: string;
+
+  @ApiPropertyOptional({ description: "Due at or before this instant (ISO)." })
+  @IsOptional()
+  @IsDateString()
+  dueTo?: string;
+
+  /** Total amount bounds, in the invoice's own currency — pair with `currency`. */
+  @ApiPropertyOptional()
+  @IsOptional()
+  @Transform(num)
+  @IsNumber()
+  minAmount?: number;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @Transform(num)
+  @IsNumber()
+  maxAmount?: number;
+
+  @ApiPropertyOptional({ description: "Only invoices with an outstanding balance." })
+  @IsOptional()
+  @Transform(bool)
+  @IsBoolean()
+  hasBalance?: boolean;
+
+  /**
+   * Outstanding AND past its due date, computed rather than read off `status`:
+   * nothing sweeps PENDING rows into OVERDUE, so the status alone under-reports.
+   */
+  @ApiPropertyOptional({ description: "Only invoices outstanding past their due date." })
+  @IsOptional()
+  @Transform(bool)
+  @IsBoolean()
+  overdue?: boolean;
+
+  @ApiPropertyOptional({ enum: Object.keys(INVOICE_SORT_COLUMNS), default: "issuedAt" })
+  @IsOptional()
+  @IsIn(Object.keys(INVOICE_SORT_COLUMNS))
+  sortBy?: string;
+
+  @ApiPropertyOptional({ enum: ["ASC", "DESC"], default: "DESC" })
+  @IsOptional()
+  @Transform(({ value }: { value: unknown }) => String(value).toUpperCase())
+  @IsIn(["ASC", "DESC"])
+  sortOrder?: "ASC" | "DESC";
 }

apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.spec.ts

@@ -60,11 +60,7 @@ const context = (over: Partial<EimsMapperContext> = {}): EimsMapperContext => ({
   unitDefault: "PCS",
   incomeWithholdValue: 0,
   transactionWithholdValue: 0,
-  buyerCountryCode: "231", // test-only, not a confirmed real MoR code
-  buyerCountryCodes: {},
-  buyerRegionCodes: { "Addis Ababa": "13" },
-  buyerWeredaCodes: {},
-  buyerCityCodes: {},
+  buyerGeo: { Country: "70", Region: "6", City: "31", Wereda: "190" },
   ...over,
 });
 
@@ -90,26 +86,24 @@ describe("toEimsInvoice", () => {
     expect(doc.SellerDetails).toBe(seller);
   });
 
-  it("maps the buyer from the company row and leaves unmodelled fields null", () => {
+  it("maps the buyer from the company row and omits Id fields for a TIN-identified buyer", () => {
     const doc = toEimsInvoice(invoice(), seller, context());
 
+    // MoR rule 7004 rejects an explicit IdType/IdNumber null — the keys must be absent.
     expect(doc.BuyerDetails).toEqual({
-      City: null,
-      // company.country is "Ethiopia" (the domestic default) — resolves to context's flat
-      // buyerCountryCode fallback, not null, per resolveCountryCode.
-      Country: "231",
+      // Resolved by the registration service before the counter was reserved; the mapper copies.
+      City: "31",
+      Country: "70",
       Email: "buyer@abc.et",
       HouseNumber: "NEW",
-      IdNumber: null,
-      IdType: null,
       Tin: "0999930000",
       LegalName: "ABC Trading PLC",
       Phone: "0912345678",
-      Region: "13",
+      Region: "6",
       Zone: "SHA",
       Kebele: "03",
       VatNumber: "123475885858",
-      Wereda: "574",
+      Wereda: "190",
     });
   });
 
@@ -284,108 +278,39 @@ describe("toEimsInvoice", () => {
 });
 
 describe("toEimsInvoice — MoR field constraints", () => {
-  it("passes a buyer region through when it is already a MoR code", () => {
+  /**
+   * Geography is no longer resolved here. `resolveMorGeo` runs in the registration service, ahead
+   * of the counter reservation, and hands the mapper finished MoR codes — so what these cover is
+   * that the resolved values reach the right `BuyerDetails` fields untouched. The lookup rules
+   * themselves (hierarchy, aliases, ambiguity) are covered in `mor-location.resolver.spec.ts`.
+   */
+  it("puts the resolved MoR codes on BuyerDetails, unmodified and as strings", () => {
     const doc = toEimsInvoice(invoice(), seller, context());
-    expect(doc.BuyerDetails.Region).toBe("13");
+
+    expect(doc.BuyerDetails.Country).toBe("70");
+    expect(doc.BuyerDetails.Region).toBe("6");
+    expect(doc.BuyerDetails.City).toBe("31");
+    expect(doc.BuyerDetails.Wereda).toBe("190");
+    for (const field of ["Country", "Region", "City", "Wereda"] as const) {
+      expect(typeof doc.BuyerDetails[field]).toBe("string");
+    }
   });
 
-  it("maps a region name to its code, ignoring case and spacing", () => {
-    const doc = toEimsInvoice(
-      invoice({ company: { ...invoice().company!, region: "  addis   ababa " } }),
-      seller,
-      context({ buyerRegionCodes: { "Addis Ababa": "13" } }),
-    );
-    expect(doc.BuyerDetails.Region).toBe("13");
-  });
-
-  it("refuses to file a buyer whose region has no mapping", () => {
-    expect(() =>
-      toEimsInvoice(
-        invoice({ company: { ...invoice().company!, region: "Somewhere Else" } }),
-        seller,
-        context(),
-      ),
-    ).toThrow(/not a MoR Region code and has no mapping/);
-  });
-
-  it("refuses a buyer with no region at all rather than guessing one", () => {
-    expect(() =>
-      toEimsInvoice(
-        invoice({ company: { ...invoice().company!, region: null } }),
-        seller,
-        context(),
-      ),
-    ).toThrow(/buyer Region \(unset\)/);
-  });
-
-  it("passes a buyer wereda through when it is already a MoR code", () => {
+  it("never emits an Open Admin Data ETxx identifier as a location", () => {
     const doc = toEimsInvoice(invoice(), seller, context());
-    expect(doc.BuyerDetails.Wereda).toBe("574");
+    for (const field of ["Country", "Region", "City", "Wereda"] as const) {
+      expect(doc.BuyerDetails[field]).toMatch(/^[0-9]+$/);
+    }
   });
 
-  it("maps a wereda name to its code", () => {
+  it("keeps BuyerDetails.Zone as the buyer's own zone name — MoR takes that one as prose", () => {
     const doc = toEimsInvoice(
-      invoice({ company: { ...invoice().company!, woreda: "Yeka" } }),
+      invoice({ company: { ...invoice().company!, zone: "Fafen" } }),
       seller,
-      context({ buyerWeredaCodes: { Yeka: "99" } }),
+      context(),
     );
-    expect(doc.BuyerDetails.Wereda).toBe("99");
-  });
-
-  it("refuses to file a buyer whose wereda has no mapping", () => {
-    expect(() =>
-      toEimsInvoice(
-        invoice({ company: { ...invoice().company!, woreda: "Yeka" } }),
-        seller,
-        context({ buyerWeredaCodes: {} }),
-      ),
-    ).toThrow(/buyer Wereda "Yeka".*EIMS_BUYER_WEREDA_CODES/);
-  });
-
-  it("derives City from the buyer's zone via the city code map", () => {
-    const doc = toEimsInvoice(
-      invoice({ company: { ...invoice().company!, zone: "Kirkos" } }),
-      seller,
-      context({ buyerCityCodes: { Kirkos: "101" } }),
-    );
-    expect(doc.BuyerDetails.City).toBe("101");
-  });
-
-  it("leaves City null (not a throw) when the buyer's zone has no city mapping — City is optional", () => {
-    const doc = toEimsInvoice(
-      invoice({ company: { ...invoice().company!, zone: "Somewhere Else" } }),
-      seller,
-      context({ buyerCityCodes: {} }),
-    );
-    expect(doc.BuyerDetails.City).toBeNull();
-  });
-
-  it("maps a buyer country name to its code via the country code map", () => {
-    const doc = toEimsInvoice(
-      invoice({ company: { ...invoice().company!, country: "Djibouti" } }),
-      seller,
-      context({ buyerCountryCodes: { Djibouti: "071" } }),
-    );
-    expect(doc.BuyerDetails.Country).toBe("071");
-  });
-
-  it("falls back to the flat domestic country code only for Ethiopia, not any unmapped country", () => {
-    const doc = toEimsInvoice(
-      invoice({ company: { ...invoice().company!, country: "Ethiopia" } }),
-      seller,
-      context({ buyerCountryCode: "231", buyerCountryCodes: {} }),
-    );
-    expect(doc.BuyerDetails.Country).toBe("231");
-  });
-
-  it("refuses a genuinely foreign buyer country with no mapping — never silently files it as Ethiopia", () => {
-    expect(() =>
-      toEimsInvoice(
-        invoice({ company: { ...invoice().company!, country: "Kenya" } }),
-        seller,
-        context({ buyerCountryCode: "231", buyerCountryCodes: {} }),
-      ),
-    ).toThrow(/buyer Country "Kenya".*EIMS_BUYER_COUNTRY_CODES/);
+    expect(doc.BuyerDetails.Zone).toBe("Fafen");
+    expect(doc.BuyerDetails.City).toBe("31");
   });
 
   it("emits NatureOfSupplies lowercase, whatever case it was configured in", () => {

apps/edr-freight-api/src/modules/billing/eims-invoice.mapper.ts

@@ -15,6 +15,7 @@
  * authoritative: they are passed through or overridable rather than validated against a fixed set.
  */
 
+import { MorGeoCodes } from "../../config/mor-location.resolver";
 import { round2 } from "./invoice-settlement.util";
 
 /** Only proven-required constant: the 400 SCHEMA ERROR sample rejects a payload without it. */
@@ -34,8 +35,9 @@ export interface EimsBuyerDetails {
   City: string | null;
   Email: string | null;
   HouseNumber: string | null;
-  IdNumber: string | null;
-  IdType: string | null;
+  /** Omitted entirely for a TIN-identified buyer — MoR rule 7004 rejects an explicit null. */
+  IdNumber?: string;
+  IdType?: string;
   Tin: string;
   LegalName: string;
   Phone: string | null;
@@ -235,35 +237,15 @@ export interface EimsMapperContext {
    */
   relatedDocument?: string | null;
   /**
-   * Domestic fallback only, applied when `company.country` is empty or "Ethiopia" and not already
-   * in `buyerCountryCodes` — see that field. Never applied to a genuinely foreign buyer.
-   */
-  buyerCountryCode?: string | null;
-  /** Country name → MoR code. Format unconfirmed, so looked up by name only, not digit-validated. */
-  buyerCountryCodes: Record<string, string>;
-  /**
-   * Region name → MoR numeric code, for buyers whose stored region is free text.
+   * The buyer's MoR location codes — `Country`/`Region`/`City`/`Wereda`, already resolved from the
+   * Ministry's location master by `resolveMorGeo`.
    *
-   * `companies.region` holds names ("Addis Ababa") while MoR validates `BuyerDetails.Region`
-   * against `^[0-9]{1,3}$`. A stored value that is already a code passes through; anything else
-   * must be in this map or the mapping **fails locally** — sending a guessed region code onto a
-   * tax document is worse than refusing to file.
+   * Resolved by the caller, not here, and deliberately so: geographic resolution can fail (unknown
+   * or ambiguous address) and that failure must happen **before** an EIMS counter is reserved, so a
+   * bad company address never burns a sequence number. See `mor-location.resolver.ts` for why the
+   * lookup has to be hierarchical, and `EimsInvoiceRegistrationService` for where it runs.
    */
-  buyerRegionCodes: Record<string, string>;
-  /**
-   * Wereda name → MoR code, same shape as `buyerRegionCodes`. `companies.woreda` holds names
-   * ("Yeka") or codes inconsistently; unlike Region, MoR has never named a Wereda regex in an
-   * error, so this is precautionary rather than confirmed — but the fix is identical either way:
-   * fail locally on an unmapped name rather than file a guess.
-   */
-  buyerWeredaCodes: Record<string, string>;
-  /**
-   * Buyer *zone* name → MoR City code. `Company` has no dedicated city column; Zone is the
-   * closest match in EDR's own data. Unlike Region/Wereda, City is optional — MoR has already
-   * accepted a live filing with it null — so an unmapped zone resolves to null, it does not fail
-   * the mapping.
-   */
-  buyerCityCodes: Record<string, string>;
+  buyerGeo: MorGeoCodes;
   buyerIdType?: string | null;
   buyerIdNumber?: string | null;
   /** Required when the invoice currency is not ETB. */
@@ -273,14 +255,6 @@ export interface EimsMapperContext {
   formatDate?: (issuedAt: Date) => string;
 }
 
-/**
- * MoR's own constraint on `Region`: one to three digits, confirmed by its 400 SCHEMA ERROR. Reused
- * as the pass-through test for `Wereda` too — every Wereda value MoR has actually shown us (seller
- * "12"/"13", the collection's "574") fits the same shape, though MoR has not named a Wereda regex
- * the way it named Region's.
- */
-const LOCATION_CODE = /^[0-9]{1,3}$/;
-
 /**
  * The only two values MoR accepts for `NatureOfSupplies`, lowercase.
  *
@@ -309,87 +283,6 @@ export const formatEimsDate = (issuedAt: Date): string =>
  * an unissued invoice, unresolved line tax, a line/total mismatch, or a non-ETB invoice with no
  * exchange rate.
  */
-/**
- * A buyer's location value (Region, Wereda or City) as a MoR code: passed through when already
- * numeric, otherwise looked up by name (case- and space-insensitive).
- *
- * Region/Wereda are required: an unmapped value throws — sending a guessed code onto a tax
- * document is worse than refusing to file. City is optional (`required: false`, City's own
- * caller) — MoR has already accepted a live filing with it null, so an unmapped zone resolves to
- * null instead of blocking the invoice.
- */
-function resolveLocationCode(
-  field: "Region" | "Wereda" | "City",
-  value: string | null | undefined,
-  codes: Record<string, string>,
-  envVar: string,
-  invoiceNumber: string,
-  opts: { required?: boolean } = {},
-): string | null {
-  const raw = (value ?? "").trim();
-  if (LOCATION_CODE.test(raw)) return raw;
-
-  const key = raw.toLowerCase().replace(/\s+/g, " ");
-  const mapped = Object.entries(codes).find(
-    ([name]) => name.trim().toLowerCase().replace(/\s+/g, " ") === key,
-  )?.[1];
-  if (mapped && LOCATION_CODE.test(mapped)) return mapped;
-
-  if (opts.required === false) return null;
-
-  throw new Error(
-    `EIMS mapping: invoice ${invoiceNumber} has buyer ${field} ${raw ? `"${raw}"` : "(unset)"}, ` +
-      `which is not a MoR ${field} code and has no mapping. Add it to ${envVar}.`,
-  );
-}
-
-/**
- * A buyer's `Country` as a MoR code: looked up by name in `codes` first; when unmapped, applies
- * `domesticFallback` only if the stored country is empty or "Ethiopia" (the DB column's default).
- * A genuinely foreign, unmapped country throws rather than silently filing as Ethiopia — same
- * "fail locally, don't guess" rule as `resolveLocationCode`, but never digit-validated: MoR's
- * Country code format is unconfirmed, unlike Region/Wereda's proven `^[0-9]{1,3}$`.
- */
-function resolveCountryCode(
-  country: string | null | undefined,
-  codes: Record<string, string>,
-  domesticFallback: string | null,
-  invoiceNumber: string,
-): string | null {
-  const raw = (country ?? "").trim();
-  const key = raw.toLowerCase().replace(/\s+/g, " ");
-  const mapped = Object.entries(codes).find(
-    ([name]) => name.trim().toLowerCase().replace(/\s+/g, " ") === key,
-  )?.[1];
-  if (mapped) return mapped;
-
-  if ((!raw || key === "ethiopia") && domesticFallback) return domesticFallback;
-
-  throw new Error(
-    `EIMS mapping: invoice ${invoiceNumber} has buyer Country "${raw || "(unset)"}", which has no ` +
-      "MoR country code mapping. Add it to EIMS_BUYER_COUNTRY_CODES.",
-  );
-}
-
-/**
- * Same name-or-code resolution as `resolveLocationCode`, for a caller with no invoice to attach an
- * error to and that must never throw — currently only `EimsSellerCacheService`, resolving
- * e-Trade's region/zone/woreda *names* for EDR's own seller identity. Pass-through numeric code,
- * name lookup, `undefined` on no match — the caller falls back to static config either way.
- */
-export function resolveOptionalCode(
-  value: string | null | undefined,
-  codes: Record<string, string>,
-): string | undefined {
-  const raw = (value ?? "").trim();
-  if (LOCATION_CODE.test(raw)) return raw;
-  const key = raw.toLowerCase().replace(/\s+/g, " ");
-  const mapped = Object.entries(codes).find(
-    ([name]) => name.trim().toLowerCase().replace(/\s+/g, " ") === key,
-  )?.[1];
-  return mapped && LOCATION_CODE.test(mapped) ? mapped : undefined;
-}
-
 export function toEimsInvoice(
   invoice: EimsMapperInvoice,
   seller: EimsSellerDetails,
@@ -511,46 +404,24 @@ export function toEimsInvoice(
 
   return {
     BuyerDetails: {
-      // No dedicated city column on Company — Zone is the closest match; optional (see
-      // resolveLocationCode's City comment).
-      City: resolveLocationCode(
-        "City",
-        company.zone,
-        context.buyerCityCodes,
-        "EIMS_BUYER_CITY_CODES",
-        invoice.invoiceNumber,
-        { required: false },
-      ),
+      // Country/Region/City/Wereda are MoR location codes resolved from the Ministry's own
+      // location master *before* this mapper ran, and before an EIMS counter was reserved — see
+      // EimsMapperContext.buyerGeo. `Zone` alongside them is the buyer's free-text zone name,
+      // which MoR takes as prose, not a code.
+      City: context.buyerGeo.City,
       Email: company.email ?? null,
       HouseNumber: company.houseNo ?? null,
-      IdNumber: context.buyerIdNumber ?? null,
-      IdType: context.buyerIdType ?? null,
+      ...(context.buyerIdNumber != null ? { IdNumber: context.buyerIdNumber } : {}),
+      ...(context.buyerIdType != null ? { IdType: context.buyerIdType } : {}),
       Tin: company.tin,
       LegalName: company.name,
       Phone: company.phone ?? null,
-      Region: resolveLocationCode(
-        "Region",
-        company.region,
-        context.buyerRegionCodes,
-        "EIMS_BUYER_REGION_CODES",
-        invoice.invoiceNumber,
-      ),
-      Country: resolveCountryCode(
-        company.country,
-        context.buyerCountryCodes,
-        context.buyerCountryCode ?? null,
-        invoice.invoiceNumber,
-      ),
+      Region: context.buyerGeo.Region,
+      Country: context.buyerGeo.Country,
       Zone: company.zone ?? null,
       Kebele: company.kebele ?? null,
       VatNumber: company.vatNumber ?? null,
-      Wereda: resolveLocationCode(
-        "Wereda",
-        company.woreda,
-        context.buyerWeredaCodes,
-        "EIMS_BUYER_WEREDA_CODES",
-        invoice.invoiceNumber,
-      ),
+      Wereda: context.buyerGeo.Wereda,
     },
     DocumentDetails: {
       DocumentNumber: context.documentNumber,

apps/edr-freight-api/src/modules/billing/entities/invoice.entity.ts

@@ -203,4 +203,12 @@ export class Invoice extends BaseEntity {
   @ManyToOne(() => Invoice)
   @JoinColumn({ name: "related_invoice_id" })
   relatedInvoice?: Invoice | null;
+
+  /**
+   * Which `POST /v1/bulkRegister` batch this invoice was submitted in, if any — MoR's own
+   * conversation id, not one we generate. Lets a stuck batch (webhook never arrived) be found and
+   * reconciled. Null for every invoice filed through single `/v1/register`.
+   */
+  @Column({ name: "eims_bulk_conversation_id", type: "text", nullable: true })
+  eimsBulkConversationId?: string | null;
 }

apps/edr-freight-api/src/modules/billing/invoice-settlement.util.spec.ts

@@ -0,0 +1,50 @@
+import { settlementReferences } from "./invoice-settlement.util";
+
+describe("settlementReferences", () => {
+  it("returns the provider reference recorded on the invoice ledger", () => {
+    expect(
+      settlementReferences({
+        payments: [{ reference: "FT26082700123" }],
+      }),
+    ).toBe("FT26082700123");
+  });
+
+  it("reads the linked gateway payment row when the ledger has no reference", () => {
+    expect(
+      settlementReferences({
+        payments: [{ reference: null }],
+        payment: { transactionId: "TB998877" },
+      }),
+    ).toBe("TB998877");
+  });
+
+  it("does not repeat a reference that both sources carry", () => {
+    expect(
+      settlementReferences({
+        payments: [{ reference: "FT26082700123" }],
+        payment: { transactionId: "FT26082700123" },
+      }),
+    ).toBe("FT26082700123");
+  });
+
+  it("lists every leg of a partially-then-fully paid invoice, oldest first", () => {
+    expect(
+      settlementReferences({
+        payments: [{ reference: "SLIP-001" }, { reference: "FT26082700123" }],
+      }),
+    ).toBe("SLIP-001, FT26082700123");
+  });
+
+  it("drops the internal intent id the gateway path falls back to", () => {
+    expect(
+      settlementReferences({
+        payments: [{ reference: "3f8a1c2e-9b4d-4a71-8c6e-2d5f7a9b1c30" }],
+      }),
+    ).toBeNull();
+  });
+
+  it("is null for an unpaid invoice", () => {
+    expect(settlementReferences({ payments: [] })).toBeNull();
+    expect(settlementReferences({})).toBeNull();
+  });
+});

apps/edr-freight-api/src/modules/billing/invoice-settlement.util.ts

@@ -34,3 +34,84 @@ export function applySettlement(
   const balanceAmount = Math.max(0, round2(total - paidAmount));
   return { paidAmount, balanceAmount, fullyPaid: paidAmount >= total };
 }
+
+/**
+ * SQL for an invoice's settled payment method, normalised to one vocabulary.
+ *
+ * Two sources have to be merged: gateway settlements carry the real provider on
+ * the linked `freight.payments` row (`cbe-bill`, `telebirr`, …) while the
+ * invoice's own `payments` ledger only records a flat `"GATEWAY"`; manual
+ * settlements have no payments row at all and the ledger is the ONLY source
+ * (`BANK_TRANSFER`, `OFFLINE`, or whatever `PayInvoiceDto.method` carried).
+ * So: provider first, newest ledger entry as the fallback.
+ *
+ * `-> -1` is the last ledger element — the ledger is appended newest-last.
+ * `::text` is not cosmetic: `payments.method` is a real Postgres enum, and
+ * COALESCE against a text fallback fails without the cast.
+ *
+ * Normalised UPPER_SNAKE so `cbe-bill` and a hand-typed `CBE_BILL` are one
+ * value on screen, in the filter and in the export.
+ */
+export const invoicePaymentMethodExpr = (invoice: string, payment: string): string =>
+  `UPPER(REPLACE(COALESCE(${payment}.method::text, ${invoice}.payments -> -1 ->> 'method'), '-', '_'))`;
+
+/**
+ * The methods the filter offers. Not exhaustive by construction — the manual
+ * pay endpoint takes a free-form `method` string — so nothing validates against
+ * this list; it is the pick-list, not a constraint.
+ */
+export const INVOICE_PAYMENT_METHODS = [
+  "TELEBIRR",
+  "CBE_BIRR",
+  "CBE_BILL",
+  "EBIRR",
+  "WAAFI",
+  "CARD",
+  "DMONEY",
+  "CAC_BANK",
+  "BANK_TRANSFER",
+  "OFFLINE",
+  /** Settled at a gateway whose provider row is no longer linked. */
+  "GATEWAY",
+] as const;
+
+/** Anything shaped enough to read settlement references off. */
+interface SettlementReferenceSource {
+  payments?: Array<{ reference?: string | null }> | null;
+  payment?: { transactionId?: string | null } | null;
+}
+
+/**
+ * A settlement reference is the PROVIDER's own transaction number, never ours.
+ * The gateway path falls back to the intent id when a provider returns no txn
+ * ref (`markInvoiceAsPaid`: `providerTxnId ?? paymentId`), and that id is a
+ * uuid — an internal correlation key that means nothing to a payer holding a
+ * bank slip, so it is dropped rather than printed. No provider's reference is
+ * uuid-shaped: CBE sends `FT…`, telebirr/ebirr/waafi send digit strings.
+ */
+const INTERNAL_ID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+
+/**
+ * Every provider transaction reference recorded against an invoice, oldest
+ * first, joined for display — CBE's `FT…`, telebirr's receipt number, or the
+ * bank-slip number a teller typed into a manual settlement. Null when nothing
+ * identifiable was recorded.
+ *
+ * Reads BOTH sources because neither alone is complete: the invoice's own
+ * ledger is the only record of manual settlements and of each leg of a
+ * partially-paid invoice, while the linked `freight.payments` row is the only
+ * place a provider txn id lands when it arrives after settlement (a webhook
+ * that stamps `transactionId` on an already-settled intent). Deduped, since
+ * the ordinary gateway path writes the same value to both.
+ */
+export function settlementReferences(
+  invoice: SettlementReferenceSource,
+): string | null {
+  const refs = [
+    ...(invoice.payments ?? []).map((p) => p.reference),
+    invoice.payment?.transactionId,
+  ].filter(
+    (ref): ref is string => Boolean(ref) && !INTERNAL_ID.test(ref as string),
+  );
+  return [...new Set(refs)].join(", ") || null;
+}

apps/edr-freight-api/src/modules/bookings/ad-hoc-label.spec.ts

@@ -0,0 +1,33 @@
+import { adHocLabel } from './clearance.util';
+
+/**
+ * The customer's typed document name travels to the API inside the multipart
+ * field code (`custom_<slug>_<n>`) — the only channel a part has — and comes
+ * back out here for GL's review grid. Mirror of `adHocSlug` in the portal's
+ * useClearanceFlow.
+ */
+const adHocSlug = (name: string) =>
+  name
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+
+const roundTrip = (typed: string) => adHocLabel(`custom_${adHocSlug(typed)}_17877000000000`);
+
+describe('adHocLabel', () => {
+  it('recovers the name the customer typed', () => {
+    expect(roundTrip('Special permit')).toBe('Special permit');
+    expect(roundTrip('Fumigation Certificate')).toBe('Fumigation certificate');
+    expect(roundTrip('bank  slip #2')).toBe('Bank slip 2');
+  });
+
+  it('returns null when there is no name to show, so callers use the filename', () => {
+    expect(roundTrip('')).toBeNull();
+    // Legacy uploads keyed `custom_<timestamp>_<n>` carry no name — without the
+    // digits guard this would surface "1755780000000" as the document label.
+    expect(adHocLabel('custom_1755780000000_0')).toBeNull();
+    expect(adHocLabel('commercial_invoice')).toBeNull();
+  });
+});

apps/edr-freight-api/src/modules/bookings/additional-charge.repository.ts

@@ -0,0 +1,13 @@
+import { BaseRepository } from '@edr/api-common';
+import { Injectable } from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+import { AdditionalCharge } from './entities/additional-charge.entity';
+
+@Injectable()
+export class AdditionalChargeRepository extends BaseRepository<AdditionalCharge> {
+  constructor(@InjectRepository(AdditionalCharge) repository: Repository<AdditionalCharge>) {
+    super(repository);
+  }
+}

apps/edr-freight-api/src/modules/bookings/additional-charge.service.ts

@@ -0,0 +1,314 @@
+import { ConflictException, Injectable, Logger, NotFoundException } from '@nestjs/common';
+import { OnEvent } from '@nestjs/event-emitter';
+import { DataSource, EntityManager } from 'typeorm';
+import { ExchangeService } from '@edr/api-common';
+import { Freight, NotificationAudience, NotificationType } from '@edr/types';
+
+import { BillingService, InvoiceEventPayload } from '../billing/billing.service';
+import { Invoice } from '../billing/entities/invoice.entity';
+import { FilesService } from '../files/files.service';
+import { NotificationsService } from '../notifications/notifications.service';
+import { NotificationInboxService } from '../notification-inbox/notification-inbox.service';
+import { sendCompanyChannels } from '../notifications/notify-company.util';
+import { FREIGHT_PERMS } from '../../seed/freight-permissions.registry';
+import { BookingsService } from './bookings.service';
+import { BookingsRepository } from './bookings.repository';
+import { AdditionalChargeRepository } from './additional-charge.repository';
+import { AdditionalCharge } from './entities/additional-charge.entity';
+import { CreateAdditionalChargeDto } from './dto/additional-charge.dto';
+
+const FILE_RESOURCE = 'additional_charges';
+
+/**
+ * Ad-hoc extra charges finance raises against a booking, independent of
+ * `BookingClearanceCharge` (which is capped at one PORT_CHARGES/MISCELLANEOUS
+ * row per booking). Any number per booking, free-text reason. DRAFT until
+ * sent; sending issues the payable invoice and notifies the customer
+ * (in-app + SMS + email). Settles via `additional_charge.invoice.paid`,
+ * same event-driven pattern as every other invoice source.
+ */
+@Injectable()
+export class AdditionalChargeService {
+  private readonly logger = new Logger(AdditionalChargeService.name);
+
+  constructor(
+    private readonly dataSource: DataSource,
+    private readonly repository: AdditionalChargeRepository,
+    private readonly bookingsRepository: BookingsRepository,
+    private readonly filesService: FilesService,
+    private readonly exchangeService: ExchangeService,
+    private readonly billing: BillingService,
+    private readonly bookingsService: BookingsService,
+    private readonly notifications: NotificationsService,
+    private readonly inbox: NotificationInboxService,
+  ) {}
+
+  private async findOwned(bookingId: string, chargeId: string): Promise<AdditionalCharge> {
+    const charge = await this.repository.findById(chargeId);
+    if (!charge || charge.bookingId !== bookingId) {
+      throw new NotFoundException('Additional charge not found');
+    }
+    return charge;
+  }
+
+  async list(bookingId: string): Promise<Freight.AdditionalCharge[]> {
+    const rows = await this.repository.findAll({
+      where: { bookingId },
+      order: { createdAt: 'DESC' },
+    });
+    return this.toDtoList(rows);
+  }
+
+  async create(
+    bookingId: string,
+    dto: CreateAdditionalChargeDto,
+    staffId: string,
+    file?: Express.Multer.File,
+  ): Promise<Freight.AdditionalCharge[]> {
+    const booking = await this.bookingsService.findById(bookingId);
+    const shouldSend = dto.action === 'send';
+
+    const chargeId = await this.dataSource.transaction(async (manager) => {
+      const repo = manager.getRepository(AdditionalCharge);
+      let saved = await repo.save(
+        repo.create({
+          bookingId,
+          reason: dto.reason.trim(),
+          amount: dto.amount.toFixed(2),
+          currency: dto.currency.trim().toUpperCase(),
+          dueAt: dto.dueDate ? new Date(dto.dueDate) : null,
+          status: 'DRAFT',
+          createdByStaffId: staffId,
+        }),
+      );
+
+      if (file) {
+        const record = await this.filesService.upload({
+          resourceId: saved.id,
+          resource: FILE_RESOURCE,
+          code: FILE_RESOURCE,
+          file,
+          uploadedByUserId: staffId,
+        });
+        await repo.update(saved.id, { fileRecordId: record.id });
+      }
+
+      if (shouldSend) {
+        saved = await this.issueInvoice(manager, saved.id, booking, staffId);
+      }
+      return saved.id;
+    });
+
+    if (shouldSend) await this.notifyCustomerSent(chargeId);
+    return this.list(bookingId);
+  }
+
+  async send(bookingId: string, chargeId: string, staffId: string): Promise<Freight.AdditionalCharge[]> {
+    const charge = await this.findOwned(bookingId, chargeId);
+    if (charge.status !== 'DRAFT') {
+      throw new ConflictException('Only a draft charge can be sent.');
+    }
+    const booking = await this.bookingsService.findById(bookingId);
+
+    await this.dataSource.transaction((manager) =>
+      this.issueInvoice(manager, charge.id, booking, staffId),
+    );
+    await this.notifyCustomerSent(charge.id);
+    return this.list(bookingId);
+  }
+
+  /** Issues the invoice and flips DRAFT → SENT. Notification happens after commit — never inside the transaction. */
+  private async issueInvoice(
+    manager: EntityManager,
+    chargeId: string,
+    booking: { id: string; companyId?: string | null; companyProfileId?: string | null; reference?: string | null },
+    staffId: string,
+  ): Promise<AdditionalCharge> {
+    const repo = manager.getRepository(AdditionalCharge);
+    const charge = await repo.findOneByOrFail({ id: chargeId });
+
+    const invoice = await this.billing.generateInvoice(
+      {
+        source: Freight.InvoiceSource.AdditionalCharge,
+        sourceId: charge.id,
+        type: 'ADDITIONAL_CHARGE',
+        companyId: booking.companyId,
+        companyProfileId: booking.companyProfileId,
+        currency: charge.currency,
+        // Unset falls through to BillingService's own DEFAULT_DUE_DAYS (14).
+        dueAt: charge.dueAt ?? undefined,
+        lines: [
+          {
+            chargeType: 'ADDITIONAL_CHARGE',
+            description: `${charge.reason} — ${booking.reference ?? booking.id}`,
+            amount: Number(charge.amount),
+          },
+        ],
+      },
+      manager,
+    );
+
+    await repo.update(charge.id, {
+      status: 'SENT',
+      invoiceId: invoice.id,
+      sentByStaffId: staffId,
+      sentAt: new Date(),
+    });
+    this.logger.log(
+      `Additional charge ${charge.id} on booking ${booking.id} sent as invoice ${invoice.invoiceNumber}`,
+    );
+    return repo.findOneByOrFail({ id: charge.id });
+  }
+
+  private async notifyCustomerSent(chargeId: string): Promise<void> {
+    try {
+      const charge = await this.repository.findById(chargeId);
+      if (!charge) return;
+      const booking = await this.bookingsService.findById(charge.bookingId);
+      if (!booking.companyId) return;
+      const body = `A new charge of ${charge.amount} ${charge.currency} has been added to booking ${booking.reference ?? charge.bookingId}: ${charge.reason}. Pay via the portal.`;
+      await this.inbox.notify({
+        recipients: { companyId: booking.companyId },
+        audience: NotificationAudience.PORTAL,
+        type: NotificationType.INVOICE_ISSUED,
+        title: 'New charge on your booking',
+        body,
+        link: `/bookings/${charge.bookingId}`,
+        data: {
+          bookingId: charge.bookingId,
+          chargeId: charge.id,
+          amount: Number(charge.amount),
+          currency: charge.currency,
+        },
+      });
+      await sendCompanyChannels(this.dataSource, this.notifications, booking.companyId, body);
+    } catch (err) {
+      this.logger.warn(`Additional charge sent-notify failed for ${chargeId}: ${(err as Error).message}`);
+    }
+  }
+
+  async cancel(
+    bookingId: string,
+    chargeId: string,
+    staffId: string,
+    reason?: string,
+  ): Promise<Freight.AdditionalCharge[]> {
+    const charge = await this.findOwned(bookingId, chargeId);
+    if (charge.status !== 'DRAFT' && charge.status !== 'SENT') {
+      throw new ConflictException('Only a draft or unpaid charge can be cancelled.');
+    }
+    if (charge.status === 'SENT' && charge.invoiceId) {
+      await this.billing.cancelInvoice(charge.invoiceId);
+    }
+    await this.repository.update(charge.id, {
+      status: 'CANCELLED',
+      cancelledByStaffId: staffId,
+      cancelledAt: new Date(),
+      cancelReason: reason ?? null,
+    });
+    return this.list(bookingId);
+  }
+
+  /** Gateway and manual settlements both land here (`${source}.invoice.paid`). */
+  @OnEvent('additional_charge.invoice.paid')
+  async onChargeInvoicePaid(payload: InvoiceEventPayload): Promise<void> {
+    const charge = await this.repository.findById(payload.sourceId);
+    if (!charge || charge.status === 'PAID') return;
+    await this.repository.update(charge.id, { status: 'PAID', paidAt: new Date() });
+
+    try {
+      const booking = await this.bookingsService.findById(charge.bookingId);
+      if (!booking.companyId) return;
+      const body = `Payment received for ${charge.amount} ${charge.currency} on booking ${booking.reference ?? charge.bookingId}: ${charge.reason}.`;
+      await this.inbox.notify({
+        recipients: { companyId: booking.companyId },
+        audience: NotificationAudience.PORTAL,
+        type: NotificationType.PAYMENT_RECEIVED,
+        title: 'Charge payment received',
+        body,
+        link: `/bookings/${charge.bookingId}`,
+        data: { bookingId: charge.bookingId, chargeId: charge.id },
+      });
+      await this.inbox.notify({
+        recipients: { permissionKeys: [FREIGHT_PERMS.additionalCharges.getNotification] },
+        audience: NotificationAudience.BACKOFFICE,
+        type: NotificationType.PAYMENT_RECEIVED,
+        title: 'Additional charge paid',
+        body,
+        link: `/bookings/${charge.bookingId}`,
+        data: { bookingId: charge.bookingId, chargeId: charge.id },
+      });
+    } catch (err) {
+      this.logger.warn(`Additional charge paid-notify failed for ${charge.id}: ${(err as Error).message}`);
+    }
+  }
+
+  private async toDtoList(rows: AdditionalCharge[]): Promise<Freight.AdditionalCharge[]> {
+    if (!rows.length) return [];
+
+    const filesByCharge = await this.filesService.findByResourceIdsGrouped(
+      rows.map((r) => r.id),
+      FILE_RESOURCE,
+    );
+    const names = await this.bookingsRepository.resolveStaffNames(
+      rows.flatMap((r) => [r.createdByStaffId, r.sentByStaffId]),
+    );
+
+    const invoiceIds = rows.map((r) => r.invoiceId).filter((id): id is string => Boolean(id));
+    const invoices = invoiceIds.length
+      ? await this.dataSource.getRepository(Invoice).find({ where: invoiceIds.map((id) => ({ id })) })
+      : [];
+    const invoiceById = new Map(invoices.map((i) => [i.id, i]));
+    const converted = await Promise.all(rows.map((r) => this.convertAmount(r)));
+    const convertedById = new Map(rows.map((r, i) => [r.id, converted[i]]));
+
+    return rows.map((r) => {
+      const file = filesByCharge.get(r.id)?.[0];
+      const fx = convertedById.get(r.id) ?? null;
+      return {
+        id: r.id,
+        bookingId: r.bookingId,
+        reason: r.reason,
+        status: r.status,
+        amount: Number(r.amount),
+        currency: r.currency,
+        convertedAmount: fx?.amount ?? null,
+        convertedCurrency: fx?.currency ?? null,
+        dueAt: r.dueAt?.toISOString() ?? null,
+        file: file ? { id: file.id, name: file.name, url: file.url } : null,
+        invoiceId: r.invoiceId ?? null,
+        invoiceNumber: r.invoiceId ? (invoiceById.get(r.invoiceId)?.invoiceNumber ?? null) : null,
+        paymentReference: r.paymentReference ?? null,
+        createdByName: r.createdByStaffId ? (names.get(r.createdByStaffId) ?? null) : null,
+        createdAt: r.createdAt.toISOString(),
+        sentByName: r.sentByStaffId ? (names.get(r.sentByStaffId) ?? null) : null,
+        sentAt: r.sentAt?.toISOString() ?? null,
+        paidAt: r.paidAt?.toISOString() ?? null,
+        cancelledAt: r.cancelledAt?.toISOString() ?? null,
+        cancelReason: r.cancelReason ?? null,
+      };
+    });
+  }
+
+  /**
+   * Amount converted to the other of ETB/USD, via the existing shared
+   * `ExchangeService` (CBE rate, falls back to the stored `exchange_settings`
+   * rate) — same mechanism `booking-wagon-cancellation.service.ts` and
+   * warehouse fee pricing already use. Null on anything but ETB/USD, or if
+   * the rate feed is down — this is a display convenience, not the payable
+   * amount, so a failure here must never break the charge list.
+   */
+  private async convertAmount(
+    charge: AdditionalCharge,
+  ): Promise<{ amount: number; currency: string } | null> {
+    if (charge.currency !== 'ETB' && charge.currency !== 'USD') return null;
+    const target = charge.currency === 'ETB' ? 'USD' : 'ETB';
+    try {
+      const amount = await this.exchangeService.convert(Number(charge.amount), charge.currency, target);
+      return { amount: Math.round(amount * 100) / 100, currency: target };
+    } catch (err) {
+      this.logger.warn(`Rate conversion failed for charge ${charge.id}: ${(err as Error).message}`);
+      return null;
+    }
+  }
+}

apps/edr-freight-api/src/modules/bookings/booking-clearance-charge.service.ts

@@ -14,11 +14,14 @@ import { Invoice } from '../billing/entities/invoice.entity';
 import { FilesService } from '../files/files.service';
 import { BookingsService } from './bookings.service';
 import { BookingsRepository } from './bookings.repository';
+import { BookingLifecycleNotifierService } from './booking-lifecycle-notifier.service';
 import { Booking } from './entities/booking.entity';
 import {
   BookingClearanceCharge,
+  ClearanceChargeStatus,
   ClearanceChargeType,
 } from './entities/booking-clearance-charge.entity';
+import { ClearanceEventService } from './clearance-event.service';
 
 /** File-record codes the charge documents are stored under on the booking. */
 const CHARGE_FILE_CODE: Record<ClearanceChargeType, string> = {
@@ -31,13 +34,22 @@ const CHARGE_LABEL: Record<ClearanceChargeType, string> = {
   MISCELLANEOUS: 'Miscellaneous charges',
 };
 
+/** Statuses the customer sees — drafts (DOC_UPLOADED / BILLED) stay GL-internal. */
+export const CUSTOMER_VISIBLE_CHARGE_STATUSES: ReadonlySet<ClearanceChargeStatus> =
+  new Set(['SENT', 'REJECTED', 'ACCEPTED', 'PAID']);
+
+/** Once the customer has accepted (invoice issued) or paid, GL cannot touch the charge. */
+export const canStaffEditCharge = (status: ClearanceChargeStatus): boolean =>
+  status !== 'ACCEPTED' && status !== 'PAID';
+
 /**
- * Post-finalization clearance charges billed to the customer. Two levels per
- * booking: GL Djibouti uploads the port-charges document; GL Ethiopia bills it
- * (amount + currency) and sends the invoice; once that invoice is paid GL
- * Ethiopia may create and send the miscellaneous charge. ETB invoices are paid
- * through the portal gateway, other currencies through Finance's manual
- * settlement worklist — both settle via `clearance_charge.invoice.paid`.
+ * Post-finalization clearance charges billed to the customer: one port charge
+ * (document from GL Djibouti, priced by GL Ethiopia) and any number of
+ * miscellaneous charges. GL prices + describes a charge and SENDs it; the
+ * customer REJECTs with a note (GL revises, re-sends) or ACCEPTs, which issues
+ * the payable invoice and locks the charge. ETB invoices are paid through the
+ * portal gateway, other currencies through Finance's manual settlement
+ * worklist — both settle via `clearance_charge.invoice.paid`.
  */
 @Injectable()
 export class BookingClearanceChargeService {
@@ -49,6 +61,8 @@ export class BookingClearanceChargeService {
     private readonly billing: BillingService,
     private readonly bookingsService: BookingsService,
     private readonly bookingsRepository: BookingsRepository,
+    private readonly clearanceEvents: ClearanceEventService,
+    private readonly notifier: BookingLifecycleNotifierService,
   ) {}
 
   private repo() {
@@ -102,6 +116,11 @@ export class BookingClearanceChargeService {
         file: file ? { id: file.id, name: file.name, url: file.url } : null,
         amount: c.amount != null ? Number(c.amount) : null,
         currency: c.currency ?? null,
+        description: c.description ?? null,
+        customerNote: c.customerNote ?? null,
+        customerDecidedAt: c.customerDecidedAt
+          ? c.customerDecidedAt.toISOString()
+          : null,
         invoiceId: c.invoiceId ?? null,
         invoiceNumber: c.invoiceId
           ? (invoiceById.get(c.invoiceId)?.invoiceNumber ?? null)
@@ -119,6 +138,24 @@ export class BookingClearanceChargeService {
     });
   }
 
+  /** The customer's view: only charges GL has sent them. */
+  async listForCustomer(bookingId: string): Promise<Freight.ClearanceCharge[]> {
+    return (await this.list(bookingId)).filter((c) =>
+      CUSTOMER_VISIBLE_CHARGE_STATUSES.has(c.status),
+    );
+  }
+
+  private async findCharge(
+    bookingId: string,
+    chargeId: string,
+  ): Promise<BookingClearanceCharge> {
+    const charge = await this.repo().findOne({
+      where: { id: chargeId, bookingId },
+    });
+    if (!charge) throw new NotFoundException('Clearance charge not found');
+    return charge;
+  }
+
   /** GL Djibouti uploads (or replaces, until billed) the port-charges document. */
   async uploadPortDocument(
     bookingId: string,
@@ -165,26 +202,34 @@ export class BookingClearanceChargeService {
         }),
       );
     }
+    await this.clearanceEvents.record({
+      bookingId,
+      action: 'CHARGE_PORT_DOC_UPLOADED',
+      label: existing
+        ? 'Replaced the port-charges document'
+        : 'Uploaded the port-charges document',
+      actorId: staffId,
+      metadata: { fileName: file.originalname },
+    });
     return this.list(bookingId);
   }
 
   /**
-   * GL Ethiopia sets (or, on the customer's request, revises) amount +
-   * currency. Revising a SENT charge cancels its unpaid invoice; a PAID charge
-   * is immutable.
+   * GL Ethiopia sets (or, after a customer rejection, revises) amount +
+   * currency + description. Allowed until the customer accepts: an ACCEPTED
+   * charge already carries an invoice and a PAID one is settled.
    */
   async billCharge(
     bookingId: string,
     chargeId: string,
-    input: { amount: number; currency: string },
+    input: { amount: number; currency: string; description?: string },
     staffId: string,
   ): Promise<Freight.ClearanceCharge[]> {
-    const charge = await this.repo().findOne({
-      where: { id: chargeId, bookingId },
-    });
-    if (!charge) throw new NotFoundException('Clearance charge not found');
-    if (charge.status === 'PAID') {
-      throw new ConflictException('A paid charge can no longer be changed.');
+    const charge = await this.findCharge(bookingId, chargeId);
+    if (!canStaffEditCharge(charge.status)) {
+      throw new ConflictException(
+        'The customer has accepted this charge — it can no longer be changed.',
+      );
     }
     if (!(input.amount > 0)) {
       throw new BadRequestException('Amount must be greater than zero.');
@@ -192,38 +237,117 @@ export class BookingClearanceChargeService {
     if (!input.currency?.trim()) {
       throw new BadRequestException('Currency is required.');
     }
-
-    if (charge.status === 'SENT' && charge.invoiceId) {
-      await this.billing.cancelInvoice(charge.invoiceId);
+    const description = (input.description ?? charge.description ?? '').trim();
+    if (charge.type === 'MISCELLANEOUS' && !description) {
+      throw new BadRequestException('Describe what this charge is for.');
     }
+    const currency = input.currency.trim().toUpperCase();
+    const revised = charge.status === 'SENT' || charge.status === 'REJECTED';
 
+    // Back to draft: the customer's previous decision no longer applies.
     await this.repo().update(charge.id, {
       amount: input.amount.toFixed(2),
-      currency: input.currency.trim().toUpperCase(),
+      currency,
+      description: description || null,
       status: 'BILLED',
-      invoiceId: null,
+      customerNote: null,
+      customerDecidedAt: null,
+      customerDecidedBy: null,
       billedByStaffId: staffId,
       billedAt: new Date(),
     });
+    await this.clearanceEvents.record({
+      bookingId,
+      action: 'CHARGE_BILLED',
+      label: `${revised ? 'Revised' : 'Billed'} ${CHARGE_LABEL[
+        charge.type
+      ].toLowerCase()}: ${input.amount} ${currency}${
+        description ? ` — ${description}` : ''
+      }`,
+      actorId: staffId,
+      metadata: {
+        chargeType: charge.type,
+        amount: input.amount,
+        currency,
+        description: description || null,
+        revised,
+      },
+    });
     return this.list(bookingId);
   }
 
-  /** GL Ethiopia issues the payable invoice to the customer. */
+  /**
+   * GL Ethiopia proposes the priced charge to the customer. No invoice yet —
+   * that is issued when the customer accepts. Re-sending after a rejection
+   * goes through here too.
+   */
   async sendCharge(
     bookingId: string,
     chargeId: string,
+    staffId: string,
   ): Promise<Freight.ClearanceCharge[]> {
-    const charge = await this.repo().findOne({
-      where: { id: chargeId, bookingId },
-    });
-    if (!charge) throw new NotFoundException('Clearance charge not found');
-    if (charge.status !== 'BILLED') {
+    const charge = await this.findCharge(bookingId, chargeId);
+    if (charge.status !== 'BILLED' && charge.status !== 'REJECTED') {
       throw new ConflictException(
-        'Set the amount and currency before sending the charge to the customer.',
+        charge.status === 'DOC_UPLOADED'
+          ? 'Set the amount and currency before sending the charge to the customer.'
+          : 'This charge has already been sent to the customer.',
       );
     }
+    const revised = charge.status === 'REJECTED';
+    const amount = Number(charge.amount);
+    const currency = charge.currency ?? 'ETB';
 
+    await this.repo().update(charge.id, {
+      status: 'SENT',
+      customerNote: null,
+      customerDecidedAt: null,
+      customerDecidedBy: null,
+    });
+    await this.clearanceEvents.record({
+      bookingId,
+      action: 'CHARGE_SENT',
+      label: `${revised ? 'Re-sent' : 'Sent'} ${CHARGE_LABEL[
+        charge.type
+      ].toLowerCase()} to the customer for approval: ${amount} ${currency}`,
+      actorId: staffId ?? null,
+      metadata: {
+        chargeType: charge.type,
+        amount,
+        currency,
+        description: charge.description ?? null,
+        revised,
+      },
+    });
     const booking = await this.bookingsService.findById(bookingId);
+    this.notifier.clearanceChargeProposed(booking, {
+      label: CHARGE_LABEL[charge.type],
+      amount,
+      currency,
+      description: charge.description ?? null,
+      revised,
+    });
+    return this.list(bookingId);
+  }
+
+  /** Customer agrees to the price: the payable invoice is issued and the charge locks. */
+  async customerAccept(
+    bookingId: string,
+    chargeId: string,
+    userId: string,
+  ): Promise<Freight.ClearanceCharge[]> {
+    const booking = await this.bookingsService.findById(bookingId);
+    await this.bookingsService.assertCustomerCanAccessBooking(userId, booking);
+    const charge = await this.findCharge(bookingId, chargeId);
+    if (charge.status !== 'SENT' && charge.status !== 'REJECTED') {
+      throw new ConflictException(
+        charge.status === 'ACCEPTED' || charge.status === 'PAID'
+          ? 'This charge has already been accepted.'
+          : 'This charge is not awaiting your decision.',
+      );
+    }
+    const amount = Number(charge.amount);
+    const currency = charge.currency ?? 'ETB';
     const invoice = await this.billing.generateInvoice({
       source: Freight.InvoiceSource.ClearanceCharge,
       // The charge's own id, NOT the booking id — booking-scoped invoice
@@ -232,85 +356,159 @@ export class BookingClearanceChargeService {
       type: charge.type,
       companyId: booking.companyId,
       companyProfileId: booking.companyProfileId,
-      currency: charge.currency ?? 'ETB',
+      currency,
       lines: [
         {
           chargeType: charge.type,
-          description: `${CHARGE_LABEL[charge.type]} — ${booking.reference ?? bookingId}`,
-          amount: Number(charge.amount),
+          description: `${CHARGE_LABEL[charge.type]} — ${
+            booking.reference ?? bookingId
+          }${charge.description ? `: ${charge.description}` : ''}`,
+          amount,
         },
       ],
     });
 
     await this.repo().update(charge.id, {
-      status: 'SENT',
+      status: 'ACCEPTED',
       invoiceId: invoice.id,
+      customerNote: null,
+      customerDecidedAt: new Date(),
+      customerDecidedBy: userId,
+    });
+    await this.clearanceEvents.record({
+      bookingId,
+      action: 'CHARGE_ACCEPTED',
+      label: `Customer accepted ${CHARGE_LABEL[
+        charge.type
+      ].toLowerCase()} (${amount} ${currency}) — invoice ${invoice.invoiceNumber} issued`,
+      actorType: 'CUSTOMER',
+      actorId: userId,
+      metadata: {
+        chargeType: charge.type,
+        invoiceNumber: invoice.invoiceNumber,
+        amount,
+        currency,
+      },
+    });
+    this.notifier.clearanceChargeInvoiceIssued(booking, {
+      label: CHARGE_LABEL[charge.type],
+      amount,
+      currency,
+      invoiceNumber: invoice.invoiceNumber,
     });
     this.logger.log(
-      `Clearance charge ${charge.type} on booking ${bookingId} sent as invoice ${invoice.invoiceNumber}`,
+      `Clearance charge ${charge.type} on booking ${bookingId} accepted; invoice ${invoice.invoiceNumber}`,
     );
-    return this.list(bookingId);
+    return this.listForCustomer(bookingId);
+  }
+
+  /** Customer declines the price with a reason; GL revises and re-sends. */
+  async customerReject(
+    bookingId: string,
+    chargeId: string,
+    note: string,
+    userId: string,
+  ): Promise<Freight.ClearanceCharge[]> {
+    const booking = await this.bookingsService.findById(bookingId);
+    await this.bookingsService.assertCustomerCanAccessBooking(userId, booking);
+    const charge = await this.findCharge(bookingId, chargeId);
+    if (charge.status !== 'SENT') {
+      throw new ConflictException(
+        charge.status === 'ACCEPTED' || charge.status === 'PAID'
+          ? 'This charge has already been accepted.'
+          : 'This charge is not awaiting your decision.',
+      );
+    }
+    if (!note?.trim()) {
+      throw new BadRequestException('Say why you are rejecting this charge.');
+    }
+    await this.repo().update(charge.id, {
+      status: 'REJECTED',
+      customerNote: note.trim(),
+      customerDecidedAt: new Date(),
+      customerDecidedBy: userId,
+    });
+    await this.clearanceEvents.record({
+      bookingId,
+      action: 'CHARGE_REJECTED',
+      label: `Customer rejected ${CHARGE_LABEL[charge.type].toLowerCase()}: ${note.trim()}`,
+      actorType: 'CUSTOMER',
+      actorId: userId,
+      metadata: { chargeType: charge.type, note: note.trim() },
+    });
+    this.notifier.clearanceChargeRejectedToStaff(booking, {
+      label: CHARGE_LABEL[charge.type],
+      note: note.trim(),
+    });
+    return this.listForCustomer(bookingId);
   }
 
   /**
-   * GL Ethiopia creates the miscellaneous charge whole (document + amount +
-   * currency). Second payment level: allowed only once the port charge is paid.
+   * GL Ethiopia creates a miscellaneous charge whole (document + amount +
+   * currency + what it is for). Lands as a BILLED draft; GL sends it next.
    */
   async createMiscellaneous(
     bookingId: string,
     file: Express.Multer.File,
-    input: { amount: number; currency: string },
+    input: { amount: number; currency: string; description?: string },
     staffId: string,
   ): Promise<Freight.ClearanceCharge[]> {
     const booking = await this.bookingsService.findById(bookingId);
     this.assertClearanceFinalized(booking);
 
-    const port = await this.repo().findOne({
-      where: { bookingId, type: 'PORT_CHARGES' },
-    });
-    if (port?.status !== 'PAID') {
-      throw new ConflictException(
-        'Miscellaneous charges open after the port charge is paid.',
-      );
-    }
-    const existing = await this.repo().findOne({
-      where: { bookingId, type: 'MISCELLANEOUS' },
-    });
-    if (existing) {
-      throw new ConflictException(
-        'This booking already has a miscellaneous charge — revise it instead.',
-      );
-    }
+    // No ordering and no cap: a miscellaneous charge may be raised before,
+    // after or alongside the port charge, and a booking may carry several.
     if (!(input.amount > 0)) {
       throw new BadRequestException('Amount must be greater than zero.');
     }
     if (!input.currency?.trim()) {
       throw new BadRequestException('Currency is required.');
     }
+    const description = input.description?.trim() ?? '';
+    if (!description) {
+      throw new BadRequestException('Describe what this charge is for.');
+    }
 
-    const record = await this.filesService.upsertByCode(
-      {
-        resourceId: bookingId,
-        resource: 'bookings',
-        code: CHARGE_FILE_CODE.MISCELLANEOUS,
-        file,
-      },
-      { userId: staffId },
-    );
-    await this.repo().save(
+    // Save the row first so its id can key the document. A booking may carry
+    // several miscellaneous charges, and `upsertByCode` retires whatever sits
+    // under the same code — a shared code would silently delete the previous
+    // charge's document.
+    const charge = await this.repo().save(
       this.repo().create({
         bookingId,
         type: 'MISCELLANEOUS',
         status: 'BILLED',
-        fileRecordId: record.id,
         amount: input.amount.toFixed(2),
         currency: input.currency.trim().toUpperCase(),
+        description,
         uploadedByStaffId: staffId,
         uploadedAt: new Date(),
         billedByStaffId: staffId,
         billedAt: new Date(),
       }),
     );
+    const record = await this.filesService.upsertByCode(
+      {
+        resourceId: bookingId,
+        resource: 'bookings',
+        code: `${CHARGE_FILE_CODE.MISCELLANEOUS}_${charge.id}`,
+        file,
+      },
+      { userId: staffId },
+    );
+    await this.repo().update(charge.id, { fileRecordId: record.id });
+    await this.clearanceEvents.record({
+      bookingId,
+      action: 'CHARGE_MISC_CREATED',
+      label: `Created miscellaneous charge: ${input.amount} ${input.currency.trim().toUpperCase()} — ${description}`,
+      actorId: staffId,
+      metadata: {
+        amount: input.amount,
+        currency: input.currency.trim().toUpperCase(),
+        description,
+        fileName: file.originalname,
+      },
+    });
     return this.list(bookingId);
   }
 
@@ -325,6 +523,16 @@ export class BookingClearanceChargeService {
       status: 'PAID',
       paidAt: new Date(),
     });
+    await this.clearanceEvents.record({
+      bookingId: charge.bookingId,
+      action: 'CHARGE_PAID',
+      label: `${CHARGE_LABEL[charge.type]} paid (invoice ${payload.invoiceNumber})`,
+      actorType: 'SYSTEM',
+      metadata: {
+        chargeType: charge.type,
+        invoiceNumber: payload.invoiceNumber,
+      },
+    });
     this.logger.log(
       `Clearance charge ${charge.type} on booking ${charge.bookingId} paid (invoice ${payload.invoiceNumber})`,
     );

apps/edr-freight-api/src/modules/bookings/booking-clearance-charge.spec.ts

@@ -0,0 +1,22 @@
+import {
+  CUSTOMER_VISIBLE_CHARGE_STATUSES,
+  canStaffEditCharge,
+} from './booking-clearance-charge.service';
+import { CLEARANCE_CHARGE_STATUSES } from './entities/booking-clearance-charge.entity';
+
+describe('clearance charge status guards', () => {
+  it('locks the charge once the customer has accepted or paid', () => {
+    expect(canStaffEditCharge('ACCEPTED')).toBe(false);
+    expect(canStaffEditCharge('PAID')).toBe(false);
+    for (const s of ['DOC_UPLOADED', 'BILLED', 'SENT', 'REJECTED'] as const) {
+      expect(canStaffEditCharge(s)).toBe(true);
+    }
+  });
+
+  it('hides GL drafts from the customer and shows everything sent', () => {
+    const visible = CLEARANCE_CHARGE_STATUSES.filter((s) =>
+      CUSTOMER_VISIBLE_CHARGE_STATUSES.has(s),
+    );
+    expect(visible).toEqual(['SENT', 'REJECTED', 'ACCEPTED', 'PAID']);
+  });
+});

apps/edr-freight-api/src/modules/bookings/booking-content.sql.spec.ts

@@ -0,0 +1,146 @@
+import {
+  CARGO_TYPE_SUBTREE_SQL,
+  bookingContainerCountSql,
+  bookingContainerVgmSql,
+  bookingContentMatchSql,
+  bookingContentSql,
+  bookingHasContainerTypeSql,
+  bookingRequestedCargoSql,
+  bookingRequestedContainerCountSql,
+} from './booking-content.sql';
+
+describe('bookingContentSql', () => {
+  const sql = bookingContentSql('b');
+
+  it('prefers the container lines, since container bookings carry no description', () => {
+    expect(sql.indexOf('freight.booking_container')).toBeLessThan(
+      sql.indexOf('freight.cargo_types'),
+    );
+    expect(sql).toContain('freight.container_types');
+    expect(sql).toContain('bc.deleted_at IS NULL');
+  });
+
+  it('falls back to commodity, then to the free-text description', () => {
+    expect(sql.indexOf('cgt.cargo_type_name')).toBeLessThan(
+      sql.indexOf('b.cargo_free_text'),
+    );
+  });
+
+  // An empty string is not a missing value to COALESCE — without NULLIF a blank
+  // description would win over the commodity behind it.
+  it('treats an empty string as absent at every level', () => {
+    expect(sql.match(/NULLIF/g)).toHaveLength(3);
+  });
+
+  it('rewrites every reference when embedded under another alias', () => {
+    expect(bookingContentSql('bk')).not.toMatch(/\bb\.(cargo|id)/);
+  });
+});
+
+describe('CARGO_TYPE_SUBTREE_SQL', () => {
+  // The filter offers groups, not just leaves, so picking "Bulk" has to reach
+  // commodities at any depth beneath it — two levels today, more tomorrow.
+  it('walks the tree recursively rather than one level of children', () => {
+    expect(CARGO_TYPE_SUBTREE_SQL).toContain('WITH RECURSIVE');
+    expect(CARGO_TYPE_SUBTREE_SQL).toContain('c.parent_group_id = sub.id');
+  });
+
+  it('includes the picked node itself, so a leaf still matches exactly', () => {
+    expect(CARGO_TYPE_SUBTREE_SQL).toContain('WHERE id = :cargoTypeId');
+  });
+});
+
+describe('bookingContentMatchSql', () => {
+  const sql = bookingContentMatchSql('b');
+
+  it('searches all three places content can live', () => {
+    expect(sql).toContain('b.cargo_free_text ILIKE :cargoText');
+    expect(sql).toContain('cgt.cargo_type_name ILIKE :cargoText');
+    expect(sql).toContain('cnt.code ILIKE :cargoText');
+  });
+
+  // Anything but OR would make the text box match nothing for whole freight
+  // types — a container booking has no commodity, a bulk one has no container.
+  it('ORs them, and stays one parenthesised term for andWhere', () => {
+    expect(sql).not.toContain(' AND :cargoText');
+    expect(sql.startsWith('(')).toBe(true);
+    expect(sql.trimEnd().endsWith(')')).toBe(true);
+  });
+});
+
+describe('bookingContainerCountSql', () => {
+  // booking_container is one row per LINE carrying a quantity, so counting rows
+  // would report a 54-container booking as 1.
+  it('sums the line quantities rather than counting lines', () => {
+    expect(bookingContainerCountSql('b')).toContain('SUM(bc.quantity)');
+    expect(bookingContainerCountSql('b')).not.toContain('COUNT(');
+  });
+
+  it('counts every type by default and one type when scoped', () => {
+    expect(bookingContainerCountSql('b')).not.toContain('container_type_id');
+    expect(bookingContainerCountSql('b', true)).toContain(
+      'bc.container_type_id = :containerTypeId',
+    );
+  });
+
+  it('is 0, never NULL, so a bound comparison still decides', () => {
+    expect(bookingContainerCountSql('b')).toContain('COALESCE(SUM(bc.quantity), 0)');
+  });
+
+  it('ignores soft-deleted lines', () => {
+    expect(bookingContainerCountSql('b')).toContain('bc.deleted_at IS NULL');
+    expect(bookingHasContainerTypeSql('b')).toContain('bc.deleted_at IS NULL');
+  });
+
+  it('rewrites the booking reference under another alias', () => {
+    expect(bookingContainerCountSql('bk')).toContain('bc.booking_id = bk.id');
+    expect(bookingHasContainerTypeSql('bk')).toContain('bc.booking_id = bk.id');
+  });
+});
+
+describe('bookingContainerVgmSql', () => {
+  // The whole point: b.cargo_total_weight_vgm is 0 for portal container
+  // bookings, so the weight has to come off the lines.
+  it('reads the lines, never the booking-level column', () => {
+    const sql = bookingContainerVgmSql('b');
+    expect(sql).toContain('SUM(bc.total_vgm_tons)');
+    expect(sql).not.toContain('cargo_total_weight_vgm');
+    expect(sql).toContain('bc.deleted_at IS NULL');
+  });
+});
+
+describe('requested (shipment-request) cargo', () => {
+  const cargo = bookingRequestedCargoSql('b');
+  const count = bookingRequestedContainerCountSql('b');
+
+  it('reads the request, never the booking or its container lines', () => {
+    for (const sql of [cargo, count]) {
+      expect(sql).toContain('freight.booking_requests br');
+      expect(sql).toContain('br.created_booking_id = b.id');
+      expect(sql).not.toContain('freight.booking_container');
+    }
+  });
+
+  // requested_lines is a free-form jsonb column; jsonb_array_elements throws on
+  // a non-array, which would 500 the whole list for one malformed row.
+  it('survives a requested_lines with no container array', () => {
+    for (const sql of [cargo, count]) {
+      expect(sql).toContain("jsonb_typeof(br.requested_lines->'containers') = 'array'");
+      expect(sql).toContain("ELSE '[]'::jsonb");
+    }
+  });
+
+  it('renders the bulk shape too, not only containers', () => {
+    expect(cargo).toContain("'bulk'->>'cargoWeightTons'");
+    expect(cargo).toContain("'bulk'->>'itemCount'");
+  });
+
+  it('counts 0 rather than NULL when no request exists', () => {
+    expect(count).toContain("COALESCE(SUM((l->>'quantity')::int), 0)");
+  });
+
+  it('ignores soft-deleted requests', () => {
+    expect(cargo).toContain('br.deleted_at IS NULL');
+    expect(count).toContain('br.deleted_at IS NULL');
+  });
+});

apps/edr-freight-api/src/modules/bookings/booking-content.sql.ts

@@ -0,0 +1,148 @@
+/**
+ * What the customer said is IN the booking, per freight type — the list
+ * filter, the summary and the export all read this one expression so the
+ * column, the pill and the sheet can never disagree.
+ *
+ * BULK      the commodity picked from the cargo tree (`cargo_types`), falling
+ *           back to the free-text description for a bare group or a legacy row
+ *           that has no commodity.
+ * CONTAINER the wizard asks for no description at all — VGM and contents are
+ *           captured later in operations — so the closest thing to the
+ *           customer's own words is the container lines they entered:
+ *           "2 × 40FT, 1 × 20FT".
+ *
+ * Containers are checked FIRST: a container booking has no `cargo_type_id`
+ * (the API rejects one), so the order only matters for a mixed legacy row,
+ * where the physical lines are the better answer.
+ */
+export function bookingContentSql(alias = 'b'): string {
+  return `COALESCE(
+    NULLIF((SELECT string_agg(bc.quantity || ' × ' || COALESCE(cnt.label, cnt.code), ', '
+                              ORDER BY cnt.size_ft DESC NULLS LAST, cnt.code)
+              FROM freight.booking_container bc
+              JOIN freight.container_types cnt ON cnt.id = bc.container_type_id
+             WHERE bc.booking_id = ${alias}.id AND bc.deleted_at IS NULL), ''),
+    NULLIF((SELECT cgt.cargo_type_name FROM freight.cargo_types cgt
+             WHERE cgt.id = ${alias}.cargo_type_id), ''),
+    NULLIF(${alias}.cargo_free_text, ''))`;
+}
+
+/**
+ * Cargo types at or under `:cargoTypeId`, so picking a GROUP in the filter
+ * matches every commodity beneath it — the same group→commodity drill-down the
+ * booking wizard offers, read back. Recursive because `cargo_types` is an
+ * arbitrary-depth tree (Bulk → Steel Billet → S1 → …), not two levels.
+ */
+export const CARGO_TYPE_SUBTREE_SQL = `(
+  WITH RECURSIVE sub AS (
+    SELECT id FROM freight.cargo_types WHERE id = :cargoTypeId
+    UNION ALL
+    SELECT c.id FROM freight.cargo_types c JOIN sub ON c.parent_group_id = sub.id
+  )
+  SELECT id FROM sub)`;
+
+/**
+ * Contains-match over every part of the content a customer can type or pick:
+ * their own description, the commodity's name, and the container types on the
+ * booking. Bind `:cargoText` already wrapped in `%`.
+ */
+export function bookingContentMatchSql(alias = 'b'): string {
+  return `(${alias}.cargo_free_text ILIKE :cargoText
+    OR EXISTS (SELECT 1 FROM freight.cargo_types cgt
+                WHERE cgt.id = ${alias}.cargo_type_id
+                  AND cgt.cargo_type_name ILIKE :cargoText)
+    OR EXISTS (SELECT 1 FROM freight.booking_container bc
+                 JOIN freight.container_types cnt ON cnt.id = bc.container_type_id
+                WHERE bc.booking_id = ${alias}.id AND bc.deleted_at IS NULL
+                  AND (cnt.label ILIKE :cargoText OR cnt.code ILIKE :cargoText)))`;
+}
+
+/**
+ * Containers on a booking, as a count of physical boxes — `booking_container`
+ * is one row PER LINE with a `quantity`, not one row per box, so this sums the
+ * quantity rather than counting rows.
+ *
+ * `scopedToType` narrows the sum to `:containerTypeId`, which is what makes one
+ * number filter answer both "10 containers in total" and "10 forty-footers":
+ * the count filter reads the container-type filter when one is set, and counts
+ * every type when it is not.
+ */
+export function bookingContainerCountSql(alias = 'b', scopedToType = false): string {
+  return `(SELECT COALESCE(SUM(bc.quantity), 0)
+             FROM freight.booking_container bc
+            WHERE bc.booking_id = ${alias}.id
+              AND bc.deleted_at IS NULL${
+                scopedToType ? '\n              AND bc.container_type_id = :containerTypeId' : ''
+              })`;
+}
+
+/** Bookings carrying at least one line of `:containerTypeId`. */
+export function bookingHasContainerTypeSql(alias = 'b'): string {
+  return `EXISTS (SELECT 1 FROM freight.booking_container bc
+                   WHERE bc.booking_id = ${alias}.id
+                     AND bc.deleted_at IS NULL
+                     AND bc.container_type_id = :containerTypeId)`;
+}
+
+/**
+ * Container VGM on a booking, in tons — the sum of the per-line totals.
+ *
+ * NOT `bookings.cargo_total_weight_vgm`: the portal wizard leaves that at 0 for
+ * container freight (VGM is captured per container, later, in operations), so
+ * reading the booking-level column showed every portal container booking as
+ * weighing nothing. Same reason `bookingTonsSql` falls through to these lines.
+ */
+export function bookingContainerVgmSql(alias = 'b'): string {
+  return `(SELECT COALESCE(SUM(bc.total_vgm_tons), 0)
+             FROM freight.booking_container bc
+            WHERE bc.booking_id = ${alias}.id
+              AND bc.deleted_at IS NULL)`;
+}
+
+/**
+ * Cargo the customer declared on the SHIPMENT REQUEST behind a booking, which
+ * is not the same fact as cargo on the booking itself.
+ *
+ * On a GENERAL + customs contract the customer cannot book directly: they
+ * submit a request (day + quantities), and `initiateForShipmentRequest` opens a
+ * BARE instance from it — "the request itself carries the quantities; the
+ * instance carries none". So between initiation and `completeUnderContract` the
+ * booking legitimately holds no cargo while the customer's declared quantities
+ * sit on `booking_requests.requested_lines`.
+ *
+ * Kept in its own column rather than folded into the real container count: a
+ * declared 2 × 20FT is a request, not two boxes on a booking, and merging the
+ * two would overstate operational totals.
+ */
+const REQUESTED_CONTAINER_LINES = `jsonb_array_elements(
+  CASE WHEN jsonb_typeof(br.requested_lines->'containers') = 'array'
+       THEN br.requested_lines->'containers'
+       ELSE '[]'::jsonb END)`;
+
+/** Human-readable declared cargo: "2 × 20FT", "12 t", "40 items". */
+export function bookingRequestedCargoSql(alias = 'b'): string {
+  return `(SELECT COALESCE(
+              (SELECT string_agg((l->>'quantity') || ' × ' || upper(l->>'containerSize'), ', '
+                                 ORDER BY l->>'containerSize')
+                 FROM ${REQUESTED_CONTAINER_LINES} AS l),
+              NULLIF(br.requested_lines->'bulk'->>'cargoWeightTons', '') || ' t',
+              NULLIF(br.requested_lines->'bulk'->>'itemCount', '') || ' items')
+            FROM freight.booking_requests br
+           WHERE br.created_booking_id = ${alias}.id
+             AND br.deleted_at IS NULL
+           ORDER BY br.created_at DESC
+           LIMIT 1)`;
+}
+
+/**
+ * Boxes declared on the shipment request. Pairs with the real container count:
+ * `Containers = 0` AND `Requested containers >= 1` is exactly the set awaiting
+ * completion.
+ */
+export function bookingRequestedContainerCountSql(alias = 'b'): string {
+  return `(SELECT COALESCE(SUM((l->>'quantity')::int), 0)
+             FROM freight.booking_requests br
+             CROSS JOIN LATERAL ${REQUESTED_CONTAINER_LINES} AS l
+            WHERE br.created_booking_id = ${alias}.id
+              AND br.deleted_at IS NULL)`;
+}

apps/edr-freight-api/src/modules/bookings/booking-lifecycle-notifier.service.ts

@@ -202,6 +202,17 @@ export class BookingLifecycleNotifierService {
   }
 
   /** A clearance document was queried and needs the customer to re-upload. */
+  /** GL asked the customer for additional clearance document(s). */
+  additionalDocsRequested(b: Booking, note: string): void {
+    const msg =
+      `Additional document(s) requested on booking ${b.reference}: ` +
+      `${note} Please upload them from the portal.`;
+    void this.notifyContact(b, msg, 'ADDITIONAL DOCUMENTS REQUESTED');
+    this.inApp(b, 'Additional documents requested', msg, {
+      type: NotificationType.DOCUMENT_ACTION,
+    });
+  }
+
   documentQueried(b: Booking, fileKey: string, note: string): void {
     const msg =
       `A clearance document on booking ${b.reference} needs attention: "${fileKey}". ` +
@@ -410,6 +421,55 @@ export class BookingLifecycleNotifierService {
     });
   }
 
+  // ── Clearance charges (port + miscellaneous) ───────────────────────────────
+
+  /** GL proposed (or re-proposed) a clearance charge — the customer accepts or rejects it in the portal. */
+  clearanceChargeProposed(
+    b: Booking,
+    c: {
+      label: string;
+      amount: number;
+      currency: string;
+      description: string | null;
+      revised: boolean;
+    },
+  ): void {
+    const msg =
+      `${c.revised ? 'Revised ' + c.label.toLowerCase() : c.label} of ${c.amount} ${c.currency}` +
+      `${c.description ? ` (${c.description})` : ''} on booking ${b.reference} ` +
+      `await your approval. Please accept or reject them in the portal.`;
+    void this.notifyContact(b, msg, c.revised ? 'CLEARANCE CHARGE REVISED' : 'CLEARANCE CHARGE SENT');
+    this.inApp(b, c.revised ? `${c.label} revised` : `${c.label} need your approval`, msg, {
+      type: NotificationType.INVOICE_ISSUED,
+    });
+  }
+
+  /** The customer accepted a clearance charge — its invoice is now payable. */
+  clearanceChargeInvoiceIssued(
+    b: Booking,
+    c: { label: string; amount: number; currency: string; invoiceNumber: string },
+  ): void {
+    const msg =
+      `Invoice ${c.invoiceNumber} for ${c.label.toLowerCase()} (${c.amount} ${c.currency}) ` +
+      `on booking ${b.reference} is ready. Please pay it from the portal.`;
+    void this.notifyContact(b, msg, 'CLEARANCE CHARGE INVOICE');
+    this.inApp(b, `${c.label} invoice issued`, msg, {
+      type: NotificationType.INVOICE_ISSUED,
+    });
+  }
+
+  /** The customer rejected a clearance charge — GL Ethiopia revises and re-sends. */
+  clearanceChargeRejectedToStaff(b: Booking, c: { label: string; note: string }): void {
+    const msg =
+      `The customer rejected the ${c.label.toLowerCase()} on booking ${this.ref(b)}: ` +
+      `"${c.note}". Revise and re-send from the clearance page.`;
+    this.inAppStaff(b, `${c.label} rejected — ${this.ref(b)}`, msg, {
+      recipients: CLEARANCE_DESK,
+      type: NotificationType.CLEARANCE_REVIEW,
+      link: `/dashboard/clearance/${b.id}`,
+    });
+  }
+
   /** GL confirmed the final-invoice payment slip. */
   finalInvoicePaid(b: Booking): void {
     const msg = `Your final invoice payment for booking ${b.reference} has been confirmed. Thank you.`;

apps/edr-freight-api/src/modules/bookings/booking-payables.service.ts

@@ -0,0 +1,107 @@
+import { Injectable } from '@nestjs/common';
+import { DataSource } from 'typeorm';
+import { Freight } from '@edr/types';
+
+/** Invoice statuses a customer can still settle (mirrors the portal's PAYABLE_STATUSES). */
+const PAYABLE_INVOICE_STATUSES = ['ISSUED', 'PENDING', 'PARTIALLY_PAID', 'OVERDUE'];
+/** Booking statuses at which the freight invoice is actually due (mirrors BookingsService). */
+const FREIGHT_PAYABLE_BOOKING_STATUSES = [
+  'FULLY_EXECUTED',
+  'SELECTED_FOR_BATCH',
+  'AWAITING_PAYMENT',
+];
+
+/**
+ * One row per outstanding item. `invoices.status` / `bookings.status` are
+ * Postgres enums, hence the ::text casts. `amount` is NULL for items that only need the
+ * customer's review (a proposed clearance charge, a draft final invoice) so
+ * they count but do not inflate "amount due".
+ */
+const SQL = `
+  -- Central invoices on the booking: freight (only while the booking is in a
+  -- payable status), wagon-cancellation fee, GL final invoice (+ its DRAFT,
+  -- which waits for the customer's approval).
+  SELECT i.source_id AS "bookingId", i.currency,
+         CASE WHEN i.status::text = 'DRAFT' THEN NULL ELSE i.balance_amount END AS amount
+    FROM freight.invoices i
+    JOIN freight.bookings b ON b.id::text = i.source_id AND b.deleted_at IS NULL
+   WHERE i.company_id = $1 AND i.deleted_at IS NULL AND i.source = 'booking'
+     AND (
+       (i.status::text = ANY($2::text[]) AND i.balance_amount > 0
+        AND (i.type IN ('WAGON_CANCEL_FEE', 'GL_FINAL') OR b.status::text = ANY($3::text[])))
+       OR (i.type = 'GL_FINAL' AND i.status::text = 'DRAFT')
+     )
+  UNION ALL
+  -- Accepted clearance charges whose invoice is still unpaid.
+  SELECT c.booking_id::text, i.currency, i.balance_amount
+    FROM freight.invoices i
+    JOIN freight.booking_clearance_charge c ON c.id::text = i.source_id AND c.deleted_at IS NULL
+   WHERE i.company_id = $1 AND i.deleted_at IS NULL AND i.source = 'clearance_charge'
+     AND i.status::text = ANY($2::text[]) AND i.balance_amount > 0
+  UNION ALL
+  -- Clearance charges waiting for the customer to accept or reject the price.
+  SELECT c.booking_id::text, c.currency, NULL::numeric
+    FROM freight.booking_clearance_charge c
+    JOIN freight.bookings b ON b.id = c.booking_id AND b.deleted_at IS NULL
+   WHERE b.company_id = $1 AND c.deleted_at IS NULL AND c.status = 'SENT'
+  UNION ALL
+  -- Duty / tax advised by customs, payment slip not uploaded yet.
+  SELECT m.booking_id::text, m.metadata->>'dutyCurrency',
+         NULLIF(m.metadata->>'dutyAmount', '')::numeric
+    FROM freight.clearance_milestones m
+    JOIN freight.bookings b ON b.id = m.booking_id AND b.deleted_at IS NULL
+   WHERE b.company_id = $1 AND m.deleted_at IS NULL AND m.status = 'COMPLETED'
+     AND (
+       (m.milestone_code = 'DUTY_TAXES_ADVISED' AND NOT EXISTS (
+          SELECT 1 FROM freight.clearance_milestones p
+           WHERE p.booking_id = m.booking_id AND p.milestone_code = 'DUTY_TAX_PAID'
+             AND p.status = 'COMPLETED' AND p.deleted_at IS NULL))
+       OR
+       (m.milestone_code = 'SECOND_DUTY_ADVISED' AND NOT EXISTS (
+          SELECT 1 FROM freight.clearance_milestones p
+           WHERE p.booking_id = m.booking_id AND p.milestone_code = 'SECOND_DUTY_PAID'
+             AND p.status = 'COMPLETED' AND p.deleted_at IS NULL))
+     )
+`;
+
+/**
+ * Everything a customer still has to act on, per booking, in one query. Drives
+ * the "Pay" badge on the home and booking-list rows; the booking's Payments tab
+ * composes the same items client-side from the per-booking endpoints.
+ */
+@Injectable()
+export class BookingPayablesService {
+  constructor(private readonly dataSource: DataSource) {}
+
+  async summarizeForCompany(
+    companyId: string,
+  ): Promise<Freight.BookingPayableSummary[]> {
+    const rows: Array<{
+      bookingId: string;
+      currency: string | null;
+      amount: string | null;
+    }> = await this.dataSource.query(SQL, [
+      companyId,
+      PAYABLE_INVOICE_STATUSES,
+      FREIGHT_PAYABLE_BOOKING_STATUSES,
+    ]);
+
+    const byBooking = new Map<string, Freight.BookingPayableSummary>();
+    for (const r of rows) {
+      const s = byBooking.get(r.bookingId) ?? {
+        bookingId: r.bookingId,
+        count: 0,
+        totals: [],
+      };
+      s.count += 1;
+      const amount = Number(r.amount ?? 0);
+      if (r.currency && amount > 0) {
+        const t = s.totals.find((x) => x.currency === r.currency);
+        if (t) t.amount += amount;
+        else s.totals.push({ currency: r.currency, amount });
+      }
+      byBooking.set(r.bookingId, s);
+    }
+    return [...byBooking.values()];
+  }
+}

apps/edr-freight-api/src/modules/bookings/booking-pricing.service.spec.ts

@@ -57,6 +57,7 @@ describe('BookingPricingService — domestic corridor', () => {
       exchangeService as never,
       { validate20ftPairing: jest.fn().mockResolvedValue([]) } as never,
       {} as never,
+      { findById: jest.fn().mockResolvedValue({ includesEthiopianCustomsOnly: false }) } as never,
     );
   });
 
@@ -333,6 +334,7 @@ describe('BookingPricingService — customs clearance fee billed on the booking
               : [],
         }),
       } as never,
+      { findById: jest.fn().mockResolvedValue({ includesEthiopianCustomsOnly: false }) } as never,
     );
 
   const containerBooking = (overrides: Record<string, unknown> = {}) =>
@@ -388,6 +390,30 @@ describe('BookingPricingService — customs clearance fee billed on the booking
     expect(line!.amount).toBe(200);
   });
 
+  it('prices an Ethiopian-customs-only service off ETHIOPIAN_CUSTOMS_CLEARANCE, not the full fee', async () => {
+    const ethiopianFee = {
+      ...containerFee20,
+      id: 'rate-et-20',
+      rateType: 'ETHIOPIAN_CUSTOMS_CLEARANCE',
+      trigger: 'ETHIOPIAN_CUSTOMS_CLEARANCE',
+      rateValue: 40,
+    } as Rate;
+    // No serviceType relation on the booking (like the GL/portal shipment
+    // preview) — the flag must be resolved from serviceTypeId.
+    const service = makeService({ liveRates: [containerFee20, ethiopianFee] });
+    (service as unknown as { serviceTypesService: { findById: jest.Mock } }).serviceTypesService = {
+      findById: jest.fn().mockResolvedValue({ includesEthiopianCustomsOnly: true }),
+    };
+    const result = await service.computePriceForBooking(
+      containerBooking({ serviceTypeId: 'st-et', serviceType: undefined }),
+    );
+
+    const line = result.lineItems.find((l) => l.code === 'ETHIOPIAN_CUSTOMS_CLEARANCE_20FT');
+    expect(line).toBeDefined();
+    expect(line!.amount).toBe(160);
+    expect(result.lineItems.some((l) => l.code === 'CUSTOMS_CLEARANCE_20FT')).toBe(false);
+  });
+
   it('hard-blocks a container type with no fee configured (never free clearance)', async () => {
     const service = makeService({ liveRates: [bulkFeePerTon] });
     const result = await service.computePriceForBooking(containerBooking());
@@ -553,6 +579,7 @@ describe('BookingPricingService — bulk base freight units', () => {
           wagonTypes: wagonCapacity !== undefined ? [{ capacityTons: wagonCapacity }] : [],
         }),
       } as never,
+      { findById: jest.fn().mockResolvedValue({ includesEthiopianCustomsOnly: false }) } as never,
     );
 
   // 12 machines, not 12 tonnes — a PER_ITEM commodity records its count here.
@@ -683,6 +710,7 @@ describe('BookingPricingService — PER_WAGON container freight', () => {
       { getRate: jest.fn().mockResolvedValue(MOCK_CBE_RATE) } as never,
       { validate20ftPairing: jest.fn().mockResolvedValue([]) } as never,
       { findById: jest.fn() } as never,
+      { findById: jest.fn().mockResolvedValue({ includesEthiopianCustomsOnly: false }) } as never,
     );
 
   const booking = (

apps/edr-freight-api/src/modules/bookings/booking-pricing.service.ts

@@ -3,6 +3,7 @@ import { Injectable, NotFoundException } from '@nestjs/common';
 import { CargoTypesService } from '../rule-engine/services/cargo-types.service';
 import { ContainerTypesService } from '../rule-engine/services/container-types.service';
 import { RatesService } from '../rule-engine/services/rates.service';
+import { ServiceTypesService } from '../rule-engine/services/service-types.service';
 import { Rate } from '../rule-engine/entities/rate.entity';
 import { isBulkQuantityUnit } from '../rule-engine/entities/rate-unit.util';
 import { ContractRateSnapshot } from '../contracts/entities/contract-rate-snapshot.entity';
@@ -25,9 +26,18 @@ import { Booking } from './entities/booking.entity';
 import { assertBookingStatus } from './booking-status.util';
 import { ContainerValidationService } from './container-validation.service';
 
+/**
+ * One physical container over its VGM limit. Weight limits are per container,
+ * so an overloaded box is reported (and billed) on its own tons above the
+ * limit — a lighter box on the same line never absorbs them.
+ */
 export interface OverweightLine {
   containerTypeCode: string;
+  /** Container number when known, else "<code> #2" — identifies the box. */
+  containerLabel: string;
+  /** This container's VGM, not the line total. */
   totalVgmTons: number;
+  /** The per-container limit. */
   maxAllowedTons: number;
   excessTons: number;
 }
@@ -84,6 +94,7 @@ export class BookingPricingService {
     private readonly exchangeService: ExchangeService,
     private readonly containerValidationService: ContainerValidationService,
     private readonly cargoTypesService: CargoTypesService,
+    private readonly serviceTypesService: ServiceTypesService,
   ) {}
 
   async generatePrice(bookingId: string): Promise<GeneratePriceResponseDto> {
@@ -248,9 +259,10 @@ export class BookingPricingService {
       clearanceBlocked.push(...clearance.blocked);
     }
 
-    // Overweight detail for the customer: map the engine's per-line results back
-    // to the booking's container lines (same order) for code + weights. maxAllowed
-    // is derived from the line total minus the excess the engine computed.
+    // Overweight detail for the customer: one row per over-limit CONTAINER,
+    // mapped back to the booking's container lines (same order) for the code and
+    // the physical container numbers. maxAllowed is the per-container limit,
+    // recovered from that container's weight minus its own excess.
     const overweightLines: OverweightLine[] = [];
     const containerLines = (booking.bookingContainers ?? []).filter(
       (bc) => bc.containerTypeId != null,
@@ -259,8 +271,6 @@ export class BookingPricingService {
       const wr = ruleResult.containerWeightResults[i];
       if (!wr?.isOverweight) continue;
       const line = containerLines[i];
-      const totalVgmTons = Number(line?.totalVgmTons ?? 0);
-      const excessTons = Number(wr.overweightExcessTons ?? 0);
       let code = line?.containerSize ?? '';
       if (line?.containerTypeId) {
         try {
@@ -269,12 +279,32 @@ export class BookingPricingService {
           // fall back to the container size label
         }
       }
-      overweightLines.push({
-        containerTypeCode: code,
-        totalVgmTons,
-        maxAllowedTons: Math.max(0, totalVgmTons - excessTons),
-        excessTons,
-      });
+      const numbers = (line?.units ?? [])
+        .slice()
+        .sort((a, b) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0))
+        .map((u) => u.containerNumber);
+      // Legacy weight results carry no per-unit detail (a line total only) —
+      // report the line as a single row, as before.
+      const units = wr.overweightUnits?.length
+        ? wr.overweightUnits
+        : [
+            {
+              unitIndex: 0,
+              vgmTons: Number(line?.totalVgmTons ?? 0),
+              excessTons: Number(wr.overweightExcessTons ?? 0),
+            },
+          ];
+      for (const u of units) {
+        overweightLines.push({
+          containerTypeCode: code,
+          containerLabel:
+            (u.unitIndex > 0 ? numbers[u.unitIndex - 1] : null) ||
+            (u.unitIndex > 0 ? `${code} #${u.unitIndex}` : code),
+          totalVgmTons: u.vgmTons,
+          maxAllowedTons: Math.max(0, u.vgmTons - u.excessTons),
+          excessTons: u.excessTons,
+        });
+      }
     }
 
     return {
@@ -344,6 +374,13 @@ export class BookingPricingService {
               quantity: qty,
               vgmPerUnitTons: vgm,
               totalVgmTons: qty * vgm,
+              // Real per-box weights when the booking recorded them: weight
+              // limits are per container, so 22/18/20t is 2t over on the first
+              // box even though the line total fits a 3x20t allowance.
+              unitVgmTons: (bc.units ?? [])
+                .slice()
+                .sort((a, b) => (a.sortOrder ?? 0) - (b.sortOrder ?? 0))
+                .map((u) => Number(u.vgmTons ?? 0)),
               isReefer: ct.isReefer,
               // Per-container opt-ins — PER_CONTAINER surcharges bill these.
               hazardousQuantity: Number(bc.hazardousQuantity ?? 0),
@@ -1060,9 +1097,27 @@ export class BookingPricingService {
     const usdToEtb = isEtb ? await this.exchangeService.getRate('USD', 'ETB') : 1;
     const convert = (usd: number): number => (isEtb ? round2(usd * usdToEtb) : usd);
 
+    // An Ethiopian-side-only customs service prices off its own rate; the
+    // contract froze its snapshots under the matching code prefix. Resolved by
+    // id when the relation isn't loaded — the GL / portal shipment previews
+    // price a transient booking object, and a missing relation must not
+    // silently quote the standard fee the created booking is then billed
+    // differently for.
+    const serviceType =
+      booking.serviceType ??
+      (booking.serviceTypeId
+        ? await this.serviceTypesService.findById(booking.serviceTypeId).catch(() => null)
+        : null);
+    const customsType = serviceType?.includesEthiopianCustomsOnly
+      ? 'ETHIOPIAN_CUSTOMS_CLEARANCE'
+      : 'CUSTOMS_CLEARANCE';
+    const customsLabel =
+      customsType === 'ETHIOPIAN_CUSTOMS_CLEARANCE'
+        ? 'Ethiopian customs clearance service'
+        : 'Customs clearance service';
     const onLeg = liveRates.filter(
       (r) =>
-        r.rateType === 'CUSTOMS_CLEARANCE' &&
+        r.rateType === customsType &&
         r.currency === 'USD' &&
         r.tradeDirection === booking.tradeDirection &&
         r.originYardId === booking.originYardId &&
@@ -1070,20 +1125,20 @@ export class BookingPricingService {
     );
     const missingRateMessage = (scope: string): string =>
       `No customs clearance service fee is configured for ${scope} on this ` +
-      'origin → destination. Ask EDR to configure the CUSTOMS_CLEARANCE rate for this route.';
+      `origin → destination. Ask EDR to configure the ${customsType} rate for this route.`;
 
     if (booking.freightType === 'CONTAINER') {
       // Legacy short-circuit: an old contract froze one flat fee — bill it once.
       const hasPerSizeSnapshot =
-        frozenRates?.has('CUSTOMS_CLEARANCE_20FT') ||
-        frozenRates?.has('CUSTOMS_CLEARANCE_40FT');
-      const legacyFlat = this.frozenRateByCode(frozenRates, 'CUSTOMS_CLEARANCE', currency, usdToEtb);
+        frozenRates?.has(`${customsType}_20FT`) ||
+        frozenRates?.has(`${customsType}_40FT`);
+      const legacyFlat = this.frozenRateByCode(frozenRates, customsType, currency, usdToEtb);
       if (legacyFlat && !hasPerSizeSnapshot) {
         const amount = Number(legacyFlat.unitPrice);
         if (amount > 0) {
           lineItems.push({
-            code: 'CUSTOMS_CLEARANCE',
-            description: 'Customs clearance service',
+            code: customsType,
+            description: customsLabel,
             amount,
             unitAmount: amount,
             unit: 'FLAT',
@@ -1106,7 +1161,7 @@ export class BookingPricingService {
           // unknown type — falls through to the live per-type lookup below
         }
         const frozen = sizeFt
-          ? this.frozenRateByCode(frozenRates, `CUSTOMS_CLEARANCE_${sizeFt}FT`, currency, usdToEtb)
+          ? this.frozenRateByCode(frozenRates, `${customsType}_${sizeFt}FT`, currency, usdToEtb)
           : null;
         const live = onLeg.find((r) => r.containerTypeId === bc.containerTypeId);
         if (!frozen && !live) {
@@ -1124,8 +1179,8 @@ export class BookingPricingService {
         const amount = unit === 'FLAT' ? unitAmount : unitAmount * billedQty;
         if (!(amount > 0)) continue;
         lineItems.push({
-          code: sizeFt ? `CUSTOMS_CLEARANCE_${sizeFt}FT` : 'CUSTOMS_CLEARANCE',
-          description: `Customs clearance service${sizeFt ? ` (${sizeFt}ft)` : ''}`,
+          code: sizeFt ? `${customsType}_${sizeFt}FT` : customsType,
+          description: `${customsLabel}${sizeFt ? ` (${sizeFt}ft)` : ''}`,
           amount,
           unitAmount,
           unit,
@@ -1141,7 +1196,7 @@ export class BookingPricingService {
     // flat snapshot share the CUSTOMS_CLEARANCE code; both are the agreed fee.
     // Live lookup: the rate scoped to the booking's commodity wins; a
     // commodity-less rate (legacy) is the catch-all fallback.
-    const frozen = this.frozenRateByCode(frozenRates, 'CUSTOMS_CLEARANCE', currency, usdToEtb);
+    const frozen = this.frozenRateByCode(frozenRates, customsType, currency, usdToEtb);
     const live =
       (booking.cargoTypeId
         ? onLeg.find(
@@ -1172,8 +1227,8 @@ export class BookingPricingService {
     const amount = unit === 'FLAT' ? unitAmount : unitAmount * billedQty;
     if (amount > 0) {
       lineItems.push({
-        code: 'CUSTOMS_CLEARANCE',
-        description: 'Customs clearance service (bulk)',
+        code: customsType,
+        description: `${customsLabel} (bulk)`,
         amount,
         unitAmount,
         unit,

apps/edr-freight-api/src/modules/bookings/booking-tons.sql.spec.ts

@@ -0,0 +1,30 @@
+import { bookingTonsSql } from './booking-tons.sql';
+
+describe('bookingTonsSql', () => {
+  const sql = bookingTonsSql('b');
+
+  // The regression this exists for: a plain COALESCE stops at the portal's
+  // literal 0 for container bookings and reports them as weighing nothing.
+  it('treats a stored 0 as "no figure" on both booking-level columns', () => {
+    expect(sql).toContain('NULLIF(b.bulk_total_weight_tons, 0)');
+    expect(sql).toContain('NULLIF(b.cargo_total_weight_vgm, 0)');
+  });
+
+  it('falls back to the per-line container VGM, excluding soft-deleted lines', () => {
+    expect(sql).toContain('SUM(bc.total_vgm_tons)');
+    expect(sql).toContain('freight.booking_container bc');
+    expect(sql).toContain('bc.booking_id = b.id');
+    expect(sql).toContain('bc.deleted_at IS NULL');
+  });
+
+  it('never returns NULL, so callers may SUM it directly', () => {
+    expect(sql.trimEnd().endsWith('0)')).toBe(true);
+  });
+
+  it('rewrites every reference when embedded under another alias', () => {
+    const aliased = bookingTonsSql('bk');
+    expect(aliased).not.toMatch(/\bb\./);
+    expect(aliased).toContain('bk.cargo_total_weight_vgm');
+    expect(aliased).toContain('bc.booking_id = bk.id');
+  });
+});

apps/edr-freight-api/src/modules/bookings/booking-tons.sql.ts

@@ -0,0 +1,26 @@
+/**
+ * SQL mirror of `bookingCargoTons()` (train-scheduling/train-capacity.util.ts).
+ *
+ * Three storage conventions share `bookings.cargo_total_weight_vgm`:
+ *  - BULK PER_TON  — the column holds tons.
+ *  - BULK PER_ITEM — the column holds an ITEM COUNT; the tons are in
+ *    `bulk_total_weight_tons`.
+ *  - CONTAINER     — the portal wizard captures VGM per line, not per booking,
+ *    and sends 0 (portal NewBookingPage: "containers carry NO weight at the
+ *    wizard"). The tons live in `booking_container.total_vgm_tons`. The
+ *    backoffice wizard does store a booking-level total, so both shapes exist
+ *    in the same table.
+ *
+ * Hence NULLIF on both columns: a plain
+ * `COALESCE(bulk_total_weight_tons, cargo_total_weight_vgm)` stops at the
+ * portal's 0 — COALESCE falls through on NULL, never on 0 — and every
+ * portal-created container booking reads as 0 tons in exports and reports.
+ */
+export function bookingTonsSql(alias = 'b'): string {
+  return `COALESCE(
+    NULLIF(${alias}.bulk_total_weight_tons, 0),
+    NULLIF(${alias}.cargo_total_weight_vgm, 0),
+    (SELECT SUM(bc.total_vgm_tons) FROM freight.booking_container bc
+      WHERE bc.booking_id = ${alias}.id AND bc.deleted_at IS NULL),
+    0)`;
+}

apps/edr-freight-api/src/modules/bookings/booking-transition.accept.spec.ts

@@ -59,6 +59,7 @@ describe('BookingTransitionService — acceptIntake validity window', () => {
         clearanceDocsUploadedToStaff: jest.fn(),
         dutySlipUploadedToStaff: jest.fn(),
       } as never, // notifier
+      { record: jest.fn() } as never, // clearanceEvents
       { emit: jest.fn() } as never, // events
     );
     return { service, bookingsRepository, ruleEngineService, contractService };

apps/edr-freight-api/src/modules/bookings/booking-transition.clearance.spec.ts

@@ -68,6 +68,7 @@ describe('BookingTransitionService — finalizeClearance gate', () => {
         clearanceDocsUploadedToStaff: jest.fn(),
         dutySlipUploadedToStaff: jest.fn(),
       } as never, // notifier
+      { record: jest.fn() } as never, // clearanceEvents
       { emit: jest.fn() } as never, // events
     );
     return { service, bookingsRepository };
@@ -172,6 +173,7 @@ describe('BookingTransitionService — finalizeClearance customs output gate', (
         clearanceDocsUploadedToStaff: jest.fn(),
         dutySlipUploadedToStaff: jest.fn(),
       } as never, // notifier
+      { record: jest.fn() } as never, // clearanceEvents
       { emit: jest.fn() } as never, // events
     );
     return { service, bookingsRepository };
@@ -262,6 +264,7 @@ describe('BookingTransitionService — submitClearanceDocuments required-fields
         clearanceDocsUploadedToStaff: jest.fn(),
         dutySlipUploadedToStaff: jest.fn(),
       } as never, // notifier
+      { record: jest.fn() } as never, // clearanceEvents
       { emit: jest.fn() } as never, // events
     );
     return { service, bookingsRepository, filesService };

apps/edr-freight-api/src/modules/bookings/booking-transition.operation.spec.ts

@@ -71,6 +71,7 @@ describe('BookingTransitionService — operation review', () => {
         clearanceDocsUploadedToStaff: jest.fn(),
         dutySlipUploadedToStaff: jest.fn(),
       } as never, // notifier
+      { record: jest.fn() } as never, // clearanceEvents
       { emit: jest.fn() } as never, // events
     );
     return { service, bookingsRepository, bookingBatchService, invoiceService };
@@ -172,6 +173,7 @@ describe('BookingTransitionService — requestOperation export space gate', () =
       {} as never, // invoiceService
       { validate20ftPairing: jest.fn().mockResolvedValue([]) } as never,
       notifier as never,
+      { record: jest.fn() } as never, // clearanceEvents
       { emit: jest.fn() } as never, // events
     );
     return { service, bookingsRepository, bookingBatchService };

apps/edr-freight-api/src/modules/bookings/booking-transition.paired-decision.spec.ts

@@ -32,6 +32,7 @@ describe('BookingTransitionService — paired staff decisions', () => {
       {} as never, // invoiceService
       {} as never, // containerValidationService
       {} as never, // notifier
+      { record: jest.fn() } as never, // clearanceEvents
       {} as never, // events
       undefined, // milestoneService
       dataSource as never,
@@ -62,7 +63,7 @@ describe('BookingTransitionService — paired staff decisions', () => {
     expect(result.partner.id).toBe('b-2');
   });
 
-  it('cancels both halves with the same reason', async () => {
+  it('cancels via cancel() once — its pair cascade settles the partner', async () => {
     const { service } = makeService(paired);
     const cancel = jest
       .spyOn(service, 'cancel')
@@ -72,21 +73,23 @@ describe('BookingTransitionService — paired staff decisions', () => {
       reason: 'customer withdrew',
     });
 
-    expect(cancel).toHaveBeenNthCalledWith(1, 'b-1', 'customer withdrew');
-    expect(cancel).toHaveBeenNthCalledWith(2, 'b-2', 'customer withdrew');
+    expect(cancel).toHaveBeenCalledTimes(1);
+    expect(cancel).toHaveBeenCalledWith('b-1', 'customer withdrew');
   });
 
   it('propagates a failure on the second half so neither is committed', async () => {
     const { service, dataSource } = makeService(paired);
     jest
-      .spyOn(service, 'cancel')
+      .spyOn(service, 'acceptIntake')
       .mockImplementationOnce(async (id) => ({ id }) as Booking)
       .mockImplementationOnce(async () => {
         throw new Error('partner is already in transit');
       });
 
     await expect(
-      service.applyPairedDecision('b-1', 'cancel', 'staff-1', { reason: 'x' }),
+      service.applyPairedDecision('b-1', 'accept', 'staff-1', {
+        validityDays: 30,
+      }),
     ).rejects.toThrow('partner is already in transit');
 
     // Both halves ran inside one transaction, so the throw rolls the first back.

apps/edr-freight-api/src/modules/bookings/booking-transition.service.ts

@@ -27,11 +27,16 @@ import { BookingPricingService } from './booking-pricing.service';
 import { ContainerValidationService } from './container-validation.service';
 import { BookingsRepository } from './bookings.repository';
 import { assertBookingStatus } from './booking-status.util';
-import { clearanceCodesForBooking } from './clearance.util';
+import {
+  adHocLabel,
+  clearanceCodesForBooking,
+  clearanceDocumentsOpen,
+} from './clearance.util';
 import {
   buildClearanceDocHistory,
   type ClearanceDocEvent,
 } from './clearance-doc-history.util';
+import { ClearanceEventService } from './clearance-event.service';
 import { computeNextStep, type BookingNextStep } from './booking-next-step.util';
 import { SubmitBookingResponseDto } from './dto/submit-booking-response.dto';
 import { PriceLineItemDto } from './dto/generate-price-response.dto';
@@ -72,6 +77,7 @@ export class BookingTransitionService {
     private readonly invoiceService: BookingInvoiceService,
     private readonly containerValidationService: ContainerValidationService,
     private readonly notifier: BookingLifecycleNotifierService,
+    private readonly clearanceEvents: ClearanceEventService,
     private readonly events: EventEmitter2,
     @Optional() private readonly milestoneService?: ClearanceMilestoneService,
     // Optional + last so the hand-constructed service in *.spec.ts files keeps
@@ -85,28 +91,10 @@ export class BookingTransitionService {
 
   /** Reject submit when the booking's 20ft containers can't be balanced onto wagons. */
   private async assert20ftPairable(booking: Booking): Promise<void> {
-    // Parity gate. 20ft ride two per wagon, so an odd total leaves one container
-    // that cannot be placed. Consolidation (pairing it with another customer's
-    // odd booking) is built end to end but switched off for now, so an odd total
-    // is rejected here rather than parked for a partner.
-    // containerSize is not always populated (some rows carry only the container
-    // type), so fall back to the type's sizeFt rather than silently skipping
-    // those lines and letting an odd booking through.
-    const ft20Quantity = (booking.bookingContainers ?? [])
-      .filter((bc) =>
-        bc.containerSize
-          ? bc.containerSize.includes("20")
-          : Number(bc.containerType?.sizeFt) === 20,
-      )
-      .reduce((sum, bc) => sum + Number(bc.quantity || 0), 0);
-    if (ft20Quantity % 2 === 1) {
-      throw new BadRequestException(
-        `20ft containers travel two per wagon, so they must be booked in even ` +
-          `numbers. This booking has ${ft20Quantity} — add one more or remove ` +
-          `one (book ${ft20Quantity + 1} or ${ft20Quantity - 1}).`,
-      );
-    }
-
+    // Odd 20ft totals are not rejected here: runConsolidationOnSubmit (called
+    // right after this gate) auto-pairs the odd leftover with another
+    // customer's odd booking or parks the booking as PENDING_CONSOLIDATION.
+    // Only the weight-pairing rule hard-blocks.
     const violations =
       await this.containerValidationService.validate20ftPairing(booking);
     if (violations.length) {
@@ -450,11 +438,44 @@ export class BookingTransitionService {
   async cancelHold(bookingId: string, reason?: string): Promise<Booking> {
     const booking = await this.bookingsService.findById(bookingId);
     assertBookingStatus(booking, ["SELECTED_FOR_BATCH"]);
-    if (booking.consolidationPartnerId) {
-      throw new BadRequestException(
-        "This booking shares a consolidated wagon with another booking — " +
-          "contact support to cancel it.",
+    // Consolidated pair: the shared wagon dies with this hold. An unpaid
+    // partner's hold is released with it (both cancel, no fee); a PAID partner
+    // cannot board alone, so the partnerLapsed listener cancels it too, with
+    // the cancellation fee — this unpaid canceller owes nothing (fees only
+    // apply to paid bookings).
+    const partnerId = booking.consolidationPartnerId;
+    if (partnerId) {
+      const partner = await this.bookingsService.findById(partnerId);
+      const partnerPaid =
+        partner.paymentStatus === "PAID" || partner.status === "PAID";
+      await this.bookingsRepository.clearConsolidationPair(
+        booking.id,
+        partnerId,
       );
+      if (partnerPaid) {
+        this.events.emit("booking.consolidation.partnerLapsed", {
+          paidBookingId: partnerId,
+        });
+      } else if (!["CANCELLED", "EXPIRED"].includes(partner.status)) {
+        const partnerReason = "Cancelled with its consolidation partner";
+        await this.bookingsRepository.createReviewNote(
+          partnerId,
+          partnerReason,
+          "REJECTION",
+        );
+        if (partner.status === "SELECTED_FOR_BATCH") {
+          await this.bookingBatchService.cancelReservation(partnerId);
+        } else {
+          await this.invoiceService.expireOpenInvoices(partnerId);
+          await this.bookingsRepository.update(partnerId, {
+            status: "CANCELLED",
+          } as never);
+        }
+        this.notifier.cancelled(
+          await this.bookingsService.findById(partnerId),
+          partnerReason,
+        );
+      }
     }
     await this.bookingsRepository.createReviewNote(
       bookingId,
@@ -508,6 +529,17 @@ export class BookingTransitionService {
       );
     }
 
+    // cancel() carries its own pair cascade (it settles the partner too), so
+    // running it twice would trip on the already-cancelled partner.
+    if (decision === "cancel") {
+      const own = await this.cancel(
+        bookingId,
+        options.reason ?? "Cancelled with its consolidation partner",
+      );
+      const other = await this.bookingsService.findById(partnerId);
+      return { booking: own, partner: other };
+    }
+
     const runOne = async (id: string): Promise<Booking> => {
       switch (decision) {
         case "accept":
@@ -519,11 +551,6 @@ export class BookingTransitionService {
             );
           }
           return this.acceptIntake(id, actorId, Number(options.validityDays));
-        case "cancel":
-          return this.cancel(
-            id,
-            options.reason ?? "Cancelled with its consolidation partner",
-          );
         case "operationAccept":
           return this.reviewOperationRequest(id, "ACCEPT", actorId, {
             note: options.note,
@@ -560,8 +587,54 @@ export class BookingTransitionService {
       "PENDING_APPROVAL",
       "CONTRACT_READY",
       "OPERATION_REQUEST_PENDING",
+      // A booking parked waiting for a consolidation partner can be walked
+      // away from — nothing is reserved yet.
+      "PENDING_CONSOLIDATION",
     ]);
 
+    // Consolidated pair: a shared wagon never ships half-full, so cancelling
+    // one half settles the other too. Neither paid → both cancel, no fee. A
+    // PAID partner cannot board alone, so the partnerLapsed listener cancels
+    // it too, with the cancellation fee — the unpaid canceller owes nothing
+    // (fees only apply to paid bookings). A PAID booking itself never comes
+    // through here (status gate above) — it cancels via wagon cancellation,
+    // where the fee machinery lives.
+    const partnerId = booking.consolidationPartnerId;
+    if (partnerId) {
+      const partner = await this.bookingsService.findById(partnerId);
+      const partnerPaid =
+        partner.paymentStatus === "PAID" || partner.status === "PAID";
+      await this.bookingsRepository.clearConsolidationPair(
+        booking.id,
+        partnerId,
+      );
+      if (partnerPaid) {
+        this.events.emit("booking.consolidation.partnerLapsed", {
+          paidBookingId: partnerId,
+        });
+      } else if (!["CANCELLED", "EXPIRED"].includes(partner.status)) {
+        const partnerReason = "Cancelled with its consolidation partner";
+        await this.bookingsRepository.createReviewNote(
+          partnerId,
+          partnerReason,
+          "REJECTION",
+        );
+        await this.invoiceService.expireOpenInvoices(partnerId);
+        if (partner.status === "SELECTED_FOR_BATCH") {
+          // Reserved hold: release the wagons through the batch engine.
+          await this.bookingBatchService.cancelReservation(partnerId);
+        } else {
+          await this.bookingsRepository.update(partnerId, {
+            status: "CANCELLED",
+          } as never);
+        }
+        this.notifier.cancelled(
+          await this.bookingsService.findById(partnerId),
+          partnerReason,
+        );
+      }
+    }
+
     await this.bookingsRepository.createReviewNote(
       bookingId,
       reason,
@@ -637,6 +710,13 @@ export class BookingTransitionService {
       history: ClearanceDocEvent[];
     }>;
     allApproved: boolean;
+    documentsOpen: boolean;
+    docRequests: Array<{
+      id: string;
+      note: string;
+      byName: string | null;
+      at: string;
+    }>;
     phase?: string | null;
     milestones?: unknown[];
     nextAction?: unknown;
@@ -668,9 +748,14 @@ export class BookingTransitionService {
       bookingId,
       "CHANGES_REQUESTED",
     );
+    const docRequestNotes = await this.bookingsRepository.findReviewNotes(
+      bookingId,
+      "ADDITIONAL_DOC_REQUEST",
+    );
     const reviewerNames = await this.bookingsRepository.resolveStaffNames([
       ...reviews.map((r) => r.reviewedByStaffId),
       ...queryNotes.map((n) => n.authorId),
+      ...docRequestNotes.map((n) => n.authorId),
     ]);
 
     const documents: Awaited<
@@ -725,7 +810,9 @@ export class BookingTransitionService {
       const review = reviewByKey.get(`custom:${f.code}`) ?? null;
       documents.push({
         fileKey: f.code,
-        label: f.name,
+        // What the customer called it, falling back to the filename for rows
+        // uploaded before the name was carried through.
+        label: f.title || adHocLabel(f.code) || f.name,
         required: false,
         uploadedBy: "customer",
         settingCode: "custom",
@@ -756,9 +843,52 @@ export class BookingTransitionService {
       outputCode,
       documents,
       allApproved,
+      documentsOpen: clearanceDocumentsOpen(booking),
+      docRequests: docRequestNotes.map((n) => ({
+        id: n.id,
+        note: n.note,
+        byName: n.authorId ? (reviewerNames.get(n.authorId) ?? null) : null,
+        at: n.createdAt.toISOString(),
+      })),
     };
   }
 
+  /**
+   * GL asks the customer for additional clearance document(s). Stored as a
+   * review-note thread shown on both the GL clearance page and the customer's
+   * portal; the customer answers with an ad-hoc upload. Allowed for as long as
+   * documents are open (until the shipment is paid).
+   */
+  async requestAdditionalDocuments(
+    bookingId: string,
+    note: string,
+    staffId: string,
+  ): Promise<void> {
+    const booking = await this.bookingsService.findById(bookingId);
+    if (!clearanceDocumentsOpen(booking)) {
+      throw new ConflictException(
+        `Clearance documents are closed for this booking (status "${booking.status}").`,
+      );
+    }
+    if (!note?.trim()) {
+      throw new BadRequestException("Describe the document(s) you need.");
+    }
+    await this.bookingsRepository.createReviewNote(
+      bookingId,
+      note.trim(),
+      "ADDITIONAL_DOC_REQUEST",
+      staffId,
+    );
+    await this.clearanceEvents.record({
+      bookingId,
+      action: "ADDITIONAL_DOCS_REQUESTED",
+      label: "Requested additional document(s) from the customer",
+      actorId: staffId,
+      metadata: { note: note.trim() },
+    });
+    this.notifier.additionalDocsRequested(booking, note.trim());
+  }
+
   /**
    * True when every REQUIRED field of the booking's customer-input clearance set
    * has an APPROVED review row. The 100% gate before clearance can be finalized.
@@ -795,12 +925,17 @@ export class BookingTransitionService {
   async submitClearanceDocuments(
     bookingId: string,
     files: Express.Multer.File[],
+    userId?: string,
   ): Promise<Booking> {
     const booking = await this.bookingsService.findById(bookingId);
-    assertBookingStatus(booking, [
-      "AWAITING_DOCUMENTS",
-      "DOCUMENTS_UNDER_REVIEW",
-    ]);
+    // Documents stay open until the shipment is paid — a customs shipment keeps
+    // collecting paperwork (amended invoices, port documents) well past
+    // clearance finalization. See {@link clearanceDocumentsOpen}.
+    if (!clearanceDocumentsOpen(booking)) {
+      throw new ConflictException(
+        `Clearance documents are closed for this booking (status "${booking.status}").`,
+      );
+    }
     const { inputCode } = clearanceCodesForBooking(booking);
     if (!inputCode) {
       throw new BadRequestException(
@@ -825,6 +960,10 @@ export class BookingTransitionService {
         resource: "bookings",
         code: file.fieldname,
         file,
+        // Ad-hoc uploads carry the name the customer typed (fieldname
+        // `custom_<label>_<n>`); it is what GL sees in the review grid instead
+        // of a raw filename like "scan_003.pdf".
+        title: adHocLabel(file.fieldname),
       });
       // Ad-hoc docs (custom_*) are not part of the required gate; still tracked.
       const settingCode = file.fieldname.startsWith("custom_")
@@ -838,21 +977,41 @@ export class BookingTransitionService {
       });
     }
 
-    await this.bookingsRepository.update(bookingId, {
-      status: "DOCUMENTS_UNDER_REVIEW",
-    } as never);
+    // Only the pre-finalization submission drives the booking into review.
+    // A later addition (an amended invoice while the shipment is already
+    // scheduled) must never rewind the status or reopen the phased workflow —
+    // it lands as a new PENDING document for GL to approve where it stands.
+    const inDocumentPhase =
+      booking.status === "AWAITING_DOCUMENTS" ||
+      booking.status === "DOCUMENTS_UNDER_REVIEW";
 
-    if (this.isPhasedCustoms(booking)) {
-      await this.workflowService.onCustomerDocsUploadedForBooking(
-        bookingId,
-        booking.tradeDirection ?? 'IMPORT',
-      );
-      await this.workflowService.onDocumentReviewReopenedForBooking(bookingId);
+    if (inDocumentPhase) {
       await this.bookingsRepository.update(bookingId, {
-        clearanceCurrentPhase: ContractDocPhase.GlEtReview,
+        status: "DOCUMENTS_UNDER_REVIEW",
       } as never);
+
+      if (this.isPhasedCustoms(booking)) {
+        await this.workflowService.onCustomerDocsUploadedForBooking(
+          bookingId,
+          booking.tradeDirection ?? 'IMPORT',
+        );
+        await this.workflowService.onDocumentReviewReopenedForBooking(bookingId);
+        await this.bookingsRepository.update(bookingId, {
+          clearanceCurrentPhase: ContractDocPhase.GlEtReview,
+        } as never);
+      }
     }
 
+    const fileKeys = files.map((f) => f.fieldname);
+    await this.clearanceEvents.record({
+      bookingId,
+      action: 'DOCS_SUBMITTED',
+      label: `Customer submitted ${files.length} clearance document(s): ${fileKeys.join(', ')}`,
+      actorType: 'CUSTOMER',
+      actorId: userId ?? null,
+      metadata: { fileKeys },
+    });
+
     const fresh = await this.bookingsService.findById(bookingId);
     this.notifier.clearanceDocsUploadedToStaff(fresh);
     return fresh;
@@ -905,7 +1064,14 @@ export class BookingTransitionService {
     note?: string,
   ): Promise<Booking> {
     const booking = await this.bookingsService.findById(bookingId);
-    assertBookingStatus(booking, ["DOCUMENTS_UNDER_REVIEW"]);
+    // GL keeps reviewing for as long as the customer can still submit — the
+    // two sides share one predicate so they can never drift apart. Documents
+    // added after clearance was finalized still need approving/querying.
+    if (!clearanceDocumentsOpen(booking)) {
+      throw new ConflictException(
+        `Clearance documents are closed for this booking (status "${booking.status}").`,
+      );
+    }
     const { inputCode, outputCode } = clearanceCodesForBooking(booking);
 
     const existing =
@@ -922,15 +1088,6 @@ export class BookingTransitionService {
         "A note is required when querying a document",
       );
     }
-    if (
-      status === 'QUERIED' &&
-      this.isPhasedCustoms(booking) &&
-      booking.preClearanceFinalizedAt
-    ) {
-      throw new BadRequestException(
-        'Customer documents cannot be queried after pre-clearance is finalized.',
-      );
-    }
 
     await this.bookingsRepository.setDocumentReviewStatus(
       bookingId,
@@ -940,6 +1097,16 @@ export class BookingTransitionService {
       staffId,
       note,
     );
+    await this.clearanceEvents.record({
+      bookingId,
+      action: status === 'APPROVED' ? 'DOC_APPROVED' : 'DOC_QUERIED',
+      label:
+        status === 'APPROVED'
+          ? `Approved document "${fileKey.replace(/_/g, ' ')}"`
+          : `Opened query on document "${fileKey.replace(/_/g, ' ')}"`,
+      actorId: staffId,
+      metadata: { fileKey, note: note ?? null },
+    });
     if (status === "QUERIED") {
       await this.bookingsRepository.createReviewNote(
         bookingId,
@@ -947,7 +1114,10 @@ export class BookingTransitionService {
         "CHANGES_REQUESTED",
         staffId,
       );
-      if (this.isPhasedCustoms(booking)) {
+      // Reopening the review phase only makes sense while clearance is still
+      // being decided. Querying a document that arrived afterwards must not
+      // drag a finalized shipment back into the GL review phase.
+      if (this.isPhasedCustoms(booking) && !booking.preClearanceFinalizedAt) {
         await this.workflowService.onDocumentReviewReopenedForBooking(bookingId);
         await this.bookingsRepository.update(bookingId, {
           clearanceCurrentPhase: ContractDocPhase.GlEtReview,
@@ -959,7 +1129,10 @@ export class BookingTransitionService {
     if (status === "QUERIED") {
       this.notifier.documentQueried(updated, fileKey, note ?? '');
     }
-    if (this.isPhasedCustoms(updated)) {
+    // Same reasoning as the query branch: advance the workflow only while
+    // clearance is still open. Approving a late-added document leaves an
+    // already-finalized shipment's phase exactly where it is.
+    if (this.isPhasedCustoms(updated) && !updated.preClearanceFinalizedAt) {
       const allApproved = await this.isClearanceFullyApproved(updated);
       if (allApproved) {
         await this.workflowService.onAllDocsApprovedForBooking(bookingId);
@@ -980,6 +1153,7 @@ export class BookingTransitionService {
   async uploadClearanceOutputDocuments(
     bookingId: string,
     files: Express.Multer.File[],
+    userId?: string,
   ): Promise<Booking> {
     const booking = await this.bookingsService.findById(bookingId);
     assertBookingStatus(booking, ["DOCUMENTS_UNDER_REVIEW"]);
@@ -1000,6 +1174,15 @@ export class BookingTransitionService {
         file,
       });
     }
+    await this.clearanceEvents.record({
+      bookingId,
+      action: 'OUTPUT_DOCS_UPLOADED',
+      label: `Uploaded customs output document(s): ${files
+        .map((f) => f.fieldname.replace(/_/g, ' '))
+        .join(', ')}`,
+      actorId: userId ?? null,
+      metadata: { fileKeys: files.map((f) => f.fieldname) },
+    });
     return this.bookingsService.findById(bookingId);
   }
 
@@ -1007,7 +1190,7 @@ export class BookingTransitionService {
    * GL confirms clearance: requires every customer document APPROVED (100% gate)
    * and, for customs, the required output documents present → CLEARANCE_READY.
    */
-  async finalizeClearance(bookingId: string): Promise<Booking> {
+  async finalizeClearance(bookingId: string, userId?: string): Promise<Booking> {
     const booking = await this.bookingsService.findById(bookingId);
     if (this.isPhasedCustoms(booking)) {
       throw new BadRequestException(
@@ -1063,6 +1246,12 @@ export class BookingTransitionService {
     await this.bookingsRepository.update(bookingId, {
       status: "CLEARANCE_READY",
     } as never);
+    await this.clearanceEvents.record({
+      bookingId,
+      action: 'CLEARANCE_FINALIZED',
+      label: 'Finalized document approval — clearance ready',
+      actorId: userId ?? null,
+    });
     const fresh = await this.bookingsService.findById(bookingId);
     this.notifier.clearanceReady(fresh);
     return fresh;
@@ -1089,6 +1278,8 @@ export class BookingTransitionService {
        * the customer pools, so the gate here would wrongly reject them).
        */
       bypassDayPool?: boolean;
+      /** Acting user, recorded in the clearance history. */
+      userId?: string;
     },
   ): Promise<Booking> {
     const booking = await this.bookingsService.findById(bookingId);
@@ -1203,6 +1394,14 @@ export class BookingTransitionService {
       scheduledDate: date,
       requestedTrainScheduleId: requestedId,
     } as never);
+    await this.clearanceEvents.record({
+      bookingId,
+      action: 'OPERATION_REQUESTED',
+      label: `Requested operation for shipment day ${scheduledDate}`,
+      actorType: 'CUSTOMER',
+      actorId: opts?.userId ?? null,
+      metadata: { scheduledDate },
+    });
     const fresh = await this.bookingsService.findById(bookingId);
     this.notifier.operationRequestedToStaff(fresh);
     return fresh;

apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.spec.ts

@@ -1,6 +1,10 @@
 import { BadRequestException } from '@nestjs/common';
 
 import { BookingWagonCancellationService } from './booking-wagon-cancellation.service';
+import {
+  bulkTonWagonsRequired,
+  bulkTonsPerWagonFor,
+} from '../train-scheduling/train-capacity.util';
 
 /**
  * Sizing of a bulk quantity cut (no DB touched on this branch): a whole-booking
@@ -40,3 +44,158 @@ describe('BookingWagonCancellationService.resolveRequestedCut (bulk)', () => {
     expect(cut.weightTons).toBeCloseTo(62.625, 3);
   });
 });
+
+/**
+ * Odd-20ft credit rebook: the rebooked booking shares a wagon again, so GL
+ * must pick the consolidation partner — no partner, no rebook; a partner
+ * already paired elsewhere is refused.
+ */
+describe('BookingWagonCancellationService.rebook (odd-20ft consolidation)', () => {
+  const units = Array.from({ length: 3 }, (_, i) => ({
+    containerSize: '20ft',
+    containerNumber: `CONT${i}`,
+    sealNumber: null,
+    vgmTons: 10,
+    isHazardous: false,
+    isReefer: false,
+  }));
+  const row = {
+    id: 'wc1',
+    bookingId: 'b1',
+    status: 'CREDIT_AVAILABLE',
+    creditAmount: 100,
+    cancelledQuantities: { bySize: { '20ft': 3 }, units },
+  };
+  const source = {
+    id: 'b1',
+    contractId: 'c1',
+    paymentCurrency: 'USD',
+    originYardId: 'y1',
+    destinationYardId: 'y2',
+    tradeDirection: 'IMPORT',
+  };
+
+  const makeSvc = (partner?: unknown) => {
+    const svc = Object.create(BookingWagonCancellationService.prototype) as Record<
+      string,
+      unknown
+    > & {
+      rebook(id: string, dto: unknown): Promise<unknown>;
+    };
+    svc.repo = { findById: async () => row };
+    svc.bookingsRepository = {
+      findById: async () => source,
+      findByIdWithFiles: async () => partner ?? null,
+    };
+    return svc;
+  };
+
+  it('refuses an odd-20ft rebook without a GL-picked partner', async () => {
+    await expect(
+      makeSvc().rebook('wc1', { scheduledDate: '2026-09-01' }),
+    ).rejects.toThrow(/pick a consolidation partner/i);
+  });
+
+  it('refuses a partner that already shares a wagon', async () => {
+    const paired = {
+      id: 'p1',
+      reference: 'BK-1',
+      status: 'SUBMITTED',
+      consolidationPartnerId: 'someone-else',
+    };
+    await expect(
+      makeSvc(paired).rebook('wc1', {
+        scheduledDate: '2026-09-01',
+        partnerBookingId: 'p1',
+      }),
+    ).rejects.toThrow(/already shares a wagon/i);
+  });
+});
+
+/**
+ * A NUMBER_OF_WAGONS booking pins its count in `bulkRequestedWagons`, and
+ * bulkTonWagonsRequired honours that verbatim. Partial cancel must shrink it
+ * alongside wagonsRequired/cargoTotalWeightVgm — left stale, the booking
+ * re-inflates to its pre-cancel count on the next allocation and each wagon
+ * carries tons / stale-count instead of the real even share.
+ */
+describe('partial cancel of a NUMBER_OF_WAGONS bulk booking', () => {
+  // 980T over 14 wagons (70T each), 2 wagons cancelled.
+  const before = { freightType: 'BULK', cargoTotalWeightVgm: 980, bulkRequestedWagons: 14 };
+  const droppedWeight = 140;
+  const wagonsCancelled = 2;
+
+  // The decrement applied in applyPaidCut's booking update.
+  const after = {
+    ...before,
+    cargoTotalWeightVgm: before.cargoTotalWeightVgm - droppedWeight,
+    bulkRequestedWagons: Math.max(
+      0,
+      Math.floor(before.bulkRequestedWagons - wagonsCancelled),
+    ),
+  };
+
+  it('reallocates at the reduced count, not the pre-cancel one', () => {
+    expect(bulkTonWagonsRequired(before, undefined, 'nw5', 70)).toBe(14);
+    expect(bulkTonWagonsRequired(after, undefined, 'nw5', 70)).toBe(12);
+  });
+
+  it('keeps tons-per-wagon at the real even share', () => {
+    // Stale count would spread 840T over 14 wagons → 60T each.
+    expect(bulkTonsPerWagonFor(after, undefined, 'nw5', 70)).toBe(70);
+  });
+
+  it('cancelling every wagon leaves no requested count behind', () => {
+    const all = Math.max(0, Math.floor(before.bulkRequestedWagons - 14));
+    expect(all).toBe(0);
+    expect(bulkTonWagonsRequired(
+      { ...before, cargoTotalWeightVgm: 0, bulkRequestedWagons: all },
+      undefined,
+      'nw5',
+      70,
+    )).toBe(0);
+  });
+});
+
+/**
+ * Rebooking a NUMBER_OF_WAGONS bulk credit: the create path rejects the rebook
+ * unless the DTO carries a wagon count ("<cargo> is booked by wagons — enter
+ * the number of wagons needed"), and the quantities snapshot holds tons only.
+ * The count therefore has to come off the cancellation row itself.
+ */
+describe('BookingWagonCancellationService.buildRebookDto (bulk wagon count)', () => {
+  const svc = Object.create(BookingWagonCancellationService.prototype) as {
+    buildRebookDto(
+      row: unknown,
+      scheduledDate: string,
+      overrides?: unknown,
+    ): { bulkLines?: { cargoWeightTons: number }[]; requestedWagons?: number };
+  };
+
+  it('carries the cancelled wagon count onto the rebook', () => {
+    const dto = svc.buildRebookDto(
+      { wagonsCancelled: 2, weightTons: 140, cancelledQuantities: { bulkTons: 140 } },
+      '2026-09-10',
+    );
+    expect(dto.bulkLines).toEqual([{ cargoWeightTons: 140 }]);
+    // Without this the create path throws before the booking is ever made.
+    expect(dto.requestedWagons).toBe(2);
+  });
+
+  it('rounds a fractional cut up to a whole wagon', () => {
+    const dto = svc.buildRebookDto(
+      { wagonsCancelled: 0.5, weightTons: 35, cancelledQuantities: { bulkTons: 35 } },
+      '2026-09-10',
+    );
+    // Flooring would send 0 into a check that demands >= 1.
+    expect(dto.requestedWagons).toBe(1);
+  });
+
+  it('leaves the count off when nothing was cancelled', () => {
+    const dto = svc.buildRebookDto(
+      { wagonsCancelled: 0, weightTons: 0, cancelledQuantities: { bulkTons: 12 } },
+      '2026-09-10',
+    );
+    expect(dto.requestedWagons).toBeUndefined();
+  });
+});

apps/edr-freight-api/src/modules/bookings/booking-wagon-cancellation.service.ts

@@ -7,6 +7,7 @@ import {
   Logger,
   NotFoundException,
 } from '@nestjs/common';
+import { EventEmitter2, OnEvent } from '@nestjs/event-emitter';
 import { ExchangeService } from '@edr/api-common';
 import { Freight, NotificationAudience, NotificationType } from '@edr/types';
 import { DataSource, EntityManager, In, IsNull } from 'typeorm';
@@ -24,6 +25,8 @@ import { Rate } from '../rule-engine/entities/rate.entity';
 import { BookingBatchService } from '../train-scheduling/booking-batch.service';
 import { TrainSchedulingService } from '../train-scheduling/services/train-scheduling.service';
 import { TrainScheduleBooking } from '../train-schedules/entities/train-schedule-booking.entity';
+import { TrainSchedule } from '../train-schedules/entities/train-schedule.entity';
+import { TrainSetWagon } from '../train-sets/entities/train-set-wagon.entity';
 import { WagonAllocationBulkLoad } from '../train-schedules/entities/wagon-allocation-bulk-load.entity';
 import { WagonAllocationContainerItem } from '../train-schedules/entities/wagon-allocation-container-item.entity';
 import { WagonBookingAllocation } from '../train-schedules/entities/wagon-booking-allocation.entity';
@@ -34,7 +37,9 @@ import {
 } from './booking-wagon-cancellations.repository';
 import { BookingsRepository } from './bookings.repository';
 import {
+  CancelRemainingWagonsDto,
   RebookCancelledWagonsDto,
+  RebookContainerLineDto,
   RequestWagonCancellationDto,
 } from './dto/wagon-cancellation.dto';
 import { Booking } from './entities/booking.entity';
@@ -44,8 +49,11 @@ import {
   BookingWagonCancellation,
   CancelledQuantities,
   CancelledUnitSnapshot,
+  WAGON_CANCEL_FEE_INVOICE_TYPE,
 } from './entities/booking-wagon-cancellation.entity';
 
+export { WAGON_CANCEL_FEE_INVOICE_TYPE };
+
 /**
  * rates.rate_type of the cancellation fee — an existing rate-engine type
  * (trigger CANCELLATION, never auto-applied to booking pricing). Staff
@@ -58,8 +66,6 @@ export const WAGON_CANCELLATION_FEE_RATE_TYPE = 'CANCELLATION_FEE';
 /** `booking_container.container_size` is stored as "20ft"/"40ft" — `Number()` on it is NaN. */
 const sizeFtOf = (size: string | number | null | undefined): number =>
   parseInt(String(size ?? ''), 10);
-/** invoices.type of the fee invoice — the settlement branch key in BookingInvoiceService. */
-export const WAGON_CANCEL_FEE_INVOICE_TYPE = 'WAGON_CANCEL_FEE';
 
 const round2 = (n: number): number => Math.round(n * 100) / 100;
 const round3 = (n: number): number => Math.round(n * 1000) / 1000;
@@ -123,6 +129,7 @@ export class BookingWagonCancellationService {
     @Inject(forwardRef(() => FirstMileService))
     private readonly firstMile: FirstMileService,
     private readonly inbox: NotificationInboxService,
+    private readonly events: EventEmitter2,
   ) {}
 
   // ── T1: request ────────────────────────────────────────────────────────────
@@ -140,7 +147,29 @@ export class BookingWagonCancellationService {
     creditAmount: number;
   }> {
     const booking = await this.loadCancellableBooking(bookingId);
-    const cut = await this.resolveRequestedCut(booking, dto);
+    // Empty dto = the whole booking ("Cancel booking" button).
+    const cut = this.isEmptyCut(dto)
+      ? await this.resolveFullCut(booking)
+      : await this.resolveRequestedCut(booking, dto);
+    // Consolidated booking: preview the same rules the request enforces — a
+    // full cut breaks the pair (canceller fee = ceil of its fractional
+    // wagons); a partial cut must spare the shared wagon.
+    if (booking.consolidationPartnerId) {
+      const full = await this.resolveFullCut(booking);
+      if (cut.wagons >= full.wagons) {
+        const feeWagons = Math.ceil(cut.wagons);
+        const fee = await this.priceFee(booking, { ...cut, wagons: feeWagons });
+        return {
+          wagons: cut.wagons,
+          weightTons: cut.weightTons,
+          feePerWagon: fee.perWagon,
+          feeAmount: fee.amount,
+          feeCurrency: fee.currency,
+          creditAmount: this.creditFor(booking, Number(booking.wagonsRequired ?? 0)),
+        };
+      }
+      this.assertCutSparesSharedWagon(cut);
+    }
     const fee = await this.priceFee(booking, cut);
     return {
       wagons: cut.wagons,
@@ -158,6 +187,24 @@ export class BookingWagonCancellationService {
     userId?: string,
   ): Promise<BookingWagonCancellation> {
     const booking = await this.loadCancellableBooking(bookingId);
+    // Consolidated booking: the shared wagon itself is untouchable — its other
+    // half belongs to the partner. The customer may still cancel
+    //  - the WHOLE booking (breaks the pair: both cancel, ceil/floor fees), or
+    //  - a PARTIAL cut of their own full wagons — an EVEN number of 20ft
+    //    containers, so the odd one stays on the shared wagon and the pair
+    //    survives untouched.
+    if (booking.consolidationPartnerId) {
+      if (this.isEmptyCut(dto)) {
+        return this.cancelConsolidatedPair(booking, dto.reason ?? null, userId);
+      }
+      const full = await this.resolveFullCut(booking);
+      const cut = await this.resolveRequestedCut(booking, dto);
+      if (cut.wagons >= full.wagons) {
+        return this.cancelConsolidatedPair(booking, dto.reason ?? null, userId);
+      }
+      this.assertCutSparesSharedWagon(cut);
+      // fall through: a pair-safe partial cut rides the normal partial flow.
+    }
     const open = await this.repo.findOpenForBooking(bookingId);
     if (open) {
       throw new ConflictException(
@@ -165,7 +212,10 @@ export class BookingWagonCancellationService {
       );
     }
 
-    const cut = await this.resolveRequestedCut(booking, dto);
+    // Empty dto = the whole booking ("Cancel booking" button).
+    const cut = this.isEmptyCut(dto)
+      ? await this.resolveFullCut(booking)
+      : await this.resolveRequestedCut(booking, dto);
     const fee = await this.priceFee(booking, cut);
     const feeAmount = fee.amount;
     const creditAmount = this.creditFor(booking, cut.wagons);
@@ -280,6 +330,291 @@ export class BookingWagonCancellationService {
     return (await this.repo.update(row.id, { status: 'WITHDRAWN' }))!;
   }
 
+  // ── Consolidated-pair cancellation ──────────────────────────────────────────
+
+  /**
+   * Cancel BOTH halves of a consolidated pair — a shared wagon never ships
+   * half-full, so a paired booking always cancels whole, together with its
+   * partner.
+   *
+   * Fee split (the canceller's leftover 20ft claims the shared wagon):
+   * canceller pays ceil(its wagons), the partner floor(its wagons) — e.g.
+   * 11 + 13 × 20ft = 12 wagons → canceller 7, partner 5, total 12. A PAID side
+   * keeps its full freight as a rebooking credit (rebooked by GL through the
+   * normal rebook endpoint once its fee settles); an UNPAID partner is
+   * cancelled with no fee and no credit.
+   */
+  private async cancelConsolidatedPair(
+    booking: Booking,
+    reason: string | null,
+    userId?: string,
+  ): Promise<BookingWagonCancellation> {
+    const partnerId = booking.consolidationPartnerId!;
+    const partner = await this.bookingsRepository.findById(partnerId);
+    if (!partner) {
+      throw new NotFoundException(`Partner booking ${partnerId} not found.`);
+    }
+    const partnerPaid =
+      partner.paymentStatus === 'PAID' || partner.status === 'PAID';
+
+    // Break the link first — every write below treats each side singly.
+    await this.bookingsRepository.clearConsolidationPair(booking.id, partnerId);
+
+    const row = await this.openConsolidationBreak(
+      booking,
+      'ceil',
+      this.creditFor(booking, Number(booking.wagonsRequired ?? 0)),
+      reason ?? 'Consolidated pair cancelled',
+      userId,
+    );
+    if (partnerPaid) {
+      await this.openConsolidationBreak(
+        partner,
+        'floor',
+        this.creditFor(partner, Number(partner.wagonsRequired ?? 0)),
+        `Cancelled with its consolidation partner ${booking.reference}`,
+        userId,
+      );
+    } else {
+      // Unpaid partner: no fee — just make sure no payable invoice stays open.
+      await this.billing
+        .expirePayable(Freight.InvoiceSource.Booking, partner.id, 'PREPAID')
+        .catch(() => undefined);
+    }
+
+    for (const b of [booking, partner]) {
+      await this.dataSource.getRepository(Booking).update(b.id, {
+        status: 'CANCELLED',
+        trainScheduleId: null,
+        requestedTrainScheduleId: null,
+        // A dead booking holds no shipment day — leaving it set lets the
+        // stranded-PAID day sweep pick the booking up and resurrect it.
+        scheduledDate: null,
+      });
+      await this.detachFromSchedule(b);
+    }
+    this.notifyCustomer(
+      booking,
+      'Consolidated booking cancelled',
+      `${booking.reference} shared a wagon with another booking, so both are cancelled. Your paid freight is kept as credit — pay the cancellation fee to rebook.`,
+    );
+    this.notifyCustomer(
+      partner,
+      'Consolidated booking cancelled',
+      partnerPaid
+        ? `${partner.reference} shared a wagon with a booking that was cancelled, so it is cancelled too. Your paid freight is kept as credit — pay the cancellation fee to rebook.`
+        : `${partner.reference} shared a wagon with a booking that was cancelled, so it is cancelled too. Nothing was paid — no fee applies.`,
+    );
+    this.notifyStaff(
+      booking,
+      'Consolidated pair cancelled',
+      `${booking.reference} + ${partner.reference}: shared-wagon pair cancelled; cancellation fee invoice(s) issued.`,
+    );
+    return row;
+  }
+
+  /**
+   * Open one side's ledger row for a consolidation break: a FULL cut whose fee
+   * is priced on the ceil/floor split of the cut's own FRACTIONAL wagons —
+   * never booking.wagonsRequired, which the contract flow persists already
+   * ceiled (3 × 20ft is stored as 2, not 1.5, and floor(2) would over-charge
+   * the partner). E.g. 1 + 3 × 20ft: canceller ceil(0.5) = 1 wagon, partner
+   * floor(1.5) = 1 wagon — 2 wagons total, matching the pair's real space.
+   * feeWagons 0 (the floor side of a lone 20ft) skips the fee entirely — the
+   * row goes straight to CREDIT_AVAILABLE.
+   */
+  private async openConsolidationBreak(
+    booking: Booking,
+    mode: 'ceil' | 'floor',
+    creditAmount: number,
+    reason: string,
+    userId?: string,
+  ): Promise<BookingWagonCancellation> {
+    const open = await this.repo.findOpenForBooking(booking.id);
+    if (open) {
+      throw new ConflictException(
+        `Booking ${booking.reference} already has a cancellation awaiting its fee. Pay or withdraw it first.`,
+      );
+    }
+    const cut = await this.resolveFullCut(booking);
+    const feeWagons =
+      mode === 'ceil' ? Math.ceil(cut.wagons) : Math.floor(cut.wagons);
+    // The pair is dead the moment it breaks — the wagons leave the schedule
+    // with the cancel itself, so T2 must not release them again.
+    const quantities = { ...cut.quantities, releasedAtRequest: true };
+
+    if (feeWagons <= 0) {
+      return this.repo.create({
+        bookingId: booking.id,
+        wagonsCancelled: cut.wagons,
+        weightTons: cut.weightTons,
+        cancelledQuantities: quantities,
+        creditAmount,
+        feeAmount: 0,
+        feeCurrency: booking.paymentCurrency ?? 'ETB',
+        status: 'CREDIT_AVAILABLE',
+        feePaidAt: new Date(),
+        reason,
+        requestedByUserId: userId ?? null,
+      });
+    }
+
+    const fee = await this.priceFee(booking, { ...cut, wagons: feeWagons });
+    const row = await this.repo.create({
+      bookingId: booking.id,
+      wagonsCancelled: cut.wagons,
+      weightTons: cut.weightTons,
+      cancelledQuantities: quantities,
+      creditAmount,
+      feeRateId: fee.rates[0].id,
+      feeAmount: fee.amount,
+      feeCurrency: fee.currency,
+      status: 'FEE_PENDING',
+      reason,
+      requestedByUserId: userId ?? null,
+    });
+    const invoice = await this.billing.generateInvoice({
+      source: Freight.InvoiceSource.Booking,
+      sourceId: booking.id,
+      type: WAGON_CANCEL_FEE_INVOICE_TYPE,
+      companyId: booking.companyId,
+      companyProfileId: booking.companyProfileId,
+      currency: fee.currency,
+      lines: [
+        {
+          chargeType: 'CANCELLATION_FEE',
+          description: `Consolidation cancellation fee — ${feeWagons} wagon(s) of booking ${booking.reference}`,
+          quantity: feeWagons,
+          unitRate: fee.perWagon,
+          amount: fee.amount,
+          currency: fee.currency,
+          metadata: { wagonCancellationId: row.id },
+        },
+      ],
+      totalAmount: fee.amount,
+      status: Freight.InvoiceStatus.Issued,
+    });
+    return (await this.repo.update(row.id, { feeInvoiceId: invoice.id })) ?? row;
+  }
+
+  /** No cut named at all — the "Cancel booking" button cancelling everything. */
+  private isEmptyCut(dto: RequestWagonCancellationDto): boolean {
+    return (
+      !dto.containers?.length && !dto.wagonAllocationIds?.length && !dto.wagons
+    );
+  }
+
+  /**
+   * A partial cut on a consolidated booking must leave the shared wagon whole:
+   * the odd 20ft riding it stays, so the cut's 20ft count must be EVEN (whole
+   * own wagons only). An odd cut — including picking the shared wagon itself in
+   * the Wagons tab (it contributes exactly one 20ft) — is rejected.
+   */
+  private assertCutSparesSharedWagon(cut: RequestedCut): void {
+    const ft20Cut = Object.entries(cut.quantities.bySize ?? {})
+      .filter(([size]) => sizeFtOf(size) === 20)
+      .reduce((sum, [, qty]) => sum + qty, 0);
+    if (ft20Cut % 2 === 1) {
+      throw new BadRequestException(
+        'This booking shares a wagon with another booking — the shared wagon cannot be cancelled on its own. Cancel an even number of 20ft containers (your own whole wagons), or cancel the whole booking to end the consolidation.',
+      );
+    }
+  }
+
+  /** The whole booking as a cut — everything it still carries. */
+  private async resolveFullCut(booking: Booking): Promise<RequestedCut> {
+    if (booking.freightType === 'CONTAINER') {
+      const lines = await this.dataSource.getRepository(BookingContainer).find({
+        where: { bookingId: booking.id },
+      });
+      const bySize = new Map<string, number>();
+      for (const line of lines) {
+        const size = line.containerSize ?? '';
+        bySize.set(size, (bySize.get(size) ?? 0) + Number(line.quantity ?? 0));
+      }
+      const containers = [...bySize.entries()]
+        .filter(([, quantity]) => quantity > 0)
+        .map(([containerSize, quantity]) => ({ containerSize, quantity }));
+      return this.resolveRequestedCut(booking, {
+        containers,
+      } as RequestWagonCancellationDto);
+    }
+    return this.resolveRequestedCut(booking, {
+      wagons: Number(booking.wagonsRequired ?? 0),
+    } as RequestWagonCancellationDto);
+  }
+
+  /**
+   * A consolidation pair broke with only one side PAID: the unpaid half
+   * expired/cancelled fee-free (cancellation fees only ever apply to a paid
+   * booking), and the PAID half cannot board either — its odd 20ft has no
+   * partner for the shared wagon. So the PAID booking is cancelled too, owing
+   * the cancellation fee on ceil of its own fractional wagons (shared wagon
+   * included); its paid freight is kept as rebooking credit. Once the fee
+   * settles, GL staff rebook it through a normal new booking, where its odd
+   * 20ft goes through consolidation pairing again.
+   */
+  @OnEvent('booking.consolidation.partnerLapsed')
+  async onConsolidationPartnerLapsed(payload: {
+    paidBookingId: string;
+  }): Promise<void> {
+    try {
+      const booking = await this.bookingsRepository.findById(
+        payload.paidBookingId,
+      );
+      if (!booking) return;
+      if (['CANCELLED', 'EXPIRED', 'COMPLETED'].includes(booking.status)) return;
+      if (await this.repo.findOpenForBooking(booking.id)) return; // already charged
+      const row = await this.openConsolidationBreak(
+        booking,
+        'ceil',
+        this.creditFor(booking, Number(booking.wagonsRequired ?? 0)),
+        'Consolidation partner lapsed unpaid — paired booking cancelled, cancellation fee applies',
+      );
+      await this.dataSource.getRepository(Booking).update(booking.id, {
+        status: 'CANCELLED',
+        trainScheduleId: null,
+        requestedTrainScheduleId: null,
+        // A dead booking holds no shipment day — leaving it set lets the
+        // stranded-PAID day sweep pick the booking up and resurrect it.
+        scheduledDate: null,
+      });
+      await this.detachFromSchedule(booking);
+      this.notifyCustomer(
+        booking,
+        'Consolidated booking cancelled',
+        `${booking.reference} shared a wagon with a booking that was never paid, so it cannot board and is cancelled. A cancellation fee for ${Math.ceil(Number(row.wagonsCancelled))} wagon(s) has been invoiced; your paid freight is kept as credit — settle the fee and EDR staff will rebook you.`,
+      );
+      this.notifyStaff(
+        booking,
+        'Consolidation partner lapsed — paid booking cancelled',
+        `${booking.reference}: its consolidation partner lapsed unpaid, so the paid booking is cancelled with a cancellation fee invoice. Rebook it from its credit once the fee settles (it must pair up again).`,
+      );
+    } catch (err) {
+      this.logger.error(
+        `Consolidation-lapse cancellation failed for paid booking ${payload.paidBookingId}: ${err instanceof Error ? err.message : String(err)}`,
+      );
+      // A silent failure here leaves a PAID half-wagon booking boarding alone
+      // (BK-2026-000201: no LIVE IMPORT 20ft CANCELLATION_FEE rate — the fee
+      // pricing threw and the booking stayed PAID). Scream to staff so it is
+      // fixed and the booking cancelled by hand instead of shipping.
+      try {
+        const failed = await this.bookingsRepository.findById(
+          payload.paidBookingId,
+        );
+        if (failed) {
+          this.notifyStaff(
+            failed,
+            'Consolidation-lapse cancellation FAILED — action needed',
+            `${failed.reference}: its consolidation partner lapsed unpaid, but the automatic cancellation failed: ${err instanceof Error ? err.message : String(err)}. Fix the cause (usually a missing LIVE per-wagon CANCELLATION_FEE rate for this trade direction + container size), then cancel the whole booking manually so the fee is invoiced and its wagons are freed.`,
+          );
+        }
+      } catch {
+        // Notification is best-effort — the error log above already fired.
+      }
+    }
+  }
+
   // ── T2: fee settled ─────────────────────────────────────────────────────────
 
   /**
@@ -293,7 +628,14 @@ export class BookingWagonCancellationService {
       this.logger.warn(`No wagon cancellation for paid fee invoice ${feeInvoiceId}.`);
       return;
     }
-    if (row.status !== 'FEE_PENDING') return;
+    if (row.status !== 'FEE_PENDING') {
+      // At-loading cancels apply the cut immediately and leave the invoice
+      // open — settle only the payment stamp when the customer pays later.
+      if (!row.feePaidAt) {
+        await this.repo.update(row.id, { feePaidAt: new Date() });
+      }
+      return;
+    }
 
     // The fee can settle after loading started (slow payment). Never cut
     // loaded cargo: leave the row FEE_PENDING and alert staff to resolve
@@ -321,6 +663,25 @@ export class BookingWagonCancellationService {
       return;
     }
 
+    await this.applyCut(row, releasedEarly, { feeSettled: true });
+    this.logger.log(
+      `Wagon cancellation ${row.id}: fee paid, booking ${row.bookingId} reduced by ${row.wagonsCancelled} wagon(s).`,
+    );
+  }
+
+  /**
+   * Apply the cut to the booking: reduce quantities/wagons/amount, release the
+   * cancelled allocations, flip the row to CREDIT_AVAILABLE. Runs at fee
+   * settlement for the customer-requested flow (feeSettled: true) and
+   * immediately for at-loading cancels (feeSettled only when no fee is owed —
+   * EDR fault; a customer-fault cut leaves feePaidAt null until the open
+   * invoice settles via onFeePaid).
+   */
+  private async applyCut(
+    row: BookingWagonCancellation,
+    releasedEarly: boolean,
+    opts: { feeSettled: boolean },
+  ): Promise<void> {
     await this.dataSource.transaction(async (manager) => {
       const booking = await manager.getRepository(Booking).findOne({
         where: { id: row.bookingId },
@@ -372,8 +733,21 @@ export class BookingWagonCancellationService {
         Number(booking.wagonsRequired ?? 0) - Number(row.wagonsCancelled),
       );
       const isFull = wagonsLeft <= 0;
+      // NUMBER_OF_WAGONS bookings pin their count in bulkRequestedWagons, which
+      // bulkTonWagonsRequired honours verbatim. Left stale it re-inflates the
+      // booking to its pre-cancel count on the next allocation (and shrinks
+      // tons-per-wagon to tons / stale-count), so shrink it with the cut.
+      const requestedWagonsLeft = booking.bulkRequestedWagons
+        ? Math.max(
+            0,
+            Math.floor(Number(booking.bulkRequestedWagons) - Number(row.wagonsCancelled)),
+          )
+        : null;
       await manager.getRepository(Booking).update(booking.id, {
         wagonsRequired: Math.max(0, wagonsLeft),
+        ...(requestedWagonsLeft !== null
+          ? { bulkRequestedWagons: requestedWagonsLeft }
+          : {}),
         cargoTotalWeightVgm: Math.max(
           0,
           round3(Number(booking.cargoTotalWeightVgm) - droppedWeight),
@@ -391,7 +765,7 @@ export class BookingWagonCancellationService {
 
       await manager.getRepository(BookingWagonCancellation).update(row.id, {
         status: 'CREDIT_AVAILABLE',
-        feePaidAt: new Date(),
+        ...(opts.feeSettled ? { feePaidAt: new Date() } : {}),
         weightTons: droppedWeight,
         cancelledQuantities: quantities,
       });
@@ -405,13 +779,149 @@ export class BookingWagonCancellationService {
         booking,
         whole ? 'Booking cancelled — credit available' : 'Wagon cancellation confirmed',
         whole
-          ? `All wagons of ${booking.reference} are cancelled. Your paid freight is kept as credit — rebook any day while your contract is valid.`
-          : `${row.wagonsCancelled} wagon(s) of ${booking.reference} are cancelled. Your paid freight is kept as credit — rebook any day while your contract is valid.`,
+          ? `All wagons of ${booking.reference} are cancelled. Your paid freight is kept as credit — rebook it on any coming train day.`
+          : `${row.wagonsCancelled} wagon(s) of ${booking.reference} are cancelled. Your paid freight is kept as credit — rebook it on any coming train day.`,
       );
     }
-    this.logger.log(
-      `Wagon cancellation ${row.id}: fee paid, booking ${row.bookingId} reduced by ${row.wagonsCancelled} wagon(s).`,
+  }
+
+  /**
+   * Staff cancel of the never-loaded remainder mid-load: the operator loaded
+   * what physically rides and cuts the rest, so the booking shrinks to its
+   * loaded wagons, dispatch unblocks, and the warehouse only ever sees the
+   * final (smaller) booking. Unlike the customer flow the cut applies
+   * IMMEDIATELY — the train cannot wait for a fee payment:
+   *  - CUSTOMER fault: cancellation fee invoiced, payable after; the credit
+   *    row opens right away (feePaidAt stamps when the invoice settles).
+   *  - EDR fault: no fee at all; the credit is rebookable in full.
+   */
+  async cancelRemainingAtLoading(
+    bookingId: string,
+    dto: CancelRemainingWagonsDto,
+    userId?: string,
+  ): Promise<BookingWagonCancellation> {
+    const booking = await this.bookingsRepository.findById(bookingId);
+    if (!booking) throw new NotFoundException(`Booking ${bookingId} not found.`);
+    if (booking.paymentStatus !== 'PAID' || booking.status !== 'PAID') {
+      throw new BadRequestException(
+        'Only a paid booking still loading can cancel its remaining wagons.',
+      );
+    }
+    if (booking.loadedAt) {
+      throw new BadRequestException(
+        'This booking is already fully loaded — there is nothing left to cancel.',
+      );
+    }
+    if (!booking.contractId) {
+      throw new BadRequestException(
+        'Wagon cancellation needs a contract booking (the credit is rebooked under the contract).',
+      );
+    }
+    const open = await this.repo.findOpenForBooking(bookingId);
+    if (open) {
+      throw new ConflictException(
+        'This booking already has a cancellation awaiting its fee. Pay or withdraw it first.',
+      );
+    }
+
+    const allocations = await this.dataSource
+      .getRepository(WagonBookingAllocation)
+      .createQueryBuilder('alloc')
+      .innerJoin(TrainSetWagon, 'slot', 'slot.id = alloc.train_set_wagon_id')
+      .innerJoin(
+        TrainSchedule,
+        'schedule',
+        'schedule.train_set_id = slot.train_set_id AND schedule.id = :scheduleId',
+        { scheduleId: dto.scheduleId },
+      )
+      .where('alloc.booking_id = :bookingId', { bookingId })
+      .getMany();
+    const remaining = allocations.filter(
+      (a) => a.status !== 'LOADED' && a.status !== 'DEPARTED',
     );
+    // A booking whose cargo never showed up at all (0 loaded) is cancelled the
+    // same way — the gate that holds the train does not care whether loading
+    // started, only that nothing is left unresolved.
+    if (!allocations.length) {
+      throw new BadRequestException(
+        'This booking has no wagons on this schedule — use the normal wagon cancellation flow.',
+      );
+    }
+    if (!remaining.length) {
+      throw new BadRequestException(
+        'Every wagon of this booking is loaded — there is nothing to cancel.',
+      );
+    }
+
+    const cut = await this.resolveRequestedCut(booking, {
+      wagonAllocationIds: remaining.map((r) => r.id),
+    } as RequestWagonCancellationDto);
+    if (booking.consolidationPartnerId) this.assertCutSparesSharedWagon(cut);
+
+    const edrFault = !!dto.edrFault;
+    const fee = edrFault ? null : await this.priceFee(booking, cut);
+    const creditAmount = this.creditFor(booking, cut.wagons);
+
+    const row = await this.repo.create({
+      bookingId,
+      wagonsCancelled: cut.wagons,
+      weightTons: cut.weightTons,
+      cancelledQuantities: cut.quantities,
+      creditAmount,
+      feeRateId: fee?.rates[0]?.id ?? null,
+      feeAmount: fee?.amount ?? 0,
+      feeCurrency: fee?.currency ?? booking.paymentCurrency ?? 'ETB',
+      status: 'FEE_PENDING',
+      reason: dto.reason,
+      fault: edrFault ? 'EDR' : 'CUSTOMER',
+      requestedByUserId: userId ?? null,
+    });
+
+    let current = row;
+    if (fee && fee.amount > 0) {
+      const invoice = await this.billing.generateInvoice({
+        source: Freight.InvoiceSource.Booking,
+        sourceId: bookingId,
+        type: WAGON_CANCEL_FEE_INVOICE_TYPE,
+        companyId: booking.companyId,
+        companyProfileId: booking.companyProfileId,
+        currency: fee.currency,
+        lines: [
+          {
+            chargeType: 'CANCELLATION_FEE',
+            description: `Wagon cancellation fee — ${cut.wagons} wagon(s) of booking ${booking.reference} cancelled at loading`,
+            quantity: cut.wagons,
+            unitRate: fee.perWagon,
+            amount: fee.amount,
+            currency: fee.currency,
+            metadata: { wagonCancellationId: row.id },
+          },
+        ],
+        totalAmount: fee.amount,
+        status: Freight.InvoiceStatus.Issued,
+      });
+      current = (await this.repo.update(row.id, { feeInvoiceId: invoice.id })) ?? row;
+    }
+
+    // The cut applies NOW — booking shrinks, allocations release, credit opens.
+    // EDR fault (or a zero fee) settles the fee side immediately; a customer-
+    // fault fee stays owed and stamps feePaidAt via onFeePaid when it settles.
+    await this.applyCut(current, false, { feeSettled: edrFault || !fee || fee.amount <= 0 });
+
+    // The booking now holds only loaded wagons — let the journey complete the
+    // load (PAID → IN_TRANSIT, warehouse inventory, milestones).
+    this.events.emit('booking.wagonsCancelledAtLoading', {
+      bookingId,
+      scheduleId: dto.scheduleId,
+      userId: userId ?? null,
+    });
+
+    this.notifyStaff(
+      booking,
+      'Wagons cancelled at loading',
+      `${booking.reference}: ${cut.wagons} unloaded wagon(s) cancelled (${edrFault ? 'EDR fault — no fee' : `customer fault — fee invoiced`}). Reason: ${dto.reason}`,
+    );
+    return this.mustFind(row.id);
   }
 
   /**
@@ -454,24 +964,41 @@ export class BookingWagonCancellationService {
         `This credit cannot be rebooked (status is ${row.status}).`,
       );
     }
+    // A consolidation-lapse row on an UNPAID booking carries no credit — the
+    // customer never paid freight, so there is nothing to redeem. Book fresh.
+    if (Number(row.creditAmount) <= 0) {
+      throw new BadRequestException(
+        'This cancellation has no rebooking credit — the booking was never paid. Create a new booking instead.',
+      );
+    }
     const source = await this.bookingsRepository.findById(row.bookingId);
     if (!source) throw new NotFoundException(`Booking ${row.bookingId} not found.`);
     if (!source.contractId) {
       throw new BadRequestException('The original booking has no contract to rebook under.');
     }
-    // Friendly pre-check; createUnderContract re-asserts inside its own guards.
-    if (
-      source.contractValidUntil &&
-      new Date(source.contractValidUntil).getTime() < Date.now()
-    ) {
-      throw new BadRequestException(
-        'Contract validity has expired — ask EDR staff to extend the contract before rebooking.',
-      );
-    }
-
-    const createDto = this.buildRebookDto(row, dto.scheduledDate);
+    const createDto = this.buildRebookDto(row, dto.scheduledDate, dto.containers);
     // Same currency as the source booking — the credit is in it.
     createDto.paymentCurrency = source.paymentCurrency ?? undefined;
+
+    // An odd-20ft credit shares a wagon again on rebook. GL picks who — never
+    // the auto-matcher (it could claim a partner behind GL's back), so the
+    // create below runs with auto-consolidation off and the chosen partner is
+    // linked once the booking exists and is PAID.
+    const oddFt20 = this.creditFt20(row) % 2 === 1;
+    let partner: Booking | null = null;
+    if (oddFt20) {
+      createDto.skipAutoConsolidation = true;
+      if (!dto.partnerBookingId) {
+        throw new BadRequestException(
+          'This credit carries an odd 20ft container — pick a consolidation partner booking to share its wagon (see the rebook-partners list).',
+        );
+      }
+      partner = await this.loadRebookPartner(
+        source,
+        dto.partnerBookingId,
+        dto.scheduledDate,
+      );
+    }
     const created = await this.contractBooking.createUnderContract(
       source.contractId,
       createDto,
@@ -479,6 +1006,9 @@ export class BookingWagonCancellationService {
       // System actor: carries the create-booking key so the GL gate passes on
       // Path B (customs-clearance) contracts; harmless on Path A.
       { permissions: [{ key: FREIGHT_PERMS.contracts.createBooking }] },
+      // The freight was paid while the contract was live — the credit stays
+      // redeemable even after the contract's validity lapses.
+      { allowExpiredContract: true },
     );
     const newBookingId = created.booking.id;
 
@@ -501,12 +1031,19 @@ export class BookingWagonCancellationService {
         `First-mile accept failed for rebooked ${newBookingId}: ${err instanceof Error ? err.message : String(err)}`,
       );
     }
-    try {
-      await this.bookingBatch.ensurePaidBookingAllocated(newBookingId);
-    } catch (err) {
-      this.logger.error(
-        `Allocation failed for rebooked ${newBookingId}: ${err instanceof Error ? err.message : String(err)}`,
-      );
+    if (partner) {
+      // Consolidated rebook: never allocate the half-wagon booking alone. It
+      // rides PAID and the batch engine settles the pair atomically once the
+      // partner's own invoice is paid.
+      await this.pairRebookedBooking(newBookingId, partner);
+    } else {
+      try {
+        await this.bookingBatch.ensurePaidBookingAllocated(newBookingId);
+      } catch (err) {
+        this.logger.error(
+          `Allocation failed for rebooked ${newBookingId}: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
     }
 
     const updated = (await this.repo.update(row.id, {
@@ -524,6 +1061,142 @@ export class BookingWagonCancellationService {
     return { cancellation: updated, bookingId: newBookingId };
   }
 
+  /** Total 20ft units the credit carries (odd ⇒ the rebook shares a wagon again). */
+  private creditFt20(row: BookingWagonCancellation): number {
+    return Object.entries(row.cancelledQuantities?.bySize ?? {})
+      .filter(([size]) => sizeFtOf(size) === 20)
+      .reduce((sum, [, qty]) => sum + Number(qty || 0), 0);
+  }
+
+  /**
+   * Partner candidates for rebooking an odd-20ft credit — what the GL rebook
+   * form lists. Empty when the credit is even (no shared wagon) or spent.
+   */
+  async rebookPartnerCandidates(
+    cancellationId: string,
+    scheduledDate: string,
+  ): Promise<
+    Array<{
+      id: string;
+      reference: string;
+      companyName: string | null;
+      status: string;
+      scheduledDate: string | null;
+      ft20Quantity: number;
+    }>
+  > {
+    const row = await this.mustFind(cancellationId);
+    if (row.status !== 'CREDIT_AVAILABLE') return [];
+    if (this.creditFt20(row) % 2 === 0) return [];
+    const source = await this.bookingsRepository.findById(row.bookingId);
+    if (!source) return [];
+    const rows = await this.bookingsRepository.findRebookConsolidationCandidates(
+      source,
+      new Date(scheduledDate),
+    );
+    return rows.map((b) => ({
+      id: b.id,
+      reference: b.reference,
+      companyName: b.company?.name ?? null,
+      status: b.status,
+      scheduledDate: b.scheduledDate ? b.scheduledDate.toISOString() : null,
+      ft20Quantity: (b.bookingContainers ?? [])
+        .filter((line) => Number(line.containerType?.sizeFt) === 20)
+        .reduce((sum, line) => sum + Number(line.quantity || 0), 0),
+    }));
+  }
+
+  /** The GL-picked partner, validated to actually fit the rebooked shared wagon. */
+  private async loadRebookPartner(
+    source: Booking,
+    partnerId: string,
+    scheduledDate: string,
+  ): Promise<Booking> {
+    const partner = await this.bookingsRepository.findByIdWithFiles(partnerId);
+    if (!partner) {
+      throw new NotFoundException(`Partner booking ${partnerId} not found.`);
+    }
+    if (partner.consolidationPartnerId) {
+      throw new ConflictException(
+        `Booking ${partner.reference} already shares a wagon with another booking.`,
+      );
+    }
+    if (!['SUBMITTED', 'PENDING_CONSOLIDATION'].includes(partner.status)) {
+      throw new BadRequestException(
+        `Booking ${partner.reference} cannot be consolidated (status ${partner.status}).`,
+      );
+    }
+    if (
+      partner.originYardId !== source.originYardId ||
+      partner.destinationYardId !== source.destinationYardId ||
+      partner.tradeDirection !== source.tradeDirection
+    ) {
+      throw new BadRequestException(
+        `Booking ${partner.reference} rides a different route/direction — it cannot share a wagon with this rebooking.`,
+      );
+    }
+    const eatDay = (d: Date | string) =>
+      new Date(d).toLocaleDateString('en-CA', { timeZone: 'Africa/Addis_Ababa' });
+    if (!partner.scheduledDate || eatDay(partner.scheduledDate) !== eatDay(scheduledDate)) {
+      throw new BadRequestException(
+        `Booking ${partner.reference} is not booked for ${eatDay(scheduledDate)} — a shared wagon must board one train.`,
+      );
+    }
+    const ft20 = (partner.bookingContainers ?? [])
+      .filter((line) => Number(line.containerType?.sizeFt) === 20)
+      .reduce((sum, line) => sum + Number(line.quantity || 0), 0);
+    if (ft20 % 2 !== 1) {
+      throw new BadRequestException(
+        `Booking ${partner.reference} has no odd 20ft container — nothing to consolidate.`,
+      );
+    }
+    return partner;
+  }
+
+  /**
+   * Link the rebooked (already PAID) booking with the GL-picked partner. A
+   * parked partner is resumed the way pairConsolidation would resume it —
+   * but only the partner: the rebooked side's PAID status must survive, so
+   * the link is written directly. The paired event then runs the partner's
+   * deferred contract finalize (invoice → pay window); the shared wagon
+   * boards once that invoice is paid.
+   */
+  private async pairRebookedBooking(
+    newBookingId: string,
+    partner: Booking,
+  ): Promise<void> {
+    // ponytail: validate-then-link without a row lock — a concurrent claim in
+    // this window loses silently; move to pairConsolidationIfUnpaired-style
+    // locking if it ever bites.
+    const fresh = await this.dataSource.getRepository(Booking).findOne({
+      where: { id: partner.id },
+      select: { id: true, consolidationPartnerId: true, status: true },
+    });
+    if (!fresh || fresh.consolidationPartnerId) {
+      throw new ConflictException(
+        `Booking ${partner.reference} was claimed by another consolidation while rebooking — pick another partner.`,
+      );
+    }
+    if (fresh.status === 'PENDING_CONSOLIDATION') {
+      await this.dataSource.getRepository(Booking).update(partner.id, {
+        status: partner.consolidationResumeStatus ?? 'SUBMITTED',
+        consolidationResumeStatus: null,
+      });
+    }
+    await this.bookingsRepository.linkConsolidationPartners(
+      newBookingId,
+      partner.id,
+    );
+    this.events.emit('booking.consolidation.paired', {
+      bookingIds: [partner.id],
+    });
+    this.notifyCustomer(
+      partner,
+      'Consolidation partner found',
+      `${partner.reference} now shares a wagon with a rebooked shipment. Pay your booking to board — the shared wagon ships once both halves are paid.`,
+    );
+  }
+
   // ── History ────────────────────────────────────────────────────────────────
 
   list(filter: WagonCancellationListFilter) {
@@ -1162,11 +1835,25 @@ export class BookingWagonCancellationService {
   private buildRebookDto(
     row: BookingWagonCancellation,
     scheduledDate: string,
+    overrides?: RebookContainerLineDto[],
   ): CreateBookingUnderContractDto {
     const dto: CreateBookingUnderContractDto = { scheduledDate };
     const q = row.cancelledQuantities;
 
     if (q.bySize && Object.keys(q.bySize).length) {
+      // Unit overrides may rename containers, change seals and VGM — but the
+      // cancelled sizes and quantities are the contract of the credit: a size
+      // not on the credit, or a wrong unit count, is rejected.
+      const overrideBySize = new Map(
+        (overrides ?? []).map((o) => [o.containerSize, o.units]),
+      );
+      for (const size of overrideBySize.keys()) {
+        if (!(size in q.bySize)) {
+          throw new BadRequestException(
+            `The credit has no ${size} containers — sizes and quantities must match the cancelled booking.`,
+          );
+        }
+      }
       const units = q.units ?? [];
       dto.containers = Object.entries(q.bySize).map(([size, quantity]) => {
         const sized = units.filter((u) => u.containerSize === size);
@@ -1175,13 +1862,23 @@ export class BookingWagonCancellationService {
             `Credit is missing unit snapshots for size ${size} (${sized.length}/${quantity}) — contact EDR support.`,
           );
         }
+        const replacement = overrideBySize.get(size);
+        if (replacement && replacement.length !== quantity) {
+          throw new BadRequestException(
+            `The credit covers exactly ${quantity} × ${size} — you entered ${replacement.length}. Quantities cannot change on a rebook.`,
+          );
+        }
         return {
           containerSize: size,
           quantity,
-          units: sized.map((u) => ({
-            containerNumber: u.containerNumber,
-            sealNumber: u.sealNumber ?? undefined,
-            vgmTons: u.vgmTons,
+          // Hazardous/reefer flags always ride from the snapshot (the cargo is
+          // the same cargo); number/seal/VGM come from the override when given.
+          units: sized.map((u, i) => ({
+            containerNumber: replacement?.[i]?.containerNumber ?? u.containerNumber,
+            sealNumber: replacement
+              ? (replacement[i]?.sealNumber ?? undefined)
+              : (u.sealNumber ?? undefined),
+            vgmTons: replacement?.[i]?.vgmTons ?? u.vgmTons,
             isHazardous: u.isHazardous,
             isReefer: u.isReefer,
           })),
@@ -1193,6 +1890,14 @@ export class BookingWagonCancellationService {
     }
 
     dto.bulkLines = [{ cargoWeightTons: Number(q.bulkTons ?? row.weightTons) }];
+    // NUMBER_OF_WAGONS cargo is booked by wagon count, not by tons: the create
+    // path rejects the rebook outright without it. The count is not in the
+    // quantities snapshot (which only carries tons) — it is the cancellation's
+    // own wagonsCancelled, so every existing credit rebooks without a backfill.
+    // Rounded UP: a fractional cut still needs a whole wagon to ride on, and
+    // flooring 0.5 would send 0 into a check that demands >= 1.
+    const cancelledWagons = Math.ceil(Number(row.wagonsCancelled ?? 0));
+    if (cancelledWagons >= 1) dto.requestedWagons = cancelledWagons;
     return dto;
   }
 

apps/edr-freight-api/src/modules/bookings/bookings.module.ts

@@ -38,7 +38,13 @@ import { BookingsService } from './bookings.service';
 import { BookingCargoModifier } from './entities/booking-cargo-modifier.entity';
 import { BookingDocumentReview } from './entities/booking-document-review.entity';
 import { BookingClearanceCharge } from './entities/booking-clearance-charge.entity';
+import { AdditionalCharge } from './entities/additional-charge.entity';
+import { AdditionalChargeRepository } from './additional-charge.repository';
+import { AdditionalChargeService } from './additional-charge.service';
 import { BookingClearanceChargeService } from './booking-clearance-charge.service';
+import { BookingPayablesService } from './booking-payables.service';
+import { BookingClearanceEvent } from './entities/booking-clearance-event.entity';
+import { ClearanceEventService } from './clearance-event.service';
 import { BookingContainer } from './entities/booking-container.entity';
 import { BookingRateSnapshot } from './entities/booking-rate-snapshot.entity';
 import { BookingContractSignature } from './entities/booking-contract-signature.entity';
@@ -79,6 +85,8 @@ import { VehiclesModule } from "../vehicles/vehicles.module";
       CustomerTruckContainer,
       ConsolidationApproval,
       BookingClearanceCharge,
+      BookingClearanceEvent,
+      AdditionalCharge,
     ]),
     BillingModule,
     DocumentsModule,
@@ -115,6 +123,10 @@ import { VehiclesModule } from "../vehicles/vehicles.module";
     BookingContractService,
     BookingInvoiceService,
     BookingClearanceChargeService,
+    BookingPayablesService,
+    ClearanceEventService,
+    AdditionalChargeRepository,
+    AdditionalChargeService,
     ContractTemplateResolver,
     ContractViewModelBuilder,
     ContractPricingScheduleBuilder,
@@ -130,6 +142,7 @@ import { VehiclesModule } from "../vehicles/vehicles.module";
   exports: [
     BookingsService,
     BookingsRepository,
+    ClearanceEventService,
     BookingPricingService,
     ContainerValidationService,
     BookingInvoiceService,

apps/edr-freight-api/src/modules/bookings/bookings.repository.ts

@@ -21,6 +21,13 @@ import { ShippingLineCompany } from '../shipping-lines/entities/shipping-line-co
 import { ContractRateSnapshot } from '../contracts/entities/contract-rate-snapshot.entity';
 import { ContractRoute } from '../contracts/entities/contract-route.entity';
 import { applyDirectionScope } from '../user-trade-access/trade-scope.util';
+import {
+  CARGO_TYPE_SUBTREE_SQL,
+  bookingContainerCountSql,
+  bookingContentMatchSql,
+  bookingHasContainerTypeSql,
+  bookingRequestedContainerCountSql,
+} from './booking-content.sql';
 import { BookingCargoModifier } from './entities/booking-cargo-modifier.entity';
 import {
   BookingDocumentReview,
@@ -65,7 +72,17 @@ export interface BookingListFilterOptions {
   contractId?: string;
   contractType?: string;
   serviceTypeId?: string;
+  /** Cargo type OR cargo group — a group matches every commodity beneath it. */
   cargoTypeId?: string;
+  /** Contains-search over content: description, commodity name, container types. */
+  cargoText?: string;
+  /** Bookings carrying this container type; also scopes the container count. */
+  containerTypeId?: string;
+  containersMin?: number;
+  containersMax?: number;
+  /** Bounds on containers declared on the shipment request behind the booking. */
+  requestedContainersMin?: number;
+  requestedContainersMax?: number;
   freightType?: string;
   bookingType?: string;
   tradeDirection?: string;
@@ -79,8 +96,10 @@ export interface BookingListFilterOptions {
   createdTo?: string;
   scheduledFrom?: string;
   scheduledTo?: string;
-  originYardId?: string;
-  destinationYardId?: string;
+  /** Any of these origin yards (OR). ANDed with `destinationYardId`. */
+  originYardId?: string[];
+  /** Any of these destination yards (OR). ANDed with `originYardId`. */
+  destinationYardId?: string[];
   isGovernment?: 'true' | 'false';
   /** Shipping-line bookings vs ordinary customer bookings (exactly one owner is set). */
   customerKind?: 'SHIPPING_LINE' | 'CUSTOMER';
@@ -375,6 +394,58 @@ export class BookingsRepository extends BaseRepository<Booking> {
     });
   }
 
+  /**
+   * Candidate partners for rebooking an odd-20ft cancellation credit: unpaired
+   * odd-20ft bookings on the same route/direction riding the requested day —
+   * SUBMITTED (committed direct booking) or parked PENDING_CONSOLIDATION.
+   * Unlike {@link findManualConsolidationCandidates} this is not customs-only:
+   * GL picks who shares the rebooked wagon whatever the contract kind.
+   */
+  async findRebookConsolidationCandidates(
+    booking: Booking,
+    scheduledDate: Date,
+    limit = 50,
+  ): Promise<Booking[]> {
+    const rows = await this.repository
+      .createQueryBuilder('b')
+      .leftJoinAndSelect('b.bookingContainers', 'bc')
+      .leftJoinAndSelect('bc.containerType', 'ct')
+      .leftJoinAndSelect('b.company', 'company')
+      .where('b.id != :bookingId', { bookingId: booking.id })
+      .andWhere('b.consolidationPartnerId IS NULL')
+      .andWhere('b.originYardId = :originYardId', {
+        originYardId: booking.originYardId,
+      })
+      .andWhere('b.destinationYardId = :destinationYardId', {
+        destinationYardId: booking.destinationYardId,
+      })
+      .andWhere('b.tradeDirection = :tradeDirection', {
+        tradeDirection: booking.tradeDirection,
+      })
+      .andWhere('b.status IN (:...statuses)', {
+        statuses: ['SUBMITTED', 'PENDING_CONSOLIDATION'],
+      })
+      // Same EAT booking day as the rebook — the pair shares one physical
+      // wagon, so it must board one train.
+      .andWhere(
+        `DATE(b.scheduled_date AT TIME ZONE 'Africa/Addis_Ababa') = DATE(:bookingDate AT TIME ZONE 'Africa/Addis_Ababa')`,
+        { bookingDate: scheduledDate },
+      )
+      .orderBy('b.createdAt', 'ASC')
+      .take(limit)
+      .getMany();
+
+    // Odd-20ft test in memory (two 20ft per wagon: odd + odd = whole wagons).
+    return rows.filter((row) => {
+      const lines = row.bookingContainers ?? [];
+      if (lines.length === 0) return false;
+      const ft20 = lines
+        .filter((line) => Number(line.containerType?.sizeFt) === 20)
+        .reduce((sum, line) => sum + Number(line.quantity || 0), 0);
+      return ft20 % 2 === 1;
+    });
+  }
+
   /**
    * Find another booking whose container quantity complements this one to fill whole wagon(s)
    * (same route, same container type, partial wagon on both sides). Only 20ft lines ever
@@ -594,6 +665,21 @@ export class BookingsRepository extends BaseRepository<Booking> {
     } as never);
   }
 
+  /**
+   * Terminal un-pair: break the consolidation link only, touching neither
+   * status. Used when one half of a pair is cancelled/expired — the caller
+   * decides each side's fate ({@link unpairConsolidation} instead re-parks
+   * BOTH sides to PENDING_CONSOLIDATION, which is wrong for a dying booking).
+   */
+  async clearConsolidationPair(bookingId: string, partnerId: string): Promise<void> {
+    await this.repository.update(bookingId, {
+      consolidationPartnerId: null,
+    } as never);
+    await this.repository.update(partnerId, {
+      consolidationPartnerId: null,
+    } as never);
+  }
+
   /** Un-pair a consolidation. */
   async unpairConsolidation(bookingId: string, partnerId: string): Promise<void> {
     await this.repository.update(bookingId, {
@@ -620,6 +706,29 @@ export class BookingsRepository extends BaseRepository<Booking> {
     });
   }
 
+  /**
+   * Bookings (of those given) that have at least one customer document still
+   * waiting on GL — PENDING or QUERIED. Includes ad-hoc `custom_*` documents,
+   * which no milestone tracks, so a file added after clearance was finalized
+   * still surfaces as needing review. One query for a whole queue page.
+   */
+  async findBookingsWithUnreviewedDocuments(
+    bookingIds: string[],
+  ): Promise<Set<string>> {
+    if (bookingIds.length === 0) return new Set();
+    const rows = (await this.dataSource
+      .getRepository(BookingDocumentReview)
+      .createQueryBuilder('r')
+      .select('DISTINCT r.booking_id', 'bookingId')
+      .where('r.booking_id IN (:...bookingIds)', { bookingIds })
+      .andWhere('r.status IN (:...statuses)', {
+        statuses: ['PENDING', 'QUERIED'],
+      })
+      .andWhere('r.deleted_at IS NULL')
+      .getRawMany()) as Array<{ bookingId: string }>;
+    return new Set(rows.map((r) => r.bookingId));
+  }
+
   findDocumentReview(
     bookingId: string,
     settingCode: string,
@@ -1084,11 +1193,55 @@ export class BookingsRepository extends BaseRepository<Booking> {
         serviceTypeId: options.serviceTypeId,
       });
     }
+    // A group is selectable in the filter, not just a leaf commodity, so this
+    // matches the whole subtree — picking "Bulk" must return every commodity
+    // under it, the same drill-down the booking wizard offers, read back.
     if (options.cargoTypeId) {
-      qb.andWhere('booking.cargo_type_id = :cargoTypeId', {
+      qb.andWhere(`booking.cargo_type_id IN ${CARGO_TYPE_SUBTREE_SQL}`, {
         cargoTypeId: options.cargoTypeId,
       });
     }
+    if (options.cargoText) {
+      qb.andWhere(bookingContentMatchSql('booking'), {
+        cargoText: `%${options.cargoText}%`,
+      });
+    }
+    if (options.containerTypeId) {
+      qb.andWhere(bookingHasContainerTypeSql('booking'), {
+        containerTypeId: options.containerTypeId,
+      });
+    }
+    // One count filter, two questions: with a container type picked it counts
+    // that type, without one it counts every box on the booking.
+    if (options.containersMin != null || options.containersMax != null) {
+      const count = bookingContainerCountSql(
+        'booking',
+        Boolean(options.containerTypeId),
+      );
+      if (options.containersMin != null) {
+        qb.andWhere(`${count} >= :containersMin`, {
+          containersMin: options.containersMin,
+        });
+      }
+      if (options.containersMax != null) {
+        qb.andWhere(`${count} <= :containersMax`, {
+          containersMax: options.containersMax,
+        });
+      }
+    }
+    // Declared on the shipment request, not on the booking. Pairs with the
+    // count above: containers 0..0 AND requested >= 1 is the set awaiting
+    // completion after clearance.
+    if (options.requestedContainersMin != null) {
+      qb.andWhere(`${bookingRequestedContainerCountSql('booking')} >= :requestedContainersMin`, {
+        requestedContainersMin: options.requestedContainersMin,
+      });
+    }
+    if (options.requestedContainersMax != null) {
+      qb.andWhere(`${bookingRequestedContainerCountSql('booking')} <= :requestedContainersMax`, {
+        requestedContainersMax: options.requestedContainersMax,
+      });
+    }
     if (omit !== 'freightType' && options.freightType) {
       qb.andWhere('booking.freight_type = :freightType', {
         freightType: options.freightType,
@@ -1128,14 +1281,17 @@ export class BookingsRepository extends BaseRepository<Booking> {
         scheduledTo: options.scheduledTo,
       });
     }
-    if (options.originYardId) {
-      qb.andWhere('booking.origin_yard_id = :originYardId', {
-        originYardId: options.originYardId,
+    // Each end is its own OR-list, and the two ends AND together — so
+    // "leaving Nagad or DMP" and "leaving Nagad, arriving Gelan" are both
+    // expressible. `?.length` guards the empty array: `IN ()` is a syntax error.
+    if (options.originYardId?.length) {
+      qb.andWhere('booking.origin_yard_id IN (:...originYardIds)', {
+        originYardIds: options.originYardId,
       });
     }
-    if (options.destinationYardId) {
-      qb.andWhere('booking.destination_yard_id = :destinationYardId', {
-        destinationYardId: options.destinationYardId,
+    if (options.destinationYardId?.length) {
+      qb.andWhere('booking.destination_yard_id IN (:...destinationYardIds)', {
+        destinationYardIds: options.destinationYardId,
       });
     }
     if (options.isGovernment === 'true') {