@openlup/platform 0.23.0 → 0.24.0

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;
+}

package/src/invoicing/handoff.ts

@@ -0,0 +1,71 @@
+import type { ChannelInvoiceDecision } from "./channelPolicy.js";
+
+// SQLSTATEs the issue-request RPCs raise for permanently non-retryable
+// conditions. Retrying these can never succeed, so the event must be discarded
+// (terminal) rather than retry-looped into a `failed` backlog that the staging
+// outbox-preview gate treats as blocking (see outboxOrderPaidFulfillmentHandler,
+// which likewise maps fatal -> discard).
+//   - 22023 (invalid_parameter_value): every validation RAISE in
+//     accounting_invoice_issue_request_from_handoff / _from_paid_order — invalid
+//     input, missing fulfillment order (deleted), missing order/client/address,
+//     payment-not-succeeded, package-not-shipped. The handed_over event commits
+//     atomically with handed_over_at, so a missing row means it was deleted, not
+//     a visibility race.
+//   - 23514 (check_violation): the #1811 provider-immutability guard
+//     (accounting_invoice_provider_mismatch). The provider is immutable, so a
+//     replay against a different provider can never be persisted.
+const PERMANENT_ISSUE_SQLSTATES = new Set(["22023", "23514"]);
+
+// The subset of permanent (22023) RAISE identifiers that mean the aggregate or
+// its graph was legitimately deleted before this async event dispatched — an
+// orphan from smoke/order cleanup or a real order deletion. Discarding these is
+// the expected, correct outcome, so they are classified `benign` (logged at warn,
+// not error). Every OTHER permanent condition — payment-not-succeeded,
+// package-not-shipped, invalid-input, and the 23514 provider-immutability guard —
+// is still discarded but kept at error level because it signals a genuine anomaly.
+const BENIGN_ISSUE_RAISE_IDENTIFIERS = new Set([
+  "accounting_invoice_handoff_not_found",
+  "accounting_invoice_order_not_found",
+  "accounting_invoice_client_not_found",
+  "accounting_invoice_address_not_found",
+]);
+
+/** Host retains event schema, key scopes, RPC error class and compatibility detail. */
+export function createFulfillmentHandoffInvoiceHandler<Row extends { payload: unknown }, Payload>(input: {
+  descriptor: { eventType: string; timeoutMs: number };
+  parsePayload(value: unknown): { success: true; data: Payload } | { success: false };
+  decide(payload: Payload): Promise<ChannelInvoiceDecision>;
+  request(row: Row, payload: Payload): Promise<Record<string, unknown>>;
+  errorDetails(error: unknown): { message: string; causeCode?: string; causeMessage?: string };
+}) {
+  return {
+    ...input.descriptor,
+    async handle(row: Row, signal: AbortSignal): Promise<
+      { kind: "processed"; detail: Record<string, unknown> } |
+      { kind: "discard"; reason: string; benign?: boolean } | { kind: "retry"; reason: string }
+    > {
+      const parsed = input.parsePayload(row.payload);
+      if (!parsed.success) return { kind: "discard", reason: "fulfillment_handoff_payload_invalid" };
+      if (signal.aborted) return { kind: "retry", reason: "fulfillment_handoff_handler_aborted" };
+      try {
+        const decision = await input.decide(parsed.data);
+        if (!decision.issue) return { kind: "processed", detail: decision.detail };
+        return { kind: "processed", detail: await input.request(row, parsed.data) };
+      } catch (error) {
+        const { message, causeCode, causeMessage } = input.errorDetails(error);
+        // Surface the RPC's own RAISE identifier so a discard reads explicitly
+        // (e.g. "…: accounting_invoice_handoff_not_found (22023)") instead of an
+        // opaque SQLSTATE — this is what lets an orphan discard be told apart
+        // from a real payment-not-succeeded failure in the logs.
+        const detail = causeMessage && causeMessage !== message ? `${message}: ${causeMessage}` : message;
+        const reason = (causeCode ? `${detail} (${causeCode})` : detail).slice(0, 300);
+        if (causeCode !== undefined && PERMANENT_ISSUE_SQLSTATES.has(causeCode)) {
+          const benign = causeMessage !== undefined
+            && BENIGN_ISSUE_RAISE_IDENTIFIERS.has(causeMessage);
+          return benign ? { kind: "discard", reason, benign: true } : { kind: "discard", reason };
+        }
+        return { kind: "retry", reason };
+      }
+    },
+  };
+}

package/src/invoicing/index.ts

@@ -1 +1,39 @@
 export { readInvoiceCapabilities } from "./capabilities.js";
+export { createNativeUnsupportedInvoicePorts } from "./nativeUnsupported.js";
+export { runInvoiceAdapterConformance } from "./adapterConformance.js";
+export { runInvoiceIssueJob } from "./issue.js";
+/** @consumer server/domains/accounting/accountingProviderSnapshot.ts */
+export { mapInvoiceClaimToProviderSnapshot } from "./snapshot.js";
+/** @consumer server/domains/accounting/accountingCanonicalProviderLines.ts */
+export { mapCanonicalIssueLines } from "./accountingCanonicalProviderLines.js";
+/** @consumer server/domains/accounting/accountingLineAllocation.ts */
+export { allocateChargedGrossTotals } from "./accountingLineAllocation.js";
+/** @consumer server/domains/accounting/accountingLineAllocation.ts */
+export { allocateDiscountedGrossTotals } from "./accountingLineAllocation.js";
+/** @consumer server/domains/accounting/accountingPaymentReadback.ts */
+export { readInvoicePaymentEvidence } from "./paymentReadback.js";
+/** @consumer server/domains/accounting/fulfillmentHandoffInvoiceHandler.ts */
+export { createFulfillmentHandoffInvoiceHandler } from "./handoff.js";
+/** @consumer server/domains/accounting/fulfillmentInvoiceTrigger.ts */
+export { withAccountingInvoiceShadowTrigger } from "./fulfillmentTrigger.js";
+/** @consumer server/domains/accounting/fulfillmentInvoiceTrigger.ts */
+export { withAutoDispatchAccountingInvoiceTrigger } from "./fulfillmentTrigger.js";
+export { runInvoiceCorrectionJob } from "./correction.js";
+export { createInvoiceReversalHandlers } from "./reversal.js";
+/** @consumer Reference native accounting adapter/runtime and installed-consumer conformance. */
+export { createPostgresInvoiceStore, runNativeInvoiceIssueJob } from "./postgresInvoiceStore.js";
+/** @consumer Native migration conformance and installed-consumer asset verification. */
+export { INVOICING_MIGRATIONS } from "./migrations.js";
+export { collectInvoiceDuties } from "./dutyCollector.js";
+export { createIndependentInvoiceDutyBinding } from "./continuity.js";
+export { runInvoiceDeliveryJob } from "./delivery.js";
+export { assertInvoicePdf, invoicePdfFilename } from "./artifacts.js";
+export { syncAcceptedInvoiceDocuments } from "./documentSync.js";
+export { syncInvoicePayoutSettlements } from "./settlementSync.js";
+export { resolveInvoiceDocumentHistory } from "./documentHistory.js";
+export { createInvoiceReadModel } from "./readModel.js";
+export { createInvoiceServices } from "./bindings.js";
+export type { InvoiceServices } from "./bindings.js";
+export { createInvoiceContribution } from "./contribution.js";
+export { claimInvoiceSellerRevision } from "./sellerRevision.js";
+export type { InvoiceSellerRevision, InvoiceClaimedFacts } from "./contracts/facts.js";

package/src/invoicing/issue.ts

@@ -0,0 +1,64 @@
+import type { InvoiceWriteResult } from "./contracts/provider.js";
+
+/** Donor issue sequencing over explicit compatibility callbacks. No transaction
+ * spans a callback; hosts bind their existing claim/preflight/finalizer contracts.
+ * @consumer server/domains/accounting/accountingJobService.ts
+ */
+export async function runInvoiceIssueJob<Claim extends { attemptCount: number }, Snapshot, Evidence, Result extends Pick<Extract<InvoiceWriteResult, { kind: "issued" }>, "providerDocumentRef" | "providerDocumentNumber">>(input: {
+  createEnabled: boolean;
+  providerEnabled: boolean;
+  claim(): Promise<readonly Claim[]>;
+  localPreflight(claim: Claim): Promise<boolean>;
+  project(claim: Claim): Snapshot;
+  blockMapper(claim: Claim, code: string, error: unknown): Promise<unknown>;
+  readPayment(claim: Claim): Promise<Evidence>;
+  freshPreflight(claim: Claim, evidence: Evidence): Promise<boolean>;
+  /** Resolve only accepted/recovered document receipts; unknown/absent is not an ACK. */
+  create(snapshot: Snapshot, options: { 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 {
+      if (!await input.localPreflight(claim)) {
+        failures += 1;
+        continue;
+      }
+      let snapshot: Snapshot;
+      try {
+        snapshot = input.project(claim);
+      } catch (error) {
+        const canonicalCode = canonicalMapperErrorCode(error);
+        if (!canonicalCode) throw error;
+        await input.blockMapper(claim, canonicalCode, error);
+        failures += 1;
+        continue;
+      }
+      const providerEvidence = await input.readPayment(claim);
+      if (!await input.freshPreflight(claim, providerEvidence)) {
+        failures += 1;
+        continue;
+      }
+      const result = await input.create(snapshot, { recoveryLookupRequired: claim.attemptCount > 1 });
+      await input.finish(claim, result);
+      updated += 1;
+    } catch (error) {
+      failures += 1;
+      if (input.isClaimFenceError(error)) continue;
+      await input.fail(claim, error, Math.min(3600, 300 * Math.max(1, claim.attemptCount)));
+    }
+  }
+  return { ok: failures === 0, checked: claims.length, updated, skipped: false, failures };
+}
+function canonicalMapperErrorCode(error: unknown): string | null {
+  if (!(error instanceof Error)) return null;
+  const match = /\b(accounting_invoice_canonical_[a-z0-9_]+)/.exec(error.message);
+  return match?.[1] ?? null;
+}
+function skipped(reason: string) { return { ok: true, checked: 0, updated: 0, skipped: true, reason, failures: 0 }; }

package/src/invoicing/migrations.ts

@@ -0,0 +1,25 @@
+/** Sparse native projections, not an installation chain. Install the full catalogue. */
+export const INVOICING_MIGRATIONS = {
+  native: {
+    correctionStorage: "child_document",
+    fiscalScope: "explicit_host_facts",
+    units: [
+      { position: 7, catalogPath: "db/platform/migrations/20260809210000_accounting_document_rail.sql", sha256: "f5c6c4b3d5ccdd7c7137669edba7d45c63685edc57fe982e3e8fd559214ccc8e", url: new URL("../../sql/20260809210000_accounting_document_rail.sql", import.meta.url) },
+      { position: 13, catalogPath: "db/platform/migrations/20260811150000_accounting_payout_rail.sql", sha256: "b127631196362d59ceb94700426766659589601c69a5adfb1b5d6bbeadf5b0db", url: new URL("../../sql/20260811150000_accounting_payout_rail.sql", import.meta.url) },
+      { position: 15, catalogPath: "db/platform/migrations/20260812130000_accounting_document_lifecycle_rail.sql", sha256: "450ae24b8ba9438ea267cfbf52f9c78a790b1803f369c216577566952fa43b5f", url: new URL("../../sql/20260812130000_accounting_document_lifecycle_rail.sql", import.meta.url) },
+      { position: 77, catalogPath: "db/platform/migrations/20261022190000_invoicing_durable_duties.sql", sha256: "2d7bf98924b4ef29b3e8f902d768e45dd9c850242f4358a0193a0c00d0f3d081", url: new URL("../../sql/20261022190000_invoicing_durable_duties.sql", import.meta.url) },
+      { position: 78, catalogPath: "db/platform/migrations/20261022191000_invoicing_document_effects.sql", sha256: "0eac3453e2b82c43e4fff9e35bcd6daefdd0bb5f992937f7f411d690550428cf", url: new URL("../../sql/20261022191000_invoicing_document_effects.sql", import.meta.url) },
+      { position: 79, catalogPath: "db/platform/migrations/20261022192000_invoicing_payment_decoupling.sql", sha256: "f4af30ee4c9365ea51bd0e95e5cc7ae869cf15dce5867fdd640f679438b36058", url: new URL("../../sql/20261022192000_invoicing_payment_decoupling.sql", import.meta.url) },
+      { position: 80, catalogPath: "db/platform/migrations/20261022195000_invoicing_seller_revision.sql", sha256: "5a6348d9af296cfc6383894e3489f70af1f3bb5026c0cc329daa9f3f95802b22", url: new URL("../../sql/20261022195000_invoicing_seller_revision.sql", import.meta.url) },
+    ],
+  },
+  managed: {
+    correctionStorage: "base_row",
+    fiscalScope: "host_managed_projection",
+    units: [
+      "supabase/migrations/20261022193000_invoicing_correction_claims.sql",
+      "supabase/migrations/20261022193100_invoicing_correction_compatibility.sql",
+      "supabase/migrations/20261022195100_invoicing_seller_revision.sql",
+    ],
+  },
+} as const;

package/src/invoicing/nativeUnsupported.ts

@@ -0,0 +1,24 @@
+import type { InvoiceHostPorts, InvoiceStorePort, InvoiceServicesOptions, InvoiceWriteResult } from "./contracts/index.js";
+
+const refusal: Extract<InvoiceWriteResult, { kind: "unsupported" }> = Object.freeze({ kind: "unsupported", code: "host_binding_required", retryable: false, effectMayHaveSucceeded: false });
+/** @consumer Host native binding / installed cold consumer. No executor, inputs,
+ * provider or storage is inspected: every missing native seam refuses before writes.
+ */
+export function createNativeUnsupportedInvoicePorts(): { host: InvoiceHostPorts; store: InvoiceStorePort; provider: NonNullable<InvoiceServicesOptions["provider"]> } {
+  const unsupported = async () => refusal;
+  return {
+    host: {
+      facts: { read: unsupported }, seller: { read: unsupported }, money: { read: unsupported }, fiscal: { verify: unsupported },
+      artifacts: { read: unsupported, download: unsupported, persist: unsupported }, registry: { lookup: unsupported },
+      delivery: { send: unsupported }, clearance: { observe: unsupported }, settlement: { record: unsupported, resolve: unsupported },
+      policy: { decide: unsupported, receipts: unsupported }, accountHistory: { read: unsupported, resolveDownload: unsupported },
+    },
+    store: {
+      captureDuty: unsupported, installFacts: unsupported, sweep: unsupported, prepareFacts: unsupported, finishFacts: unsupported,
+      readDuties: unsupported, claim: unsupported, preflight: unsupported, finish: unsupported, fail: unsupported,
+      requestReversal: unsupported, requestLocalDocument: unsupported, listClearanceTargets: unsupported,
+      recordObservation: unsupported, claimDeliveries: unsupported, settleDelivery: unsupported,
+    },
+    provider: { issue: unsupported, correct: unsupported, read: unsupported, void: unsupported },
+  };
+}

package/src/invoicing/paymentReadback.ts

@@ -0,0 +1,70 @@
+type PaymentEvidence = {
+  providerStatus: "succeeded" | "failed" | "pending" | "unknown" | "unavailable";
+  providerAmountCents: number | null;
+  providerCurrency: string | null;
+  providerEvidence: Record<string, unknown>;
+};
+
+export async function readInvoicePaymentEvidence(
+  payment: { provider: string; providerPaymentId: string | null },
+  provider: { readPayment(input: { providerPaymentId: string }): Promise<{
+    status: "succeeded" | "failed" | "pending" | "unknown"; providerStatus: string; amountMinor: number | null; currency: string | null;
+  }> } | undefined,
+): Promise<PaymentEvidence> {
+  const providerName = payment.provider;
+  if (!provider || !payment.providerPaymentId) {
+    return unavailable(
+      providerName,
+      payment.providerPaymentId,
+      provider ? "provider_payment_id_missing" : "provider_not_configured",
+    );
+  }
+
+  try {
+    const readback = await provider.readPayment({
+      providerPaymentId: payment.providerPaymentId,
+    });
+    return {
+      providerStatus: readback.status,
+      providerAmountCents: integerOrNull(readback.amountMinor),
+      providerCurrency: currencyOrNull(readback.currency),
+      providerEvidence: {
+        source: "provider_api",
+        provider: providerName,
+        providerPaymentId: payment.providerPaymentId,
+        providerStatus: readback.providerStatus.slice(0, 80),
+        amountAvailable: integerOrNull(readback.amountMinor) !== null,
+        currencyAvailable: currencyOrNull(readback.currency) !== null,
+      },
+    };
+  } catch {
+    return unavailable(providerName, payment.providerPaymentId, "provider_read_failed");
+  }
+}
+
+function unavailable(
+  provider: string,
+  providerPaymentId: string | null,
+  reason: string,
+): PaymentEvidence {
+  return {
+    providerStatus: "unavailable",
+    providerAmountCents: null,
+    providerCurrency: null,
+    providerEvidence: {
+      source: "provider_api",
+      provider,
+      providerPaymentId,
+      unavailableReason: reason,
+    },
+  };
+}
+
+function integerOrNull(value: number | null): number | null {
+  return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
+}
+
+function currencyOrNull(value: string | null): string | null {
+  const normalized = value?.trim().toUpperCase() ?? "";
+  return /^[A-Z]{3}$/.test(normalized) ? normalized : null;
+}