@openlup/platform 0.23.0 → 0.24.0

package/dist/invoicing/postgresInvoiceStore.js

@@ -0,0 +1,344 @@
+import { claimInvoiceSellerRevision } from "./sellerRevision.js";
+import { createNativeUnsupportedInvoicePorts } from "./nativeUnsupported.js";
+const unsupported = { kind: "unsupported", code: "host_binding_required", retryable: false, effectMayHaveSucceeded: false };
+/** 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, options) {
+    async function call(name, values) {
+        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;
+    }
+    const fence = (claim) => [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, orderId: row.orderId }));
+        },
+        async captureDuty(v) {
+            try {
+                return await call("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("invoicing_install_facts", [v.dutyId, v.facts, v.facts.factRevision]);
+        },
+        sweep: limit => call("invoicing_sweep_duties", [limit]),
+        async prepareFacts(v) {
+            const result = await call("invoicing_prepare_facts", [v.dutyId, v.token]);
+            const { kind, ...rest } = result;
+            return kind ? { ...rest, code: kind } : rest;
+        },
+        async finishFacts(v) {
+            const result = await call("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)))
+                return unsupported;
+            const rows = await call("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;
+                if (!validFacts(facts))
+                    throw new Error("invoicing_native_facts_invalid");
+                const correction = row.parent_duty_id !== null;
+                return {
+                    dutyId: row.id, documentId: row.document_id, requestId: row.request_id,
+                    token: row.claim_token, generation: row.generation, leaseUntil: row.lease_until,
+                    identity: identity(row, facts), facts: { ...facts, seller: row.seller, sellerRevision: row.sellerRevision, sellerMode: row.sellerMode },
+                    action: row.last_result.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("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("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;
+            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("invoicing_claim_deliveries", [v.limit, v.visibilitySeconds, v.requireClearance, v.orderId ?? null]);
+            const claims = [];
+            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("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("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) { return typeof error === "object" && error !== null && "code" in error && error.code === "23505"; }
+function sameIdentity(a, b) {
+    return Object.keys(a).every(key => a[key] === b[key]);
+}
+function identity(row, facts) {
+    const correction = row.parent_duty_id !== null;
+    return {
+        providerRef: row.provider, requestKey: row.original_key,
+        providerCreateIdentity: row.providerCreateIdentity, 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) { return typeof value === "string" && value.trim().length > 0; }
+function validFacts(facts) {
+    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`;
+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) {
+    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) => {
+            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) => {
+            check(await input.store.fail(outcome));
+        };
+        const preflight = async (evidence) => {
+            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 };
+}

package/dist/invoicing/readModel.d.ts

@@ -0,0 +1,74 @@
+import type { InvoiceHostPorts, InvoiceIdentity, InvoiceProviderPort, InvoiceStorePort } from "./contracts/index.js";
+/** Read-only orchestration. Auth, owner resolution and queries stay in host
+ * callbacks. Safe native account projections preserve negative correction totals,
+ * currency and parent identity without exposing provider payloads or URLs.
+ * @consumer Customer download/history and authorized operator host facades.
+ */
+export declare function createInvoiceReadModel(ports?: {
+    accountHistory?: InvoiceHostPorts["accountHistory"];
+    artifacts?: Pick<InvoiceHostPorts["artifacts"], "download">;
+    provider?: Pick<InvoiceProviderPort, "read">;
+    duties?: Pick<InvoiceStorePort, "readDuties">;
+}): {
+    history(input: Parameters<InvoiceHostPorts["accountHistory"]["read"]>[0]): ReturnType<InvoiceHostPorts["accountHistory"]["read"]>;
+    download(input: Parameters<InvoiceHostPorts["accountHistory"]["resolveDownload"]>[0]): Promise<{
+        readonly kind: "unsupported";
+        readonly code: "host_binding_required";
+        readonly retryable: false;
+        readonly effectMayHaveSucceeded: false;
+    } | {
+        readonly kind: "unknown";
+        readonly code: "unknown";
+    } | {
+        kind: "denied";
+        content?: undefined;
+        contentType?: undefined;
+        fileName?: undefined;
+        parentDocumentRef?: undefined;
+    } | {
+        kind: "downloaded";
+        content: Uint8Array<ArrayBufferLike>;
+        contentType: string;
+        fileName: string;
+        parentDocumentRef: string | null;
+    }>;
+    readback(identity: InvoiceIdentity): Promise<import("./contracts/provider.js").InvoiceReadbackResult | {
+        readonly kind: "unsupported";
+        readonly code: "host_binding_required";
+        readonly retryable: false;
+        readonly effectMayHaveSucceeded: false;
+    }>;
+    /** Operator-only duty readback. The host must authorize the caller before
+     * invoking it, as operator() does; this method has no auth hook of its own. */
+    readDuties(orderId: string): Promise<import("./contracts/provider.js").InvoiceUnsupported | import("./contracts/store.js").InvoiceDutyReadback | {
+        readonly kind: "unknown";
+        readonly code: "unknown";
+    }>;
+    /** The authorize callback runs before the query. HTTP status mapping stays host-owned. */
+    operator<Summary>(input: {
+        authorize(): Promise<boolean>;
+        read(): Promise<Summary>;
+    }): Promise<{
+        kind: "denied";
+        value?: undefined;
+    } | {
+        kind: "found";
+        value: Awaited<Summary>;
+    }>;
+    /** Legacy ticket resolver verifies the real order owner before any PDF I/O. */
+    ownedPdf<Ticket, Pdf extends {
+        content: Uint8Array;
+        contentType: string;
+    }>(input: {
+        resolve(): Promise<Ticket | null>;
+        download(ticket: Ticket): Promise<Pdf>;
+    }): Promise<{
+        kind: "denied";
+        ticket?: undefined;
+        pdf?: undefined;
+    } | {
+        kind: "downloaded";
+        ticket: NonNullable<Awaited<Ticket>>;
+        pdf: Pdf;
+    }>;
+};

package/dist/invoicing/readModel.js

@@ -0,0 +1,90 @@
+import { assertInvoicePdf } from "./artifacts.js";
+import { opaqueReference, readInvoiceReadback } from "./readback.js";
+const unsupported = () => ({ kind: "unsupported", code: "host_binding_required", retryable: false, effectMayHaveSucceeded: false });
+const unknown = () => ({ kind: "unknown", code: "unknown" });
+/** Read-only orchestration. Auth, owner resolution and queries stay in host
+ * callbacks. Safe native account projections preserve negative correction totals,
+ * currency and parent identity without exposing provider payloads or URLs.
+ * @consumer Customer download/history and authorized operator host facades.
+ */
+export function createInvoiceReadModel(ports = {}) {
+    return {
+        async history(input) {
+            if (!ports.accountHistory)
+                return unsupported();
+            try {
+                const result = await ports.accountHistory.read(input);
+                if (result.kind !== "found")
+                    return result.kind === "unsupported" ? unsupported() : result.kind === "denied" ? { kind: "denied" } : unknown();
+                if (result.accountRef !== input.accountRef || result.orderId !== input.orderId)
+                    return { kind: "denied" };
+                return {
+                    kind: "found", accountRef: input.accountRef, orderId: input.orderId,
+                    documents: result.documents.map(document => ({
+                        documentRef: document.documentRef, invoiceRef: document.invoiceRef,
+                        parentDocumentRef: document.parentDocumentRef, role: document.role,
+                        status: document.status, issuedAt: document.issuedAt,
+                        clearance: document.clearance ? { state: document.clearance.state, reference: document.clearance.reference } : null,
+                        documentKind: document.documentKind, artifact: document.artifact,
+                        providerDocumentNumber: document.providerDocumentNumber,
+                        totalGrossMinor: document.totalGrossMinor, currency: document.currency,
+                        emailState: document.emailState, isCurrent: document.isCurrent,
+                        createdAt: document.createdAt, downloadAvailable: document.downloadAvailable,
+                    })),
+                };
+            }
+            catch {
+                return unknown();
+            }
+        },
+        async download(input) {
+            if (!ports.accountHistory || !ports.artifacts)
+                return unsupported();
+            try {
+                const ticket = await ports.accountHistory.resolveDownload(input);
+                if (ticket.kind !== "authorized")
+                    return ticket.kind === "unsupported" ? unsupported() : ticket.kind === "denied" ? { kind: "denied" } : unknown();
+                if (ticket.identity.documentRef !== input.documentRef || !opaqueReference(ticket.artifactRef))
+                    return { kind: "denied" };
+                const pdf = await ports.artifacts.download({ identity: ticket.identity, artifactRef: ticket.artifactRef });
+                if (pdf.kind !== "downloaded")
+                    return pdf.kind === "unsupported" ? unsupported() : unknown();
+                assertInvoicePdf(pdf);
+                return { kind: "downloaded", content: pdf.content, contentType: pdf.contentType, fileName: ticket.fileName, parentDocumentRef: ticket.parentDocumentRef };
+            }
+            catch {
+                return unknown();
+            }
+        },
+        async readback(identity) {
+            return ports.provider ? readInvoiceReadback(ports.provider, identity) : unsupported();
+        },
+        /** Operator-only duty readback. The host must authorize the caller before
+         * invoking it, as operator() does; this method has no auth hook of its own. */
+        async readDuties(orderId) {
+            if (!ports.duties)
+                return unsupported();
+            try {
+                return await ports.duties.readDuties(orderId);
+            }
+            catch {
+                return unknown();
+            }
+        },
+        /** The authorize callback runs before the query. HTTP status mapping stays host-owned. */
+        async operator(input) {
+            if (!await input.authorize())
+                return { kind: "denied" };
+            return { kind: "found", value: await input.read() };
+        },
+        /** Legacy ticket resolver verifies the real order owner before any PDF I/O. */
+        async ownedPdf(input) {
+            const ticket = await input.resolve();
+            if (!ticket)
+                return { kind: "denied" };
+            const pdf = await input.download(ticket);
+            assertInvoicePdf(pdf);
+            return { kind: "downloaded", ticket, pdf };
+        },
+    };
+}

package/dist/invoicing/readback.d.ts

@@ -0,0 +1,4 @@
+import type { InvoiceIdentity, InvoiceProviderPort, InvoiceReadbackResult } from "./contracts/provider.js";
+/** Internal validation used by the read model. No nullable lookup shortcut. */
+export declare function readInvoiceReadback(provider: Pick<InvoiceProviderPort, "read">, identity: InvoiceIdentity): Promise<InvoiceReadbackResult>;
+export declare function opaqueReference(ref: string): boolean;

package/dist/invoicing/readback.js

@@ -0,0 +1,30 @@
+const identityKeys = ["providerRef", "requestKey", "providerCreateIdentity", "factRevision", "orderRef", "invoiceRef", "operation", "correctionRef", "parentProviderDocumentRef"];
+/** Internal validation used by the read model. No nullable lookup shortcut. */
+export async function readInvoiceReadback(provider, identity) {
+    const unknown = () => ({ kind: "unknown", identity, code: "unknown" });
+    try {
+        const result = await provider.read(identity);
+        if (result.kind === "unsupported")
+            return { kind: "unsupported", code: result.code, retryable: false, effectMayHaveSucceeded: false };
+        if (!sameIdentity(identity, result.identity))
+            return unknown();
+        if (result.kind === "found") {
+            if (!opaqueReference(result.providerDocumentRef))
+                return unknown();
+            return { kind: "found", identity, providerDocumentRef: result.providerDocumentRef, providerDocumentNumber: result.providerDocumentNumber, proof: { evidenceRef: result.proof.evidenceRef, fingerprint: result.proof.fingerprint, observedAt: result.proof.observedAt } };
+        }
+        if (result.kind === "absent" && result.evidence.exact === true && result.evidence.complete === true && sameIdentity(identity, result.evidence.scope)) {
+            return { kind: "absent", identity, evidence: { evidenceRef: result.evidence.evidenceRef, fingerprint: result.evidence.fingerprint, observedAt: result.evidence.observedAt, exact: true, complete: true, scope: identity } };
+        }
+        return unknown();
+    }
+    catch {
+        return unknown();
+    }
+}
+function sameIdentity(a, b) {
+    return Boolean(b) && identityKeys.every(key => a[key] === b[key]);
+}
+export function opaqueReference(ref) {
+    return typeof ref === "string" && ref.trim().length > 0 && !/^(?:https?:|data:|blob:|\/\/)/i.test(ref.trim());
+}

package/dist/invoicing/reversal.d.ts

@@ -0,0 +1,37 @@
+/** Donor reversal outcome/order semantics over host event adapters and writer.
+ * @consumer api/_cron/accountingOrderReversalHandlers.ts
+ */
+export declare function createInvoiceReversalHandlers<Row, Request, Result extends {
+    action: string;
+    invoice: {
+        status: string;
+    } | null;
+}>(input: {
+    enabled: boolean;
+    events: readonly {
+        eventType: string;
+        adapt(row: Row): {
+            kind: "ready";
+            request: Request;
+        } | {
+            kind: "invalid_payload";
+        };
+    }[];
+    request(request: Request): Promise<Result>;
+}): {
+    eventType: string;
+    timeoutMs: number;
+    handle(row: Row): Promise<{
+        kind: "discard";
+        reason: string;
+    } | {
+        kind: "processed";
+        detail: {
+            accountingReversalAction: string;
+            invoiceStatus: string;
+        };
+    } | {
+        kind: "retry";
+        reason: string;
+    }>;
+}[];

package/dist/invoicing/reversal.js

@@ -0,0 +1,28 @@
+/** Donor reversal outcome/order semantics over host event adapters and writer.
+ * @consumer api/_cron/accountingOrderReversalHandlers.ts
+ */
+export function createInvoiceReversalHandlers(input) {
+    if (!input.enabled)
+        return [];
+    return input.events.map(event => ({
+        eventType: event.eventType,
+        timeoutMs: 10_000,
+        async handle(row) {
+            const compatibility = event.adapt(row);
+            if (compatibility.kind === "invalid_payload") {
+                return { kind: "discard", reason: "accounting_reversal_payload_invalid" };
+            }
+            try {
+                const result = await input.request(compatibility.request);
+                return {
+                    kind: "processed",
+                    detail: { accountingReversalAction: result.action, invoiceStatus: result.invoice?.status ?? "no_invoice" },
+                };
+            }
+            catch (error) {
+                const message = error instanceof Error ? error.message : String(error);
+                return { kind: "retry", reason: message.slice(0, 300) };
+            }
+        },
+    }));
+}

package/dist/invoicing/sellerRevision.d.ts

@@ -0,0 +1,19 @@
+import type { InvoiceSellerRevision } from "./contracts/facts.js";
+import type { InvoiceUnsupported } from "./contracts/provider.js";
+/** Read the host selection before leasing. Persistence and race serialization
+ * belong exclusively to the pinned SQL wrapper, never to an in-memory cache.
+ * Unknown/unsupported selection consumes no claim and must be retried by the host.
+ */
+export declare function claimInvoiceSellerRevision<Seller extends object>(read: () => Promise<({
+    readonly kind: "found";
+} & InvoiceSellerRevision<Seller>) | {
+    readonly kind: "unknown";
+    readonly code: "unknown";
+} | InvoiceUnsupported>): Promise<InvoiceUnsupported | {
+    readonly kind: "unknown";
+    readonly code: "unknown";
+} | {
+    readonly kind: "found";
+    readonly seller: Seller;
+    readonly revisionRef: string;
+}>;

package/dist/invoicing/sellerRevision.js

@@ -0,0 +1,14 @@
+/** Read the host selection before leasing. Persistence and race serialization
+ * belong exclusively to the pinned SQL wrapper, never to an in-memory cache.
+ * Unknown/unsupported selection consumes no claim and must be retried by the host.
+ */
+export async function claimInvoiceSellerRevision(read) {
+    const selected = await read();
+    if (selected.kind !== "found")
+        return selected;
+    if (!selected.seller || typeof selected.seller !== "object" || Array.isArray(selected.seller)
+        || typeof selected.revisionRef !== "string" || !selected.revisionRef.trim()) {
+        return { kind: "unsupported", code: "host_binding_required", retryable: false, effectMayHaveSucceeded: false };
+    }
+    return { kind: "found", seller: selected.seller, revisionRef: selected.revisionRef };
+}