@openlup/platform 0.23.0 → 0.24.0

package/src/invoicing/contracts/facts.ts

@@ -48,7 +48,7 @@ export interface InvoiceFacts {
   readonly clearanceRequired: boolean;
   readonly currency: string;
   readonly buyer: InvoiceBuyer;
-  /** Supplied separately for execution; P8 freezes it at first claim before provider I/O. */
+  /** Claim projection only: the first durable claim freezes the seller; legacy obligations retain execution-time fallback. */
   readonly seller?: InvoiceSeller;
   readonly payment: { readonly intentRef: string; readonly providerRef: string | null; readonly providerPaymentRef: string | null; readonly amountMinor: number; readonly currency: string; readonly localSettlementState: "matched" | "unavailable" };
   readonly orderMoney: { readonly subtotalMinor: number; readonly discountMinor: number; readonly shippingMinor: number; readonly shippingDiscountMinor: number; readonly totalMinor: number } | null;
@@ -58,3 +58,14 @@ export interface InvoiceFacts {
   readonly totalGrossMinor: number;
   readonly chargedTotalGrossMinor: number;
 }
+
+/** Host-selected immutable revision; it contains no provider or country defaults. */
+export interface InvoiceSellerRevision<Seller = InvoiceSeller> {
+  readonly seller: Seller;
+  readonly revisionRef: string;
+}
+/** Added only to returned claim facts, never to installed historical revisions. */
+export interface InvoiceClaimedFacts extends InvoiceFacts {
+  readonly sellerRevision?: string;
+  readonly sellerMode?: "frozen" | "legacy_fallback";
+}

package/src/invoicing/contracts/host.ts

@@ -12,8 +12,8 @@ import type { InvoiceStorePort } from "./store.js";
 export interface InvoiceHostPorts {
   facts: { read(orderId: string): Promise<{ readonly kind: "found"; readonly facts: InvoiceFacts } | { readonly kind: "unknown"; readonly code: "missing_facts" } | InvoiceUnsupported> };
   /** Read the current host seller for the next claim, never per duty. Null orderId
-   * means an unscoped claim (including corrections). P8 freezes this seller at
-   * first claim; revisionRef feeds the claim wrapper's revision argument.
+   * means an unscoped claim (including corrections). The durable wrapper freezes this seller at
+   * the first-ever claim; revisionRef feeds the claim wrapper's revision argument.
    */
   seller: { read(input: { readonly orderId: string | null }): Promise<{ readonly kind: "found"; readonly seller: InvoiceSeller; readonly revisionRef: string } | { readonly kind: "unknown"; readonly code: "unknown" } | InvoiceUnsupported> };
   /** Read-only projection of the final claimed M07 identity, never a refund writer.
@@ -71,8 +71,7 @@ export interface InvoiceHostPorts {
     resolveDownload(input: { readonly accountRef: string; readonly orderId: string; readonly documentRef: string }): Promise<{ readonly kind: "authorized"; readonly identity: InvoiceDocumentIdentity; readonly artifactRef: string; readonly fileName: string; readonly parentDocumentRef: string | null } | { readonly kind: "denied" } | { readonly kind: "unknown"; readonly code: "unknown" } | InvoiceUnsupported>;
   };
 }
-/** Future service composition inputs only; no constructor, worker or runtime route
- * is supplied in P1. Closures/credentials must never be serialized with options.
+/** Explicit service composition inputs; the host retains worker and route authority. Closures/credentials must never be serialized with options.
  */
 export interface InvoiceServicesOptions {
   readonly enabled?: boolean;

package/src/invoicing/contracts/index.ts

@@ -1,5 +1,5 @@
 /** @consumer Frozen fact provider and installed declaration consumer. */
-export type { InvoiceFacts, InvoiceLine, InvoiceSeller, InvoiceBuyer } from "./facts.js";
+export type { InvoiceFacts, InvoiceLine, InvoiceSeller, InvoiceBuyer, InvoiceSellerRevision, InvoiceClaimedFacts } from "./facts.js";
 /** @consumer A4 issue/correction bridge, adapters and operator proof readback. */
 export type { InvoiceIdentity, InvoiceDocumentIdentity, InvoiceWriteResult, InvoiceReadbackResult, InvoiceProviderPort, InvoiceUnsupported, InvoiceDiagnosticCode, InvoiceProof } from "./provider.js";
 /** @consumer Host artifact storage/download binding. */

package/src/invoicing/contracts/store.ts

@@ -1,5 +1,5 @@
 import type { InvoiceHostPorts } from "./host.js";
-import type { InvoiceFacts } from "./facts.js";
+import type { InvoiceFacts, InvoiceClaimedFacts } from "./facts.js";
 import type { InvoiceIdentity, InvoiceDocumentIdentity, InvoiceProof, InvoiceUnsupported, InvoiceWriteResult, InvoiceReadbackResult } from "./provider.js";
 import type { InvoiceClearanceObservation, InvoiceArtifactResult, InvoiceDeliveryPort } from "./delivery.js";
 type InvoiceDutyStatus = "owed" | "blocked" | "ready" | "processing" | "unknown" | "issued" | "voided" | "unsupported" | "faulted";
@@ -14,7 +14,7 @@ export interface InvoiceClaim {
   readonly generation: number;
   readonly leaseUntil: string;
   readonly identity: InvoiceIdentity;
-  readonly facts: InvoiceFacts;
+  readonly facts: InvoiceClaimedFacts;
   readonly action: "create" | "readback";
   readonly correction: { readonly before: InvoiceFacts; readonly reason: string; readonly after: { readonly totalNetMinor: 0; readonly totalTaxMinor: 0; readonly totalGrossMinor: 0 } } | null;
 }
@@ -40,14 +40,15 @@ export interface InvoiceDutyReadback {
 }
 /** Every operation is one local transaction; commit before external I/O. Native
  * success atomically saves late identity and compensation; stale catch writes nothing.
- * Managed and native stores are bound to the selected provider at construction.
+ * Compatibility stores bind provider selection at construction; the structural
+ * native store accepts it per claim and persists the first provider on the duty.
  * No implementation, executor or migration is installed by these declarations.
  */
 export interface InvoiceStorePort {
   /** Never call inside a renewal money, dunning or dispatch transaction without
    * isolation: capture failure must not propagate; the sweep recovers.
    */
-  captureDuty(input: { readonly requestKey: string; readonly sourceKind: "paid" | "handoff"; readonly sourceId: string; readonly orderId: string; readonly occurredAt: string; readonly evidence: { readonly settlementIntentId: string; readonly amountMinor: number; readonly currency: string } | { readonly shipmentId: string; readonly handedOverAt: string } }): Promise<{ readonly dutyId: string; readonly status: InvoiceDutyStatus } | InvoiceUnsupported>;
+  captureDuty(input: { readonly requestKey: string; readonly sourceKind: "paid" | "handoff"; readonly sourceId: string; readonly orderId: string; readonly occurredAt: string; readonly evidence: { readonly settlementIntentId: string; readonly amountMinor: number; readonly currency: string } | { readonly shipmentId: string; readonly handedOverAt: string } }): Promise<{ readonly dutyId: string; readonly status: InvoiceDutyStatus } | { readonly kind: "conflict"; readonly code: "identity_mismatch" } | InvoiceUnsupported>;
   installFacts(input: { readonly dutyId: string; readonly facts: InvoiceFacts }): Promise<{ readonly dutyId: string; readonly status: InvoiceDutyStatus; readonly replayed?: boolean } | InvoiceUnsupported>;
   /** Pinned split facts lease: sweep and prepare commit separately; finishing
    * requires the same token and authoritative document/fact match. No host I/O
@@ -58,7 +59,7 @@ export interface InvoiceStorePort {
   finishFacts(input: { readonly dutyId: string; readonly token: string; readonly result: Omit<Exclude<Awaited<ReturnType<InvoiceStorePort["prepareFacts"]>>, InvoiceUnsupported>, "status"> & { readonly status: "owed" | "ready" | "issued" | "voided" | "unsupported" } }): Promise<{ readonly dutyId: string; readonly status: "owed" | "ready" | "issued" | "voided" | "unsupported" | "faulted" | "stale" } | InvoiceUnsupported>;
   readDuties(orderId: string): Promise<InvoiceDutyReadback | InvoiceUnsupported>;
   /** Filter order before locking/limit; never lease unrelated orders then filter.
-   * P8 reads the injected host seller before calling the first-claim SQL wrapper;
+   * P7 host composition reads the injected seller before the separate first-claim SQL wrapper;
    * its revisionRef supplies p_revision, without requiring a duty from the caller.
    */
   claim(input: { readonly limit: number; readonly visibilitySeconds: number; readonly providerRef: string; readonly orderId?: string | null }): Promise<readonly InvoiceClaim[] | InvoiceUnsupported>;
@@ -80,7 +81,7 @@ export interface InvoiceStorePort {
    * Missing means no M09 duty, never invoice absence: retain/retry the reversal
    * intent and route legacy documents to the incumbent path.
    */
-  requestReversal(input: { readonly requestKey: string; readonly orderId: string; readonly reason: "order_canceled" | "order_refunded"; readonly proof: InvoiceProof }): Promise<{ readonly kind: "missing" | "voided" | "pending_readback" | "correction_requested"; readonly dutyId?: string; readonly replayed?: boolean } | { readonly kind: "unsupported_recorded"; readonly dutyId?: string; readonly replayed?: boolean } | InvoiceUnsupported>;
+  requestReversal(input: { readonly requestKey: string; readonly orderId: string; readonly reason: "order_canceled" | "order_refunded"; readonly proof: InvoiceProof }): Promise<{ readonly kind: "missing" | "voided" | "pending_readback" | "correction_requested"; readonly dutyId?: string; readonly replayed?: boolean } | { readonly kind: "unsupported_recorded"; readonly dutyId?: string; readonly replayed?: boolean } | { readonly kind: "conflict"; readonly code: "identity_mismatch" } | InvoiceUnsupported>;
   /** Existing local-only request remains distinct from fiscal issuance. */
   requestLocalDocument(input: { readonly requestKey: string; readonly orderId: string; readonly providerRef: string }): Promise<{ readonly kind: "requested"; readonly documentId: string; readonly invoiceRef: string; readonly status: string; readonly replayed: boolean } | InvoiceUnsupported>;
   listClearanceTargets(limit: number): Promise<readonly { readonly documentId: string; readonly identity: InvoiceDocumentIdentity; readonly providerDocumentRef: string; readonly providerDocumentNumber: string | null; readonly state: InvoiceClearanceObservation["state"] }[] | InvoiceUnsupported>;
@@ -92,7 +93,10 @@ export interface InvoiceStorePort {
   claimDeliveries(input: { readonly limit: number; readonly visibilitySeconds: number; readonly requireClearance: boolean; readonly orderId?: string | null }): Promise<readonly { readonly token: string; readonly generation: number; readonly identity: InvoiceDocumentIdentity; readonly providerDocumentRef: string; readonly delivery: Omit<Parameters<InvoiceDeliveryPort["send"]>[0], "filename" | "content" | "contentType"> }[] | InvoiceUnsupported>;
   /** Native uncertain settlement passes p_receipt NULL and retains a non-null
    * receiptRef hint in p_evidence; managed uses it as the provider message id.
-   * Managed failed_before_send uses retrySeconds for backoff; native ignores it.
+   * Managed failed_before_send uses the retrySeconds RPC argument. Native
+   * failed_before_send carries { phase: 'before_send', retryable, retrySeconds }
+   * in p_evidence: whole seconds clamp to 60..86400, absent/invalid uses 900.
+   * retryable:false parks at infinity, with failed status and last_error visible.
    */
   settleDelivery(input: { readonly deliveryRef: string; readonly token: string; readonly generation: number; readonly providerDocumentRef: string; readonly retrySeconds: number; readonly result: Exclude<Awaited<ReturnType<InvoiceDeliveryPort["send"]>>, InvoiceUnsupported> }): Promise<{ readonly kind: "recorded" | "stale"; readonly replayed: boolean } | InvoiceUnsupported>;
 }

package/src/invoicing/contribution.ts

@@ -0,0 +1,28 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+
+/** Inert descriptors for the host's existing registry and executor. No registration. */
+export function createInvoiceContribution(input: {
+  version: string;
+  requiredSchema: RequiredSchema;
+  invoicing: Readonly<Record<string, ((...args: never[]) => unknown) | null>>;
+  handlers: Contribution["handlers"];
+  schedules: Contribution["schedules"];
+  routes: Contribution["routes"];
+}) {
+  const contribution: Contribution = {
+    manifest: {
+      name: "@openlup/platform", version: input.version, kind: "rail",
+      module: { id: "invoicing", kind: "capability", provides: ["./invoicing"], dependsOn: [] },
+      emits: [], handles: input.handlers.map(handler => handler.eventType), env: [],
+      schedules: input.schedules.map(({ id, cadenceSeconds }) => ({ id, cadenceSeconds })),
+      requiredPorts: Object.keys(input.invoicing), routes: input.routes.map(route => route.id), requiredSchema: input.requiredSchema,
+    },
+    handlers: input.handlers, schedules: input.schedules, routes: input.routes,
+  };
+  return {
+    contributions: [contribution],
+    ports: Object.fromEntries(Object.entries(input.invoicing).filter(([, fn]) => typeof fn === "function").map(([name, fn]) => [`@openlup/platform/invoicing:${name}`, fn])),
+    routes: Object.fromEntries(input.routes.map(route => [`@openlup/platform/invoicing:${route.id}`, route.handle])),
+    triggers: Object.fromEntries(input.schedules.map(schedule => [`@openlup/platform/invoicing:${schedule.id}`, schedule.run])),
+  };
+}

package/src/invoicing/correction.ts

@@ -0,0 +1,56 @@
+import type { InvoiceWriteResult } from "./contracts/provider.js";
+
+/** Durable correction identity, recovery and claim fencing from the donor worker.
+ * Hosts project immutable BEFORE facts and bind a conforming recovery provider.
+ * @consumer server/domains/accounting/accountingJobService.ts
+ */
+export async function runInvoiceCorrectionJob<Claim extends {
+  outboxId: string; attemptCount: number; providerInvoiceId: string;
+  correctionReason: string; payload: Record<string, unknown>;
+}, Snapshot, Result extends Pick<Extract<InvoiceWriteResult, { kind: "issued" }>, "providerDocumentRef" | "providerDocumentNumber">>(input: {
+  createEnabled: boolean;
+  providerEnabled: boolean;
+  claim(): Promise<readonly Claim[]>;
+  project(claim: Claim): Snapshot;
+  /** Resolve accepted/recovered receipts only; unknown is never an ACK or absence. */
+  create(snapshot: Snapshot, options: {
+    correctionReason: string; correctedProviderInvoiceId: string;
+    correctionRef: string; recoveryLookupRequired: boolean;
+  }): Promise<Result>;
+  finish(claim: Claim, result: Result): Promise<unknown>;
+  isClaimFenceError(error: unknown): boolean;
+  fail(claim: Claim, error: unknown, retrySeconds: number): Promise<unknown>;
+}) {
+  if (!input.createEnabled) return skipped("create_disabled");
+  if (!input.providerEnabled) return skipped("provider_disabled");
+  const claims = await input.claim();
+  let updated = 0;
+  let failures = 0;
+  for (const claim of claims) {
+    try {
+      const correctionRef = `accounting-correction:${claim.outboxId}`;
+      if (claim.payload.providerCreateIdentity !== correctionRef) {
+        throw new Error("accounting_correction_recovery_identity_missing");
+      }
+      const snapshot = input.project(claim);
+      const result = await input.create(snapshot, {
+        correctionReason: claim.correctionReason,
+        correctedProviderInvoiceId: claim.providerInvoiceId,
+        correctionRef,
+        recoveryLookupRequired: claim.attemptCount > 1,
+      });
+      await input.finish(claim, result);
+      updated += 1;
+    } catch (error) {
+      failures += 1;
+      if (input.isClaimFenceError(error)) continue;
+      try {
+        await input.fail(claim, error, Math.min(3600, 300 * Math.max(1, claim.attemptCount)));
+      } catch (failureError) {
+        if (!input.isClaimFenceError(failureError)) throw failureError;
+      }
+    }
+  }
+  return { ok: failures === 0, checked: claims.length, updated, skipped: false, failures };
+}
+function skipped(reason: string) { return { ok: true, checked: 0, updated: 0, skipped: true, reason, failures: 0 }; }

package/src/invoicing/delivery.ts

@@ -0,0 +1,122 @@
+import type { InvoiceUnsupported } from "./contracts/provider.js";
+import type { InvoiceStorePort } from "./contracts/store.js";
+import type { InvoiceDeliveryPort } from "./contracts/delivery.js";
+import { assertInvoicePdf } from "./artifacts.js";
+
+type DeliveryOutcome = Omit<Extract<Awaited<ReturnType<InvoiceDeliveryPort["send"]>>, { kind: "provider_accepted" }>, "proof">
+  | Exclude<Awaited<ReturnType<InvoiceDeliveryPort["send"]>>, { kind: "provider_accepted" }>;
+
+/** Donor sequencing over host claims, original keys, M04 transport and fenced
+ * finalizers. Native hosts MUST bind terminalFailure before leasing work.
+ * With CTL-M09-3's 191000 pin, failedBeforeSend settles failed_before_send with
+ * evidence { phase: 'before_send', retrySeconds }: whole seconds clamped
+ * to 60..86400, absent/invalid uses 900;
+ * terminalFailure uses { phase: 'before_send', retryable: false } for no reclaim.
+ * Native store mode refuses before claim unless its host projection is bound.
+ * @consumer Host delivery facade and explicit native M04 binding.
+ */
+type DeliveryJobInput<Claim, Result extends DeliveryOutcome> = {
+  enabled: boolean;
+  providerEnabled: boolean;
+  deliveryEnabled: boolean;
+  claim(): Promise<readonly Claim[] | InvoiceUnsupported>;
+  attemptCount(claim: Claim): number;
+  validate(claim: Claim): void;
+  download(claim: Claim): Promise<{ content: Uint8Array; contentType: string }>;
+  filename(claim: Claim): string;
+  /** A rejected promise proves failure BEFORE transport entry. Once entered,
+   * the M04 binding must return uncertain, including timeout/lost ACK. */
+  send(claim: Claim, document: { filename: string; content: Uint8Array; contentType: string }): Promise<Result>;
+  failedBeforeSend(claim: Claim, error: unknown, retrySeconds: number): Promise<unknown>;
+  /** Must durably stop reclaim using the same fence. Native failed_before_send
+   * evidence { phase: 'before_send', retryable: false } sets available_at to infinity. */
+  terminalFailure(claim: Claim, result: Extract<Result, { kind: "failed_before_send" | "unsupported" }>): Promise<unknown>;
+  uncertain(claim: Claim, result: Extract<Result, { kind: "uncertain" }>): Promise<unknown>;
+  accepted(claim: Claim, result: Extract<Result, { kind: "provider_accepted" }>): Promise<unknown>;
+  finalizeUncertain(claim: Claim, receiptRef: string): Promise<unknown>;
+};
+type NativeClaim = Exclude<Awaited<ReturnType<InvoiceStorePort["claimDeliveries"]>>, InvoiceUnsupported>[number];
+type NativeDeliveryJobInput = {
+  enabled: boolean;
+  providerEnabled: boolean;
+  deliveryEnabled: boolean;
+  store: Pick<InvoiceStorePort, "claimDeliveries" | "settleDelivery">;
+  claimOptions: Parameters<InvoiceStorePort["claimDeliveries"]>[0];
+  download(claim: NativeClaim): Promise<{ content: Uint8Array; contentType: string }>;
+  filename(claim: NativeClaim): string;
+  send: InvoiceDeliveryPort["send"];
+};
+/** Host callback mode preserves donor sequencing. Native store mode supplies
+ * fenced terminal/backoff finalizers and the M04 envelope from claimDeliveries.
+ * @consumer Host delivery facade and explicit native M04 binding.
+ */
+export function runInvoiceDeliveryJob(input: NativeDeliveryJobInput): ReturnType<typeof runDeliveryJob>;
+export function runInvoiceDeliveryJob<Claim, Result extends DeliveryOutcome>(input: DeliveryJobInput<Claim, Result>): ReturnType<typeof runDeliveryJob>;
+export function runInvoiceDeliveryJob<Claim, Result extends DeliveryOutcome>(input: NativeDeliveryJobInput | DeliveryJobInput<Claim, Result>): ReturnType<typeof runDeliveryJob> {
+  if (!("store" in input)) return runDeliveryJob(input);
+  const settle = async (claim: NativeClaim, result: Parameters<InvoiceStorePort["settleDelivery"]>[0]["result"], retrySeconds = 900) => {
+    const outcome = await input.store.settleDelivery({ deliveryRef: claim.delivery.deliveryRef, token: claim.token,
+      generation: claim.generation, providerDocumentRef: claim.providerDocumentRef, retrySeconds, result });
+    if (outcome.kind !== "recorded") throw new Error("invoicing_delivery_fence");
+  };
+  return runDeliveryJob<NativeClaim, Awaited<ReturnType<InvoiceDeliveryPort["send"]>>>({
+    enabled: input.enabled, providerEnabled: input.providerEnabled, deliveryEnabled: input.deliveryEnabled,
+    claim: () => input.store.claimDeliveries(input.claimOptions), attemptCount: claim => claim.generation,
+    validate: () => {}, download: input.download, filename: input.filename,
+    send: (claim, document) => input.send({ ...claim.delivery, ...document }),
+    failedBeforeSend: (claim, _error, retrySeconds) => settle(claim, { kind: "failed_before_send", retryable: true, code: "retryable" }, retrySeconds),
+    terminalFailure: (claim, result) => settle(claim, result.kind === "failed_before_send" ? result
+      : { kind: "failed_before_send", retryable: false, code: "retryable" }),
+    uncertain: (claim, result) => settle(claim, result), accepted: (claim, result) => settle(claim, result),
+    finalizeUncertain: (claim, receiptRef) => settle(claim, { kind: "uncertain", code: "uncertain_delivery", receiptRef }),
+  });
+}
+async function runDeliveryJob<Claim, Result extends DeliveryOutcome>(input: DeliveryJobInput<Claim, Result>) {
+  if (!input.enabled) return skipped("provider_email_disabled");
+  if (!input.providerEnabled) return skipped("provider_disabled");
+  if (!input.deliveryEnabled) return skipped("email_delivery_provider_disabled");
+  // JS hosts missing a mandatory terminal policy must refuse before claiming.
+  if (typeof input.terminalFailure !== "function") return skipped("host_binding_required");
+  const claims = await input.claim();
+  if (!Array.isArray(claims)) return skipped("host_binding_required");
+  let updated = 0;
+  let failures = 0;
+  for (const claim of claims as readonly Claim[]) {
+    let result: Result;
+    const retrySeconds = Math.min(3600, 300 * Math.max(1, input.attemptCount(claim)));
+    try {
+      input.validate(claim);
+      const pdf = await input.download(claim);
+      assertInvoicePdf(pdf);
+      result = await input.send(claim, { ...pdf, filename: input.filename(claim) });
+    } catch (error) {
+      failures += 1;
+      await input.failedBeforeSend(claim, error, retrySeconds);
+      continue;
+    }
+    if (result.kind === "failed_before_send" || result.kind === "unsupported") {
+      failures += 1;
+      if (result.kind === "failed_before_send" && result.retryable) {
+        await input.failedBeforeSend(claim, result, retrySeconds);
+      } else {
+        await input.terminalFailure(claim, result as Extract<Result, { kind: "failed_before_send" | "unsupported" }>);
+      }
+      continue;
+    }
+    if (result.kind === "uncertain") {
+      failures += 1;
+      await input.uncertain(claim, result as Extract<Result, { kind: "uncertain" }>);
+      continue;
+    }
+    try {
+      await input.accepted(claim, result as Extract<Result, { kind: "provider_accepted" }>);
+      updated += 1;
+    } catch {
+      failures += 1;
+      // Acceptance plus a lost local ACK cannot become a retryable send.
+      await input.finalizeUncertain(claim, result.receiptRef).catch(() => undefined);
+    }
+  }
+  return { ok: failures === 0, checked: claims.length, updated, skipped: false, failures };
+}
+function skipped(reason: string) { return { ok: true, checked: 0, updated: 0, skipped: true, reason, failures: 0 }; }

package/src/invoicing/documentHistory.ts

@@ -0,0 +1,301 @@
+type InvoiceDocumentRole = "original" | "correction" | "replacement";
+type InvoiceDocumentArtifact = "invoice" | "correction";
+type InvoiceDocumentEmailState = "not_requested" | "pending" | "provider_accepted" | "failed";
+
+type InvoiceDocumentHistoryRow = Record<string, unknown>;
+
+interface InvoiceDocumentHistoryEntry {
+  documentKey: string;
+  invoiceId: string;
+  parentDocumentRef: string | null;
+  orderId: string;
+  invoiceRef: string;
+  role: InvoiceDocumentRole;
+  artifact: InvoiceDocumentArtifact;
+  status: string;
+  blockedReason: string | null;
+  documentKind: string | null;
+  providerKind: string | null;
+  providerDocumentRef: string | null;
+  providerDocumentNumber: string | null;
+  clearanceReference: string | null;
+  clearanceState: string;
+  totalGrossMinor: number | null;
+  /**
+   * The currency the document was **issued in**, copied from
+   * `accounting_invoices.currency` (`NOT NULL CHECK (char_length = 3)`).
+   *
+   * It travels with the amount rather than being resolved by whoever renders it. An
+   * issued invoice is the most historical money the platform holds: it is a document
+   * of record whose denomination was fixed the day it was written, and a reader that
+   * asked the current settlement profile instead would re-label the customer's own
+   * accounting the first time a deployment changed what it sells in.
+   */
+  currency: string;
+  issuedAt: string | null;
+  createdAt: string;
+  isCurrent: boolean;
+  downloadAvailable: boolean;
+  emailState: InvoiceDocumentEmailState;
+}
+
+interface InvoiceDocumentHistory {
+  current: InvoiceDocumentHistoryEntry | null;
+  documents: InvoiceDocumentHistoryEntry[];
+}
+
+interface ResolveInvoiceDocumentHistoryInput {
+  invoices: InvoiceDocumentHistoryRow[];
+  operations?: InvoiceDocumentHistoryRow[];
+  deliveryOutboxes?: InvoiceDocumentHistoryRow[];
+  providerArtifactEligible?: (providerKind: string) => boolean;
+}
+
+const CURRENT_STATUSES = new Set(["issued", "accepted"]);
+const HISTORICAL_INVOICE_STATUSES = new Set(["issued", "accepted", "corrected"]);
+
+export function resolveInvoiceDocumentHistory({
+  invoices,
+  operations = [],
+  deliveryOutboxes = [],
+  providerArtifactEligible = () => true,
+}: ResolveInvoiceDocumentHistoryInput): InvoiceDocumentHistory {
+  const orderedInvoices = [...invoices].sort(compareRowsChronologically);
+  const correctionOperations = operations.filter((row) => text(row.operation) === "correction_issued");
+  const activeInvoice = [...orderedInvoices]
+    .filter((row) => currentInvoiceEligible(row, providerArtifactEligible))
+    .sort(compareRowsNewestFirst)[0] ?? null;
+  const activeInvoiceId = activeInvoice ? text(activeInvoice.id) : null;
+  const documents: InvoiceDocumentHistoryEntry[] = [];
+
+  for (const invoice of orderedInvoices) {
+    const invoiceId = text(invoice.id);
+    const replacement = nullableText(invoice.correction_of_invoice_id) !== null;
+    const providerDocumentRef = nullableText(invoice.provider_document_ref);
+    documents.push({
+      documentKey: `invoice:${invoiceId}`,
+      invoiceId,
+      parentDocumentRef: replacement ? `invoice:${nullableText(invoice.correction_of_invoice_id)}` : null,
+      orderId: text(invoice.order_id),
+      invoiceRef: text(invoice.invoice_ref),
+      role: replacement ? "replacement" : "original",
+      artifact: "invoice",
+      status: text(invoice.status),
+      blockedReason: nullableText(invoice.blocked_reason),
+      documentKind: nullableText(invoice.document_kind),
+      providerKind: nullableText(invoice.provider_kind),
+      providerDocumentRef,
+      providerDocumentNumber: nullableText(invoice.provider_document_number),
+      clearanceReference: nullableText(invoice.clearance_reference),
+      clearanceState: text(invoice.clearance_state),
+      totalGrossMinor: nonnegativeNumber(invoice.total_gross_minor),
+      currency: text(invoice.currency),
+      issuedAt: nullableText(invoice.created_at),
+      createdAt: text(invoice.created_at),
+      isCurrent: invoiceId === activeInvoiceId,
+      downloadAvailable: historicalInvoiceDownloadEligible(invoice, providerArtifactEligible),
+      emailState: resolveEmailState({
+        invoice,
+        providerDocumentRef,
+        operations,
+        deliveryOutboxes,
+        preferInvoiceFallback: !correctionProviderDocumentRef(invoice),
+      }),
+    });
+
+    const correctionProviderId = correctionProviderDocumentRef(invoice);
+    if (!correctionProviderId) continue;
+    const correctionOperation = correctionOperations
+      .filter((row) => text(row.invoice_id) === invoiceId)
+      .sort(compareRowsNewestFirst)[0] ?? null;
+    const correctionNumber = correctionProviderDocumentNumber(invoice);
+    const correctionCreatedAt = nullableText(correctionOperation?.created_at)
+      ?? laterTimestamp(text(invoice.updated_at), text(invoice.created_at));
+    const providerKind = nullableText(invoice.provider_kind);
+    const persistedCorrectionStatus = normalize(invoice.correction_status);
+    const correctionStatus = ["issued", "accepted"].includes(persistedCorrectionStatus)
+      ? persistedCorrectionStatus
+      : "not_ready";
+    documents.push({
+      documentKey: `correction:${invoiceId}`,
+      invoiceId,
+      parentDocumentRef: `invoice:${invoiceId}`,
+      orderId: text(invoice.order_id),
+      invoiceRef: correctionNumber ?? `correction-${text(invoice.invoice_ref)}`.slice(0, 160),
+      role: "correction",
+      artifact: "correction",
+      status: correctionStatus,
+      blockedReason: nullableText(invoice.blocked_reason),
+      documentKind: "correction",
+      providerKind,
+      providerDocumentRef: correctionProviderId,
+      providerDocumentNumber: correctionNumber,
+      clearanceReference: null,
+      clearanceState: "not_required",
+      totalGrossMinor: null,
+      // A correction has no total of its own on this row, but it is a document of the
+      // same invoice and therefore of the same currency. Stating it keeps the field
+      // total, so a consumer never has to ask "which document has a currency?".
+      currency: text(invoice.currency),
+      issuedAt: correctionCreatedAt || null,
+      createdAt: correctionCreatedAt,
+      isCurrent: false,
+      downloadAvailable: Boolean(
+        providerKind
+        && providerArtifactEligible(providerKind)
+        && nullableText(invoice.blocked_reason) === null
+        && ["issued", "accepted"].includes(correctionStatus),
+      ),
+      emailState: resolveEmailState({
+        invoice,
+        providerDocumentRef: correctionProviderId,
+        operations,
+        deliveryOutboxes,
+        preferInvoiceFallback: true,
+      }),
+    });
+  }
+
+  documents.sort(compareDocumentsChronologically);
+  return {
+    current: documents.find((document) => document.isCurrent) ?? null,
+    documents,
+  };
+}
+
+function currentInvoiceEligible(
+  row: InvoiceDocumentHistoryRow,
+  providerArtifactEligible: (providerKind: string) => boolean,
+): boolean {
+  const providerKind = nullableText(row.provider_kind);
+  return Boolean(
+    providerKind
+    && providerArtifactEligible(providerKind)
+    && nullableText(row.provider_document_ref)
+    && nullableText(row.blocked_reason) === null
+    && CURRENT_STATUSES.has(normalize(row.status)),
+  );
+}
+
+function historicalInvoiceDownloadEligible(
+  row: InvoiceDocumentHistoryRow,
+  providerArtifactEligible: (providerKind: string) => boolean,
+): boolean {
+  const providerKind = nullableText(row.provider_kind);
+  return Boolean(
+    providerKind
+    && providerArtifactEligible(providerKind)
+    && nullableText(row.provider_document_ref)
+    && nullableText(row.blocked_reason) === null
+    && HISTORICAL_INVOICE_STATUSES.has(normalize(row.status)),
+  );
+}
+
+function resolveEmailState({
+  invoice,
+  providerDocumentRef,
+  operations,
+  deliveryOutboxes,
+  preferInvoiceFallback,
+}: {
+  invoice: InvoiceDocumentHistoryRow;
+  providerDocumentRef: string | null;
+  operations: InvoiceDocumentHistoryRow[];
+  deliveryOutboxes: InvoiceDocumentHistoryRow[];
+  preferInvoiceFallback: boolean;
+}): InvoiceDocumentEmailState {
+  if (!providerDocumentRef) return "not_requested";
+  const invoiceId = text(invoice.id);
+  const accepted = operations.some((row) => {
+    if (text(row.invoice_id) !== invoiceId || text(row.operation) !== "provider_email_sent") return false;
+    const payloadProviderId = nullableText(record(row.payload).providerDocumentRef);
+    return (payloadProviderId ?? nullableText(row.provider_ref)) === providerDocumentRef;
+  });
+  if (accepted) return "provider_accepted";
+
+  const outbox = deliveryOutboxes
+    .filter((row) => text(row.invoice_id) === invoiceId)
+    .filter((row) => {
+      const targetProviderId = nullableText(record(row.metadata).providerDocumentRef);
+      return targetProviderId ? targetProviderId === providerDocumentRef : preferInvoiceFallback;
+    })
+    .sort(compareRowsNewestFirst)[0];
+  const outboxStatus = normalize(outbox?.status);
+  if (["failed", "uncertain", "cancelled"].includes(outboxStatus)) return "failed";
+  if (["pending", "processing", "queued"].includes(outboxStatus)) return "pending";
+  if (outboxStatus === "succeeded") return "provider_accepted";
+
+  if (preferInvoiceFallback) {
+    const emailStatus = normalize(invoice.email_status);
+    if (emailStatus === "failed") return "failed";
+    if (emailStatus === "pending") return "pending";
+    if (emailStatus === "sent") return "provider_accepted";
+  }
+  return "not_requested";
+}
+
+function correctionProviderDocumentRef(row: InvoiceDocumentHistoryRow): string | null {
+  return nullableText(record(row.metadata).correctionProviderDocumentRef);
+}
+
+function correctionProviderDocumentNumber(row: InvoiceDocumentHistoryRow): string | null {
+  return nullableText(record(row.metadata).correctionProviderDocumentNumber);
+}
+
+function compareRowsChronologically(a: InvoiceDocumentHistoryRow, b: InvoiceDocumentHistoryRow): number {
+  return compareTimestamps(a.created_at, b.created_at) || text(a.id).localeCompare(text(b.id));
+}
+
+function compareRowsNewestFirst(a: InvoiceDocumentHistoryRow, b: InvoiceDocumentHistoryRow): number {
+  return compareTimestamps(b.created_at ?? b.updated_at, a.created_at ?? a.updated_at) || text(b.id).localeCompare(text(a.id));
+}
+
+function compareDocumentsChronologically(a: InvoiceDocumentHistoryEntry, b: InvoiceDocumentHistoryEntry): number {
+  return compareTimestamps(a.createdAt, b.createdAt)
+    || documentRolePriority(a.role) - documentRolePriority(b.role)
+    || a.documentKey.localeCompare(b.documentKey);
+}
+
+function documentRolePriority(role: InvoiceDocumentRole): number {
+  if (role === "original") return 0;
+  if (role === "correction") return 1;
+  return 2;
+}
+
+function laterTimestamp(a: string, b: string): string {
+  const aTime = Date.parse(a);
+  const bTime = Date.parse(b);
+  if (Number.isFinite(aTime) && Number.isFinite(bTime)) return aTime >= bTime ? a : b;
+  return a || b;
+}
+
+function compareTimestamps(a: unknown, b: unknown): number {
+  const aTime = Date.parse(text(a));
+  const bTime = Date.parse(text(b));
+  if (Number.isFinite(aTime) && Number.isFinite(bTime) && aTime !== bTime) return aTime - bTime;
+  if (Number.isFinite(aTime) && !Number.isFinite(bTime)) return -1;
+  if (!Number.isFinite(aTime) && Number.isFinite(bTime)) return 1;
+  return 0;
+}
+
+function nonnegativeNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
+}
+
+function record(value: unknown): InvoiceDocumentHistoryRow {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? value as InvoiceDocumentHistoryRow
+    : {};
+}
+
+function normalize(value: unknown): string {
+  return text(value).trim().toLowerCase();
+}
+
+function text(value: unknown): string {
+  return typeof value === "string" ? value : "";
+}
+
+function nullableText(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}