@openlup/platform 0.22.0 → 0.24.0

package/dist/invoicing/documentHistory.d.ts

@@ -0,0 +1,50 @@
+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;
+}
+export declare function resolveInvoiceDocumentHistory({ invoices, operations, deliveryOutboxes, providerArtifactEligible, }: ResolveInvoiceDocumentHistoryInput): InvoiceDocumentHistory;
+export {};

package/dist/invoicing/documentHistory.js

@@ -0,0 +1,213 @@
+const CURRENT_STATUSES = new Set(["issued", "accepted"]);
+const HISTORICAL_INVOICE_STATUSES = new Set(["issued", "accepted", "corrected"]);
+export function resolveInvoiceDocumentHistory({ invoices, operations = [], deliveryOutboxes = [], providerArtifactEligible = () => true, }) {
+    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 = [];
+    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, providerArtifactEligible) {
+    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, providerArtifactEligible) {
+    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, }) {
+    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) {
+    return nullableText(record(row.metadata).correctionProviderDocumentRef);
+}
+function correctionProviderDocumentNumber(row) {
+    return nullableText(record(row.metadata).correctionProviderDocumentNumber);
+}
+function compareRowsChronologically(a, b) {
+    return compareTimestamps(a.created_at, b.created_at) || text(a.id).localeCompare(text(b.id));
+}
+function compareRowsNewestFirst(a, b) {
+    return compareTimestamps(b.created_at ?? b.updated_at, a.created_at ?? a.updated_at) || text(b.id).localeCompare(text(a.id));
+}
+function compareDocumentsChronologically(a, b) {
+    return compareTimestamps(a.createdAt, b.createdAt)
+        || documentRolePriority(a.role) - documentRolePriority(b.role)
+        || a.documentKey.localeCompare(b.documentKey);
+}
+function documentRolePriority(role) {
+    if (role === "original")
+        return 0;
+    if (role === "correction")
+        return 1;
+    return 2;
+}
+function laterTimestamp(a, b) {
+    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, b) {
+    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) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 ? value : null;
+}
+function record(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : {};
+}
+function normalize(value) {
+    return text(value).trim().toLowerCase();
+}
+function text(value) {
+    return typeof value === "string" ? value : "";
+}
+function nullableText(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}

package/dist/invoicing/documentSync.d.ts

@@ -0,0 +1,24 @@
+/** 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 declare 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 declare 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;
+}>;

package/dist/invoicing/documentSync.js

@@ -0,0 +1,26 @@
+export async function syncAcceptedInvoiceDocuments(input) {
+    const sync = async (target, 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, input.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, failures };
+}

package/dist/invoicing/dutyCollector.d.ts

@@ -0,0 +1,15 @@
+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 declare function collectInvoiceDuties(input: {
+    store: Pick<InvoiceStorePort, "sweep" | "prepareFacts" | "finishFacts">;
+    limit?: number;
+}): Promise<{
+    kind: "collected";
+    collected: number;
+    prepared: number;
+    failures: number;
+} | InvoiceUnsupported>;

package/dist/invoicing/dutyCollector.js

@@ -0,0 +1,35 @@
+/** 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) {
+    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/dist/invoicing/fulfillmentTrigger.d.ts

@@ -0,0 +1,56 @@
+interface AccountingInvoiceIssuePort {
+    requestInvoiceIssueFromPaidOrder(input: {
+        idempotencyKey: string;
+        orderId: string;
+        providerKind: string;
+    }): Promise<unknown>;
+    requestInvoiceIssueFromFulfillmentHandoff(input: {
+        idempotencyKey: string;
+        fulfillmentOrderId: string;
+        providerKind: string;
+    }): Promise<unknown>;
+}
+import { type OrderInvoicePolicyReader } from "./channelPolicy.js";
+export type AutoDispatchFulfillmentResult = {
+    kind: "completed" | "skipped";
+    detail?: Record<string, unknown>;
+} | {
+    kind: "retryable" | "snooze" | "fatal";
+    reason: string;
+} | {
+    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";
+    invoicePolicyReader?: OrderInvoicePolicyReader;
+}
+export declare function withAccountingInvoiceShadowTrigger<TResult, TPort extends FulfillmentHandoffPort<TResult>>(fulfillmentPort: TPort, options: Omit<AccountingHandoffTriggerOptions, "accountingPort"> & {
+    accountingPort: Pick<AccountingInvoiceIssuePort, "requestInvoiceIssueFromFulfillmentHandoff"> & Partial<AccountingInvoiceIssuePort>;
+}): TPort;
+export declare function withAutoDispatchAccountingInvoiceTrigger(fulfillmentPort: AutoDispatchFulfillmentPort, options: AccountingHandoffTriggerOptions): AutoDispatchFulfillmentPort;
+export {};

package/dist/invoicing/fulfillmentTrigger.js

@@ -0,0 +1,90 @@
+import { decideChannelInvoice, } from "./channelPolicy.js";
+export function withAccountingInvoiceShadowTrigger(fulfillmentPort, options) {
+    return {
+        ...fulfillmentPort,
+        async handOffCommerceFulfillmentOrder(request) {
+            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;
+        },
+    };
+}
+// 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, options) {
+    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", 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) {
+    if (result.kind !== "completed" && result.kind !== "skipped")
+        return null;
+    const id = result.detail?.fulfillmentOrderId;
+    return typeof id === "string" ? id : null;
+}

package/dist/invoicing/handoff.d.ts

@@ -0,0 +1,37 @@
+import type { ChannelInvoiceDecision } from "./channelPolicy.js";
+/** Host retains event schema, key scopes, RPC error class and compatibility detail. */
+export declare 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;
+    };
+}): {
+    handle(row: Row, signal: AbortSignal): Promise<{
+        kind: "processed";
+        detail: Record<string, unknown>;
+    } | {
+        kind: "discard";
+        reason: string;
+        benign?: boolean;
+    } | {
+        kind: "retry";
+        reason: string;
+    }>;
+    eventType: string;
+    timeoutMs: number;
+};

package/dist/invoicing/handoff.js

@@ -0,0 +1,62 @@
+// 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(input) {
+    return {
+        ...input.descriptor,
+        async handle(row, signal) {
+            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/dist/invoicing/index.d.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";