@openlup/platform 0.22.0 → 0.24.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;
+}

package/src/invoicing/documentSync.ts

@@ -0,0 +1,51 @@
+/** Direct donor extraction: host supplies attachment kinds, durable provider
+ * references, status/event keys, hashing and recording. Downloads confer no blob
+ * storage proof. The optional observation mode retains polling without adding
+ * another public runner/export or provider-specific status vocabulary. */
+export async function syncAcceptedInvoiceDocuments<Target, Status, Document>(input: {
+  target: Target;
+  status: Status;
+  downloads: readonly ((target: Target) => Promise<Document>)[];
+  record(target: Target, status: Status, documents: readonly Document[]): Promise<unknown>;
+}): Promise<void>;
+export async function syncAcceptedInvoiceDocuments<Target, Status, Document>(input: {
+  targets(): Promise<readonly Target[]>;
+  observe(target: Target): Promise<Status>;
+  recordStatus(target: Target, status: Status): Promise<unknown>;
+  accepted(status: Status): boolean;
+  downloads: readonly ((target: Target) => Promise<Document>)[];
+  record(target: Target, status: Status, documents: readonly Document[]): Promise<unknown>;
+}): Promise<{ ok: boolean; checked: number; updated: number; skipped: false; failures: number }>;
+export async function syncAcceptedInvoiceDocuments<Target, Status, Document>(input: {
+  target?: Target;
+  status?: Status;
+  targets?: () => Promise<readonly Target[]>;
+  observe?: (target: Target) => Promise<Status>;
+  recordStatus?: (target: Target, status: Status) => Promise<unknown>;
+  accepted?: (status: Status) => boolean;
+  downloads: readonly ((target: Target) => Promise<Document>)[];
+  record(target: Target, status: Status, documents: readonly Document[]): Promise<unknown>;
+}): Promise<void | { ok: boolean; checked: number; updated: number; skipped: false; failures: number }> {
+  const sync = async (target: Target, status: Status) => {
+    const documents = await Promise.all(input.downloads.map(download => download(target)));
+    await input.record(target, status, documents);
+  };
+  if (!input.targets) {
+    await sync(input.target as Target, input.status as Status);
+    return;
+  }
+  const targets = await input.targets();
+  let updated = 0;
+  let failures = 0;
+  for (const target of targets) {
+    try {
+      const status = await input.observe!(target);
+      await input.recordStatus!(target, status);
+      if (input.accepted!(status)) await sync(target, status);
+      updated += 1;
+    } catch {
+      failures += 1;
+    }
+  }
+  return { ok: failures === 0, checked: targets.length, updated, skipped: false as const, failures };
+}

package/src/invoicing/dutyCollector.ts

@@ -0,0 +1,31 @@
+import type { InvoiceStorePort, InvoiceUnsupported } from "./contracts/index.js";
+
+/** Collect retained sources, then prepare each leased duty in separate transactions.
+ * The host commits every store call; no money/parcel callback or provider I/O is
+ * accepted here. Missing facts stay owed until the host installs their revision.
+ * @consumer Independent invoice duty binding.
+ */
+export async function collectInvoiceDuties(input: {
+  store: Pick<InvoiceStorePort, "sweep" | "prepareFacts" | "finishFacts">;
+  limit?: number;
+}): Promise<{ kind: "collected"; collected: number; prepared: number; failures: number } | InvoiceUnsupported> {
+  const batch = await input.store.sweep(input.limit ?? 10);
+  if ("kind" in batch) return batch;
+  let prepared = 0, failures = 0;
+  for (const claim of batch.claims) {
+    try {
+      const result = await input.store.prepareFacts(claim);
+      if ("kind" in result) { failures++; continue; }
+      if (result.status === "stale") continue;
+      const finished = await input.store.finishFacts({ ...claim, result: { ...result, status: result.status } });
+      if ("kind" in finished) failures++;
+      else if (finished.status === "ready" || finished.status === "issued" || finished.status === "voided") prepared++;
+      else if (finished.status !== "stale") failures++;
+    } catch {
+      // A failed prepare/finalize leaves the persisted lease reclaimable. Never
+      // manufacture a successful finish or prevent another claim's progress.
+      failures++;
+    }
+  }
+  return { kind: "collected", collected: batch.collected, prepared, failures };
+}

package/src/invoicing/fulfillmentTrigger.ts

@@ -0,0 +1,144 @@
+interface AccountingInvoiceIssuePort {
+  requestInvoiceIssueFromPaidOrder(input: { idempotencyKey: string; orderId: string; providerKind: string }): Promise<unknown>;
+  requestInvoiceIssueFromFulfillmentHandoff(input: { idempotencyKey: string; fulfillmentOrderId: string; providerKind: string }): Promise<unknown>;
+}
+import {
+  decideChannelInvoice,
+  type OrderInvoicePolicyReader,
+} from "./channelPolicy.js";
+
+// Structural mirror of the commerce OrderPaidFulfillmentPort, declared locally
+// so the accounting domain does not import the commerce domain (the
+// architecture guardrail forbids importing another domain's non-public
+// internals). The composition root in api/cron passes the real commerce port,
+// which is structurally compatible.
+export type AutoDispatchFulfillmentResult =
+  | { kind: "completed" | "skipped"; detail?: Record<string, unknown> }
+  | { kind: "retryable" | "snooze" | "fatal"; reason: string }
+  // A paid order routed to manual review (split shipment unsupported): no
+  // handoff, so no accounting invoice is requested (readHandedOverFulfillmentOrderId
+  // returns null). Mirrors OrderPaidFulfillmentResult so the commerce port stays
+  // structurally assignable here.
+  | { kind: "manual_review"; reason: string; detail?: Record<string, unknown> };
+
+export interface AutoDispatchFulfillmentPort {
+  ensureFulfilledFromPaidOrder(input: {
+    orderUuid: string;
+    outboxEventId: string;
+    signal: AbortSignal;
+  }): Promise<AutoDispatchFulfillmentResult>;
+}
+
+type FulfillmentHandoffRequest = {
+  idempotencyKey: string;
+  fulfillmentOrderId: string;
+  actorUserId: string;
+};
+
+type FulfillmentHandoffPort<TResult = unknown> = {
+  handOffCommerceFulfillmentOrder: (request: FulfillmentHandoffRequest) => Promise<TResult>;
+};
+
+export interface AccountingHandoffTriggerOptions {
+  accountingPort: AccountingInvoiceIssuePort;
+  providerKind: string;
+  keys: { shadow(key: string): string; paid(orderId: string): string; handoff(orderId: string): string };
+  failOnAccountingError?: boolean;
+  issueTrigger?: "handoff" | "paid";
+  // Wave B6. Absent everywhere this wave did not wire it, and an absent reader
+  // decides `issue` — so every composition that predates it keeps today's
+  // behaviour byte for byte.
+  invoicePolicyReader?: OrderInvoicePolicyReader;
+}
+
+export function withAccountingInvoiceShadowTrigger<TResult, TPort extends FulfillmentHandoffPort<TResult>>(
+  fulfillmentPort: TPort,
+  options: Omit<AccountingHandoffTriggerOptions, "accountingPort"> & {
+    accountingPort: Pick<AccountingInvoiceIssuePort, "requestInvoiceIssueFromFulfillmentHandoff"> & Partial<AccountingInvoiceIssuePort>;
+  },
+): TPort {
+  return {
+    ...fulfillmentPort,
+    async handOffCommerceFulfillmentOrder(request: FulfillmentHandoffRequest) {
+      const result = await fulfillmentPort.handOffCommerceFulfillmentOrder(request);
+      try {
+        // The operator hand-off reaches this wrapper holding only the
+        // fulfillment order id, so the policy is read by that key.
+        const decision = await decideChannelInvoice(options.invoicePolicyReader, {
+          by: "fulfillmentOrder",
+          fulfillmentOrderId: request.fulfillmentOrderId,
+        });
+        if (decision.issue) {
+          await options.accountingPort.requestInvoiceIssueFromFulfillmentHandoff({
+            idempotencyKey: options.keys.shadow(request.idempotencyKey),
+            fulfillmentOrderId: request.fulfillmentOrderId,
+            providerKind: options.providerKind,
+          });
+        }
+      } catch (error) {
+        if (options.failOnAccountingError) throw error;
+      }
+      return result;
+    },
+  } as TPort;
+}
+
+// Auto-dispatch sibling of withAccountingInvoiceShadowTrigger. The outbox
+// commerce.order.paid -> fulfillment path drives handoff through the
+// OrderPaidFulfillmentPort (ensureFulfilledFromPaidOrder), which issues the
+// mark-handed-over RPC directly and therefore never reaches the admin
+// hand-off wrapper above. Without this, an auto-dispatched paid order reaches
+// handed_over but no accounting invoice is ever requested. Same semantics:
+// idempotent (the issue RPC dedups on the order-derived invoice_ref, so any
+// key is duplicate-safe) and fail-soft (accounting errors never fail the
+// fulfillment dispatch — the outbox event still settles as processed).
+export function withAutoDispatchAccountingInvoiceTrigger(
+  fulfillmentPort: AutoDispatchFulfillmentPort,
+  options: AccountingHandoffTriggerOptions,
+): AutoDispatchFulfillmentPort {
+  return {
+    async ensureFulfilledFromPaidOrder(input) {
+      // Both branches hold the order uuid, so both ask by the order key — the
+      // strongest key available, and the one that needs no join.
+      const lookup = { by: "order" as const, orderUuid: input.orderUuid };
+      if (options.issueTrigger === "paid") {
+        try {
+          const decision = await decideChannelInvoice(options.invoicePolicyReader, lookup);
+          if (decision.issue) {
+            await options.accountingPort.requestInvoiceIssueFromPaidOrder({
+              idempotencyKey: options.keys.paid(input.orderUuid),
+              orderId: input.orderUuid,
+              providerKind: options.providerKind,
+            });
+          }
+        } catch (error) {
+          if (options.failOnAccountingError) throw error;
+        }
+      }
+      const result = await fulfillmentPort.ensureFulfilledFromPaidOrder(input);
+      if (options.issueTrigger === "paid") return result;
+      const fulfillmentOrderId = readHandedOverFulfillmentOrderId(result);
+      if (fulfillmentOrderId) {
+        try {
+          const decision = await decideChannelInvoice(options.invoicePolicyReader, lookup);
+          if (decision.issue) {
+            await options.accountingPort.requestInvoiceIssueFromFulfillmentHandoff({
+              idempotencyKey: options.keys.handoff(input.orderUuid),
+              fulfillmentOrderId,
+              providerKind: options.providerKind,
+            });
+          }
+        } catch (error) {
+          if (options.failOnAccountingError) throw error;
+        }
+      }
+      return result;
+    },
+  };
+}
+
+function readHandedOverFulfillmentOrderId(result: AutoDispatchFulfillmentResult): string | null {
+  if (result.kind !== "completed" && result.kind !== "skipped") return null;
+  const id = result.detail?.fulfillmentOrderId;
+  return typeof id === "string" ? id : null;
+}