@openlup/platform 0.22.0 → 0.24.0

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

@@ -0,0 +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;
+}

package/src/invoicing/postgresInvoiceStore.ts

@@ -0,0 +1,334 @@
+import type { InvoiceFacts, InvoiceIdentity, InvoiceStorePort, InvoiceHostPorts, InvoiceProviderPort } from "./contracts/index.js";
+import { claimInvoiceSellerRevision } from "./sellerRevision.js";
+import { createNativeUnsupportedInvoicePorts } from "./nativeUnsupported.js";
+
+type InvoiceClaim = Parameters<InvoiceStorePort["preflight"]>[0]["claim"];
+type NativeStore = InvoiceStorePort & {
+  /** Read-only discovery before a host can install facts. Replays may repeat targets. */
+  discoverDuties(limit: number, afterDutyId?: string | null): Promise<readonly { readonly dutyId: string; readonly orderId: string }[]>;
+};
+type DeliveryClaim = Exclude<Awaited<ReturnType<InvoiceStorePort["claimDeliveries"]>>, { kind: "unsupported" }>[number];
+type DeliveryProjection = {
+  /** Host-owned M04 keys, presentation and recipient resolution, after leasing.
+   * Return only the envelope for this document; a failed projection never sends.
+   */
+  projectDelivery(input: { readonly deliveryRef: string; readonly documentId: string; readonly channel: string; readonly recipientRef: string; readonly attemptCount: number }): Promise<Pick<DeliveryClaim, "identity" | "delivery">>;
+};
+type Executor = { query(text: string, values?: unknown[]): Promise<{ rows: Record<string, unknown>[] }> };
+const unsupported = { kind: "unsupported", code: "host_binding_required", retryable: false, effectMayHaveSucceeded: false } as const;
+
+/** Bind an autocommit executor. Never pass a transaction spanning host/provider I/O.
+ * Missing fiscal facts or delivery binding refuse before writes; no scheduler is installed.
+ */
+export function createPostgresInvoiceStore(db: Executor, options?: Partial<DeliveryProjection> & { readonly seller?: InvoiceHostPorts["seller"] }): NativeStore {
+  async function call<T>(name: string, values: unknown[]): Promise<T> {
+    const result = await db.query(`SELECT public.${name}(${values.map((_, i) => `$${i + 1}`).join(",")}) AS response`, values);
+    if (result.rows[0]?.response === undefined) throw new Error("invoicing_native_response_missing");
+    return result.rows[0].response as T;
+  }
+  const fence = (claim: InvoiceClaim) => [claim.dutyId, claim.token, claim.generation];
+  return {
+    ...createNativeUnsupportedInvoicePorts().store,
+    async discoverDuties(limit, afterDutyId = null) {
+      const result = await db.query(`SELECT d.id AS "dutyId", d.order_id AS "orderId"
+        FROM public.invoicing_duties d
+        WHERE ($2::uuid IS NULL OR d.id>$2::uuid)
+          AND d.request_id IS NULL AND d.status IN ('owed','blocked')
+          AND d.reversal IS NULL AND d.available_at<=now()
+          AND NOT EXISTS (SELECT 1 FROM public.invoicing_fact_revisions f WHERE f.duty_id=d.id)
+        ORDER BY d.id LIMIT least(greatest(coalesce($1::integer,10),1),100)`, [limit, afterDutyId]);
+      return result.rows.map(row => ({ dutyId: row.dutyId as string, orderId: row.orderId as string }));
+    },
+    async captureDuty(v) {
+      try { return await call<Awaited<ReturnType<InvoiceStorePort["captureDuty"]>>>("invoicing_request_with_seller_policy", [v.requestKey, v.sourceKind, v.sourceId, v.orderId, v.evidence, v.occurredAt]); }
+      catch (error) { if (isConflict(error)) return { kind: "conflict", code: "identity_mismatch" }; throw error; }
+    },
+    async installFacts(v) {
+      if (!validFacts(v.facts)) return unsupported;
+      return call<Awaited<ReturnType<InvoiceStorePort["installFacts"]>>>("invoicing_install_facts", [v.dutyId, v.facts, v.facts.factRevision]);
+    },
+    sweep: limit => call("invoicing_sweep_duties", [limit]),
+    async prepareFacts(v) {
+      const result = await call<{ status: "owed" | "ready" | "issued" | "voided" | "unsupported" | "stale"; documentId?: string; requestId?: string; kind?: "retryable" | "legacy_facts_unproved" }>("invoicing_prepare_facts", [v.dutyId, v.token]);
+      const { kind, ...rest } = result;
+      return kind ? { ...rest, code: kind } : rest;
+    },
+    async finishFacts(v) {
+      const result = await call<{ status: "owed" | "ready" | "issued" | "voided" | "unsupported" | "faulted" | "stale" }>("invoicing_finish_facts", [v.dutyId, v.token, { ...v.result, kind: v.result.code }]);
+      return { ...result, dutyId: v.dutyId };
+    },
+    readDuties: orderId => call("invoicing_duty_readback", [orderId]),
+    async claim(v) {
+      if (!options?.seller) return unsupported;
+      const selected = await claimInvoiceSellerRevision(() => options!.seller!.read({ orderId: v.orderId ?? null }));
+      if (selected.kind !== "found") return unsupported;
+      // Revisions are immutable. Refuse legacy/incomplete host projections before
+      // the lease RPC mutates a duty; supported writers install through this store.
+      const candidates = await db.query(`SELECT f.facts FROM public.invoicing_duties d
+        JOIN public.invoicing_fact_revisions f ON f.duty_id=d.id
+        WHERE ($1::uuid IS NULL OR d.order_id=$1) AND (d.provider IS NULL OR d.provider=$2)
+          AND d.status IN ('ready','processing','unknown') AND d.available_at<=now()
+          AND (d.status<>'processing' OR d.lease_until<=now())`, [v.orderId ?? null, v.providerRef]);
+      if (candidates.rows.some(row => !validFacts(row.facts as InvoiceFacts))) return unsupported;
+      const rows = await call<Record<string, unknown>[]>("invoicing_claim_with_seller", [v.limit, v.visibilitySeconds, v.providerRef, selected.seller, selected.revisionRef, v.orderId ?? null]);
+      return rows.map(row => {
+        const facts = row.facts as InvoiceFacts & { before?: InvoiceFacts; reason?: string; parentExternalId?: string };
+        if (!validFacts(facts)) throw new Error("invoicing_native_facts_invalid");
+        const correction = row.parent_duty_id !== null;
+        return {
+          dutyId: row.id as string, documentId: row.document_id as string, requestId: row.request_id as string,
+          token: row.claim_token as string, generation: row.generation as number, leaseUntil: row.lease_until as string,
+          identity: identity(row, facts), facts: { ...facts, seller: row.seller as InvoiceFacts["seller"], sellerRevision: row.sellerRevision as string, sellerMode: row.sellerMode as "frozen" | "legacy_fallback" },
+          action: (row.last_result as { action: "create" | "readback" }).action,
+          correction: correction ? { before: facts.before!, reason: facts.reason!, after: { totalNetMinor: 0, totalTaxMinor: 0, totalGrossMinor: 0 } } : null,
+        };
+      });
+    },
+    preflight: v => call("invoicing_preflight_duty", [...fence(v.claim), {
+      kind: v.status === "unavailable" || v.status === "unknown" || v.status === "absent" || v.amountMinor === null || v.currency === null ? "unavailable" : "observed",
+      outcome: v.status === "succeeded" ? "captured" : v.status,
+      amountMinor: v.amountMinor, currency: v.currency, proof: v.status === "absent" ? v.evidence : v.proof,
+    }]),
+    async finish(v) {
+      if (!sameIdentity(v.claim.identity, v.result.identity)) return unsupported;
+      return call(v.claim.correction ? "invoicing_finish_correction" : "invoicing_finish_issue", [
+        ...fence(v.claim), v.result.providerDocumentRef, v.result.providerDocumentNumber,
+        { kind: v.result.kind === "issued" ? "issued" : "readback_found", externalId: v.result.providerDocumentRef,
+          providerCreateIdentity: v.claim.identity.providerCreateIdentity, parentExternalId: v.claim.identity.parentProviderDocumentRef, proof: v.result.proof },
+      ]);
+    },
+    async fail(v) {
+      if (v.kind === "absent" && (!sameIdentity(v.claim.identity, v.evidence.identity)
+        || !sameIdentity(v.claim.identity, v.evidence.evidence.scope)
+        || v.evidence.evidence.exact !== true || v.evidence.evidence.complete !== true)) return unsupported;
+      const evidence = v.kind === "absent"
+        ? { kind: "authoritative_absence", providerCreateIdentity: v.claim.identity.providerCreateIdentity, proof: v.evidence.evidence }
+        : { ...(v.kind === "retryable" ? { phase: "before_send" } : {}), proof: v.proof };
+      const result = await call<{ kind: string }>("invoicing_fail_duty", [...fence(v.claim), v.kind, evidence, v.retrySeconds]);
+      return { kind: result.kind === "stale" || result.kind === "voided" ? result.kind : "recorded" };
+    },
+    async requestReversal(v) {
+      try {
+      const result = await call<{ kind: "missing" | "voided" | "pending_readback" | "correction_requested" | "unsupported"; dutyId?: string; replayed?: boolean }>("invoicing_request_with_seller_policy", [v.requestKey, "correction", null, v.orderId, { ...v.proof, reason: v.reason }, null]);
+      return result.kind === "unsupported" ? { ...result, kind: "unsupported_recorded" } : { ...result, kind: result.kind };
+      } catch (error) { if (isConflict(error)) return { kind: "conflict", code: "identity_mismatch" }; throw error; }
+    },
+    async requestLocalDocument(v) {
+      const result = await db.query(LOCAL_DOCUMENT_SQL, [v.requestKey, v.orderId, v.providerRef]);
+      const response = result.rows[0]?.response as { replayed?: boolean; document?: { id?: string; status?: string } } | undefined;
+      if (typeof response?.document?.id !== "string" || typeof response.replayed !== "boolean" || typeof response.document.status !== "string") throw new Error("accounting_paid_order_document_response_invalid");
+      const document = (await db.query("SELECT document_ref FROM public.accounting_documents WHERE id=$1::uuid", [response.document.id])).rows[0];
+      if (typeof document?.document_ref !== "string") throw new Error("accounting_paid_order_document_reference_missing");
+      return { kind: "requested", documentId: response.document.id, invoiceRef: document.document_ref, replayed: response.replayed, status: response.document.status };
+    },
+    async claimDeliveries(v) {
+      if (typeof options?.projectDelivery !== "function") return unsupported;
+      const rows = await call<{ delivery_id: string; document_id: string; channel: string; recipient_reference: string; claim_token: string; generation: number }[]>(
+        "invoicing_claim_deliveries", [v.limit, v.visibilitySeconds, v.requireClearance, v.orderId ?? null]);
+      const claims: DeliveryClaim[] = [];
+      for (const row of rows) {
+        let retryable = true;
+        try {
+          const projected = await options!.projectDelivery!({ deliveryRef: row.delivery_id, documentId: row.document_id,
+            channel: row.channel, recipientRef: row.recipient_reference, attemptCount: row.generation });
+          const doc = (await db.query("SELECT order_id, provider_reference FROM public.accounting_documents WHERE id=$1::uuid", [row.document_id])).rows[0];
+          const { identity, delivery } = projected;
+          if (!doc || !nonempty(doc.provider_reference) || identity.documentRef !== row.document_id
+            || identity.providerDocumentRef !== doc.provider_reference || delivery.documentRef !== row.document_id
+            || delivery.deliveryRef !== row.delivery_id || delivery.orderId !== doc.order_id
+            || delivery.providerDocumentRef !== doc.provider_reference || delivery.attemptCount !== row.generation
+            || delivery.orderRef !== identity.orderRef || delivery.invoiceRef !== identity.invoiceRef
+            || !nonempty(delivery.requestKey) || !nonempty(delivery.recipient)) {
+            retryable = false;
+            throw new Error("invoicing_delivery_projection_invalid");
+          }
+          claims.push({ ...projected, token: row.claim_token, generation: row.generation, providerDocumentRef: doc.provider_reference });
+        } catch {
+          const settled = await call<{ kind: string }>("invoicing_settle_delivery", [
+            row.delivery_id, row.claim_token, row.generation, "failed_before_send", null,
+            { phase: "before_send", retryable, retrySeconds: Math.min(3600, 300 * Math.max(1, row.generation)),
+              code: retryable ? "retryable" : "identity_mismatch" },
+          ]);
+          if (settled.kind !== "failed_before_send") throw new Error("invoicing_delivery_fence");
+        }
+      }
+      return claims;
+    },
+    async settleDelivery(v) {
+      if (typeof options?.projectDelivery !== "function") return unsupported;
+      const doc = (await db.query(`SELECT doc.provider_reference FROM public.accounting_document_deliveries d
+        JOIN public.accounting_documents doc ON doc.id=d.document_id WHERE d.id=$1::uuid`, [v.deliveryRef])).rows[0];
+      if (!doc || doc.provider_reference !== v.providerDocumentRef) return unsupported;
+      const result = v.result;
+      const kind = result.kind === "provider_accepted" ? "sent" : result.kind;
+      const receipt = result.kind === "provider_accepted" ? result.receiptRef : null;
+      const evidence = result.kind === "failed_before_send"
+        ? { phase: "before_send", retryable: result.retryable, retrySeconds: v.retrySeconds, code: result.code }
+        : result.kind === "uncertain" ? { code: result.code, receiptHint: result.receiptRef } : { proof: result.proof };
+      const settled = await call<{ kind: string; replayed?: boolean }>("invoicing_settle_delivery",
+        [v.deliveryRef, v.token, v.generation, kind, receipt, evidence]);
+      return { kind: settled.kind === "stale" ? "stale" : "recorded", replayed: settled.replayed ?? false };
+    },
+  };
+}
+
+function isConflict(error: unknown): boolean { return typeof error === "object" && error !== null && "code" in error && error.code === "23505"; }
+function sameIdentity(a: InvoiceIdentity, b: InvoiceIdentity): boolean {
+  return (Object.keys(a) as (keyof InvoiceIdentity)[]).every(key => a[key] === b[key]);
+}
+function identity(row: Record<string, unknown>, facts: InvoiceFacts & { parentExternalId?: string }): InvoiceIdentity {
+  const correction = row.parent_duty_id !== null;
+  return {
+    providerRef: row.provider as string, requestKey: row.original_key as string,
+    providerCreateIdentity: row.providerCreateIdentity as string, factRevision: facts.factRevision,
+    orderRef: facts.refs.orderRef, invoiceRef: facts.refs.invoiceRef,
+    operation: correction ? "full_reversal" : "issue", correctionRef: correction ? `invoicing:${row.id}` : null,
+    parentProviderDocumentRef: correction ? facts.parentExternalId! : null,
+  };
+}
+function nonempty(value: unknown): value is string { return typeof value === "string" && value.trim().length > 0; }
+function validFacts(facts: InvoiceFacts): boolean {
+  if (!facts || !nonempty(facts.factRevision) || !nonempty(facts.policyVersion) || !nonempty(facts.documentKind)
+    || !facts.refs?.orderId || !facts.refs.orderRef || !facts.refs.invoiceRef || !facts.dates?.issueDate || !facts.dates.sellDate
+    || !facts.buyer?.name || !facts.payment?.intentRef || facts.payment.currency !== facts.currency || typeof facts.clearanceRequired !== "boolean"
+    || facts.currency?.length !== 3 || !Array.isArray(facts.lines) || !facts.lines.length) return false;
+  const sums = [0, 0, 0];
+  for (const line of facts.lines) {
+    if (!line || !nonempty(line.description) || !Number.isSafeInteger(line.quantity) || line.quantity < 1
+      || !Number.isSafeInteger(line.taxRateBps) || line.taxRateBps < 0 || line.taxRateBps > 10000
+      || ![line.unitNetMinor, line.unitGrossMinor, line.totalNetMinor, line.totalTaxMinor, line.totalGrossMinor].every(Number.isSafeInteger)
+      || line.totalNetMinor < 0 || line.totalTaxMinor < 0 || line.totalNetMinor + line.totalTaxMinor !== line.totalGrossMinor) return false;
+    sums[0] += line.totalNetMinor; sums[1] += line.totalTaxMinor; sums[2] += line.totalGrossMinor;
+  }
+  return [facts.totalNetMinor, facts.totalTaxMinor, facts.totalGrossMinor].every((n, i) => Number.isSafeInteger(n) && n === sums[i])
+    && facts.chargedTotalGrossMinor === facts.totalGrossMinor;
+}
+
+// Incumbent local-only constructor, byte-preserved SQL; zero tax is not a fiscal projection.
+const LOCAL_DOCUMENT_SQL = `
+  WITH snapshot AS (
+    SELECT
+      order_row.total_amount_minor,
+      COALESCE(
+        jsonb_agg(
+          jsonb_build_object(
+            'description', 'order position ' || item.line_ordinal::text,
+            'quantity', item.quantity,
+            'unitGrossMinor', item.unit_amount_minor,
+            'totalGrossMinor', item.line_amount_minor,
+            'taxRateBps', 0
+          ) ORDER BY item.line_ordinal
+        ) FILTER (WHERE item.id IS NOT NULL),
+        '[]'::jsonb
+      ) AS positions
+    FROM public.commerce_orders order_row
+    LEFT JOIN public.commerce_order_items item ON item.order_id = order_row.id
+    WHERE order_row.id = $2::uuid
+    GROUP BY order_row.id, order_row.total_amount_minor
+  )
+  SELECT public.accounting_document_request_from_paid_order(
+    $1, $2::uuid, snapshot.positions, snapshot.total_amount_minor,
+    jsonb_build_object('providerKind', $3::text)
+  ) AS response
+  FROM snapshot`;
+
+type MoneyEvidence = Awaited<ReturnType<InvoiceHostPorts["money"]["read"]>>;
+class ClaimFenceError extends Error {}
+
+/** Native issue/readback binding; every store operation commits before host I/O.
+ * @consumer Explicit native host issue binding and installed-consumer conformance.
+ */
+export async function runNativeInvoiceIssueJob(input: {
+  store: Pick<InvoiceStorePort, "claim" | "preflight" | "finish" | "fail">;
+  provider: Pick<InvoiceProviderPort, "issue" | "correct" | "read">;
+  money: InvoiceHostPorts["money"];
+  readLocalPayment(claim: InvoiceClaim): Promise<MoneyEvidence>;
+  providerRef: string;
+  orderId?: string | null;
+  limit?: number;
+  visibilitySeconds?: number;
+}) {
+  const batch = await input.store.claim({ limit: input.limit ?? 10, visibilitySeconds: input.visibilitySeconds ?? 300,
+    providerRef: input.providerRef, orderId: input.orderId });
+  if ("kind" in batch) return batch;
+  let updated = 0, failures = 0;
+  for (const native of batch) {
+    const claim = { ...native, attemptCount: native.generation };
+    let remoteStarted = false;
+    const retrySeconds = Math.min(3600, 300 * Math.max(1, claim.attemptCount));
+    const check = (result: { kind: string }) => {
+      if (result.kind === "stale") throw new ClaimFenceError("invoicing_claim_fence");
+      if (result.kind === "unsupported") throw new Error("invoicing_host_binding_required");
+    };
+    const fail = async (outcome: Parameters<InvoiceStorePort["fail"]>[0]) => {
+      check(await input.store.fail(outcome));
+    };
+    const preflight = async (evidence: MoneyEvidence) => {
+      const common = { claim, amountMinor: evidence.kind === "observed" ? evidence.amountMinor : null,
+        currency: evidence.kind === "observed" ? evidence.currency : null };
+      const result = await input.store.preflight(evidence.kind === "absent"
+        ? { ...common, status: "absent", evidence: evidence.evidence }
+        : { ...common, status: evidence.kind === "observed" ? evidence.status : "unavailable",
+          proof: evidence.kind === "observed" ? evidence.proof : null });
+      check(result);
+      return result.kind;
+    };
+    try {
+      if (claim.action === "readback") {
+        remoteStarted = true;
+        const result = await input.provider.read(claim.identity);
+        if (result.kind === "found") {
+          check(await input.store.finish({ claim, result }));
+          updated++;
+        } else {
+          await fail(result.kind === "absent" ? { claim, retrySeconds, kind: "absent", evidence: result }
+            : { claim, retrySeconds, kind: "unknown", proof: null });
+          failures++;
+        }
+        continue;
+      }
+      // Non-observed local evidence is unavailable, never a reason to stop the
+      // owed duty. A fresh authoritative host read still runs before dispatch.
+      const local = await preflight(await input.readLocalPayment(claim));
+      if (local === "blocked" || local === "mismatch") {
+        await fail({ claim, retrySeconds, kind: "blocked", proof: null });
+        failures++; continue;
+      }
+      const fresh = await preflight(await input.money.read({ intentRef: claim.facts.payment.intentRef,
+        providerRef: claim.facts.payment.providerRef ?? input.providerRef,
+        providerPaymentRef: claim.facts.payment.providerPaymentRef,
+        expectedMoney: { amountMinor: claim.facts.totalGrossMinor, currency: claim.facts.currency } }));
+      if (fresh !== "ready") {
+        await fail(fresh === "unavailable" ? { claim, retrySeconds, kind: "retryable", phase: "before_send", proof: null }
+          : { claim, retrySeconds, kind: "blocked", proof: null });
+        failures++; continue;
+      }
+      const correctionFacts = claim.correction && { ...claim.correction.before,
+        seller: claim.facts.seller, sellerRevision: claim.facts.sellerRevision, sellerMode: claim.facts.sellerMode };
+      remoteStarted = true;
+      const result = claim.correction
+        ? await input.provider.correct({ identity: { ...claim.identity, operation: "full_reversal",
+          correctionRef: claim.identity.correctionRef!, parentProviderDocumentRef: claim.identity.parentProviderDocumentRef! },
+          ...claim.correction,
+          before: correctionFacts!,
+          recoveryLookupRequired: claim.attemptCount > 1 })
+        : await input.provider.issue({ identity: { ...claim.identity, operation: "issue", correctionRef: null, parentProviderDocumentRef: null },
+          facts: claim.facts, recoveryLookupRequired: claim.attemptCount > 1 });
+      if (result.kind === "issued") {
+        check(await input.store.finish({ claim, result })); updated++;
+      } else {
+        await fail(result.kind === "refused" && result.retryable
+          ? { claim, retrySeconds, kind: "retryable", phase: "before_send", proof: null }
+          : { claim, retrySeconds, kind: result.kind === "refused" ? "blocked" : result.kind === "unsupported" ? "unsupported" : "unknown", proof: null });
+        failures++;
+      }
+    } catch (error) {
+      failures++;
+      if (error instanceof ClaimFenceError) continue;
+      const recorded = await input.store.fail(remoteStarted ? { claim, retrySeconds, kind: "unknown", proof: null }
+        : { claim, retrySeconds, kind: "retryable", phase: "before_send", proof: null });
+      if (recorded.kind !== "stale") check(recorded);
+    }
+  }
+  return { checked: batch.length, updated, failures, ok: failures === 0 };
+}