@openlup/platform 0.23.0 → 0.24.0

package/dist/invoicing/accountingCanonicalProviderLines.d.ts

@@ -0,0 +1,5 @@
+import type { InvoiceLine } from "./contracts/facts.js";
+export declare function mapCanonicalIssueLines(linesSnapshot: unknown[], chargedTotalGrossMinor: number, chargedTotalNetMinor: number, defaultLabel: string): Array<Pick<InvoiceLine, "quantity" | "unitGrossMinor" | "unitNetMinor" | "totalGrossMinor" | "totalNetMinor"> & {
+    name: string;
+    vatRate: string;
+}>;

package/dist/invoicing/accountingCanonicalProviderLines.js

@@ -0,0 +1,104 @@
+import { allocateDiscountedGrossTotals } from "./accountingLineAllocation.js";
+export function mapCanonicalIssueLines(linesSnapshot, chargedTotalGrossMinor, chargedTotalNetMinor, defaultLabel) {
+    const lines = linesSnapshot.map((value) => {
+        const row = isRecord(value) ? value : {};
+        const quantity = requiredPositiveInteger(row.quantity, "quantity");
+        const totalGrossMinor = requiredNonnegativeInteger(row.totalGrossMinor, "total_gross");
+        const totalNetMinor = requiredNonnegativeInteger(row.totalNetMinor, "total_net");
+        const vatRateBps = requiredNonnegativeInteger(row.vatRateBps, "vat_rate_bps");
+        if (vatRateBps > 10_000 || netFromGross(totalGrossMinor, vatRateBps) !== totalNetMinor) {
+            throw new Error("accounting_invoice_canonical_position_vat_mismatch");
+        }
+        const vatRate = canonicalVatRate(vatRateBps);
+        const suppliedVatRate = textValue(row.vatRate);
+        if (suppliedVatRate !== null && normalizeVatRate(suppliedVatRate) !== vatRate) {
+            throw new Error("accounting_invoice_canonical_position_vat_label_mismatch");
+        }
+        return {
+            positionKind: textValue(row.positionKind),
+            name: textValue(row.name) ?? defaultLabel,
+            quantity,
+            unitGrossMinor: requiredNonnegativeInteger(row.unitGrossMinor, "unit_gross"),
+            unitNetMinor: requiredNonnegativeInteger(row.unitNetMinor, "unit_net"),
+            totalGrossMinor,
+            totalNetMinor,
+            vatRate,
+            catalogTotalGrossMinor: numberValue(row.catalogTotalGrossMinor),
+            discountAllocatedMinor: numberValue(row.discountAllocatedMinor),
+            shippingGrossMinor: numberValue(row.shippingGrossMinor),
+            shippingDiscountMinor: numberValue(row.shippingDiscountMinor),
+        };
+    });
+    const items = lines.filter((line) => line.positionKind === "item");
+    const delivery = lines.filter((line) => line.positionKind === "delivery");
+    if (items.length === 0 || delivery.length > 1) {
+        throw new Error("accounting_invoice_canonical_position_cardinality_invalid");
+    }
+    const actualDelivery = delivery[0]?.totalGrossMinor ?? 0;
+    if (delivery.length === 1) {
+        const shippingGross = delivery[0].shippingGrossMinor;
+        const shippingDiscount = delivery[0].shippingDiscountMinor;
+        if (!Number.isSafeInteger(shippingGross) || !Number.isSafeInteger(shippingDiscount)
+            || shippingGross < 0 || shippingDiscount < 0 || shippingDiscount > shippingGross
+            || shippingGross - shippingDiscount !== actualDelivery) {
+            throw new Error("accounting_invoice_canonical_delivery_mismatch");
+        }
+    }
+    const catalogTotals = items.map((line) => {
+        if (!Number.isInteger(line.catalogTotalGrossMinor) || (line.catalogTotalGrossMinor ?? -1) < 0) {
+            throw new Error("accounting_invoice_canonical_catalog_total_invalid");
+        }
+        if (!Number.isInteger(line.discountAllocatedMinor) || (line.discountAllocatedMinor ?? -1) < 0) {
+            throw new Error("accounting_invoice_canonical_discount_allocation_invalid");
+        }
+        if (line.totalGrossMinor + line.discountAllocatedMinor !== line.catalogTotalGrossMinor) {
+            throw new Error("accounting_invoice_canonical_line_allocation_mismatch");
+        }
+        return line.catalogTotalGrossMinor;
+    });
+    const independentlyAllocated = allocateDiscountedGrossTotals(catalogTotals, chargedTotalGrossMinor - actualDelivery);
+    if (items.some((line, index) => line.totalGrossMinor !== independentlyAllocated[index])) {
+        throw new Error("accounting_invoice_canonical_allocator_delta_nonzero");
+    }
+    const grossSum = lines.reduce((sum, line) => sum + line.totalGrossMinor, 0);
+    const netSum = lines.reduce((sum, line) => sum + line.totalNetMinor, 0);
+    if (grossSum !== chargedTotalGrossMinor || netSum !== chargedTotalNetMinor) {
+        throw new Error(`accounting_invoice_canonical_positions_header_mismatch gross=${grossSum}/${chargedTotalGrossMinor} net=${netSum}/${chargedTotalNetMinor}`);
+    }
+    return lines.map(({ positionKind: _kind, catalogTotalGrossMinor: _catalog, discountAllocatedMinor: _discount, shippingGrossMinor: _shippingGross, shippingDiscountMinor: _shippingDiscount, ...line }) => line);
+}
+function requiredNonnegativeInteger(value, field) {
+    const number = numberValue(value);
+    if (number === null || !Number.isSafeInteger(number) || number < 0) {
+        throw new Error(`accounting_invoice_canonical_${field}_invalid`);
+    }
+    return number;
+}
+function requiredPositiveInteger(value, field) {
+    const number = requiredNonnegativeInteger(value, field);
+    if (number === 0)
+        throw new Error(`accounting_invoice_canonical_${field}_invalid`);
+    return number;
+}
+function netFromGross(gross, vatRateBps) {
+    return Math.round(gross * 10_000 / (10_000 + vatRateBps));
+}
+function canonicalVatRate(vatRateBps) {
+    return normalizeVatRate(String(vatRateBps / 100));
+}
+function normalizeVatRate(value) {
+    const parsed = Number(value.replace(",", "."));
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        throw new Error("accounting_invoice_canonical_position_vat_label_invalid");
+    }
+    return String(parsed);
+}
+function textValue(value) {
+    return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+function numberValue(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function isRecord(value) {
+    return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}

package/dist/invoicing/accountingLineAllocation.d.ts

@@ -0,0 +1,2 @@
+export declare function allocateChargedGrossTotals(lineTotals: number[], chargedTotal: number): number[];
+export declare function allocateDiscountedGrossTotals(lineTotals: number[], chargedTotal: number): number[];

package/dist/invoicing/accountingLineAllocation.js

@@ -0,0 +1,69 @@
+// Independent document-boundary allocation. The database writer performs its
+// own SQL allocation; this copy deliberately verifies persisted results rather
+// than sharing an implementation with the order writer.
+export function allocateChargedGrossTotals(lineTotals, chargedTotal) {
+    if (!Number.isInteger(chargedTotal) || chargedTotal < 0) {
+        throw new Error(`accounting_invoice_charged_total_invalid charged=${chargedTotal}`);
+    }
+    if (lineTotals.some((total) => !Number.isInteger(total) || total < 0)) {
+        throw new Error("accounting_invoice_line_totals_invalid");
+    }
+    const linesTotal = lineTotals.reduce((sum, total) => sum + total, 0);
+    if (linesTotal === chargedTotal)
+        return lineTotals;
+    if (linesTotal < chargedTotal) {
+        throw new Error(`accounting_invoice_lines_below_charged_total lines=${linesTotal} charged=${chargedTotal}`);
+    }
+    const scaled = lineTotals.map((total) => (total * chargedTotal) / linesTotal);
+    const allocated = scaled.map((value) => Math.floor(value));
+    let remainder = chargedTotal - allocated.reduce((sum, total) => sum + total, 0);
+    const byFraction = scaled
+        .map((value, index) => ({ index, fraction: value - allocated[index] }))
+        .sort((a, b) => b.fraction - a.fraction || a.index - b.index);
+    for (const { index } of byFraction) {
+        if (remainder <= 0)
+            break;
+        allocated[index] += 1;
+        remainder -= 1;
+    }
+    return allocated;
+}
+// Mirrors the order writer's discount allocation rule for verification only:
+// allocate the discount (not the charged total) by largest remainder, then
+// subtract it from each catalog line. Allocating the charged total directly
+// reverses the deterministic tie-break for equal lines.
+export function allocateDiscountedGrossTotals(lineTotals, chargedTotal) {
+    const linesTotal = lineTotals.reduce((sum, total) => sum + total, 0);
+    const discount = linesTotal - chargedTotal;
+    if (!Number.isInteger(chargedTotal) || chargedTotal < 0 || discount < 0) {
+        throw new Error(`accounting_invoice_charged_total_invalid charged=${chargedTotal}`);
+    }
+    if (lineTotals.some((total) => !Number.isInteger(total) || total < 0)) {
+        throw new Error("accounting_invoice_line_totals_invalid");
+    }
+    if (discount === 0)
+        return lineTotals;
+    if (linesTotal === 0) {
+        throw new Error("accounting_invoice_discount_allocation_zero_spread");
+    }
+    const sumExact = BigInt(linesTotal);
+    const discountExact = BigInt(discount);
+    const scaledDiscounts = lineTotals.map((total) => {
+        const product = BigInt(total) * discountExact;
+        return { base: product / sumExact, remainder: product % sumExact };
+    });
+    const allocatedDiscounts = scaledDiscounts.map(({ base }) => Number(base));
+    let remainder = discount - allocatedDiscounts.reduce((sum, total) => sum + total, 0);
+    const byFraction = scaledDiscounts
+        .map((value, index) => ({ index, fraction: value.remainder }))
+        .sort((a, b) => a.fraction === b.fraction
+        ? a.index - b.index
+        : a.fraction > b.fraction ? -1 : 1);
+    for (const { index } of byFraction) {
+        if (remainder <= 0)
+            break;
+        allocatedDiscounts[index] += 1;
+        remainder -= 1;
+    }
+    return lineTotals.map((total, index) => total - allocatedDiscounts[index]);
+}

package/dist/invoicing/adapterConformance.d.ts

@@ -0,0 +1,42 @@
+import type { InvoiceCapabilities, InvoiceIdentity, InvoiceWriteResult, InvoiceReadbackResult, InvoiceArtifactResult, InvoiceHostPorts, InvoiceServicesOptions } from "./contracts/index.js";
+type Provider = NonNullable<InvoiceServicesOptions["provider"]>;
+type Fixture<Input, Result> = {
+    readonly input: Input;
+    readonly expected: Result;
+};
+interface Subject {
+    readonly subjectId: string;
+    readonly capability: InvoiceCapabilities;
+    readonly provider: Provider;
+    readonly host?: InvoiceHostPorts;
+    /** Adapter-owned offline fixtures; count writes across every injected transport. */
+    readonly readWriteCount: () => number;
+    readonly sensitiveValues: readonly string[];
+    readonly fixtures: {
+        readonly issue: readonly (Fixture<Parameters<Provider["issue"]>[0], InvoiceWriteResult> & {
+            readonly replay?: boolean;
+        })[];
+        readonly correction: readonly (Fixture<Parameters<Provider["correct"]>[0], InvoiceWriteResult> & {
+            readonly replay?: boolean;
+        })[];
+        readonly readback: readonly Fixture<InvoiceIdentity, InvoiceReadbackResult>[];
+        readonly void: readonly Fixture<Parameters<Provider["void"]>[0], Awaited<ReturnType<Provider["void"]>>>[];
+        readonly artifact?: readonly Fixture<Parameters<InvoiceHostPorts["artifacts"]["read"]>[0], InvoiceArtifactResult>[];
+        readonly clearance?: readonly Fixture<Parameters<InvoiceHostPorts["clearance"]["observe"]>[0], Awaited<ReturnType<InvoiceHostPorts["clearance"]["observe"]>>>[];
+        readonly settlement?: readonly Fixture<Parameters<InvoiceHostPorts["settlement"]["record"]>[0], Awaited<ReturnType<InvoiceHostPorts["settlement"]["record"]>>>[];
+        readonly companyLookup?: readonly Fixture<Parameters<InvoiceHostPorts["registry"]["lookup"]>[0], Awaited<ReturnType<InvoiceHostPorts["registry"]["lookup"]>>>[];
+    };
+}
+/** @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 declare function runInvoiceAdapterConformance(subjects: readonly Subject[]): Promise<{
+    readonly subjects: readonly {
+        readonly subjectId: string;
+        readonly providerRef: string;
+        readonly cases: readonly string[];
+    }[];
+}>;
+export {};

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 {};