Merge pull request #707 from Tria-plc/freight_feature/usermanagement

changes

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

@@ -1,7 +1,10 @@
 import { Injectable, NotFoundException } from '@nestjs/common';
 
 import { ContractsRepository } from '../modules/contracts/contracts.repository';
-import { Contract } from '../modules/contracts/entities/contract.entity';
+import {
+  Contract,
+  ContractDocumentSnapshot,
+} from '../modules/contracts/entities/contract.entity';
 import { ContractRoute } from '../modules/contracts/entities/contract-route.entity';
 import {
   ContractSignature,
@@ -11,7 +14,10 @@ import { ContractPricingBreakdown } from '../modules/contracts/contract-pricing.
 import { ContractTemplatesService } from '../modules/contract-templates/contract-templates.service';
 import { ContractTemplateResolver } from './contract-template.resolver';
 import { getTemplateMeta } from './contract-template.registry';
-import { ContractViewModel } from './contract-view-model.builder';
+import {
+  ContractDynamicTemplateView,
+  ContractViewModel,
+} from './contract-view-model.builder';
 
 /**
  * Signature row for the contract PDF. Mirrors the booking builder's
@@ -90,22 +96,36 @@ export class ContractDocumentViewModelBuilder {
       contract.contractTemplateKey ?? this.templateResolver.resolve(this.toResolverInput(contract));
     let template = getTemplateMeta(templateKey);
 
-    // Prefer the admin-editable DB template matching the contract's
-    // direction/freight pair; fall back to the code-defined generic layout
-    // when none is active.
-    const dynamicSource = await this.contractTemplates.findActiveForContract(
-      contract.tradeDirection,
-      contract.freightType,
-    );
-    const dynamicTemplate = dynamicSource
-      ? {
-          code: dynamicSource.code,
-          name: dynamicSource.name,
-          documentTitle: dynamicSource.documentTitle,
-          whereasClauses: dynamicSource.whereasClauses ?? [],
-          articles: dynamicSource.articles ?? [],
-        }
-      : undefined;
+    // The document articles come, in order of preference, from:
+    //  1. this contract's frozen snapshot (staff accepted / edited it) — the
+    //     shared six templates are never consulted for these contracts;
+    //  2. the admin-editable DB template matching the direction/freight pair;
+    //  3. the code-defined generic layout (handled below when none of the above).
+    const snapshot = contract.documentSnapshot as ContractDocumentSnapshot | null;
+    let dynamicTemplate: ContractDynamicTemplateView | undefined;
+    if (snapshot && (snapshot.articles?.length ?? 0) > 0) {
+      dynamicTemplate = {
+        code: snapshot.code ?? 'CONTRACT',
+        name: snapshot.name ?? template.title,
+        documentTitle: snapshot.documentTitle ?? '',
+        whereasClauses: snapshot.whereasClauses ?? [],
+        articles: snapshot.articles,
+      };
+    } else {
+      const dynamicSource = await this.contractTemplates.findActiveForContract(
+        contract.tradeDirection,
+        contract.freightType,
+      );
+      dynamicTemplate = dynamicSource
+        ? {
+            code: dynamicSource.code,
+            name: dynamicSource.name,
+            documentTitle: dynamicSource.documentTitle,
+            whereasClauses: dynamicSource.whereasClauses ?? [],
+            articles: dynamicSource.articles ?? [],
+          }
+        : undefined;
+    }
     if (dynamicTemplate) {
       template = {
         ...template,

apps/edr-freight-api/src/migrations/2210000000000-ScheduleScopedWagonPins.ts

@@ -0,0 +1,48 @@
+import { MigrationInterface, QueryRunner } from "typeorm";
+
+/**
+ * Schedule-scoped wagon pins.
+ *
+ * Wagon occupancy now lives ONLY on each schedule's own train_set_wagons slots
+ * (the per-schedule snapshot): pinning/releasing a wagon no longer mutates the
+ * Wagon entity, so the same physical wagon can serve many schedules (the July 17
+ * and July 20 runs of one train both use its 50 wagons). The Wagon columns
+ * `current_train_schedule_id` / `train_set_wagon_id` keep only their physical
+ * meaning — "out on this DISPATCHED train right now" (stamped at dispatch,
+ * cleared at arrive/unload/cancel).
+ *
+ * This migration erases the legacy pin-time stamps left by the old flow: any
+ * wagon pointing at a schedule that is not currently DISPATCHED (or that no
+ * longer exists) gets its pointers cleared, and — when the old flow had parked
+ * it in ASSIGNED — its status returns to the pool semantics (ASSIGNED only
+ * while coupled to a built train, otherwise AVAILABLE).
+ */
+export class ScheduleScopedWagonPins2210000000000 implements MigrationInterface {
+  name = "ScheduleScopedWagonPins2210000000000";
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      UPDATE freight.wagons w
+         SET current_train_schedule_id = NULL,
+             train_set_wagon_id = NULL,
+             status = CASE
+               WHEN w.status = 'ASSIGNED' AND w.train_id IS NULL THEN 'AVAILABLE'
+               ELSE w.status
+             END
+       WHERE w.deleted_at IS NULL
+         AND w.current_train_schedule_id IS NOT NULL
+         AND NOT EXISTS (
+           SELECT 1
+             FROM freight.train_schedules ts
+            WHERE ts.id = w.current_train_schedule_id
+              AND ts.deleted_at IS NULL
+              AND ts.status = 'DISPATCHED'
+         );
+    `);
+  }
+
+  public async down(_queryRunner: QueryRunner): Promise<void> {
+    // Pin-time stamps cannot be reconstructed (the data was the bug); the
+    // slots on train_set_wagons still hold every live pin, so down is a no-op.
+  }
+}

apps/edr-freight-api/src/migrations/2220000000000-AddContractDocumentSnapshot.ts

@@ -0,0 +1,27 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Adds freight.contracts.document_snapshot — a per-contract frozen copy of the
+ * contract-document template (articles + WHEREAS recitals) captured at staff
+ * accept. Staff can edit these articles for a single contract before generating
+ * its PDF; the edit never touches the shared six freight.contract_templates
+ * rows. Null on existing contracts → the PDF keeps rendering from the live
+ * template, so this is backward compatible.
+ */
+export class AddContractDocumentSnapshot2220000000000
+  implements MigrationInterface
+{
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.contracts
+        ADD COLUMN IF NOT EXISTS document_snapshot JSONB;
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.contracts
+        DROP COLUMN IF EXISTS document_snapshot;
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/2230000000000-RenameWagonStatusRetiredToDetained.ts

@@ -0,0 +1,24 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Wagon status RETIRED is renamed DETAINED (wagons pulled from circulation).
+ * The column is a plain varchar, so this is a data-only rename. Vehicles keep
+ * their own RETIRED status — only freight.wagons rows are touched.
+ */
+export class RenameWagonStatusRetiredToDetained2230000000000
+  implements MigrationInterface
+{
+  name = 'RenameWagonStatusRetiredToDetained2230000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      UPDATE freight.wagons SET status = 'DETAINED' WHERE status = 'RETIRED'
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      UPDATE freight.wagons SET status = 'RETIRED' WHERE status = 'DETAINED'
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/2240000000000-AddTransferRequestReason.ts

@@ -0,0 +1,24 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Every new wagon-transfer request must state WHY the wagons are needed; the
+ * reason is shown on the OCC request queue. Nullable in the DB — legacy rows
+ * predate the requirement; the DTO enforces it for new requests.
+ */
+export class AddTransferRequestReason2240000000000 implements MigrationInterface {
+  name = 'AddTransferRequestReason2240000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.wagon_transfer_requests
+        ADD COLUMN IF NOT EXISTS reason text NULL
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      ALTER TABLE freight.wagon_transfer_requests
+        DROP COLUMN IF EXISTS reason
+    `);
+  }
+}

apps/edr-freight-api/src/migrations/2250000000000-CreatePriorityRuleChangeRequests.ts

@@ -0,0 +1,42 @@
+import { MigrationInterface, QueryRunner } from 'typeorm';
+
+/**
+ * Approval workflow for priority-rule changes: every create/update/delete of a
+ * priority config is filed here as a PENDING change request; an approver
+ * applies or rejects it. `payload` carries the proposed field values (null for
+ * DELETE), `priority_config_id` the target row (null for CREATE).
+ */
+export class CreatePriorityRuleChangeRequests2250000000000
+  implements MigrationInterface
+{
+  name = 'CreatePriorityRuleChangeRequests2250000000000';
+
+  public async up(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(`
+      CREATE TABLE IF NOT EXISTS freight.priority_rule_change_requests (
+        id uuid PRIMARY KEY DEFAULT gen_random_uuid(),
+        action varchar(10) NOT NULL,
+        priority_config_id uuid NULL REFERENCES freight.priority_configs (id),
+        payload jsonb NULL,
+        status varchar(10) NOT NULL DEFAULT 'PENDING',
+        requested_by_user_id uuid NULL,
+        decided_by_user_id uuid NULL,
+        decided_at timestamptz NULL,
+        decision_note text NULL,
+        created_at timestamptz NOT NULL DEFAULT now(),
+        updated_at timestamptz NOT NULL DEFAULT now(),
+        deleted_at timestamptz NULL
+      )
+    `);
+    await queryRunner.query(`
+      CREATE INDEX IF NOT EXISTS idx_prcr_status
+        ON freight.priority_rule_change_requests (status)
+    `);
+  }
+
+  public async down(queryRunner: QueryRunner): Promise<void> {
+    await queryRunner.query(
+      `DROP TABLE IF EXISTS freight.priority_rule_change_requests`,
+    );
+  }
+}

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

@@ -1003,18 +1003,26 @@ export class BookingTransitionService {
     }
 
     // The binding shipment day must have at least one OPEN departure on the
-    // route — only schedule-backed days are selectable. The batch engine
-    // assigns the specific train within that (route, day) pool later.
-    const hasDeparture = await this.bookingsService.hasOpenDepartureOnDay(
-      booking.originYardId,
-      booking.destinationYardId,
-      eatDay(date),
-    );
+    // route — only schedule-backed days are selectable — AND some departure
+    // that day must be able to physically carry this cargo type (wagon-TYPE
+    // gate; quantity never blocks — oversized bookings get a partial split
+    // offer). The batch engine assigns the specific train within that
+    // (route, day) pool later.
+    const { hasDeparture, hasCompatible } =
+      await this.bookingsService.checkDayCompatibilityForBooking(
+        booking,
+        eatDay(date),
+      );
     if (!hasDeparture) {
       throw new BadRequestException(
         "No departures available on the selected day for this route",
       );
     }
+    if (!hasCompatible) {
+      throw new BadRequestException(
+        "No wagon on the selected day can carry this cargo type — please choose another day",
+      );
+    }
 
     await this.bookingsRepository.update(bookingId, {
       status: "OPERATION_REQUEST_PENDING",

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

@@ -348,6 +348,28 @@ export class BookingsController {
     return this.transitionService.enrichBookingResponse(booking);
   }
 
+  @Get(':id/available-days')
+  @ApiOperation({
+    summary:
+      'Days bookable for THIS booking (cargo-aware wagon-TYPE gate; days only, no capacity counts)',
+  })
+  async availableDays(
+    @Param('id', ParseUUIDPipe) id: string,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    const booking = await this.bookingsService.findById(id);
+    if (
+      !hasFreightPermission(user, FREIGHT_PERMS.bookings.view) &&
+      !hasFreightPermission(user, FREIGHT_PERMS.bookings.clearanceView)
+    ) {
+      await this.bookingsService.assertCustomerCanAccessBooking(
+        user?.id,
+        booking,
+      );
+    }
+    return this.bookingsService.availableDaysForBooking(id);
+  }
+
   @Get(':id/mile-summary')
   @ApiOperation({
     summary: 'First/last-mile operational summary for a booking (customer-safe)',

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

@@ -653,22 +653,37 @@ export class BookingsService {
     } else if (dto.scheduledDate) {
       // A real (binding) scheduledDate was supplied (e.g. staff pinning a day
       // directly). Require that the route has at least one OPEN departure on
-      // that EAT day. The booking wizard does NOT send scheduledDate at creation
-      // — it captures a non-binding estimatedShipmentDate instead, and the
-      // binding day is chosen later at the operation-request step. General
-      // contracts also skip this (each drawdown order validates its own day).
+      // that EAT day AND that some departure that day can physically carry the
+      // cargo (wagon-TYPE gate — quantity never blocks; oversized bookings get
+      // a partial split offer later). The booking wizard does NOT send
+      // scheduledDate at creation — it captures a non-binding
+      // estimatedShipmentDate instead, and the binding day is chosen later at
+      // the operation-request step. General contracts also skip this (each
+      // drawdown order validates its own day).
       const day = eatDay(new Date(dto.scheduledDate));
-      const hasDeparture =
-        await this.trainSchedulingService.existsOpenScheduleOnRouteDay(
+      const { hasDeparture, hasCompatible } =
+        await this.trainSchedulingService.checkDayCargoCompatibility(
           dto.originYardId,
           dto.destinationYardId,
           day,
+          {
+            freightType: dto.freightType as 'CONTAINER' | 'BULK',
+            cargoTypeId: dto.cargoTypeId,
+            containerTypeIds: (dto.containers ?? [])
+              .map((c) => c.containerTypeId)
+              .filter((id): id is string => Boolean(id)),
+          },
         );
       if (!hasDeparture) {
         throw new BadRequestException(
           'No departures available on the selected day for this route',
         );
       }
+      if (!hasCompatible) {
+        throw new BadRequestException(
+          'No wagon on the selected day can carry this cargo type — please choose another day',
+        );
+      }
     }
 
     const containers = dto.containers ?? [];
@@ -1149,6 +1164,52 @@ export class BookingsService {
     );
   }
 
+  /** Cargo identity of a booking for the wagon-TYPE compatibility gate. */
+  private cargoIdentityOf(booking: Booking): {
+    freightType: 'CONTAINER' | 'BULK';
+    cargoTypeId?: string | null;
+    containerTypeIds?: string[];
+  } {
+    return {
+      freightType: booking.freightType as 'CONTAINER' | 'BULK',
+      cargoTypeId: booking.cargoTypeId ?? null,
+      containerTypeIds: (booking.bookingContainers ?? [])
+        .map((line) => line.containerTypeId)
+        .filter((id): id is string => Boolean(id)),
+    };
+  }
+
+  /**
+   * Day gate for a specific booking: OPEN departure exists AND some departure
+   * that day can physically carry the booking's cargo/container type.
+   * Quantity never blocks — oversized bookings get a partial split offer.
+   */
+  async checkDayCompatibilityForBooking(
+    booking: Booking,
+    day: string,
+  ): Promise<{ hasDeparture: boolean; hasCompatible: boolean }> {
+    return this.trainSchedulingService.checkDayCargoCompatibility(
+      booking.originYardId,
+      booking.destinationYardId,
+      day,
+      this.cargoIdentityOf(booking),
+    );
+  }
+
+  /**
+   * Days the customer may pick for THIS booking (operation-request step):
+   * cargo-aware — only days whose departures can carry the booking's cargo
+   * type. Returns days only, no capacity counts.
+   */
+  async availableDaysForBooking(bookingId: string): Promise<{ days: string[] }> {
+    const booking = await this.findById(bookingId);
+    return this.trainSchedulingService.getAvailableDaysForCargo({
+      originYardId: booking.originYardId,
+      destinationYardId: booking.destinationYardId,
+      ...this.cargoIdentityOf(booking),
+    });
+  }
+
   /**
    * Batched version of the findById flag: marks each page item whose booking
    * has a generated-but-unsigned SELF_HAUL handover, so list rows (portal

apps/edr-freight-api/src/modules/contracts/contract-transition.service.ts

@@ -4,6 +4,7 @@ import {
   Injectable,
   Logger,
 } from '@nestjs/common';
+import { randomUUID } from 'node:crypto';
 import { Readable } from 'stream';
 import { insertWithGeneratedReference } from '@edr/api-common';
 import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
@@ -21,16 +22,35 @@ import { DropdownSettingsService } from '../dropdown-settings/dropdown-settings.
 import { FilesService } from '../files/files.service';
 import { SignaturesService } from '../signatures/signatures.service';
 import { OtpService } from '../otp/otp.service';
+import { ContractTemplatesService } from '../contract-templates/contract-templates.service';
 import { ContractPricingService } from './contract-pricing.service';
 import { ContractNotifierService } from './contract-notifier.service';
 import { ClearanceMilestoneService } from './clearance-milestone.service';
 import { ContractsRepository } from './contracts.repository';
 import { ContractsService } from './contracts.service';
 import { contractClearanceSettingCode } from './contract-clearance.util';
-import { Contract } from './entities/contract.entity';
+import {
+  Contract,
+  ContractDocumentArticle,
+  ContractDocumentSnapshot,
+  ContractDocumentSnapshotInput,
+} from './entities/contract.entity';
 import { ContractSignerRole } from './entities/contract-signature.entity';
 import { SignContractDto } from './dto/sign-contract.dto';
 
+/** The editable contract-document draft returned for the accept/edit dialog. */
+export interface ContractDocumentDraft {
+  documentTitle: string | null;
+  whereasClauses: string[];
+  articles: ContractDocumentArticle[];
+  code: string | null;
+  name: string | null;
+  /** True once the document may no longer be edited/regenerated. */
+  locked: boolean;
+  generatedAt: Date | null;
+  status: string;
+}
+
 /**
  * Dropdown-settings code holding the admin-configured contract validity options
  * (each option's `value` is a day count). The staff accept dialog reads the same
@@ -68,6 +88,7 @@ export class ContractTransitionService {
     private readonly minioService: MinioService,
     private readonly otpService: OtpService,
     private readonly notifier: ContractNotifierService,
+    private readonly contractTemplates: ContractTemplatesService,
   ) {}
 
   /** Customer submits the contract for approval → SUBMITTED; freeze unit rates. */
@@ -110,6 +131,7 @@ export class ContractTransitionService {
     contractId: string,
     actorId: string,
     validityDays: number,
+    documentSnapshot?: ContractDocumentSnapshotInput | null,
   ): Promise<Contract> {
     const contract = await this.contractsService.findById(contractId);
     assertContractStatus(contract, ['SUBMITTED']);
@@ -128,6 +150,12 @@ export class ContractTransitionService {
 
     await this.instantiateApprovalSteps(contract);
 
+    // Freeze the contract document for THIS contract only. Staff may have edited
+    // the articles in the accept dialog; otherwise the live template is captured
+    // as-is so later template edits never change an in-flight contract. The
+    // shared six templates are never written here.
+    const snapshot = await this.resolveDocumentSnapshot(contract, documentSnapshot);
+
     await this.contractsRepository.update(contractId, {
       status: 'PENDING_APPROVAL',
       approvedByStaffId: actorId,
@@ -135,12 +163,148 @@ export class ContractTransitionService {
       contractValidityDays: validityDays,
       contractValidFrom: validFrom,
       contractValidUntil: validUntil,
+      documentSnapshot: snapshot,
     } as never);
     const updated = await this.contractsService.findById(contractId);
     this.notifier.accepted(updated);
     return updated;
   }
 
+  // ── Per-contract document snapshot (US: edit articles for one contract) ─────
+
+  /**
+   * The editable document draft for the accept/edit dialog: the frozen snapshot
+   * if one exists, else the live active template resolved for this contract's
+   * direction/freight pair. `locked` flips true once the document may no longer
+   * be edited (an approver has acted, or the contract has left the pre-approval
+   * window).
+   */
+  async getContractDocumentDraft(
+    contractId: string,
+  ): Promise<ContractDocumentDraft> {
+    const contract = await this.contractsService.findById(contractId);
+    const snapshot =
+      (contract.documentSnapshot as ContractDocumentSnapshot | null) ??
+      (await this.resolveDocumentSnapshot(contract));
+    return {
+      documentTitle: snapshot?.documentTitle ?? null,
+      whereasClauses: snapshot?.whereasClauses ?? [],
+      articles: snapshot?.articles ?? [],
+      code: snapshot?.code ?? null,
+      name: snapshot?.name ?? null,
+      locked: !this.documentIsEditable(contract),
+      generatedAt: contract.contractGeneratedAt ?? null,
+      status: contract.status,
+    };
+  }
+
+  /**
+   * Replace this contract's document articles from the editor. Per-contract
+   * only — it writes the contract's own snapshot and never the shared templates.
+   * Allowed while the document is still editable (PENDING_APPROVAL, no approver
+   * has acted).
+   */
+  async updateContractDocument(
+    contractId: string,
+    input: ContractDocumentSnapshotInput,
+  ): Promise<Contract> {
+    const contract = await this.contractsService.findById(contractId);
+    assertContractStatus(contract, ['PENDING_APPROVAL']);
+    this.assertDocumentEditable(contract);
+
+    const current =
+      (contract.documentSnapshot as ContractDocumentSnapshot | null) ??
+      (await this.resolveDocumentSnapshot(contract));
+    const merged: ContractDocumentSnapshotInput = {
+      code: current?.code ?? null,
+      name: input.name ?? current?.name ?? null,
+      documentTitle: input.documentTitle ?? current?.documentTitle ?? null,
+      whereasClauses: input.whereasClauses ?? current?.whereasClauses ?? [],
+      articles: input.articles ?? current?.articles ?? [],
+    };
+    await this.contractsRepository.update(contractId, {
+      documentSnapshot: this.normalizeSnapshot(merged),
+    } as never);
+    return this.contractsService.findById(contractId);
+  }
+
+  /**
+   * Build the per-contract document snapshot. Prefer the staff's edited articles
+   * from the dialog; otherwise freeze the active template matching the
+   * contract's direction/freight. Returns null when no active template exists
+   * (the renderer then falls back to the built-in generic layout at render time).
+   */
+  private async resolveDocumentSnapshot(
+    contract: Contract,
+    provided?: ContractDocumentSnapshotInput | null,
+  ): Promise<ContractDocumentSnapshot | null> {
+    if (provided && (provided.articles?.length ?? 0) > 0) {
+      return this.normalizeSnapshot(provided);
+    }
+    const active = await this.contractTemplates.findActiveForContract(
+      contract.tradeDirection,
+      contract.freightType,
+    );
+    if (!active) return null;
+    return {
+      code: active.code,
+      name: active.name,
+      documentTitle: active.documentTitle,
+      whereasClauses: active.whereasClauses ?? [],
+      articles: this.normalizeArticles(active.articles ?? []),
+    };
+  }
+
+  private normalizeSnapshot(
+    input: ContractDocumentSnapshotInput,
+  ): ContractDocumentSnapshot {
+    return {
+      code: input.code ?? null,
+      name: input.name ?? null,
+      documentTitle: input.documentTitle ?? null,
+      whereasClauses: Array.isArray(input.whereasClauses)
+        ? input.whereasClauses
+            .map((c) => String(c))
+            .filter((c) => c.trim().length > 0)
+        : [],
+      articles: this.normalizeArticles(input.articles ?? []),
+    };
+  }
+
+  /** Re-key ids and renumber order sequentially, dropping empty-title rows. */
+  private normalizeArticles(
+    articles: Array<{ id?: string; title?: string; body?: string; order?: number }>,
+  ): ContractDocumentArticle[] {
+    return articles
+      .filter((a) => (a.title ?? '').trim().length > 0 || (a.body ?? '').trim().length > 0)
+      .map((a, index) => ({
+        id: a.id ?? randomUUID(),
+        title: (a.title ?? '').trim(),
+        body: a.body ?? '',
+        order: index + 1,
+      }));
+  }
+
+  /**
+   * The per-contract document may be edited/regenerated while the contract is at
+   * the accept stage (SUBMITTED) or in approval with NO approver having acted
+   * yet. The first approval action freezes it.
+   */
+  private documentIsEditable(contract: Contract): boolean {
+    if (contract.status === 'SUBMITTED') return true;
+    if (contract.status !== 'PENDING_APPROVAL') return false;
+    return !(contract.approvalSteps ?? []).some((s) => s.status !== 'PENDING');
+  }
+
+  private assertDocumentEditable(contract: Contract): void {
+    if (!this.documentIsEditable(contract)) {
+      throw new ConflictException(
+        'The contract document is locked — an approver has already acted or the ' +
+          'contract has advanced. It can no longer be edited or regenerated.',
+      );
+    }
+  }
+
   /**
    * Ensure the chosen validity (days) is one of the admin-configured options in
    * the `contract_validity_periods` dropdown setting. If the setting is missing
@@ -303,6 +467,15 @@ export class ContractTransitionService {
     const contract = await this.contractsService.findById(contractId);
     assertContractStatus(contract, ['PENDING_APPROVAL', 'APPROVED_PENDING_SIGNATURE']);
 
+    // Approvers review the generated contract document, so it must exist before
+    // the first approval can be recorded. Staff generate it (from the frozen,
+    // optionally-edited snapshot) at the accept stage.
+    if (contract.status === 'PENDING_APPROVAL' && !contract.contractGeneratedAt) {
+      throw new BadRequestException(
+        'Generate the contract document before it can be approved.',
+      );
+    }
+
     const step = await this.contractsRepository.findApprovalStepById(contractId, stepId);
     if (!step || step.status !== 'PENDING') {
       throw new BadRequestException('Approval step not found or already actioned');
@@ -350,15 +523,14 @@ export class ContractTransitionService {
     const updated = await this.contractsService.findById(contractId);
     if (allDone) {
       this.notifier.approved(updated);
-      // Final approval step also generates the contract document from the
-      // template matching the contract's direction/freight pair. Best-effort:
-      // a rendering hiccup must not roll back the approval — the document can
-      // still be generated manually or lazily on view/download.
+      // Every step approved → CONTRACT_READY. The document was already generated
+      // (and reviewed) at the accept stage, so we reuse it rather than
+      // re-rendering. Best-effort: a hiccup must not roll back the approval.
       try {
-        return await this.generateContract(contractId);
+        return await this.finalizeApprovedContract(contractId);
       } catch (err) {
         this.logger.warn(
-          `Auto contract generation after final approval failed for ${updated.reference}: ${err}`,
+          `Finalizing contract after final approval failed for ${updated.reference}: ${err}`,
         );
       }
     }
@@ -366,30 +538,66 @@ export class ContractTransitionService {
   }
 
   /**
-   * Render the contract PDF from the Contract aggregate, store it via FilesService,
-   * stamp the template key, and move to CONTRACT_READY. PDF rendering (Puppeteer/
-   * Chromium) is best-effort and must NOT block the contract from becoming ready —
-   * the document is (re)rendered lazily on view/download once Chromium is available.
+   * Staff (re)generate the contract PDF. Two stages:
+   *  - PENDING_APPROVAL: render from the frozen (optionally staff-edited)
+   *    snapshot so approvers review the real document. Status is UNCHANGED, and
+   *    it is blocked once an approver has acted (the document is then locked).
+   *  - APPROVED / APPROVED_PENDING_SIGNATURE (fallback): render and advance to
+   *    CONTRACT_READY.
+   * PDF rendering (Puppeteer/Chromium) is best-effort and never blocks the
+   * transition — the document re-renders lazily on view/download.
    */
   async generateContract(contractId: string): Promise<Contract> {
     const contract = await this.contractsService.findById(contractId);
+
+    if (contract.status === 'PENDING_APPROVAL') {
+      this.assertDocumentEditable(contract);
+      await this.renderContractDocument(contract);
+      return this.contractsService.findById(contractId);
+    }
+
     assertContractStatus(contract, ['APPROVED', 'APPROVED_PENDING_SIGNATURE']);
+    await this.renderContractDocument(contract);
+    await this.contractsRepository.update(contractId, {
+      status: 'CONTRACT_READY',
+    } as never);
+    return this.contractsService.findById(contractId);
+  }
 
-    const { view } = await this.documentViewModelBuilder.build(contractId);
-
+  /**
+   * Render the contract PDF from the Contract aggregate (snapshot-driven), store
+   * it via FilesService, and stamp the template key + generated timestamp. Never
+   * changes status. Rendering is best-effort — a Chromium hiccup defers the file
+   * (it re-renders on view/download) but the timestamp is still stamped.
+   */
+  private async renderContractDocument(contract: Contract): Promise<void> {
+    const { view } = await this.documentViewModelBuilder.build(contract.id);
     try {
-      await this.upsertContractPdf(contractId, contract.reference, view);
+      await this.upsertContractPdf(contract.id, contract.reference, view);
     } catch (err) {
       this.logger.warn(
         `Contract PDF deferred for ${contract.reference}: ${err}. It will render on view/download once Chromium is available.`,
       );
     }
-
-    await this.contractsRepository.update(contractId, {
-      status: 'CONTRACT_READY',
+    await this.contractsRepository.update(contract.id, {
       contractTemplateKey: view.templateKey,
       contractGeneratedAt: new Date(),
     } as never);
+  }
+
+  /**
+   * Every approval step landed → CONTRACT_READY. The document was already
+   * generated (and reviewed) at the accept stage, so reuse it; render now only
+   * if it was somehow never generated. Never re-renders over an existing file.
+   */
+  private async finalizeApprovedContract(contractId: string): Promise<Contract> {
+    const contract = await this.contractsService.findById(contractId);
+    if (!contract.contractGeneratedAt) {
+      await this.renderContractDocument(contract);
+    }
+    await this.contractsRepository.update(contractId, {
+      status: 'CONTRACT_READY',
+    } as never);
     return this.contractsService.findById(contractId);
   }
 

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

@@ -8,6 +8,7 @@ import {
   ParseUUIDPipe,
   Patch,
   Post,
+  Put,
   Query,
   Res,
   UnauthorizedException,
@@ -57,6 +58,7 @@ import { UpdateContractDto } from './dto/update-contract.dto';
 import { FilterContractDto } from './dto/filter-contract.dto';
 import { ContractListSummaryDto } from './dto/contract-list-summary.dto';
 import { AcceptContractDto } from './dto/accept-contract.dto';
+import { UpdateContractDocumentDto } from './dto/contract-document.dto';
 import {
   ApproveStepDto,
   RejectContractDto,
@@ -340,9 +342,33 @@ export class ContractsController {
       id,
       resolveAuthUserId(user),
       dto.validityDays,
+      dto.documentSnapshot,
     );
   }
 
+  @Get(':id/document/draft')
+  @BookingStaff(FREIGHT_PERMS.contracts.staffAccept)
+  @ApiOperation({
+    summary:
+      'Editable contract-document draft (this contract\'s snapshot, or the live template) for the accept/edit dialog',
+  })
+  getContractDocumentDraft(@Param('id', ParseUUIDPipe) id: string) {
+    return this.transitionService.getContractDocumentDraft(id);
+  }
+
+  @Put(':id/document/articles')
+  @BookingStaff(FREIGHT_PERMS.contracts.staffAccept)
+  @ApiOperation({
+    summary:
+      'Edit this contract\'s document articles only (per-contract; never touches the six shared templates)',
+  })
+  updateContractDocument(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: UpdateContractDocumentDto,
+  ) {
+    return this.transitionService.updateContractDocument(id, dto);
+  }
+
   @Post(':id/staff/request-changes')
   @BookingStaff(FREIGHT_PERMS.contracts.requestChanges)
   @ApiOperation({ summary: 'Staff return contract for customer updates' })

apps/edr-freight-api/src/modules/contracts/dto/accept-contract.dto.ts

@@ -1,5 +1,8 @@
-import { ApiProperty } from '@nestjs/swagger';
-import { IsInt, Max, Min } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import { IsInt, IsOptional, Max, Min, ValidateNested } from 'class-validator';
+
+import { UpdateContractDocumentDto } from './contract-document.dto';
 
 export class AcceptContractDto {
   @ApiProperty({
@@ -14,4 +17,16 @@ export class AcceptContractDto {
   @Min(1)
   @Max(3650)
   validityDays!: number;
+
+  /**
+   * Optional per-contract document override edited by staff in the accept
+   * dialog. When present its articles are frozen onto THIS contract; when
+   * omitted the live template is snapshotted as-is. Never edits the shared
+   * six templates.
+   */
+  @ApiPropertyOptional({ type: UpdateContractDocumentDto })
+  @IsOptional()
+  @ValidateNested()
+  @Type(() => UpdateContractDocumentDto)
+  documentSnapshot?: UpdateContractDocumentDto;
 }

apps/edr-freight-api/src/modules/contracts/dto/contract-document.dto.ts

@@ -0,0 +1,64 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import {
+  IsArray,
+  IsInt,
+  IsOptional,
+  IsString,
+  ValidateNested,
+} from 'class-validator';
+
+/** One article of a per-contract document override sent from the editor. */
+export class ContractDocumentArticleDto {
+  @ApiPropertyOptional({ description: 'Stable id; omitted for a new article.' })
+  @IsOptional()
+  @IsString()
+  id?: string;
+
+  @ApiProperty()
+  @IsString()
+  title!: string;
+
+  @ApiProperty({ description: 'Plain multiline body; each line becomes a clause.' })
+  @IsString()
+  body!: string;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsInt()
+  order?: number;
+}
+
+/**
+ * The per-contract document override sent from the accept/edit editor. It edits
+ * ONLY this contract's frozen snapshot — it is never written back to the shared
+ * six {@link ContractTemplate} rows.
+ */
+export class UpdateContractDocumentDto {
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  code?: string | null;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  name?: string | null;
+
+  @ApiPropertyOptional()
+  @IsOptional()
+  @IsString()
+  documentTitle?: string | null;
+
+  @ApiPropertyOptional({ type: [String] })
+  @IsOptional()
+  @IsArray()
+  @IsString({ each: true })
+  whereasClauses?: string[];
+
+  @ApiProperty({ type: [ContractDocumentArticleDto] })
+  @IsArray()
+  @ValidateNested({ each: true })
+  @Type(() => ContractDocumentArticleDto)
+  articles!: ContractDocumentArticleDto[];
+}

apps/edr-freight-api/src/modules/contracts/entities/contract.entity.ts

@@ -42,6 +42,43 @@ export const CONTRACT_STATUSES = [
 
 export type ContractStatus = (typeof CONTRACT_STATUSES)[number];
 
+/** One article on a per-contract document snapshot (mirrors the template shape). */
+export interface ContractDocumentArticle {
+  id: string;
+  title: string;
+  body: string;
+  order: number;
+}
+
+/**
+ * A per-contract copy of the resolved contract-document template, frozen when
+ * staff accept the contract for approval. Staff may edit these articles for a
+ * single contract in the accept/edit dialog — editing NEVER writes back to the
+ * shared six {@link ContractTemplate} rows. The PDF is rendered from this
+ * snapshot when present; a null snapshot renders from the live template.
+ */
+export interface ContractDocumentSnapshot {
+  code?: string | null;
+  name?: string | null;
+  documentTitle?: string | null;
+  whereasClauses: string[];
+  articles: ContractDocumentArticle[];
+}
+
+/** Loose inbound shape (article ids/order optional) — normalized before store. */
+export interface ContractDocumentSnapshotInput {
+  code?: string | null;
+  name?: string | null;
+  documentTitle?: string | null;
+  whereasClauses?: string[];
+  articles?: Array<{
+    id?: string;
+    title?: string;
+    body?: string;
+    order?: number;
+  }>;
+}
+
 export const CONTRACT_KINDS = ['ONE_TIME', 'GENERAL'] as const;
 export type ContractKindValue = (typeof CONTRACT_KINDS)[number];
 
@@ -193,6 +230,14 @@ export class Contract extends BaseEntity {
   @Column({ name: 'contract_generated_at', type: 'timestamptz', nullable: true })
   contractGeneratedAt?: Date | null;
 
+  /**
+   * Per-contract frozen copy of the document template (articles + WHEREAS),
+   * captured at staff accept. Editing it affects only this contract, never the
+   * shared six templates. Null → the PDF renders from the live template.
+   */
+  @Column({ name: 'document_snapshot', type: 'jsonb', nullable: true })
+  documentSnapshot?: ContractDocumentSnapshot | null;
+
   @Column({ name: 'contract_summary', type: 'text', nullable: true })
   contractSummary?: string | null;
 

apps/edr-freight-api/src/modules/rule-engine/controllers/priority-rule-change-requests.controller.ts

@@ -0,0 +1,72 @@
+import {
+  Body,
+  Controller,
+  Get,
+  Param,
+  ParseUUIDPipe,
+  Post,
+  Query,
+} from '@nestjs/common';
+import { ApiBearerAuth, ApiOperation, ApiQuery, ApiTags } from '@nestjs/swagger';
+import { CurrentUser } from '@edr/api-common';
+import type { TCurrentUser } from '@tria-plc/api-common/modules/auth/types/current-user.type';
+
+import { RuleEngineManage, RuleEngineView } from '../../../common/rule-engine-guards';
+import {
+  DecidePriorityRuleChangeDto,
+  SubmitPriorityRuleChangeDto,
+} from '../dto/priority-rule-change-request.dto';
+import { PriorityRuleChangeStatus } from '../entities/priority-rule-change-request.entity';
+import { PriorityRuleChangeRequestsService } from '../services/priority-rule-change-requests.service';
+
+/**
+ * Approval workflow for priority-rule changes. Anyone with the manage
+ * permission SUBMITS a change; an approver (same permission — the team decides
+ * who reviews) approves or rejects it. The team is notified at each step.
+ */
+@ApiTags('priority-rule-change-requests')
+@Controller('priority-rule-change-requests')
+@ApiBearerAuth()
+export class PriorityRuleChangeRequestsController {
+  constructor(private readonly service: PriorityRuleChangeRequestsService) {}
+
+  @Post()
+  @RuleEngineManage('priority-configs')
+  @ApiOperation({ summary: 'Submit a priority-rule change for approval' })
+  submit(
+    @Body() dto: SubmitPriorityRuleChangeDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.service.submit(dto, user?.id);
+  }
+
+  @Get()
+  @RuleEngineView('priority-configs')
+  @ApiQuery({ name: 'status', required: false, enum: ['PENDING', 'APPROVED', 'REJECTED'] })
+  @ApiOperation({ summary: 'List priority-rule change requests' })
+  list(@Query('status') status?: PriorityRuleChangeStatus) {
+    return this.service.list(status);
+  }
+
+  @Post(':id/approve')
+  @RuleEngineManage('priority-configs')
+  @ApiOperation({ summary: 'Approve and apply a pending change' })
+  approve(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: DecidePriorityRuleChangeDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.service.approve(id, user?.id, dto.decisionNote);
+  }
+
+  @Post(':id/reject')
+  @RuleEngineManage('priority-configs')
+  @ApiOperation({ summary: 'Reject a pending change' })
+  reject(
+    @Param('id', ParseUUIDPipe) id: string,
+    @Body() dto: DecidePriorityRuleChangeDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.service.reject(id, user?.id, dto.decisionNote);
+  }
+}

apps/edr-freight-api/src/modules/rule-engine/dto/priority-rule-change-request.dto.ts

@@ -0,0 +1,49 @@
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import { Type } from 'class-transformer';
+import {
+  IsIn,
+  IsOptional,
+  IsString,
+  IsUUID,
+  MaxLength,
+  ValidateNested,
+} from 'class-validator';
+
+import { CreatePriorityConfigDto } from './create-priority-config.dto';
+import { UpdatePriorityConfigDto } from './update-priority-config.dto';
+
+/**
+ * File a priority-rule change for approval. CREATE carries a full `create`
+ * payload; UPDATE carries the target id + an `update` patch; DELETE carries
+ * only the target id.
+ */
+export class SubmitPriorityRuleChangeDto {
+  @ApiProperty({ enum: ['CREATE', 'UPDATE', 'DELETE'] })
+  @IsIn(['CREATE', 'UPDATE', 'DELETE'])
+  action!: 'CREATE' | 'UPDATE' | 'DELETE';
+
+  @ApiPropertyOptional({ description: 'Target rule id (UPDATE / DELETE)' })
+  @IsOptional()
+  @IsUUID()
+  priorityConfigId?: string;
+
+  @ApiPropertyOptional({ description: 'Proposed new rule (CREATE)' })
+  @IsOptional()
+  @ValidateNested()
+  @Type(() => CreatePriorityConfigDto)
+  create?: CreatePriorityConfigDto;
+
+  @ApiPropertyOptional({ description: 'Proposed field changes (UPDATE)' })
+  @IsOptional()
+  @ValidateNested()
+  @Type(() => UpdatePriorityConfigDto)
+  update?: UpdatePriorityConfigDto;
+}
+
+export class DecidePriorityRuleChangeDto {
+  @ApiPropertyOptional({ description: 'Optional note shown to the requester' })
+  @IsOptional()
+  @IsString()
+  @MaxLength(1000)
+  decisionNote?: string;
+}

apps/edr-freight-api/src/modules/rule-engine/entities/priority-rule-change-request.entity.ts

@@ -0,0 +1,46 @@
+import { BaseEntity } from '@edr/api-common';
+import { Column, Entity, Index, JoinColumn, ManyToOne } from 'typeorm';
+
+import { PriorityConfig } from './priority-config.entity';
+
+export type PriorityRuleChangeAction = 'CREATE' | 'UPDATE' | 'DELETE';
+export type PriorityRuleChangeStatus = 'PENDING' | 'APPROVED' | 'REJECTED';
+
+/**
+ * One proposed change to a priority rule, awaiting approval. Every
+ * create/update/delete of a priority config is filed here first; an approver
+ * applies (which runs the real mutation, including range-collision checks) or
+ * rejects it. `payload` holds the proposed field values (null for DELETE);
+ * `priorityConfigId` the target rule (null for CREATE).
+ */
+@Entity({ schema: 'freight', name: 'priority_rule_change_requests' })
+@Index(['status'])
+export class PriorityRuleChangeRequest extends BaseEntity {
+  @Column({ name: 'action', type: 'varchar', length: 10 })
+  action!: PriorityRuleChangeAction;
+
+  @Column({ name: 'priority_config_id', type: 'uuid', nullable: true })
+  priorityConfigId?: string | null;
+
+  @ManyToOne(() => PriorityConfig, { nullable: true })
+  @JoinColumn({ name: 'priority_config_id' })
+  priorityConfig?: PriorityConfig | null;
+
+  @Column({ name: 'payload', type: 'jsonb', nullable: true })
+  payload?: Record<string, unknown> | null;
+
+  @Column({ name: 'status', type: 'varchar', length: 10, default: 'PENDING' })
+  status!: PriorityRuleChangeStatus;
+
+  @Column({ name: 'requested_by_user_id', type: 'uuid', nullable: true })
+  requestedByUserId?: string | null;
+
+  @Column({ name: 'decided_by_user_id', type: 'uuid', nullable: true })
+  decidedByUserId?: string | null;
+
+  @Column({ name: 'decided_at', type: 'timestamptz', nullable: true })
+  decidedAt?: Date | null;
+
+  @Column({ name: 'decision_note', type: 'text', nullable: true })
+  decisionNote?: string | null;
+}

apps/edr-freight-api/src/modules/rule-engine/rule-engine.module.ts

@@ -5,6 +5,7 @@ import { ApprovalRulesController } from './controllers/approval-rules.controller
 import { CargoTypesController } from './controllers/cargo-types.controller';
 import { ContainerTypesController } from './controllers/container-types.controller';
 import { PriorityConfigsController } from './controllers/priority-configs.controller';
+import { PriorityRuleChangeRequestsController } from './controllers/priority-rule-change-requests.controller';
 import { RatesController } from './controllers/rates.controller';
 import { ServiceTypesController } from './controllers/service-types.controller';
 import { ShippingLinesController } from './controllers/shipping-lines.controller';
@@ -15,6 +16,7 @@ import { ApprovalRule } from './entities/approval-rule.entity';
 import { CargoType } from './entities/cargo-type.entity';
 import { ContainerType } from './entities/container-type.entity';
 import { PriorityConfig } from './entities/priority-config.entity';
+import { PriorityRuleChangeRequest } from './entities/priority-rule-change-request.entity';
 import { Rate } from './entities/rate.entity';
 import { ServiceType } from './entities/service-type.entity';
 import { ShippingLine } from './entities/shipping-line.entity';
@@ -46,6 +48,7 @@ import { DisplayOrderService } from './services/display-order.service';
 import { CargoTypesService } from './services/cargo-types.service';
 import { ContainerTypesService } from './services/container-types.service';
 import { PriorityConfigsService } from './services/priority-configs.service';
+import { PriorityRuleChangeRequestsService } from './services/priority-rule-change-requests.service';
 import { RatesService } from './services/rates.service';
 import { ServiceTypesService } from './services/service-types.service';
 import { ShippingLinesService } from './services/shipping-lines.service';
@@ -54,6 +57,8 @@ import { YardsService } from './services/yards.service';
 
 import { RuleEngineService } from './rule-engine.service';
 
+import { NotificationInboxModule } from '../notification-inbox/notification-inbox.module';
+
 import { BookingApprovalStep } from '../bookings/entities/booking-approval-step.entity';
 import { BookingCargoModifier } from '../bookings/entities/booking-cargo-modifier.entity';
 import { BookingContainer } from '../bookings/entities/booking-container.entity';
@@ -66,6 +71,7 @@ import { BookingRateSnapshot } from '../bookings/entities/booking-rate-snapshot.
       CargoType,
       ContainerType,
       PriorityConfig,
+      PriorityRuleChangeRequest,
       ServiceType,
       WeightLimitRule,
       Yard,
@@ -77,11 +83,14 @@ import { BookingRateSnapshot } from '../bookings/entities/booking-rate-snapshot.
       BookingApprovalStep,
       BookingRateSnapshot,
     ]),
+    // Team notifications for the priority-rule approval workflow.
+    NotificationInboxModule,
   ],
   controllers: [
     CargoTypesController,
     ContainerTypesController,
     PriorityConfigsController,
+    PriorityRuleChangeRequestsController,
     ServiceTypesController,
     WeightLimitRulesController,
     YardsController,
@@ -111,6 +120,7 @@ import { BookingRateSnapshot } from '../bookings/entities/booking-rate-snapshot.
     CargoTypesService,
     ContainerTypesService,
     PriorityConfigsService,
+    PriorityRuleChangeRequestsService,
     ServiceTypesService,
     WeightLimitRulesService,
     YardsService,

apps/edr-freight-api/src/modules/rule-engine/services/priority-configs.service.ts

@@ -31,6 +31,12 @@ export class PriorityConfigsService {
 
   async create(dto: CreatePriorityConfigDto): Promise<PriorityConfig> {
     this.validateCurrencyField(dto.type, dto.currency);
+    await this.assertNoRangeCollision({
+      type: dto.type,
+      currency: dto.currency ?? null,
+      minWagonCount: dto.minWagonCount,
+      maxWagonCount: dto.maxWagonCount,
+    });
 
     const displayOrder = await this.displayOrder.resolveCreateOrder(PriorityConfig, 'displayOrder', {});
 
@@ -52,6 +58,13 @@ export class PriorityConfigsService {
     const type = dto.type ?? existing.type;
     const currency = dto.currency !== undefined ? dto.currency : existing.currency;
     this.validateCurrencyField(type, currency);
+    await this.assertNoRangeCollision({
+      type,
+      currency: currency ?? null,
+      minWagonCount: dto.minWagonCount ?? existing.minWagonCount,
+      maxWagonCount: dto.maxWagonCount ?? existing.maxWagonCount,
+      excludeId: id,
+    });
 
     const { ...patch } = dto;
     const updated = await this.repository.update(id, patch);
@@ -59,6 +72,43 @@ export class PriorityConfigsService {
     return updated;
   }
 
+  /**
+   * No two rules of the same type (and, for CURRENCY rules, the same currency)
+   * may cover overlapping wagon-count ranges — a booking must match at most one
+   * rule per type. Rejects an exact duplicate (1–5 vs 1–5) and any partial
+   * overlap (1–5 vs 4–7). Ranges are inclusive on both ends.
+   */
+  async assertNoRangeCollision(input: {
+    type: 'WAGON' | 'CURRENCY' | 'CUSTOMS';
+    currency?: string | null;
+    minWagonCount: number;
+    maxWagonCount: number;
+    excludeId?: string;
+  }): Promise<void> {
+    if (input.minWagonCount > input.maxWagonCount) {
+      throw new BadRequestException(
+        'Min wagon count cannot be greater than max wagon count',
+      );
+    }
+    const siblings = await this.repository.findAll({
+      where: { type: input.type },
+    });
+    const clash = siblings.find(
+      (s) =>
+        s.id !== input.excludeId &&
+        (input.type !== 'CURRENCY' || (s.currency ?? null) === (input.currency ?? null)) &&
+        input.minWagonCount <= s.maxWagonCount &&
+        input.maxWagonCount >= s.minWagonCount,
+    );
+    if (clash) {
+      throw new BadRequestException(
+        `Wagon range ${input.minWagonCount}–${input.maxWagonCount} overlaps existing rule ` +
+          `"${clash.label}" (${clash.minWagonCount}–${clash.maxWagonCount}). ` +
+          'Adjust the range so rules do not collide.',
+      );
+    }
+  }
+
   async remove(id: string): Promise<void> {
     await this.findById(id);
     await this.repository.softDelete(id);

apps/edr-freight-api/src/modules/rule-engine/services/priority-rule-change-requests.service.ts

@@ -0,0 +1,226 @@
+import {
+  NotificationAudience,
+  NotificationType,
+} from '@edr/types';
+import {
+  BadRequestException,
+  ConflictException,
+  Injectable,
+  Logger,
+  NotFoundException,
+} from '@nestjs/common';
+import { InjectRepository } from '@nestjs/typeorm';
+import { Repository } from 'typeorm';
+
+import { NotificationInboxService } from '../../notification-inbox/notification-inbox.service';
+import { CreatePriorityConfigDto } from '../dto/create-priority-config.dto';
+import { SubmitPriorityRuleChangeDto } from '../dto/priority-rule-change-request.dto';
+import { UpdatePriorityConfigDto } from '../dto/update-priority-config.dto';
+import {
+  PriorityRuleChangeRequest,
+  PriorityRuleChangeStatus,
+} from '../entities/priority-rule-change-request.entity';
+import { PriorityConfigsService } from './priority-configs.service';
+
+/** Backoffice rule-engine page — where both queue and rules live. */
+const RULES_LINK = '/dashboard/rules/priority-configs';
+
+/**
+ * Approval workflow for priority-rule changes. Nobody mutates priority configs
+ * directly any more: a change is SUBMITTED here (validated up front so the
+ * requester gets immediate feedback on range collisions), the team is
+ * notified, and an approver later applies or rejects it. Applying re-runs the
+ * full validation — the winning state is whatever is true at approval time.
+ */
+@Injectable()
+export class PriorityRuleChangeRequestsService {
+  private readonly logger = new Logger(PriorityRuleChangeRequestsService.name);
+
+  constructor(
+    @InjectRepository(PriorityRuleChangeRequest)
+    private readonly repo: Repository<PriorityRuleChangeRequest>,
+    private readonly configs: PriorityConfigsService,
+    private readonly inbox: NotificationInboxService,
+  ) {}
+
+  async submit(
+    dto: SubmitPriorityRuleChangeDto,
+    userId?: string | null,
+  ): Promise<PriorityRuleChangeRequest> {
+    const payload = await this.validateSubmission(dto);
+
+    const request = await this.repo.save(
+      this.repo.create({
+        action: dto.action,
+        priorityConfigId: dto.priorityConfigId ?? null,
+        payload,
+        status: 'PENDING',
+        requestedByUserId: userId ?? null,
+      }),
+    );
+
+    this.notifyTeam(
+      'Priority rule change submitted',
+      `A ${dto.action.toLowerCase()} of a priority rule was submitted and awaits approval.`,
+      request,
+    );
+    return request;
+  }
+
+  async list(status?: PriorityRuleChangeStatus): Promise<PriorityRuleChangeRequest[]> {
+    return this.repo.find({
+      where: status ? { status } : {},
+      relations: { priorityConfig: true },
+      order: { createdAt: 'DESC' },
+    });
+  }
+
+  async approve(
+    id: string,
+    userId?: string | null,
+    decisionNote?: string,
+  ): Promise<PriorityRuleChangeRequest> {
+    const request = await this.findPending(id);
+
+    // Apply the change through the normal service so currency + range-collision
+    // validation runs against the CURRENT rules; a stale request that now
+    // collides fails here and stays PENDING for the approver to see the error.
+    if (request.action === 'CREATE') {
+      await this.configs.create(request.payload as unknown as CreatePriorityConfigDto);
+    } else if (request.action === 'UPDATE') {
+      await this.configs.update(
+        this.requireTarget(request),
+        request.payload as unknown as UpdatePriorityConfigDto,
+      );
+    } else {
+      await this.configs.remove(this.requireTarget(request));
+    }
+
+    request.status = 'APPROVED';
+    request.decidedByUserId = userId ?? null;
+    request.decidedAt = new Date();
+    request.decisionNote = decisionNote ?? null;
+    const saved = await this.repo.save(request);
+
+    this.notifyTeam(
+      'Priority rule change approved',
+      `The ${request.action.toLowerCase()} priority-rule change was approved and applied.` +
+        (decisionNote ? ` Note: ${decisionNote}` : ''),
+      saved,
+    );
+    return saved;
+  }
+
+  async reject(
+    id: string,
+    userId?: string | null,
+    decisionNote?: string,
+  ): Promise<PriorityRuleChangeRequest> {
+    const request = await this.findPending(id);
+    request.status = 'REJECTED';
+    request.decidedByUserId = userId ?? null;
+    request.decidedAt = new Date();
+    request.decisionNote = decisionNote ?? null;
+    const saved = await this.repo.save(request);
+
+    this.notifyTeam(
+      'Priority rule change rejected',
+      `The ${request.action.toLowerCase()} priority-rule change was rejected.` +
+        (decisionNote ? ` Note: ${decisionNote}` : ''),
+      saved,
+    );
+    return saved;
+  }
+
+  /**
+   * Validate a submission the way applying it would, so bad requests are
+   * refused at the door — most importantly the wagon-range collision rule.
+   * Returns the payload to persist.
+   */
+  private async validateSubmission(
+    dto: SubmitPriorityRuleChangeDto,
+  ): Promise<Record<string, unknown> | null> {
+    if (dto.action === 'CREATE') {
+      if (!dto.create) {
+        throw new BadRequestException('CREATE requires the proposed rule in `create`');
+      }
+      await this.configs.assertNoRangeCollision({
+        type: dto.create.type,
+        currency: dto.create.currency ?? null,
+        minWagonCount: dto.create.minWagonCount,
+        maxWagonCount: dto.create.maxWagonCount,
+      });
+      return { ...dto.create };
+    }
+
+    if (!dto.priorityConfigId) {
+      throw new BadRequestException(`${dto.action} requires priorityConfigId`);
+    }
+    const existing = await this.configs.findById(dto.priorityConfigId);
+
+    if (dto.action === 'DELETE') return null;
+
+    if (!dto.update || Object.keys(dto.update).length === 0) {
+      throw new BadRequestException('UPDATE requires the field changes in `update`');
+    }
+    await this.configs.assertNoRangeCollision({
+      type: dto.update.type ?? existing.type,
+      currency:
+        dto.update.currency !== undefined ? dto.update.currency : existing.currency,
+      minWagonCount: dto.update.minWagonCount ?? existing.minWagonCount,
+      maxWagonCount: dto.update.maxWagonCount ?? existing.maxWagonCount,
+      excludeId: existing.id,
+    });
+    return { ...dto.update };
+  }
+
+  private async findPending(id: string): Promise<PriorityRuleChangeRequest> {
+    const request = await this.repo.findOne({
+      where: { id },
+      relations: { priorityConfig: true },
+    });
+    if (!request) throw new NotFoundException(`Change request ${id} not found`);
+    if (request.status !== 'PENDING') {
+      throw new ConflictException(
+        `Change request is already ${request.status.toLowerCase()}`,
+      );
+    }
+    return request;
+  }
+
+  private requireTarget(request: PriorityRuleChangeRequest): string {
+    if (!request.priorityConfigId) {
+      throw new BadRequestException(
+        `${request.action} change request has no target rule`,
+      );
+    }
+    return request.priorityConfigId;
+  }
+
+  /**
+   * In-app notification to the whole backoffice team (submission AND decision
+   * both notify the team; the requester is staff, so they are included).
+   * Fire-and-forget — a notification failure never blocks the workflow.
+   */
+  private notifyTeam(
+    title: string,
+    body: string,
+    request: PriorityRuleChangeRequest,
+  ): void {
+    void this.inbox
+      .notify({
+        recipients: { allBackoffice: true },
+        audience: NotificationAudience.BACKOFFICE,
+        type: NotificationType.REQUEST_SUBMITTED,
+        title,
+        body,
+        link: RULES_LINK,
+        data: { priorityRuleChangeRequestId: request.id, action: request.action },
+      })
+      .catch((err) =>
+        this.logger.warn(
+          `Priority-rule notification failed: ${(err as Error).message}`,
+        ),
+      );
+  }
+}

apps/edr-freight-api/src/modules/train-scheduling/dto/available-days-for-cargo-query.dto.ts

@@ -41,6 +41,28 @@ export class AvailableDaysForCargoQueryDto {
   @IsString()
   cargoTypeCode?: string;
 
+  @ApiPropertyOptional({ format: 'uuid', description: 'Bulk cargo type id (preferred over code).' })
+  @IsOptional()
+  @IsUUID()
+  cargoTypeId?: string;
+
+  @ApiPropertyOptional({
+    description:
+      'Container type ids as a JSON string array — enables the exact wagon-type compatibility gate (falls back to containerSize matching when absent).',
+  })
+  @IsOptional()
+  @Transform(({ value }) => {
+    if (value == null || value === '') return undefined;
+    if (typeof value !== 'string') return value;
+    try {
+      return JSON.parse(value);
+    } catch {
+      return undefined;
+    }
+  })
+  @IsArray()
+  containerTypeIds?: string[];
+
   @ApiPropertyOptional({ description: 'Total bulk weight in tons.' })
   @IsOptional()
   @Transform(({ value }) => (value === '' || value == null ? undefined : Number(value)))

apps/edr-freight-api/src/modules/train-scheduling/train-scheduling.controller.ts

@@ -234,9 +234,11 @@ export class TrainSchedulingController {
       originYardId: query.originYardId,
       destinationYardId: query.destinationYardId,
       freightType: query.freightType,
+      cargoTypeId: query.cargoTypeId,
       cargoTypeCode: query.cargoTypeCode,
       totalWeightTons: query.totalWeightTons,
       containers: query.containers,
+      containerTypeIds: query.containerTypeIds,
     });
   }
 

apps/edr-freight-api/src/modules/train-scheduling/train-scheduling.service.ts

@@ -1391,8 +1391,6 @@ export class TrainSchedulingService {
     await this.dataSource.transaction(async (manager) => {
       const trainSetId = schedule.trainSetId;
 
-      await this.releasePinnedWagonsForTrainSet(manager, trainSetId);
-
       const deletedAllocationIds =
         await this.wagonBookingAllocationsRepository.deleteByTrainSetId(trainSetId, manager);
 
@@ -1528,7 +1526,6 @@ export class TrainSchedulingService {
         (sb) => sb.bookingId !== bookingId,
       );
       if (remainingBookings.length === 0) {
-        await this.releasePinnedWagonsForTrainSet(manager, schedule.trainSetId);
         await this.wagonBookingAllocationsRepository.deleteByTrainSetId(
           schedule.trainSetId,
           manager,
@@ -1768,7 +1765,18 @@ export class TrainSchedulingService {
       throw new BadRequestException('Cannot pin wagons on a dispatched or cancelled schedule');
     }
 
-    const slotIds = new Set((schedule.trainSet?.wagons ?? []).map((w) => w.id));
+    const slots = schedule.trainSet?.wagons ?? [];
+    const slotIds = new Set(slots.map((w) => w.id));
+    const slotById = new Map(slots.map((w) => [w.id, w]));
+    const builtTrainId = await this.builtTrainIdOfSchedule(scheduleId);
+    // Occupancy is judged against THIS schedule's own slots only — a wagon
+    // pinned on another schedule (e.g. the same train's July 17 run) stays
+    // pinnable here.
+    const slotIdByPhysicalId = new Map(
+      slots
+        .filter((w) => w.physicalWagonId)
+        .map((w) => [w.physicalWagonId as string, w.id]),
+    );
 
     await this.dataSource.transaction(async (manager) => {
       for (const assignment of dto.assignments) {
@@ -1784,29 +1792,61 @@ export class TrainSchedulingService {
         if (!physicalWagon) {
           throw new NotFoundException(`Wagon ${assignment.physicalWagonId} not found`);
         }
-        if (
-          physicalWagon.status !== WagonStatus.Available &&
-          physicalWagon.currentTrainScheduleId !== scheduleId
-        ) {
+        const occupyingSlotId = slotIdByPhysicalId.get(assignment.physicalWagonId);
+        if (occupyingSlotId && occupyingSlotId !== assignment.trainSetWagonId) {
+          const occupyingSlot = slotById.get(occupyingSlotId);
           throw new ConflictException(
-            `Wagon ${physicalWagon.wagonNumber} is not available`,
+            `Wagon ${physicalWagon.wagonNumber} is already pinned to slot #${occupyingSlot?.sequenceNo ?? '?'} of this schedule`,
           );
         }
-        if (physicalWagon.currentYardId !== schedule.originStationId) {
-          throw new ConflictException(
-            `Wagon ${physicalWagon.wagonNumber} is at yard ${physicalWagon.currentYardId} but schedule originates from ${schedule.originStationId}`,
-          );
+        if (builtTrainId) {
+          // Train-bound schedule: only the built train's own consist may be
+          // pinned — wherever the wagons currently sit, they travel with the
+          // train, so no yard/status gate applies.
+          if (physicalWagon.trainId !== builtTrainId) {
+            throw new ConflictException(
+              `Wagon ${physicalWagon.wagonNumber} is not part of this schedule's train`,
+            );
+          }
+        } else {
+          if (physicalWagon.trainId) {
+            throw new ConflictException(
+              `Wagon ${physicalWagon.wagonNumber} is coupled to a built train and cannot be pinned as a loose wagon`,
+            );
+          }
+          if (!this.isWagonPhysicallyUsable(physicalWagon)) {
+            throw new ConflictException(
+              `Wagon ${physicalWagon.wagonNumber} is not available (${physicalWagon.status})`,
+            );
+          }
+          if (
+            physicalWagon.currentTrainScheduleId &&
+            physicalWagon.currentTrainScheduleId !== scheduleId
+          ) {
+            throw new ConflictException(
+              `Wagon ${physicalWagon.wagonNumber} is out on a dispatched train`,
+            );
+          }
+          if (physicalWagon.currentYardId !== schedule.originStationId) {
+            throw new ConflictException(
+              `Wagon ${physicalWagon.wagonNumber} is at yard ${physicalWagon.currentYardId} but schedule originates from ${schedule.originStationId}`,
+            );
+          }
         }
 
+        // The pin lives ONLY on the schedule's slot — the Wagon entity keeps
+        // its status untouched so other schedules can still use the wagon.
         await manager.getRepository(TrainSetWagon).update(assignment.trainSetWagonId, {
           physicalWagonId: assignment.physicalWagonId,
           status: 'RESERVED',
         });
-        await manager.getRepository(Wagon).update(assignment.physicalWagonId, {
-          trainSetWagonId: assignment.trainSetWagonId,
-          currentTrainScheduleId: scheduleId,
-          status: WagonStatus.Assigned,
-        });
+        for (const [physicalId, slotId] of slotIdByPhysicalId) {
+          if (slotId === assignment.trainSetWagonId) {
+            slotIdByPhysicalId.delete(physicalId);
+            break;
+          }
+        }
+        slotIdByPhysicalId.set(assignment.physicalWagonId, assignment.trainSetWagonId);
       }
     });
 
@@ -1860,6 +1900,22 @@ export class TrainSchedulingService {
     // at a time — block dispatch while any set locomotive is out on a dispatched train.
     const setLocomotiveIds = this.locomotivesOfTrainSet(schedule.trainSet).map((l) => l.id);
     await this.assertLocomotivesNotDispatchedElsewhere(setLocomotiveIds, scheduleId);
+    // Same rule for wagons: many schedules may pin the same wagon, but it can
+    // only be OUT on one dispatched train at a time.
+    const pinnedPhysicalIds = (schedule.trainSet?.wagons ?? [])
+      .map((slot) => slot.physicalWagonId)
+      .filter((id): id is string => Boolean(id));
+    if (pinnedPhysicalIds.length) {
+      const rolling = await this.dataSource.getRepository(Wagon).find({
+        where: { id: In(pinnedPhysicalIds), currentTrainScheduleId: Not(IsNull()) },
+      });
+      const busy = rolling.filter((w) => w.currentTrainScheduleId !== scheduleId);
+      if (busy.length) {
+        throw new ConflictException(
+          `Cannot dispatch: wagon(s) ${busy.map((w) => w.wagonNumber).join(', ')} are still out on another dispatched train`,
+        );
+      }
+    }
 
     const now = new Date();
     await this.dataSource.transaction(async (manager) => {
@@ -3735,10 +3791,11 @@ export class TrainSchedulingService {
     originYardId: string,
     targetScheduleId?: string,
   ): Promise<Array<{ wagonTypeId: string; wagonTypeCode: string; available: number }>> {
-    const [wagons, wagonTypes, builtTrainId] = await Promise.all([
+    const [wagons, wagonTypes, builtTrainId, pinnedToTargetIds] = await Promise.all([
       this.dataSource.getRepository(Wagon).find(),
       this.dataSource.getRepository(WagonType).find(),
       this.builtTrainIdOfSchedule(targetScheduleId),
+      this.pinnedPhysicalWagonIdsForSchedule(targetScheduleId),
     ]);
     const typeCodeById = new Map(wagonTypes.map((type) => [type.id, type.code]));
     const counts = new Map<string, { code: string; available: number }>();
@@ -3750,10 +3807,20 @@ export class TrainSchedulingService {
       if (builtTrainId) {
         if (wagon.trainId !== builtTrainId) continue;
       } else {
-        const pinnedOnTarget = targetScheduleId
-          ? wagon.currentTrainScheduleId === targetScheduleId
-          : false;
-        if (wagon.status !== WagonStatus.Available && !pinnedOnTarget) continue;
+        // Schedule-scoped availability: pins held by OTHER schedules never
+        // consume a wagon here — the same physical wagon may serve the July 17
+        // and the July 20 run. A wagon is unusable only when it is coupled to a
+        // built train's consist, physically blocked, or out on a dispatched
+        // train right now.
+        const pinnedOnTarget = pinnedToTargetIds.has(wagon.id);
+        if (wagon.trainId) continue;
+        if (!this.isWagonPhysicallyUsable(wagon) && !pinnedOnTarget) continue;
+        if (
+          wagon.currentTrainScheduleId &&
+          wagon.currentTrainScheduleId !== targetScheduleId
+        ) {
+          continue;
+        }
         if (wagon.currentYardId !== originYardId) continue;
       }
 
@@ -3812,22 +3879,59 @@ export class TrainSchedulingService {
     };
   }
 
-  private async releasePinnedWagonsForTrainSet(manager: EntityManager, trainSetId: string) {
-    const slots = await manager.getRepository(TrainSetWagon).find({ where: { trainSetId } });
-    const physicalIds = slots
-      .map((slot) => slot.physicalWagonId)
-      .filter((id): id is string => Boolean(id));
-    if (!physicalIds.length) return;
-    const wagons = await manager.getRepository(Wagon).find({ where: { id: In(physicalIds) } });
-    for (const wagon of wagons) {
-      await manager.getRepository(Wagon).update(wagon.id, {
-        // Built-train wagons stay coupled to their train (ASSIGNED); loose
-        // wagons return to the open AVAILABLE pool.
-        status: wagon.trainId ? WagonStatus.Assigned : WagonStatus.Available,
-        trainSetWagonId: null,
-        currentTrainScheduleId: null,
-      });
-    }
+  /**
+   * A wagon in a blocked physical state can never be planned or pinned.
+   * ASSIGNED no longer blocks: it only means the wagon is coupled to a built
+   * train or stamped by a live run — schedule-level occupancy is tracked on
+   * the schedule's own TrainSetWagon slots, never on the Wagon entity.
+   */
+  private isWagonPhysicallyUsable(wagon: Wagon): boolean {
+    return (
+      wagon.status === WagonStatus.Available || wagon.status === WagonStatus.Assigned
+    );
+  }
+
+  /**
+   * Physical wagons already pinned to THIS schedule's slots. Availability is
+   * schedule-scoped: only a duplicate pin within the same schedule conflicts;
+   * pins held by other schedules of the same train are irrelevant.
+   */
+  private async pinnedPhysicalWagonIdsForSchedule(
+    scheduleId: string | undefined,
+    manager?: EntityManager,
+  ): Promise<Set<string>> {
+    if (!scheduleId) return new Set();
+    const runner = manager ?? this.dataSource;
+    const rows: { physical_wagon_id: string }[] = await runner.query(
+      `SELECT tsw.physical_wagon_id
+         FROM freight.train_set_wagons tsw
+         JOIN freight.train_schedules ts ON ts.train_set_id = tsw.train_set_id
+        WHERE ts.id = $1
+          AND ts.deleted_at IS NULL
+          AND tsw.deleted_at IS NULL
+          AND tsw.physical_wagon_id IS NOT NULL`,
+      [scheduleId],
+    );
+    return new Set(rows.map((row) => row.physical_wagon_id));
+  }
+
+  /**
+   * Physical wagons pinned to any slot of a live (DRAFT/SCHEDULED/DISPATCHED)
+   * schedule. Used to guard consist trims — the Wagon entity itself carries no
+   * schedule-occupancy state anymore.
+   */
+  private async wagonIdsPinnedToLiveSchedules(manager?: EntityManager): Promise<Set<string>> {
+    const runner = manager ?? this.dataSource;
+    const rows: { physical_wagon_id: string }[] = await runner.query(
+      `SELECT DISTINCT tsw.physical_wagon_id
+         FROM freight.train_set_wagons tsw
+         JOIN freight.train_schedules ts ON ts.train_set_id = tsw.train_set_id
+        WHERE ts.status IN ('DRAFT', 'SCHEDULED', 'DISPATCHED')
+          AND ts.deleted_at IS NULL
+          AND tsw.deleted_at IS NULL
+          AND tsw.physical_wagon_id IS NOT NULL`,
+    );
+    return new Set(rows.map((row) => row.physical_wagon_id));
   }
 
   private async autoPinWagonsForSchedule(
@@ -3839,6 +3943,10 @@ export class TrainSchedulingService {
     const wagons = await manager.getRepository(Wagon).find();
     const wagonTypes = await manager.getRepository(WagonType).find();
     const builtTrainId = await this.builtTrainIdOfSchedule(scheduleId, manager);
+    const pinnedToScheduleIds = await this.pinnedPhysicalWagonIdsForSchedule(
+      scheduleId,
+      manager,
+    );
     const typeCodeById = new Map(wagonTypes.map((wt) => [wt.id, wt.code]));
 
     const planSlots = [...slots]
@@ -3857,6 +3965,7 @@ export class TrainSchedulingService {
       scheduleId,
       originYardId,
       builtTrainId,
+      pinnedToScheduleIds,
     );
     if (unpinnable.length) {
       throw new BadRequestException({
@@ -3874,18 +3983,17 @@ export class TrainSchedulingService {
         originYardId,
         assignedPhysicalIds,
         builtTrainId,
+        pinnedToScheduleIds,
       );
       if (!physical) continue;
 
+      // Pin lives ONLY on the schedule's own slot — the Wagon entity is never
+      // touched here, so the same physical wagon stays free for every other
+      // schedule (it gets stamped at dispatch, when it physically leaves).
       await manager.getRepository(TrainSetWagon).update(slot.trainSetWagonId!, {
         physicalWagonId: physical.id,
         status: 'RESERVED',
       });
-      await manager.getRepository(Wagon).update(physical.id, {
-        trainSetWagonId: slot.trainSetWagonId,
-        currentTrainScheduleId: scheduleId,
-        status: WagonStatus.Assigned,
-      });
       assignedPhysicalIds.add(physical.id);
     }
   }
@@ -3898,9 +4006,10 @@ export class TrainSchedulingService {
   ): Promise<string[]> {
     if (!wagonPlan.length) return [];
 
-    const [wagons, builtTrainId] = await Promise.all([
+    const [wagons, builtTrainId, pinnedToScheduleIds] = await Promise.all([
       this.dataSource.getRepository(Wagon).find(),
       this.builtTrainIdOfSchedule(targetScheduleId),
+      this.pinnedPhysicalWagonIdsForSchedule(targetScheduleId),
     ]);
     return this.findUnpinnableWagonSlots(
       wagonPlan.map((slot) => ({
@@ -3913,6 +4022,7 @@ export class TrainSchedulingService {
       targetScheduleId,
       originYardId,
       builtTrainId,
+      pinnedToScheduleIds,
     );
   }
 
@@ -3927,6 +4037,7 @@ export class TrainSchedulingService {
     scheduleId: string | undefined,
     originYardId: string,
     builtTrainId: string | null = null,
+    pinnedToScheduleIds: Set<string> = new Set(),
   ): string[] {
     const violations: string[] = [];
     const assignedPhysicalIds = new Set<string>();
@@ -3939,6 +4050,7 @@ export class TrainSchedulingService {
         originYardId,
         assignedPhysicalIds,
         builtTrainId,
+        pinnedToScheduleIds,
       );
       if (!physical) {
         violations.push(
@@ -3964,14 +4076,22 @@ export class TrainSchedulingService {
     originYardId: string,
     assignedPhysicalIds: Set<string>,
     builtTrainId: string | null = null,
+    pinnedToScheduleIds: Set<string> = new Set(),
   ): Wagon | undefined {
     const usable = (wagon: Wagon): boolean => {
       if (wagon.wagonTypeId !== slot.wagonTypeId) return false;
       if (assignedPhysicalIds.has(wagon.id)) return false;
-      const pinnedOnSchedule = scheduleId
-        ? wagon.currentTrainScheduleId === scheduleId
-        : false;
-      return wagon.status === WagonStatus.Available || pinnedOnSchedule;
+      // Loose pool never lends a wagon coupled to a built train's consist.
+      if (wagon.trainId) return false;
+      // Out on a dispatched train right now — physically gone.
+      if (
+        wagon.currentTrainScheduleId &&
+        wagon.currentTrainScheduleId !== scheduleId
+      ) {
+        return false;
+      }
+      const pinnedOnSchedule = pinnedToScheduleIds.has(wagon.id);
+      return this.isWagonPhysicallyUsable(wagon) || pinnedOnSchedule;
     };
     // Train-bound schedule: ONLY the built train's own wagons may be pinned —
     // wherever they currently sit (they travel with the train), never a loose
@@ -4746,6 +4866,7 @@ export class TrainSchedulingService {
         .filter((slot) => slot.physicalWagonId && (slot.allocations?.length ?? 0) > 0)
         .map((slot) => slot.physicalWagonId as string),
     );
+    const pinnedToLiveIds = await this.wagonIdsPinnedToLiveSchedules();
 
     const limits = minLocomotiveLimits(this.locomotivesOfTrainSet(schedule.trainSet));
     const maxPullWeightTons = roundTons(Number(limits?.maxPullWeightTons ?? 0));
@@ -4802,8 +4923,8 @@ export class TrainSchedulingService {
       wagons: wagons.map((wagon) => ({
         ...mapWagon(wagon),
         loaded: loadedWagonIds.has(wagon.id),
-        // Free = not pinned to any run; only free wagons can be trimmed.
-        removable: wagon.currentTrainScheduleId == null && !loadedWagonIds.has(wagon.id),
+        // Free = not pinned to any live run's slot; only free wagons can be trimmed.
+        removable: !pinnedToLiveIds.has(wagon.id) && !loadedWagonIds.has(wagon.id),
       })),
       addableWagons: addableWagons.map(mapWagon),
       adjustments: adjustments.map((log) => ({
@@ -4882,13 +5003,14 @@ export class TrainSchedulingService {
       const consistById = new Map(consist.map((w) => [w.id, w]));
 
       // --- validate removals: must be coupled and free (no cargo, no pin) ---
+      const pinnedToLiveIds = await this.wagonIdsPinnedToLiveSchedules(manager);
       const removed: Wagon[] = [];
       for (const wagonId of removeWagonIds) {
         const wagon = consistById.get(wagonId);
         if (!wagon) {
           throw new NotFoundException(`Wagon ${wagonId} is not coupled to train ${train.code}`);
         }
-        if (loadedWagonIds.has(wagon.id) || wagon.currentTrainScheduleId != null) {
+        if (loadedWagonIds.has(wagon.id) || pinnedToLiveIds.has(wagon.id)) {
           throw new ConflictException(
             `Wagon ${wagon.wagonNumber} is loaded/pinned on a schedule and cannot be trimmed`,
           );
@@ -5369,10 +5491,10 @@ export class TrainSchedulingService {
   /**
    * Cargo-aware day pool: the EAT days a customer may pick for this cargo. A day
    * is selectable when ≥1 OPEN schedule on the route that day still has remaining
-   * train capacity (not fully allocated). Wagon availability is deliberately NOT
-   * checked here: whether a matching wagon currently sits in the right yard is an
-   * operational question staff resolve when they approve or reject the booking,
-   * not something the customer can act on while choosing a date. Same
+   * train capacity (not fully allocated) AND its wagon stock can physically carry
+   * the selected cargo/container type (wagon-TYPE gate). Quantity is deliberately
+   * NOT gated — a booking bigger than the free capacity is accepted and the batch
+   * engine offers a partial split later. No counts are exposed: same
    * `{ days: string[] }` shape as getAvailableDays — the customer picks a DAY,
    * not a train.
    */
@@ -5380,9 +5502,11 @@ export class TrainSchedulingService {
     originYardId?: string;
     destinationYardId?: string;
     freightType: 'CONTAINER' | 'BULK';
+    cargoTypeId?: string | null;
     cargoTypeCode?: string | null;
     totalWeightTons?: number;
     containers?: Array<{ containerSize: string; quantity: number }>;
+    containerTypeIds?: string[];
   }): Promise<{ days: string[] }> {
     const schedules = await this.getBookableScheduleEntities(
       input.originYardId,
@@ -5390,17 +5514,233 @@ export class TrainSchedulingService {
     );
     if (schedules.length === 0) return { days: [] };
 
+    const withCapacity = schedules.filter(
+      (s) => Math.max(0, (s.maxWagons ?? 0) - (s.trainSet?.wagonCount ?? 0)) > 0,
+    );
+    const compatible = await this.filterCargoCompatibleSchedules(withCapacity, input);
+
     const days = new Set<string>();
-    for (const s of schedules) {
-      const hasCapacity =
-        Math.max(0, (s.maxWagons ?? 0) - (s.trainSet?.wagonCount ?? 0)) > 0;
-      if (!hasCapacity) continue;
+    for (const s of compatible) {
       if (s.scheduledDepartureDate)
         days.add(eatDay(new Date(s.scheduledDepartureDate)));
     }
     return { days: [...days].sort() };
   }
 
+  /**
+   * Wagon-TYPE compatibility gate (customer booking): keep only the schedules
+   * whose wagon stock can physically carry the selected cargo — every container
+   * line (or the bulk cargo type) must map to at least one wagon type the
+   * schedule's stock actually has. Stock = the built train's own consist, or the
+   * origin yard's loose pool for schedules assembled from loose locomotives.
+   * QUANTITY is deliberately ignored: an over-sized booking is allowed and gets
+   * a partial split offer from the batch engine later.
+   */
+  private async filterCargoCompatibleSchedules(
+    schedules: TrainSchedule[],
+    cargo: {
+      freightType: 'CONTAINER' | 'BULK';
+      cargoTypeId?: string | null;
+      cargoTypeCode?: string | null;
+      containers?: Array<{ containerSize: string; quantity: number }>;
+      containerTypeIds?: string[];
+    },
+  ): Promise<TrainSchedule[]> {
+    if (!schedules.length) return schedules;
+    const required = await this.requiredWagonTypeSets(cargo);
+    // No cargo identity supplied — nothing to gate on (legacy callers).
+    if (required === null) return schedules;
+
+    const stockByScheduleId = await this.scheduleWagonTypeStock(schedules);
+    return schedules.filter((s) => {
+      const stock = stockByScheduleId.get(s.id) ?? new Set<string>();
+      return required.every((set) => {
+        for (const typeId of set) if (stock.has(typeId)) return true;
+        return false;
+      });
+    });
+  }
+
+  /**
+   * One Set of allowed wagon-type ids per required cargo dimension: per
+   * container line's type (or per container size when only sizes are known),
+   * or a single set for the bulk cargo type. `null` = no cargo identity given,
+   * skip gating. An EMPTY set means "nothing can carry this" (no wagon types
+   * configured) — the gate then blocks every schedule, mirroring the hard
+   * config violation scheduling raises for the same state.
+   */
+  private async requiredWagonTypeSets(cargo: {
+    freightType: 'CONTAINER' | 'BULK';
+    cargoTypeId?: string | null;
+    cargoTypeCode?: string | null;
+    containers?: Array<{ containerSize: string; quantity: number }>;
+    containerTypeIds?: string[];
+  }): Promise<Set<string>[] | null> {
+    if (cargo.freightType === 'CONTAINER') {
+      const typeIds = [...new Set((cargo.containerTypeIds ?? []).filter(Boolean))];
+      if (typeIds.length) {
+        const rows: { container_type_id: string; wagon_type_id: string | null }[] =
+          await this.dataSource.query(
+            `SELECT ct.id AS container_type_id, wt.id AS wagon_type_id
+               FROM freight.container_types ct
+               LEFT JOIN freight.container_type_wagon_types ctwt ON ctwt.container_type_id = ct.id
+               LEFT JOIN freight.wagon_types wt
+                 ON wt.id = ctwt.wagon_type_id AND wt.deleted_at IS NULL AND wt.is_active = true
+              WHERE ct.id = ANY($1::uuid[]) AND ct.deleted_at IS NULL`,
+            [typeIds],
+          );
+        const byType = new Map<string, Set<string>>(typeIds.map((id) => [id, new Set()]));
+        for (const row of rows) {
+          if (row.wagon_type_id) byType.get(row.container_type_id)?.add(row.wagon_type_id);
+        }
+        return [...byType.values()];
+      }
+      // Legacy callers only know sizes ("20ft"/"40ft"): a size is carriable when
+      // ANY active container type of that size has a matching wagon type.
+      const sizes = [
+        ...new Set(
+          (cargo.containers ?? [])
+            .map((line) => parseInt(String(line.containerSize), 10))
+            .filter((n) => Number.isFinite(n) && n > 0),
+        ),
+      ];
+      if (!sizes.length) return null;
+      const rows: { size_ft: number; wagon_type_id: string | null }[] =
+        await this.dataSource.query(
+          `SELECT ct.size_ft, wt.id AS wagon_type_id
+             FROM freight.container_types ct
+             LEFT JOIN freight.container_type_wagon_types ctwt ON ctwt.container_type_id = ct.id
+             LEFT JOIN freight.wagon_types wt
+               ON wt.id = ctwt.wagon_type_id AND wt.deleted_at IS NULL AND wt.is_active = true
+            WHERE ct.size_ft = ANY($1::int[]) AND ct.deleted_at IS NULL
+              AND (ct.is_active IS DISTINCT FROM false)`,
+          [sizes],
+        );
+      const bySize = new Map<number, Set<string>>(sizes.map((s) => [s, new Set()]));
+      for (const row of rows) {
+        if (row.wagon_type_id) bySize.get(Number(row.size_ft))?.add(row.wagon_type_id);
+      }
+      return [...bySize.values()];
+    }
+
+    if (!cargo.cargoTypeId && !cargo.cargoTypeCode) return null;
+    const rows: { wagon_type_id: string | null }[] = await this.dataSource.query(
+      `SELECT wt.id AS wagon_type_id
+         FROM freight.cargo_types c
+         LEFT JOIN freight.cargo_type_wagon_types ctwt ON ctwt.cargo_type_id = c.id
+         LEFT JOIN freight.wagon_types wt
+           ON wt.id = ctwt.wagon_type_id AND wt.deleted_at IS NULL AND wt.is_active = true
+        WHERE c.deleted_at IS NULL
+          AND (($1::uuid IS NOT NULL AND c.id = $1::uuid) OR ($1::uuid IS NULL AND c.code = $2))`,
+      [cargo.cargoTypeId ?? null, cargo.cargoTypeCode ?? null],
+    );
+    const set = new Set<string>();
+    for (const row of rows) if (row.wagon_type_id) set.add(row.wagon_type_id);
+    return [set];
+  }
+
+  /**
+   * Wagon-type ids each schedule's stock can offer: the built train's own
+   * consist for train-bound schedules, the origin yard's loose usable pool
+   * otherwise. Batched — two queries for the whole schedule list.
+   */
+  private async scheduleWagonTypeStock(
+    schedules: TrainSchedule[],
+  ): Promise<Map<string, Set<string>>> {
+    const builtTrainIds = [
+      ...new Set(
+        schedules
+          .map((s) => s.trainSet?.trainId)
+          .filter((id): id is string => Boolean(id)),
+      ),
+    ];
+    const looseOriginYardIds = [
+      ...new Set(
+        schedules
+          .filter((s) => !s.trainSet?.trainId)
+          .map((s) => s.originStationId)
+          .filter(Boolean),
+      ),
+    ];
+
+    const [trainRows, yardRows] = await Promise.all([
+      builtTrainIds.length
+        ? (this.dataSource.query(
+            `SELECT train_id, wagon_type_id
+               FROM freight.wagons
+              WHERE train_id = ANY($1::uuid[]) AND deleted_at IS NULL
+              GROUP BY train_id, wagon_type_id`,
+            [builtTrainIds],
+          ) as Promise<{ train_id: string; wagon_type_id: string }[]>)
+        : Promise.resolve([] as { train_id: string; wagon_type_id: string }[]),
+      looseOriginYardIds.length
+        ? (this.dataSource.query(
+            `SELECT current_yard_id, wagon_type_id
+               FROM freight.wagons
+              WHERE train_id IS NULL AND deleted_at IS NULL
+                AND status IN ('AVAILABLE', 'ASSIGNED')
+                AND current_yard_id = ANY($1::uuid[])
+              GROUP BY current_yard_id, wagon_type_id`,
+            [looseOriginYardIds],
+          ) as Promise<{ current_yard_id: string; wagon_type_id: string }[]>)
+        : Promise.resolve([] as { current_yard_id: string; wagon_type_id: string }[]),
+    ]);
+
+    const byTrain = new Map<string, Set<string>>();
+    for (const row of trainRows) {
+      const set = byTrain.get(row.train_id) ?? new Set<string>();
+      set.add(row.wagon_type_id);
+      byTrain.set(row.train_id, set);
+    }
+    const byYard = new Map<string, Set<string>>();
+    for (const row of yardRows) {
+      const set = byYard.get(row.current_yard_id) ?? new Set<string>();
+      set.add(row.wagon_type_id);
+      byYard.set(row.current_yard_id, set);
+    }
+
+    const result = new Map<string, Set<string>>();
+    for (const s of schedules) {
+      const trainId = s.trainSet?.trainId;
+      result.set(
+        s.id,
+        trainId
+          ? byTrain.get(trainId) ?? new Set()
+          : byYard.get(s.originStationId) ?? new Set(),
+      );
+    }
+    return result;
+  }
+
+  /**
+   * Booking-time gate for a chosen day: does the route have an OPEN departure
+   * that day at all, and can any of that day's departures physically carry the
+   * cargo (wagon-TYPE only — quantity never blocks, oversized bookings get a
+   * partial split offer instead).
+   */
+  async checkDayCargoCompatibility(
+    originYardId: string,
+    destinationYardId: string,
+    day: string,
+    cargo: {
+      freightType: 'CONTAINER' | 'BULK';
+      cargoTypeId?: string | null;
+      containerTypeIds?: string[];
+    },
+  ): Promise<{ hasDeparture: boolean; hasCompatible: boolean }> {
+    const schedules = await this.getBookableScheduleEntities(
+      originYardId,
+      destinationYardId,
+    );
+    const onDay = schedules.filter(
+      (s) =>
+        s.scheduledDepartureDate && eatDay(new Date(s.scheduledDepartureDate)) === day,
+    );
+    if (!onDay.length) return { hasDeparture: false, hasCompatible: false };
+    const compatible = await this.filterCargoCompatibleSchedules(onDay, cargo);
+    return { hasDeparture: true, hasCompatible: compatible.length > 0 };
+  }
+
   /**
    * Ordered stop yards of a schedule's route: origin → milestones → destination,
    * de-duplicated. Falls back to the two-endpoint pseudo-route when the schedule
@@ -5553,6 +5893,7 @@ export class TrainSchedulingService {
       status: schedule.status,
       freightType: this.resolveScheduleFreightType(schedule),
       trainNumber: schedule.trainNumber ?? null,
+      maxWagons: schedule.maxWagons ?? null,
       direction: schedule.direction ?? null,
       requiresLoadingConfirmation,
       loadingConfirmed,

apps/edr-freight-api/src/modules/trains/train-builder.service.ts

@@ -399,7 +399,7 @@ export class TrainBuilderService {
       if (!wagon || wagon.trainId !== train.id) {
         throw new NotFoundException(`Wagon ${wagonId} is not part of this train`);
       }
-      if (wagon.currentTrainScheduleId) {
+      if (await this.isWagonPinnedToLiveSchedule(manager, wagon.id)) {
         throw new ConflictException(
           `Wagon ${wagon.wagonNumber} is pinned to an active schedule and cannot be removed`,
         );
@@ -426,7 +426,7 @@ export class TrainBuilderService {
       if (!wagon || wagon.trainId !== train.id) {
         throw new NotFoundException(`Wagon ${wagonId} is not part of this train`);
       }
-      if (wagon.currentTrainScheduleId) {
+      if (await this.isWagonPinnedToLiveSchedule(manager, wagon.id)) {
         throw new ConflictException(
           `Wagon ${wagon.wagonNumber} is pinned to an active schedule and cannot be removed`,
         );
@@ -441,6 +441,29 @@ export class TrainBuilderService {
     return this.getComposition(id);
   }
 
+  /**
+   * Schedule occupancy lives on TrainSetWagon slots (per-schedule snapshot),
+   * not on the Wagon entity — a wagon is busy when any live (DRAFT/SCHEDULED/
+   * DISPATCHED) schedule has it pinned to one of its slots.
+   */
+  private async isWagonPinnedToLiveSchedule(
+    manager: EntityManager,
+    wagonId: string,
+  ): Promise<boolean> {
+    const rows: { exists: boolean }[] = await manager.query(
+      `SELECT TRUE AS exists
+         FROM freight.train_set_wagons tsw
+         JOIN freight.train_schedules ts ON ts.train_set_id = tsw.train_set_id
+        WHERE tsw.physical_wagon_id = $1
+          AND ts.status IN ('DRAFT', 'SCHEDULED', 'DISPATCHED')
+          AND ts.deleted_at IS NULL
+          AND tsw.deleted_at IS NULL
+        LIMIT 1`,
+      [wagonId],
+    );
+    return rows.length > 0;
+  }
+
   /** Persist a drag-reorder: `wagonIds` is the full consist in its new order. */
   async reorderWagons(id: string, dto: ReorderTrainWagonsDto) {
     await this.dataSource.transaction(async (manager) => {

apps/edr-freight-api/src/modules/wagons/dto/bulk-fulfill-transfer-requests.dto.ts

@@ -0,0 +1,13 @@
+import { ArrayMaxSize, ArrayMinSize, IsArray, IsUUID } from 'class-validator';
+
+/**
+ * OCC bulk accept-and-execute: the subset of PENDING request ids to execute
+ * now. Requests not listed (or that cannot be executed) stay PENDING.
+ */
+export class BulkFulfillTransferRequestsDto {
+  @IsArray()
+  @ArrayMinSize(1)
+  @ArrayMaxSize(200)
+  @IsUUID('all', { each: true })
+  requestIds!: string[];
+}

apps/edr-freight-api/src/modules/wagons/dto/create-transfer-request.dto.ts

@@ -1,10 +1,20 @@
-import { ApiPropertyOptional } from '@nestjs/swagger';
-import { IsInt, IsOptional, IsString, IsUUID, Max, Min } from 'class-validator';
+import { ApiProperty, ApiPropertyOptional } from '@nestjs/swagger';
+import {
+  IsInt,
+  IsNotEmpty,
+  IsOptional,
+  IsString,
+  IsUUID,
+  Max,
+  MaxLength,
+  Min,
+} from 'class-validator';
 
 /**
  * A count-only wagon-transfer request. The requester picks source yard, wagon
  * type, destination yard and HOW MANY — never the specific wagons; OCC hand-picks
- * those at fulfilment.
+ * those at fulfilment. The quantity may not exceed the AVAILABLE wagons of that
+ * type currently in the source yard, and a reason is mandatory.
  */
 export class CreateTransferRequestDto {
   @IsUUID()
@@ -21,6 +31,12 @@ export class CreateTransferRequestDto {
   @Max(1000)
   quantity!: number;
 
+  @ApiProperty({ description: 'Why the wagons are needed — shown on the OCC queue' })
+  @IsString()
+  @IsNotEmpty()
+  @MaxLength(2000)
+  reason!: string;
+
   @ApiPropertyOptional({ description: 'Optional note for the fulfilling staff' })
   @IsOptional()
   @IsString()

apps/edr-freight-api/src/modules/wagons/entities/wagon-transfer-request.entity.ts

@@ -59,4 +59,11 @@ export class WagonTransferRequest extends BaseEntity {
 
   @Column({ name: 'note', type: 'text', nullable: true })
   note?: string | null;
+
+  /**
+   * Why the wagons are needed — required for every new request and shown on
+   * the OCC queue. Nullable only for rows that predate the requirement.
+   */
+  @Column({ name: 'reason', type: 'text', nullable: true })
+  reason?: string | null;
 }

apps/edr-freight-api/src/modules/wagons/entities/wagon.entity.ts

@@ -15,7 +15,7 @@ export const WAGON_STATUSES = [
   WagonStatus.ImportReady,
   WagonStatus.ExportReady,
   WagonStatus.Maintenance,
-  WagonStatus.Retired,
+  WagonStatus.Detained,
 ] as const;
 
 export type WagonStatusType = (typeof WAGON_STATUSES)[number];

apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.controller.ts

@@ -19,6 +19,7 @@ import {
   WagonTransferHistoryAll,
   WagonTransferRequest,
 } from '../../common/booking-guards';
+import { BulkFulfillTransferRequestsDto } from './dto/bulk-fulfill-transfer-requests.dto';
 import { CreateTransferRequestDto } from './dto/create-transfer-request.dto';
 import { FulfillTransferRequestDto } from './dto/fulfill-transfer-request.dto';
 import { WagonTransferRequestsService } from './wagon-transfer-requests.service';
@@ -51,6 +52,22 @@ export class WagonTransferRequestsController {
     return this.service.listRequests(status);
   }
 
+  // NOTE: static routes (`history`, `bulk-fulfill`) MUST stay above `@Get(':id')`
+  // — Express matches in declaration order, so they would otherwise be captured
+  // by the `:id` param route (and rejected by ParseUUIDPipe).
+  @Post('bulk-fulfill')
+  @WagonTransferFulfill()
+  @ApiOperation({
+    summary:
+      'OCC: accept-and-execute a subset of pending requests (auto-picks available wagons; the rest stay PENDING)',
+  })
+  bulkFulfill(
+    @Body() dto: BulkFulfillTransferRequestsDto,
+    @CurrentUser() user: TCurrentUser,
+  ) {
+    return this.service.bulkFulfill(dto.requestIds, user?.id);
+  }
+
   // NOTE: the two `history` routes MUST stay above `@Get(':id')` — Express
   // matches in declaration order, so `/history` would otherwise be captured by
   // the `:id` param route (and rejected by ParseUUIDPipe).

apps/edr-freight-api/src/modules/wagons/wagon-transfer-requests.service.ts

@@ -1,4 +1,4 @@
-import { WagonTransferRequestStatus } from '@edr/types';
+import { WagonStatus, WagonTransferRequestStatus } from '@edr/types';
 import {
   BadRequestException,
   ConflictException,
@@ -48,7 +48,12 @@ export class WagonTransferRequestsService {
     private readonly wagonsService: WagonsService,
   ) {}
 
-  /** Record a PENDING request. Count-only — no wagons are picked here. */
+  /**
+   * Record a PENDING request. Count-only — no wagons are picked here, but the
+   * count is capped at the AVAILABLE wagons of that type currently sitting in
+   * the source yard: staff may only ask for wagons that are actually there to
+   * give. A reason is mandatory and is shown on the OCC queue.
+   */
   async createRequest(
     dto: CreateTransferRequestDto,
     userId?: string | null,
@@ -58,6 +63,14 @@ export class WagonTransferRequestsService {
         'Source and destination yard must be different',
       );
     }
+    const available = await this.countAvailable(dto.fromYardId, dto.wagonTypeId);
+    if (available < dto.quantity) {
+      throw new BadRequestException(
+        available === 0
+          ? 'No available wagons of this type in the source yard'
+          : `Only ${available} available wagon(s) of this type in the source yard — request at most ${available}`,
+      );
+    }
     const request = this.requestRepo.create({
       fromYardId: dto.fromYardId,
       toYardId: dto.toYardId,
@@ -65,12 +78,24 @@ export class WagonTransferRequestsService {
       quantity: dto.quantity,
       status: WagonTransferRequestStatus.Pending,
       requestedByUserId: userId ?? null,
+      reason: dto.reason,
       note: dto.note ?? null,
     });
     const saved = await this.requestRepo.save(request);
     return this.findById(saved.id);
   }
 
+  /** AVAILABLE wagons of `wagonTypeId` currently in `yardId`. */
+  private countAvailable(yardId: string, wagonTypeId: string): Promise<number> {
+    return this.wagonRepo.count({
+      where: {
+        currentYardId: yardId,
+        wagonTypeId,
+        status: WagonStatus.Available,
+      },
+    });
+  }
+
   /** Requests, newest first, optionally filtered by status (OCC queue = PENDING). */
   async listRequests(
     status?: WagonTransferRequestStatus,
@@ -136,6 +161,14 @@ export class WagonTransferRequestsService {
           .join(', ')}`,
       );
     }
+    const notAvailable = wagons.filter((w) => w.status !== WagonStatus.Available);
+    if (notAvailable.length) {
+      throw new BadRequestException(
+        `These wagons are not available: ${notAvailable
+          .map((w) => w.wagonNumber)
+          .join(', ')}`,
+      );
+    }
 
     // Reuse the audited bulk-transfer path (writes wagon_movements ledger rows,
     // each stamped with this request's id so history can link them back).
@@ -152,6 +185,71 @@ export class WagonTransferRequestsService {
     return this.findById(id);
   }
 
+  /**
+   * OCC accepts AND executes a subset of pending requests in one action. For
+   * each selected request the system auto-picks the required number of
+   * AVAILABLE wagons of the requested type from the source yard (lowest wagon
+   * number first) and runs the audited transfer. A request that cannot be
+   * executed — already decided, or not enough available wagons left after the
+   * ones processed before it — is SKIPPED and simply stays PENDING, visible to
+   * both teams; nothing is rolled back for the others.
+   */
+  async bulkFulfill(
+    requestIds: string[],
+    userId?: string | null,
+  ): Promise<{
+    fulfilled: WagonTransferRequest[];
+    skipped: Array<{ id: string; reason: string }>;
+  }> {
+    const fulfilled: WagonTransferRequest[] = [];
+    const skipped: Array<{ id: string; reason: string }> = [];
+
+    // Sequential on purpose: each executed transfer moves wagons out of the
+    // source yard, and the next request's auto-pick must see that new state.
+    for (const id of [...new Set(requestIds)]) {
+      const request = await this.requestRepo.findOne({ where: { id } });
+      if (!request) {
+        skipped.push({ id, reason: 'Request not found' });
+        continue;
+      }
+      if (request.status !== WagonTransferRequestStatus.Pending) {
+        skipped.push({
+          id,
+          reason: `Already ${request.status.toLowerCase()}`,
+        });
+        continue;
+      }
+      const wagons = await this.wagonRepo.find({
+        where: {
+          currentYardId: request.fromYardId,
+          wagonTypeId: request.wagonTypeId,
+          status: WagonStatus.Available,
+        },
+        order: { wagonNumber: 'ASC' },
+        take: request.quantity,
+      });
+      if (wagons.length < request.quantity) {
+        skipped.push({
+          id,
+          reason: `Only ${wagons.length} of ${request.quantity} wagon(s) available in the source yard — left pending`,
+        });
+        continue;
+      }
+      await this.wagonsService.bulkTransfer(
+        { wagonIds: wagons.map((w) => w.id), toYardId: request.toYardId },
+        userId,
+        { transferRequestId: request.id },
+      );
+      request.status = WagonTransferRequestStatus.Fulfilled;
+      request.fulfilledByUserId = userId ?? null;
+      request.fulfilledAt = new Date();
+      await this.requestRepo.save(request);
+      fulfilled.push(await this.findById(id));
+    }
+
+    return { fulfilled, skipped };
+  }
+
   /**
    * Per-user transfer history: the requests a user filed OR fulfilled, plus the
    * individual wagons they physically moved (linked back to their request when

apps/edr-freight-api/src/modules/warehouses/scheduling-read.facade.ts

@@ -144,7 +144,7 @@ export class SchedulingReadFacade {
       `SELECT id, wagon_number AS "wagonNumber", status, train_id AS "trainId"
        FROM freight.wagons
        WHERE deleted_at IS NULL
-         AND UPPER(status) NOT IN ('RETIRED', 'MAINTENANCE')
+         AND UPPER(status) NOT IN ('DETAINED', 'MAINTENANCE')
        ORDER BY wagon_number ASC`,
     );
   }

apps/edr-freight-web/backoffice/src/components/contracts/ContractActionsToolbar.tsx

@@ -1,19 +1,13 @@
-import { useEffect, useMemo, useState } from "react";
+import { useMemo, useState } from "react";
 import { useNavigate } from "react-router-dom";
 import { useQuery } from "@tanstack/react-query";
-import {
-  Anchor,
-  Button,
-  Modal,
-  Select,
-  Stack,
-  Text,
-  Textarea,
-} from "@mantine/core";
+import { Button, Modal, Stack, Text, Textarea } from "@mantine/core";
 import {
   Check,
+  FilePen,
   FileSignature,
   MessageSquareWarning,
+  RefreshCw,
   ShieldCheck,
   Sparkles,
   XCircle,
@@ -23,6 +17,7 @@ import type { Freight } from "@edr/types";
 
 import { api } from "@/services/api";
 import { SectionCard } from "@/components/bookings/detail/SectionCard";
+import { ContractDocumentEditorModal } from "@/components/contracts/ContractDocumentEditorModal";
 import type { useContractMutations } from "@/hooks/contracts/useContracts";
 
 /** Dropdown-settings code holding the admin-configured contract validity days. */
@@ -54,8 +49,8 @@ export function ContractActionsToolbar({
   const navigate = useNavigate();
   const { status } = contract;
 
-  const [acceptOpen, setAcceptOpen] = useState(false);
-  const [validityDays, setValidityDays] = useState<string | null>(null);
+  const [editorOpen, setEditorOpen] = useState(false);
+  const [editorMode, setEditorMode] = useState<"accept" | "edit">("accept");
   const [changesOpen, setChangesOpen] = useState(false);
   const [changesNote, setChangesNote] = useState("");
   const [rejectOpen, setRejectOpen] = useState(false);
@@ -76,12 +71,6 @@ export function ContractActionsToolbar({
         .map((o) => ({ value: String(o.value), label: o.label })),
     [validitySetting],
   );
-  // Default the selection to the first configured option when the dialog opens.
-  useEffect(() => {
-    if (acceptOpen && !validityDays && validityOptions.length > 0) {
-      setValidityDays(validityOptions[0].value);
-    }
-  }, [acceptOpen, validityDays, validityOptions]);
 
   if (["REJECTED", "CANCELLED", "EXPIRED", "CONTRACT_CLOSED"].includes(status)) {
     return null;
@@ -98,10 +87,16 @@ export function ContractActionsToolbar({
   }
 
   const canAccept = status === "SUBMITTED";
-  // Generation only becomes available once EVERY approval step is complete and
-  // the contract reaches APPROVED. While any step is still pending the contract
-  // stays in PENDING_APPROVAL, so this button does not appear after only the
-  // first (line-staff) approval — the director step must land first.
+  // While the contract is PENDING_APPROVAL and NO approver has acted yet, staff
+  // can edit this contract's articles and (re)generate its PDF. The first
+  // approval action locks the document.
+  const docLocked =
+    status !== "PENDING_APPROVAL" ||
+    (contract.approvalSteps ?? []).some((s) => s.status !== "PENDING");
+  const canEditGenerate = status === "PENDING_APPROVAL" && !docLocked;
+  const documentGenerated = Boolean(contract.contractGeneratedAt);
+  // Legacy fallback: if a contract ever lands on APPROVED without a document
+  // (older flow), still offer a manual generate that moves it to CONTRACT_READY.
   const needsManualGenerate =
     status === "APPROVED" && !contract.contractGeneratedAt;
   // Signing now happens on the contract VIEW page (staff must open and read the
@@ -131,7 +126,10 @@ export function ContractActionsToolbar({
               fullWidth
               color="edr-green"
               leftSection={<Check size={16} />}
-              onClick={() => setAcceptOpen(true)}
+              onClick={() => {
+                setEditorMode("accept");
+                setEditorOpen(true);
+              }}
             >
               Accept for approval
             </Button>
@@ -156,6 +154,43 @@ export function ContractActionsToolbar({
           </>
         )}
 
+        {canEditGenerate && (
+          <>
+            <Text size="xs" c="dimmed">
+              {documentGenerated
+                ? "Document generated. Approvers can now review it. You can still edit and regenerate until the first approval."
+                : "Review the contract document, edit its articles if needed, then generate it so approvers can review."}
+            </Text>
+            <Button
+              fullWidth
+              variant="light"
+              color="gray"
+              leftSection={<FilePen size={16} />}
+              onClick={() => {
+                setEditorMode("edit");
+                setEditorOpen(true);
+              }}
+            >
+              Edit contract articles
+            </Button>
+            <Button
+              fullWidth
+              color="edr-green"
+              leftSection={
+                documentGenerated ? (
+                  <RefreshCw size={16} />
+                ) : (
+                  <Sparkles size={16} />
+                )
+              }
+              loading={mutations.generateContract.isPending}
+              onClick={() => mutations.generateContract.mutate()}
+            >
+              {documentGenerated ? "Regenerate contract" : "Generate contract"}
+            </Button>
+          </>
+        )}
+
         {needsManualGenerate && (
           <Button
             fullWidth
@@ -198,6 +233,7 @@ export function ContractActionsToolbar({
             the customer creates the booking in the portal. */}
 
         {!canAccept &&
+          !canEditGenerate &&
           !needsManualGenerate &&
           !canViewContract &&
           !canReviewClearance && (
@@ -208,62 +244,28 @@ export function ContractActionsToolbar({
           )}
       </Stack>
 
-      {/* Accept — sets the contract validity window */}
-      <Modal
-        opened={acceptOpen}
-        onClose={() => setAcceptOpen(false)}
-        title="Accept contract for approval"
-        centered
-      >
-        <Stack gap="md">
-          <Text size="sm" c="dimmed">
-            Pick the contract validity window, then start the approval chain.
-          </Text>
-          {validityOptions.length > 0 ? (
-            <Select
-              label="Validity"
-              placeholder="Select a validity period"
-              data={validityOptions}
-              value={validityDays}
-              onChange={setValidityDays}
-              allowDeselect={false}
-              comboboxProps={{ withinPortal: true }}
-            />
-          ) : (
-            <Text size="sm" c="orange.7">
-              {validityLoading
-                ? "Loading validity periods…"
-                : "No validity periods are configured yet. Add them under "}
-              {!validityLoading && (
-                <Anchor
-                  href="/dashboard/dropdown-settings"
-                  onClick={(e) => {
-                    e.preventDefault();
-                    navigate("/dashboard/dropdown-settings");
-                  }}
-                >
-                  Dropdown Settings
-                </Anchor>
-              )}
-              {!validityLoading && "."}
-            </Text>
-          )}
-          <Button
-            color="edr-green"
-            loading={mutations.staffAccept.isPending}
-            disabled={!validityDays}
-            onClick={() => {
-              const days = Number(validityDays);
-              if (!days) return;
-              mutations.staffAccept.mutate(days, {
-                onSuccess: () => setAcceptOpen(false),
-              });
-            }}
-          >
-            Accept
-          </Button>
-        </Stack>
-      </Modal>
+      {/* Accept / edit — review + optionally edit this contract's articles */}
+      <ContractDocumentEditorModal
+        opened={editorOpen}
+        onClose={() => setEditorOpen(false)}
+        contractId={contract.id}
+        mode={editorMode}
+        validityOptions={validityOptions}
+        validityLoading={validityLoading}
+        accepting={mutations.staffAccept.isPending}
+        saving={mutations.updateDocument.isPending}
+        onAccept={(days, snapshot) =>
+          mutations.staffAccept.mutate(
+            { validityDays: days, documentSnapshot: snapshot },
+            { onSuccess: () => setEditorOpen(false) },
+          )
+        }
+        onSaveEdit={(snapshot) =>
+          mutations.updateDocument.mutate(snapshot, {
+            onSuccess: () => setEditorOpen(false),
+          })
+        }
+      />
 
       {/* Request changes */}
       <Modal

apps/edr-freight-web/backoffice/src/components/contracts/ContractDocumentEditorModal.tsx

@@ -0,0 +1,413 @@
+import { useEffect, useMemo, useState } from "react";
+import { useQuery } from "@tanstack/react-query";
+import {
+  ActionIcon,
+  Alert,
+  Box,
+  Button,
+  Divider,
+  Group,
+  Loader,
+  Modal,
+  Select,
+  Stack,
+  Text,
+  Textarea,
+  TextInput,
+  Tooltip,
+} from "@mantine/core";
+import {
+  ArrowDown,
+  ArrowUp,
+  FileText,
+  Info,
+  Lock,
+  Plus,
+  Trash2,
+} from "lucide-react";
+import type { Freight } from "@edr/types";
+
+import { contractsService } from "@/services/contracts.service";
+
+/** New client-side article id (server keeps whatever id we send). */
+function newArticleId(): string {
+  const c = globalThis.crypto;
+  if (c && typeof c.randomUUID === "function") return c.randomUUID();
+  return `art-${Date.now()}-${Math.floor(Math.random() * 1e6)}`;
+}
+
+interface EditableArticle {
+  id: string;
+  title: string;
+  body: string;
+}
+
+export interface ContractDocumentEditorModalProps {
+  opened: boolean;
+  onClose: () => void;
+  contractId: string;
+  /**
+   * "accept" — shown from the Accept-for-approval action: pick a validity window
+   * and (optionally) edit the articles, then start the approval chain.
+   * "edit" — re-edit the frozen articles of an already-accepted contract before
+   * generating/regenerating its PDF.
+   */
+  mode: "accept" | "edit";
+  /** Validity options (accept mode only). */
+  validityOptions?: Array<{ value: string; label: string }>;
+  validityLoading?: boolean;
+  accepting?: boolean;
+  saving?: boolean;
+  onAccept?: (
+    validityDays: number,
+    snapshot: Freight.IContractDocumentSnapshot,
+  ) => void;
+  onSaveEdit?: (snapshot: Freight.IContractDocumentSnapshot) => void;
+}
+
+/**
+ * Per-contract contract-document editor. Loads the resolved template (or this
+ * contract's frozen snapshot) and lets staff add/remove/reorder/edit articles
+ * for THIS contract only — it never writes back to the shared six templates.
+ */
+export function ContractDocumentEditorModal({
+  opened,
+  onClose,
+  contractId,
+  mode,
+  validityOptions = [],
+  validityLoading = false,
+  accepting = false,
+  saving = false,
+  onAccept,
+  onSaveEdit,
+}: ContractDocumentEditorModalProps) {
+  const { data: draft, isLoading } = useQuery({
+    queryKey: ["contracts", contractId, "document-draft"],
+    queryFn: () => contractsService.getContractDocumentDraft(contractId),
+    enabled: opened && Boolean(contractId),
+    // Always refetch the current draft when the dialog opens.
+    staleTime: 0,
+  });
+
+  const [documentTitle, setDocumentTitle] = useState("");
+  const [whereasClauses, setWhereasClauses] = useState<string[]>([]);
+  const [articles, setArticles] = useState<EditableArticle[]>([]);
+  const [validityDays, setValidityDays] = useState<string | null>(null);
+
+  // Seed the editor from the loaded draft whenever the dialog (re)opens.
+  useEffect(() => {
+    if (!opened || !draft) return;
+    setDocumentTitle(draft.documentTitle ?? "");
+    setWhereasClauses(draft.whereasClauses ?? []);
+    setArticles(
+      (draft.articles ?? []).map((a) => ({
+        id: a.id || newArticleId(),
+        title: a.title,
+        body: a.body,
+      })),
+    );
+  }, [opened, draft]);
+
+  // Default validity to the first configured option (accept mode).
+  useEffect(() => {
+    if (mode === "accept" && !validityDays && validityOptions.length > 0) {
+      setValidityDays(validityOptions[0].value);
+    }
+  }, [mode, validityDays, validityOptions]);
+
+  const locked = mode === "edit" && Boolean(draft?.locked);
+
+  const moveArticle = (index: number, delta: number) => {
+    setArticles((prev) => {
+      const next = [...prev];
+      const target = index + delta;
+      if (target < 0 || target >= next.length) return prev;
+      [next[index], next[target]] = [next[target], next[index]];
+      return next;
+    });
+  };
+
+  const updateArticle = (id: string, patch: Partial<EditableArticle>) =>
+    setArticles((prev) =>
+      prev.map((a) => (a.id === id ? { ...a, ...patch } : a)),
+    );
+
+  const removeArticle = (id: string) =>
+    setArticles((prev) => prev.filter((a) => a.id !== id));
+
+  const addArticle = () =>
+    setArticles((prev) => [
+      ...prev,
+      { id: newArticleId(), title: "", body: "" },
+    ]);
+
+  const buildSnapshot = (): Freight.IContractDocumentSnapshot => ({
+    code: draft?.code ?? null,
+    name: draft?.name ?? null,
+    documentTitle: documentTitle.trim() || null,
+    whereasClauses: whereasClauses
+      .map((c) => c.trim())
+      .filter((c) => c.length > 0),
+    articles: articles
+      .filter((a) => a.title.trim().length > 0 || a.body.trim().length > 0)
+      .map((a, index) => ({
+        id: a.id,
+        title: a.title.trim(),
+        body: a.body,
+        order: index + 1,
+      })),
+  });
+
+  const hasArticles = useMemo(
+    () => articles.some((a) => a.title.trim() || a.body.trim()),
+    [articles],
+  );
+
+  const submit = () => {
+    const snapshot = buildSnapshot();
+    if (mode === "accept") {
+      const days = Number(validityDays);
+      if (!days) return;
+      onAccept?.(days, snapshot);
+    } else {
+      onSaveEdit?.(snapshot);
+    }
+  };
+
+  const submitting = accepting || saving;
+  const canSubmit =
+    hasArticles &&
+    !locked &&
+    (mode === "edit" || Boolean(validityDays)) &&
+    !submitting;
+
+  return (
+    <Modal
+      opened={opened}
+      onClose={onClose}
+      size="xl"
+      centered
+      radius="md"
+      title={
+        <Group gap="xs">
+          <FileText size={18} />
+          <Text fw={700}>
+            {mode === "accept"
+              ? "Review contract document & accept"
+              : "Edit contract document"}
+          </Text>
+        </Group>
+      }
+    >
+      {isLoading ? (
+        <Group justify="center" py="xl">
+          <Loader size="sm" color="gray" />
+          <Text size="sm" c="dimmed">
+            Loading document…
+          </Text>
+        </Group>
+      ) : (
+        <Stack gap="md">
+          <Alert
+            variant="light"
+            color={locked ? "orange" : "blue"}
+            icon={locked ? <Lock size={16} /> : <Info size={16} />}
+          >
+            {locked
+              ? "This document is locked — an approver has already acted, so it can no longer be edited."
+              : "Edits apply to THIS contract only. The six shared templates are never changed."}
+          </Alert>
+
+          <TextInput
+            label="Document title"
+            placeholder="e.g. Bulk Cargo Transportation and Customs Clearance Services"
+            value={documentTitle}
+            onChange={(e) => setDocumentTitle(e.currentTarget.value)}
+            disabled={locked}
+          />
+
+          <Box>
+            <Group justify="space-between" mb={6}>
+              <Text size="sm" fw={600}>
+                WHEREAS recitals
+              </Text>
+              <Button
+                size="compact-xs"
+                variant="light"
+                color="gray"
+                leftSection={<Plus size={13} />}
+                disabled={locked}
+                onClick={() => setWhereasClauses((p) => [...p, ""])}
+              >
+                Add recital
+              </Button>
+            </Group>
+            {whereasClauses.length === 0 ? (
+              <Text size="xs" c="dimmed">
+                No recitals.
+              </Text>
+            ) : (
+              <Stack gap="xs">
+                {whereasClauses.map((clause, i) => (
+                  <Group key={i} gap="xs" wrap="nowrap" align="flex-start">
+                    <Textarea
+                      style={{ flex: 1 }}
+                      autosize
+                      minRows={1}
+                      value={clause}
+                      disabled={locked}
+                      onChange={(e) =>
+                        setWhereasClauses((prev) =>
+                          prev.map((c, idx) =>
+                            idx === i ? e.currentTarget.value : c,
+                          ),
+                        )
+                      }
+                    />
+                    <ActionIcon
+                      variant="subtle"
+                      color="red"
+                      disabled={locked}
+                      onClick={() =>
+                        setWhereasClauses((prev) =>
+                          prev.filter((_, idx) => idx !== i),
+                        )
+                      }
+                    >
+                      <Trash2 size={15} />
+                    </ActionIcon>
+                  </Group>
+                ))}
+              </Stack>
+            )}
+          </Box>
+
+          <Divider label="Articles" labelPosition="left" />
+
+          <Stack gap="md">
+            {articles.map((article, index) => (
+              <Box
+                key={article.id}
+                p="sm"
+                style={{
+                  border: "1px solid var(--mantine-color-gray-3)",
+                  borderRadius: 8,
+                }}
+              >
+                <Group justify="space-between" mb="xs" wrap="nowrap">
+                  <Text size="sm" fw={700} c="dimmed">
+                    Article {index + 1}
+                  </Text>
+                  <Group gap={4} wrap="nowrap">
+                    <Tooltip label="Move up" withArrow>
+                      <ActionIcon
+                        variant="subtle"
+                        color="gray"
+                        disabled={locked || index === 0}
+                        onClick={() => moveArticle(index, -1)}
+                      >
+                        <ArrowUp size={15} />
+                      </ActionIcon>
+                    </Tooltip>
+                    <Tooltip label="Move down" withArrow>
+                      <ActionIcon
+                        variant="subtle"
+                        color="gray"
+                        disabled={locked || index === articles.length - 1}
+                        onClick={() => moveArticle(index, 1)}
+                      >
+                        <ArrowDown size={15} />
+                      </ActionIcon>
+                    </Tooltip>
+                    <Tooltip label="Delete article" withArrow>
+                      <ActionIcon
+                        variant="subtle"
+                        color="red"
+                        disabled={locked}
+                        onClick={() => removeArticle(article.id)}
+                      >
+                        <Trash2 size={15} />
+                      </ActionIcon>
+                    </Tooltip>
+                  </Group>
+                </Group>
+                <Stack gap="xs">
+                  <TextInput
+                    placeholder="Article title"
+                    value={article.title}
+                    disabled={locked}
+                    onChange={(e) =>
+                      updateArticle(article.id, { title: e.currentTarget.value })
+                    }
+                  />
+                  <Textarea
+                    placeholder="Article body — each line becomes a numbered clause. Use '- ' for bullets. Placeholders like {{client.companyName}} are supported."
+                    autosize
+                    minRows={3}
+                    styles={{ input: { fontFamily: "var(--mantine-font-family-monospace)" } }}
+                    value={article.body}
+                    disabled={locked}
+                    onChange={(e) =>
+                      updateArticle(article.id, { body: e.currentTarget.value })
+                    }
+                  />
+                </Stack>
+              </Box>
+            ))}
+
+            <Button
+              variant="light"
+              color="edr-green"
+              leftSection={<Plus size={15} />}
+              disabled={locked}
+              onClick={addArticle}
+            >
+              Add article
+            </Button>
+          </Stack>
+
+          <Divider />
+
+          {mode === "accept" && (
+            <>
+              {validityOptions.length > 0 ? (
+                <Select
+                  label="Contract validity"
+                  placeholder="Select a validity period"
+                  data={validityOptions}
+                  value={validityDays}
+                  onChange={setValidityDays}
+                  allowDeselect={false}
+                  comboboxProps={{ withinPortal: true }}
+                />
+              ) : (
+                <Text size="sm" c="orange.7">
+                  {validityLoading
+                    ? "Loading validity periods…"
+                    : "No validity periods are configured yet. Add them under Dropdown Settings."}
+                </Text>
+              )}
+            </>
+          )}
+
+          <Group justify="flex-end" gap="sm">
+            <Button variant="default" onClick={onClose} disabled={submitting}>
+              Cancel
+            </Button>
+            <Button
+              color="edr-green"
+              loading={submitting}
+              disabled={!canSubmit}
+              onClick={submit}
+            >
+              {mode === "accept"
+                ? "Accept & start approval"
+                : "Save document changes"}
+            </Button>
+          </Group>
+        </Stack>
+      )}
+    </Modal>
+  );
+}

apps/edr-freight-web/backoffice/src/components/fleet/fleetFormat.tsx

@@ -40,7 +40,7 @@ export const formatFleetCell = (
       if (s === "INACTIVE") return "gray";
       if (s === "SUSPENDED" || s === "OUT_OF_SERVICE") return "red";
       if (s === "MAINTENANCE" || s === "ON_LEAVE") return "orange";
-      if (s === "RETIRED") return "gray";
+      if (s === "RETIRED" || s === "DETAINED") return "gray";
       return "gray";
     };
     const color = getStatusColor(status);

apps/edr-freight-web/backoffice/src/components/wagons/WagonTransferRequestsModal.tsx

@@ -168,6 +168,11 @@ function HistoryPanel({ opened }: { opened: boolean }) {
                         </Badge>
                       </Group>
                     </Group>
+                    {r.reason ? (
+                      <Text size="xs" c="dimmed" mt={4}>
+                        Reason: {r.reason}
+                      </Text>
+                    ) : null}
                   </Card>
                 ))}
               </Stack>
@@ -233,6 +238,8 @@ const WagonTransferRequestsModal = ({
   const [tab, setTab] = useState<string | null>("queue");
   const [active, setActive] = useState<WagonTransferRequest | null>(null);
   const [picked, setPicked] = useState<Set<string>>(new Set());
+  // Bulk accept-and-execute: the subset of pending requests OCC ticked.
+  const [selected, setSelected] = useState<Set<string>>(new Set());
 
   const { data: requests = [], isLoading } = useQuery({
     ...api.wagonTransferRequests.list.queryOptions({ input: { status: PENDING } }),
@@ -256,6 +263,9 @@ const WagonTransferRequestsModal = ({
   });
 
   const fulfill = useMutation(api.wagonTransferRequests.fulfill.mutationOptions());
+  const bulkFulfill = useMutation(
+    api.wagonTransferRequests.bulkFulfill.mutationOptions(),
+  );
   const cancel = useMutation(api.wagonTransferRequests.cancel.mutationOptions());
 
   const showError = (err: unknown, fallback: string) => {
@@ -310,6 +320,36 @@ const WagonTransferRequestsModal = ({
     }
   };
 
+  const toggleSelected = (id: string) =>
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+
+  // Execute the ticked subset; whatever cannot run (not enough available
+  // wagons, already decided) is reported and simply stays PENDING.
+  const handleBulkFulfill = async () => {
+    if (selected.size === 0) return;
+    try {
+      const res = await bulkFulfill.mutateAsync({ requestIds: [...selected] });
+      setSelected(new Set());
+      const skippedNote = res.skipped.length
+        ? ` · ${res.skipped.length} left pending (${res.skipped
+            .map((s) => s.reason)
+            .join('; ')})`
+        : "";
+      toast({
+        title: `Executed ${res.fulfilled.length} transfer request(s)`,
+        description: skippedNote || undefined,
+        variant: res.fulfilled.length === 0 ? "destructive" : undefined,
+      });
+    } catch (err) {
+      showError(err, "Bulk execute failed");
+    }
+  };
+
   const sortedWagons = useMemo(
     () => [...wagons].sort((a, b) => a.wagonNumber.localeCompare(b.wagonNumber)),
     [wagons],
@@ -371,17 +411,65 @@ const WagonTransferRequestsModal = ({
           </Card>
         ) : (
           <Stack gap="sm">
+            {/* Bulk accept-and-execute action bar: tick a subset, run it, and
+                everything unticked (or unexecutable) stays PENDING. */}
+            <Group justify="space-between" wrap="nowrap">
+              <Checkbox
+                label={
+                  selected.size > 0
+                    ? `${selected.size} of ${requests.length} selected`
+                    : "Select all"
+                }
+                checked={selected.size === requests.length && requests.length > 0}
+                indeterminate={selected.size > 0 && selected.size < requests.length}
+                onChange={() =>
+                  setSelected(
+                    selected.size === requests.length
+                      ? new Set()
+                      : new Set(requests.map((r) => r.id)),
+                  )
+                }
+                color="edr-green"
+              />
+              <Button
+                size="compact-sm"
+                color="edr-green"
+                leftSection={<PackageCheck size={14} />}
+                loading={bulkFulfill.isPending}
+                disabled={selected.size === 0}
+                onClick={handleBulkFulfill}
+              >
+                Accept & execute {selected.size > 0 ? `(${selected.size})` : ""}
+              </Button>
+            </Group>
+
             {requests.map((r) => (
               <Card key={r.id} withBorder radius="md" padding="md">
                 <Group justify="space-between" wrap="nowrap" align="flex-start">
-                  <Stack gap={6} style={{ minWidth: 0 }}>
-                    <RequestSummary r={r} />
-                    {r.note ? (
-                      <Text size="xs" c="dimmed">
-                        “{r.note}”
-                      </Text>
-                    ) : null}
-                  </Stack>
+                  <Group gap="sm" wrap="nowrap" align="flex-start" style={{ minWidth: 0 }}>
+                    <Checkbox
+                      checked={selected.has(r.id)}
+                      onChange={() => toggleSelected(r.id)}
+                      color="edr-green"
+                      mt={2}
+                    />
+                    <Stack gap={6} style={{ minWidth: 0 }}>
+                      <RequestSummary r={r} />
+                      {r.reason ? (
+                        <Text size="xs">
+                          <Text span fw={600}>
+                            Reason:
+                          </Text>{" "}
+                          {r.reason}
+                        </Text>
+                      ) : null}
+                      {r.note ? (
+                        <Text size="xs" c="dimmed">
+                          “{r.note}”
+                        </Text>
+                      ) : null}
+                    </Stack>
+                  </Group>
                   <Group gap={8} wrap="nowrap">
                     <Button
                       size="compact-sm"

apps/edr-freight-web/backoffice/src/components/wagons/WagonYardWorkspaceModal.tsx

@@ -15,6 +15,7 @@ import {
   Slider,
   Stack,
   Text,
+  Textarea,
   ThemeIcon,
 } from "@mantine/core";
 import { useMutation, useQuery } from "@tanstack/react-query";
@@ -125,6 +126,7 @@ const WagonYardWorkspaceModal = ({ opened, onClose }: WagonYardWorkspaceModalPro
 
   const [transferYardId, setTransferYardId] = useState<string | null>(null);
   const [transferQty, setTransferQty] = useState(0);
+  const [transferReason, setTransferReason] = useState("");
   const [toAssignedQty, setToAssignedQty] = useState(0);
   const [toAvailableQty, setToAvailableQty] = useState(0);
 
@@ -207,6 +209,7 @@ const WagonYardWorkspaceModal = ({ opened, onClose }: WagonYardWorkspaceModalPro
   useEffect(() => {
     setTransferYardId(null);
     setTransferQty(0);
+    setTransferReason("");
     setToAssignedQty(0);
     setToAvailableQty(0);
   }, [yardId, typeId]);
@@ -219,8 +222,9 @@ const WagonYardWorkspaceModal = ({ opened, onClose }: WagonYardWorkspaceModalPro
     }
   }, [opened]);
 
-  // Keep quantities within bounds as counts shift after each action.
-  useEffect(() => setTransferQty((q) => Math.min(q, total)), [total]);
+  // Keep quantities within bounds as counts shift after each action. Transfers
+  // may only ask for AVAILABLE wagons, so the request cap is availableCount.
+  useEffect(() => setTransferQty((q) => Math.min(q, availableCount)), [availableCount]);
   useEffect(() => setToAssignedQty((q) => Math.min(q, availableCount)), [availableCount]);
   useEffect(() => setToAvailableQty((q) => Math.min(q, assignedCount)), [assignedCount]);
 
@@ -233,13 +237,21 @@ const WagonYardWorkspaceModal = ({ opened, onClose }: WagonYardWorkspaceModalPro
   // Request-only: the requester specifies count + destination; OCC later picks
   // the physical wagons and executes the move. No wagons are moved here.
   const handleRequest = async () => {
-    if (!yardId || !typeId || !transferYardId || transferQty < 1) return;
+    if (
+      !yardId ||
+      !typeId ||
+      !transferYardId ||
+      transferQty < 1 ||
+      !transferReason.trim()
+    )
+      return;
     try {
       await createRequest.mutateAsync({
         fromYardId: yardId,
         toYardId: transferYardId,
         wagonTypeId: typeId,
         quantity: transferQty,
+        reason: transferReason.trim(),
       });
       toast({
         title: `Requested ${transferQty} ${typeInfo.code(typeId)} wagon(s) · ${yardName(
@@ -249,6 +261,7 @@ const WagonYardWorkspaceModal = ({ opened, onClose }: WagonYardWorkspaceModalPro
       });
       setTransferQty(0);
       setTransferYardId(null);
+      setTransferReason("");
     } catch (err) {
       showError(err, "Request failed");
     }
@@ -407,10 +420,19 @@ const WagonYardWorkspaceModal = ({ opened, onClose }: WagonYardWorkspaceModalPro
                   </Text>
                   <Stack gap="md">
                     <div>
-                      <Text size="sm" fw={500} mb={4}>
-                        How many wagons
-                      </Text>
-                      <QuantityField value={transferQty} onChange={setTransferQty} max={total} />
+                      <Group justify="space-between" mb={4}>
+                        <Text size="sm" fw={500}>
+                          How many wagons
+                        </Text>
+                        <Badge color="teal" variant="light">
+                          {availableCount} available
+                        </Badge>
+                      </Group>
+                      <QuantityField
+                        value={transferQty}
+                        onChange={setTransferQty}
+                        max={availableCount}
+                      />
                     </div>
                     <Select
                       label="Destination yard"
@@ -421,6 +443,16 @@ const WagonYardWorkspaceModal = ({ opened, onClose }: WagonYardWorkspaceModalPro
                       searchable
                       radius="md"
                     />
+                    <Textarea
+                      label="Reason"
+                      placeholder="Why are these wagons needed?"
+                      value={transferReason}
+                      onChange={(e) => setTransferReason(e.currentTarget.value)}
+                      required
+                      autosize
+                      minRows={2}
+                      radius="md"
+                    />
                     {transferYardId && transferQty > 0 ? (
                       <Card bg="var(--mantine-color-gray-0)" radius="md" padding="sm" withBorder>
                         <Group gap={8} wrap="nowrap">
@@ -446,7 +478,12 @@ const WagonYardWorkspaceModal = ({ opened, onClose }: WagonYardWorkspaceModalPro
                       leftSection={<ArrowRightLeft size={16} />}
                       onClick={handleRequest}
                       loading={createRequest.isPending}
-                      disabled={busy || !transferYardId || transferQty < 1}
+                      disabled={
+                        busy ||
+                        !transferYardId ||
+                        transferQty < 1 ||
+                        !transferReason.trim()
+                      }
                       color="edr-green"
                     >
                       Request {transferQty > 0 ? `${transferQty} ` : ""}wagon

apps/edr-freight-web/backoffice/src/constants/QUERY_KEYS.ts

@@ -166,6 +166,7 @@ export const QUERY_KEYS = {
     ) => ["rule-engine", "select-options", resource, params ?? {}] as const,
     orderList: (resource: RuleEngineResourceSlug | string) =>
       ["rule-engine", "order-list", resource] as const,
+    priorityRuleChanges: ["rule-engine", "priority-rule-changes"] as const,
   },
 
   OVERVIEW: {

apps/edr-freight-web/backoffice/src/constants/URLS.ts

@@ -176,6 +176,9 @@ export const URL_CONSTANTS = {
     CONTRACT_VIEW: (id: string) => `/contracts/${id}/contract/view`,
     CONTRACT_DOCUMENT: (id: string) => `/contracts/${id}/contract/document`,
     CONTRACT_SIGN: (id: string) => `/contracts/${id}/contract/sign`,
+    CONTRACT_DOCUMENT_DRAFT: (id: string) => `/contracts/${id}/document/draft`,
+    CONTRACT_DOCUMENT_ARTICLES: (id: string) =>
+      `/contracts/${id}/document/articles`,
     CLEARANCE_QUEUE: "/contracts/clearance/queue",
     CLEARANCE: (id: string) => `/contracts/${id}/clearance`,
     CLEARANCE_REVIEW: (id: string) => `/contracts/${id}/clearance/review`,

apps/edr-freight-web/backoffice/src/hooks/contracts/useContracts.ts

@@ -125,12 +125,27 @@ export function useContractMutations(contractId: string) {
   };
 
   const staffAccept = useMutation({
-    mutationFn: (validityDays: number) =>
-      contractsService.staffAccept(contractId, validityDays),
+    mutationFn: (payload: {
+      validityDays: number;
+      documentSnapshot?: Freight.IContractDocumentSnapshot;
+    }) =>
+      contractsService.staffAccept(
+        contractId,
+        payload.validityDays,
+        payload.documentSnapshot,
+      ),
     onSuccess: (data) => onSuccess(data, "Contract accepted for approval"),
     onError: () => toast.error("Failed to accept contract"),
   });
 
+  // Edit THIS contract's document articles (per-contract; never the templates).
+  const updateDocument = useMutation({
+    mutationFn: (snapshot: Freight.IContractDocumentSnapshot) =>
+      contractsService.updateContractDocument(contractId, snapshot),
+    onSuccess: (data) => onSuccess(data, "Contract document updated"),
+    onError: () => toast.error("Failed to update contract document"),
+  });
+
   const requestChanges = useMutation({
     mutationFn: (note: string) =>
       contractsService.requestChanges(contractId, note),
@@ -144,11 +159,6 @@ export function useContractMutations(contractId: string) {
     onError: () => toast.error("Failed to reject contract"),
   });
 
-  // Statuses that mean every approval step is done and the contract is ready to
-  // be generated. Once the final approval lands we generate the PDF
-  // automatically — staff no longer click a separate "Generate" button.
-  const READY_TO_GENERATE = ["APPROVED", "APPROVED_PENDING_SIGNATURE"];
-
   const approveStep = useMutation({
     mutationFn: ({
       stepId,
@@ -158,25 +168,15 @@ export function useContractMutations(contractId: string) {
       requiredRole: string;
     }) =>
       contractsService.approveStep({ id: contractId, stepId, requiredRole }),
-    onSuccess: async (data) => {
-      // If this was the LAST approval, auto-generate the contract so it goes
-      // straight to CONTRACT_READY without a manual step.
-      const alreadyGenerated = Boolean(
-        (data as Freight.IContract).contractGeneratedAt,
-      );
-      if (READY_TO_GENERATE.includes(data.status) && !alreadyGenerated) {
-        toast.success("Final approval complete — generating contract…");
-        try {
-          const generated = await contractsService.generateContract(data.id);
-          onSuccess(generated, "Contract generated and ready to sign");
-          return;
-        } catch {
-          toast.error("Approved, but contract generation failed. Retry below.");
-          void invalidateContractDetail(qc, data.id);
-          return;
-        }
-      }
-      onSuccess(data, "Approval step completed");
+    onSuccess: (data) => {
+      // The document is generated at the accept stage and reviewed during
+      // approval, so the final approval moves the contract straight to
+      // CONTRACT_READY on the server — no client-side generate call here.
+      const message =
+        data.status === "CONTRACT_READY"
+          ? "Final approval complete — contract ready to sign"
+          : "Approval step completed";
+      onSuccess(data, message);
     },
     onError: () => toast.error("Failed to approve step"),
   });
@@ -239,6 +239,7 @@ export function useContractMutations(contractId: string) {
 
   const isPending =
     staffAccept.isPending ||
+    updateDocument.isPending ||
     requestChanges.isPending ||
     reject.isPending ||
     approveStep.isPending ||
@@ -249,6 +250,7 @@ export function useContractMutations(contractId: string) {
 
   return {
     staffAccept,
+    updateDocument,
     requestChanges,
     reject,
     approveStep,

apps/edr-freight-web/backoffice/src/hooks/rule-engine/useRuleEngine.ts

@@ -3,7 +3,11 @@ import toast from "react-hot-toast";
 
 import { QUERY_KEYS } from "@/constants/QUERY_KEYS";
 import { api } from "@/services/api";
-import { ruleEngineService, type RuleEngineListParams } from "@/services/ruleEngine/ruleEngine.service";
+import {
+  ruleEngineService,
+  type RuleEngineListParams,
+  type SubmitPriorityRuleChangePayload,
+} from "@/services/ruleEngine/ruleEngine.service";
 import { RULE_ENGINE_SELECT_NONE } from "@/pages/ruleEngine/config/resources";
 import type {
   RuleEngineRecord,
@@ -239,6 +243,68 @@ export const useRuleEngineMutations = (resource: RuleEngineResourceSlug) => {
   return { create, update, remove };
 };
 
+/**
+ * Priority-rule approval workflow. Every create/update/delete of a priority
+ * config is SUBMITTED as a change request; an approver applies or rejects it.
+ * Error toasts surface the backend message so range-collision rejections
+ * ("1–5 overlaps existing rule …") reach the user verbatim.
+ */
+export const usePriorityRuleWorkflow = (enabled: boolean) => {
+  const qc = useQueryClient();
+
+  const backendMessage = (err: unknown, fallback: string) => {
+    const msg = (err as { response?: { data?: { message?: string | string[] } } })
+      ?.response?.data?.message;
+    if (Array.isArray(msg)) return msg.join(", ");
+    return msg || fallback;
+  };
+
+  const pending = useQuery({
+    queryKey: QUERY_KEYS.RULE_ENGINE.priorityRuleChanges,
+    queryFn: () => ruleEngineService.listPriorityRuleChanges("PENDING"),
+    enabled,
+  });
+
+  const invalidate = async () => {
+    await qc.invalidateQueries({
+      queryKey: QUERY_KEYS.RULE_ENGINE.priorityRuleChanges,
+    });
+    await invalidateRuleEngineList(qc, "priority-configs");
+  };
+
+  const submit = useMutation({
+    mutationFn: (payload: SubmitPriorityRuleChangePayload) =>
+      ruleEngineService.submitPriorityRuleChange(payload),
+    onSuccess: async () => {
+      toast.success("Change submitted for approval — the team has been notified");
+      await invalidate();
+    },
+    onError: (err) => toast.error(backendMessage(err, "Failed to submit change")),
+  });
+
+  const approve = useMutation({
+    mutationFn: ({ id, decisionNote }: { id: string; decisionNote?: string }) =>
+      ruleEngineService.approvePriorityRuleChange(id, decisionNote),
+    onSuccess: async () => {
+      toast.success("Change approved and applied");
+      await invalidate();
+    },
+    onError: (err) => toast.error(backendMessage(err, "Failed to approve change")),
+  });
+
+  const reject = useMutation({
+    mutationFn: ({ id, decisionNote }: { id: string; decisionNote?: string }) =>
+      ruleEngineService.rejectPriorityRuleChange(id, decisionNote),
+    onSuccess: async () => {
+      toast.success("Change rejected");
+      await invalidate();
+    },
+    onError: (err) => toast.error(backendMessage(err, "Failed to reject change")),
+  });
+
+  return { pending, submit, approve, reject };
+};
+
 export const useRateWorkflow = () => {
   const qc = useQueryClient();
 

apps/edr-freight-web/backoffice/src/pages/fleet/FleetCrudPages.tsx

@@ -965,7 +965,7 @@ export function WagonsCrudPage() {
             { value: 'EXPORT_READY', label: 'Export ready' },
             { value: 'ASSIGNED', label: 'Assigned' },
             { value: 'MAINTENANCE', label: 'Maintenance' },
-            { value: 'RETIRED', label: 'Retired' },
+            { value: 'DETAINED', label: 'Detained' },
           ],
         },
         { key: 'notes', label: 'Notes' },

apps/edr-freight-web/backoffice/src/pages/fleet/config/resources.ts

@@ -113,7 +113,7 @@ const WAGON_STATUS_OPTIONS = [
   { label: "Available", value: Freight.WagonStatus.Available },
   { label: "Assigned", value: Freight.WagonStatus.Assigned },
   { label: "Maintenance", value: Freight.WagonStatus.Maintenance },
-  { label: "Retired", value: Freight.WagonStatus.Retired },
+  { label: "Detained", value: Freight.WagonStatus.Detained },
 ];
 
 

apps/edr-freight-web/backoffice/src/pages/ruleEngine/PriorityRuleApprovalsSection.tsx

@@ -0,0 +1,125 @@
+import { Badge, Button, Card, Group, Stack, Text } from "@mantine/core";
+import type { UseMutationResult } from "@tanstack/react-query";
+import { CheckCircle2, XCircle } from "lucide-react";
+
+import type { PriorityRuleChangeRequest } from "@/services/ruleEngine/ruleEngine.service";
+
+const ACTION_COLOR: Record<PriorityRuleChangeRequest["action"], string> = {
+  CREATE: "teal",
+  UPDATE: "blue",
+  DELETE: "red",
+};
+
+const fmtDateTime = (iso: string) =>
+  new Date(iso).toLocaleString("en-GB", {
+    day: "numeric",
+    month: "short",
+    hour: "2-digit",
+    minute: "2-digit",
+    hour12: false,
+  });
+
+/** "WAGON 1–5 · 30 pts" from a change payload / target rule. */
+const ruleSummary = (
+  r: PriorityRuleChangeRequest,
+): string => {
+  const source = (r.payload ?? r.priorityConfig ?? {}) as Record<string, unknown>;
+  const base = (r.priorityConfig ?? {}) as Record<string, unknown>;
+  const pick = (key: string) => source[key] ?? base[key];
+  const type = pick("type");
+  const currency = pick("currency");
+  const min = pick("minWagonCount");
+  const max = pick("maxWagonCount");
+  const pts = pick("scorePoints");
+  const parts = [
+    type ? String(type) : null,
+    currency ? String(currency) : null,
+    min != null && max != null ? `${min}–${max} wagons` : null,
+    pts != null ? `${pts} pts` : null,
+  ].filter(Boolean);
+  return parts.join(" · ") || "—";
+};
+
+type Decide = UseMutationResult<
+  PriorityRuleChangeRequest,
+  unknown,
+  { id: string; decisionNote?: string }
+>;
+
+interface PriorityRuleApprovalsSectionProps {
+  requests: PriorityRuleChangeRequest[];
+  canDecide: boolean;
+  approve: Decide;
+  reject: Decide;
+}
+
+/**
+ * Pending priority-rule change requests awaiting approval. Rendered above the
+ * rules table on the priority-configs page; every rule change lands here first
+ * and only an approval applies it.
+ */
+const PriorityRuleApprovalsSection = ({
+  requests,
+  canDecide,
+  approve,
+  reject,
+}: PriorityRuleApprovalsSectionProps) => {
+  if (requests.length === 0) return null;
+
+  return (
+    <Card withBorder radius="md" padding="md" mb="md">
+      <Group gap={8} mb="sm">
+        <Text fw={700}>Pending approvals</Text>
+        <Badge variant="light" color="yellow">
+          {requests.length}
+        </Badge>
+      </Group>
+      <Stack gap={8}>
+        {requests.map((r) => (
+          <Card key={r.id} withBorder radius="md" padding="sm">
+            <Group justify="space-between" wrap="nowrap" align="flex-start">
+              <Stack gap={4} style={{ minWidth: 0 }}>
+                <Group gap={8} wrap="nowrap">
+                  <Badge variant="light" color={ACTION_COLOR[r.action]} radius="sm">
+                    {r.action.toLowerCase()}
+                  </Badge>
+                  <Text size="sm" fw={600} truncate>
+                    {ruleSummary(r)}
+                  </Text>
+                </Group>
+                <Text size="xs" c="dimmed">
+                  Submitted {fmtDateTime(r.createdAt)}
+                </Text>
+              </Stack>
+              {canDecide ? (
+                <Group gap={8} wrap="nowrap">
+                  <Button
+                    size="compact-sm"
+                    variant="subtle"
+                    color="red"
+                    leftSection={<XCircle size={14} />}
+                    loading={reject.isPending}
+                    onClick={() => reject.mutate({ id: r.id })}
+                  >
+                    Reject
+                  </Button>
+                  <Button
+                    size="compact-sm"
+                    color="edr-green"
+                    leftSection={<CheckCircle2 size={14} />}
+                    loading={approve.isPending}
+                    onClick={() => approve.mutate({ id: r.id })}
+                  >
+                    Approve & apply
+                  </Button>
+                </Group>
+              ) : null}
+            </Group>
+          </Card>
+        ))}
+      </Stack>
+    </Card>
+  );
+};
+
+export default PriorityRuleApprovalsSection;

apps/edr-freight-web/backoffice/src/pages/ruleEngine/RuleEngineResourcePage.tsx

@@ -18,6 +18,7 @@ import { Navigate, useLocation, useParams } from "react-router-dom";
 
 import { PageContainer, PageHeader } from "@/components/page";
 import ManageRuleEngineOrderDialog from "@/components/ruleEngine/ManageRuleEngineOrderDialog";
+import PriorityRuleApprovalsSection from "@/pages/ruleEngine/PriorityRuleApprovalsSection";
 import RuleEngineCardGrid from "@/components/ruleEngine/RuleEngineCardGrid";
 import RuleEngineFormDialog from "@/components/ruleEngine/RuleEngineFormDialog";
 import RuleEngineOrderControls from "@/components/ruleEngine/RuleEngineOrderControls";
@@ -34,6 +35,7 @@ import {
     useContainerTypeOptions,
     useLiveRateOptions,
     useWagonTypeOptions,
+    usePriorityRuleWorkflow,
     useRateWorkflow,
     useRuleEngineList,
     useRuleEngineMutations,
@@ -142,6 +144,13 @@ const RuleEngineResourcePage = () => {
     chainOpen && config?.slug === "approval-rules",
   );
 
+  // Priority rules never mutate directly: changes are filed for approval and a
+  // pending queue renders above the table.
+  const isPriorityRules = config?.slug === "priority-configs";
+  const priorityWorkflow = usePriorityRuleWorkflow(
+    Boolean(isPriorityRules && canView),
+  );
+
   const editingId = editing?.id ? String(editing.id) : undefined;
   const usesContainerTypeField = Boolean(
     config?.formFields.some((f) => f.name === "containerTypeId"),
@@ -360,9 +369,37 @@ const RuleEngineResourcePage = () => {
         currency: "USD",
         trigger: isSurcharge ? values.trigger : "ALWAYS",
       };
-    } else if (config.slug === "priority-configs") {
+    } else if (isPriorityRules) {
       // Label is required by the backend but hidden in the UI for now.
       payload = { ...values, label: String(Date.now()) };
+      // Approval workflow: file a change request instead of mutating directly.
+      // On update, keep the target's existing label rather than a fresh stamp.
+      if (editing?.id) {
+        priorityWorkflow.submit.mutate(
+          {
+            action: "UPDATE",
+            priorityConfigId: String(editing.id),
+            update: { ...values, label: String(editing.label ?? Date.now()) },
+          },
+          {
+            onSuccess: () => {
+              setFormOpen(false);
+              setEditing(null);
+            },
+          },
+        );
+      } else {
+        priorityWorkflow.submit.mutate(
+          { action: "CREATE", create: payload },
+          {
+            onSuccess: () => {
+              setFormOpen(false);
+              setEditing(null);
+            },
+          },
+        );
+      }
+      return;
     } else if (config.slug === "weight-limit-rules") {
       // Empty max capacity means "no ceiling" — send null explicitly so an
       // edit can clear a previously-set ceiling (omitting the key keeps it).
@@ -406,6 +443,15 @@ const RuleEngineResourcePage = () => {
         }
       />
 
+      {isPriorityRules ? (
+        <PriorityRuleApprovalsSection
+          requests={priorityWorkflow.pending.data ?? []}
+          canDecide={canManage}
+          approve={priorityWorkflow.approve}
+          reject={priorityWorkflow.reject}
+        />
+      ) : null}
+
       <Card p={0}>
         <Stack gap={0}>
           <Box px="md" pt="md" pb="sm" w="100%">
@@ -519,7 +565,9 @@ const RuleEngineResourcePage = () => {
         }
         fields={formFields}
         initialRecord={editing}
-        isSubmitting={create.isPending || update.isPending}
+        isSubmitting={
+          create.isPending || update.isPending || priorityWorkflow.submit.isPending
+        }
         selectOptionsLoading={
           (config.slug === "cargo-types" && cargoParentOptionsLoading) ||
           (usesContainerTypeField && containerTypeOptionsLoading) ||
@@ -557,8 +605,9 @@ const RuleEngineResourcePage = () => {
       >
         <Stack gap="md">
           <Text size="sm">
-            This will soft-delete the selected {config.label.toLowerCase()}{" "}
-            record.
+            {isPriorityRules
+              ? "This files a delete request for approval — the rule is removed once an approver confirms."
+              : `This will soft-delete the selected ${config.label.toLowerCase()} record.`}
           </Text>
           <Group justify="flex-end" gap="sm">
             <Button variant="default" onClick={() => setDeleteTarget(null)}>
@@ -566,15 +615,25 @@ const RuleEngineResourcePage = () => {
             </Button>
             <Button
               color="red"
-              loading={remove.isPending}
+              loading={remove.isPending || priorityWorkflow.submit.isPending}
               onClick={() => {
                 if (!deleteTarget) return;
+                if (isPriorityRules) {
+                  priorityWorkflow.submit.mutate(
+                    {
+                      action: "DELETE",
+                      priorityConfigId: String(deleteTarget.id),
+                    },
+                    { onSuccess: () => setDeleteTarget(null) },
+                  );
+                  return;
+                }
                 remove.mutate(deleteTarget.id, {
                   onSuccess: () => setDeleteTarget(null),
                 });
               }}
             >
-              Delete
+              {isPriorityRules ? "Request delete" : "Delete"}
             </Button>
           </Group>
         </Stack>

apps/edr-freight-web/backoffice/src/pages/trainScheduling/TrainScheduleV2DetailPage.tsx

@@ -68,6 +68,7 @@ import {
   ScheduleWarningsAlert,
 } from "@/components/trainScheduling/ScheduleWarningsAlert";
 import { TrainCompositionDiagram } from "@/components/trainScheduling/TrainCompositionDiagram";
+import { TrainConsistView } from "@/components/trainScheduling/compositionEditor";
 import { WagonPlanGrid } from "@/components/trainScheduling/WagonPlanGrid";
 import { WorkflowRail, WorkflowStep } from "@/components/trainScheduling/WorkflowStep";
 import { openPdfBlob } from "@/components/warehouses/pdf";
@@ -252,12 +253,6 @@ export default function TrainScheduleV2DetailPage() {
     () => (isExportDisplay ? [...displayWagonPlan].reverse() : displayWagonPlan),
     [displayWagonPlan, isExportDisplay],
   );
-  const diagramWagons = useMemo(() => {
-    const source = schedule?.trainSet?.wagons?.length
-      ? schedule.trainSet.wagons
-      : displayWagonPlan;
-    return isExportDisplay ? [...source].reverse() : source;
-  }, [schedule?.trainSet?.wagons, displayWagonPlan, isExportDisplay]);
 
   const runPreview = useCallback(
     async (options?: { silent?: boolean; advanceStep?: boolean }) => {
@@ -774,22 +769,26 @@ export default function TrainScheduleV2DetailPage() {
       );
     }
 
-    // finalize
+    // finalize — the train is known here, so draw the full composition the
+    // same way the batch board's composition tab does (interactive consist).
     return (
       <Stack gap="md">
-        <TrainCompositionDiagram
-          locomotive={schedule.trainSet?.locomotive}
-          locomotives={locomotives}
-          wagons={diagramWagons}
-          freightType={freightType}
-          trainNumber={schedule.trainNumber ?? schedule.train?.code ?? null}
-          totalLengthMeters={schedule.trainSet?.totalLengthMeters}
-        />
-        {isExportDisplay && diagramWagons.length ? (
-          <Text size="xs" c="dimmed">
-            Shown rear-first (export direction) — positions keep their original numbers.
-          </Text>
-        ) : null}
+        {schedule.trainSet ? (
+          <TrainConsistView
+            scheduleDetail={schedule}
+            scheduleId={scheduleId ?? ""}
+            maxWagons={schedule.maxWagons ?? 53}
+          />
+        ) : (
+          <TrainCompositionDiagram
+            locomotive={null}
+            locomotives={locomotives}
+            wagons={[]}
+            freightType={freightType}
+            trainNumber={schedule.trainNumber ?? schedule.train?.code ?? null}
+            totalLengthMeters={null}
+          />
+        )}
         <Paper
           p="lg"
           radius="lg"

apps/edr-freight-web/backoffice/src/services/api.ts

@@ -202,6 +202,7 @@ import {
   type WagonMovementRecord,
   type WagonTransferRequest,
   type CreateTransferRequestPayload,
+  type BulkFulfillResult,
   type TransferHistory,
 } from "./wagon.service";
 import { warehouseService } from "./warehouse.service";
@@ -1721,6 +1722,15 @@ export const api = {
       () => [["wagonTransferRequests"], ["wagons"]],
     ),
 
+    bulkFulfill: endpoint<{ requestIds: string[] }, BulkFulfillResult>(
+      "wagonTransferRequests",
+      "bulkFulfill",
+      ({ requestIds }) =>
+        wagonTransferRequestService.bulkFulfill(requestIds).then((r) => r.data),
+      undefined,
+      () => [["wagonTransferRequests"], ["wagons"]],
+    ),
+
     cancel: endpoint<{ id: string }, WagonTransferRequest>(
       "wagonTransferRequests",
       "cancel",

apps/edr-freight-web/backoffice/src/services/contracts.service.ts

@@ -170,8 +170,35 @@ export const contractsService = {
   },
 
   // ── Staff review ──
-  staffAccept: (id: string, validityDays: number) =>
-    postContract<Freight.IContract>(C.STAFF_ACCEPT(id), { validityDays }),
+  staffAccept: (
+    id: string,
+    validityDays: number,
+    documentSnapshot?: Freight.IContractDocumentSnapshot,
+  ) =>
+    postContract<Freight.IContract>(C.STAFF_ACCEPT(id), {
+      validityDays,
+      documentSnapshot,
+    }),
+
+  /** The editable per-contract document draft (snapshot or live template). */
+  getContractDocumentDraft: async (
+    id: string,
+  ): Promise<Freight.IContractDocumentDraft> => {
+    const response = await client.get(C.CONTRACT_DOCUMENT_DRAFT(id));
+    return unwrap(response.data) as Freight.IContractDocumentDraft;
+  },
+
+  /** Save this contract's edited document articles (never touches the templates). */
+  updateContractDocument: async (
+    id: string,
+    snapshot: Freight.IContractDocumentSnapshot,
+  ): Promise<Freight.IContract> => {
+    const response = await client.put(
+      C.CONTRACT_DOCUMENT_ARTICLES(id),
+      snapshot,
+    );
+    return unwrap(response.data) as Freight.IContract;
+  },
 
   requestChanges: (id: string, note: string) =>
     postContract<Freight.IContract>(C.STAFF_REQUEST_CHANGES(id), { note }),

apps/edr-freight-web/backoffice/src/services/ruleEngine/ruleEngine.service.ts

@@ -24,6 +24,30 @@ export interface RuleEngineReorderPayload {
   requiresDirectorApproval?: boolean;
 }
 
+/** Priority-rule approval workflow (all priority-config changes go through it). */
+const PRIORITY_RULE_CHANGES_BASE = "/priority-rule-change-requests";
+
+export interface PriorityRuleChangeRequest {
+  id: string;
+  action: "CREATE" | "UPDATE" | "DELETE";
+  priorityConfigId: string | null;
+  priorityConfig?: RuleEngineRecord | null;
+  payload: Record<string, unknown> | null;
+  status: "PENDING" | "APPROVED" | "REJECTED";
+  requestedByUserId: string | null;
+  decidedByUserId: string | null;
+  decidedAt: string | null;
+  decisionNote: string | null;
+  createdAt: string;
+}
+
+export interface SubmitPriorityRuleChangePayload {
+  action: "CREATE" | "UPDATE" | "DELETE";
+  priorityConfigId?: string;
+  create?: Record<string, unknown>;
+  update?: Record<string, unknown>;
+}
+
 const RESOURCE_BASE: Record<RuleEngineResourceSlug, string> = {
   "cargo-types": URL_CONSTANTS.RULE_ENGINE.CARGO_TYPES,
   "container-types": URL_CONSTANTS.RULE_ENGINE.CONTAINER_TYPES,
@@ -242,6 +266,46 @@ export const ruleEngineService = {
     return normalizeEntity<T>(response.data);
   },
 
+  /** File a priority-rule change (create/update/delete) for approval. */
+  submitPriorityRuleChange: async (
+    payload: SubmitPriorityRuleChangePayload,
+  ): Promise<PriorityRuleChangeRequest> => {
+    const response = await client.post(PRIORITY_RULE_CHANGES_BASE, payload);
+    return unwrap(response.data) as PriorityRuleChangeRequest;
+  },
+
+  listPriorityRuleChanges: async (
+    status?: PriorityRuleChangeRequest["status"],
+  ): Promise<PriorityRuleChangeRequest[]> => {
+    const response = await client.get(PRIORITY_RULE_CHANGES_BASE, {
+      params: status ? { status } : undefined,
+    });
+    const body = unwrap(response.data) as unknown;
+    return Array.isArray(body) ? (body as PriorityRuleChangeRequest[]) : [];
+  },
+
+  approvePriorityRuleChange: async (
+    id: string,
+    decisionNote?: string,
+  ): Promise<PriorityRuleChangeRequest> => {
+    const response = await client.post(
+      `${PRIORITY_RULE_CHANGES_BASE}/${id}/approve`,
+      { decisionNote },
+    );
+    return unwrap(response.data) as PriorityRuleChangeRequest;
+  },
+
+  rejectPriorityRuleChange: async (
+    id: string,
+    decisionNote?: string,
+  ): Promise<PriorityRuleChangeRequest> => {
+    const response = await client.post(
+      `${PRIORITY_RULE_CHANGES_BASE}/${id}/reject`,
+      { decisionNote },
+    );
+    return unwrap(response.data) as PriorityRuleChangeRequest;
+  },
+
   getApprovalChain: async (
     requiresDirectorApproval = true,
   ): Promise<RuleEngineRecord[]> => {

apps/edr-freight-web/backoffice/src/services/wagon.service.ts

@@ -108,6 +108,8 @@ export interface WagonTransferRequest {
   requestedByUserId: string | null;
   fulfilledByUserId: string | null;
   fulfilledAt: string | null;
+  /** Why the wagons are needed — required for new requests, shown on the queue. */
+  reason?: string | null;
   note: string | null;
   fromYard?: { id: string; label?: string; code?: string } | null;
   toYard?: { id: string; label?: string; code?: string } | null;
@@ -120,9 +122,17 @@ export interface CreateTransferRequestPayload {
   toYardId: string;
   wagonTypeId: string;
   quantity: number;
+  /** Mandatory: why the wagons are needed. */
+  reason: string;
   note?: string;
 }
 
+/** Bulk accept-and-execute result: what ran, what stayed PENDING and why. */
+export interface BulkFulfillResult {
+  fulfilled: WagonTransferRequest[];
+  skipped: Array<{ id: string; reason: string }>;
+}
+
 /** Per-user activity: requests filed/fulfilled + the wagons physically moved. */
 export interface TransferHistory {
   requests: WagonTransferRequest[];
@@ -146,6 +156,11 @@ export const wagonTransferRequestService = {
     apiClient.get<WagonTransferRequest>(`/wagon-transfer-requests/${id}`),
   create: (data: CreateTransferRequestPayload) =>
     apiClient.post<WagonTransferRequest>('/wagon-transfer-requests', data),
+  /** OCC: accept-and-execute a subset of pending requests (auto-picked wagons). */
+  bulkFulfill: (requestIds: string[]) =>
+    apiClient.post<BulkFulfillResult>('/wagon-transfer-requests/bulk-fulfill', {
+      requestIds,
+    }),
   /** OCC: execute the transfer with the hand-picked wagons. */
   fulfill: (id: string, wagonIds: string[]) =>
     apiClient.post<WagonTransferRequest>(

apps/edr-freight-web/backoffice/src/types/trainScheduling.ts

@@ -528,6 +528,8 @@ export interface TrainScheduleDetail {
   deferredBookings?: DeferredBookingRow[];
   freightType?: FreightType | null;
   trainNumber?: string | null;
+  /** Wagon cap for this departure (built-train consist size or configured limit). */
+  maxWagons?: number | null;
   /** Built train (Train Builder) behind this departure, when scheduled by train. */
   train?: {
     id: string;

apps/edr-freight-web/portal/src/pages/bookings/NewBookingPage.tsx

@@ -279,6 +279,60 @@ export default function NewBookingPage() {
   const originYard = form.watch("originYard");
   const destinationYard = form.watch("destinationYard");
   const operationType = form.watch("operationType");
+  const watchedCargoKind = form.watch("cargoType");
+  const watchedContainers = form.watch("containers");
+  const watchedCargoTypePath = form.watch("cargoTypePath");
+  const watchedScheduledDate = form.watch("scheduledDate");
+  const isGeneralContractBooking =
+    form.watch("bookingType") === "general_contract";
+
+  // Wagon-TYPE availability gate: which days have a departure whose train can
+  // physically carry the selected cargo/container type. Quantity is NOT part
+  // of this gate — an oversized booking is accepted and gets a partial split
+  // offer later. Only selectable days reach the UI; no capacity counts.
+  const gateContainerTypeIds = useMemo(() => {
+    if (watchedCargoKind !== "container") return [];
+    const groups = referenceData?.containers ?? [];
+    const ids = new Set<string>();
+    for (const line of watchedContainers ?? []) {
+      if (!line?.containerType) continue;
+      for (const group of groups) {
+        const ct = group.types.find((t) => t.name === line.containerType);
+        if (ct) ids.add(ct.id);
+      }
+    }
+    return [...ids];
+  }, [watchedCargoKind, watchedContainers, referenceData]);
+  const gateCargoTypeId =
+    watchedCargoKind === "bulk" ? watchedCargoTypePath?.[1] : undefined;
+  const gateReady =
+    !isGeneralContractBooking &&
+    !!originYard &&
+    !!destinationYard &&
+    (watchedCargoKind === "bulk"
+      ? !!gateCargoTypeId
+      : gateContainerTypeIds.length > 0);
+  const availableDaysQuery = useQuery(
+    api.bookings.getAvailableDaysForCargo.queryOptions({
+      input: {
+        originYardId: originYard,
+        destinationYardId: destinationYard,
+        freightType: watchedCargoKind === "bulk" ? "BULK" : "CONTAINER",
+        cargoTypeId: gateCargoTypeId || undefined,
+        containerTypeIds: gateContainerTypeIds,
+      },
+      enabled: gateReady,
+    }),
+  );
+  const availableBookingDays = gateReady ? availableDaysQuery.data : undefined;
+  // Block submit only on a POSITIVE answer that the picked day has no wagon
+  // for this cargo — a loading/failed availability lookup never bricks the
+  // wizard (the backend re-checks at the binding step anyway).
+  const noWagonForSelectedDay = Boolean(
+    availableBookingDays &&
+      watchedScheduledDate &&
+      !availableBookingDays.includes(watchedScheduledDate),
+  );
 
   // The estimated shipment date lives in the Route step now; for general
   // contracts that date field is simply hidden there (the date is chosen per
@@ -678,6 +732,8 @@ export default function NewBookingPage() {
               form={form}
               referenceData={referenceData}
               isLoading={refDataLoading}
+              availableDays={availableBookingDays}
+              noWagonForSelectedDay={noWagonForSelectedDay}
             />
           )}
           {step === 6 && <StepDocuments form={form} />}
@@ -698,6 +754,7 @@ export default function NewBookingPage() {
                 persistAndPriceMutation.isPending &&
                 persistAndPriceMutation.variables?.mode === "submit"
               }
+              noWagonForSelectedDay={noWagonForSelectedDay}
             />
           )}
         </Box>
@@ -746,6 +803,7 @@ export default function NewBookingPage() {
                 leftSection={<Send size={16} />}
                 onClick={handleSubmitBooking}
                 loading={isPricing}
+                disabled={noWagonForSelectedDay}
               >
                 Submit
               </Button>

apps/edr-freight-web/portal/src/pages/bookings/clearance/ClearanceFlow.tsx

@@ -220,12 +220,14 @@ export function ClearanceFlow({ booking, flow, footer }: ClearanceFlowProps) {
             Choose your shipment day
           </Text>
           <Text fz="12px" c="dimmed" mb="sm">
-            Only days with a scheduled departure on your route can be selected.
-            The operations team assigns the specific train for that day.
+            Only days with a scheduled departure that can carry your cargo type
+            can be selected. The operations team assigns the specific train for
+            that day.
           </Text>
           <OperationDatePicker
             originYardId={booking.originYard?.id}
             destinationYardId={booking.destinationYard?.id}
+            bookingId={booking.id}
             value={scheduledDate}
             onChange={setScheduledDate}
           />

apps/edr-freight-web/portal/src/pages/bookings/clearance/OperationDatePicker.tsx

@@ -6,6 +6,8 @@ import { api } from "@/services/api";
 interface OperationDatePickerProps {
   originYardId?: string;
   destinationYardId?: string;
+  /** When set, days are cargo-aware: only days whose train can carry THIS booking's cargo type. */
+  bookingId?: string;
   value: string;
   onChange: (date: string) => void;
 }
@@ -13,20 +15,31 @@ interface OperationDatePickerProps {
 /**
  * Route-based day picker for the operation-request step: a thin query wrapper
  * around the shared presentational `OperationDatePicker` from `@edr/ui-common`.
- * Only days with an OPEN scheduled departure on the route are selectable.
+ * Only days with an OPEN scheduled departure on the route are selectable; with
+ * a `bookingId` the server additionally drops days whose trains have no wagon
+ * type that can carry the booking's cargo (no capacity counts are shown).
  */
 export function OperationDatePicker({
   originYardId,
   destinationYardId,
+  bookingId,
   value,
   onChange,
 }: OperationDatePickerProps) {
-  const { data: availableDays, isLoading } = useQuery(
+  const routeDays = useQuery(
     api.bookings.getAvailableDays.queryOptions({
       input: { originYardId, destinationYardId },
-      enabled: !!originYardId && !!destinationYardId,
+      enabled: !bookingId && !!originYardId && !!destinationYardId,
     }),
   );
+  const bookingDays = useQuery(
+    api.bookings.getAvailableDaysForBooking.queryOptions({
+      input: { bookingId: bookingId ?? "" },
+      enabled: !!bookingId,
+    }),
+  );
+  const availableDays = bookingId ? bookingDays.data : routeDays.data;
+  const isLoading = bookingId ? bookingDays.isLoading : routeDays.isLoading;
 
   return (
     <DatePicker

apps/edr-freight-web/portal/src/pages/bookings/new-booking-form/step4-route.tsx

@@ -1,5 +1,5 @@
 import type { Freight } from "@edr/types";
-import { Box, Skeleton, Stack } from "@mantine/core";
+import { Box, Skeleton, Stack, Text } from "@mantine/core";
 import { DatePickerInput } from "@mantine/dates";
 import { CalendarDays, MapPin, Route as RouteIcon } from "lucide-react";
 import { useCallback, useEffect, useMemo } from "react";
@@ -21,10 +21,19 @@ export function Step4Route({
   form,
   referenceData,
   isLoading,
+  availableDays,
+  noWagonForSelectedDay,
 }: {
   form: BookingForm;
   referenceData?: Freight.BookingReferenceData;
   isLoading?: boolean;
+  /**
+   * Days with a departure whose train can carry the selected cargo type
+   * (wagon-TYPE gate). `undefined` = unknown (loading/failed) — no gating.
+   * Never carries capacity counts.
+   */
+  availableDays?: string[];
+  noWagonForSelectedDay?: boolean;
 }) {
   const originYard = form.watch("originYard");
   const destinationYard = form.watch("destinationYard");
@@ -194,6 +203,16 @@ export function Step4Route({
                     minDate={todayISODate}
                     leftSection={<CalendarDays size={16} />}
                     error={fieldState.error?.message}
+                    // Days whose trains cannot carry the selected cargo type are
+                    // not selectable (wagon-TYPE gate; quantity never blocks).
+                    excludeDate={(date) => {
+                      if (!availableDays) return false;
+                      const day =
+                        typeof date === "string"
+                          ? date.slice(0, 10)
+                          : new Date(date).toISOString().slice(0, 10);
+                      return !availableDays.includes(day);
+                    }}
                     // Mantine v9 DatePickerInput uses string (YYYY-MM-DD) values,
                     // matching the form's `scheduledDate` string directly.
                     value={field.value || null}
@@ -204,6 +223,19 @@ export function Step4Route({
                   />
                 )}
               />
+              {noWagonForSelectedDay && (
+                <Text size="xs" c="red.7" mt={6}>
+                  No wagon on this day&apos;s train can carry your cargo type —
+                  please pick another available day.
+                </Text>
+              )}
+              {availableDays && availableDays.length === 0 && (
+                <Text size="xs" c="red.7" mt={6}>
+                  No upcoming departure can carry this cargo type on the chosen
+                  route right now. Try a different cargo/container type or check
+                  back later.
+                </Text>
+              )}
             </Box>
           )}
         </div>

apps/edr-freight-web/portal/src/pages/bookings/new-booking-form/step8-review.tsx

@@ -137,6 +137,7 @@ export function Step8Review({
   onSubmit,
   saveDraftPending = false,
   submitPending = false,
+  noWagonForSelectedDay = false,
 }: {
   form: BookingForm;
   setStep: (step: number) => void;
@@ -147,6 +148,8 @@ export function Step8Review({
   onSubmit?: () => void;
   saveDraftPending?: boolean;
   submitPending?: boolean;
+  /** Wagon-TYPE gate: the picked day has no train that can carry this cargo. */
+  noWagonForSelectedDay?: boolean;
 }) {
   const values = form.watch();
   const serviceType = referenceData?.service.find(
@@ -551,6 +554,19 @@ export function Step8Review({
                     </p>
                   </AlertBox>
                 </Box>
+              ) : noWagonForSelectedDay ? (
+                <Box mb="md">
+                  <AlertBox tone="error">
+                    <p className="font-semibold">
+                      No wagon available for the selected day
+                    </p>
+                    <p className="mt-1 text-xs">
+                      No train departing that day has a wagon type that can carry
+                      your cargo. Go back to the route step and pick one of the
+                      available days.
+                    </p>
+                  </AlertBox>
+                </Box>
               ) : (
                 <Text size="sm" c="dimmed" mb="md">
                   Ready to submit. You'll review the unit rates before final
@@ -567,7 +583,7 @@ export function Step8Review({
                   leftSection={<Send size={16} />}
                   onClick={onSubmit}
                   loading={submitPending}
-                  disabled={submitPending || hasOdd20ft}
+                  disabled={submitPending || hasOdd20ft || noWagonForSelectedDay}
                 >
                   Submit
                 </Button>

apps/edr-freight-web/portal/src/services/api.ts

@@ -423,6 +423,12 @@ export const api = {
       bookingsService.getAvailableDaysForCargo(input),
     ),
 
+    getAvailableDaysForBooking: endpoint<{ bookingId: string }, string[]>(
+      "train-scheduling",
+      "availableDaysForBooking",
+      ({ bookingId }) => bookingsService.getAvailableDaysForBooking(bookingId),
+    ),
+
     getMyBookingWindows: endpoint<void, MyBookingWindow[]>(
       "train-scheduling",
       "myBookingWindows",

apps/edr-freight-web/portal/src/services/bookings.service.ts

@@ -414,25 +414,38 @@ export const bookingsService = {
     return (data.data as Freight.AvailableDaysResponse).days;
   },
 
-  // Cargo-aware day pool: only days where a train has remaining capacity AND
-  // enough matching-type wagons for this cargo. `containers` is serialized as a
-  // JSON string param (the server parses it).
+  // Cargo-aware day pool: only days where a train has remaining capacity AND a
+  // wagon TYPE that can carry this cargo. `containers`/`containerTypeIds` are
+  // serialized as JSON string params (the server parses them). Days only — no
+  // capacity counts are ever returned.
   getAvailableDaysForCargo: async (
     query: Freight.AvailableDaysForCargoQuery,
   ): Promise<string[]> => {
-    const { containers, ...rest } = query;
+    const { containers, containerTypeIds, ...rest } = query;
     const { data } = await client.get(
       URL_CONSTANTS.TRAIN_SCHEDULING.AVAILABLE_DAYS_FOR_CARGO,
       {
         params: {
           ...rest,
           ...(containers ? { containers: JSON.stringify(containers) } : {}),
+          ...(containerTypeIds?.length
+            ? { containerTypeIds: JSON.stringify(containerTypeIds) }
+            : {}),
         },
       },
     );
     return (data.data as Freight.AvailableDaysResponse).days;
   },
 
+  // Days bookable for an EXISTING booking (operation-request step): the server
+  // derives the cargo from the booking and applies the wagon-type gate.
+  getAvailableDaysForBooking: async (bookingId: string): Promise<string[]> => {
+    const { data } = await client.get(
+      `/api/bookings/${bookingId}/available-days`,
+    );
+    return (data.data as Freight.AvailableDaysResponse).days;
+  },
+
   /**
    * Upcoming/open booking windows on the signed-in customer's active-contract
    * lanes (import booking-day windows + export 24h pre-departure windows).

packages/types/src/freight/contracts.ts

@@ -182,6 +182,42 @@ export interface IContractSignature {
   signedAt: string;
 }
 
+// ── Per-contract document snapshot (staff-editable articles for one contract) ─
+
+export interface IContractDocumentArticle {
+  id: string;
+  title: string;
+  body: string;
+  order: number;
+}
+
+/**
+ * A per-contract frozen copy of the resolved document template. Staff may edit
+ * its articles for a single contract in the accept/edit dialog — this never
+ * writes back to the shared six contract templates. Null → the PDF renders from
+ * the live template.
+ */
+export interface IContractDocumentSnapshot {
+  code?: string | null;
+  name?: string | null;
+  documentTitle?: string | null;
+  whereasClauses: string[];
+  articles: IContractDocumentArticle[];
+}
+
+/** Editable document draft returned for the accept/edit editor. */
+export interface IContractDocumentDraft {
+  documentTitle: string | null;
+  whereasClauses: string[];
+  articles: IContractDocumentArticle[];
+  code: string | null;
+  name: string | null;
+  /** True once the document may no longer be edited/regenerated. */
+  locked: boolean;
+  generatedAt: string | null;
+  status: ContractStatus;
+}
+
 export type ContractApprovalStepStatus =
   | "PENDING"
   | "APPROVED"
@@ -584,6 +620,8 @@ export interface IContract extends BaseEntity {
   contractType?: string | null;
   contractTemplateKey?: string | null;
   contractGeneratedAt?: string | null;
+  /** Per-contract frozen document (articles + WHEREAS) captured at staff accept. */
+  documentSnapshot?: IContractDocumentSnapshot | null;
   contractSummary?: string | null;
   versionNumber: number;
   financialTerms?: string | null;

packages/types/src/freight/index.ts

@@ -231,7 +231,8 @@ export enum WagonStatus {
   ImportReady = "IMPORT_READY",
   ExportReady = "EXPORT_READY",
   Maintenance = "MAINTENANCE",
-  Retired = "RETIRED",
+  /** Formerly RETIRED — wagons pulled from circulation. */
+  Detained = "DETAINED",
 }
 
 export enum WagonReadiness {
@@ -359,6 +360,8 @@ export interface IWagonTransferRequest extends BaseEntity {
   requestedByUserId?: string | null;
   fulfilledByUserId?: string | null;
   fulfilledAt?: string | null;
+  /** Why the wagons are needed — required for new requests, shown on the OCC queue. */
+  reason?: string | null;
   note?: string | null;
 }
 
@@ -923,10 +926,14 @@ export interface AvailableDaysForCargoQuery {
   freightType: "CONTAINER" | "BULK";
   /** Bulk cargo type code (e.g. "COFFEE"); ignored for container freight. */
   cargoTypeCode?: string;
+  /** Bulk cargo type id — preferred over code for the wagon-type gate. */
+  cargoTypeId?: string;
   /** Total bulk weight in tons. */
   totalWeightTons?: number;
   /** Container lines (size + quantity) for container freight. */
   containers?: { containerSize: string; quantity: number }[];
+  /** Container type ids — enables the exact wagon-type compatibility gate. */
+  containerTypeIds?: string[];
 }
 
 /**