@openlup/platform 0.22.0 → 0.24.0

package/dist/invoicing/adapterConformance.js

@@ -0,0 +1,296 @@
+class ContractFailure extends Error {
+}
+function requireFact(value, code) {
+    if (!value)
+        throw new ContractFailure(`INVOICE_CONFORMANCE:${code}`);
+}
+function same(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b || typeof a !== "object" || typeof b !== "object")
+        return false;
+    if (Array.isArray(a) !== Array.isArray(b))
+        return false;
+    const left = Object.keys(a), right = Object.keys(b);
+    return left.length === right.length && left.every(key => Object.hasOwn(b, key) && same(a[key], b[key]));
+}
+function keys(value, allowed) {
+    requireFact(value !== null && typeof value === "object", "proof_required");
+    requireFact(Object.keys(value).every(key => allowed.includes(key)), "unexpected_field");
+}
+function proof(value, extra = []) {
+    requireFact(value !== null && typeof value === "object", "proof_required");
+    keys(value, ["evidenceRef", "fingerprint", "observedAt", ...extra]);
+    requireFact([value.evidenceRef, value.fingerprint, value.observedAt].every(v => typeof v === "string" && v.trim().length > 0), "proof_required");
+}
+function identity(value, expected) {
+    keys(value, "documentRef" in expected ? ["providerRef", "documentRef", "providerDocumentRef", "orderRef", "invoiceRef", "parentProviderDocumentRef"] : ["providerRef", "requestKey", "providerCreateIdentity", "factRevision", "orderRef", "invoiceRef", "operation", "correctionRef", "parentProviderDocumentRef"]);
+    requireFact(same(value, expected), "identity_scope");
+}
+function safe(result, subject) {
+    const serialized = JSON.stringify(result);
+    requireFact(subject.sensitiveValues.every(value => value.length > 0 && !serialized.includes(value) && !serialized.includes(encodeURIComponent(value))), "sensitive_result");
+}
+function documentResult(result, expected, operation) {
+    requireFact(operation === "void" ? result.kind === "unsupported" : operation === "read" ? ["found", "absent", "unknown", "unsupported"].includes(result.kind) : ["issued", "refused", "unknown", "unsupported"].includes(result.kind), "document_result_kind");
+    if (result.kind === "unsupported") {
+        keys(result, ["kind", "code", "retryable", "effectMayHaveSucceeded"]);
+        requireFact(result.retryable === false && result.effectMayHaveSucceeded === false && ["unsupported", "host_binding_required"].includes(result.code), "unsupported_before_write");
+        return;
+    }
+    identity(result.identity, expected);
+    if (result.kind === "issued" || result.kind === "found") {
+        keys(result, result.kind === "found" ? ["kind", "identity", "providerDocumentRef", "providerDocumentNumber", "proof"] : ["kind", "identity", "providerDocumentRef", "providerDocumentNumber", "proof", "replayed"]);
+        proof(result.proof);
+        if (result.kind === "issued")
+            requireFact(typeof result.replayed === "boolean", "issued_replay");
+        requireFact(result.providerDocumentRef.trim().length > 0 && (result.providerDocumentNumber === null || typeof result.providerDocumentNumber === "string"), "issued_identity");
+    }
+    else if (result.kind === "absent") {
+        keys(result, ["kind", "identity", "evidence"]);
+        proof(result.evidence, ["exact", "complete", "scope"]);
+        requireFact(result.evidence.exact === true && result.evidence.complete === true, "exact_complete_absence");
+        identity(result.evidence.scope, expected);
+    }
+    else if (result.kind === "unknown") {
+        keys(result, ["kind", "identity", "code", "effectMayHaveSucceeded"]);
+        requireFact(result.code === "unknown" && (operation === "write" ? "effectMayHaveSucceeded" in result && result.effectMayHaveSucceeded === true : !("effectMayHaveSucceeded" in result)), "unknown_not_absent");
+    }
+    else {
+        keys(result, ["kind", "identity", "code", "retryable", "effectMayHaveSucceeded"]);
+        requireFact(result.kind === "refused" && result.effectMayHaveSucceeded === false && typeof result.retryable === "boolean" && ["blocked", "retryable", "missing_facts", "identity_mismatch", "parent_mismatch", "money_mismatch"].includes(result.code), "refusal_before_write");
+    }
+}
+function hostResult(operation, input, value) {
+    const result = value;
+    if (result.kind === "unsupported") {
+        keys(result, ["kind", "code", "retryable", "effectMayHaveSucceeded"]);
+        requireFact(result.retryable === false && result.effectMayHaveSucceeded === false && (result.code === "unsupported" || result.code === "host_binding_required"), "host_unsupported");
+        return;
+    }
+    if (operation === "artifact") {
+        const artifact = value, request = input;
+        identity(artifact.identity, request.identity);
+        if (artifact.kind === "found") {
+            keys(artifact, ["kind", "identity", "artifact"]);
+            keys(artifact.artifact, ["kind", "ref", "owner", "mediaType", "proof"]);
+            requireFact(artifact.artifact.kind === request.kind && artifact.artifact.ref.length > 0 && artifact.artifact.mediaType.length > 0 && ["provider", "host_storage"].includes(artifact.artifact.owner), "artifact_reference");
+            proof(artifact.artifact.proof);
+        }
+        else if (artifact.kind === "absent") {
+            keys(artifact, ["kind", "identity", "evidence"]);
+            proof(artifact.evidence, ["exact", "complete", "scope"]);
+            keys(artifact.evidence.scope, ["identity", "kind", "artifactRef"]);
+            requireFact(artifact.evidence.exact === true && artifact.evidence.complete === true && artifact.evidence.scope.kind === request.kind && artifact.evidence.scope.artifactRef === null, "artifact_absence");
+            identity(artifact.evidence.scope.identity, request.identity);
+        }
+        else {
+            keys(artifact, ["kind", "identity", "code"]);
+            requireFact(artifact.kind === "unknown" && artifact.code === "unknown", "artifact_unknown");
+        }
+    }
+    else if (operation === "clearance") {
+        const observation = value;
+        if (observation.kind === "observed") {
+            keys(observation, ["kind", "observation"]);
+            const observed = observation.observation;
+            keys(observed, ["state", "reference", "proof"]);
+            proof(observed.proof);
+            requireFact(["not_submitted", "pending", "rejected", "accepted", "not_required", "unsupported"].includes(observed.state), "clearance_state");
+            requireFact(observed.state === "accepted" ? typeof observed.reference === "string" && observed.reference.trim().length > 0 : observed.reference === null || typeof observed.reference === "string", "clearance_reference");
+        }
+        else {
+            keys(observation, ["kind", "code"]);
+            requireFact(observation.kind === "unknown" && observation.code === "unknown", "clearance_unknown");
+        }
+    }
+    else if (operation === "settlement") {
+        const item = input;
+        requireFact([item.grossMinor, item.feeMinor, item.netMinor].every(Number.isSafeInteger) && item.grossMinor - item.feeMinor === item.netMinor, "settlement_money");
+        keys(result, ["kind", "itemRef", "settlementItemRef", "replayed", "code"]);
+        requireFact(result.itemRef === item.itemRef, "settlement_item_identity");
+        requireFact(["recorded", "conflict", "unknown"].includes(String(result.kind)), "settlement_result");
+        if (result.kind === "recorded")
+            requireFact(typeof result.replayed === "boolean" && typeof result.settlementItemRef === "string" && result.settlementItemRef.length > 0, "settlement_receipt");
+        if (result.kind === "conflict")
+            requireFact(result.code === "identity_mismatch" || result.code === "money_mismatch", "settlement_conflict");
+        if (result.kind === "unknown")
+            requireFact(result.code === "unknown", "settlement_unknown");
+    }
+    else {
+        const company = value;
+        keys(result, ["kind", "identifier", "legalName", "registrationIds", "address", "taxRegistrations", "sourceRef", "proof", "code"]);
+        const request = input;
+        requireFact(company.sourceRef === request.sourceRef, "company_source");
+        if (company.kind !== "unknown")
+            requireFact(same(company.identifier, request.identifier), "company_identity");
+        if (company.kind === "found" || company.kind === "partial") {
+            proof(company.proof);
+            for (const registration of company.taxRegistrations) {
+                keys(registration, ["scheme", "status"]);
+                requireFact(["active", "exempt", "not_registered", "unknown"].includes(registration.status), "company_tax_status");
+            }
+        }
+        else if (company.kind === "not_found")
+            proof(company.proof);
+        else
+            requireFact(company.kind === "unknown" && company.code === "unknown", "company_unknown");
+    }
+}
+/** @consumer Offline provider bridge tests and installed cold consumer. Runner-
+ * agnostic contract evidence only; adapters own fixtures, transport and I/O counts.
+ * Throws closed failure codes. It neither certifies live fiscal readiness nor logs
+ * provider results, secrets, buyer facts or raw adapter errors.
+ */
+export async function runInvoiceAdapterConformance(subjects) {
+    const evidence = [];
+    try {
+        requireFact(subjects.length > 0, "subject_required");
+        for (const subject of subjects) {
+            const { capability: caps, provider, fixtures } = subject;
+            const cases = [];
+            requireFact(caps.defaultOff === true, "default_off");
+            requireFact(caps.version === "invoicing.capabilities.v1" && caps.numberingOwner === "provider"
+                && [caps.providerRef, caps.fiscalScope.scopeRef, caps.fiscalScope.version, ...Object.values(caps.policies)].every(value => value.trim().length > 0), "capability_scope");
+            for (const operation of ["issue", "correction"]) {
+                const rows = fixtures[operation];
+                requireFact(rows.length > 0, "write_fixture_required");
+                if (caps.operations[operation].supported)
+                    requireFact(rows.some(row => row.expected.kind === "issued"), "issued_fixture_required");
+                if (caps.operations[operation].supported && caps.operations.recovery.supported)
+                    requireFact(rows.some(row => row.replay), "recovery_fixture_required");
+                const unknownRecovery = rows.filter(row => row.input.recoveryLookupRequired
+                    && row.expected.kind === (caps.operations.recovery.supported ? "unknown" : "unsupported"));
+                if (caps.operations[operation].supported) {
+                    requireFact(unknownRecovery.length > 0, "recovery_unknown_fixture_required");
+                    if (caps.operations.recovery.supported && caps.operations.readback.supported)
+                        requireFact(unknownRecovery.every(row => fixtures.readback.some(read => read.expected.kind === "unknown" && same(read.input, row.input.identity))), "recovery_unknown_readback_required");
+                }
+                for (const row of rows) {
+                    requireFact(row.input.identity.providerRef === caps.providerRef, "selected_provider");
+                    const before = subject.readWriteCount();
+                    const invoke = operation === "issue" ? () => provider.issue(row.input) : () => provider.correct(row.input);
+                    const result = await invoke();
+                    documentResult(result, row.input.identity, "write");
+                    safe(result, subject);
+                    if (unknownRecovery.includes(row))
+                        requireFact(result.kind === row.expected.kind && subject.readWriteCount() === before, "recovery_unknown_no_write");
+                    if (row.input.recoveryLookupRequired === true) {
+                        if (!caps.operations.recovery.supported)
+                            requireFact(result.kind !== "issued" && subject.readWriteCount() === before, "recovery_create_without_absence");
+                        if (subject.readWriteCount() > before || (result.kind === "issued" && result.replayed === false)) {
+                            requireFact(caps.operations.recovery.supported && caps.operations.readback.supported && caps.operations.exactAbsence.supported
+                                && fixtures.readback.some(read => same(read.input, row.input.identity) && read.expected.kind === "absent")
+                                && !fixtures.readback.some(read => same(read.input, row.input.identity) && (read.expected.kind === "unknown" || read.expected.kind === "unsupported")), "recovery_create_without_absence");
+                        }
+                    }
+                    requireFact(same(result, row.expected), "write_fixture");
+                    if (!caps.operations[operation].supported)
+                        requireFact(result.kind === "unsupported", "declared_unsupported");
+                    if (operation === "correction" && caps.operations.correction.supported) {
+                        const request = row.input;
+                        requireFact(request.identity.correctionRef.length > 0 && request.identity.parentProviderDocumentRef.length > 0
+                            && request.before.totalGrossMinor > 0 && Object.values(request.after).every(value => value === 0), "correction_before_after");
+                        const parent = fixtures.correction.find(fixture => fixture.expected.kind === "issued" && fixture.input.identity.correctionRef === request.identity.correctionRef);
+                        if (parent && parent.input.identity.parentProviderDocumentRef !== request.identity.parentProviderDocumentRef)
+                            requireFact((result.kind === "refused" || result.kind === "unknown") && subject.readWriteCount() === before, "parent_mismatch_no_write");
+                    }
+                    if (result.kind === "unsupported" || result.kind === "refused")
+                        requireFact(subject.readWriteCount() === before, "refused_write");
+                    if (row.replay) {
+                        requireFact(caps.operations.recovery.supported && result.kind === "issued", "replay_requires_issued");
+                        const count = subject.readWriteCount();
+                        const recovered = operation === "issue" ? await provider.issue({ ...row.input, recoveryLookupRequired: true }) : await provider.correct({ ...row.input, recoveryLookupRequired: true });
+                        documentResult(recovered, row.input.identity, "write");
+                        safe(recovered, subject);
+                        requireFact(recovered.kind === "issued" && recovered.replayed === true && recovered.providerDocumentRef === result.providerDocumentRef && recovered.providerDocumentNumber === result.providerDocumentNumber, "recovery_identity");
+                        requireFact(subject.readWriteCount() === count, "recovery_no_second_write");
+                    }
+                    cases.push(operation + ":" + result.kind + (row.replay ? ":recovery" : ""));
+                }
+            }
+            if (caps.operations.correction.supported) {
+                const issued = fixtures.correction.find(row => row.expected.kind === "issued");
+                requireFact(issued && fixtures.correction.some(row => row.input.recoveryLookupRequired
+                    && row.input.identity.correctionRef === issued.input.identity.correctionRef
+                    && row.input.identity.providerCreateIdentity === issued.input.identity.providerCreateIdentity
+                    && row.input.identity.parentProviderDocumentRef !== issued.input.identity.parentProviderDocumentRef
+                    && (row.expected.kind === "refused" || row.expected.kind === "unknown")), "correction_parent_fixture_required");
+            }
+            requireFact(fixtures.readback.length > 0 && fixtures.void.length > 0, "read_void_fixture_required");
+            if (caps.operations.readback.supported)
+                requireFact(fixtures.readback.some(row => row.expected.kind === "unknown") && fixtures.readback.some(row => row.expected.kind === "found"), "found_unknown_fixtures_required");
+            if (caps.operations.exactAbsence.supported)
+                requireFact(fixtures.readback.some(row => row.expected.kind === "absent"), "absence_fixture_required");
+            for (const row of fixtures.readback) {
+                const before = subject.readWriteCount(), result = await provider.read(row.input);
+                documentResult(result, row.input, "read");
+                safe(result, subject);
+                requireFact(same(result, row.expected), "read_fixture");
+                requireFact(subject.readWriteCount() === before, "read_no_write");
+                if (!caps.operations.readback.supported)
+                    requireFact(result.kind === "unsupported", "declared_unsupported");
+                if (result.kind === "absent")
+                    requireFact(caps.operations.exactAbsence.supported, "absence_capability");
+                cases.push("read:" + result.kind);
+            }
+            requireFact(caps.operations.remoteVoid.supported === false && caps.operations.remoteVoid.reason === "not_implemented", "remote_void_cut");
+            for (const row of fixtures.void) {
+                const before = subject.readWriteCount(), result = await provider.void(row.input);
+                documentResult(result, row.input, "void");
+                safe(result, subject);
+                requireFact(same(result, row.expected), "void_fixture");
+                requireFact(subject.readWriteCount() === before, "void_refused_write");
+                cases.push("void:" + result.kind);
+            }
+            const settlementReceipts = new Map();
+            const settlementRows = fixtures.settlement ?? [];
+            const distinctPayoutRows = settlementRows.filter(row => row.expected.kind === "recorded" && settlementRows.some(other => other.expected.kind === "recorded"
+                && row.input.itemRef !== other.input.itemRef && row.input.providerRef === other.input.providerRef
+                && row.input.batchRef === other.input.batchRef && row.input.providerPaymentRef === other.input.providerPaymentRef));
+            if (caps.operations.settlement.supported)
+                requireFact(distinctPayoutRows.length >= 2, "distinct_payout_fixtures_required");
+            // Optional host-owned capabilities require their own fixtures when declared.
+            for (const operation of ["artifact", "clearance", "settlement", "companyLookup"]) {
+                const rows = fixtures[operation] ?? [];
+                if (caps.operations[operation].supported)
+                    requireFact(subject.host && rows.some(row => ["found", "partial", "recorded", "observed"].includes(row.expected.kind) && !("observation" in row.expected && row.expected.observation.state === "unsupported")), "host_fixture_required");
+                for (const row of rows) {
+                    requireFact(subject.host, "host_required");
+                    const before = subject.readWriteCount();
+                    const result = operation === "artifact" ? await subject.host.artifacts.read(row.input)
+                        : operation === "clearance" ? await subject.host.clearance.observe(row.input)
+                            : operation === "settlement" ? await subject.host.settlement.record(row.input)
+                                : await subject.host.registry.lookup(row.input);
+                    hostResult(operation, row.input, result);
+                    if (operation === "settlement" && distinctPayoutRows.some(fixture => fixture === row))
+                        requireFact(result.kind === "recorded", "distinct_payout_items");
+                    if (operation === "settlement" && "kind" in result && result.kind === "recorded") {
+                        const input = row.input;
+                        const item = JSON.stringify([input.providerRef, input.batchRef, input.itemRef]);
+                        requireFact(!settlementReceipts.has(result.settlementItemRef) || settlementReceipts.get(result.settlementItemRef) === item, "distinct_payout_items");
+                        settlementReceipts.set(result.settlementItemRef, item);
+                    }
+                    safe(result, subject);
+                    requireFact(same(result, row.expected), "host_fixture");
+                    if (result.kind === "unsupported")
+                        requireFact(subject.readWriteCount() === before, "host_unsupported_write");
+                    if (operation !== "settlement")
+                        requireFact(subject.readWriteCount() === before, "host_read_no_write");
+                    if (!caps.operations[operation].supported)
+                        requireFact((result.kind === "unsupported" || ("observation" in result && result.observation.state === "unsupported")) && subject.readWriteCount() === before, "host_unsupported_before_write");
+                    cases.push(operation);
+                }
+            }
+            const row = { subjectId: subject.subjectId, providerRef: caps.providerRef, cases };
+            safe(row, subject);
+            evidence.push(row);
+        }
+        return { subjects: evidence };
+    }
+    catch (error) {
+        if (error instanceof ContractFailure)
+            throw error;
+        throw new ContractFailure("INVOICE_CONFORMANCE:adapter_threw");
+    }
+}

package/dist/invoicing/artifacts.d.ts

@@ -0,0 +1,7 @@
+/** Validate transient bytes; this is neither storage proof nor delivery proof. */
+export declare function assertInvoicePdf(pdf: {
+    content: Uint8Array;
+    contentType: string;
+}): void;
+/** The host supplies its existing fallback caption. No locale/content default. */
+export declare function invoicePdfFilename(reference: string, fallback?: string): string;

package/dist/invoicing/artifacts.js

@@ -0,0 +1,20 @@
+const MAX_INVOICE_PDF_BYTES = 25 * 1024 * 1024;
+/** Validate transient bytes; this is neither storage proof nor delivery proof. */
+export function assertInvoicePdf(pdf) {
+    const contentType = pdf.contentType.split(";", 1)[0]?.trim().toLowerCase();
+    if (contentType !== "application/pdf")
+        throw new Error("invoice_pdf_content_type_invalid");
+    if (!pdf.content || pdf.content.byteLength === 0)
+        throw new Error("invoice_pdf_empty");
+    if (pdf.content.byteLength > MAX_INVOICE_PDF_BYTES)
+        throw new Error("invoice_pdf_too_large");
+    if (String.fromCharCode(...pdf.content.subarray(0, 5)) !== "%PDF-") {
+        throw new Error("invoice_pdf_signature_invalid");
+    }
+}
+/** The host supplies its existing fallback caption. No locale/content default. */
+export function invoicePdfFilename(reference, fallback = "invoice") {
+    const safe = (value) => value.normalize("NFKD")
+        .replace(/[^A-Za-z0-9_-]+/g, "-").replace(/^-+|-+$/g, "").slice(0, 100);
+    return `${safe(reference) || safe(fallback) || "invoice"}.pdf`;
+}

package/dist/invoicing/bindings.d.ts

@@ -0,0 +1,46 @@
+import type { InvoiceServicesOptions } from "./contracts/host.js";
+import type { InvoiceUnsupported } from "./contracts/provider.js";
+import { runNativeInvoiceIssueJob } from "./postgresInvoiceStore.js";
+import { syncAcceptedInvoiceDocuments } from "./documentSync.js";
+import { syncInvoicePayoutSettlements } from "./settlementSync.js";
+import { createInvoiceReadModel } from "./readModel.js";
+type Operation = "issue" | "correction" | "delivery" | "documentSync" | "settlementSync" | "collectDuties" | "history";
+type Ports = Pick<InvoiceServicesOptions, "host"> & Required<{
+    provider: NonNullable<InvoiceServicesOptions["provider"]>;
+    store: NonNullable<InvoiceServicesOptions["store"]>;
+    capability: NonNullable<InvoiceServicesOptions["capability"]>;
+}>;
+type Refusal = InvoiceUnsupported | {
+    readonly kind: "refused";
+    readonly code: "disabled" | "selection_required";
+    readonly retryable: false;
+    readonly effectMayHaveSucceeded: false;
+};
+/** Host factories bind existing workers/readers, never another executor or cron. */
+export interface InvoiceServices<Result = unknown> {
+    readiness(): Promise<{
+        readonly kind: "ready";
+    } | Refusal>;
+    run(operation: Operation): Promise<Result | Refusal>;
+}
+/** 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 declare function createInvoiceServices<Result = unknown>(options: InvoiceServicesOptions & {
+    readonly factories?: Partial<Record<Operation, (ports: Ports) => () => Promise<Result>>>;
+    readonly jobs?: {
+        readonly issue?: Omit<Parameters<typeof runNativeInvoiceIssueJob>[0], "store" | "provider" | "money" | "providerRef">;
+        readonly delivery?: {
+            readonly claimOptions: Parameters<NonNullable<InvoiceServicesOptions["store"]>["claimDeliveries"]>[0];
+            filename(claim: Exclude<Awaited<ReturnType<NonNullable<InvoiceServicesOptions["store"]>["claimDeliveries"]>>, InvoiceUnsupported>[number]): string;
+        };
+        readonly documentSync?: Parameters<typeof syncAcceptedInvoiceDocuments>[0];
+        readonly settlementSync?: Omit<Parameters<typeof syncInvoicePayoutSettlements>[0], "settlement">;
+        readonly history?: Parameters<ReturnType<typeof createInvoiceReadModel>["history"]>[0];
+        readonly collectDuties?: {
+            readonly limit?: number;
+        };
+    };
+}): InvoiceServices<Result>;
+export {};

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/capabilities.d.ts

@@ -0,0 +1,11 @@
+import type { InvoiceCapabilities, InvoiceCapabilitySelection } from "./contracts/capabilities.js";
+/** @consumer Host readiness / installed cold consumer. Default off and explicit
+ * provider selection precede capability use; construction never selects a provider.
+ */
+export declare function readInvoiceCapabilities(input: {
+    readonly enabled?: boolean;
+    readonly selection: {
+        readonly providerRef: string;
+    } | null;
+    readonly capability: InvoiceCapabilities | null;
+}): InvoiceCapabilitySelection;

package/dist/invoicing/capabilities.js

@@ -0,0 +1,10 @@
+/** @consumer Host readiness / installed cold consumer. Default off and explicit
+ * provider selection precede capability use; construction never selects a provider.
+ */
+export function readInvoiceCapabilities(input) {
+    if (input.enabled !== true)
+        return { kind: "refused", code: "disabled", retryable: false, effectMayHaveSucceeded: false };
+    if (!input.selection || !input.capability || input.selection.providerRef !== input.capability.providerRef)
+        return { kind: "refused", code: "selection_required", retryable: false, effectMayHaveSucceeded: false };
+    return { kind: "ready", capability: input.capability };
+}

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/capabilities.d.ts

@@ -0,0 +1,40 @@
+import type { InvoiceDiagnosticCode, InvoiceUnsupported } from "./provider.js";
+export interface InvoiceCapabilities {
+    readonly version: "invoicing.capabilities.v1";
+    readonly providerRef: string;
+    readonly fiscalScope: {
+        readonly scopeRef: string;
+        readonly version: string;
+    };
+    readonly policies: {
+        readonly identifierRef: string;
+        readonly taxRef: string;
+        readonly roundingRef: string;
+    };
+    readonly documentKinds: readonly string[];
+    readonly correctionKinds: readonly "full_reversal"[];
+    readonly numberingOwner: "provider";
+    readonly sellerTiming: "execution" | "first_claim";
+    readonly operations: Readonly<Record<"issue" | "correction" | "recovery" | "readback" | "exactAbsence" | "artifact" | "clearance" | "settlement" | "companyLookup", {
+        readonly supported: true;
+    } | {
+        readonly supported: false;
+        readonly reason: "host_required" | "not_implemented" | "not_exposed";
+    }>> & {
+        readonly remoteVoid: {
+            readonly supported: false;
+            readonly reason: "not_implemented";
+        };
+    };
+    readonly defaultOff: true;
+}
+/** Interpretation only: no environment discovery, activation, writes or provider calls. */
+export type InvoiceCapabilitySelection = InvoiceUnsupported | {
+    readonly kind: "ready";
+    readonly capability: InvoiceCapabilities;
+} | {
+    readonly kind: "refused";
+    readonly code: Extract<InvoiceDiagnosticCode, "disabled" | "selection_required">;
+    readonly retryable: false;
+    readonly effectMayHaveSucceeded: false;
+};

package/dist/invoicing/contracts/capabilities.js

@@ -0,0 +1 @@
+export {};