changes

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[];
 }
 
 /**