@openlup/platform 0.23.0 → 0.25.0

package/dist/invoicing/bindings.js

@@ -0,0 +1,69 @@
+import { createIndependentInvoiceDutyBinding } from "./continuity.js";
+import { runNativeInvoiceIssueJob } from "./postgresInvoiceStore.js";
+import { runInvoiceDeliveryJob } from "./delivery.js";
+import { syncAcceptedInvoiceDocuments } from "./documentSync.js";
+import { syncInvoicePayoutSettlements } from "./settlementSync.js";
+import { createInvoiceReadModel } from "./readModel.js";
+import { readInvoiceCapabilities } from "./capabilities.js";
+/** Explicit selection and host readiness precede factory construction and claim.
+ * Native jobs use the installed module helpers; transport-specific host facades
+ * may supply factories. Auth, invocation scope and leases stay host-owned.
+ */
+export function createInvoiceServices(options) {
+    const { enabled, selection, capability, provider, store, host, readiness: observe } = options;
+    const factories = { ...options.factories };
+    const unsupported = { kind: "unsupported", code: "host_binding_required", retryable: false, effectMayHaveSucceeded: false };
+    const readiness = async () => {
+        const selected = readInvoiceCapabilities({ enabled, selection, capability });
+        if (selected.kind !== "ready")
+            return selected;
+        if (!provider || !store)
+            return unsupported;
+        return observe();
+    };
+    return {
+        readiness,
+        async run(operation) {
+            const state = await readiness();
+            if (state.kind !== "ready")
+                return state;
+            const factory = factories[operation];
+            const capabilityKey = operation === "documentSync" ? "readback"
+                : operation === "settlementSync" ? "settlement" : operation;
+            if ((capabilityKey === "issue" || capabilityKey === "correction" || capabilityKey === "readback" || capabilityKey === "settlement")
+                && !capability.operations[capabilityKey].supported)
+                return unsupported;
+            if (factory)
+                return factory({ provider: provider, store: store, capability: capability, host })();
+            const jobs = options.jobs;
+            // Inputs are explicit host selections. No operation acquires a host run lease.
+            if (operation === "collectDuties" && jobs?.collectDuties)
+                return createIndependentInvoiceDutyBinding({ ...jobs.collectDuties, store: store }).collect();
+            // The native claim batch includes issue and correction/readback duties.
+            if (operation === "issue" && jobs?.issue && (!capability.operations.correction.supported || !capability.operations.readback.supported))
+                return unsupported;
+            if (operation === "issue" && jobs?.issue)
+                return runNativeInvoiceIssueJob({ ...jobs.issue, store: store, provider: provider, money: host.money, providerRef: selection.providerRef });
+            if (operation === "delivery" && jobs?.delivery)
+                return runInvoiceDeliveryJob({
+                    enabled: true, providerEnabled: true, deliveryEnabled: true, store: store, ...jobs.delivery,
+                    download: async (claim) => {
+                        const artifact = await host.artifacts.read({ identity: claim.identity, kind: "pdf" });
+                        if (artifact.kind !== "found")
+                            throw new Error("invoicing_artifact_unavailable");
+                        const result = await host.artifacts.download({ identity: claim.identity, artifactRef: artifact.artifact.ref });
+                        if (result.kind !== "downloaded")
+                            throw new Error("invoicing_artifact_unavailable");
+                        return result;
+                    }, send: input => host.delivery.send(input),
+                });
+            if (operation === "documentSync" && jobs?.documentSync)
+                return syncAcceptedInvoiceDocuments(jobs.documentSync);
+            if (operation === "settlementSync" && jobs?.settlementSync)
+                return syncInvoicePayoutSettlements({ ...jobs.settlementSync, settlement: host.settlement });
+            if (operation === "history" && jobs?.history)
+                return createInvoiceReadModel({ accountHistory: host.accountHistory }).history(jobs.history);
+            return unsupported;
+        },
+    };
+}

package/dist/invoicing/channelPolicy.d.ts

@@ -0,0 +1,28 @@
+type ChannelInvoiceAction = "issue" | "channel_issues" | "suppress";
+export type InvoicePolicyLookup = {
+    by: "order";
+    orderUuid: string;
+} | {
+    by: "fulfillmentOrder";
+    fulfillmentOrderId: string;
+};
+/** Reads the resolved sales-source invoice action for either producer key.
+ * Read failures propagate to the caller.
+ */
+export interface OrderInvoicePolicyReader {
+    readOrderInvoicePolicy(lookup: InvoicePolicyLookup): Promise<ChannelInvoiceAction>;
+}
+export interface ChannelInvoiceDecision {
+    issue: boolean;
+    action: ChannelInvoiceAction;
+    detail: Record<string, unknown>;
+}
+/**
+ * Whether this deployment should request the sales document for an order.
+ *
+ * An ABSENT reader answers `issue`. Composition roots that predate this wave —
+ * and every test that builds a producer without one — keep today's behaviour
+ * exactly, which is what makes the storefront path provably unchanged.
+ */
+export declare function decideChannelInvoice(reader: OrderInvoicePolicyReader | undefined, lookup: InvoicePolicyLookup): Promise<ChannelInvoiceDecision>;
+export {};

package/dist/invoicing/channelPolicy.js

@@ -0,0 +1,27 @@
+const ISSUE = { issue: true, action: "issue", detail: {} };
+function refusal(action) {
+    return {
+        issue: false,
+        action,
+        detail: action === "channel_issues"
+            // The far side mints the document. Stamped with the same key an order
+            // metadata write would have used, so a later wave that gains a metadata
+            // path moves the value rather than renaming it.
+            ? { invoicePolicy: action, invoiceIssuedBy: "channel", accountingInvoiceSkipped: action }
+            // The operator declared that no sales document is produced at all.
+            : { invoicePolicy: action, accountingInvoiceSkipped: action },
+    };
+}
+/**
+ * Whether this deployment should request the sales document for an order.
+ *
+ * An ABSENT reader answers `issue`. Composition roots that predate this wave —
+ * and every test that builds a producer without one — keep today's behaviour
+ * exactly, which is what makes the storefront path provably unchanged.
+ */
+export async function decideChannelInvoice(reader, lookup) {
+    if (!reader)
+        return ISSUE;
+    const action = await reader.readOrderInvoicePolicy(lookup);
+    return action === "issue" ? ISSUE : refusal(action);
+}

package/dist/invoicing/continuity.d.ts

@@ -0,0 +1,12 @@
+import { collectInvoiceDuties } from "./dutyCollector.js";
+/** Explicit independent host invocation, never an inline fulfillment/payment hook.
+ * Durable source receipts and fact leases own replay, backoff and fault ceilings.
+ * A collector outage remains visible and can be retried by the host later.
+ * @consumer Reference native accounting runtime and installed cold consumer.
+ */
+export declare function createIndependentInvoiceDutyBinding(input: Parameters<typeof collectInvoiceDuties>[0]): {
+    collect(): Promise<Awaited<ReturnType<typeof collectInvoiceDuties>> | {
+        kind: "unavailable";
+        code: "retryable";
+    }>;
+};

package/dist/invoicing/continuity.js

@@ -0,0 +1,18 @@
+import { collectInvoiceDuties } from "./dutyCollector.js";
+/** Explicit independent host invocation, never an inline fulfillment/payment hook.
+ * Durable source receipts and fact leases own replay, backoff and fault ceilings.
+ * A collector outage remains visible and can be retried by the host later.
+ * @consumer Reference native accounting runtime and installed cold consumer.
+ */
+export function createIndependentInvoiceDutyBinding(input) {
+    return {
+        async collect() {
+            try {
+                return await collectInvoiceDuties(input);
+            }
+            catch {
+                return { kind: "unavailable", code: "retryable" };
+            }
+        },
+    };
+}

package/dist/invoicing/contracts/facts.d.ts

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

package/dist/invoicing/contracts/host.d.ts

@@ -20,8 +20,8 @@ export interface InvoiceHostPorts {
         } | InvoiceUnsupported>;
     };
     /** Read the current host seller for the next claim, never per duty. Null orderId
-     * means an unscoped claim (including corrections). P8 freezes this seller at
-     * first claim; revisionRef feeds the claim wrapper's revision argument.
+     * means an unscoped claim (including corrections). The durable wrapper freezes this seller at
+     * the first-ever claim; revisionRef feeds the claim wrapper's revision argument.
      */
     seller: {
         read(input: {
@@ -228,8 +228,7 @@ export interface InvoiceHostPorts {
         } | InvoiceUnsupported>;
     };
 }
-/** Future service composition inputs only; no constructor, worker or runtime route
- * is supplied in P1. Closures/credentials must never be serialized with options.
+/** Explicit service composition inputs; the host retains worker and route authority. Closures/credentials must never be serialized with options.
  */
 export interface InvoiceServicesOptions {
     readonly enabled?: boolean;

package/dist/invoicing/contracts/index.d.ts

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

package/dist/invoicing/contracts/store.d.ts

@@ -1,5 +1,5 @@
 import type { InvoiceHostPorts } from "./host.js";
-import type { InvoiceFacts } from "./facts.js";
+import type { InvoiceFacts, InvoiceClaimedFacts } from "./facts.js";
 import type { InvoiceIdentity, InvoiceDocumentIdentity, InvoiceProof, InvoiceUnsupported, InvoiceWriteResult, InvoiceReadbackResult } from "./provider.js";
 import type { InvoiceClearanceObservation, InvoiceArtifactResult, InvoiceDeliveryPort } from "./delivery.js";
 type InvoiceDutyStatus = "owed" | "blocked" | "ready" | "processing" | "unknown" | "issued" | "voided" | "unsupported" | "faulted";
@@ -14,7 +14,7 @@ export interface InvoiceClaim {
     readonly generation: number;
     readonly leaseUntil: string;
     readonly identity: InvoiceIdentity;
-    readonly facts: InvoiceFacts;
+    readonly facts: InvoiceClaimedFacts;
     readonly action: "create" | "readback";
     readonly correction: {
         readonly before: InvoiceFacts;
@@ -53,7 +53,8 @@ export interface InvoiceDutyReadback {
 }
 /** Every operation is one local transaction; commit before external I/O. Native
  * success atomically saves late identity and compensation; stale catch writes nothing.
- * Managed and native stores are bound to the selected provider at construction.
+ * Compatibility stores bind provider selection at construction; the structural
+ * native store accepts it per claim and persists the first provider on the duty.
  * No implementation, executor or migration is installed by these declarations.
  */
 export interface InvoiceStorePort {
@@ -77,6 +78,9 @@ export interface InvoiceStorePort {
     }): Promise<{
         readonly dutyId: string;
         readonly status: InvoiceDutyStatus;
+    } | {
+        readonly kind: "conflict";
+        readonly code: "identity_mismatch";
     } | InvoiceUnsupported>;
     installFacts(input: {
         readonly dutyId: string;
@@ -118,7 +122,7 @@ export interface InvoiceStorePort {
     } | InvoiceUnsupported>;
     readDuties(orderId: string): Promise<InvoiceDutyReadback | InvoiceUnsupported>;
     /** Filter order before locking/limit; never lease unrelated orders then filter.
-     * P8 reads the injected host seller before calling the first-claim SQL wrapper;
+     * P7 host composition reads the injected seller before the separate first-claim SQL wrapper;
      * its revisionRef supplies p_revision, without requiring a duty from the caller.
      */
     claim(input: {
@@ -194,6 +198,9 @@ export interface InvoiceStorePort {
         readonly kind: "unsupported_recorded";
         readonly dutyId?: string;
         readonly replayed?: boolean;
+    } | {
+        readonly kind: "conflict";
+        readonly code: "identity_mismatch";
     } | InvoiceUnsupported>;
     /** Existing local-only request remains distinct from fiscal issuance. */
     requestLocalDocument(input: {
@@ -250,7 +257,10 @@ export interface InvoiceStorePort {
     }[] | InvoiceUnsupported>;
     /** Native uncertain settlement passes p_receipt NULL and retains a non-null
      * receiptRef hint in p_evidence; managed uses it as the provider message id.
-     * Managed failed_before_send uses retrySeconds for backoff; native ignores it.
+     * Managed failed_before_send uses the retrySeconds RPC argument. Native
+     * failed_before_send carries { phase: 'before_send', retryable, retrySeconds }
+     * in p_evidence: whole seconds clamp to 60..86400, absent/invalid uses 900.
+     * retryable:false parks at infinity, with failed status and last_error visible.
      */
     settleDelivery(input: {
         readonly deliveryRef: string;

package/dist/invoicing/contribution.d.ts

@@ -0,0 +1,21 @@
+import type { Contribution, RequiredSchema } from "@openlup/core/readiness";
+/** Inert descriptors for the host's existing registry and executor. No registration. */
+export declare function createInvoiceContribution(input: {
+    version: string;
+    requiredSchema: RequiredSchema;
+    invoicing: Readonly<Record<string, ((...args: never[]) => unknown) | null>>;
+    handlers: Contribution["handlers"];
+    schedules: Contribution["schedules"];
+    routes: Contribution["routes"];
+}): {
+    contributions: Contribution[];
+    ports: {
+        [k: string]: ((...args: never[]) => unknown) | null;
+    };
+    routes: {
+        [k: string]: (...args: never[]) => unknown;
+    };
+    triggers: {
+        [k: string]: (...args: never[]) => unknown;
+    };
+};

package/dist/invoicing/contribution.js

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

package/dist/invoicing/correction.d.ts

@@ -0,0 +1,42 @@
+import type { InvoiceWriteResult } from "./contracts/provider.js";
+/** Durable correction identity, recovery and claim fencing from the donor worker.
+ * Hosts project immutable BEFORE facts and bind a conforming recovery provider.
+ * @consumer server/domains/accounting/accountingJobService.ts
+ */
+export declare function runInvoiceCorrectionJob<Claim extends {
+    outboxId: string;
+    attemptCount: number;
+    providerInvoiceId: string;
+    correctionReason: string;
+    payload: Record<string, unknown>;
+}, Snapshot, Result extends Pick<Extract<InvoiceWriteResult, {
+    kind: "issued";
+}>, "providerDocumentRef" | "providerDocumentNumber">>(input: {
+    createEnabled: boolean;
+    providerEnabled: boolean;
+    claim(): Promise<readonly Claim[]>;
+    project(claim: Claim): Snapshot;
+    /** Resolve accepted/recovered receipts only; unknown is never an ACK or absence. */
+    create(snapshot: Snapshot, options: {
+        correctionReason: string;
+        correctedProviderInvoiceId: string;
+        correctionRef: string;
+        recoveryLookupRequired: boolean;
+    }): Promise<Result>;
+    finish(claim: Claim, result: Result): Promise<unknown>;
+    isClaimFenceError(error: unknown): boolean;
+    fail(claim: Claim, error: unknown, retrySeconds: number): Promise<unknown>;
+}): Promise<{
+    ok: boolean;
+    checked: number;
+    updated: number;
+    skipped: boolean;
+    reason: string;
+    failures: number;
+} | {
+    ok: boolean;
+    checked: number;
+    updated: number;
+    skipped: boolean;
+    failures: number;
+}>;

package/dist/invoicing/correction.js

@@ -0,0 +1,44 @@
+/** Durable correction identity, recovery and claim fencing from the donor worker.
+ * Hosts project immutable BEFORE facts and bind a conforming recovery provider.
+ * @consumer server/domains/accounting/accountingJobService.ts
+ */
+export async function runInvoiceCorrectionJob(input) {
+    if (!input.createEnabled)
+        return skipped("create_disabled");
+    if (!input.providerEnabled)
+        return skipped("provider_disabled");
+    const claims = await input.claim();
+    let updated = 0;
+    let failures = 0;
+    for (const claim of claims) {
+        try {
+            const correctionRef = `accounting-correction:${claim.outboxId}`;
+            if (claim.payload.providerCreateIdentity !== correctionRef) {
+                throw new Error("accounting_correction_recovery_identity_missing");
+            }
+            const snapshot = input.project(claim);
+            const result = await input.create(snapshot, {
+                correctionReason: claim.correctionReason,
+                correctedProviderInvoiceId: claim.providerInvoiceId,
+                correctionRef,
+                recoveryLookupRequired: claim.attemptCount > 1,
+            });
+            await input.finish(claim, result);
+            updated += 1;
+        }
+        catch (error) {
+            failures += 1;
+            if (input.isClaimFenceError(error))
+                continue;
+            try {
+                await input.fail(claim, error, Math.min(3600, 300 * Math.max(1, claim.attemptCount)));
+            }
+            catch (failureError) {
+                if (!input.isClaimFenceError(failureError))
+                    throw failureError;
+            }
+        }
+    }
+    return { ok: failures === 0, checked: claims.length, updated, skipped: false, failures };
+}
+function skipped(reason) { return { ok: true, checked: 0, updated: 0, skipped: true, reason, failures: 0 }; }

package/dist/invoicing/delivery.d.ts

@@ -0,0 +1,85 @@
+import type { InvoiceUnsupported } from "./contracts/provider.js";
+import type { InvoiceStorePort } from "./contracts/store.js";
+import type { InvoiceDeliveryPort } from "./contracts/delivery.js";
+type DeliveryOutcome = Omit<Extract<Awaited<ReturnType<InvoiceDeliveryPort["send"]>>, {
+    kind: "provider_accepted";
+}>, "proof"> | Exclude<Awaited<ReturnType<InvoiceDeliveryPort["send"]>>, {
+    kind: "provider_accepted";
+}>;
+/** Donor sequencing over host claims, original keys, M04 transport and fenced
+ * finalizers. Native hosts MUST bind terminalFailure before leasing work.
+ * With CTL-M09-3's 191000 pin, failedBeforeSend settles failed_before_send with
+ * evidence { phase: 'before_send', retrySeconds }: whole seconds clamped
+ * to 60..86400, absent/invalid uses 900;
+ * terminalFailure uses { phase: 'before_send', retryable: false } for no reclaim.
+ * Native store mode refuses before claim unless its host projection is bound.
+ * @consumer Host delivery facade and explicit native M04 binding.
+ */
+type DeliveryJobInput<Claim, Result extends DeliveryOutcome> = {
+    enabled: boolean;
+    providerEnabled: boolean;
+    deliveryEnabled: boolean;
+    claim(): Promise<readonly Claim[] | InvoiceUnsupported>;
+    attemptCount(claim: Claim): number;
+    validate(claim: Claim): void;
+    download(claim: Claim): Promise<{
+        content: Uint8Array;
+        contentType: string;
+    }>;
+    filename(claim: Claim): string;
+    /** A rejected promise proves failure BEFORE transport entry. Once entered,
+     * the M04 binding must return uncertain, including timeout/lost ACK. */
+    send(claim: Claim, document: {
+        filename: string;
+        content: Uint8Array;
+        contentType: string;
+    }): Promise<Result>;
+    failedBeforeSend(claim: Claim, error: unknown, retrySeconds: number): Promise<unknown>;
+    /** Must durably stop reclaim using the same fence. Native failed_before_send
+     * evidence { phase: 'before_send', retryable: false } sets available_at to infinity. */
+    terminalFailure(claim: Claim, result: Extract<Result, {
+        kind: "failed_before_send" | "unsupported";
+    }>): Promise<unknown>;
+    uncertain(claim: Claim, result: Extract<Result, {
+        kind: "uncertain";
+    }>): Promise<unknown>;
+    accepted(claim: Claim, result: Extract<Result, {
+        kind: "provider_accepted";
+    }>): Promise<unknown>;
+    finalizeUncertain(claim: Claim, receiptRef: string): Promise<unknown>;
+};
+type NativeClaim = Exclude<Awaited<ReturnType<InvoiceStorePort["claimDeliveries"]>>, InvoiceUnsupported>[number];
+type NativeDeliveryJobInput = {
+    enabled: boolean;
+    providerEnabled: boolean;
+    deliveryEnabled: boolean;
+    store: Pick<InvoiceStorePort, "claimDeliveries" | "settleDelivery">;
+    claimOptions: Parameters<InvoiceStorePort["claimDeliveries"]>[0];
+    download(claim: NativeClaim): Promise<{
+        content: Uint8Array;
+        contentType: string;
+    }>;
+    filename(claim: NativeClaim): string;
+    send: InvoiceDeliveryPort["send"];
+};
+/** Host callback mode preserves donor sequencing. Native store mode supplies
+ * fenced terminal/backoff finalizers and the M04 envelope from claimDeliveries.
+ * @consumer Host delivery facade and explicit native M04 binding.
+ */
+export declare function runInvoiceDeliveryJob(input: NativeDeliveryJobInput): ReturnType<typeof runDeliveryJob>;
+export declare function runInvoiceDeliveryJob<Claim, Result extends DeliveryOutcome>(input: DeliveryJobInput<Claim, Result>): ReturnType<typeof runDeliveryJob>;
+declare function runDeliveryJob<Claim, Result extends DeliveryOutcome>(input: DeliveryJobInput<Claim, Result>): Promise<{
+    ok: boolean;
+    checked: number;
+    updated: number;
+    skipped: boolean;
+    reason: string;
+    failures: number;
+} | {
+    ok: boolean;
+    checked: number;
+    updated: number;
+    skipped: boolean;
+    failures: number;
+}>;
+export {};

package/dist/invoicing/delivery.js

@@ -0,0 +1,79 @@
+import { assertInvoicePdf } from "./artifacts.js";
+export function runInvoiceDeliveryJob(input) {
+    if (!("store" in input))
+        return runDeliveryJob(input);
+    const settle = async (claim, result, retrySeconds = 900) => {
+        const outcome = await input.store.settleDelivery({ deliveryRef: claim.delivery.deliveryRef, token: claim.token,
+            generation: claim.generation, providerDocumentRef: claim.providerDocumentRef, retrySeconds, result });
+        if (outcome.kind !== "recorded")
+            throw new Error("invoicing_delivery_fence");
+    };
+    return runDeliveryJob({
+        enabled: input.enabled, providerEnabled: input.providerEnabled, deliveryEnabled: input.deliveryEnabled,
+        claim: () => input.store.claimDeliveries(input.claimOptions), attemptCount: claim => claim.generation,
+        validate: () => { }, download: input.download, filename: input.filename,
+        send: (claim, document) => input.send({ ...claim.delivery, ...document }),
+        failedBeforeSend: (claim, _error, retrySeconds) => settle(claim, { kind: "failed_before_send", retryable: true, code: "retryable" }, retrySeconds),
+        terminalFailure: (claim, result) => settle(claim, result.kind === "failed_before_send" ? result
+            : { kind: "failed_before_send", retryable: false, code: "retryable" }),
+        uncertain: (claim, result) => settle(claim, result), accepted: (claim, result) => settle(claim, result),
+        finalizeUncertain: (claim, receiptRef) => settle(claim, { kind: "uncertain", code: "uncertain_delivery", receiptRef }),
+    });
+}
+async function runDeliveryJob(input) {
+    if (!input.enabled)
+        return skipped("provider_email_disabled");
+    if (!input.providerEnabled)
+        return skipped("provider_disabled");
+    if (!input.deliveryEnabled)
+        return skipped("email_delivery_provider_disabled");
+    // JS hosts missing a mandatory terminal policy must refuse before claiming.
+    if (typeof input.terminalFailure !== "function")
+        return skipped("host_binding_required");
+    const claims = await input.claim();
+    if (!Array.isArray(claims))
+        return skipped("host_binding_required");
+    let updated = 0;
+    let failures = 0;
+    for (const claim of claims) {
+        let result;
+        const retrySeconds = Math.min(3600, 300 * Math.max(1, input.attemptCount(claim)));
+        try {
+            input.validate(claim);
+            const pdf = await input.download(claim);
+            assertInvoicePdf(pdf);
+            result = await input.send(claim, { ...pdf, filename: input.filename(claim) });
+        }
+        catch (error) {
+            failures += 1;
+            await input.failedBeforeSend(claim, error, retrySeconds);
+            continue;
+        }
+        if (result.kind === "failed_before_send" || result.kind === "unsupported") {
+            failures += 1;
+            if (result.kind === "failed_before_send" && result.retryable) {
+                await input.failedBeforeSend(claim, result, retrySeconds);
+            }
+            else {
+                await input.terminalFailure(claim, result);
+            }
+            continue;
+        }
+        if (result.kind === "uncertain") {
+            failures += 1;
+            await input.uncertain(claim, result);
+            continue;
+        }
+        try {
+            await input.accepted(claim, result);
+            updated += 1;
+        }
+        catch {
+            failures += 1;
+            // Acceptance plus a lost local ACK cannot become a retryable send.
+            await input.finalizeUncertain(claim, result.receiptRef).catch(() => undefined);
+        }
+    }
+    return { ok: failures === 0, checked: claims.length, updated, skipped: false, failures };
+}
+function skipped(reason) { return { ok: true, checked: 0, updated: 0, skipped: true, reason, failures: 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 {};